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---5
6# Setup
7
8```bash
9clawctl init # create the database
10export CLAW_AGENT=your-name # set identity (falls back to $USER with warning)
11export CLAW_DB=~/.openclaw/clawctl.db # optional, this is the default
12```
13
14# Operational Rhythm
15
16Follow this pattern every session:
17
181. `clawctl checkin` — register presence, see unread count
192. `clawctl inbox --unread` — read messages before picking up work
203. `clawctl next` — find highest-priority actionable task (or `clawctl list --mine`)
214. `clawctl claim <id>` then `clawctl start <id>` — take ownership and begin
225. `clawctl msg <agent> "update" --task <id>` — coordinate during work
236. `clawctl done <id> -m "what I did"` then `clawctl next` — complete and move on
24
25Only claim tasks assigned to you or matching your role. Completing an already-done task is a safe no-op.
26
27# Decision Tree
28
29| 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` |
39
40# Task Statuses
41
42```
43pending → claimed → in_progress → done
44 ↘ blocked ↗ ↘ cancelled
45 ↘ review ↗
46```
47
48`list` excludes done/cancelled by default. Use `--all` for history (newest first).
49
50# Commands
51
52## Tasks
53
54| 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 |
66
67## Messages
68
69| 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 |
74
75## Fleet
76
77| 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 |
83
84## Monitoring
85
86| 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` |
modbender