Workboard Plugin: Kanban Board for Agent Cards and Session Handoff

The Workboard plugin introduces an optional Kanban-style board to the Control UI: cards sized for agent work, assignment to agents, and a link back to the card's task, run, and dashboard session.

Workboard stays deliberately minimal: it tracks local operating work for one OpenClaw Gateway. It does not replace GitHub Issues, Linear, Jira, or other team project management systems.

Enable it

Workboard ships bundled but starts disabled:

1. Open Plugins in the Control UI, or run /settings/plugins relative to the configured Control UI base path. For instance, a base path of /openclaw maps to /openclaw/settings/plugins.
2. Locate Workboard and pick Enable. Since Workboard ships with OpenClaw, no Install action is needed.
3. If the UI says a restart is required, restart the Gateway.

Once the plugin runtime loads, the Workboard tab appears in the dashboard nav. While disabled, the tab remains hidden from navigation. Directly opening the /workboard route while the plugin is disabled or blocked by plugins.allow/plugins.deny renders a plugin-unavailable state rather than card data.

The equivalent CLI workflow is:

openclaw plugins enable workboard
openclaw gateway restart
openclaw dashboard

Configuration

Workboard carries no plugin-specific config. Toggle it using the standard plugin entry:

{
  plugins: {
    entries: {
      workboard: {
        enabled: true,
        config: {},
      },
    },
  },
}

openclaw plugins disable workboard
openclaw gateway restart

Card fields

Cards additionally hold 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.

The plugin and Control UI share one Workboard card contract. Dashboard refreshes therefore preserve workspace provenance and authority, claim state, diagnostic actions, and notification sequence numbers instead of projecting a smaller UI-only copy of the card. Unknown diagnostic kinds, diagnostic severities, and notification kinds are ignored until both surfaces support them; they are never rewritten into another valid state.

The open dashboard updates from plugin.workboard.changed invalidations. Each event contains only a store epoch and revision; the UI then rereads canonical cards through the normal operator.read RPC. Multiple revisions coalesce into one follow-up read. Workboard defers that read while a card is being dragged, edited, or written, then resumes after the local interaction finishes. A reconnect always performs a canonical reload. There is no routine full-card poll, and Refresh remains available as manual recovery.

When multiple boards are present, the toolbar shows a Board filter that relies on stored board metadata, not just the cards currently in view. This means empty and archived boards stay available for selection. Cards lacking an explicit board id fall under the default default board. Every board has its own canonical /workboard/<boardId> page, which users can bookmark, share, or pin in the sidebar. The older /workboard?board=<boardId> form still works as a compatibility alias, forwarding to that page while keeping other query parameters intact. Picking All boards navigates back to /workboard.

Card data lives in the plugin's own Gateway state and travels alongside the rest of that Gateway's OpenClaw state (see Storage).

Starting work from a card

Cards that are not linked can begin work right away:

• Run Codex / Run Claude launches a task-tracked agent run with a specific engine, sends the card prompt, and sets the card to running. Codex runs rely on openai/gpt-5.6-sol; Claude runs rely on anthropic/claude-sonnet-4-6.
• Open Codex / Open Claude opens a linked dashboard session without sending the card prompt or changing the card's status, for manual work that remains tied to the board.

Autonomous starts go through the Gateway's task-tracked agent run path (default agent and model unless Codex/Claude is explicitly chosen); Workboard then attaches the resulting task, run id, and session key to the card. Every linked execution also logs an attempt summary (engine, mode, model, run id, timestamps, status, rolling failure count) so recurring failures remain visible.

The dashboard pulls task status from the Gateway task ledger, matching tasks to cards by task id, run id, or linked session key. A queued or running task keeps the card's lifecycle active; a finished, failed, timed-out, or cancelled task pushes the card toward review or blocked following the same sync rule as linked sessions (see Session lifecycle sync).

Agent tools

