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 |
1---2name: clawctl3description: Coordination layer for OpenClaw agent fleets (tasks, messaging, activity feed, dashboard).4---56# Setup78```bash9clawctl init # create the database10export CLAW_AGENT=your-name # set identity (falls back to $USER with warning)11export CLAW_DB=~/.openclaw/clawctl.db # optional, this is the default12```1314# Operational Rhythm1516Follow this pattern every session:17181. `clawctl checkin` — register presence, see unread count192. `clawctl inbox --unread` — read messages before picking up work203. `clawctl next` — find highest-priority actionable task (or `clawctl list --mine`)214. `clawctl claim <id>` then `clawctl start <id>` — take ownership and begin225. `clawctl msg <agent> "update" --task <id>` — coordinate during work236. `clawctl done <id> -m "what I did"` then `clawctl next` — complete and move on2425Only claim tasks assigned to you or matching your role. Completing an already-done task is a safe no-op.2627# Decision Tree2829| Situation | Command |30|-----------|---------|31| New task | `clawctl add "Subject" -d "Details"` |32| Find work | `clawctl next` then `clawctl claim <id>` |33| Blocked | `clawctl block <id> --by <blocker-id>` and notify via `clawctl msg` |34| Finished | `clawctl done <id> -m "Result"` |35| Hand off | `clawctl msg <agent> "Ready for you" --task <id> --type handoff` |36| Ready for review | `clawctl review <id>` |37| Catch up | `clawctl feed --last 20` or `clawctl summary` |38| Link artifacts | Add `--meta '{"note":"path/to/file"}'` to `done`, `claim`, `start`, or `block` |3940# Task Statuses4142```43pending → claimed → in_progress → done44 ↘ blocked ↗ ↘ cancelled45 ↘ review ↗46```4748`list` excludes done/cancelled by default. Use `--all` for history (newest first).4950# Commands5152## Tasks5354| Command | Description |55|---------|-------------|56| `add SUBJECT` | Create task. `-d` desc, `-p 0\|1\|2` priority, `--for AGENT` assign, `--parent ID` |57| `list` | Active tasks. `--mine`, `--status STATUS`, `--owner AGENT`, `--all` |58| `next` | Highest-priority actionable task for current agent |59| `claim ID` | Claim task. `--force` overrides ownership, `--meta JSON` |60| `start ID` | Begin work (in_progress). `--meta JSON` |61| `done ID` | Complete. `-m` note, `--force`, `--meta JSON` |62| `review ID` | Mark ready for review. `--meta JSON` |63| `cancel ID` | Cancel task. `--meta JSON` |64| `block ID --by OTHER` | Mark blocked. `--meta JSON` |65| `board` | Kanban board grouped by status |6667## Messages6869| Command | Description |70|---------|-------------|71| `msg AGENT BODY` | Send message. `--task ID`, `--type TYPE` (comment, status, handoff, question, answer, alert) |72| `broadcast BODY` | Alert all agents |73| `inbox` | Read messages. `--unread` for unread only |7475## Fleet7677| Command | Description |78|---------|-------------|79| `checkin` | Heartbeat — update presence, report unread count |80| `register NAME` | Register agent. `--role TEXT` |81| `fleet` | All agents with status and current task |82| `whoami` | Identity, role, and DB path |8384## Monitoring8586| Command | Description |87|---------|-------------|88| `feed` | Activity log. `--last N`, `--agent NAME`, `--meta` |89| `summary` | Fleet overview with counts and recent events |90| `dashboard` | Web UI. `--port INT`, `--stop`, `--verbose` |
dvcrn