Workboard Plugin: Kanban Board for Agent Cards and Session Handoff

The Workboard plugin introduces an optional Kanban-style board to the Control UI, featuring agent-sized work cards, agent assignment capabilities, and a return link to the card's associated task, run, and dashboard session.

Workboard keeps its scope deliberately narrow: it monitors local operational work for a single OpenClaw Gateway. It does not substitute for GitHub Issues, Linear, Jira, or other team project management systems.

Enable it

Workboard ships with the product but starts disabled:

1. Navigate to Plugins in the Control UI, or access /settings/plugins relative to your configured Control UI base path. With a base path of /openclaw, the address becomes /openclaw/settings/plugins.
2. Locate Workboard and click Enable. Since Workboard ships with OpenClaw, no Install action is required.
3. If the interface indicates a restart is necessary, restart the Gateway.

After the plugin runtime loads, the Workboard tab becomes visible in the dashboard navigation. While disabled, the tab remains absent from the navigation. Opening the /workboard route directly when the plugin is disabled or restricted by plugins.allow/plugins.deny displays a plugin-unavailable message instead of card data.

The equivalent CLI procedure is:

openclaw plugins enable workboard
openclaw gateway restart
openclaw dashboard

Configuration

Workboard requires no plugin-specific configuration. Use the standard plugin entry to enable or disable it:

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

openclaw plugins disable workboard
openclaw gateway restart

Card fields

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.

A single Workboard card contract is shared between the plugin and Control UI. 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 receives updates through plugin.workboard.changed invalidations. Each event contains only a store epoch and revision; the UI then rereads canonical cards via the standard operator.read RPC. Multiple revisions merge into a single follow-up read. Workboard postpones that read while a card is being dragged, edited, or written, then resumes after the local interaction completes. A reconnect always triggers a full canonical reload. No routine full-card polling occurs, and Refresh remains available as a manual recovery option.

When multiple boards exist, a Board filter appears in the toolbar. This filter relies on stored board metadata, not just the currently displayed cards. Consequently, empty and archived boards stay available for selection. Cards that lack an explicit board identifier belong to the default default board. Every board has a dedicated /workboard/<boardId> page that can be bookmarked, shared, or added to the sidebar. The older /workboard?board=<boardId> form is still functional as a compatibility alias and redirects to that page while keeping other query parameters intact. Selecting All boards returns the view to /workboard.

Card data lives in the plugin's own Gateway state and travels along with the rest of that Gateway's OpenClaw state (refer to Storage).

Starting work from a card

Unlinked cards can begin work immediately:

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

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

The dashboard refreshes task status by consulting the Gateway task ledger, matching tasks to cards using 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 moves the card toward review or blocked using the same sync rule applied to linked sessions (see Session lifecycle sync).

Agent tools

Proof statuses reflect what workers report, not verified outcomes. A passed entry indicates the worker reported its command or check succeeded; consumers needing an independent quality gate should examine the attached command, URL, or artifact and run their own verifier. workboard_proof returns the new record's proofId. When workboard_complete reports that same proof's terminal status, pass proofId so the pending record resolves in place without losing its identity or timestamp. A proof already holding the same terminal status is reused unchanged. Completion proof without proofId stays append-only, so a later retry cannot overwrite older history just because its command or note is identical.

Claimed cards block agent-tool mutations from other agents unless the caller possesses 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 appears 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 operates within the Gateway only; it does not launch arbitrary OS processes. Normal OpenClaw subagent sessions still own execution. One dispatch pass:

1. Promotes cards whose dependencies are ready.
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 receive bounded card context plus the claim token needed to heartbeat, complete, or block the card through the Workboard tools.

Workspace paths follow 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 use their sandbox workspace access, while unsandboxed workspace-only tools use their configured workspace root. Workboard records that authority when a workspace is assigned and intersects it with the current caller's authority again at dispatch, so a persisted card cannot widen 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 adopt the current caller's authority when first dispatched.

Workspace-bound dispatch accepts a directory or Git checkout only when its repository root exactly matches the target agent workspace. A worktree request is narrowed to that directory and persisted as a directory workspace, so the host does not materialize the checkout or execute 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 trusting a workboard_* prefix, and dispatch refuses a hot Docker container whose live mount/config hash is stale. Dispatch reports the incompatible target policy instead of starting a less-confined worker. Full-host dispatch may target other local checkouts and keeps normal managed-worktree setup.

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

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:<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 win. When a card is placed into review, blocked, or done, its auto-sync pauses until you return it to todo or running.

Launching a card uses standard Gateway sessions. The Workboard plugin only keeps card metadata and its links. The regular session system retains ownership of the conversation transcript, model selection, and run lifecycle. To abort an active run on a linked card, press Stop. Workboard then marks that card as blocked so it remains visible for later review.

Cards can be created from Workboard templates (bugfix, docs, release, pr_review, plugin). These templates prepopulate the title, notes, labels, and priority. The template identifier is stored as card metadata.

Dashboard workflow

1. Navigate to the Workboard tab inside the Control UI.
2. Build a card by providing a title, notes, priority, labels, and optionally an agent and linked session. Alternatively, open Sessions and select Add to Workboard for a session that already exists.
3. Drag the card between columns, or focus its compact status control and use either the menu or ArrowLeft/ArrowRight. While dragging, the source card dims and every valid drop column gets an outline.
4. Start work from the card to either create a new dashboard session or reuse an existing one.
5. While the agent runs, open the linked session from the card.
6. Let lifecycle sync move the running work into review/blocked, then manually transfer the card to done once it is accepted.

Session-board widgets

Two native widgets for session dashboards ship with Workboard (see Dashboards). The agent pins them using its dashboard tool via content: { kind: "plugin", pluginKind, props }. They render as first-party UI with live data, no sandbox frame or capability grant required:

• workboard:card combined with props: { cardId } displays a single card along with its status control, priority, and assigned agent.
• workboard:mini with optional props: { boardId, limit } shows per-status counts, the top ready and running cards, and a link to the full board page. Without boardId it aggregates every board; with boardId it restricts the view to that specific board. Cards created without an explicit board id live on default.

Diagnostics

Diagnostics derive from local card metadata. Built-in checks flag the following:

Permissions

Gateway RPC methods are organized under workboard.*:

No RPC method requires operator.admin. Browsers that connect with read-only operator access can view the board but cannot modify cards. An admin scope expands the set of accepted Workboard host paths, yet the available methods stay the same.

Storage

Workboard stores persistent data in its own relational SQLite database within 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 rather than plugin key-value entries. A card export captures the board narrative but does not embed attachment blob contents.

Installations that used Workboard in the .28 release can run openclaw doctor --fix to migrate the previously 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

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

Verify that 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

Review the card's agent id and linked session, then open Sessions or Chat to examine the actual run state.

Dispatch does not start a worker

Ensure 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 updates 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