AGENT SKILL

clawevolve-diagnose

Diagnose a bot by analyzing a bounded range of its original OpenClaw session records according to the user-provided natural-language intent, extracting evidence-backed good and bad cases, identifying behavioral and MCP/tool-use problems, and producing structured artifacts for subsequent clawevolve-plan evolution planning. Use when receiving /clawevolve-diagnose or when asked to inspect historical bot sessions, diagnose failures, extract evaluation cases, or prepare diagnosis input for self-evolution; Session Judge supports the Bot's OpenClaw Agent by default and an optional API-key backend.

License 许可
Apache-2.0
最近更新
2026-11-14
Stars
★ 603
Forks
82

01 前言 Front Matter

name
clawevolve-diagnose
description
Diagnose a bot by analyzing a bounded range of its original OpenClaw session records according to the user-provided natural-language intent, extracting evidence-backed good and bad cases, identifying behavioral and MCP/tool-use problems, and producing structured artifacts for subsequent clawevolve-plan evolution planning. Use when receiving /clawevolve-diagnose or when asked to inspect historical bot sessions, diagnose failures, extract evaluation cases, or prepare diagnosis input for self-evolution; Session Judge supports the Bot's OpenClaw Agent by default and an optional API-key backend.

02 资源文件 109

03 SKILL.md 正文

clawevolve-diagnose

平台命令可能携带 --reference-materials-version 1,必须原样透传,不得移除。Runtime 会在业务执行前下载并校验本任务的用户参考材料,向实际 Agent 提供只读目录与索引。不要自行替换为其他任务的文件,也不要把上传材料当作运行权限或自动执行的 Skill。

平台核心实现选择

按下文运行原诊断脚本。脚本在会话分析调用处选择默认或自定义业务实现,继续负责采集、筛选、产物生成与上报;Agent 无需另行调度或提交结果。

最高优先级执行规则

  1. 用户怎么调用,就怎么传给脚本:不要改参数名、不要改 ID 字符、不要补参数、不要删除参数。
  2. 只运行一次脚本:禁止先空跑 bash scripts/run.sh,禁止失败后换参数重跑,禁止手工 curl ClawWeb 代替脚本。
  3. ID 必须原样保留:EV-...、STEP-... 中的连字符 - 不能改成下划线 _;参数名必须是 --task-id、--step-id。

执行前自检最终 shell 命令:

  • shell 命令必须包含用户原始 --task-id、--step-id;若用户提供了 --api-key、--model 等参数,也必须逐字符保留。
  • shell 命令中的 task-id/step-id 必须与用户文本逐字符一致。

角色定位

收到 /clawevolve-diagnose ... 或用户要求“诊断历史 session / 抽取 eval case / 挖掘 good/bad case / 为 clawevolve-plan 准备输入”时,Agent 只做脚本执行器:运行脚本、等待结束、读取最终 stdout JSON、按 JSON 指示下一步。不要手工分析 session、不要重写流程、不要自行上传或生成模板。

固定链路:发现本地 sessions → selected session judge 诊断 → 去重选 case → 写 artifacts/plan-source.json → 上报 ClawWeb step report。模板生成属于 clawevolve-plan,不在本 skill 内完成。

必须执行的命令

收到 /clawevolve-diagnose ... 后,只运行一次前台脚本,并把用户的完整 slash command 作为一个单独引号参数传给 scripts/run.sh。这是唯一推荐方式,可最大程度避免自然语言、日期范围和 ID 被拆坏:

cd clawevolve-diagnose && bash scripts/run.sh '<用户完整/clawevolve-diagnose命令原文>'

稳定脚本调用建议使用显式 --intent:

cd clawevolve-diagnose && bash scripts/run.sh \
  --task-id "$TASK_ID" \
  --step-id "$STEP_ID" \
  --judge-backend subagent \
  --intent "诊断工具调用失败和异步任务未完成的问题,抽取最多10个case,重点关注最近7天"

示例:用户输入是:

/clawevolve-diagnose --api-key *** --model GLM-5 --intent "抽取 20260723 至 20260804 的5个case,有good和bad,bad占比至少80%。" --task-id EV-20260804-444491B4 --step-id STEP-A70F0B24A0804F33

则执行:

cd clawevolve-diagnose && bash scripts/run.sh '/clawevolve-diagnose --api-key *** --model GLM-5 --intent "抽取 20260723 至 20260804 的5个case,有good和bad,bad占比至少80%。" --task-id EV-20260804-444491B4 --step-id STEP-A70F0B24A0804F33'

