Setup
clawctl init # create the database
export CLAW_AGENT=your-name # set identity (falls back to $USER with warning)
export CLAW_DB=~/.openclaw/clawctl.db # optional, this is the default
Operational Rhythm
Follow this pattern every session:
clawctl checkin — register presence, see unread countclawctl inbox --unread — read messages before picking up workclawctl next — find highest-priority actionable task (or clawctl list --mine)clawctl claim <id> then clawctl start <id> — take ownership and beginclawctl msg <agent> "update" --task <id> — coordinate during workclawctl done <id> -m "what I did" then clawctl next — complete and move on
Only claim tasks assigned to you or matching your role. Completing an already-done task is a safe no-op.
Decision Tree
| Situation | Command |
|---|
| New task | clawctl add "Subject" -d "Details" |
| Find work | clawctl next then clawctl claim <id> |
| Blocked | clawctl block <id> --by <blocker-id> and notify via clawctl msg |
| Finished | clawctl done <id> -m "Result" |
| Hand off | clawctl msg <agent> "Ready for you" --task <id> --type handoff |
| Ready for review | clawctl review <id> |
| Catch up | clawctl feed --last 20 or clawctl summary |
| Link artifacts | Add --meta '{"note":"path/to/file"}' to done, claim, start, or block |
Task Statuses
pending → claimed → in_progress → done
↘ blocked ↗ ↘ cancelled
↘ review ↗
list excludes done/cancelled by default. Use --all for history (newest first).
Commands
Tasks
| Command | Description |
|---|
add SUBJECT | Create task. -d desc, -p 0|1|2 priority, --for AGENT assign, --parent ID |
list | Active tasks. --mine, --status STATUS, --owner AGENT, --all |
next | Highest-priority actionable task for current agent |
claim ID | Claim task. --force overrides ownership, --meta JSON |
start ID | Begin work (in_progress). --meta JSON |
done ID | Complete. -m note, --force, --meta JSON |
review ID | Mark ready for review. --meta JSON |
cancel ID | Cancel task. --meta JSON |
block ID --by OTHER | Mark blocked. --meta JSON |
board | Kanban board grouped by status |
Messages
| Command | Description |
|---|
msg AGENT BODY | Send message. --task ID, --type TYPE (comment, status, handoff, question, answer, alert) |
broadcast BODY | Alert all agents |
inbox | Read messages. --unread for unread only |
Fleet
| Command | Description |
|---|
checkin | Heartbeat — update presence, report unread count |
register NAME | Register agent. --role TEXT |
fleet | All agents with status and current task |
whoami | Identity, role, and DB path |
Monitoring
| Command | Description |
|---|
feed | Activity log. --last N, --agent NAME, --meta |
summary | Fleet overview with counts and recent events |
dashboard | Web UI. --port INT, --stop, --verbose |