22. 诊断工具与日志：help、debug、diagnostics

本节目标：搞懂 OpenClaw 自带的诊断命令和日志系统，排错时知道去哪看、开什么开关、怎么打包证据。

上一章讲了”按症状排查”。这一章讲工具本身：日志在哪、怎么开更详细的输出、怎么临时改配置不改文件、怎么把现场打包发给别人协助。

help：先问内置帮助

忘了命令或参数，先敲 openclaw help。它不像普通文档那样罗列一切，而是按”最快脱困”的思路，把相关页面分组指给你：

openclaw help

它会列出几个入口：排错决策树（troubleshooting）、调试（debugging）、安装自检（node）、网关排错（gateway troubleshooting）、doctor 健康检查等。卡住时从这里跳，比盲搜快得多。

Tip

每个子命令也带 --help。比如 openclaw gateway --help、openclaw update --help，能直接看到该命令支持的参数。

看日志：logs 与日志文件

OpenClaw 有两类日志输出：终端里看到的”控制台输出”，以及写到磁盘的”文件日志”。

实时跟踪文件日志：

openclaw logs --follow

只想看纯文本、方便过滤：

openclaw logs --plain --limit 5000 | rg "telegram http error"

文件日志默认位置：

普通机器：/tmp/openclaw/openclaw-YYYY-MM-DD.log（每天一个文件）。
Windows：固定落在系统临时目录下的 openclaw-<uid> 路径。
命名 profile（如 --dev）：文件名带 profile 后缀，比如 openclaw-dev-YYYY-MM-DD.log。

文件写的是 JSONL 格式，一行一条记录。想改路径或级别，在 ~/.openclaw/openclaw.json 里设：

{
  "logging": {
    "file": "/var/log/openclaw/gateway.log",
    "level": "info"
  }
}

Note

--verbose 只影响控制台详细程度，不会把文件日志级别调高。要文件里也出现调试细节，得把 logging.level 设成 debug 或 trace。日志里的敏感令牌默认全程脱敏，不会原样落盘。

诊断开关：diagnostics flags

有时候只想给某一个子系统加日志，不想把全局日志级别调高。用诊断开关（diagnostics flags）最合适。

临时开一次（覆盖配置）：

OPENCLAW_DIAGNOSTICS=telegram.http,brave.http openclaw gateway run

或在配置里常开：

{
  "diagnostics": {
    "flags": ["telegram.http", "brave.http"]
  }
}

常用开关举例：

开关	作用
`telegram.http`	Telegram Bot API 的 HTTP 错误日志
`brave.http`	Brave 搜索请求/响应日志
`health`	网关健康探测细节
`plugin.load-profile`	插件模块同步加载耗时
`timeline`	把启动/运行时间线写成 JSONL

改了配置里的 diagnostics.flags 要重启网关才生效，它不支持热重载。OPENCLAW_DIAGNOSTICS=0 可以临时关掉所有开关，包括配置里设的。

/debug 与 /trace：运行时临时调整

在对话里就能用的两个命令，改的是”内存里的配置”，不落盘，重启即失效。

Note

/debug 默认是关闭的。要先在 openclaw.json 里设 commands.debug: true 才会响应，否则发过去只会被当成普通消息。

/debug 适合临时改一项配置看效果：

/debug show
/debug set channels.whatsapp.responsePrefix="[openclaw]"
/debug unset channels.whatsapp.responsePrefix
/debug reset

/trace 只给某个会话打开插件级的调试行，不必开全局 verbose：

/trace on
/trace off

Tip

拿不准某次改动会不会搞坏配置，先用 /debug set 试。不满意就 /debug reset 回到磁盘上的配置，文件一个字都不用改。

导出诊断包：给报 bug 用

要找人协助或提 issue，别直接贴原始日志——那里可能有敏感信息。用导出命令生成一份脱敏的诊断包：

openclaw gateway diagnostics export

它会打包网关状态、健康、日志、配置形态和最近的稳定性事件，输出一个 .zip 路径。也能指定输出位置：

openclaw gateway diagnostics export --output openclaw-diagnostics.zip

在聊天里，拥有者可以直接发 /diagnostics 备注文字，OpenClaw 会请求一次执行审批后生成报告并私回给你。

Note

诊断包的设计就是”脱敏”的：聊天文本、提示词、工具输出、密钥、令牌都不会写进去。但里面仍汇总了本地日志和运行时状态，发给别人前自己先扫一眼。

原始流日志（raw stream）

想确认 AI 的”思考过程”是不是以纯文本片段到达，可以开原始流日志，看到过滤/格式化之前的助手输出：

OPENCLAW_RAW_STREAM=1 openclaw gateway run

默认写到 ~/.openclaw/logs/raw-stream.jsonl。这个文件可能包含完整提示词和工具输出，调试完记得删掉。

Warning

原始流日志属于高敏感。本地留存就好，分享前务必擦掉密钥和个人信息。

小结

排错工具就这几样：openclaw help 找方向，openclaw logs --follow 看现场，diagnostics.flags 给单个子系统加料，/debug 临时试配置，gateway diagnostics export 打包脱敏证据。把它们组合用，绝大多数问题都能自己看清、说清。