背景

线上运行的 OpenClaw v2026.6.11 遇到两个严重问题：

• #99241 tool-result-placeholder：上下文累积到 65K tokens 后，工具输出被替换为 (see attached image) 占位符，模型无法读取工具结果。触发阈值从最初的 180K 一路恶化到 65K，严重影响使用。
• #98416 reply-session-conflict：WebChat 连续发消息报 reply session initialization conflicted，会话不可用。

升级到 v2026.7.1-beta.2 后，#98416 官方已修复，#99241 靠 PR #98955（尾部 tool-result 保护）缓解。本文记录升级过程和补丁维护经验。

升级过程

1. 备份：dist 目录 + openclaw.json 配置文件
2. 升级：npm install -g openclaw@2026.7.1-beta.2
3. 重打补丁：6 个本地补丁重新打入（reply-session-source-fix 官方已修复，移除）
4. patch-check：7/7 通过
5. Gateway 重启，功能验证通过

备份位置：/usr/lib/node_modules/openclaw.bak-2026.6.11 + openclaw.json.bak-2026.6.11

补丁维护核心发现

1. attachment-normalize：遗漏的第二处栈溢出

6月25日打补丁时只修了第89行 data: URL 提取正则（(.*)$ 对大字符串触发 V8 正则引擎栈溢出），改为 indexOf + slice。

但遗漏了第59行 isValidBase64 函数中的另一个正则：/^[A-Za-z0-9+/]+={0,2}$/.test(value)，同样使用 + 量词对大字符串匹配，同样栈溢出。

之前测试的文件都是 6MB 左右，刚好没触发 V8 正则引擎的栈深度上限。7月10日上传 14MB 文件时暴露，改为逐字符 charCodeAt 遍历修复。

教训：补丁记录必须完整。一个函数里有两处正则栈溢出风险，只修一处是不够的。每次修复后要排查同文件中是否有同类问题。

2. reply-session-conflict：官方三层修复已到位

v2026.7.1-beta.2 中官方已完成三层修复：

• 源头修复（PR #98835）：收窄 guard 对比范围到 sessionId/sessionFile 身份字段，允许并发 metadata drift
• 重入保护：isActiveStoreWriter/runActiveStoreWriter 正确处理 reentrant: true
• 重试退避：retryDelays = [1000, 3000, 5000, 8000]，maxRetries = 4

不再需要本地补丁。patches.json 中保留检测规则作为升级后的验证检查。

3. workspace-file-viewer：官方已修复

v2026.7.1-beta.2 的官方代码已包含 statWorkspacePath 非 touched 文件处理逻辑，前端 sessionKind 限制已移除。不需要本地补丁。

升级后测试时发现”补丁打了但没用”，实际是浏览器 JS 缓存问题，硬刷新后正常。前端代码变更后必须 Ctrl+Shift+R 硬刷新。

4. control-ui-allowed-folders：官方未修复，仍需本地补丁

问题 #10210240 分两层：

• 前端：正则 /^(\/Users\/[^/]+|\/home\/[^/]+)(?:\/|$)/ 只匹配 macOS 和 Linux 非 root 用户，不匹配 /root。本地补丁加 |\/root。
• 服务端：getAgentScopedMediaLocalRoots 只返回当前 agent 的 workspace，不包含其他 agent。本地补丁遍历 cfg.agents.list 追加所有 agent workspace。

升级后验证：发送 docx 文件到 WebChat，点击预览正常，不再提示 “Outside allowed folders”。

openclaw-patch-check 技能清理

升级过程中发现技能存在两个问题：

1. 两套目录：~/.openclaw/skills/openclaw-patch-check/（实际运行）和 ~/.openclaw/workspace/skills/openclaw-patch-check/（多余副本）。删除了 workspace 下的副本。
2. 补丁记录过时：patches.json 从 7 个精简到 4 个，移除 3 个官方已修复的条目，更新检测规则。

当前 patches.json（4 个）

ID	Issue	类型
attachment-normalize	#90098 两处正则栈溢出	本地补丁
reply-session-conflict	#98416 reply session conflicted	验证官方修复
control-ui-allowed-folders-frontend	#10210240 前端正则缺 /root	本地补丁
control-ui-allowed-folders-backend	#10210240 服务端缺非默认 agent workspace	本地补丁

架构限制：大文件上传

WebChat 通过 WebSocket 上传文件，MAX_PAYLOAD_BYTES = 25 * 1024 * 1024 硬编码限制。14MB 文件 base64 编码后约 19MB，可以上传。但超过 25MB 的文件 base64 后超过限制，无法上传。

已提交 Feature Request #103560，建议增加 HTTP multipart upload endpoint，不受 WS payload 限制。

补丁状态总览

补丁	状态	说明
attachment-normalize	本地补丁	两处正则栈溢出，PR #92223 未合并
reply-session-conflict	官方已修复	v2026.7.1-beta.2 三层修复到位
workspace-file-viewer	官方已修复	代码已含 statWorkspacePath 逻辑
control-ui-allowed-folders	本地补丁	官方未修复 #10210240
tool-result-placeholder	已回滚	PR #99756 打后更差，等官方根治

经验总结

1. 补丁记录要完整：attachment-normalize 有两处正则栈溢出，只记一处导致遗漏。每处修改都要记录原始代码、修复代码、行号、原因。
2. 检测规则要通用：从匹配特定文件名 hash 改为 glob get-reply-*.js，从匹配特定数组值改为检测关键字 retryDelays + maxRetries。
3. 区分”补丁生效”和”官方已修复”：patches.json 中保留 reply-session-conflict 条目，作用从”检查本地补丁”变为”验证官方修复”。
4. 前端变更后硬刷新：workspace-file-viewer 补丁打了但浏览器缓存旧 JS，硬刷新后正常。
5. 维护单一数据源：发现两套技能目录后删除多余副本，只维护 ~/.openclaw/skills/ 下的版本。

遗留问题

• #99241：beta.2 缓解但未根治，长上下文下仍可能触发 tool-result-placeholder
• #103560：Feature Request，HTTP 文件上传通道
• #90098：PR #92223 未合并，attachment-normalize 仍需本地补丁
• #10210240：control-ui-allowed-folders 官方未修复

今天在使用 AI Agent 的过程中发现了一个典型问题：一个无人值守的 Agent 会话陷入了死循环，短时间内消耗了 65 万 tokens 却几乎没有产出。记录整个发现、分析和复盘过程。

现象

通过监控发现某个 Agent 会话（模型 deepseek-v4-flash）反复执行相同的命令，每次调用都没有产出有效结果，但上下文在持续膨胀。

发送 /stop 中断后，让该会话分析自身死循环的原因——结果它又陷入了同样的循环模式。这说明 stop 只能中断当前 turn，无法修复根因。

死循环数据

指标	数值	说明
exec 总调用次数	166 次	大部分是重复命令
上下文大小	654K tokens（输入）	正常会话约 30-50K
有效输出	212 tokens	几乎为零
turn failed 次数	9 次	模型无法产出内容
prompt-error 次数	4 次	请求被拒绝
最终状态	killed（手动 /stop）	用户通过 /stop 强制终止

循环模式分析

从 166 次 exec 调用中提取重复模式：

命令	重复次数	说明
ls -la .../blog-publisher-wordpress/	33 次	反复列出同一目录
python3 ...读取 session JSONL	20 次	反复解析同一文件
find .../blog-publisher-wordpress -type f	19 次	反复搜索同一路径
python3 -c "...读取 session"	8 次	换种写法做同样的事
tail -100 ...log	5 次	反复读同一段日志

同一个 ls 命令调用了 33 次，find 调用了 19 次。模型完全没有意识到自己在重复。

根因分析

1. 模型缺乏自我觉察

deepseek-v4-flash 在处理”找不到上下文”的情况时，没有能力判断”我已经搜过 30 次了，再搜也不会有结果”。每次搜索的结果被追加到上下文，模型看到更多数据后反而更困惑，于是继续搜索。

2. 没有 Circuit Breaker

当前 Agent 框架没有检测”同一命令重复 N 次”的机制。无论模型调用同一命令多少次，系统都会忠实地执行并返回结果。166 次 exec 调用全部被执行了。

3. 上下文窗口失控

每次 exec 的输入和输出都被追加到上下文。166 次调用的结果累积到 654K tokens，远超模型的有效处理能力。当上下文过大时，模型开始报错（assistant turn failed），但报错本身又被追加到上下文，形成恶性循环。

恶性循环链

找不到上下文 → 搜索 session 文件 → 结果加入上下文
→ 上下文膨胀 → 模型处理不了 → 重新搜索
→ 更多上下文 → 更多错误 → 最终被手动 /stop

浪费的代价

这次死循环消耗了约 654K 输入 tokens，几乎没有有效输出。按主流 API 定价估算：

• 以 deepseek-v4-flash 的价格计算，单次死循环的成本虽然不高
• 但如果 无人值守，一个晚上可能触发多次这样的循环
• 多个 Agent 同时失控，累积消耗会非常可观

