Workboard plugin

Workboard plugin 문서는 OpenClaw 공식 문서(plugins/workboard)를 한국어로 정리한 가이드입니다. Optional dashboard workboard for agent-owned cards and session handoff 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Optional dashboard workboard for agent-owned cards and session handoff

한국어 가이드 범위: plugins/workboard 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Enable it
구성
Card fields
Starting work from a card
Agent tools
Dispatch
Worker selection
Entry points
CLI and slash command
Session lifecycle sync
Dashboard workflow
Session-board widgets
Diagnostics
Permissions
Storage
트러블슈팅
관련 문서

상세 내용

본문

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

Enable it

Workboard is bundled but disabled by default:

openclaw plugins enable workboard
openclaw gateway restart
openclaw dashboard

구성

Workboard has no plugin-specific config. Enable/disable it with the standard plugin entry:

{
  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.

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)

Starting work from a card

explicit engine, sends the card prompt, and marks the card running. Codex runs use openai/gpt-5.6-sol; Claude runs use anthropic/claude-sonnet-4-6.

주요 항목:

Run Codex / Run Claude starts a task-tracked agent run with an
Open Codex / Open Claude creates a linked dashboard session without

Agent tools

Proof statuses are worker-reported outcomes, not independent verification. A passed entry means the worker reports that its command or check succeeded; consumers that need an independent quality gate should inspect 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 is resolved in place without losing its identity or timestamp. A proof that already has the same terminal status is reused unchanged. Completion proof without proofId remains append-only, so a later retry cannot rewrite older history merely because its command or note is identical.

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_move`	Move a card to another status; claimed cards require the caller's agent claim scope.
`workboard_dispatch`	Nudge dependency promotion or stale-claim cleanup without launching workers; worker launch uses Gateway or slash-command dispatch.

Dispatch

Dispatch is Gateway-local: it does not spawn arbitrary OS processes. Normal OpenClaw subagent sessions still own execution. One dispatch pass:

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).

주요 항목:

Assigned cards: agent:<agentId>:subagent:workboard-<boardId>-<cardId>
Unassigned cards: subagent:workboard-<boardId>-<cardId> (Gateway resolves

Entry points

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.

주요 항목:

Dashboard dispatch action
openclaw workboard dispatch
/workboard dispatch on a command-capable channel

CLI and slash command

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.

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]

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.

Linked session state	Card status
active	`running`
completed	`review`
failed, killed, timed out, or aborted	`blocked`

Dashboard workflow

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. During a drag, the source card dims and available drop columns gain an outline. 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.

Session-board widgets

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

주요 항목:

workboard:card with props: { cardId } shows one card with its status
workboard:mini with optional props: { boardId, limit } shows per-status

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

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.

트러블슈팅

If plugins.allow is configured, add workboard to it. If plugins.deny contains workboard, remove it before enabling the plugin.

openclaw plugins inspect workboard --runtime --json

openclaw workboard list --status ready

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/plugins/workboard
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw plugins enable workboard
openclaw gateway restart
openclaw dashboard

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

openclaw plugins disable workboard
openclaw gateway restart

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]

openclaw plugins inspect workboard --runtime --json

openclaw workboard list --status ready

Workboard plugin

핵심 요약

Optional dashboard workboard for agent-owned cards and session handoff

한국어 가이드 범위: plugins/workboard 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Enable it
구성
Card fields
Starting work from a card
Agent tools
Dispatch
Worker selection
Entry points
CLI and slash command
Session lifecycle sync
Dashboard workflow
Session-board widgets
Diagnostics
Permissions
Storage
트러블슈팅
관련 문서

상세 내용

본문

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

Enable it

Workboard is bundled but disabled by default:

openclaw plugins enable workboard
openclaw gateway restart
openclaw dashboard

구성

Workboard has no plugin-specific config. Enable/disable it with the standard plugin entry:

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

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)

Starting work from a card

explicit engine, sends the card prompt, and marks the card running. Codex runs use openai/gpt-5.6-sol; Claude runs use anthropic/claude-sonnet-4-6.

주요 항목:

Run Codex / Run Claude starts a task-tracked agent run with an
Open Codex / Open Claude creates a linked dashboard session without

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_move`	Move a card to another status; claimed cards require the caller's agent claim scope.
`workboard_dispatch`	Nudge dependency promotion or stale-claim cleanup without launching workers; worker launch uses Gateway or slash-command dispatch.

Dispatch

Dispatch is Gateway-local: it does not spawn arbitrary OS processes. Normal OpenClaw subagent sessions still own execution. One dispatch pass:

Worker selection

주요 항목:

Assigned cards: agent:<agentId>:subagent:workboard-<boardId>-<cardId>
Unassigned cards: subagent:workboard-<boardId>-<cardId> (Gateway resolves

Entry points

주요 항목:

Dashboard dispatch action
openclaw workboard dispatch
/workboard dispatch on a command-capable channel

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]

Session lifecycle sync

Linked session state	Card status
active	`running`
completed	`review`
failed, killed, timed out, or aborted	`blocked`

Dashboard workflow

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. During a drag, the source card dims and available drop columns gain an outline. 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.

Session-board widgets

주요 항목:

workboard:card with props: { cardId } shows one card with its status
workboard:mini with optional props: { boardId, limit } shows per-status

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

Storage

트러블슈팅

If plugins.allow is configured, add workboard to it. If plugins.deny contains workboard, remove it before enabling the plugin.

openclaw plugins inspect workboard --runtime --json

openclaw workboard list --status ready

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/plugins/workboard
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw plugins enable workboard
openclaw gateway restart
openclaw dashboard

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

openclaw plugins disable workboard
openclaw gateway restart

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]

openclaw plugins inspect workboard --runtime --json

openclaw workboard list --status ready

Workboard plugin

핵심 요약

문서 구성

상세 내용

본문

Enable it

구성

Card fields

Starting work from a card

Agent tools

Dispatch

Worker selection

Entry points

CLI and slash command

Session lifecycle sync

Dashboard workflow

Session-board widgets

Diagnostics

Permissions

Storage

트러블슈팅

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Workboard plugin

핵심 요약

문서 구성

상세 내용

본문

Enable it

구성

Card fields

Starting work from a card

Agent tools

Dispatch

Worker selection

Entry points

CLI and slash command

Session lifecycle sync

Dashboard workflow

Session-board widgets

Diagnostics

Permissions

Storage

트러블슈팅

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드