openclaw-debugging

OpenClaw 调试

本地测试、在线模型、提供商、代码模式、工具搜索、Crabbox 和 CI 中的行为各不相同：先获取调试信号，再做判断。

首先阅读

• docs/logging.md：日志文件、openclaw logs、针对性调试标志。
• docs/reference/test.md：本地测试命令。
• docs/tools/code-mode.md：代码模式的 exec/wait + 工具目录规则。
• $openclaw-testing：测试通道选择。
• $crabbox：广泛验证、Docker、软件包、Linux、实时密钥和 CI 一致性验证。

默认流程

1. 说明怀疑的边界：配置、工具构建、提供商载荷、fetch、 stream/SSE、对话记录重放、工作进程/运行时、软件包/dist、CI。
2. 添加/启用能证明该边界的最精简信号。
3. 使用相同的提供商/模型/配置复现。除非模型本身就是受测变量，否则切勿随意切换模型。
4. 比较已配置状态与实际运行时的激活状态。
5. 修复根因。
6. 重新运行精确的失败探测；仅在契约要求时扩大范围。

模型传输日志

模型请求结构/流传输时序：优先使用针对性的环境标志，而不是全局调试：

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted OPENCLAW_DEBUG_SSE=peek openclaw gateway

有用的标志：

• OPENCLAW_DEBUG_MODEL_TRANSPORT=1：在 info 级别记录请求开始、fetch 响应、SDK 标头、首个 SSE 事件、流结束和传输错误。
• OPENCLAW_DEBUG_MODEL_PAYLOAD=summary：有界的载荷摘要。
• OPENCLAW_DEBUG_MODEL_PAYLOAD=tools：所有面向模型的工具名称。
• OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted：有大小上限且经过脱敏的 JSON 载荷。仅在调试时使用；提示词/消息文本仍可能出现。
• OPENCLAW_DEBUG_SSE=events：首个事件和流完成的时序。
• OPENCLAW_DEBUG_SSE=peek：前五个经过脱敏的 SSE 事件。
• OPENCLAW_DEBUG_CODE_MODE=1：代码模式工具界面诊断信息。

查看日志：

openclaw logs --follow

常见边界

• **配置与激活：**已启用的配置可能与已禁用的运行工具、原始运行、空允许列表或缺少模型工具支持并存。在强制执行提供商载荷不变量之前，先检查实际可见的工具。
• **工具界面：**检查最终对模型可见的工具名称，而不只是注册表/配置。只有在实际激活后，代码模式才会严格限定为 exec + wait。
• **提供商载荷：**调用 SDK 之前，记录字段、模型 ID、服务层级、推理、输入大小、元数据键、提示词缓存键是否存在以及工具名称。
• **Fetch 与 SSE：**fetch 响应可证明 HTTP 标头已到达；首个 SSE 事件可证明提供商正文已有进展。此处的延迟表明是流/正文/提供商问题，而非工具执行问题。
• **工作进程/dist：**涉及工作进程、动态导入、软件包导出、惰性运行时边界或已发布路径时 → pnpm build。
• **实时密钥：**缺少提供商密钥时，在宣称实时验证受阻之前，先使用已配置的密钥工作流。环境变量检查只确认是否存在；绝不打印密钥。

获取会话和转录记录

聊天会话错误报告：获取实际转录记录、发送者归属信息， 以及作为证据的附件。

优先使用 CLI（需要已配置的安装；不会影响运行中的网关）：

openclaw sessions list --agent <agentId> --json
openclaw sessions tail
openclaw sessions export-trajectory

文档：存储布局见 docs/reference/database-schemas.md； CLI 见 https://docs.openclaw.ai/cli/sessions。

原始存储：CLI 不可用（例如通过 SSH 连接远程主机）或需要事件级详细信息时：

• 每个 Agent 的数据平面：~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite。 规范架构：src/state/openclaw-agent-schema.sql。
• 托管服务 / systemd 状态：服务用户的主目录（例如 /home/openclaw/.openclaw/...）， 而不是 root 的主目录。root 可能有单独的残留安装，且其中的 Agent 不同。 找不到预期的 Agent 目录：使用 find / -maxdepth 6 -name openclaw-agent.sqlite 定位实际的数据库。
• Web 聊天 URL 中的会话 ID 片段：/chat/<agentId>/<slug>-<hex>。 在 session_nodes 中解析：session_key LIKE '%<hex>%' → current_session_id、display_name。键的结构： agent:<agentId>:<surface>:<uuid>；子 Agent 会话使用 surface subagent。
• 转录记录：transcript_events（session_id、seq、event_json）。 event_json.message：role（user/assistant/toolResult）+ content（字符串或由 text/toolCall/image 类型部分组成）。
• 发送者来源：真实用户消息包含 message.__openclaw （senderId、senderName、senderIsOwner）；运行时合成的输入则不包含。 可据此区分操作者撰写的文本和注入的提示词。
• 转录记录全文搜索：session_transcript_fts。
• 附件：media://inbound/<file> URL → <state-dir>/media/inbound/<file>。
• 用户附加的图片 ≠ image 内容部分。消息封装中包含 message.__openclaw.media[] 条目：url（media://inbound/<file>）、 contentType、kind、fileName。仅检查内容部分的提取器会漏掉所有图片； 在原始 event_json 中搜索 media://。远程主机：使用 scp 将文件复制到本地 （每个 scp 参数指定一个远程路径）；在本地读取。

没有 sqlite3 二进制文件的主机仍有 Node：node:sqlite 无需依赖。

node -e 'const {DatabaseSync}=require("node:sqlite");
const db=new DatabaseSync(process.argv[1],{readOnly:true});
console.log(JSON.stringify(db.prepare(
  "SELECT seq,event_json FROM transcript_events WHERE session_id=? ORDER BY seq"
).all(process.argv[2])))' <db-path> <session-id>

• 始终以 readOnly: true 打开运行中的存储；绝不写入运行中网关的状态 （根目录 AGENTS.md 中的 Validation rules）。
• 使用真实数据时：先将数据库复制到开发状态目录。

代码位置

• 模型负载和 Responses 流： src/agents/openai-transport-stream.ts
• 受保护的 fetch / 计时： src/agents/provider-transport-fetch.ts
• OpenAI/Codex 提供方封装： src/llm/providers/stream-wrappers/openai.ts
• 工具构建、工具搜索、代码模式激活： src/agents/embedded-agent-runner/run/attempt.ts
• 代码模式运行时和 worker： src/agents/code-mode.ts src/agents/code-mode.worker.ts
• 工具搜索目录： src/agents/tool-search.ts

证明方式选择

• 单个辅助函数 / 负载错误：本地定向 Vitest。
• 仅涉及文档 / 日志：pnpm check:docs + git diff --check。
• Worker / dist / 延迟导入 / 包表面：定向测试 + pnpm build。
• 运行中的提供方 / 模型行为：相同的提供方 / 模型、调试标志，以及可用时的真实密钥。
• Docker / 包 / Linux / CI 环境一致性：能力允许时使用当前专用 Linux worker； 否则使用 $crabbox。
• CI 失败：使用确切的 SHA，仅检查相关作业；仅在失败 / 完成后查看日志。

输出习惯

报告：

• 测试的边界
• 确切的命令 / 环境变量形式，并对敏感信息脱敏
• 观察到的信号，例如工具名称或首个 SSE 事件的时间
• 修复位置
• 有针对性的验证 + 剩余风险