进度卡片

progress_card 是会话中唯一的代理状态工具。它存储一个有序步骤计划、一个紧凑的 Markdown 备注，或两者兼有。每次调用都会替换整个卡片，因此最新写入是跟踪工作而不阅读转录的人的事实来源。

该卡片属于用户正在对话的父会话及其代理。生成的子代理永远不会接收 progress_card 或其提示提醒，包括可见的仪表板子会话和恢复的子会话。它们的结果返回父会话，父会话负责进度更新。该工具从运行中的会话绑定会话和代理；模型只提供 markdown 和 plan。

卡片是持久化的会话状态。重新连接或页面刷新会从 Gateway 读取最新卡片，而不是从工具事件或转录历史中重建它。转录只保留一条简短的更新回执，而不是卡片的另一份完整副本。

采用¶

仅为具有至少两个有意义的顺序步骤的实质性工作创建卡片。跳过问候、快速提问和单步骤请求；不要为了证明卡片的必要性而编造步骤。检查清单仍然是可选的：符合条件的工作可以使用 Markdown、计划，或两者兼有。当进度发生有意义的变化时，仍可以更新现有卡片；当被要求时，也可以清除卡片。

OpenClaw 仅对非主、非子代理会话添加简短的进度卡片提醒，条件是某个 web、iOS、Android 或 macOS 卡片渲染器已与 Gateway 配对，并且该运行未使用代理的 utility model。仅通道的部署（例如仅 WhatsApp 的 Gateway）不会收到该提醒。

提醒内容如下：

仅对具有至少两个有意义的顺序步骤的实质性工作使用 progress_card 创建卡片，绝不用于问候、快速提问或单步骤请求。对于具有已知总量的可衡量工作，优先使用前置进度条，并标注所测量的内容以及观察到的已完成/总数；绝不编造百分比。根据需要更新或清除现有卡片。

该提醒不会覆盖工具策略。tools.updatePlan: false 或匹配的 tools.deny 条目仍会将 progress_card 完全从运行中移除。

更新卡片¶

两个输入字段都是可选的：

• plan：最多 50 个有序步骤。每个步骤都有非空的 step 文本，以及 pending、in_progress 或 completed 之一的 status。最多一个步骤可以是 in_progress。
• markdown：关于发生了什么、什么被阻塞或接下来是什么的紧凑叙述。当一眼可见的备注比步骤列表表达得更多时，使用它；不要在 Markdown 中重复计划。

对于具有已知总量的批量工作，优先使用前置进度条：

{
  "markdown": "<progress aria-label=\"PRs reviewed · 12/30\" value=\"12\" max=\"30\"></progress>\n\nTwo obsolete PRs closed. Verifying the next fix."
}

对于真正顺序执行的工作，检查清单可以显示当前阶段：

{
  "plan": [
    { "step": "Inspect the failing route", "status": "completed" },
    { "step": "Repair the session owner", "status": "in_progress" },
    { "step": "Run focused verification", "status": "pending" }
  ],
  "markdown": "The failure is isolated to session ownership. No blocker."
}

每次调用都是替换，而不是补丁。省略 markdown 会移除之前的备注；省略 plan 会移除之前的检查清单。

该工具返回一条简短回执，例如 Progress card updated (rev 4, 1/3 done)，或者在没有计划时返回 Progress card updated (rev 4)。其结构化结果包含修订号以及已完成/总步骤数，或者在没有计划时为 null。成功写入还会根据完整的计划状态更新通道预览。失败或被阻塞的写入会保留之前的计划。活动通道预览会保留一条安全的失败通知。

在活动运行结束前¶

当运行仍欠一个可见回复时，如果该运行成功保存了一个未完成的检查清单，然后产生一个正常的最终答案，内置代理运行时最多执行一次完成自检。代理会重新检查最新的用户指令：继续可行的、已授权的工作，核对已完成的步骤，或解释无法继续的具体原因。这可能会增加一次模型响应；它不保证模型完成每个任务。

该检查继续同一个活动运行，使用其现有转录、权限、时间限制和已完成的工具结果。它不会重放之前的操作，也不会重启原始请求。已在聊天中显示的检查点在继续工作时仍保留在对话中。真正的阻塞可能在检查后使步骤保持 pending。

