OpenClaw 实时进度卡:用 progress_card 让长任务「看得见」

为什么需要进度卡

OpenClaw 跑长任务（构建、批量抓取、定时生成文章）时，默认只在对话里逐步输出。问题在于：

• 后台任务（automations / isolated session）用户根本不在对话现场，看不到任何中间状态；

• 一个多步骤任务中途卡住，你只能干等，不知道卡在第几步；

• 重启、掉线后再回来，不知道上次跑到哪了。

progress_card 就是解决这个的工具：它维护当前会话旁边那张持久状态卡，别人不翻聊天记录也能一眼看到你在干什么、做到哪了、成没成。

工具本身长什么样

progress_card 每次调用都会整体替换那张卡，不是追加。所以你每次把「最新全貌」传进去即可。

它支持两部分：

| 字段 | 作用 | 什么时候用 |

|------|------|-----------|

| markdown | 一段极简文本说明（紧凑笔记 / 表格 / 进度条） | 任何状态变化 |

| plan | 有序步骤清单（pending / in_progress / completed） | 真正串行的多步骤任务 |

最多 8KB markdown、最多 50 个步骤。

基础用法：一句话状态

最简单的形式，只更新 markdown：

{
  "markdown": "正在发布今日文章 → 已写入静态站，等待线上校验"
}

调用后，卡片立刻变成这句话。任务结束再补一句最终结果即可。

进阶用法：步骤清单

当任务是明确的几步流水线，用 plan 最清晰：

{
  "plan": [
    {"step": "选题去重", "status": "completed"},
    {"step": "写稿", "status": "in_progress"},
    {"step": "发布到静态站", "status": "pending"},
    {"step": "线上校验 200", "status": "pending"}
  ]
}

同一时刻最多一个步骤为 in_progress，其余是 completed 或 pending。每推进一步就整体重传一次，把当前那步翻成 in_progress、上一步翻成 completed。

实战：嵌入每日发文脚本

把每日 03:00 发文任务真实跑一遍，进度卡这样推进（伪代码，真实可操作）：

# 1) 选题去重完成
progress_card(markdown="选题去重完成，无重复，锁定角度:progress_card",
              plan=[
                {"step":"选题去重","status":"completed"},
                {"step":"写稿","status":"in_progress"},
                {"step":"发布","status":"pending"},
                {"step":"线上校验","status":"pending"},
              ])

# 2) 写稿 + 发布脚本跑完
progress_card(markdown="已发布，等待线上 curl 校验",
              plan=[
                {"step":"选题去重","status":"completed"},
                {"step":"写稿","status":"completed"},
                {"step":"发布","status":"completed"},
                {"step":"线上校验","status":"in_progress"},
              ])

# 3) 校验结果（HTTP 200）
progress_card(markdown="✅ 发布成功 https://zyker.cn/archives/.../ 字数 1820 含二维码",
              plan=[
                {"step":"选题去重","status":"completed"},
                {"step":"写稿","status":"completed"},
                {"step":"发布","status":"completed"},
                {"step":"线上校验","status":"completed"},
              ])

进度条（不依赖 plan）

纯文本也能画进度条，适合「单一大活按百分比」的场景：

{
  "markdown": "批量抓取 3/7 篇\n<progress value=\"3\" max=\"7\"></progress>"
}

<progress> 是标准 HTML，OpenClaw 的卡片会直接渲染成可视进度条。

三个容易踩的坑

• 整张替换，不是追加
  ：别指望「再发一条就多一行」。想保留旧信息，就把旧内容一起写回。

• 别每句话都刷
  ：步骤级更新足够，消息级刷屏会让卡片失去「概览」意义。

• 失败也要更新
  ：任务挂了，把 markdown 改成失败原因（例如「❌ 构建失败：gen.js 退出码 1」）。静默失败是最糟的——卡片还停在 in_progress，没人知道已经死了。

和 dashboard 的区别

• progress_card
  ：轻量、持久、贴在当前会话旁，适合「这一件事做到哪了」。

• dashboard
  ：富可视化 widget，适合「同时盯好几个指标面板」。

日常长任务用 progress_card 就够了；要做监控大盘再上 dashboard。

小结

进度卡的本质是把「AI 在忙」变成「AI 在哪」。多步骤任务开头建 plan，每步翻状态，结束翻 completed 或写失败原因——用户不在现场也能一眼看懂，重启后也有迹可查。

关注公众号，获取更多 OpenClaw 实操技巧