Workboard

The Workboard is a Kanban-style task board bundled with OpenClaw as a plugin (disabled by default). It lets you collect agent-sized work cards, assign them to specific agents, dispatch workers, and track progress from the dashboard, CLI, or chat.

The first Workboard entries appear in v2026.5.28; the orchestration primitives (dependencies, dispatch, claims) landed in v2026.5.31 and v2026.6.1. Official reference: Workboard plugin and Workboard CLI.

info

The Workboard tracks work inside one Gateway. It is not an issue tracker: keep GitHub Issues, Linear or Jira for the project itself.

Enable the Workboard

openclaw plugins enable workboard
openclaw dashboard

Enabling applies to a running Gateway without a restart. openclaw dashboard opens the Control UI; the Workboard tab appears once the plugin has loaded. The openclaw workboard CLI is only available while the plugin is enabled.

You can also enable it in config:

~/.openclaw/openclaw.json
{
  plugins: { entries: { workboard: { enabled: true } } },
}

Cards

What a Card Contains

Field	Required	Description
Title	Yes	Short description of the task
Notes	No	Context, instructions, or prompt for the agent
Priority	No	`low`, `normal`, `high`, or `urgent`
Labels	No	Custom tags for filtering (`bug`, `docs`, `feature`)
Agent ID	No	Assign to a specific agent
Linked resource	No	Task ID, run ID, session ID, or source URL

Card Lifecycle

Cards have nine statuses:

triage → backlog → todo → ready → running → review → done
                     ↘ scheduled ↗        ↘ blocked

Status	Meaning
`triage`	Rough idea, not yet specified
`backlog`	Accepted, not yet queued
`todo`	Queued; children wait here until every parent is `done` (the default for new cards)
`scheduled`	Held until a scheduled time
`ready`	Eligible for dispatch
`running`	Linked session is active
`review`	Linked session completed, needs human review
`blocked`	Run failed, timed out, or was aborted
`done`	Work accepted and complete

Automatic Lifecycle Sync

If a card is linked to a session, the Workboard updates the card state automatically:

Active session → card moves to running
Completed session → card moves to review
Failed, killed, timed-out or aborted session → card moves to blocked

Once you manually move a card to review, blocked, or done, automatic sync stops until you move it back to todo or running.

CLI Commands

Create a Card

openclaw workboard create "Write Workboard docs" \
  --status ready \
  --priority high \
  --labels docs,workboard \
  --agent docs-agent \
  --board docs \
  --notes "Cover CLI, slash command, dispatch, and SQLite state."

New cards start in todo unless you pass --status. Add --json to print the created card.

List Cards

openclaw workboard list
openclaw workboard list --board default --status ready
openclaw workboard list --json
openclaw workboard list --include-archived

Show Card Details

openclaw workboard show 7f4a2c10
openclaw workboard show 7f4a2c10 --json

Move a Card

openclaw workboard move 7f4a2c10 --status review
openclaw workboard move 7f4a2c10 --status done

move is the same operator action as dragging a card in the dashboard. Dependency and schedule holds still apply.

Dispatch Workers

Dispatch scans for ready cards and starts agent workers:

openclaw workboard dispatch
openclaw workboard dispatch --max-starts 10
openclaw workboard dispatch --url http://127.0.0.1:18789 \
  --token "$OPENCLAW_GATEWAY_TOKEN"

One dispatch starts at most three workers by default, and only one card per owner or agent per pass. --max-starts raises the cap, but the one-per-agent rule still applies. If the local Gateway is stopped, dispatch runs data-only: it promotes dependencies and cleans stale claims but starts no workers.

Slash Commands

On command-capable channels (Slack, Discord):

/workboard list
/workboard show 7f4a2c10
/workboard create Fix stale worker heartbeat
/workboard dispatch

Dispatch Workflow

When you run dispatch, the Workboard:

Promotes dependency-ready children to ready state
Blocks expired claims or timed-out worker runs
Records dispatch metadata on ready cards
Selects a batch of unclaimed ready cards
Claims each card for the dispatcher or assigned agent
Starts workers: each worker is a subagent run with bounded card context and the claim token

Dispatch can be triggered from (a card's Start action in the dashboard starts that one card directly):

The dashboard dispatch button
openclaw workboard dispatch in the CLI
/workboard dispatch on chat channels

Dispatch does not run on its own. To dispatch on a schedule, run openclaw workboard dispatch from a cron job or systemd timer on the Gateway host. An agent cannot do it for you: the workboard_dispatch tool promotes dependencies and cleans stale claims but does not start workers. For a scheduled agent review of the board, see Self-Organizing Heartbeat.

Agent Coordination Tools

The Workboard exposes tools that agents can call during execution. The card tools are optional plugin tools: enabling Workboard gives agents only the three workboard_sessions_board_* tools. An agent that should create, claim or complete cards needs them allowed:

~/.openclaw/openclaw.json
{
  plugins: { entries: { workboard: { enabled: true } } },
  agents: {
    entries: {
      main: {
        tools: { alsoAllow: ["workboard"] },
      },
    },
  },
}

Workers that the Workboard starts from a card (Start or dispatch) do not need this: each worker run is granted workboard_heartbeat, workboard_complete and workboard_block for its card.

Tool	What It Does
`workboard_list`	List cards with claim and diagnostic state
`workboard_read`	Read one card plus bounded worker context
`workboard_create`	Create a card with optional parents, skills, and workspace metadata
`workboard_claim`	Claim a card for the calling agent (moves it to `running`)
`workboard_link`	Link a parent to a child; the child waits in `todo` until every parent is `done`
`workboard_heartbeat`	Refresh the claim heartbeat during longer runs
`workboard_release`	Release the claim after completion, pause or handoff
`workboard_complete` / `workboard_block`	Finish with a summary and proof, or block with a reason
`workboard_specify`	Turn a rough triage/backlog card into a clarified `todo` card
`workboard_decompose`	Fan a parent card into linked children
`workboard_runs`	Return persisted run-attempt history for a card
`workboard_dispatch`	Nudge dependency promotion and stale-claim cleanup; does not launch workers

The full list, including attachments, notifications and recovery tools, is in the plugin reference.

Dashboard Workflow

The full workflow in the Control UI:

Open the Workboard tab
Create a card — fill in title, notes, priority, labels, and optionally assign an agent
Drag cards between columns — or use the status menu to change state
Start work from a card — creates or reuses a dashboard session with the card's notes as the prompt
Watch the linked session as the agent works
Lifecycle sync moves the card to review or blocked automatically
Manually move to done when you're satisfied with the result

tip

You can also capture an existing session as a card: open Sessions → choose Add to Workboard.

Templates

Workboard supports templates for common card types. Templates pre-fill title, notes, labels, and priority. The built-in template ids are bugfix, docs, release, pr_review and plugin.

Practical Recipes

Research → Writing Pipeline

A researcher agent gathers information, a writer agent turns it into content:

~/.openclaw/openclaw.json
{
  plugins: { entries: { workboard: { enabled: true } } },
  agents: {
    ownership: "explicit",
    defaults: { systemAgent: { agentId: "researcher" } },
    entries: {
      researcher: {
        model: "anthropic/claude-opus-5-5",
        workspace: "~/.openclaw/workspace-researcher",
      },
      writer: {
        model: "anthropic/claude-sonnet-5-5",
        workspace: "~/.openclaw/workspace-writer",
      },
    },
  },
}

Create Workboard cards for each research topic with --agent researcher --status ready
Run openclaw workboard dispatch
When a researcher run completes, its card moves to review
Review the research, then create cards assigned to writer that reference the research sessions (--notes), or link them as children so they wait for the research cards
Dispatch again for the writing pass

Bug Triage

Queue bugs as cards with priority and labels, let agents claim them:

openclaw workboard create "Fix memory leak in gateway session handler" \
  --status ready \
  --priority urgent \
  --labels bug,gateway \
  --agent coder

openclaw workboard create "Update FAQ for v2026.10 changes" \
  --status ready \
  --priority normal \
  --labels docs \
  --agent docs-writer

openclaw workboard dispatch

Autonomous Sub-Tasks

An orchestrator agent (with tools.alsoAllow: ["workboard"]) breaks complex work into sub-cards:

You create one card: "Audit all API endpoints for auth bypasses"
The orchestrator agent claims the card
It uses workboard_decompose (or workboard_create plus workboard_link) to make linked child cards for each endpoint
Children wait in todo until their parents are done; dispatch promotes them to ready
Dispatch starts workers for the children, one per agent per pass
You review the results and move cards to done

Self-Organizing Heartbeat

To review the board on a schedule, create an automation job rather than a heartbeat checklist (HEARTBEAT.md is retired):

openclaw automations add "every 2h" \
  "Check the Workboard for blocked cards. For each, diagnose the failure and either unblock it or create a fix card. Send me a short status summary." \
  --name workboard-review --agent main --session isolated \
  --announce --channel telegram --to "123456789"

The agent running this job needs the card tools (tools.alsoAllow: ["workboard"]). Keep exec approvals on for anything the fix cards might do unattended; see Security hardening.

Permissions

Operation	Required Permission
`list`, `show` (and the `export`/`diagnostics` Gateway methods)	`operator.read`
`create`, `move`, `dispatch` (and `diagnostics.refresh`)	`operator.write`

Troubleshooting

"Workboard is unavailable"

openclaw plugins inspect workboard --runtime --json

Check that the plugin is enabled and the state root is writable.

Cards not saving

Verify the gateway is running and the plugin can write to its state directory.

Dispatch starts nothing

openclaw workboard list --status ready

At least one ready card must exist without an active claim.

Dispatch says "data-only"

openclaw gateway restart
openclaw gateway status --deep

Enable the Workboard​

Cards​

What a Card Contains​

Card Lifecycle​

Automatic Lifecycle Sync​

CLI Commands​

Create a Card​

List Cards​

Show Card Details​

Move a Card​

Dispatch Workers​

Slash Commands​

Dispatch Workflow​

Agent Coordination Tools​

Dashboard Workflow​

Templates​

Practical Recipes​

Research → Writing Pipeline​

Bug Triage​

Autonomous Sub-Tasks​

Self-Organizing Heartbeat​

Permissions​

Troubleshooting​

See Also​