旧卡片不会重启空闲工作。已完成、已清除和仅备注的替换不会请求检查。取消、审批等待、已接受的子会话/媒体完成交接、仅状态刷新以及显式插件最终化保留其现有行为。其他代理框架保留其自身的最终化策略。

暂停而不将工作标记为完成¶

如果由于显式暂停、所需审批或外部依赖，没有任何已授权步骤可以继续，请用仅 Markdown 卡片替换检查清单。保持未完成的工作、阻塞项、负责方和恢复条件可见。不要将受阻步骤标记为已完成，也不要暗示请求已完成。

{
  "markdown": "Update remains open and paused. Waiting for the source owner to publish the reviewed repair. No deployment is authorized; reconcile the new packet and current instructions before resuming."
}

省略 plan 会移除检查清单，而不是移除备注或任务的未解决工作。仅备注替换不会请求完成自检。在后续普通回合中重新保存未完成的检查清单可能会请求另一次检查，即使同一阻塞仍然存在。当已授权工作可以继续时，恢复检查清单；将任何其他未解决的依赖保留在备注中。

格式化备注¶

对于具有已知总量的符合条件的多步骤工作，优先使用基于观察到的已完成/总数的前置进度条：已审查的 PR、已完成的测试、已处理的文件，或其他有意义的工作单元。优先使用这些计数，而不是粗略的阶段计数，例如“3 步中的 1 步”。准确标注计数所测量的内容：已审查的 PR 不是已合并的 PR，已完成的测试也不一定是通过的测试。绝不编造百分比，也不要从经过的时间推断完成度。当总量未知时，改用紧凑的状态备注或表格。

在进度条后跟一句简短的结果、阻塞项或下一步操作。使用表格进行对比，并且仅当工作确实按顺序进行时使用检查清单。如果表格、进度条或句子能更好地表达，则省略检查清单，并且不要在计划和 Markdown 中重复相同的事实。在有意义的批次或状态变化后更新，并在每次替换中保持进度条及其标签为最新。Markdown 支持普通格式、链接和进度条：

<progress aria-label="Checks finished · 3/7" value="3" max="7"></progress>

Tests are running.

| check      | state   |
| ---------- | ------- |
| unit tests | passed  |
| live flow  | running |

先放一个进度条，并为其提供一个简短的 aria-label，说明其用途以及当前值/总数。在会话悬停卡片中，Agent Notepad 会将进度条固定在笔记上方并显示该标签。其他原始 HTML 会被 Markdown 清理器移除。

限制¶

• Markdown：最多 8,192 个 UTF-8 字节。
• 计划：最多 50 个步骤。
• 步骤文本：非空，且每个步骤最多 512 个 UTF-8 字节。
• 活动工作：最多一个 in_progress 步骤。

Gateway 会在存储卡片之前，从 Markdown 和步骤文本中移除不可见 Unicode 和双向控制字符。

清除卡片¶

调用 progress_card，使两部分均缺失或为空，以移除当前卡片：

{}

空计划加上空或仅包含空白字符的 Markdown 也会清除它。成功清除会返回 Progress card cleared。频道预览会移除检查清单及其状态，保留其他活动，并删除否则为空的草稿。后续的卡片更新可以创建新草稿。

在 Control UI 中，具有写入权限的用户可以使用 Dismiss progress card（×）清除当前卡片，无论其处于展开还是折叠状态。该按钮可用于未完成、已暂停、已完成和仅笔记卡片。关闭会清除已保存的卡片，而不是对话或活动 agent 运行；后续的进度更新可以创建新卡片。关闭仅清除用户看到的修订版本；如果 agent 已写入更新的修订版本，则会保留并显示更新的卡片。

完整就地对话重置（不带 soft 的 /reset，或 sessions.reset）也会清除上一个任务的卡片。清除会随重置边界提交并刷新已订阅的客户端；新页面加载也不会看到旧卡片。在该重置之前被接受的写入无法恢复它。重置会保留对话记录历史和仪表板布局。保留先前上下文的自动连续性重置不会清除卡片。

卡片显示位置¶

带有进度草稿的频道会在活动的 partial、block 和 progress 预览中显示最新检查清单，具体取决于其预览设置和行数限制。带有步骤的卡片会提供完成计数。没有步骤的笔记会提供可读文本，并移除 Markdown 格式和作者编写的 HTML，受现有标题限制约束。没有可读文本的笔记会提供 Progress updated。完整 Markdown 仍保留在持久卡片中。Telegram 在 channels.telegram.richMessages: true 时使用原生复选框，否则使用可读 HTML 检查清单。参见 流式传输和分块。

