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:

Decision Tree

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

Messages

Fleet

Monitoring

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.