Documentation Index
Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
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:
Usage
list
| 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 |
create
| 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.
show
dispatch
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:
- Promotes dependency-ready children to
ready. - Blocks expired claims or timed-out worker runs.
- Records dispatch metadata on ready cards.
- Selects a small batch of unclaimed ready cards.
- Claims each selected card for the dispatcher or assigned agent.
- Starts a subagent worker run with bounded card context and the card claim token.
- Stores the worker run id, session key, task linkage when the Gateway task ledger reports it, execution status, and worker log on the card.
--url or --token target are reported directly.
Text output reports worker starts:
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.
Slash Command Parity
Command-capable channels can use the matching slash command:/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.
Permissions
The CLI dispatch path calls Gateway RPC withoperator.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.
Troubleshooting
No Cards Appear
Confirm the plugin is enabled for the same profile and state root:--dev or --profile setting.
Dispatch Says Data-Only
Start or restart the Gateway:openclaw workboard dispatch. Data-only fallback is useful for local
state cleanup, but worker runs need a live Gateway.
Dispatch Starts Nothing
Check for at least oneready card without an active claim:
done, release stale claims through the Workboard
tools, or run dispatch again after the active worker finishes.