默认情况下，当前聊天会在每个宽度下，在 composer 内的可折叠区域中恰好保留一个实时卡片。打开侧边栏不会将其移出对话。仪表板组件和会话悬停卡片是独立的只读放置位置：将鼠标悬停在侧边栏中的会话行或聊天中的会话引用链接上，即可查看该会话的同一卡片。所有卡片放置位置都读取相同的 Gateway 支持状态，并在 progressCard.changed 通知后刷新。通知是刷新提示，包括空修订；客户端通过针对该会话和 agent 的读取或清除响应来确认移除。

在 Control UI 中，Settings → Appearance → Chat → Show task progress cards 用于隐藏或显示 composer 卡片。它默认启用，并且仅存储在此浏览器中。关闭它还会移除加载占位符，但不会停止 agent 工作、清除已保存的进度，或更改仪表板组件和会话预览。重新打开它即可查看当前卡片。独立的 Collapse task progress by default on desktop 首选项在卡片隐藏期间会保留。

在移动设备上，composer 卡片初始为折叠状态，发送新消息不会打开它。在桌面端，新创建的卡片初始为展开状态，除非启用了 Collapse task progress by default on desktop。挂载卡片或切换会话时，会显示其初始状态，且没有折叠动画。在阅读较早消息时，自动折叠需要至少两次向上滚动手势，总距离至少 320 像素，随后 300 毫秒内没有滚动。间隔超过 200 毫秒的滚轮突发分别计数；每次触摸拖动计为一次手势，包括其惯性。仅由对话记录消费的上移量计数；工具输出内的滚动、已取消的输入和程序化位置调整不计入。返回底部会重置计数。

当展开的问题替换 composer 时，任务进度卡片会随之隐藏。回答、跳过或折叠问题会恢复卡片，并保留其展开状态。在问题展开时滚动对话记录不会折叠隐藏的卡片。

发送新消息、完成运行、返回底部以及进度更新都不会重新打开已折叠的卡片。已打开的卡片同样会在新消息和完成过程中保持其选定的打开状态。只有当 Gateway 确认前一个卡片已被清除后，新卡片才会获得其初始桌面或移动默认状态；更改笔记或检查清单是更新，而不是创建。如果客户端无法确认清除，它会保留之前的选择，而不是猜测新任务已开始。

完全打开、关闭和部分高度选择会在当前 Gateway 连接中为每个卡片记住，直到页面重新加载。切换 Gateway 连接会从全新选择开始。手动关闭会阻止自动重新打开。在一次访问或运行期间，首次手动重新打开后，继续向上滚动可以再次折叠卡片，但阈值更高：三次手势和 640 像素，随后是相同的 300 毫秒暂停。该折叠会记住关闭状态。第二次手动重新打开会停止该访问期间的自动折叠。离开聊天并返回会恢复基础阈值，同时保留卡片记住的打开状态。新消息和运行完成不会重置选择。

在 composer 卡片的标题栏上向上拖动，或在指针悬停于其上时向上滚动，以显示更多面板内容。向下移动可将其关闭。完全关闭会记住与点击标题栏相同的完全关闭选择，包括跨新消息的情况。面板会跟随你移动的距离：停止会保持部分打开状态，反向移动会将其移回，没有定时动画或释放吸附。在标题栏上进行触摸拖动也有效。备注和清单保持正常的滚动和链接。

点击标题栏，或聚焦后按 Enter 或 Space，以打开或关闭整个卡片。部分打开状态在激活时会完全展开；已经显示整个面板的打开状态会在第一次激活时关闭，包括通过手势到达的情况。

部分打开是当前卡片的像素高度选择：新输出、卡片修订、新运行和最终响应不会完成或撤销它。在当前 Gateway 连接中离开并返回同一卡片会保留该高度；清除并创建新卡片会丢弃它。其他会话和 Gateway 连接不会继承它。较小的视口会将保留的高度限制在可用面板空间内。

