1. 日志与调试标志（Debug Flags）
技能提供了一系列精准的环境变量调试标志，用于定向捕获特定环节的日志，而非开启全局调试：
| 环境变量 | 用途 |
|---|---|
OPENCLAW_DEBUG_MODEL_TRANSPORT=1 |
记录请求开始、fetch 响应、SDK 头、首个 SSE 事件、流完成及传输错误 |
OPENCLAW_DEBUG_MODEL_PAYLOAD=summary |
输出有边界的 payload 摘要 |
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools |
输出所有模型可见的工具名称 |
OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted |
输出经过截断和脱敏的完整 JSON payload（仅调试时使用，提示/消息文本仍可能可见） |
OPENCLAW_DEBUG_SSE=events |
记录首个事件和流完成的时间 |
OPENCLAW_DEBUG_SSE=peek |
输出前五个脱敏后的 SSE 事件 |
OPENCLAW_DEBUG_CODE_MODE=1 |
输出 code-mode 工具层面的诊断信息 |
查看日志可使用 openclaw logs --follow 命令。
2. 常见问题边界定位
技能将问题可能出现的边界进行了分类，帮助快速缩小排查范围：
-
配置 vs 激活（Config vs activation）：配置可能已启用，但运行时禁用了工具、处于 raw 模式、allowlist 为空或模型不支持工具。在强制执行 provider payload 约束前，先检查实际可见的工具。
-
工具表面（Tool surface）：检查最终模型可见的工具名称，而非仅看工具注册表或配置。Code mode 意味着只有
exec和wait在实际激活后才生效。 -
Provider payload：记录字段、模型 ID、service tier、推理参数、输入大小、metadata 键、prompt-cache 键存在性以及 SDK 调用前的工具名称。
-
Fetch vs SSE：fetch 响应证明 HTTP 头已到达；首个 SSE 事件证明 provider 正在返回内容。两者之间的间隙表明是流/body/provider 问题，而非工具执行问题。
-
Worker/分发（Worker/dist）：修改 workers、动态导入、package exports、懒加载运行时边界或发布路径后，运行
pnpm build。 -
Live keys：使用配置的 secret workflow 检查缺失的 provider key，不要因 key 问题而中断 live 验证。环境检查仅验证存在性，绝不打印 secrets。
3. 代码定位指针
技能提供了关键源码文件的快速索引：
| 文件路径 | 职责 |
|---|---|
src/agents/openai-transport-stream.ts |
Model payload + Responses stream |
src/agents/provider-transport-fetch.ts |
Guarded fetch/timing |
src/agents/pi-embedded-runner/openai-stream-wrappers.ts |
OpenAI/Codex provider wrappers |
src/agents/pi-embedded-runner/run/attempt.ts |
Tool 构造、Tool Search、code-mode 激活 |
src/agents/code-mode.ts / src/agents/code-mode.worker.ts |
Code-mode 运行时和 worker |
src/agents/tool-search.ts |
Tool Search catalog |
4. 证明路径选择（Proof Choice）
根据问题类型选择最合适的验证方式：
| 问题类型 | 推荐验证方式 |
|---|---|
| 单点 helper/payload bug | 本地 targeted Vitest |
| 文档/日志问题 | pnpm check:docs + git diff --check |
| Worker/dist/lazy import/package surface | targeted tests + pnpm build |
| Live provider/model 行为 | 相同 provider/model + debug flags + 真实 key（如有） |
| Docker/package/Linux/CI 一致性 | $crabbox |
| CI 失败 | 精确 SHA + 相关 job + 失败/完成后的日志 |
三、主要用途
-
定位行为差异的根因
当 OpenClaw 在不同环境（本地测试、live models、不同 provider、code mode、Tool Search、Crabbox、CI）中表现不一致时，系统化地定位问题边界。 -
精准捕获调试信号
使用定向的环境变量调试标志，而非开启全局调试，避免日志泛滥，只捕获最相关的信息。 -
验证配置与实际运行的一致性
检查配置是否真正生效，工具是否实际可见，code mode 是否真正激活。 -
区分传输层与执行层问题
通过 Fetch vs SSE 的对比，判断问题是出在 HTTP/流传输层还是工具执行层。 -
Worker 和构建问题的快速定位
修改 workers、动态导入或 package 边界后，通过pnpm build验证构建是否完整。
四、标准调试流程
1. 声明怀疑的边界：config、tool construction、provider payload、fetch、stream/SSE、transcript replay、worker/runtime、package/dist 或 CI[reference:24]
2. 添加或启用最精准的信号来证明该边界[reference:25]
3. 使用相同的 provider/model/config 复现问题（除非模型本身是测试变量）[reference:26]
4. 比较配置状态与实际运行激活状态[reference:27]
5. 修复根因[reference:28]
6. 重新运行精确的失败探测，仅在契约要求时才扩大范围[reference:29]五、重要原则
-
不随机切换模型：除非模型本身是测试变量，否则复现时必须使用相同的 provider/model/config。
-
环境检查仅验证存在性：绝不打印 secrets。
-
输出习惯：报告时必须包含——测试的边界、精确的命令/env 形状（脱敏后）、观察到的信号（如工具名称或首个 SSE 事件时间）、修复位置、窄化证明及剩余风险。
六、总结
OpenClaw Debugging 是一个系统化的调试技能，通过精准的调试标志、清晰的问题边界分类和代码指针，帮助开发者快速定位 OpenClaw 在不同环境中的行为差异根因。它适用于 OpenClaw 开发者在遇到本地与生产环境不一致、不同 provider 表现不同、code mode 或 Tool Search 行为异常、CI 失败等场景时，以信号驱动而非猜测驱动的方式进行调试。
