Workboard CLI

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

핵심 요약

CLI reference for openclaw workboard cards, dispatch, and worker runs

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

문서 구성

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

사용법
list
create
show
move
dispatch
Slash command parity
Permissions
트러블슈팅
No cards appear
Dispatch says data-only
Dispatch starts nothing
관련 문서

상세 내용

본문

openclaw workboard is the terminal surface for the bundled Workboard plugin. It lets an operator list cards, create a card, inspect one card, and ask the running Gateway to dispatch ready work into subagent worker runs.

openclaw plugins enable workboard
openclaw gateway restart

사용법

The command reads and writes the same plugin-owned SQLite database used by the dashboard and Workboard agent tools. Card ids are UUIDs; commands that accept a card id also accept an unambiguous id prefix (the compact text output shows the first 8 characters).

openclaw workboard list [--board <id>] [--status <status>] [--include-archived] [--json]
openclaw workboard create <title...> [--notes <text>] [--status <status>] [--priority <priority>] [--agent <id>] [--board <id>] [--labels <items>] [--json]
openclaw workboard show <id> [--json]
openclaw workboard move <id> --status <status> [--json]
openclaw workboard dispatch [--board <id>] [--max-starts <count>] [--admin] [--url <url>] [--token <token>] [--timeout <ms>] [--json]

list

Columns are id prefix, status, priority, board id, optional agent id, and title.

Flag	Purpose
`--board <id>`	Limit results to one board namespace
`--status <status>`	Limit results to one Workboard status
`--include-archived`	Include archived cards in compact text output
`--json`	Print the full card list as machine JSON

openclaw workboard list
openclaw workboard list --board default --status ready
openclaw workboard list --json

7f4a2c10  ready     high    default agent-a  Fix stale worker heartbeat

create

create writes directly to Workboard SQLite state. The card is immediately visible in the Control UI Workboard tab and to Workboard tools.

Flag	Purpose
`--notes <text>`	Initial card notes
`--status <status>`	Initial status, default `todo`
`--priority <priority>`	Priority, default `normal`
`--agent <id>`	Assign the card to an agent or owner id
`--board <id>`	Store the card on a board namespace
`--labels <items>`	Comma-separated labels
`--json`	Print the created card as machine JSON

openclaw workboard create "Fix stale worker heartbeat" --priority high --labels bug,workboard
openclaw workboard create "Write Workboard docs" --status ready --agent docs-agent --board docs --notes "Cover CLI, slash command, dispatch, and SQLite state."

show

Text output prints the compact card line and notes. JSON output returns the full card record, including execution metadata, attempts, comments, links, proof, artifacts, worker logs, protocol state, diagnostics, and automation metadata.

openclaw workboard show 7f4a2c10
openclaw workboard show 7f4a2c10 --json

move

move changes the card's status using the same manual-operator path as dragging a card in the dashboard. It accepts a full card id or an unambiguous prefix. Active dependency and schedule holds still apply. Operators may move a claimed card without its agent claim token; claim tokens remain scoped to agent-tool mutations and are redacted from JSON output.

openclaw workboard move 7f4a2c10 --status review
openclaw workboard move 7f4a2c10 --status done --json

dispatch

dispatch first calls the running Gateway RPC method workboard.cards.dispatch, which uses the same subagent runtime as the dashboard dispatch action, so ready cards become task-tracked worker runs with linked session keys. --max-starts uses the additive workboard.cards.dispatchWithOptions method so an older Gateway rejects the option before starting any workers; restart the Gateway after upgrading before using the flag. Cards with an assigned agent use agent-scoped subagent session keys; unassigned cards keep an unscoped subagent key so the Gateway's configured default agent is preserved.

openclaw workboard dispatch
openclaw workboard dispatch --json
openclaw workboard dispatch --max-starts 10
openclaw workboard dispatch --admin
openclaw workboard dispatch --url http://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"

dispatch complete: started=2 failures=0

gateway unavailable; data dispatch only: promoted=1 blocked=0

Slash command parity

Command-capable channels can use the matching slash command:

/workboard list
/workboard show 7f4a2c10
/workboard create Fix stale worker heartbeat
/workboard move 7f4a2c10 --status review
/workboard dispatch

Permissions

The CLI dispatch path normally requests Gateway operator.write and operator.read scopes. Workspace-bound cards run directly in an exact configured agent workspace; a worktree request is narrowed to that directory instead of letting the host materialize repository-controlled code. The selected worker must have writable, non-shared Docker sandbox access to that exact workspace, a live container hash matching the requested mounts and policy, and no host escape capability. Pass --admin to explicitly request operator.admin, allow another host checkout, and use normal managed-worktree setup; the connection fails if that scope is not approved for the client. A read-only Gateway token can inspect Workboard data through read methods, but it cannot create cards or dispatch workers. Workspace limits do not otherwise change manual card movement for callers with Workboard mutation permission.

트러블슈팅

이 섹션의 세부 항목은 공식 문서 트러블슈팅를 참고하세요.

No cards appear

Confirm the plugin is enabled for the same profile and state root:

openclaw plugins inspect workboard --runtime --json

Dispatch says data-only

Then retry openclaw workboard dispatch. Data-only fallback is useful for local state cleanup, but worker runs need a live Gateway.

openclaw gateway restart
openclaw gateway status --deep

Dispatch starts nothing

Check for at least one ready card without an active claim:

openclaw workboard list --status ready

실습 체크리스트

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

자주 쓰는 명령·설정 예시

openclaw plugins enable workboard
openclaw gateway restart