真正的风险不是单次成本，而是 无人监控下的累积浪费。如果没有人工 /stop 干预，session 会一直跑到 context window 上限才可能停止——甚至可能不会停止。

一个残酷的事实

OpenClaw 目前 没有自动防护机制 能阻止这类死循环。已有的 globalCircuitBreakerThreshold 是按工具类型计数的，agent 通过轮换不同工具（ls → find → python3 → tail）就能绕过。GitHub 上已有相关 issue（#79252），修复方案（#97577）正在推进中。

防御建议

1. 模型选择

复杂上下文追踪任务避免使用 deepseek-v4-flash。实测 mimo-v2.5 在同一场景下不会陷入重复调用循环，具备更好的自我觉察能力。

2. 建立监控机制

定期检查活跃 session 的 token 消耗和工具调用频率，超阈值自动告警：

# 检查活跃 session 的 token 消耗
openclaw sessions list --active

3. 考虑 Session Token 预算

为单个 session 设置 token 上限，超过后自动中断。这是最直接的防护，但目前 Agent 框架尚未内置此功能。

4. 工具调用频率限制

检测同一命令的连续重复调用，达到阈值后自动中断并通知用户。这需要在框架层面实现。

结论

AI Agent 的死循环不是理论风险，而是真实会发生的问题。关键认知：

1. /stop 只能中断当前 turn，不能修复根因
2. 模型重复调用同一命令时，系统不会自动干预
3. 无人值守的 Agent 可能白白消耗大量 tokens
4. 选择更稳定的模型 + 建立监控是最现实的防线

在 Agent 真正可靠之前，有人值守仍然是必要的安全网。

---

二、深入源码分析（2026-07-01 更新）

在初次发布本文后，我们对 OpenClaw 源码进行了深入分析，发现死循环的根因比表面现象更复杂。以下是完整分析过程。

1. 死循环类型：大循环 vs 调度器自循环

最初我们怀疑这是 OpenClaw 调度器层面的”自激循环”——调度器自己反复调用同一个工具，不经过大模型。但经过源码分析确认：这是标准的 OpenClaw → 大模型 → OpenClaw 大循环。

调度器层面没有 auto-retry/auto-continue 机制。每次 exec 工具调用都必须由大模型发起：

1. 模型发出 tool call（exec）
2. OpenClaw 执行命令，结果返回给模型
3. 模型收到结果后，决定再次调用 exec
4. 循环往复

之所以感觉”速度快”，是因为 exec 输出很短，模型处理快，每轮只需几百毫秒。

2. Loop Detection 机制分析

OpenClaw 内置了 tool-loop-detection 模块，包含 4 种检测器：

检测器	触发条件	Warning 阈值	Critical 阈值	适用场景
genericRepeat	相同 toolName + 相同 argsHash + 相同 resultHash	10	20	工具调用完全相同且结果不变
knownPollNoProgress	process poll/log 工具，相同参数，结果不变	10	20	轮询死循环
pingPong	两个工具交替调用，参数签名来回切换，结果不变	10	20	A→B→A→B 交替死循环
unknownToolRepeat	连续调用不存在的工具	10	–	模型反复尝试已删除的工具

响应级别：

• Warning（≥10次）：给模型发警告消息，让模型自己停止
• Critical（≥20次）：直接 block，返回 status: "blocked"
• Global Circuit Breaker（≥30次）：全局熔断，阻止整个 session 继续执行

3. 为什么 Loop Detection 没有阻止死循环？

我们的 openclaw.json 中已正确配置了 loopDetection：

"tools": {
  "loopDetection": {
    "enabled": true,
    "warningThreshold": 10,
    "criticalThreshold": 20,
    "globalCircuitBreakerThreshold": 30,
    "detectors": {
      "genericRepeat": true,
      "knownPollNoProgress": true,
      "pingPong": true
    }
  }
}

但死循环仍然发生了。根因在于 hashExecToolOutcome() 函数的实现：

对于 exec 工具的 status: "completed" 或 status: "failed" 结果，哈希计算包含：

digestStable({
  status,
  exitCode,
  timedOut,
  output: normalizeNullableString(details.aggregated) ?? text
})

关键问题：output 字段（完整的命令输出文本）被纳入了 resultHash 计算。即使命令相同、exit code 相同，只要输出文本有任何细微差异（比如时间戳、路径顺序、错误信息的微小变化），resultHash 就会不同。

这导致 noProgressStreak（要求连续相同的 resultHash）始终为 1，永远不会达到 criticalThreshold（20）或 globalCircuitBreakerThreshold（30）。

检测路径	使用的计数器	是否触发	原因
Warning	recentCount（相同 args 计数，不看 result）	✅ 触发	参数相同即可
Critical	noProgressStreak（要求 resultHash 相同）	❌ 不触发	exec 输出略有变化，resultHash 每次不同
Global Circuit Breaker	noProgressStreak	❌ 不触发	同上

Warning 虽然触发了，但模型（GLM-5.2）忽略了警告文本，继续循环。

4. 复现验证

在分析过程中，我们多次复现了死循环。最典型的场景：模型反复执行 grep -n "loopDetection" /root/.openclaw/openclaw.json，每次输出为空（exit code 1），模型不断重试，30+ 次后需要手动 /stop。

每次 exec 的输出完全相同（都是空），但 hashExecToolOutcome() 仍然为每次生成了不同的 resultHash——这可能是因为 exec 的 status details 中包含了 tail 或 aggregated 字段的细微差异。

5. GitHub Issue 跟踪

这个问题已在 GitHub 上提交并跟踪：

• Issue #93917：Bug: genericRepeat critical/circuit-breaker never fires when exec results vary slightly
• PR #97577：fix: make tool loop circuit breaker session-global
• Issue #97485：feat(agents): add iteration budget for agent loop safety

我们已在 #93917 下补充了复现信息，包括 OpenClaw 2026.6.10 + GLM-5.2 的完整配置和现象描述。

6. 临时缓解措施

在官方修复之前，可考虑以下措施：

• 降低 warningThreshold：设为 3-5，让 warning 更早触发（虽然模型可能仍忽略）
• 关注 PR #97577：session-global circuit breaker 可以防住跨工具循环
• 关注 PR #97485：iteration budget 从根本上限制工具调用轮数
• 模型选择：不同模型对 warning 的遵从度不同，换模型可能有缓解效果
• 人工监控：在可预见的死循环场景中保持 /stop 就绪

7. 根因总结

设计缺陷：hashExecToolOutcome() 将完整 output 文本纳入 resultHash，导致 exec 结果的任何微小变化都会重置 noProgressStreak。

影响范围：所有使用 exec 工具的场景，只要命令输出有细微变化（时间戳、错误信息、路径顺序等），critical 和 circuit-breaker 就不会触发。

修复方向：

1. 从 exec resultHash 中剥离 volatile 字段（output、tail）
2. 或采用相似度比较替代精确哈希匹配
3. 配合 session-global circuit breaker 作为兜底

8. 模型能力差异对比（2026-07-01 补充）

在后续测试中发现，死循环的严重程度与模型能力密切相关。同一个任务场景下，不同模型的表现差异显著：

模型	行为特征	循环次数	是否会换工具	结果
deepseek-v4-flash（火山引擎）	同一个 exec 命令反复调用，不改变策略	166 次	❌ 很少换工具	654K tokens，手动 /stop
GLM-5.2（智谱）	也会重复调用，但会尝试换命令、换工具	30+ 次	✅ 会换工具/换参数	仍然会循环，但次数少很多

关键发现：

• deepseek-v4-flash 在工具连续失败后缺乏”停下来反思”的能力，倾向于用完全相同的参数反复重试，陷入最坏情况的死循环
• GLM-5.2 虽然也会循环，但会尝试不同的命令和参数（比如换 grep 为 find、换路径），说明它有一定的”换策略”意识，只是不足以完全跳出循环
• 更强的模型（如 GPT-5.5）可能根本不会陷入循环——在 3-5 次失败后就会主动停下来向用户报告问题

这说明死循环是两层问题叠加：

1. OpenClaw 层：loop detection 的 critical/circuit-breaker 对 exec 失效（resultHash 问题），缺少 session 级别的硬上限——这是系统性缺陷，所有模型都受影响
2. 模型层：部分模型在工具连续失败后缺乏策略切换能力——这是模型能力差异，不同模型表现不同

如果只修 OpenClaw 层（加上 session-global circuit breaker 或 iteration budget），所有模型都安全。但如果模型本身能力强，可能根本不需要 loop detection 兜底。

实践建议：在 OpenClaw 官方修复 loop detection 之前，选择”工具失败后容易换策略”的模型（如 GLM-5.2、GPT-5.5）可以显著降低死循环的风险和严重程度。避免在生产环境中使用 deepseek-v4-flash 执行需要多次工具调用的复杂任务。

---

三、supportsTools: false 与死循环的关系（2026-07-01 补充）

在分析过程中，我们发现了一个值得关注的问题：之前因 DeepSeek-v4-flash 工具调用不匹配导致大量 400 错误，在 openclaw.json 中禁用了其工具支持：