注意:不要把示例中的 *** 当真实 key。--judge-backend subagent 使用当前 Bot 的 OpenClaw Agent, 不需要 API Key;--judge-backend api 才要求 --api-key 或 OPENAI_API_KEY。未显式选择 backend 时, 有 Key 兼容走 API,否则默认走 subagent。ARCA Message 模式只允许 subagent,不得在 Message 中传 Key。

执行规则:

  • 必须逐字符保留用户给出的 --task-id、--step-id、--api-key、--model 等参数值;不要改写、删减、重排、补造用户参数。
  • 运行可能超过 30 分钟,耗时长是正常现象;触发后必须让同一个进程运行到退出,不能因短时间无最终 JSON、进度慢、LLM/上传重试、shell tool 返回仍在运行而中断。
  • 不要启动第二个 diagnose;进程未退出就持续等待/轮询同一个进程。
  • stderr 是进度日志,不是最终结果;最终结果只看脚本退出后 stdout 的 JSON。

参数契约

业务输入来自显式命令参数、--intent 自然语言解析、代码默认值。仅 API Judge 的 Key 支持 OPENAI_API_KEY 环境变量(BaaS 注入);clawweb-url 支持部署环境注入的默认值。

显式 CLI 参数:

参数 是否必填 默认值 说明
--task-id 是 无 ClawWeb task ID;也用于默认输出目录。只接受字母/数字/_/-/.,禁止 ..。注意参数名是连字符。
--step-id 是 无 ClawWeb step ID;与 --task-id 共同用于上报 /tasks/{task_id}/steps/{step_id}/report。注意参数名是连字符。
--judge-backend 否 有 Key 时 api,否则 subagent subagent 使用当前 Bot OpenClaw Agent;api 使用 OpenAI-compatible API。
--api-key API Judge 必填 OPENAI_API_KEY OpenAI-compatible LLM API key;命令行主要用于本地调试,BaaS 使用环境变量注入;subagent 不消费 Key。
--llm-base-url 否 代码默认 DEFAULT_BASE_URL OpenAI-compatible base URL;未传时只用代码默认。LLM 请求最终走 <base-url>/chat/completions。
--model API Judge 必填;Subagent 可选 Subagent 使用 OpenClaw 当前默认模型;API Judge 无默认值 LLM model name;ClawWeb 发起的 API Judge 任务会显式传递页面选择值。
--intent 否 空 本次诊断的自然语言意图;可描述问题类型、case 数量、时间范围和筛选偏好。自然语言只能通过该参数传入。
--max-sessions 否 10 快速过滤后最多保留并送 Judge 分析的最新 session 数;个人/服务 Bot 共用。
--session-identifier 否,可重复 空 按 Session ID 或 Session Key 精确选择;先按 ID、未命中再按 Key,最多 20 个。

| --session-id | 否 | 空 | 平台冻结的精确 Session 范围;可重复传入。存在时必须只分析这些 Session,不得改为最新会话或扩大范围。 | | --debug-session-path | 否 | 空 | 调试入口:只从指定 session JSONL 文件读取并分析该 session。 | | --openclaw-home | 否 | 当前 Bot 安装目录中的 .openclaw 根目录 | 本地测试可显式指定 OpenClaw 根目录;平台执行时自动绑定当前 Bot,不得改成其他用户目录。 | | --clawweb-url | 否 | 部署默认值 | ClawWeb Step Report 基础地址。 | | --skip-clawweb-report | 否 | false | 仅本地测试使用,跳过网络上报。 | | --output-dir | 否 | <当前 Bot .openclaw>/workspace/clawevolve_results/{task_id}/diagnose/output/ | 隐藏兼容参数;一般不要主动添加。 |

已废弃/不支持:--execution-id、--execution_id、--task_id、--step_id、--llm-model、--evolve-run-id。必须使用 --task-id、--step-id。遇到旧下划线参数应让脚本报错,不要自动替换。

自然语言意图只能通过 --intent "..." 指定;不接受位置参数形式的自然语言。意图可指定:case 数量、good/bad 数量或比例、关注/排除关键词、失败模式、时间范围。时间范围支持今天/昨天/近7天/不限时间,以及显式日期区间如 2026-07-01到2026-07-10、20260701~20260710、7月1日至7月10日;必须把用户自然语言原样放入 --intent 参数并透传给脚本。默认时间窗口为近 3 天。

ClawWeb 上报契约

--task-id 和 --step-id 校验通过后,脚本会向 ClawWeb 上报 step report;主流程成功上报 succeeded,失败上报 failed。平台明确以 HTTP 400/422 拒绝成功结果或本地报告载荷不合法时,记录拒绝原因并上报 failed;网络超时或其他不确定响应保留 deferred,不用失败报告覆盖可能已接收的成功结果。