接管标题栏会清除待处理的对话记录折叠手势。显示一个已关闭的卡片计为一次手动重新打开，而不是每次移动计一次；后续真实的对话记录手势仍遵循上述阈值。直接操作还会暂停对话记录跟随；使用 最新 或滚动回最新消息以恢复。最新 不会改变所选卡片高度。

瞬时刷新失败会保留最后加载的卡片。仪表板小部件会显示重试通知，直到刷新成功。如果 Gateway 报告该连接不再参与会话，客户端会隐藏卡片，直到访问恢复且刷新成功。

composer 和仪表板位置显示上次进度更新的本地时间。悬停卡片则显示当前或下一个计划步骤及其已完成/总数计数，当存在备注时，随后在单独的 Agent Notepad 中显示 Markdown。

如果没有匹配的终结结果，如果 Gateway 报告没有活动运行，或卡片早于后续运行，未完成的步骤会显示为暂停。最后更新时间显示代理上次修订卡片的时间；仅凭经过时间不会使属于活动运行的卡片过期。

刷新当前工作状态¶

在 Control UI 的 composer 中，选择卡片时间戳旁边的 刷新任务进度，以要求代理将卡片与其当前工作协调一致。卡片折叠时该操作仍可用。它不会发送可见的聊天消息。

在请求待处理期间，之前的卡片及其最后更新时间仍可见。只有当 Gateway 返回更新的已保存卡片后，刷新才会确认。如果请求失败或耗时过长，请使用重试操作；超时不会取消正在运行的工作。

活动代理会在其下一个受支持的引导边界接收请求，而不会中断正在运行的工具或回答待处理的问题。如果引导不可用，请求会等待一个仅状态轮次。空闲代理可以使用只读上下文工具和 progress_card 更新卡片；刷新不会授权其恢复已停止的工作或更改任务目标。控制请求和独立刷新输出对聊天保持隐藏，包括重新加载的历史。来自已活动任务的正常回复仍可见。

引导针对当前会话自身的运行。如果父级已让出，而子代理继续工作，刷新会在父会话中使用一个单独的仅状态轮次。

该操作使用会话现有的写入权限。仪表板和悬停卡片位置保持只读。

Gateway 请求¶

progressCard.get、progressCard.put 和 progressCard.refresh 接受必需的 sessionKey 和可选的 agentId。显式选择代理时，请同时传递两者，例如 { "sessionKey": "global", "agentId": "research" }。省略 agentId 会保留 Gateway 现有的会话所有者解析。未知代理或与会话所有者冲突的代理会被拒绝。

在后续读取和清除时，请保持原始会话和代理一起。返回的卡片和变更事件使用代理限定的显示键；仅凭该键无法区分保留的 global 会话和键为 agent:<agentId>:global 的普通会话。除操作员读取或写入范围外，所有三种方法都使用所选会话的正常访问检查。

progressCard.refresh 还要求 idempotencyKey 和一个现有卡片。它不接受提示文本。其 { runId, status: "accepted", revision } 响应确认请求并标识基线修订；这并不意味着卡片已更新。客户端通过现有的变更事件和读取路径确认更新的卡片。

使用相同幂等键的重试会保留原始修订基线，并将已完成的工作与最新保存的卡片进行比较。

Control UI 与其 Gateway 一起发布，并在不进行版本协商的情况下遵循捕获的会话所有者：普通代理限定的键会省略冗余的 agentId，而原始目标保留其显式所有者。Gateway 还会在 hello.features.capabilities 中为独立升级的客户端（例如原生应用）通告 progress-card-agent-scope-v1。这些客户端在发送 agentId 之前会检查该能力：普通代理限定的键可以省略该字段，而具有显式所有者的规范 global 目标需要该字段。如果缺少该能力，独立升级的客户端会报告需要更新 Gateway。

将卡片固定到仪表板¶

使用 dashboard 工具将实时卡片保留在当前会话的仪表板上：

{
  "action": "widget_put",
  "name": "session-progress",
  "title": "Session progress",
  "pluginKind": "session:progress",
  "size": "md"
}

省略 props.sessionKey 以跟随仪表板的会话。要显示另一个会话的卡片，请添加 "props": { "sessionKey": "agent:main:release" }。当前连接必须参与该会话；否则请选择可访问的会话或更改其共享。

相关¶

• 工具概览
• openclaw dashboard — 从 CLI 打开 Control UI
• Control UI 网址 — 在浏览器中访问 Control UI