docs/cli/workboard.md
openclaw workboard is the terminal surface for the bundled
Workboard plugin. It lets an operator list cards, create a
card, inspect one card, and ask the running Gateway to dispatch ready work into
subagent worker runs.
Enable the plugin before using the command:
openclaw plugins enable workboard
openclaw gateway restart
openclaw workboard list [--board <id>] [--status <status>] [--json]
openclaw workboard create <title...> [--notes <text>] [--status <status>] [--priority <priority>] [--agent <id>] [--board <id>] [--labels <items>] [--json]
openclaw workboard show <id> [--json]
openclaw workboard dispatch [--url <url>] [--token <token>] [--timeout <ms>] [--json]
The command reads and writes the same plugin-owned SQLite database used by the dashboard and Workboard agent tools. Card ids can be passed by full id or by an unambiguous prefix when a command accepts a card id.
listopenclaw workboard list
openclaw workboard list --board default --status ready
openclaw workboard list --json
Text output is compact:
7f4a2c10 ready high default agent-a Fix stale worker heartbeat
Columns are id prefix, status, priority, board id, optional agent id, and title.
Flags:
| Flag | Purpose |
|---|---|
--board <id> | Limit results to one board namespace |
--status <status> | Limit results to one Workboard status |
--json | Print the full card list as machine JSON |
createopenclaw workboard create "Fix stale worker heartbeat" --priority high --labels bug,workboard
openclaw workboard create "Write Workboard docs" --status ready --agent docs-agent --board docs --notes "Cover CLI, slash command, dispatch, and SQLite state."
Flags:
| Flag | Purpose |
|---|---|
--notes <text> | Initial card notes |
--status <status> | Initial status, default todo |
--priority <priority> | Priority, default normal |
--agent <id> | Assign the card to an agent or owner id |
--board <id> | Store the card on a board namespace |
--labels <items> | Comma-separated labels |
--json | Print the created card as machine JSON |
create writes directly to Workboard SQLite state. The card is immediately
visible in the Control UI Workboard tab and to Workboard tools.
showopenclaw workboard show 7f4a2c10
openclaw workboard show 7f4a2c10 --json
Text output prints the compact card line and notes. JSON output returns the full card record, including execution metadata, attempts, comments, links, proof, artifacts, worker logs, protocol state, diagnostics, and automation metadata.
dispatchopenclaw workboard dispatch
openclaw workboard dispatch --json
openclaw workboard dispatch --url http://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
dispatch first calls the running Gateway RPC method
workboard.cards.dispatch. That path uses the same subagent runtime as the
dashboard dispatch action, so ready cards become task-tracked worker runs with
linked session keys. Cards with an assigned agent use agent-scoped subagent
session keys; unassigned cards keep an unscoped subagent key so the Gateway's
configured default agent is preserved.
The dispatch loop:
ready.Selection is intentionally conservative. One dispatch starts at most three workers by default, skips archived or already-claimed cards, and starts only one card per owner or agent in a single pass. Cards already owned by active running or review work are left for a later dispatch.
If worker start fails after a card is claimed, Workboard blocks that card, clears the claim, and records the failure in card execution and worker-log metadata. This keeps failed starts visible instead of silently returning the card to the queue.
If no explicit Gateway target is provided and the local Gateway is unavailable
or does not expose the Workboard dispatch method yet, the CLI falls back to
data-only dispatch against local Workboard state. Data-only dispatch can still
promote dependencies, clean stale claims, and block timed-out runs, but it does
not start workers. Auth, permission, validation failures, and failures for an
explicit --url or --token target are reported directly.
Text output reports worker starts:
dispatch complete: started=2 failures=0
Fallback output is explicit:
gateway unavailable; data dispatch only: promoted=1 blocked=0
JSON output includes the dispatch result. Gateway-backed dispatch can include
started and startFailures; data-only fallback includes
gatewayUnavailable: true. Claim tokens are redacted from card JSON output.
In the dashboard, the same dispatch result is shown as a short summary so an operator can see how many cards started, promoted, blocked, reclaimed, or failed without opening card details.
Command-capable channels can use the matching slash command:
/workboard list
/workboard show 7f4a2c10
/workboard create Fix stale worker heartbeat
/workboard dispatch
Slash command dispatch also uses the Gateway subagent runtime, so it follows the same claim, worker-start, and failure behavior as the dashboard and CLI Gateway path.
/workboard list and /workboard show are read commands for authorized command
senders. /workboard create and /workboard dispatch mutate board state and
require owner status on chat surfaces or a Gateway client with operator.write
or operator.admin.
The CLI dispatch path calls Gateway RPC with operator.read and
operator.write scopes. A read-only Gateway token can inspect Workboard data
through read methods, but it cannot create cards or dispatch workers.
Local list, create, and show commands operate on the local OpenClaw state
directory used by the current profile. Use --dev or --profile <name> on the
top-level openclaw command when you need a different state root.
Confirm the plugin is enabled for the same profile and state root:
openclaw plugins inspect workboard --runtime --json
If the dashboard shows cards but the CLI does not, check that both commands use
the same --dev or --profile setting.
Start or restart the Gateway:
openclaw gateway restart
openclaw gateway status --deep
Then retry openclaw workboard dispatch. Data-only fallback is useful for local
state cleanup, but worker runs need a live Gateway.
Check for at least one ready card without an active claim:
openclaw workboard list --status ready
Cards can also be skipped when the same owner already has running or review
work. Move completed work to done, release stale claims through the Workboard
tools, or run dispatch again after the active worker finishes.