工作板 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]
该命令使用与仪表板和 Workboard agent 工具相同的插件拥有的 SQLite 数据库。当本地 Gateway 拥有状态目录时,命令会先通过该 Gateway 路由,然后再打开存储。当 Gateway 已停止时,命令会获取独占的离线所有权,并在释放之前关闭存储。不可用、版本过旧或拒绝请求的实时 Gateway 绝不会触发本地写入回退;请修复其连接,或通过其服务所有者停止它,然后重试。卡片 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 和标题。
无效的 --status 会退出并输出错误,列出允许的值,而不是返回空列表。
| 标志 | 用途 |
|---|---|
--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 通过所选状态所有者写入。卡片会立即显示在 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 或无歧义前缀。活动的依赖项和计划保留仍然适用。操作员可以在没有其 agent claim token 的情况下移动已认领卡片。claim token 仍仅限于 agent 工具变更,并且 JSON 输出会将其脱敏。
该命令通过所选状态所有者写入,在 Gateway 运行时使用 Gateway RPC,在 Gateway 停止时使用独占离线所有权。
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 在打开本地 Workboard 状态之前选择活动 Gateway。隐式本地请求使用所有者绑定的 workboard.cards.dispatch.owner RPC。该方法使用与仪表板 dispatch 操作相同的子代理运行时。因此,就绪卡片会成为带有链接 session key 的任务跟踪 worker 运行。--max-starts 对隐式本地 Gateway 使用 workboard.cards.dispatchWithOptions.owner。没有所有者路由的旧版 Gateway 或 Workboard 插件会在启动 worker 之前拒绝;显式远程目标保留现有的 workboard.cards.dispatch 和 workboard.cards.dispatchWithOptions 契约。升级后,在使用该标志之前,请重启 Gateway。已分配 agent 的卡片使用 agent 作用域的 subagent session key。未分配卡片保留无作用域的 subagent key,因此 Gateway 配置的默认 agent 得以保留。
调度循环:
- 将依赖已就绪的子卡片提升为
ready。 - 阻止过期认领或超时的 worker 运行。
- 选择一小批未认领的就绪卡片。
- 为调度器或指定代理认领每个选中的卡片。
- 使用有界的卡片上下文和卡片认领令牌启动子代理 worker 运行。
- 在卡片上存储 worker 运行 id、会话密钥、执行状态和 worker 日志。
空闲扫描不会改变就绪卡片的历史记录。现有调度计数器和时间戳保留为历史值;新启动使用卡片的启动、尝试和执行历史。
选择是保守的。默认情况下,一次调度最多启动三个 worker。它会跳过已归档或已认领的卡片。单次遍历中,每个所有者或代理只启动一个卡片。已被活跃运行或 review 工作拥有的卡片留待后续调度。传入 --max-starts <count> 并指定正整数以更改每次遍历的上限。每个所有者一个卡片的规则仍然适用,因此实际启动数量可能更低。
如果在卡片被认领后 worker 启动失败,Workboard 会阻止该卡片并清除认领。它会在卡片执行和 worker 日志元数据中记录失败。失败的启动会保持可见,而不是将卡片静默返回队列。
当以下两个条件都为真时,CLI 会回退到针对本地 Workboard 状态的数据专用调度:
- 你没有指定显式 Gateway 目标。
- 本地 Gateway 已停止,并且 CLI 可以获取独占的离线状态所有权。
数据专用调度仍然可以提升依赖、清理过期认领并阻止超时运行,但它不会启动 worker。无法到达的活跃所有者、缺少所需方法或拒绝请求的情况,永远不会触发本地回退。认证、权限、验证和显式目标失败会直接报告。在收到不确定的响应后,重试前请先检查看板。
数据专用调度要求 Gateway 已停止。仅凭连接错误或缺失的 RPC 方法并不能证明它已停止。正在运行的 Gateway 不会轮询由另一个进程所做的变更。
文本输出会报告 worker 启动情况:
当 worker 无法启动时,文本输出还会打印其卡片 id 前缀和失败原因。JSON 输出会在 startFailures 中包含相同的原因。
对于已获准访问完整主机工作区的卡片,如果由于当前调用者仅限于已配置工作区而被拒绝,则会包含 --admin 提示。这会请求 operator.admin;Gateway 必须批准该权限范围。该提示不适用于具有受限、只读或未知持久化工作区权限的卡片,并且 --admin 不会覆盖这些限制。
回退输出是明确的:
JSON 输出包含调度结果。Gateway 支持的调度可以包含 started 和 startFailures。数据专用回退包含 gatewayUnavailable: true 以及空的 started 和 startFailures 数组。认领令牌会从卡片 JSON 输出中隐藏。
在仪表板中,相同的调度结果会以简短摘要显示。操作员无需打开卡片详情,即可看到有多少卡片已启动、提升、阻止、重新认领或失败。
斜杠命令一致性¶
支持命令的频道可以使用对应的斜杠命令:
/workboard list
/workboard show 7f4a2c10
/workboard create Fix stale worker heartbeat
/workboard move 7f4a2c10 --status review
/workboard dispatch
斜杠命令调度也使用 Gateway 子代理运行时。它遵循与仪表板和 CLI Gateway 路径相同的认领、worker 启动和失败行为。
/workboard list 和 /workboard show 是面向已授权命令发送者的只读命令。/workboard create、/workboard move 和 /workboard dispatch 会修改看板状态,并要求在聊天界面具有所有者状态,或具有 operator.write 或 operator.admin 的 Gateway 客户端。
权限¶
CLI 调度路径通常请求 Gateway 的 operator.write 和 operator.read 权限范围。与工作区绑定的卡片直接在精确配置的代理工作区中运行。worktree 请求会缩小到该目录,因此主机不会实例化由仓库控制的代码。所选 worker 必须具有对该精确工作区的可写、非共享 Docker 沙箱访问权限、与请求的挂载和策略匹配的实时容器哈希,以及没有主机逃逸能力。传入 --admin 以显式请求 operator.admin、允许另一个主机检出,并使用常规 managed-worktree 设置。如果该权限范围未获客户端批准,连接将失败。只读 Gateway token 可以通过只读方法检查 Workboard 数据,但不能创建卡片或调度 worker。工作区限制不会以其他方式改变具有 Workboard 修改权限的调用者的手动卡片移动。
本地 list、create、show 和 move 命令操作当前 profile 使用的本地 OpenClaw 状态目录。当需要不同的状态根时,在顶层 openclaw 命令上使用 --dev 或 --profile <name>。
故障排除¶
没有卡片出现¶
检查插件是否针对相同的 profile 和状态根启用:
如果仪表板显示卡片但 CLI 不显示,请检查两个命令是否使用相同的 --dev 或 --profile 设置。
调度显示数据专用¶
启动或重启 Gateway:
然后重试 openclaw workboard dispatch。数据专用回退适用于本地状态清理,但 worker 运行需要活跃的 Gateway。
调度未启动任何内容¶
检查是否至少有一个没有活跃认领的 ready 卡片:
当同一所有者已有运行中或 review 工作时,卡片也可能被跳过。将已完成的工作移动到 done,通过 Workboard 工具释放过期认领,或在活跃 worker 完成后再次运行调度。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw