Worker Management

Quick Create (2 steps)

# 1. Write SOUL.md (REQUIRED)
mkdir -p /root/hiclaw-fs/agents/<NAME>
# Write SOUL.md with AI Identity + Role + Security sections (see references/create-worker.md)

# 2. Run create script
bash /opt/hiclaw/agent/skills/worker-management/scripts/create-worker.sh \
  --name <NAME> --skills <skill1>,<skill2>
# Add --runtime copaw for Python workers
# Add --remote for admin-managed deployment

Full creation workflow (runtime selection, SOUL.md template, skill matching, post-creation greeting): read references/create-worker.md

Gotchas

• Worker name must be lowercase and > 3 characters — Tuwunel stores usernames in lowercase; short names cause registration failures
• --remote means "remote from Manager" — which is actually LOCAL from the admin's perspective. Use it when admin says "local mode" / "run on my machine"
• file-sync, task-progress, project-participation are default skills — always included, cannot be removed
• Use hiclaw-find-worker only for Nacos-backed market imports or Worker discovery during task assignment — generic Worker creation and lifecycle changes stay in this skill
• Peer mentions cause loops if not briefed — after enabling, explicitly tell Workers to only @mention peers for blocking info, never for acknowledgments
• Always notify Workers to file-sync after writing files they need — the 5-minute periodic sync is fallback only
• Workers are stateless — all state is in centralized storage. Reset = recreate config files
• Matrix accounts persist in Tuwunel (cannot be deleted via API) — reuse same username on reset

Operation Reference

Read the relevant doc before executing. Do not load all of them.