工作板 CLI
openclaw workboard 是随附的 Workboard 插件 的终端界面。它允许操作员列出卡片、创建卡片、检查单张卡片，并请求正在运行的 Gateway 将就绪工作分派到子代理 worker 运行中。
使用该命令前，请先启用插件：
用法¶
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]
该命令读写的是插件自有的 SQLite 数据库，与仪表板和 Workboard agent 工具所使用的数据库相同。卡片 id 是 UUID。接受卡片 id 的命令也接受无歧义的 id 前缀。紧凑文本输出显示前 8 个字符。
有效的 status 取值：triage、backlog、todo、scheduled、ready、running、review、blocked、done。有效的 priority 取值：low、normal、high、urgent。
list¶
openclaw workboard list
openclaw workboard list --board default --status ready
openclaw workboard list --json
文本输出简洁紧凑：
各列依次为：id 前缀、状态、优先级、board id、可选的 agent id，以及标题。
| 标志 | 用途 |
|---|---|
--board <id> |
将结果限制在单个 board 命名空间内 |
--status <status> |
将结果限制为单一 Workboard 状态 |
--include-archived |
在紧凑文本输出中包含已归档卡片 |
--json |
将完整卡片列表以机器可读 JSON 形式输出 |
紧凑文本输出默认隐藏已归档卡片，以便 CLI 与 /workboard list 保持一致。传入 --include-archived 即可显示它们。为了兼容现有自动化，JSON 输出始终保留完整卡片列表（包括已归档卡片）。
create¶
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."
| 标志 | 用途 |
|---|---|
--notes <text> |
卡片的初始备注 |
--status <status> |
初始状态，默认为 todo |
--priority <priority> |
优先级，默认为 normal |
--agent <id> |
将卡片分配给某个 agent 或 owner id |
--board <id> |
将卡片存储在某个 board 命名空间 |
--labels <items> |
逗号分隔的标签 |
--json |
将创建的卡片以机器可读 JSON 形式输出 |
create 直接写入 Workboard 的 SQLite 状态。该卡片会立即出现在 Control UI 的 Workboard 标签页中，Workboard 工具也能看到它。
show¶
文本输出会打印简洁的卡片行和备注。JSON 输出返回完整卡片记录，包括执行元数据、尝试记录、评论、链接、proof（证明）、工件、worker 日志、协议状态、诊断信息和自动化元数据。
JSON 中的 proof 状态是 worker 上报的结果。passed 记录的是 worker 对所附命令或检查的自我评估，并不是独立的验证结果。
move¶
openclaw workboard move 7f4a2c10 --status review
openclaw workboard move 7f4a2c10 --status done --json
move 使用与在仪表板中拖拽卡片相同的操作员手动路径来更改卡片状态。它接受完整卡片 id 或无歧义前缀。当前生效的依赖和日程保持（holds）仍然适用。操作员无需 agent 认领令牌即可移动已认领的卡片。认领令牌仍然限定于 agent 工具的变更操作，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 首先调用正在运行的 Gateway 的 RPC 方法 workboard.cards.dispatch。该方法与仪表板中的 dispatch 操作使用相同的子代理运行时。因此，就绪卡片会变成受任务跟踪的 worker 运行，并具有关联的会话密钥。--max-starts 使用的是附加的 workboard.cards.dispatchWithOptions 方法，因此旧版 Gateway 会在启动任何 worker 之前拒绝该选项。升级后，在使用该标志之前，请先重启 Gateway。已分配 agent 的卡片使用 agent 作用域内的子代理会话密钥。未分配 agent 的卡片保留无作用域的子代理密钥，从而保留 Gateway 配置的默认 agent。
dispatch 循环如下：
- 将依赖已就绪的子卡片提升为
ready。 - 阻止已过期的认领或已超时的 worker 运行。
- 选择一小批未被认领的就绪卡片。
- 为 dispatcher 或已分配的 agent 认领每张被选中的卡片。
- 使用受限的卡片上下文和卡片认领令牌启动子代理 worker 运行。
- 将 worker 运行 id、会话密钥、执行状态和 worker 日志存储到卡片上。
空闲扫描不会改变就绪卡片的历史记录。已有的 dispatch 计数器和时间戳仍作为历史值保留；新的启动会使用该卡片的启动（launch）、尝试和执行历史。
选择策略是保守的。默认情况下，一次 dispatch 最多启动三个 worker。它会跳过已归档或已被认领的卡片。在单轮中，每个 owner 或 agent 只会启动一张卡片。已被活跃的 running 或 review 工作占用的卡片会留待后续 dispatch 处理。传入正整数 --max-starts <count> 可更改每轮上限。每个 owner 一张卡片的规则仍然适用，因此实际启动数量可能会更少。
If worker start fails after a card is claimed, Workboard blocks that card and clears the claim. It records the failure in card execution and worker-log metadata. Failed starts stay visible instead of returning the card to the queue silently.
当卡片被认领后工作器启动失败时，Workboard 会阻塞该卡片并清除认领。它会在卡片执行和 worker-log 元数据中记录失败。失败的启动会保持可见，而不是静默地将卡片返回队列。
The CLI falls back to data-only dispatch against local Workboard state when both of these are true:
当以下两个条件都成立时，CLI 会回退到针对本地 Workboard 状态的仅数据调度：
- You give no explicit Gateway target.
-
The local Gateway is unavailable, or it does not expose the Workboard dispatch method yet.
-
你没有提供显式 Gateway 目标。
- 本地 Gateway 不可用，或它尚未暴露 Workboard 调度方法。
Data-only dispatch can still promote dependencies, clean stale claims, and block timed-out runs, but it does not start workers. Auth, permission, and validation failures, and failures for an explicit --url or --token target, are reported directly instead of triggering the fallback.
仅数据调度仍可以提升依赖项、清理过期认领并阻塞超时运行，但它不会启动工作器。身份验证、权限和验证失败，以及针对显式 --url 或 --token 目标的失败，会直接报告，而不是触发回退。
Text output reports worker starts:
文本输出会报告工作器启动情况：
Fallback output is explicit:
回退输出会明确显示：
JSON output includes the dispatch result. Gateway-backed dispatch can include started and startFailures. Data-only fallback includes gatewayUnavailable: true. Claim tokens are redacted from card JSON output.
JSON 输出包含调度结果。基于 Gateway 的调度可以包含 started 和 startFailures。仅数据回退包含 gatewayUnavailable: true。卡片 JSON 输出中的认领令牌会被脱敏。
In the dashboard, the same dispatch result appears as a short summary. An operator can see how many cards started, promoted, blocked, reclaimed, or failed without opening card details.
在仪表板中，相同的调度结果会显示为简短摘要。操作员无需打开卡片详情，即可看到启动、提升、阻塞、重新认领或失败的卡片数量。
斜杠命令一致性¶
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
Slash command dispatch also uses the Gateway subagent runtime. It follows the same claim, worker-start, and failure behavior as the dashboard and CLI Gateway path.
斜杠命令调度也使用 Gateway 子代理运行时。它与仪表板和 CLI Gateway 路径遵循相同的认领、工作器启动和失败行为。
/workboard list and /workboard show are read commands for authorized command senders. /workboard create, /workboard move, and /workboard dispatch mutate board state and require owner status on chat surfaces or a Gateway client with operator.write or operator.admin.
/workboard list 和 /workboard show 是面向已授权命令发送者的只读命令。/workboard create、/workboard move 和 /workboard dispatch 会修改看板状态，并要求在聊天界面具有所有者身份，或具有 operator.write 或 operator.admin 的 Gateway 客户端。
权限¶
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, so the host does not 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.
CLI 调度路径通常请求 Gateway 的 operator.write 和 operator.read 作用域。工作区绑定卡片直接在精确配置的代理工作区中运行。worktree 请求会被限定到该目录，因此主机不会实例化由仓库控制的代码。所选工作器必须具有对该精确工作区可写且非共享的 Docker 沙箱访问权限、与请求的挂载和策略匹配的实时容器哈希，且没有主机逃逸能力。传入 --admin 可显式请求 operator.admin，允许另一个主机检出，并使用常规受管 worktree 设置。如果该作用域未获客户端批准，连接将失败。只读 Gateway 令牌可以通过只读方法检查 Workboard 数据，但不能创建卡片或调度工作器。工作区限制不会改变具有 Workboard 变更权限的调用者手动移动卡片的行为。
Local list, create, show, and move commands operate on the local OpenClaw state directory used by the current profile. Use --dev or --profile <name> on the top-level openclaw command when you need a different state root.
本地 list、create、show 和 move 命令操作当前配置资料使用的本地 OpenClaw 状态目录。当需要不同的状态根目录时，在顶层 openclaw 命令上使用 --dev 或 --profile <name>。
故障排查¶
没有卡片显示¶
Check that the plugin is enabled for the same profile and state root:
检查插件是否针对相同配置资料和状态根目录启用：
If the dashboard shows cards but the CLI does not, check that both commands use the same --dev or --profile setting.
如果仪表板显示卡片但 CLI 不显示，请检查两个命令是否使用相同的 --dev 或 --profile 设置。
调度显示仅数据¶
Start or restart the Gateway:
启动或重启 Gateway：
Then retry openclaw workboard dispatch. Data-only fallback is useful for local state cleanup, but worker runs need a live Gateway.
然后重试 openclaw workboard dispatch。仅数据回退适用于本地状态清理，但工作器运行需要可用的 Gateway。
调度未启动任何内容¶
Check for at least one ready card without an active claim:
检查是否至少有一张没有活动认领的 ready 卡片：
Cards can also be skipped when the same owner already has running or review work. Move completed work to done, release stale claims through the Workboard tools, or run dispatch again after the active worker finishes.
当同一所有者已有运行中或审查中的工作时，卡片也可能被跳过。将已完成的工作移动到 done，通过 Workboard 工具释放过期认领，或在活动工作器完成后再次运行调度。
相关¶
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw