--- summary: "Optional dashboard workboard for agent-owned cards and session handoff" read_when: - You want a Kanban-style workboard in the Control UI - You are enabling or disabling the bundled Workboard plugin - You want to track planned agent work without an external project manager title: "Workboard plugin" --- The Workboard plugin adds an optional Kanban-style board to the [Control UI](/web/control-ui): agent-sized work cards, assignment to agents, and a link back to the card's task, run, and dashboard session. Workboard is intentionally small: it tracks local operating work for one OpenClaw Gateway. It is not a replacement for GitHub Issues, Linear, Jira, or other team project management systems. ## Enable it Workboard is bundled but disabled by default: ```bash openclaw plugins enable workboard openclaw gateway restart openclaw dashboard ``` The Workboard tab appears in the dashboard nav. If the tab is visible but the plugin is disabled or blocked by `plugins.allow`/`plugins.deny`, the tab shows a plugin-unavailable state instead of card data. ## Configuration Workboard has no plugin-specific config. Enable/disable it with the standard plugin entry: ```json5 { plugins: { entries: { workboard: { enabled: true, config: {}, }, }, }, } ``` ```bash openclaw plugins disable workboard openclaw gateway restart ``` ## Card fields | Field | Values | | ----------- | ------------------------------------------------------------------------------------------------------------- | | `status` | `triage`, `backlog`, `todo`, `scheduled`, `ready`, `running`, `review`, `blocked`, `done` | | `priority` | `low`, `normal`, `high`, `urgent` | | `labels` | free-form strings | | `agentId` | optional assigned agent | | linked refs | optional task, run, session, or source URL | | `execution` | optional metadata for a Codex/Claude run started from the card (engine, mode, model, session, run id, status) | Cards also carry compact metadata for attempts, comments, links, proof, artifacts, automation settings, attachments, worker logs, worker protocol state, claims, diagnostics, notifications, template id, archive state, and stale-session detection, plus a recent-events list (`created`, `edited`, `moved`, `linked`, `specified`, `decomposed`, `claimed`, `heartbeat`, `execution_updated`, `attempt_started`, `attempt_updated`, `comment_added`, `link_added`, `proof_added`, `artifact_added`, `attachment_added`, `diagnostic`, `notification`, `dispatch`, `orchestration`, `protocol_violation`, `archived`, `unarchived`, `stale`). This metadata lets an operator see how a card moved through the board without opening the linked session; it is local operating context, not a replacement for session transcripts or GitHub issue history. Cards are stored in the plugin's own Gateway state and move with the rest of that Gateway's OpenClaw state (see [Storage](#storage)). ## Starting work from a card Unlinked cards can start work directly: - **Run Codex** / **Run Claude** starts a task-tracked agent run with an explicit engine, sends the card prompt, and marks the card `running`. Codex runs use `openai/gpt-5.5`; Claude runs use `anthropic/claude-sonnet-4-6`. - **Open Codex** / **Open Claude** creates a linked dashboard session without sending the card prompt or moving the card, for manual work that stays attached to the board. Autonomous starts use the Gateway's task-tracked agent run path (default agent and model unless Codex/Claude is chosen explicitly); Workboard then links the resulting task, run id, and session key back onto the card. Each linked execution also records an attempt summary (engine, mode, model, run id, timestamps, status, rolling failure count) so repeated failures stay visible. The dashboard refreshes task status from the Gateway task ledger, matching tasks to cards by task id, run id, or linked session key. A queued/running task keeps the card's lifecycle active; a finished, failed, timed-out, or cancelled task moves the card toward `review` or `blocked` using the same sync rule as linked sessions (see [Session lifecycle sync](#session-lifecycle-sync)). ## Agent tools | Tool | Purpose | | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workboard_list` | List compact cards with claim/diagnostic state; optional board filter. | | `workboard_read` | Return one card plus bounded worker context (notes, attempts, comments, links, proof, artifacts, parent results, recent assignee work, active diagnostics). | | `workboard_create` | Create a card with optional parents, tenant, skills, board, workspace metadata, idempotency key, runtime limit, retry budget. | | `workboard_link` | Link a parent to a child card. Children stay `todo` until every parent reaches `done`, then dispatch promotion moves them to `ready`. | | `workboard_claim` | Claim a card for the calling agent; moves `backlog`/`todo`/`ready` into `running`. | | `workboard_heartbeat` | Refresh the claim heartbeat during a longer run. | | `workboard_release` | Release the claim after completion, pause, or handoff; can move the card to a next status. | | `workboard_complete` / `workboard_block` | Structured lifecycle tools for final summaries, proof, artifacts, and created-card manifests (must reference cards linked back to the completed card) or blocker reasons. | | `workboard_attachment_add` / `workboard_attachment_read` / `workboard_attachment_delete` | Store small card attachments in plugin SQLite state, index on the card, expose in worker context. | | `workboard_worker_log` / `workboard_protocol_violation` | Record worker log lines and block a card when an automated worker stops without calling `workboard_complete`/`workboard_block`. | | `workboard_board_create` / `workboard_board_archive` / `workboard_board_delete` | Manage persisted board metadata (display name, description, archive state, default workspace). | | `workboard_runs` | Return the persisted run-attempt history for a card. | | `workboard_specify` | Turn a rough triage/backlog card into a clarified `todo` card; records the spec summary on the card. | | `workboard_decompose` | Fan a parent orchestration card into linked children, inheriting board/tenant metadata; can complete the parent with a created-card manifest. | | `workboard_notify_subscribe` / `workboard_notify_list` / `workboard_notify_events` / `workboard_notify_advance` / `workboard_notify_unsubscribe` | Manage notification subscriptions. Event reads are replay-safe; `advance` moves the durable cursor so callers resume without losing or double-reading completed/failed/stale card events. | | `workboard_boards` / `workboard_stats` | Inspect board namespaces and queue stats. | | `workboard_promote` / `workboard_reassign` / `workboard_reclaim` | Recover or hand off stuck work. | | `workboard_comment` / `workboard_proof` | Add handoff notes or attach proof/artifact references. | | `workboard_unblock` | Move blocked work back to `todo`. | | `workboard_dispatch` | Nudge dependency promotion or stale-claim cleanup. | Claimed cards reject agent-tool mutations from other agents unless the caller holds the claim token returned by `workboard_claim`. Every card returned by an agent tool or Gateway RPC call redacts `metadata.claim.token` to `[redacted]` (the token itself is returned once, top-level, only from `workboard_claim`), so dashboard operators and other agents can inspect claim state without ever seeing a usable token. Recovery goes through `workboard_promote`/`workboard_reassign`/`workboard_reclaim`, which do not require the token. ## Dispatch Dispatch is Gateway-local: it does not spawn arbitrary OS processes. Normal OpenClaw subagent sessions still own execution. One dispatch pass: 1. Promotes dependency-ready cards. 2. Records dispatch metadata on ready cards. 3. Blocks expired claims or timed-out runs. 4. Marks board-configured triage cards as orchestration candidates. 5. Claims a small batch of ready cards and starts worker runs through the Gateway subagent runtime. Workers get bounded card context plus the claim token needed to heartbeat, complete, or block the card through the Workboard tools. ### Worker selection Each pass starts **at most 3 workers by default**. Ready cards are ordered by priority, then position, then creation time. A pass starts only one card per owner/agent and skips owners that already have running or review work on the board. Archived cards, cards with an active claim, and cards not in `ready` status are never selected for worker starts (they can still be affected by the data side of dispatch: stale-claim cleanup, dependency promotion, timeout cleanup). Session keys are deterministic per board/card, so repeated dispatches route back to the same worker lane instead of creating unrelated sessions: - Assigned cards: `agent::subagent:workboard--` - Unassigned cards: `subagent:workboard--` (Gateway resolves the configured default agent) If a worker cannot be started after a card is claimed, Workboard blocks the card, clears the claim, records the run-start failure, and appends a worker log line - visible in the dashboard, CLI JSON, agent tools, and card diagnostics. ### Entry points - Dashboard dispatch action - `openclaw workboard dispatch` - `/workboard dispatch` on a command-capable channel All three use the Gateway subagent runtime when the Gateway is available. The CLI has one operator fallback: if the Gateway call fails with a connection/unavailable error (or an `unknown method` error for older Gateways), and no explicit `--url`/`--token` target and no configured remote Gateway (`OPENCLAW_GATEWAY_URL` or `gateway.mode: remote`) apply, the CLI runs data-only dispatch against local SQLite state - it can promote dependencies, clean stale claims, and block timed-out runs, but cannot start workers. Auth, permission, and validation failures from a reachable Gateway are not treated as unavailable; they surface as command errors, and so does any Gateway failure when an explicit `--url`/`--token` target was given. Board metadata can set `autoDecompose`, `autoDecomposePerDispatch`, `defaultAssignee`, and `orchestratorProfile`. OpenClaw records this intent and exposes it in worker context; actual specification/decomposition still runs through the normal Workboard tools. ## CLI and slash command ```bash openclaw workboard list [--board ] [--status ] [--include-archived] [--json] openclaw workboard create "Fix stale card lifecycle" --priority high --labels bug,workboard openclaw workboard show [--json] openclaw workboard dispatch [--board ] [--json] ``` `list` text output hides archived cards by default (`--include-archived` overrides); `--json` always includes archived cards, matching the full-card contract used by existing scripts. `show` accepts an unambiguous id prefix. `list`, `create`, and `show` always read/write local plugin state directly. Only `dispatch` calls the running Gateway, with the fallback described above. See [Workboard CLI](/cli/workboard) for full flags, JSON output, Gateway fallback behavior, id-prefix handling, dispatch selection rules, and troubleshooting. `/workboard list`, `/workboard show `, `/workboard create `, and `/workboard dispatch` mirror the CLI. List and show are read operations for any authorized command sender. Create and dispatch require owner status on chat surfaces, or a Gateway client with `operator.write`/`operator.admin`. ## Session lifecycle sync Cards can link to an existing dashboard session, or one created when you start work from the card. Linked cards show the session lifecycle inline: running, stale, linked idle, done, failed, or missing. You can also capture an existing session from the Sessions tab with **Add to Workboard**; the card links to that session, uses the session label or recent user prompt as title, and seeds notes from the recent user prompt plus the latest assistant response when available. If the linked session goes missing, the card stays linked for context and still offers start controls to restart into a fresh session. If an active linked session stops reporting recent activity, Workboard marks the card `stale` and stores that as metadata until the lifecycle clears it. While a card is in an active work state, Workboard follows the linked session: | Linked session state | Card status | | ------------------------------------- | ----------- | | active | `running` | | completed | `review` | | failed, killed, timed out, or aborted | `blocked` | **Manual review states win.** Moving a card to `review`, `blocked`, or `done` stops auto-sync for that card until you move it back to `todo` or `running`. Starting a card uses normal Gateway sessions; Workboard only stores card metadata and links. 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 run - Workboard marks that card `blocked` so it stays visible for follow-up. New cards can start from Workboard templates (`bugfix`, `docs`, `release`, `pr_review`, `plugin`). Templates prefill title, notes, labels, and priority; the template id is stored as card metadata. ## Dashboard workflow 1. Open the Workboard tab in the Control UI. 2. Create a card with a title, notes, priority, labels, optional agent, and optional linked session - or open Sessions and choose **Add to Workboard** for an existing session. 3. Drag the card between columns, or focus its compact status control and use the menu or ArrowLeft/ArrowRight. 4. Start work from the card to create or reuse a dashboard session. 5. Open the linked session from the card while the agent works. 6. Let lifecycle sync move running work into `review`/`blocked`, then manually move the card to `done` when accepted. ## Diagnostics Diagnostics are computed from local card metadata. Built-in checks flag: | Kind | Condition | | --------------------------- | ------------------------------------------------------------------------------ | | `stranded_ready` | Assigned `todo`/`backlog`/`ready` card not updated in over 1 hour. | | `running_without_heartbeat` | `running` card with no claim heartbeat or execution update in over 20 minutes. | | `blocked_too_long` | `blocked` card not updated in over 24 hours. | | `repeated_failures` | Card's tracked failure count reaches 2 or more. | | `missing_proof` | `done` card with no proof, artifacts, or attachments. | | `orphaned_session` | `running` card with a `sessionKey` but no `execution` metadata. | ## Permissions Gateway RPC methods live under `workboard.*`: | Scope | Methods | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `operator.read` | `cards.list`, `cards.export`, `cards.diagnostics`, attachment list/get, notification event reads, `boards.list`, `cards.stats`, `cards.runs` | | `operator.write` | `cards.diagnostics.refresh`, create/update/move/delete/comment/link/linkDependency/proof/artifact, attachment add/delete, worker log, protocol violation, claim/heartbeat/release/promote/reassign/reclaim/complete/block/unblock, `cards.dispatch`, `cards.bulk`, archive, `boards.upsert`/`archive`/`delete`, `cards.specify`/`decompose`, notification subscribe/delete/advance | No RPC method requires `operator.admin`. Browsers connected with read-only operator access can inspect the board but cannot mutate cards. ## Storage Workboard stores durable data in a plugin-owned relational SQLite database under the OpenClaw state directory: boards, cards, labels, lifecycle events, run attempts, comments, dependency links, proof, artifact references, attachment metadata and blobs, diagnostics, notifications, worker logs, protocol state, and subscriptions all live in Workboard tables (not plugin key-value entries). A card export preserves the board narrative without inlining attachment blob contents. Installations that used Workboard in the `.28` release can run `openclaw doctor --fix` to migrate the shipped legacy plugin-state namespaces (`workboard.cards`, `workboard.boards`, `workboard.notify`, and, if present, `workboard.attachments`) into the relational database. ## Troubleshooting **The tab says Workboard is unavailable** ```bash openclaw plugins inspect workboard --runtime --json ``` If `plugins.allow` is configured, add `workboard` to it. If `plugins.deny` contains `workboard`, remove it before enabling the plugin. **Cards do not save** Confirm the browser connection has `operator.write` access. Read-only operator sessions can list cards but cannot create, edit, move, or delete them. **Starting a card does not open the expected session** Check the card's agent id and linked session, then open Sessions or Chat to inspect the actual run state. **Dispatch does not start a worker** Confirm there is at least one `ready` card without an active claim: ```bash openclaw workboard list --status ready ``` If the CLI reports data-only dispatch, start or restart the Gateway and retry - data-only dispatch updates local board state but cannot start subagent worker runs. Cards can also be skipped when another card for the same owner or agent is already running or waiting for review; complete, block, or release that active work before dispatching more for the same owner. ## Related - [Control UI](/web/control-ui) - [Workboard CLI](/cli/workboard) - [Plugins](/tools/plugin) - [Manage plugins](/plugins/manage-plugins) - [Sessions](/concepts/session)