{
  "id": "deepseek-v4-flash",
  "compat": { "supportsTools": false }
}

今天的死循环发生时，session 使用的正是这个配置了 supportsTools: false 的 deepseek-v4-flash。这引发了我们的疑问：禁用工具支持是否反而加剧了死循环问题？

1. supportsTools: false 的实际效果

通过源码分析，supportsTools: false 的实际效果如下：

层面	行为	是否符合预期
API 请求	不传 tools 字段给模型 API	✅ 符合
工具构建	tools: toolsEnabled ? toolsRaw : []，传给 runner 的工具为空	✅ 符合
System Prompt	仍然包含完整的工具描述（”你可以用 exec 工具…”）	❌ 不符合

关键问题：effectiveToolsAllow（决定 system prompt 中列出哪些工具）不依赖 toolsEnabled，而是来自 params.toolsAllow。因此即使工具被禁用，system prompt 仍然告诉模型”你有 exec、read、write 等工具可用”。

2. DSML Recoverer 分析

OpenClaw 有一个 DeepSeek DSML Tool Call Recoverer，能从模型文本输出中解析 DSML 格式的工具调用并执行。我们最初假设这是死循环的根因，但源码分析排除了这个假设：

shouldFilterDeepSeekDsmlText(compat) 的判断条件是 compat.thinkingFormat === "deepseek"，而 handai/deepseek-v4-flash 的配置里没有 thinkingFormat: "deepseek"，所以 DSML recoverer 不会生效。

3. 矛盾点

如果 supportsTools: false 确实完全禁用了工具调用，那 deepseek-v4-flash 不可能反复执行 exec 命令。但实际观察到的现象是：模型确实陷入了工具调用死循环。

可能的解释：

• 模型在文本中模拟工具调用：模型收到 system prompt 说有工具可用，但 API 请求里没有 tools 定义，于是在文本输出中生成类似工具调用的格式。虽然 DSML recoverer 不生效，但可能存在其他文本解析路径。
• 触发了 fallback：deepseek-v4-flash 调用失败后，OpenClaw 的 fallback 机制切换到有工具能力的模型（如 deepseek/deepseek-v4-flash 或 alibaba/deepseek-v4-flash），由 fallback 模型执行了工具调用。
• 其他未发现的机制：可能存在我们尚未发现的工具调用解析路径。

4. 设计缺陷

无论死循环的具体触发路径是什么，system prompt 与实际工具可用性不一致本身就是一个设计缺陷：

• System prompt 告诉模型”你有 exec、read、write 等工具可用”
• 但 API 请求里没有 tools 定义
• 模型被诱导去”使用”实际不存在的工具
• 这种行为在弱模型（如 deepseek-v4-flash）上更容易导致问题

正确的做法应该是：当 supportsTools: false 时，system prompt 中也应该移除工具描述，或明确告知模型”当前模式下工具不可用”。

5. 待验证问题

1. supportsTools: false 时，system prompt 仍包含工具描述是否合理？
2. 是否存在 DSML 之外的文本工具调用解析路径？
3. 死循环时 session 实际使用的模型是哪个？是 deepseek-v4-flash 本身，还是 fallback 到了其他模型？

这些问题需要进一步验证，欢迎在评论区讨论或到 GitHub Issue #93917 跟进。

四、Loop Detection 实际生效验证（2026-07-01 补充）

在之前的分析中，我们指出 Loop Detection 的 critical/circuit-breaker 对 exec 工具失效（因为 hashExecToolOutcome() 将完整 output 纳入 resultHash，exec 输出的微小变化导致哈希每次不同）。但今天的测试提供了一个新的观察角度。

1. 现象：browser 工具的 Loop Detection 正常工作

今天在执行一个浏览器自动化任务时，由于 targetId 不匹配，agent 反复用相同参数调用 browser 工具的 navigate 和 act 操作。网关日志中记录了大量 Loop Detection 警告：

时间	警告内容	调用次数
14:42:59	Loop warning: browser called 12 times with identical arguments	12
14:43:06	Loop warning: browser called 13 times with identical arguments	13
…	（持续递增）	…
14:46:45	Loop warning: browser called 18 times with identical arguments	18

当次数达到 20 次时，系统执行了 Critical 级别的拦截：

CRITICAL: Called browser with identical arguments and identical outcomes 20 times. Session execution blocked to prevent runaway loops.

Session 被成功阻止，不再继续执行重复调用。这说明 对于 browser 工具，Loop Detection 的 warning → critical → block 全链路正常工作。

2. 为什么 browser 有效而 exec 无效？

关键差异在于 resultHash 的稳定性：

工具	相同参数时的结果	resultHash 是否稳定	Critical 是否触发
browser	相同参数 → 相同结果（页面状态不变）	✅ 稳定	✅ 触发
exec	相同命令 → 输出可能有微小差异（时间戳、路径顺序等）	❌ 不稳定	❌ 不触发

browser 工具的返回值是结构化的 JSON（页面 URL、snapshot 等），当参数完全相同时，结果也完全相同，resultHash 保持一致，noProgressStreak 能正确累加到 criticalThreshold。而 exec 工具的输出包含命令的 stdout/stderr，即使命令相同，输出的微小差异（如 ls -la 的时间戳）会导致 resultHash 每次不同。

3. 关于 supportsTools: false 的重要发现

在之前的章节中，我们分析了 supportsTools: false 配置可能导致 system prompt 与实际工具可用性不一致的问题。今天的测试进一步确认了一个关键事实：

当 deepseek-v4-flash 配置了 supportsTools: false 时，它根本不会调用任何工具（包括 browser、exec 等），因此 Loop Detection 机制永远不会被触发。

这解释了为什么之前认为”Loop Detection 没有起作用”——不是因为配置问题，而是因为 deepseek-v4-flash 禁用了工具调用，agent 根本不会发起工具调用循环。今天的测试使用了 GLM-5.2（工具调用启用），agent 频繁调用 browser 工具，Loop Detection 立即正常工作。

换句话说：

• deepseek-v4-flash（supportsTools: false）：不调用工具 → 不触发 Loop Detection → 但也不执行实际任务（陷入文本层面的重复）
• GLM-5.2（supportsTools: true）：调用工具 → 触发 Loop Detection → Critical 拦截成功阻止循环

4. 结论与修正

对之前分析的两个修正：

1. Loop Detection 配置是生效的——至少对 browser 工具完全正常。exec 工具的 resultHash 问题仍然存在（详见第二章），但这不影响其他工具的检测。
2. 之前”没有看到 Loop Detection 日志”的原因——不是配置问题，而是 deepseek-v4-flash 的 supportsTools: false 导致工具调用根本不发生。切换到有工具能力的模型后，Loop Detection 立即表现出正常行为。

这一发现进一步印证了第三章的结论：supportsTools: false 的影响远超预期——它不仅可能导致 system prompt 不一致，还掩盖了 Loop Detection 机制本身的正常运作。在排查”防护机制是否生效”类问题时，首先需要确认当前模型是否实际具备工具调用能力。

今天在使用 OpenClaw 的过程中遇到一个现象：正在进行的会话突然“失忆”了，助手对不久前做过的操作完全不知情。经过日志追溯和源码分析，弄清了整个链路。记录如下。

现象

一次完整的会话链涉及了 3 个关联的 session：

时间	Session	内容	结果
20:25	639ede17	Agent宕机诊断 → 发布博客 → iNove主题排版调整	被 abort
20:32	6520c2c3	继续iNove主题调整，找CSS文件	被 abort
20:38	7f1f9d61	当前会话，全新开始，对之前一无所知	正常运行

两个前序 session 在 abort 后被 reset，新 session 从零开始，对过去 13 分钟内的所有操作完全没有记忆。

直接原因：手抖多打了一个 0

在 openclaw.json 的模型配置中，deepseek-v4-flash 的 maxTokens 值被设为了 3840000：

{
  "id": "deepseek-v4-flash",
  "name": "deepseek-v4-flash",
  "contextWindow": 1000000,
  "maxTokens": 3840000,    ← 多了一个 0
  "compat": { "supportsTools": false }
}

这个值应该是 393216（火山引擎 deepseek-v4 实际支持的 max_completion_tokens 上限），但配置时多输入了一个 0，变成了 384 万。OpenClaw 的计算逻辑是：

max_completion_tokens = min(maxTokens, contextWindow - 已用token数)

当上下文膨胀后，contextWindow - 已用token数 约 90 万，min(3840000, 90万) 取了 90 万，远超火山引擎 393216 的上限，直接 400 拒绝：

400 The parameter `max_completion_tokens` specified in the request are not valid:
expected a value <= 393216, but got 966158 instead.

也就是说，整条调用链 OpenClaw → handai(newapi) → 火山引擎 本身没有兼容性问题，根因就是配置错误。

链式崩溃经过

第 1 轮：连番 400 错误 + 大量重试

