clawctl

name	clawctl
description	Coordination layer for OpenClaw agent fleets (tasks, messaging, activity feed, dashboard).
metadata	{"openclaw":{"emoji":"🛰️","requires":{"bins":["clawctl"]}}}

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:

1. Check in — clawctl checkin — register presence, see unread count
2. Read messages — clawctl inbox --unread — read ALL messages before doing anything else
   • If a message is a proposal or approval request, relay it to the coordinator (don't just return HEARTBEAT_OK)
   • If a message asks you to do something, acknowledge it with clawctl msg
3. Review your work — clawctl list --mine — see what's assigned to you
4. Pick up work — clawctl next — find highest-priority actionable task
5. Read task context — clawctl show <id> — read the full detail, message thread, and blockers BEFORE starting
6. Claim and start — clawctl claim <id> then clawctl start <id>
7. Coordinate — clawctl msg <agent> "update" --task <id> — send updates during work
8. Submit for review — clawctl review <id> — this notifies the creator automatically
9. Move on — clawctl next — pick up the next task

Do NOT call clawctl done directly on tasks that need approval. Use review to submit, then wait for the coordinator to approve or reject.

Review Workflow

This is the approval gate pattern. Use it for any work that needs sign-off.

Agent does work → clawctl review <id>     (creator auto-notified)
                                    ↓
Coordinator reviews → clawctl show <id>   (reads thread + result)
                                    ↓
           clawctl approve <id> -m "LGTM"     → task moves to done
           clawctl reject <id> -r "Needs X"   → task moves to pending (agent re-claims)

As the worker: After review, stop working on that task. Check inbox for the approve/reject decision. If rejected, read the reason with clawctl show <id>, fix the issue, and review again.

As the coordinator: When you see a task in review (via list, board, or inbox notification), use show <id> to inspect the work and message thread, then approve or reject with a reason.

Recovering From Failures

Don't resort to raw SQL. These commands handle recovery:

Problem	Fix
Task stuck in done/cancelled, needs redo	clawctl reset <id> (or --force if not owner)
Task blocked, blocker resolved	clawctl reset <id> to unblock
Need to find a task or message	clawctl search "keyword"
Don't know what a status symbol means	clawctl legend
Need full context on a task	clawctl show <id> (detail + messages + blockers)

Decision Tree

Situation	Command
New task	clawctl add "Subject" -d "Details"
New task for specific agent	clawctl add "Subject" --for <agent> -d "Details"
Find work	clawctl next then clawctl claim <id>
Understand a task	clawctl show <id> — read detail, thread, blockers
Blocked	clawctl block <id> --by <blocker-id> and clawctl msg <owner> "blocked on #<id>"
Work done, needs approval	clawctl review <id> — creator auto-notified
Work done, no approval needed	clawctl done <id> -m "Result"
Approve submitted work	clawctl approve <id> or clawctl approve <id> -m "note"
Reject submitted work	clawctl reject <id> -r "reason"
Redo a completed/cancelled task	clawctl reset <id> (back to pending)
Hand off to another agent	clawctl msg <agent> "Ready for you" --task <id> --type handoff
Find something	clawctl search "query" — searches tasks and messages
Catch up	clawctl feed --last 20 or clawctl summary
Link artifacts	Add --meta '{"note":"path/to/file"}' to mutating commands

Task Statuses

pending → claimed → in_progress → review → done (approved)
                  ↘ blocked ↗           ↘ pending (rejected)
                                         ↘ cancelled

Use clawctl legend to see all status symbols and their meanings.

list excludes done/cancelled by default. Blocked tasks show their blocker IDs inline. 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
show ID	Full detail: status, description, message thread, blockers
search QUERY	Search tasks and messages by keyword
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	Submit for review (auto-notifies creator). --meta JSON
approve ID	Approve a reviewed task (moves to done). -m note, --meta JSON
reject ID	Reject a reviewed task (back to pending). -r reason, --meta JSON
reset ID	Move done/cancelled/blocked back to pending. --force, --meta JSON
cancel ID	Cancel task. --meta JSON
block ID --by OTHER	Mark blocked. --meta JSON
board	Kanban board grouped by status
legend	Status symbol reference

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

Critical Rules for Agents

1. Always read inbox first. Don't skip messages — they may contain approvals, rejections, or handoff requests.
2. Always show <id> before working. Read the full context: description, thread, blockers. Don't start blind.
3. Use review, not done, when approval is needed. The coordinator decides when work is complete.
4. Relay important messages. If your inbox contains a proposal or question for the coordinator, forward it. Don't swallow it.
5. Use reset for retries. If a task failed or needs to be redone, reset it. Don't use raw SQL.
6. Use search to find things. Don't grep the database. clawctl search "keyword" checks tasks and messages.
7. Send updates during long work. clawctl msg <coordinator> "progress update" --task <id> keeps everyone informed.