docs/plugins/workboard.md
The Workboard plugin adds an optional Kanban-style board to the Control UI. Use it to collect agent-sized work cards, assign them to agents, and jump from a card into the linked dashboard session.
Workboard is intentionally small. It tracks local operating work for an OpenClaw Gateway; it is not a replacement for GitHub Issues, Linear, Jira, or other team project management systems.
Workboard is a bundled plugin and is disabled by default unless you enable it in plugin config.
Enable it with:
openclaw plugins enable workboard
openclaw gateway restart
Then open the dashboard:
openclaw dashboard
The Workboard tab appears in the dashboard navigation. If the tab is visible
but the plugin is disabled or blocked by plugins.allow / plugins.deny, the
view shows a plugin-unavailable state instead of local card data.
Each card stores:
backlog, todo, running, review, blocked, or donelow, normal, high, or urgentCards are stored in the plugin's Gateway state. They are local to the Gateway state directory and move with the rest of that Gateway's OpenClaw state.
Workboard keeps compact per-card metadata so operators can see how a card moved through the board without opening the linked session. Events, attempt summaries, proof snippets, related links, comments, archive markers, and stale-session markers are intentionally local metadata; they do not replace session transcripts or GitHub issue history.
Unlinked cards can start work from the card. Start uses the Gateway's configured default agent and model. Codex and Claude actions are optional explicit model choices:
running.Execution metadata stores the selected engine, mode, model ref, session key,
run id, and lifecycle status on the card. Codex executions use
openai/gpt-5.5; Claude executions use anthropic/claude-sonnet-4-6.
Each linked execution also records an attempt summary on the same card record. The attempt summary keeps the engine, mode, model, run id, timestamps, status, and rolling failure count so repeated failures remain visible on the board.
Workboard also exposes optional agent tools for board-aware workflows:
workboard_list lists compact cards with claim and diagnostic state.workboard_read returns one card plus bounded worker context built from notes,
attempts, comments, links, proof, artifacts, and active diagnostics.workboard_claim claims a card for the calling agent and moves backlog or todo
cards into running.workboard_heartbeat refreshes the claim heartbeat during longer runs.workboard_release releases the claim after completion, pause, or handoff and
can move the card to a next status.workboard_comment, workboard_proof, and workboard_unblock let an agent
add handoff notes, attach proof or artifact references, and move blocked work
back to todo.Claimed cards reject agent-tool mutations from other agents unless the caller
has the claim token returned by workboard_claim. Dashboard operators still use
the normal Gateway RPC surface and can recover or reassign cards.
Workboard diagnostics are computed from local card metadata. The built-in checks flag assigned cards that wait too long, running cards without recent heartbeat, blocked cards that need attention, repeated failures, done cards without proof, and running cards that only have a loose session link.
Cards can be linked to existing dashboard sessions or to the session created when you start work from a card. Linked cards show the session lifecycle inline: running, stale, linked idle, done, failed, or missing.
If the linked session is missing, the card stays linked for context and still offers start controls so you can restart work into a fresh dashboard session. If an active linked session stops reporting recent activity, Workboard marks the card stale and stores the marker as card metadata until the lifecycle clears it.
You can also capture an existing dashboard session from the Sessions tab with Add to Workboard. The card is linked to that session, uses the session label or recent user prompt as the title, and seeds notes from the recent user prompt plus the latest assistant response when chat history is available.
Workboard follows the linked session while the card is still in an active work state:
runningreviewblockedManual review states win. If you move a card to review, blocked, or done,
Workboard stops auto-moving that card until you move it back to todo or
running.
Starting a card uses normal Gateway sessions. The Workboard plugin only stores card metadata and links; the conversation transcript, model selection, and run lifecycle stay owned by the regular session system.
Use Stop on a live linked card to abort the active session run. Workboard marks
that card blocked so it remains visible for follow-up.
New cards can start from Workboard templates for bugfixes, docs, releases, PR reviews, or plugin work. Templates prefill title, notes, labels, and priority, and the selected template id is stored as card metadata.
The plugin registers Gateway RPC methods under the workboard.* namespace:
workboard.cards.list requires operator.readworkboard.cards.export requires operator.readworkboard.cards.diagnostics requires operator.readworkboard.cards.diagnostics.refresh requires operator.writeoperator.writeBrowsers connected with read-only operator access can inspect the board but cannot mutate cards.
Workboard has no plugin-specific config today. Enable or disable it with the standard plugin entry:
{
plugins: {
entries: {
workboard: {
enabled: true,
config: {},
},
},
},
}
Disable it again with:
openclaw plugins disable workboard
openclaw gateway restart
Check plugin policy:
openclaw plugins inspect workboard --runtime --json
If plugins.allow is configured, add workboard to that allowlist. If
plugins.deny contains workboard, remove it before enabling the plugin.
Confirm the browser connection has operator.write access. Read-only operator
sessions can list cards but cannot create, edit, move, or delete them.
Workboard creates links to normal dashboard sessions. Check the card's agent id and linked session, then open the Sessions or Chat view to inspect the actual run state.