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 then clawctl start — take ownership and beginclawctl msg "update" --task — coordinate during workclawctl done -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 |
| Blocked | clawctl block --by and notify via clawctl msg |
| Finished | clawctl done -m "Result" |
| Hand off | clawctl msg "Ready for you" --task --type handoff |
| Ready for review | clawctl review |
| 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 |