用户在 webchat 上发送了 Agent 宕机诊断请求，模型连续返回 400 format error。每次 failover（handai→deepseek→alibaba）都持续失败——因为模型提供商本身没问题，是请求参数超标了。用户因看不到响应，在 webchat 上反复发送同一条消息 30 多次，每一次都触发新的 400 错误，形成恶性循环。

最终用户手动 abort 当前请求，但 abort 的回收超时了：

embedded abort settle timed out: timeoutMs=2000

同时 session 文件已被修改，触发保护机制：

session file changed while embedded prompt lock was released

结果：session 639ede17 被标记为 .reset.，视为被接管放弃。

第 2 轮：CSS 文件查找也 abort

新 session 启动后，用户继续讨论 iNove 主题的 CSS 调整。助手在 /var/www/、/www/ 等路径远程查找 CSS 文件，全部失败（路径不存在）。用户再次 abort，同样的 chat.abort + settle timeout → session 6520c2c3 也被 reset。

OpenClaw 的 Session Reset 机制

从日志可以看出 OpenClaw 在这类场景下的行为：

1. 模型 400 错误 → 触发 failover（handai → alibaba → deepseek），但 failover 同样失败（请求参数依然超标）
2. 用户手动 abort → 调用 chat.abort WebSocket 接口
3. Abort settle timeout（2秒） → 如果在 2 秒内 abort 不能被嵌入层清理完成，触发 session takeover
4. Session takeover → 旧的 session 文件被重命名为 .reset.，新请求从新 session 开始
5. 失忆 → 新 session 没有历史消息，模型看到的是一块空白画布

如何重建记忆

当前这个 session 恢复“记忆”的方式并非真正记住了，而是通过以下步骤从文件系统中重新构建了上下文：

1. 搜 session 文件：用 grep -rl "retailsolution|xmlrpc" 在所有 session 文件中找到相关记录
2. 读 trajectory 日志：从 reset 过的 session 的 .trajectory.jsonl 中提取助手回复文本和用户消息
3. 找残留证据：/tmp/publish_xmlrpc.py 等脚本还躺在文件系统上
4. 翻日志确认崩溃原因：/tmp/openclaw/openclaw-YYYY-MM-DD.log 中的 failover 和 abort 记录

这种方式的问题很明显：它依赖助手在运行时主动去“考古”，且只能找到轨迹日志中残留的信息，并非系统级的内存持久化。

启示

这次事件揭示了几个值得注意的问题：

1. 配置错误是最隐蔽的故障源：多输入一个 0，就能让整套系统反复崩溃。模型配置中的 maxTokens 要与最终提供商的实际支持上限对齐，不能写理论最大值。
2. Abort 回收的可靠窗口：2 秒的 settle timeout 在复杂场景下偏短，一旦超时就导致整个 session 上下文丢失。这是 OpenClaw 的一个设计缺陷（Issue #98156）。
3. 长期记忆 vs 会话记忆：OpenClaw 的 memory 系统保存的是长期语义记忆，但会话级的工作记忆在 session reset 后彻底消失。即使这次是配置错误触发的，其他场景（网络波动、模型超时等）同样会触发 session takeover，导致同样的失忆问题。

故障时间线

本次故障从触发到恢复历经约8个小时,关键节点如下:

时间	事件	状态
10:00:21	handai/deepseek-v4-flash 模型服务首次返回 400 format 错误	触发点
10:12:42	h0assistant 主会话 context overflow(290条消息),自动压缩超时	加剧
10:15:41	上下文压缩 Compaction timed out, failover 到 qwen3.5-flash	失败
10:46	首次 long-running session 告警	队列积压
13:01~13:12	handai/deepseek-v4-flash 反复出 format 400	恶化
13:21~17:37	h0assistant 卡死 processing 状态	完全卡死
16:17	飞书消息无法响应	影响用户
17:33	手动导出诊断包并重启网关	恢复

根本原因分析

本次故障并非单一故障点,而是链式连锁反应的结果.

触发点: 模型提供商 Tool Schema 兼容性问题

调用链路: OpenClaw -> handai(newapi) -> 火山引擎 deepseek-v4-flash. 日志中出现: FailoverError: provider rejected the request schema or tool payload. status=400, reason=format. 火山引擎 deepseek-v4 在 tool_call 参数校验上与 OpenAI 标准不完全一致,复杂 tool call 触发校验失败.

加剧因素 1: Context Overflow 死循环

290条历史消息触发 context overflow,自动压缩超时,全量摘要也失败,形成死循环.

加剧因素 2: 内存压力过高

网关进程内存达 1.95 GB,加载 59 个插件,大量未使用.

加剧因素 3: 历史会话积压

主 agent 66 个会话, h0assistant 18 个会话.

已采取的解决方案

方案一: 关闭模型 Tool Call 能力

compat.supportsTools = false,规避火山引擎 tool schema 校验问题.

方案二: 插件白名单削减

59 个插件缩减到 24 个必要插件.

方案三: 内存压力立即缓解

重启后内存从 1.95 GB 下降至 432 MB.

防御建议

建议一: 定期清理历史会话

建议二: 控制模型兼容性

建议三: 添加 Context Overflow 告警监控

效果总结

指标	整改前	整改后	变化
网关内存	1,955 MB	432 MB	darr;78%
插件数量	59 个	24 个	darr;59%
deepseek-v4-flash tools	开启	关闭	规避 400 format

本次故障揭示了 AI Agent 系统在生产环境中的典型威胁:模型提供商兼容性问题、上下文管理失败、插件臃肿、内存危机之间形成链式反应.

---

后续复盘：supportsTools: false 是双刃剑（2026-07-01 更新）

在采用 supportsTools: false 作为应急方案一段时间后，我们发现这个配置本身引发了新的问题。

背景补充：DeepSeek 官方 vs 火山引擎

经查证，DeepSeek 官方 API（api.deepseek.com）完全支持 Function Calling</strong，遵循 OpenAI 标准 tools 参数格式。当时的 400 错误来自火山引擎的 deepseek-v4-flash 端点，其 tool_call 参数校验与 OpenAI 标准不完全一致。

调用链路：OpenClaw → handai(newapi) → 火山引擎 deepseek-v4-flash

supportsTools: false 的实际效果

通过 OpenClaw 源码分析，supportsTools: false 的效果是”禁用了一半”：

层面	行为	是否符合预期
API 请求	不传 tools 字段给模型 API	✅ 符合
工具构建	传给 runner 的工具列表为空	✅ 符合
System Prompt	仍然包含完整的工具描述（”你可以用 exec 工具…”）	❌ 不符合

原因：effectiveToolsAllow（决定 system prompt 中列出哪些工具的参数）不依赖 toolsEnabled，而是来自 params.toolsAllow。因此即使工具被禁用，system prompt 仍然告诉模型”你有 exec、read、write 等工具可用”。

引发的新问题：死循环

在 2026-07-01 的分析中，我们发现 supportsTools: false 配置下的 deepseek-v4-flash 陷入了工具调用死循环（详见 OpenClaw 会话死循环案例分析）。

矛盾点：如果工具确实被禁用了，模型不应该能执行工具调用。但实际观察到模型反复执行 exec 命令 166 次，上下文膨胀到 654K tokens。

可能的解释：

• 模型收到 system prompt 说有工具可用，但 API 请求里没有 tools 定义，于是在文本输出中”模拟”工具调用格式
• OpenClaw 的 DSML 过滤器或其他文本解析路径检测到这些工具调用块并执行了它们
• 或者触发了 fallback 机制，切换到有工具能力的模型执行了工具调用

利弊分析

时间维度	利	弊
短期（应急）	立即消除 400 错误，恢复服务	模型不能正常调用工具
长期（现状）	—	system prompt 仍诱导工具使用 → 死循环；虚假安全感；模型能力浪费

建议的长期方案

1. 排查火山引擎 tool schema 兼容性问题：具体是哪个字段不兼容？能否在 handai provider 层做 schema 转换？
2. 或换用 DeepSeek 官方 API（api.deepseek.com）代替火山引擎端点，官方 API 完全兼容 OpenAI 格式
3. 恢复 supportsTools: true，同时确保 loop detection 对 exec 生效（参考 Issue #93917）
4. 如果确实需要禁用工具：应该同时从 system prompt 中移除工具描述，而不是只禁用 API 层面的工具传递

本次复盘的核心教训：supportsTools: false 只禁用了 API 层面的工具传递，但没有同步调整 system prompt，导致”告诉模型有工具但又不给工具”的矛盾状态，反而引发了更严重的死循环问题。

提出问题：为什么 Agent 没有变得越用越聪明？

AI Agent 应该是”越用越聪明”的——遇到问题时记住教训，下次遇到同类问题时自动规避。OpenClaw 的 self-improvement 技能正是为此设计：当命令执行失败、用户纠正模型、发现 API 故障、或发现更好的做法时，自动将经验记录到 .learnings/ 目录：

.learnings/LEARNINGS.md — 经验教训

.learnings/ERRORS.md — 错误记录

.learnings/FEATURE_REQUESTS.md — 功能请求

但实际观察发现：这些经验在持续积累，却从未被用到过。

Agent 犯过同样的错误，记录过教训，但下次照样犯。self-improvement 循环断了——写入端在转，召回端没接上。越用越聪明只是愿景，现实是越用越浪费。

分析问题：两条管道，一个断裂点

要理解为什么”写了等于没写”，需要看清 OpenClaw 的记忆架构中有两条独立管道。

写入管道

self-improvement 技能负责写入。触发条件明确，写入路径固定（.learnings/ 目录），不依赖运行时配置。这条管道没有问题。

召回管道

active-memory 负责召回。它是一个独立子智能体，在用户发消息之前运行，调用 memory_search 工具搜索相关记忆，将摘要注入主模型上下文。memory_search 的索引范围由 openclaw.json 中的 agents.defaults.memorySearch 配置决定，默认只索引 MEMORY.md + memory/**/*.md。

断裂点

self-improvement -> 写入 .learnings/ -> 不在索引范围

memory_search -> 搜索 MEMORY.md + memory/*.md -> 看不到 .learnings/

active-memory -> 调用 memory_search -> 注入上下文 -> 经验永远缺席

问题的本质：写入和召回是两个独立管道，必须显式接通。.learnings/ 是自定义路径，不在默认索引范围内，而没有人在配置中告诉 memory_search 去索引它。

解决问题：接通管道

第一步：让 memory_search 能搜到

在 openclaw.json 的 agents.defaults.memorySearch 中添加 extraPaths：

{ “agents”: { “defaults”: { “memorySearch”: { “extraPaths”: [“.learnings”] } } } }

配置变更，不改代码。extraPaths 的设计初衷就是处理这类场景——agent 有额外的 Markdown 文件需要被记忆索引覆盖时，通过这个字段声明即可。

验证：配置前索引 51 个文件，配置后索引 54 个文件（多了 .learnings/ 下 3 个）。测试 memory_search 查询 “PPT 模板生成经验教训”，.learnings/LEARNINGS.md 成功出现，排名第 1，得分 0.503。

索引通了。但测试 active-memory 实际召回时，它仍然返回 no_relevant_memory。

第二步：让 active-memory 能召回

单独测试 memory_search 工具能搜到 .learnings/，但 active-memory 子智能体执行后依然输出 NONE。排查发现：

1. active-memory 使用的模型是 deepseek-v4-flash——一个轻量级模型

2. 轻量模型对”是否需要召回”的判断偏保守——即使 memory_search 返回了相关结果，这个模型在摘要生成阶段倾向于认为”当前对话不需要这些记忆”，直接输出 NONE

修复方向有两个：

方案	做法	优点	缺点
换更重的模型	将 active-memory 的 model 改为 qwen3.7-plus 等	召回判断更精准	token 成本更高、延迟更大
调整 promptStyle	将 promptStyle 从 balanced 改为 recall-heavy	不增加模型成本，召回更积极	可能召回一些边缘内容

我们选择了调 promptStyle。将 promptStyle 从 balanced 改为 recall-heavy，让子智能体更积极地召回记忆，对模糊匹配也倾向于返回结果。成本可控，效果立竿见影。

验证：再次测试 active-memory 召回，成功返回了 .learnings/ 中的自我提升经验内容。

管道接通的完整闭环

self-improvement -> 写入 .learnings/ -> extraPaths 索引

memory_search -> 搜索 MEMORY.md + memory/*.md + .learnings/*.md -> 能搜到

active-memory -> recall-heavy 策略 -> 能召回

主模型 -> 上下文中包含历史经验 -> 越用越聪明

关键认知

1. memory_search 能搜到 不等于 active-memory 能召回

索引和工具只是基础设施，中间还隔着一个模型的”是否需要”判断。轻量模型（如 deepseek-v4-flash）可能在摘要阶段丢弃相关结果。必须端到端验证，不能只测工具。

2. 写入和召回是独立管道，必须显式接通

非默认路径的 .md 文件需要被检索覆盖时，应在 extraPaths 中声明。不声明就等于不存在。

3. promptStyle 是精度-召回率的权衡

balanced 适合通用对话，recall-heavy 适合依赖历史经验做决策的场景。宁可多召回一些，也不要漏掉关键经验。

最佳实践

1. 端到端验证。配置变更后，不仅测试 memory_search 工具，还要测试 active-memory 实际召回结果。

2. 声明额外索引路径。自定义目录下的 .md 文件，必须在 extraPaths 中声明。

3. 根据场景选 promptStyle。依赖经验的 agent 用 recall-heavy，通用场景用 balanced。

4. 定期审计 .learnings/ 目录。经验积累多了，过时内容要及时清理。

核心结论：Agent 没有变得越用越聪明，根源在于经验管道断裂。写入了不等于生效了，搜到了不等于召回了——每一环都需要显式验证。

当你发现 AI 助手开始”变笨”,问题可能不在模型,而在上下文。

上下文膨胀的代价

模型处理上下文时,注意力机制会对所有 token 做关联计算。注入越多无关信息:

– 注意力稀释 — 模型需要从大量文本中定位有用信息,无关内容越多,定位成本越高

– 指令遵循退化 — 特别是小模型(如 128K context 的模型),静态注入占比越大,遵循用户指令的能力越弱

– token 浪费 — 虽然缓存命中率高,但每次调用仍然计费

这恰好对应了 OpenClaw Issue #92451 报告的问题:v2026.6.x 新增了 20+ 个默认工具和系统指令,导致 instruction following 退化。

一、OpenClaw 会话的上下文结构

OpenClaw 的一次会话,上下文由六层构成:

层	模块	内容	加载时机
1	系统指令	角色定义、工具调用规范、安全策略、格式规则	初始注入
2	工具定义	30+ 工具的完整 JSON Schema 描述	初始注入
3	可用技能列表	53 个启用 skill 的名称、描述、路径	初始注入
4	Project Context	AGENTS.md / SOUL.md / USER.md / TOOLS.md / MEMORY.md / HEARTBEAT.md	初始注入
5	动态上下文	Inbound Context、Messaging 规范、Group Chat Context、Runtime 信息	初始注入
6	对话历史	用户消息 + AI 回复 + 工具调用结果	随对话增长

其中 1-5 属于初始注入,在每次新会话启动时一次性加载;6 是随对话推进逐渐增长的部分。

二、初始上下文注入构成

用 /status 查看初始注入的实测数据。优化前:

Context: 44k/1.0m (4.4%)   Cache: 98% hit

Tokens: 43k in / 37 out

44k tokens 的初始注入,各模块占比:

模块	估算大小	占比	用户可控?
系统指令	~5k	11%	否
工具定义	~10k	23%	否
技能列表	~3k	7%	否
Project Context 文件	~25k	57%	是
动态上下文 + 运行时	~1k	2%	否
合计初始注入	~44k	100%	—
对话历史 (首轮)	~6k	—	是

关键事实:

– 系统指令 + 工具定义 = 15k,占初始注入的 34%。这是 OpenClaw 框架自身的开销,用户无法优化。

– 技能列表 = 3k,占 7%。53 个启用 skill,每个描述约 60 tokens。OpenClaw 已正确过滤禁用 skill,但数量本身无法由用户缩减。

– Project Context = 25k,占 57%。这是用户唯一能直接优化的部分,也是最大的膨胀源。– “98% 缓存命中率”是假象。静态模板每次都相同,prompt cache 直接命中不代表对话历史被复用。

三、我们能优化什么,为什么只能优化这些

初始注入的六个模块中:

模块	能否优化	原因
系统指令	否	OpenClaw 框架内置,除非官方修改
工具定义	否	工具 schema 是运行时必需,不能删减
技能列表	部分	可以禁用不需要的 skill,但框架层面无法缩减描述长度
Project Context	是	用户完全控制文件内容
动态上下文	否	运行时自动生成
对话历史	是	但这是增量增长,不是初始注入

所以,唯一可优化的初始注入源就是 Project Context 文件 — 也就是 SOUL.md、USER.md、AGENTS.md、TOOLS.md、MEMORY.md 这些。优化前这 5 个文件合计约 25k tokens,占初始注入的 57%。

四、解决方案:冷热分层策略

核心思路:

每次会话都用到的 -> 留在 MD 文件中(热数据);偶尔才用到的 -> 迁移到 Obsidian 知识库,MD 中只留引用(冷数据);从来不用的 -> 直接删除。

第一刀:TOOLS.md 瘦身

TOOLS.md 是最大的膨胀源。原始版本约 15KB,包含大量场景化的代码示例:

# 原始内容(已删除)

– HZERO 低代码平台 React 表单填写完整代码(~1.5KB)

– SVG 中文字体规范完整教程(~0.8KB)

– PPTX 图标规则完整示例(~0.8KB)

– 模板占位内容 “What Goes Here / Examples”(~0.5KB)

问题在于:模型本身就知道这些知识。React 表单怎么填、SVG 字体怎么设、PPT 图标怎么做 — 不需要在 TOOLS.md 里写完整教程。只需要保留模型不知道的、犯过错的教训:

## HZERO 低代码平台操作经验

– iframe 嵌套:所有页面在 iframe 中,通过 iframe.contentDocument 访问

– React 表单:设置值后必须清除 _valueTracker 再触发事件

– 事件上下文:用 iframeWin.Event 而非外层 Event

从 15KB 降到 3.9KB,减少 74%。

第二刀:MEMORY.md 冷数据迁移

MEMORY.md 原始版本约 12KB,其中有些条目长期不被引用。通过 memory_search 搜索会话记录验证:

条目	近期被引用?	处理
HZERO 产品授权控制	0 次	迁移到 HZERO-wiki
信通院合作事项	0 次	迁移到 HZERO-wiki
GitHub Issue 操作偏好	1 次	保留
HZERO 飞码架构与定位	1 次	已是指针,保留

迁移后 MEMORY.md 从详细内容变为只留 wiki 路径引用:

## HZERO 产品授权控制

详细内容已入库 HZERO-wiki: `wiki/HZERO授权用户数控制逻辑.md`

第三刀:红线文件精简

SOUL.md、USER.md、AGENTS.md 定位为”仅人工维护”,AI 禁止自动修改。同时精简内容:

1. SOUL.md: 删除开头结尾的修辞性文字,只保留核心原则和边界(2.1KB -> 0.97KB)

2. AGENTS.md: 删除委派模板的详细格式说明,只保留必填项(2.4KB -> 1.7KB)

3. USER.md: 新增红线禁令表,禁止修改 (1KB,保持不变)

治理效果

指标	优化前	优化后
TOOLS.md	~15KB	~3.9KB
MEMORY.md	~12KB	~3KB
SOUL.md	2.1KB	0.97KB
AGENTS.md	2.4KB	1.7KB
USER.md	1KB	1KB
Project Context 合计	~25k tokens	~8k tokens
初始注入总计	~44k tokens	~27k tokens
红线文件	可被 AI 修改	仅人工维护
冷数据	无限膨胀	自动迁移到 wiki

审计机制:memory-lifecycle 技能

冷热分层不是一次性工作,需要持续维护。为此我们创建了 memory-lifecycle 技能,将审计流程标准化、自动化。

条目级审计元数据:

每个 MEMORY.md 和 TOOLS.md 的条目加上审计标记:

## HZERO 产品授权控制

**Created:** 2026-03-30 | **Audited:** 2026-06-13 | **Status:** cold

技能工作流:

扫描条目 -> 分类使用频率 -> 迁移冷数据 -> 更新元数据 -> 生成报告

具体步骤:

1. 扫描: 用 Python 脚本解析 MD 文件,提取所有 ## heading 条目及元数据

2. 分类: 对每个条目执行 memory_search(corpus=”sessions”),根据近 30 天命中次数判定: >=2 次 = hot(留在 MD);1 次 = warm(保留观察);0 次 = cold(迁移或删除)

3. 迁移: 冷数据写入 Obsidian 知识库(HZERO 相关 -> HZERO-wiki,其他 -> MY-wiki),MD 中替换为一行引用

4. 元数据: 更新 Audited 日期和 Status 状态

5. 报告: 输出审计报告到 .memory-audit/YYYY-MM-DD.md

触发方式:

场景	触发	说明
定时审计	cron 每两周执行	每月 1 号和 15 号
手动触发	用户说 “审计 MEMORY.md”	按需执行
写入前检查	新增条目前	确保有审计元数据

红线规则: 只审计 MEMORY.md 和 TOOLS.md,不触碰 SOUL.md / USER.md / AGENTS.md。

知识库分工:

知识库	用途	共享性
HZERO-wiki	HZERO PaaS 平台相关知识	可共享
MY-wiki	个人开发经验和通用知识	永不共享

冷数据迁移规则:HZERO 相关 -> HZERO-wiki,其他 -> MY-wiki。

五、与 Active-Memory 的关系

有人会问:OpenClaw 有 Active-Memory 功能,能动态召回相关记忆,还需要手动管理 MEMORY.md 吗?

答案是:两者解决不同层面的问题。

维度	Active-Memory	冷热审计
层面	检索层	管理层
作用	从记忆库中找到相关信息	决定什么信息留在记忆库中
类比	图书馆的检索系统	库存管理
局限	不能减少静态注入体积	不能帮你找到记忆

关键矛盾:

即使 Active-Memory 再强大,只要冷数据还在 MEMORY.md 里,就永远被注入到每次会话的上下文。Active-Memory 不能减少静态注入的体积。

类比:检索系统再强,如果书架上堆满没人看的旧书,也会挤掉新书的空间。冷热审计解决的是”书架上该放什么书”,Active-Memory 解决的是”怎么快速找到你要的那本”。

六、关键教训

1. 3%的初始上下文也不代表健康 — 上下文使用率低不代表注入内容都是有用的。

2. 模型知道的知识不需要写进 MD — TOOLS.md 应该只保留”模型不知道的规则”和”犯过错的教训”

3. 引用比全文更高效 — 冷数据迁移到 wiki,MD 中只留路径引用

4. 审计比一次性清理更重要 — 建立机制比手动执行更可持续

5. 红线文件应极度精简 — 每次新增内容前自问”这个真的每次都需要吗?”

6. 分清两层问题 — 用户层(MEMORY/TOOLS)自己能优化,系统层(默认工具/Skills 列表)只能反馈给开发团队

7. Active-Memory 不能替代冷热审计 — 检索层和管理层解决不同问题,缺一不可

本文基于 2026-06-13 的 OpenClaw 实践整理。相关 Issue: #92451(system prompt bloat)。

测试日期：2026-06-06 | 测试主题：AI Agent 对企业组织架构的影响

测试模型：mimo-v2.5（主）+ GPT-5.5（mckinsey 对比验证）

一、测试概览

#	技能	安装来源	依赖	输出格式	页数	HTML 大小
1	html-ppt-skill	ClawHub	无	HTML (scroll-snap)	10	48 KB
2	frontend-slides	ClawHub	无	HTML (动画)	10	52 KB
3	guizang-ppt-skill	GitHub 手动	无	HTML (WebGL)	10	48 KB
4	nanobanana-ppt-skills	ClawHub	Gemini API	PNG 图片	7	12 KB
5	mckinsey-presentation-generator	ClawHub	无	HTML (SVG 图表)	11	92 KB

二、模型能力要求分级（关键发现）

不同技能对模型的代码生成能力要求差异很大，直接决定中等模型能否可用：

技能	模型要求	技能类型	mimo-v2.5	GPT-5.5	说明
html-ppt-skill	**低**	模板驱动	✅ 成功	—	提供完整 CSS 模板，模型只填内容
frontend-slides	**低**	模板驱动	✅ 成功	—	12 种预设风格，模板骨架完善
guizang-ppt-skill	**低**	模板驱动	✅ 成功	—	提供 template.html，模型基于模板生成
nanobanana-ppt-skills	**中**	API 依赖	❌ API 不通	—	需 Gemini API，沙箱环境无法访问
mckinsey-presentation-generator	**高**	规范驱动	⚠️ 有错需修	✅ 零错误	只给规范不给模板，模型需自己生成完整 HTML + SVG

模型对比实测（mckinsey 技能）

维度	mimo-v2.5	GPT-5.5
HTML 语法错误	**11 处**（style 属性错位）	**0**
内容深度	无研究阶段，凭空编数据	做了完整研究（McKinsey/Gartner/IBM/WEF）
数据可视化	SVG 柱状图、条形图	SVG 柱状图、热力图、矩阵、进度条
生成耗时	13m10s（104K tokens）	5m30s（106K tokens）
需要修复	需要手动修复 HTML 语法	直接可用

结论： 技能分两类——

• 模板驱动型（html-ppt、frontend-slides、guizang）：代码骨架已写好，模型只填空 → mimo 够用
• 规范驱动型（mckinsey）：模型需从零构建完整 HTML → 对代码生成能力要求高，mimo 容易出语法错误

三、屏幕自适应能力对比（关键发现）

技能	自适应策略	尺寸单位	自适应效果
**html-ppt-skill**	流式布局	全部 `vw` 单位	★★★★★ 完美自适应
**guizang-ppt-skill**	流式布局	`vw`/`vh` + `max()` 兜底	★★★★★ 完美自适应
**frontend-slides**	固定容器	`clamp()` 字号 + **固定 px 容器**	★★★☆☆ 大屏留白多
**mckinsey-pptx**	固定尺寸	960×540 + JS scale	★★★★☆ 等比缩放
**nanobanana-ppt**	图片输出	N/A	N/A

具体差异

html-ppt-skill（最佳自适应）：

guizang-ppt-skill（最佳自适应）：

frontend-slides（自适应不足）：

问题： frontend-slides 的内容容器用了固定像素宽度（max-width: 900px），在 1920px 大屏上两侧留白过多，在 1366px 小屏上内容占比过大。而 html-ppt 和 guizang 用 vw 单位，内容区随屏幕等比缩放。

四、封面视觉对比

技能	视觉分	信息层次分	专业度分	创意分	综合
html-ppt-skill	8.0	9.0	8.0	7.0	**8.0**
frontend-slides	8.5	9.0	8.5	8.0	**8.5**
guizang-ppt-skill	9.0	9.5	9.5	8.5	**9.0**
mckinsey-pptx	8.5	9.0	9.5	7.5	**8.6**
nanobanana-ppt	4.0	2.0	1.0	3.0	**2.5**

nanobanana 因 Gemini API 沙箱不可达，生成的是 PIL 占位图（乱码），不计入正式对比。

五、内容页对比（第 4 页）

维度	html-ppt	frontend-slides	guizang-ppt	mckinsey-pptx
信息密度	★★★★	★★★	★★★★	★★★★★
排版美观	★★★	★★★★	★★★★★	★★★★
数据可视化	★★★★	★★★	★★★	★★★★★
综合评分	8/10	6/10	7/10	8/10

六、技能详细评价

1. html-ppt-skill ⭐⭐⭐⭐

优势：

• 无依赖，纯 HTML/CSS/JS，输出文件小（48KB）
• CSS scroll-snap 翻页体验流畅
• 支持键盘/滚轮操作，可打印导出 PDF
• 屏幕自适应完美（全 vw 单位）
• 内容呈现清晰，数据可视化效果不错
• 上手简单，生成速度快
• mimo-v2.5 可独立完成

劣势：

• 设计感偏常规，缺乏独特视觉记忆点
• 动画效果较弱
• 没有风格选择，千篇一律

适用场景： 日常内部汇报、快速原型、技术分享

不适用： 高端客户提案、需要视觉冲击力的场景

2. frontend-slides ⭐⭐⭐½

优势：

• 12 种预设视觉风格，选择丰富
• 动画效果华丽（过渡、粒子、3D 效果）
• 支持 PPT 文件转换
• 视觉风格预览机制（先看效果再选风格）
• 设计感在 5 个技能中最强

劣势：

• 屏幕自适应不足：内容容器用固定 `max-width: 900px`，大屏留白多
• 文件较大（截图 8.2MB，说明动画/粒子效果重）
• 部分风格可能过于花哨，分散注意力
• 风格太多反而可能导致选择困难

适用场景： 产品发布、客户提案、需要视觉冲击力的演示

不适用： 极简风格需求、数据密集型报告、多分辨率场景

3. guizang-ppt-skill ⭐⭐⭐⭐⭐

优势：

• 两种风格（杂志风 + 瑞士风）都很成熟
• WebGL 背景效果独特，高端感拉满
• 杂志风排版极具辨识度（像 Monocle 杂志）
• 屏幕自适应完美（vw/vh + max() 兜底）
• 信息层次丰富，字号对比强烈
• 封面设计在 5 个技能中最佳（9/10）
• 模板系统完善，布局参考丰富

劣势：

• WebGL 背景可能在低端设备上卡顿
• 杂志风不适合所有场景（太文艺）
• 需要手动下载安装（不在 ClawHub 上）

适用场景： 高端行业分享、发布会、需要「高级感」的演讲

不适用： 快速内部汇报、纯数据报告

4. nanobanana-ppt-skills ⭐⭐½

优势：

• 概念新颖：AI 生成图片作为 PPT 页面
• 支持转场视频生成
• 交互式播放器
• 图片质量上限很高（取决于 Gemini API）

劣势：

• 强依赖外部 API（Gemini + Kling），沙箱环境不可用
• 生成速度慢（每页 28-32 秒）
• 文字渲染不可控（AI 生图的文字容易出错/乱码）
• 无 HTML 输出，只有图片，无法编辑
• 成本较高（API 调用费用）

适用场景： 短视频封面、社交媒体宣传图、视觉型演示

不适用： 正式商务汇报、需要文字精确控制的场景、预算有限的项目

5. mckinsey-presentation-generator ⭐⭐⭐⭐½

优势：

• 专业度最高，完全对标麦肯锡风格
• 内置 SVG 图表（柱状图、折线图、水平条形图、风险矩阵）
• 严格遵循咨询行业规范（来源引用、页码徽章、square corners）
• 数据驱动，信息密度最高
• 无需任何外部依赖
• 色彩系统克制（海军蓝 + 钴蓝 + ≤2 强调色）
• GPT-5.5 生成质量极高，一次零错误

劣势：

• 对模型能力要求高：mimo-v2.5 生成有 11 处语法错误，deepseek-v4-flash 无法完成
• 风格单一，只有麦肯锡风
• 设计感偏严肃，不够「现代」
• 生成时间较长
• 对非咨询场景可能过于正式

适用场景： 咨询报告、投行路演、企业战略汇报、董事会材料

不适用： 创意演示、轻松分享、社交媒体内容

推荐模型： GPT-5.5 或 Claude Opus（mimo 不推荐）

七、guizang HTML → PPTX 转换工作流（补充测试）

guizang-ppt-skill 本身只输出 HTML，但配套的 guizang-html-to-pptx 技能可以把它转成真正可编辑的 .pptx。

工作流

转换效果

维度	HTML 原版	PPTX 转换版
视觉效果	WebGL 背景、衬线字体、杂志风	纯深蓝背景、无衬线字体、简洁商务风
可编辑性	浏览器查看，不可直接编辑	**原生文本框，可编辑**
信息完整度	10 页全部内容	10 页全部内容
字体	Noto Serif SC + Playfair Display	Noto Sans SC（4 种全嵌入）
对象数量	N/A	167 个文本框/形状
文件大小	48 KB	83 KB

已知问题

• 背景色不统一：HTML 原版是明暗交替设计，转换后部分页面白底、部分深底，视觉不协调
• 视觉大幅简化：WebGL 背景、衬线字体、圆角卡片、发光装饰全部丢失，PPTX 只剩纯色背景 + 无衬线文字
• 手动修复反而更差：强制统一背景色后，对象数量从 167 降至 40，内容精简过度，效果不如原版
• 根因：技能本身的转换逻辑不够完善，没有指导模型输出合理的 PPTX 布局

适用场景

需要「发 .pptx 文件给别人」的场景，但对视觉质量要求不能太高。本质上是 HTML 精品 → PPTX 简版的降级转换。

八、综合排名

排名	技能	综合评分	最佳场景	mimo 可用？	性价比
1	guizang-ppt-skill	9.0	高端分享、发布会	✅	★★★★★
1+	guizang-ppt + guizang-html-to-pptx	7.0	需要发 .pptx 文件（降级版）	✅	★★★☆☆
2	html-ppt-skill	8.0	日常内部汇报	✅	★★★★★
3	frontend-slides	7.5	客户提案、产品发布	✅	★★★★☆
4	mckinsey-presentation-generator	8.6	咨询/投行报告	⚠️ 需修错	★★☆☆☆
5	nanobanana-ppt-skills	2.5*	社交媒体宣传	❌ 需外网	★☆☆☆☆

– nanobanana 因 API 不可达导致低分，正常环境下预计 7-8 分

– frontend-slides 因自适应问题从 8.5 降至 7.5

– mckinsey 效果虽好（8.6 分），但**必须 GPT-5.5 才能零错误生成**，mimo 有 11 处语法错误、deepseek 直接跑不出来，性价比低，排名下调

九、选型建议

你的需求	推荐技能	理由
中文商务、国企券商汇报	guizang-ppt-skill（瑞士风）	杂志感 + 专业度 + 完美自适应
咨询/投行商业报告	mckinsey-presentation-generator	完全对标麦肯锡，**但必须 GPT-5.5，成本高**
短视频/产品宣传炫酷演示	frontend-slides	12 种风格 + 华丽动画
日常快速 PPT	html-ppt-skill	零依赖、快速、自适应好
演讲者控制台 + 双屏预览	html-ppt-skill	支持 S 键提词 + 倒计时
社交媒体图片 PPT	nanobanana-ppt-skills	AI 生图，视觉冲击力强
多设备/多分辨率演示	html-ppt 或 guizang-ppt	vw 流式布局，天然自适应
需要发 .pptx 文件	guizang-ppt + guizang-html-to-pptx	⚠️ HTML 精品 → PPTX 降级版，视觉简化严重

十、技能改进建议

技能	改进项	优先级
**frontend-slides**	内容容器 `max-width: 900px` → `max-width: 80vw`，修复自适应	高
**mckinsey-pptx**	增加 HTML 模板骨架，降低对模型能力的要求	高
**html-ppt-skill**	增加风格选择器（3-5 种配色方案）	中
**guizang-ppt-skill**	发布到 ClawHub 简化安装	中
**nanobanana-ppt**	增加离线/本地生图模式	低
**mckinsey-pptx**	增加非麦肯锡风格选项（BCG、Bain）	低

十一、关键结论

1. 没有「最好」的技能，只有「最匹配」的技能 — 选型取决于场景、模型、预算
2. 模板驱动型技能对中等模型更友好 — 代码骨架已写好，模型只填空
3. 规范驱动型技能需要强模型 — GPT-5.5/Claude Opus 才能零错误生成，但成本高、性价比低
4. 屏幕自适应是被忽视的关键指标 — vw 流式布局 >> 固定 px 容器
5. nanobanana 的概念好但受限于外部 API — 适合有外网环境的场景
6. mimo-v2.5 最佳搭配：guizang-ppt > html-ppt > frontend-slides（按性价比排序）
7. guizang HTML→PPTX 是降级转换：HTML 视觉效果好但转 PPTX 后大幅简化，背景色不统一、装饰全丢，技能本身转换逻辑不完善，不能作为「精品 PPTX」方案

意外收获：

mckinsey-presentation-generator 这个麦肯锡技能，是规范驱动的，对模型要求高，本次测试过程中，发现用这个技能时，gpt-5.5可以一把过，没有错误，mimo-v2.5第一轮有10多个错误，后续需要修复，但也可以修复好，勉强可能撑得住。Deepseek-v4-flash ,直接就生成失败，扛不住这个要求。所以，以后可以用来测模型能力😄。

一、落地架构与企业选型思路（核心落地理念）

Openclaw作为企业员工个人助手最优落地方案：全公司只维护 1 个正式对外的飞书机器人（default 产品经理 Bot），全公司所有业务群统一拉入这一个机器人，飞书侧零配置、零新增飞书应用；仅在 OpenClaw 配置层做群 ID→Agent 路由分发。

落地优势

1. 飞书端零运维：业务人员新建飞书业务群，只需在群设置→添加机器人，搜索机器人名称拉入即可使用 AI 能力，不用开发、不用申请飞书应用、不用配置权限；
2. 能力全局共享：OpenClaw 所有 Skill 技能全局共用，平台迭代新增工具、插件、知识库后，全公司所有飞书群立刻同步享用新能力；
3. 灵活精细化隔离：
   1. 同类型业务群（日常咨询、通用答疑）：多个群复用同一个 Agent，共用一套 Prompt 与技能；
   2. 业务差异大、领域完全割裂的专属群（项目专项群、财务群、研发故障群）：OpenClaw 管理员新建独立 Agent（独立 workspace 工作目录、独立对话记忆、可单独配置专属 Skill / 专属角色 Prompt），在 bindings 新增一条路由，把该群定向绑定到新建 Agent；
      
4. 运维集中化：全部配置收敛在 OpenClaw 服务端，仅 OpenClaw 管理员维护配置，业务侧无任何配置成本，规模化落地效率极高。

关键避坑：几十个业务群共用同一个 Agent 工作目录，多群上下文混杂、历史聊天记忆互相干扰，极易造成 AI 注意力混乱、答非所问，建议业务跨度大的群组一律单独新建专属 Agent 隔离会话空间。

⚠️ 重要前置安全提醒（企业落地必看）： OpenClaw 官方明确：项目仅限个人学习、非商用场景使用，不推荐企业直接投产商用。 企业若基于本文方案落地试用，硬性规范：

1. 部署环境物理隔离：单独搭建独立测试环境，严禁对接企业生产业务系统、核心业务数据库、涉密数据、财务 / 人事敏感信息；
2. 数据管控：禁止群内同步企业机密、合同、客户隐私、核心技术资料等敏感内容；
3. 边界区分：仅用作内部闲聊、通用辅助答疑试用，不嵌入企业正式生产流程，规避数据泄露、合规、业务稳定性安全翻车风险。

二、飞书开放平台前置配置（全局统一 Bot）

1. 应用身份权限清单（必开）

应用→权限管理→应用身份开通以下权限：

im:message

im:message:send_as_bot

im:message.group_msg          # 全群消息接收，无需@即可触发

im:message.group_at_msg:readonly

im:message.p2p_msg:readonly

im:chat:readonly              # 获取群信息，规避99991672无权限报错

⚠️ 重要：权限勾选后页面 “修改已发布” 仅开发环境生效，必须创建新版本发布，线上权限才生效。

2. 事件配置

事件与回调→事件配置：接入方式 WebSocket，订阅事件im.message.receive_v1，和 OpenClaw connectionMode”:”websocket”匹配。

3. 机器人可被全公司搜索添加（跨部门 / 外部群）

1. 个人创建的飞书机器人，必须完成个人实名认证，发布页面开启对外共享时附带实名跳转链接；
2. 应用发布→创建新版本→可用范围编辑→勾选【允许外部租户用户添加到外部群和单聊】，保存发布；
3. 群添加机器人路径：飞书群→群设置→添加机器人→搜索机器人名称添加。

4. 飞书群 ID 获取方法

机器人入群→群内任意发消息→查看 OpenClaw 网关日志，日志中oc_开头字符串即为群组 ID。

三、openclaw.json 渠道配置

json

“channels”: {

  “feishu”: {

    “enabled”: true,

    “connectionMode”: “websocket”,

    “domain”: “feishu”,

    “accounts”: {

      “h0assistant-personal”: {

        “appId”: “cli_xxxx”,

        “appSecret”: “xxxx”,

        “name”: “H0-总助-个人”

      },

      “h0devmanager-personal”: {

        “appId”: “cli_xxxx”,

        “appSecret”: “xxxx”,

        “name”: “H0-项目开发经理-个人”

      },

      “default”: {

        “appId”: “cli_xxxx”,

        “appSecret”: “xxxx”,

        “name”: “H0-产品经理-个人”,

        “webhookPath”: “/feishu/events”,

        “dmPolicy”: “pairing”,

        “groupPolicy”: “open”,

        “groupAllowFrom”: [

          “ou_xxxx部门ID”,

          “oc_dc29b559b3******************”

        ]

      }

    }

  }}

实测结论：groupPolicy”:”open”即可实现免 @触发消息，无需额外配置 requireMention:false；禁止填写groupPolicy”:”all”（参数无效，强制 @机器人）；groupAllowFrom配置白名单，不在名单的群组消息直接拦截。

四、bindings 路由核心配置（企业多群分流关键）

配置规则说明

1. 前两项：存量历史独立 Bot 全量消息绑定原有 Agent（历史存量兼容保留）；
2. 从 default 配置开始：同一个全局 Bot + 单群 ID → 绑定独立 Agent，实现一 Bot 多群、分群隔离会话。

json

“bindings”: [

  {

    “agentId”: “h0assistant”,

    “match”: {

      “channel”: “feishu”,

      “accountId”: “h0assistant-personal”

    }

  },

  {

    “agentId”: “h0devmanager”,

    “match”: {

      “channel”: “feishu”,

      “accountId”: “h0devmanager-personal”

    }

  },

  // 产品专项群：独立Agent、独立记忆

  {

    “agentId”: “h0prdmanager”,

    “match”: {

      “channel”: “feishu”,

      “accountId”: “default”,

      “peer”: {

        “kind”: “group”,

        “id”: “oc_dc29b559b3******************”

      }

    }

  },

  // 通用咨询群：复用公共通用Agent

  {

    “agentId”: “common-help”,

    “match”: {

      “channel”: “feishu”,

      “accountId”: “default”,

      “peer”: {

        “kind”: “group”,

        “id”: “oc_xxxx通用群ID”

      }

    }

  }]

新增业务群标准模板

拿到新群 oc_群 ID 后，追加配置即可：

json

{

  “agentId”: “新群专属AgentID”,

  “match”: {

    “channel”: “feishu”,

    “accountId”: “default”,

    “peer”: {

      “kind”: “group”,

      “id”: “oc_新群组ID”

    }

  }}

五、新建独立 Agent（群组业务隔离操作）

业务跨度大的专属群，新建独立 Agent，生成隔离工作目录：

bash

运行

openclaw agents add 自定义AgentID –workspace ~/.openclaw/workspace-自定义AgentID

• 独立 workspace：群聊天记忆、上下文完全隔离，不会和其他群互相污染；
• 可单独配置专属 Prompt、按需启停专属技能，公共 Skill 默认全 Agent 共享。

六、上线验证步骤

1. 飞书配置变更后发布版本，等待 1~3min 权限同步；
2. 修改 openclaw.json 后重启 OpenClaw 网关；
3. 群发消息校验：
   1. 无did not mention bot日志 = 免 @生效；
   2. 无99991672 getChatInfo failed = 群信息权限正常；
   3. 日志 dispatch 指向对应 agentId = 路由配置生效。

七、踩坑汇总

1. 权限已勾选但 99991672 报错：未发布新版本；
2. 消息收到提示 did not mention bot：groupPolicy 填 all，改为 open；
3. 机器人搜不到无法加群：未实名、未开启对外共享；
4. 群组收不到消息：群 ID 未写入 groupAllowFrom 白名单。

八、企业规模化落地总结

1. 轻量化落地：全公司共用一个飞书 Bot，业务建群只拉机器人即用，落地成本最低；
2. 灵活隔离：普通通用群复用公共 Agent，垂直专项群新建独立 Agent，兼顾易用性与上下文稳定性；
3. 能力统一迭代：OpenClaw 侧更新技能、知识库后全公司所有群同步受益；
4. 合规底线重申：遵循官方使用约定，仅限个人学习、企业内部隔离环境试用，严禁接入生产系统、存储企业敏感数据用于正式商用。