启用它
Workboard 已内置，但默认禁用：plugins.allow/plugins.deny 阻止时，直接打开 /workboard 路由会显示插件不可用状态，而不是卡片数据。
配置
Workboard 没有插件专属配置。使用标准插件条目启用/禁用它：卡片字段
| 字段 | 取值 |
|---|---|
status | triage, backlog, todo, scheduled, ready, running, review, blocked, done |
priority | low, normal, high, urgent |
labels | 自由格式字符串 |
agentId | 可选的已分配智能体 |
| 关联引用 | 可选的任务、运行、会话或源 URL |
execution | 从卡片启动的 Codex/Claude 运行的可选元数据（引擎、模式、模型、会话、运行 id、状态） |
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）。这些元数据让操作员无需打开关联会话，就能看到卡片如何在看板中流转；它是本地操作上下文，不是会话转录或 GitHub issue 历史的替代品。
卡片存储在该插件自己的 Gateway 网关状态中，并会随该 Gateway 网关的其他 OpenClaw 状态一起移动（参见 存储）。
从卡片开始工作
未关联的卡片可以直接开始工作：- 运行 Codex / 运行 Claude 会以显式引擎启动一个跟踪任务的智能体运行，发送卡片提示，并将卡片标记为
running。Codex 运行使用openai/gpt-5.5；Claude 运行使用anthropic/claude-sonnet-4-6。 - 打开 Codex / 打开 Claude 会创建一个已关联的仪表盘会话，但不发送卡片提示，也不移动卡片，用于保持挂接到看板的手动工作。
review 或 blocked（参见 会话生命周期同步）。
智能体工具
| 工具 | 用途 |
|---|---|
workboard_list | 列出带有声明/诊断状态的紧凑卡片；可选看板过滤器。 |
workboard_read | 返回一张卡片以及有界 worker 上下文（备注、尝试、评论、链接、证明、工件、父级结果、最近的负责人工作、活动诊断）。 |
workboard_create | 创建一张卡片，可附带可选父级、租户、Skills、看板、工作区元数据、幂等键、运行时限制、重试预算。 |
workboard_link | 将父卡片链接到子卡片。子卡片会保持 todo，直到每个父卡片都达到 done，然后调度提升会将它们移动到 ready。 |
workboard_claim | 为调用智能体声明一张卡片；将 backlog/todo/ready 移动到 running。 |
workboard_heartbeat | 在较长运行期间刷新声明心跳。 |
workboard_release | 在完成、暂停或移交后释放声明；可以将卡片移动到下一个状态。 |
workboard_complete / workboard_block | 用于最终摘要、证明、工件和已创建卡片清单（必须引用链接回已完成卡片的卡片）或阻塞原因的结构化生命周期工具。 |
workboard_attachment_add / workboard_attachment_read / workboard_attachment_delete | 将小型卡片附件存储在插件 SQLite 状态中，在卡片上建立索引，并暴露到 worker 上下文中。 |
workboard_worker_log / workboard_protocol_violation | 记录 worker 日志行，并在自动化 worker 未调用 workboard_complete/workboard_block 就停止时阻塞卡片。 |
workboard_board_create / workboard_board_archive / workboard_board_delete | 管理持久化看板元数据（显示名称、描述、归档状态、默认工作区）。 |
workboard_runs | 返回一张卡片的持久化运行尝试历史。 |
workboard_specify | 将粗略的分诊/待办卡片转为澄清后的 todo 卡片；在卡片上记录规格摘要。 |
workboard_decompose | 将父级编排卡片展开为已关联的子卡片，并继承看板/租户元数据；可以用已创建卡片清单完成父卡片。 |
workboard_notify_subscribe / workboard_notify_list / workboard_notify_events / workboard_notify_advance / workboard_notify_unsubscribe | 管理通知订阅。事件读取可安全重放；advance 会移动持久游标，使调用方恢复时不会丢失或重复读取已完成/失败/陈旧卡片事件。 |
workboard_boards / workboard_stats | 检查看板命名空间和队列统计信息。 |
workboard_promote / workboard_reassign / workboard_reclaim | 恢复或移交卡住的工作。 |
workboard_comment / workboard_proof | 添加移交备注或附加证明/工件引用。 |
workboard_unblock | 将被阻塞的工作移回 todo。 |
workboard_dispatch | 触发依赖提升或陈旧声明清理。 |
workboard_claim 返回的认领令牌。智能体工具或 Gateway 网关 RPC 调用返回的每张卡片都会将 metadata.claim.token 脱敏为 [redacted]（令牌本身只会由 workboard_claim 以顶层字段返回一次），因此仪表板操作员和其他智能体可以检查认领状态，而永远不会看到可用令牌。恢复通过 workboard_promote/workboard_reassign/workboard_reclaim 进行，这些操作不需要令牌。
调度
调度是 Gateway 网关本地的：它不会生成任意 OS 进程。正常的 OpenClaw 子智能体会话仍然拥有执行权。一次调度流程会：- 提升依赖已就绪的卡片。
- 在就绪卡片上记录调度元数据。
- 阻止过期认领或超时运行。
- 将按看板配置的分诊卡片标记为编排候选项。
- 认领一小批就绪卡片，并通过 Gateway 网关子智能体运行时启动 worker 运行。
Worker 选择
默认情况下，每次调度最多启动 3 个 worker。就绪卡片按优先级排序，然后按位置排序，再按创建时间排序。一次调度只会为每个 owner/智能体启动一张卡片，并跳过看板上已有运行中或 review 工作的 owner。已归档卡片、已有活跃认领的卡片，以及状态不是ready 的卡片，永远不会被选中用于启动 worker（它们仍可能受到调度的数据侧影响：陈旧认领清理、依赖提升、超时清理）。
会话键按看板/卡片确定性生成，因此重复调度会路由回同一个 worker 通道，而不是创建无关会话：
- 已分配卡片：
agent:<agentId>:subagent:workboard-<boardId>-<cardId> - 未分配卡片：
subagent:workboard-<boardId>-<cardId>（Gateway 网关解析已配置的默认智能体）
入口点
- 仪表板调度操作
openclaw workboard dispatch- 支持命令的渠道上的
/workboard dispatch
unknown method 错误），并且没有显式的 --url/--token 目标，也没有适用的已配置远程 Gateway 网关（OPENCLAW_GATEWAY_URL 或 gateway.mode: remote），CLI 会针对本地 SQLite 状态运行仅数据调度 - 它可以提升依赖、清理陈旧认领、阻止超时运行，但不能启动 worker。来自可访问 Gateway 网关的身份验证、权限和校验失败不会被视为不可用；它们会作为命令错误浮现；当给定了显式 --url/--token 目标时，任何 Gateway 网关失败也同样如此。
看板元数据可以设置 autoDecompose、autoDecomposePerDispatch、defaultAssignee 和 orchestratorProfile。OpenClaw 会记录此意图并在 worker 上下文中公开；实际的规格说明/分解仍通过正常的 Workboard 工具运行。
CLI 和斜杠命令
list 文本输出默认隐藏已归档卡片（--include-archived 会覆盖）；--json 始终包含已归档卡片，与现有脚本使用的完整卡片契约一致。show 接受无歧义的 ID 前缀。list、create 和 show 始终直接读写本地插件状态。只有 dispatch 会调用正在运行的 Gateway 网关，并使用上文所述的回退行为。
完整标志、JSON 输出、Gateway 网关回退行为、ID 前缀处理、调度选择规则和故障排查，请参阅 Workboard CLI。
/workboard list、/workboard show <card-id>、/workboard create <title> 和 /workboard dispatch 与 CLI 对应。List 和 show 对任何已授权命令发送者都是读取操作。Create 和 dispatch 在聊天界面上需要 owner 状态，或需要具备 operator.write/operator.admin 的 Gateway 网关客户端。
会话生命周期同步
卡片可以链接到现有仪表板会话，也可以链接到从卡片开始工作时创建的会话。已链接卡片会内联显示会话生命周期：running、stale、linked idle、done、failed 或 missing。你也可以在 Sessions 标签页中使用 Add to Workboard 捕获现有会话；该卡片会链接到该会话，使用会话标签或最近的用户提示作为标题，并在可用时使用最近的用户提示加最新的助手响应填充 notes。 如果链接的会话缺失，卡片会保持链接以保留上下文，并仍提供启动控件以重启到新会话。如果一个活跃的已链接会话停止报告近期活动，Workboard 会将卡片标记为stale，并将其作为元数据存储，直到生命周期清除它。
当卡片处于活跃工作状态时，Workboard 会跟随已链接会话：
| 已链接会话状态 | 卡片状态 |
|---|---|
| active | running |
| completed | review |
| failed、killed、timed out 或 aborted | blocked |
review、blocked 或 done 会停止该卡片的自动同步，直到你将其移回 todo 或 running。
启动卡片会使用正常的 Gateway 网关会话；Workboard 只存储卡片元数据和链接。对话 transcript、模型选择和运行生命周期仍由常规会话系统拥有。对一个实时已链接卡片使用 Stop 可中止活跃运行 - Workboard 会将该卡片标记为 blocked，使其保持可见以便后续处理。
新卡片可以从 Workboard 模板（bugfix、docs、release、pr_review、plugin）开始。模板会预填标题、notes、标签和优先级；模板 ID 会存储为卡片元数据。
仪表板工作流
- 在 Control UI 中打开 Workboard 标签页。
- 创建一张带有标题、notes、优先级、标签、可选智能体和可选已链接会话的卡片 - 或打开 Sessions 并为现有会话选择 Add to Workboard。
- 在列之间拖动卡片，或聚焦其紧凑状态控件并使用菜单或 ArrowLeft/ArrowRight。
- 从卡片开始工作，以创建或复用仪表板会话。
- 在智能体工作时，从卡片打开已链接会话。
- 让生命周期同步把运行中的工作移动到
review/blocked，然后在接受后手动将卡片移动到done。
诊断
诊断根据本地卡片元数据计算。内置检查会标记：| 类型 | 条件 |
|---|---|
stranded_ready | 已分配的 todo/backlog/ready 卡片超过 1 小时未更新。 |
running_without_heartbeat | running 卡片超过 20 分钟没有认领 heartbeat 或执行更新。 |
blocked_too_long | blocked 卡片超过 24 小时未更新。 |
repeated_failures | 卡片跟踪的失败计数达到 2 次或更多。 |
missing_proof | done 卡片没有 proof、artifacts 或 attachments。 |
orphaned_session | running 卡片有 sessionKey，但没有 execution 元数据。 |
权限
Gateway 网关 RPC 方法位于workboard.* 下：
| 权限范围 | 方法 |
|---|---|
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 |
operator.admin。以只读操作员访问权限连接的浏览器可以检查看板，但不能变更卡片。
存储
Workboard 将持久数据存储在 OpenClaw 状态目录下由插件拥有的关系型 SQLite 数据库中：boards、cards、labels、lifecycle events、run attempts、comments、dependency links、proof、artifact references、attachment metadata and blobs、diagnostics、notifications、worker logs、protocol state 和 subscriptions 都位于 Workboard 表中（不是插件键值条目）。卡片导出会保留看板叙事，而不会内联 attachment blob 内容。 在.28 版本中使用过 Workboard 的安装可以运行 openclaw doctor --fix，将已发布的旧版插件状态命名空间（workboard.cards、workboard.boards、workboard.notify，以及如果存在的 workboard.attachments）迁移到关系型数据库中。
故障排查
标签页显示 Workboard 不可用plugins.allow，请向其中添加 workboard。如果 plugins.deny 包含 workboard，请先移除它再启用插件。
卡片无法保存
确认浏览器连接具有 operator.write 访问权限。只读操作员会话可以列出卡片，但不能创建、编辑、移动或删除卡片。
启动卡片没有打开预期会话
检查卡片的智能体 ID 和已链接会话，然后打开 Sessions 或 Chat 检查实际运行状态。
调度没有启动 worker
确认至少有一张没有活跃认领的 ready 卡片：