Proof statuses reflect what a worker reports, not what has been independently confirmed. An passed entry signals that the worker states its command or check succeeded; anyone requiring a separate quality check should review the linked command, URL, or artifact and execute their own verifier. workboard_proof gives back the new record's proofId. When workboard_complete reports the final status for that same proof, supply proofId so the pending record is settled in place, keeping its identity and timestamp intact. A proof that already carries the same terminal status is reused as is. Completion proof lacking proofId stays append-only, meaning a later retry cannot overwrite earlier history just because its command or note matches.

Claimed cards block agent-tool mutations from other agents unless the caller possesses the claim token that workboard_claim returns. Every card delivered by an agent tool or Gateway RPC call hides metadata.claim.token down to [redacted] (the token itself appears once, at the top level, only from workboard_claim), so dashboard operators and other agents can examine claim state without ever encountering a usable token. Recovery uses workboard_promote/workboard_reassign/workboard_reclaim, none of which demand the token.

Dispatch

Dispatch operates locally within the Gateway; it never launches arbitrary OS processes. Standard OpenClaw subagent sessions still handle execution. A single dispatch pass:

1. Advances cards whose dependencies are ready.
2. Writes dispatch metadata onto ready cards.
3. Halts expired claims or runs that have timed out.
4. Flags board-configured triage cards as orchestration candidates.
5. Takes a small batch of ready cards and initiates worker runs via the Gateway subagent runtime.

Workers receive limited card context plus the claim token needed to heartbeat, complete, or block the card through the Workboard tools.

Workspace paths respect the caller's existing filesystem authority. Gateway clients with operator.write can use configured agent workspaces; operator.admin clients can use other host checkouts. Sandboxed agent tools rely on their sandbox workspace access, while unsandboxed workspace-only tools use their configured workspace root. Workboard records that authority when a workspace is assigned and re-checks it against the current caller's authority at dispatch, so a persisted card cannot expand a later caller's access. Older cards with an explicit host workspace but no recorded authority must have that workspace re-saved before a full-host dispatch; cards without a host path take on the current caller's authority at their first dispatch.

Workspace-bound dispatch accepts a directory or Git checkout only when its repository root matches the target agent workspace exactly. A worktree request is narrowed to that directory and stored as a directory workspace, so the host does not materialize the checkout or run repository setup code. The target worker must use a writable, non-shared Docker sandbox for that exact workspace, without elevated execution, persisted host/node exec overrides, or unclassified plugin and MCP tools. Workboard enumerates its registered tools instead of relying on a workboard_* prefix, and dispatch rejects a hot Docker container whose live mount/config hash is outdated. Dispatch reports the incompatible target policy rather than launching a less-confined worker. Full-host dispatch may target other local checkouts and retains normal managed-worktree setup.

Workspace authority does not introduce a second permission model for card lifecycle. Callers that can mutate Workboard cards may manually move them through the same statuses on every surface; read-only workspace access only blocks worker dispatch that requires writes.

Worker selection

Each pass starts at most 3 workers by default. Ready cards are sorted 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 chosen for worker starts (they can still be touched by the data side of dispatch: stale-claim cleanup, dependency promotion, timeout cleanup).

Session keys are deterministic per board/card, so repeated dispatches return to the same worker lane instead of spawning unrelated sessions:

• Assigned cards: agent:<agentId>:subagent:workboard-<boardId>-<cardId>
• Unassigned cards: subagent:workboard-<boardId>-<cardId> (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

openclaw workboard list [--board <id>] [--status <status>] [--include-archived] [--json]
openclaw workboard create "Fix stale card lifecycle" --priority high --labels bug,workboard
openclaw workboard show <card-id> [--json]
openclaw workboard move <card-id> --status <status> [--json]
openclaw workboard dispatch [--board <id>] [--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 and move accept an unambiguous id prefix. list, create, show, and move always read/write local plugin state directly. Only dispatch calls the running Gateway, with the fallback described above.

See Workboard CLI for full flags, JSON output, Gateway fallback behavior, id-prefix handling, dispatch selection rules, and troubleshooting.

/workboard list, /workboard show <card-id>, /workboard create <title>, /workboard move <card-id> --status <status>, and /workboard dispatch mirror the CLI. List and show are read operations for any authorized command sender. Create, move, and dispatch require owner status on chat surfaces, or a Gateway client with operator.write/operator.admin. Manual operator moves use the same claim-override behavior as dashboard drag-and-drop. Their worktree access still follows the same workspace boundary described above.

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:

Manual review states take precedence. Placing a card into review, blocked, or done disables auto-sync for that card until you return it to todo or running.

Normal Gateway sessions handle card startup; Workboard retains only card metadata and links. The regular session system keeps ownership of the conversation transcript, model selection, and run lifecycle. To halt an active run, press Stop on a live linked card, which makes Workboard flag that card blocked so it remains available for later attention.

Workboard templates (bugfix, docs, release, pr_review, plugin) let you launch new cards. These templates populate the title, notes, labels, and priority in advance, and the template id gets stored within the card metadata.

Dashboard workflow

1. Head to the Workboard tab inside the Control UI.
2. Build a card with a title, notes, priority, labels, an optional agent, and an optional linked session, or go to Sessions and pick Add to Workboard for a session that already exists.
3. Move the card across columns by dragging it, or bring up its compact status control and navigate with the menu or ArrowLeft/ArrowRight. While dragging, the originating card fades and possible drop columns show an outline.
4. Kick off work from the card to spin up or reuse a dashboard session.
5. While the agent is working, open the linked session straight from the card.
6. Allow lifecycle sync to shift active work into review/blocked, then relocate the card to done by hand once it is accepted.

Session-board widgets

Session dashboards come with two native widgets included in Workboard (refer to Dashboards). The agent pins them through its dashboard tool with content: { kind: "plugin", pluginKind, props }, and they appear as first-party UI carrying live data, no sandbox frame or capability grant required:

• workboard:card paired with props: { cardId } renders a single card along with its status control, priority, and assigned agent.
• workboard:mini with optional props: { boardId, limit } presents per-status totals plus the top ready/running cards, and connects to the complete board page. Omitting boardId aggregates all boards; including boardId restricts it to that board, and cards created without an explicit board id land on default.

Diagnostics

Local card metadata drives the diagnostics. Built-in checks identify:

Permissions

Gateway RPC methods are grouped under workboard.*:

None of the RPC methods call for operator.admin. A browser with read-only operator access can view the board but is barred from altering cards. An admin scope broadens which Workboard host paths are accepted; the set of methods stays unchanged.

Storage

Durable data for Workboard is kept in a relational SQLite database that the plugin owns, located 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 reside in Workboard tables, not in plugin key-value entries. Exporting a card keeps the board narrative intact without embedding attachment blob contents.

For installations that used Workboard in the .28 release, openclaw doctor --fix migrates the shipped legacy plugin-state namespaces (workboard.cards, workboard.boards, workboard.notify, and, when present, workboard.attachments) into the relational database.

Troubleshooting

The tab says Workboard is unavailable

openclaw plugins inspect workboard --runtime --json

When plugins.allow is set, append workboard to it. If plugins.deny holds workboard, strip that out before turning the plugin on.

Cards do not save

Make sure the browser connection carries operator.write access. Read-only operator sessions can list cards, yet they cannot create, edit, move, or delete them.

Starting a card does not open the expected session

Look at the card's agent id and linked session, then head to Sessions or Chat to see the real run state.

Dispatch does not start a worker

Verify that at least one ready card exists without an active claim:

openclaw workboard list --status ready

If the CLI reports data-only dispatch, start or restart the Gateway and try again. Data-only dispatch refreshes local board state but cannot launch subagent worker runs. Cards may also be skipped when another card for the same owner or agent is already running or awaiting review; complete, block, or release that active work before dispatching more for the same owner.

Related

• Control UI
• Workboard CLI
• Plugins
• Manage plugins
• Sessions