openclaw workboard list [--board <id>] [--status <status>] [--include-archived] [--json]
openclaw workboard create <title...> [--notes <text>] [--status <status>] [--priority <priority>] [--agent <id>] [--board <id>] [--labels <items>] [--json]
openclaw workboard show <id> [--json]
openclaw workboard move <id> --status <status> [--json]
openclaw workboard dispatch [--board <id>] [--max-starts <count>] [--admin] [--url <url>] [--token <token>] [--timeout <ms>] [--json]

openclaw workboard list
openclaw workboard list --board default --status ready
openclaw workboard list --json

7f4a2c10  ready     high    default agent-a  Fix stale worker heartbeat

openclaw workboard create "Fix stale worker heartbeat" --priority high --labels bug,workboard
openclaw workboard create "Write Workboard docs" --status ready --agent docs-agent --board docs --notes "Cover CLI, slash command, dispatch, and SQLite state."

openclaw workboard show 7f4a2c10
openclaw workboard show 7f4a2c10 --json

Workboard CLI

핵심 요약

CLI reference for openclaw workboard cards, dispatch, and worker runs

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

문서 구성

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

사용법
list
create
show
move
dispatch
Slash command parity
Permissions
트러블슈팅
No cards appear
Dispatch says data-only
Dispatch starts nothing
관련 문서

상세 내용

본문

openclaw plugins enable workboard
openclaw gateway restart

사용법

openclaw workboard list [--board <id>] [--status <status>] [--include-archived] [--json]
openclaw workboard create <title...> [--notes <text>] [--status <status>] [--priority <priority>] [--agent <id>] [--board <id>] [--labels <items>] [--json]
openclaw workboard show <id> [--json]
openclaw workboard move <id> --status <status> [--json]
openclaw workboard dispatch [--board <id>] [--max-starts <count>] [--admin] [--url <url>] [--token <token>] [--timeout <ms>] [--json]

list

Columns are id prefix, status, priority, board id, optional agent id, and title.

Flag	Purpose
`--board <id>`	Limit results to one board namespace
`--status <status>`	Limit results to one Workboard status
`--include-archived`	Include archived cards in compact text output
`--json`	Print the full card list as machine JSON

openclaw workboard list
openclaw workboard list --board default --status ready
openclaw workboard list --json

7f4a2c10  ready     high    default agent-a  Fix stale worker heartbeat

create

create writes directly to Workboard SQLite state. The card is immediately visible in the Control UI Workboard tab and to Workboard tools.

Flag	Purpose
`--notes <text>`	Initial card notes
`--status <status>`	Initial status, default `todo`
`--priority <priority>`	Priority, default `normal`
`--agent <id>`	Assign the card to an agent or owner id
`--board <id>`	Store the card on a board namespace
`--labels <items>`	Comma-separated labels
`--json`	Print the created card as machine JSON

openclaw workboard create "Fix stale worker heartbeat" --priority high --labels bug,workboard
openclaw workboard create "Write Workboard docs" --status ready --agent docs-agent --board docs --notes "Cover CLI, slash command, dispatch, and SQLite state."

show

openclaw workboard show 7f4a2c10
openclaw workboard show 7f4a2c10 --json

move

openclaw workboard move 7f4a2c10 --status review
openclaw workboard move 7f4a2c10 --status done --json

dispatch

openclaw workboard dispatch
openclaw workboard dispatch --json
openclaw workboard dispatch --max-starts 10
openclaw workboard dispatch --admin
openclaw workboard dispatch --url http://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"

dispatch complete: started=2 failures=0

gateway unavailable; data dispatch only: promoted=1 blocked=0

Slash command parity

Command-capable channels can use the matching slash command:

/workboard list
/workboard show 7f4a2c10
/workboard create Fix stale worker heartbeat
/workboard move 7f4a2c10 --status review
/workboard dispatch

Permissions

트러블슈팅

이 섹션의 세부 항목은 공식 문서 트러블슈팅를 참고하세요.

No cards appear

Confirm the plugin is enabled for the same profile and state root:

openclaw plugins inspect workboard --runtime --json

Dispatch says data-only

Then retry openclaw workboard dispatch. Data-only fallback is useful for local state cleanup, but worker runs need a live Gateway.

openclaw gateway restart
openclaw gateway status --deep

Dispatch starts nothing

Check for at least one ready card without an active claim:

openclaw workboard list --status ready

실습 체크리스트

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

자주 쓰는 명령·설정 예시

openclaw plugins enable workboard
openclaw gateway restart

openclaw workboard list [--board <id>] [--status <status>] [--include-archived] [--json]
openclaw workboard create <title...> [--notes <text>] [--status <status>] [--priority <priority>] [--agent <id>] [--board <id>] [--labels <items>] [--json]
openclaw workboard show <id> [--json]
openclaw workboard move <id> --status <status> [--json]
openclaw workboard dispatch [--board <id>] [--max-starts <count>] [--admin] [--url <url>] [--token <token>] [--timeout <ms>] [--json]

openclaw workboard list
openclaw workboard list --board default --status ready
openclaw workboard list --json

7f4a2c10  ready     high    default agent-a  Fix stale worker heartbeat

openclaw workboard create "Fix stale worker heartbeat" --priority high --labels bug,workboard
openclaw workboard create "Write Workboard docs" --status ready --agent docs-agent --board docs --notes "Cover CLI, slash command, dispatch, and SQLite state."

openclaw workboard show 7f4a2c10
openclaw workboard show 7f4a2c10 --json

Workboard CLI

핵심 요약

문서 구성

상세 내용

본문

사용법

list

create

show

move

dispatch

Slash command parity

Permissions

트러블슈팅

No cards appear

Dispatch says data-only

Dispatch starts nothing

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Workboard CLI

핵심 요약

문서 구성

상세 내용

본문

사용법

list

create

show

move

dispatch

Slash command parity

Permissions

트러블슈팅

No cards appear

Dispatch says data-only

Dispatch starts nothing

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드