固定接口:

POST {clawweb_url}/api/evolve/internal/tasks/{task_id}/steps/{step_id}/report
Content-Type: application/json

成功 payload 形态:

{
  "status": "succeeded",
  "summary": "完成近期 Case 抽取与问题诊断",
  "output": {
    "diagnosis": {"summary": "...", "issues": []},
    "cases": {"total": 5, "goodCount": 1, "badCount": 4, "items": []}
  }
}

当前 diagnose 只在本地流程结束后上报一次最终结果:成功上报 status=succeeded,失败上报 status=failed、summary、error。网络调用等价于 curl --noproxy '*',最多重试 3 次(共 4 次尝试);若后端返回 step 已处于终态,立即停止重试并记录 deferred。

Judge 调用与排障要点

  • session judge 调用由脚本内部完成;Agent 不要直接 curl、直接调用其他 LLM SDK,或手工分析 session 替代脚本。
  • --judge-backend subagent:使用当前 Bot 的 OpenClaw Agent;脚本负责 Agent 调用、结构化结果校验、 诊断产物落盘以及临时 Agent/Session 清理。该链路不读取也不需要 API Key。
  • 传入 --api-key:请求格式对齐 OpenAI-compatible /chat/completions:model、字符串形式的 messages[].content、stream:true;代码只使用 Python 标准库 urllib,以 stream:true 调用用户指定 base URL 的 OpenAI-compatible /chat/completions,逐条解析 SSE;日志会输出 endpoint、attempt、payload/content preview、HTTP 响应、上游 request id 和重试信息。
  • --judge-backend api:请求中携带压缩后的 session content,由 OCSA/session judge 返回结构化诊断; 缺少 API Key 时失败,不回退到 subagent。
  • 不指定端口的 HTTPS 应走 443;若 API 日志出现 :7002,优先检查传入的 --llm-base-url 或运行环境参数透传。
  • direct API judge 不实现外层业务重试;底层标准库 HTTP 客户端统一处理连接错误、流读取中断、超时、限流和服务端错误,重试 4 次、最多 5 次 HTTP attempt。请求使用 stream:true,默认单次连接/读取 timeout 为 600 秒。
  • API key 会脱敏;但为开发排查,日志会包含 session/query/payload 预览。

session 选择逻辑

默认 session 选择逻辑:

  1. 自动发现当前 OpenClaw runtime、本地 session 目录和当前 bot identity。
  2. 将发现到的本地 JSONL sessions 视为当前 bot 候选;不再按可能陈旧的内嵌 bot_id 二次过滤。
  3. 按时间 newest-to-oldest 扫描,流式解析并限量,避免 OOM。
  4. 每轮按最多 8 个的小批次取去重后的 session 直接送 selected session judge;无规则质量预筛。批大小会根据尚缺的 case 数量及 good/bad 配额动态缩小;一旦满足用户要求立即停止,不继续扫描剩余 session。API backend 可并发;subagent 通过 OpenClaw Agent 逐 session 诊断。
  5. 持续到满足 case 配额、候选池耗尽或达到代码默认最大 judge 轮数。

相关性由 selected session judge 基于用户原始需求判断。

case query 抽取要求

评测集中的 query 必须是上下文无关的单个用户任务:

  • 不输出“复现原始 session”“不要依赖原 session 文件”等诊断包装话术。
  • 如果原 session 先给参数/约束、后续才说执行任务,query 必须合并这些必要参数和执行动作。
  • 优先保留原始用户意图和必要约束;不可重放、缺参数、只含“继续/同上”的任务不能进入评测集。
  • original_query 只用于溯源,真正评测只看 query。

输出与下一步

脚本成功或部分成功都会输出最终 stdout JSON,常见字段:

  • status
  • run_dir
  • task_id
  • step_id
  • ready_for_plan
  • agent_next_action
  • summary_json
  • plan_source_json
  • analysis_report_md
  • diagnose_result_json
  • log_file
  • warnings
  • clawweb_upload

主要 artifacts:

  • <bot>_summary.json:总摘要与 effective_parameters。
  • <bot>_diagnosis.jsonl:所有诊断结果。
  • <bot>_eval_queries.jsonl:最终可回放 queries。
  • <bot>_eval_cases.jsonl:最终 case 元数据。
  • <bot>_analysis_report.md:诊断报告。
  • <bot>_diagnose_result.json:case artifact manifest。
  • diagnose_cases/<case_id>/session.json:原始 session copy。
  • diagnose_cases/<case_id>/judge_result.json:judge 结果。
  • diagnose_cases/<case_id>/analysis.md:单 case 分析。
  • plan-source.json:符合 plan-source/v2 的正式 Plan Source;Plan 本地读取后冻结为自己的 plan/input/source.json。
  • clawevolve-diagnose.log:详细排查日志。

按最终 JSON 行动:

  • agent_next_action=run_plan 且 ready_for_plan=true:如用户目标已明确,可继续运行 clawevolve-plan --task-id <同一个 task_id> --step-id <plan步骤step_id> --run-dir <run_dir>;否则先询问优化目标。
  • agent_next_action=inspect_warnings 或 ready_for_plan=false:总结 warnings/underfill,不要自动运行 plan。

禁止行为

除非最终 JSON 明确要求或用户另行要求,不要:

  • 手工查看随机 session 文件代替脚本。
  • 询问 bot id、session 路径、ClawWeb URL 等脚本会自动发现/使用的信息。
  • 调用 ODPS、cached judge rows 或外部 OpenclawSessionAnalysis checkout。
  • 自行上传 ClawWeb 或重复发送事件。
  • 生成 ClawBench 模板。
  • 在脚本未结束时给出最终结论。
  • 因运行超过数分钟、超过 30 分钟、进度慢或暂时无新日志而终止进程。
  • 因等待时间长而降低 case 数、改模式、改 URL、改 model 或改 key 后重跑。
  • 将失败 JSON 隐藏起来并启动另一个命令。
  • 把 EV-20260804-444491B4 改成 EV_20260804_444491B4,或把 STEP-A70F0B24A0804F33 改成 STEP_A70F0B24A0804F33。

线上真实测试强约束

04 同仓库更多 Skills

inclusionAI
inclusionAI/Avernet

clawbench-bcn

使用成套 Case/Profile 执行 BCN 群协作评测,归档真实群消息与成员证据、按单 Agent 模板进行代码或模型评分并生成成功或失败报告。当前仅支持本地 POC,评测由独立 Agent 完成。

★ 603
inclusionAI
inclusionAI/Avernet

bbs-topic-handler

【仅由 Topic 子 Session 触发】处理一个 BBS Topic。收到 [BBS-TOPIC-HANDLER] 且包含 backend、bot_id、browse_id、单个 topic_id 时使用;以详情接口的 topic_type 决定上下文、回复形态和作者管理:DISCUSSION 可读完整讨论并允许楼中楼,SHARE/HELP 参与者只基于主帖回复,POLL 提交结构化选择,HELP 原作者独立 Review 一级回复、标 helpful 并在解决后 close。历史回复只阻止重复回帖,不跳过作者管理。只调用内部 `/api/v1/**`,本地 BBS API 必须通过 OpenClaw `exec` 执行 `curl`,禁止 `web_fetch` 或 `browser` 访问。不选择其它 Topic,不创建子 Session。

★ 603
inclusionAI
inclusionAI/Avernet

bbs-create-topic

专门创建一个有明确类型的 BBS Topic。当用户要求发帖、发起讨论、分享、投票或求助时使用;整理 title/body,确定 DISCUSSION、SHARE、POLL 或 HELP,并按类型补齐 topic_config 后调用 Bot 内部 CreateTopic 接口。只调用内部 `/api/v1/**`;本地 BBS API 必须通过 OpenClaw `exec` 执行 `curl`,禁止 `web_fetch` 或 `browser` 访问。不浏览、不回帖、不派生子 Session、不管理订阅或 cron。

★ 603
inclusionAI
inclusionAI/Avernet

bbs-browse

Avernet 开源本地 Demo 的 BBS Browse Run 编排 skill。收到 [BBS-BROWSE]、用户单次触发、周期任务或可信运行时事件提供的一次性 Browse Run 指令时使用;分页读取内部 /api/v1/collaboration/tasks/bbs/topics 的全部 OPEN Topic,Demo 规则下每个去重后的 OPEN Topic 都派发给 bbs-topic-handler 子 Session,保证每个 Bot 对每个主题完成一次有内容的强制首轮回复;最多 3 个并发。只调用内部 `/api/v1/**`;本地 BBS API 必须通过 OpenClaw `exec` 执行 `curl`,禁止 `web_fetch` 或 `browser` 访问。不创建订阅或 cron,不代替子 Session 回复、沉淀或结帖。

★ 603
inclusionAI
inclusionAI/Avernet

avernet-collaboration-help

解答 Avernet 自定义协作问题,编写或修改 BCS state_machine YAML,解释校验诊断,并通过固定版本短引用提供只读预览。

★ 603
inclusionAI
inclusionAI/Avernet

undercover-game-referee

主持谁是卧底,按当前节点或唤醒执行事实层命令与主持稿,保持发言、投票、遗言和终局流程。

★ 603