OpenClaw系列第27课:日志与调试 – 怎么看 Gateway 日志排错

这是「OpenClaw 教程课程」第 27 课。 上一课我们讲了 SSH、防火墙、自动更新这些主机安全基线。今天继续进入运维核心：OpenClaw 出问题时，怎么看 Gateway 日志，怎么判断到底是哪一层坏了。

图：OpenClaw 排错不是只盯一行报错，而是把 status、health、logs、doctor、channels probe、security audit 组合起来看。

OpenClaw 跑久了，你一定会遇到这些问题：

• Telegram 不回复了
• WhatsApp 显示连接但消息没反应
• Agent 一直思考但没有结果
• 模型报 429 或 auth error
• exec 被拒绝
• browser 打不开页面
• node 已经 paired 但工具失败
• cron / heartbeat 没按预期触发
• Gateway 重启后状态不对

这时候最怕的是直接乱改配置。

正确姿势是：

先看状态，再看日志，再按层定位。

这一课就是一份实战排错手册。

一、先记住排错命令梯子

OpenClaw 官方 troubleshooting 文档给了一个很实用的命令顺序：

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

我建议你把它记下来。

它对应的是五层问题：

这五个命令不是互相替代。

它们是一个排错梯子。

图：建议按 status、gateway status、logs、doctor、channels probe 的顺序排查，不要一开始就乱改配置。

二、openclaw logs 是什么？

openclaw logs 用来查看 Gateway file logs。

它通过 Gateway RPC tail 日志，所以 remote mode 下也能用。

常用命令：

openclaw logsopenclaw logs --followopenclaw logs --limit 500openclaw logs --jsonopenclaw logs --plainopenclaw logs --local-time

最常用的是：

openclaw logs --follow

它会持续跟随日志，适合你一边复现问题，一边看 Gateway 到底记录了什么。

比如你可以这样做：

1. 开一个终端：

openclaw logs --follow --local-time

1. 在 Telegram 里发一条测试消息
2. 看日志里出现了什么
3. 判断消息有没有进 Gateway、有没有进入 Agent、有没有工具调用、有没有回复发送

三、日志文件在哪里？

OpenClaw 文档里说，默认 rolling log file 在：

/tmp/openclaw/openclaw-YYYY-MM-DD.log

日期使用 Gateway 主机本地时区。

日志是 JSON lines 格式，也就是一行一个 JSON object。

你也可以通过配置指定：

{  logging: {    file: "/path/to/openclaw.log",    level: "info"  }}

常见日志级别：

• info
• debug
• trace

注意：

--verbose 影响 console 输出，不等于提高 file log level。  

如果你想让文件日志记录更多细节，需要配置：

{  logging: {    level: "debug"  }}

或者更细：

{  logging: {    level: "trace"  }}

不要长期无脑开 trace。

因为日志会更大，也可能记录更多运行细节。

四、日志有两种表面：console 和 file

OpenClaw 的 logging 文档把日志分成两类 surface：

1. Console output
2. File logs

Console output

就是你在终端启动 Gateway 时看到的输出。

比如：

openclaw gateway --verbose

它适合临时排查启动过程、WebSocket 请求等。

File logs

这是 Gateway logger 写到文件里的 JSONL。

openclaw logs --follow tail 的就是这个。

如果你是 systemd / launchd 后台运行 Gateway，file logs 通常比 terminal output 更可靠。

所以新手记住：

日常排错优先用 openclaw logs --follow，不是去猜后台服务终端输出。

五、日志里的敏感信息会怎么处理？

OpenClaw 有日志脱敏机制。

关键配置：

{  logging: {    redactSensitive: "tools"  }}

常见值：

• off
• tools

默认建议是 tools。

文档里说，redaction 会应用到 console、file-log、OTLP log-record、session transcript text sinks 等地方。

默认会遮罩常见：

• API key
• bearer token
• JSON secret fields
• CLI token flags
• PEM blocks
• payment credential fields

但你不能因此就随便把日志发给别人。

因为日志仍然可能包含：

• provider 名称
• channel id
• plugin id
• 错误路径
• 本地环境信息
• 部分上下文摘要
• 主机状态

所以分享日志前，至少做一次人工检查。

一句话：

日志会尽量脱敏，但分享前仍然要当成敏感材料。

六、先用 status 看“大方向”

openclaw status 是最快的总览。

常用：

openclaw statusopenclaw status --allopenclaw status --deepopenclaw status --usage

普通 status

openclaw status

适合快速看：

• Gateway 概况
• channel 状态
• session 概况
• runtime / execution
• update 提示

deep status

openclaw status --deep

会跑 live probes。

适合：

• 你怀疑通道实际上不可用
• 表面在线但不回复
• 刚改过 token / proxy / channel 配置

usage

openclaw status --usage

适合看 provider 使用额度窗口。

如果模型突然不回复、报 quota / 429 / rate limit，这个有帮助。

七、用 health 看 Gateway 快照

openclaw health 会从运行中的 Gateway 获取健康快照。

常用：

openclaw healthopenclaw health --jsonopenclaw health --verboseopenclaw health --timeout 2500

--verbose 会强制 live probe，并展开更多账号和 agent 信息。

适合：

• 你想确认 Gateway 是否真的能响应 RPC
• 状态页看起来不对
• service 运行但 Gateway 不健康
• 自动化脚本需要 JSON 输出

八、用 doctor 做“体检”和修复建议

openclaw doctor 是健康检查和指导修复工具。

常用：

openclaw doctoropenclaw doctor --deepopenclaw doctor --repairopenclaw doctor --repair --non-interactive

它会检查很多常见问题：

• Gateway service 状态
• 配置迁移
• channel token / SecretRef 问题
• 插件缺失或配置异常
• sandbox 依赖
• model route 问题
• command owner 缺失
• cron 旧配置
• stale TUI clients

注意：

doctor --repair 会修改配置或状态，执行前要确认。  

日常排查先跑只读：

openclaw doctor

真要修，再考虑 repair。

九、channels status –probe：通道是不是“真能用”

有时候通道看起来 connected，但实际不能收发。

这时用：

openclaw channels status --probe

它会做各通道 live probe。

健康信号可能包括：

• transport connected
• works
• audit ok
• token status ok

特别适合排查：

• Telegram bot token 错误
• WhatsApp 连接抖动
• Discord intent / channel allowlist 问题
• Slack app token / bot token 问题
• Signal daemon 问题

图：status 看概览，health 看 Gateway 快照，doctor 看系统和配置，channels probe 看消息通道是否真的可用。

十、排错第一类：没有回复

症状：

我发消息给 bot，但它不回复。

不要第一反应重启。

按顺序查：

openclaw statusopenclaw channels status --probeopenclaw logs --followopenclaw doctor

看日志里的关键字

常见方向：

• pairing request
• mention required
• allowlist / blocked
• group policy
• token unavailable
• send failed
• model error
• tool denied

常见原因

典型日志线索

比如你看到：

drop guild message (mention required)

这不是模型坏了。

是群聊 mention gating 生效。

如果看到：

pairing request

说明 sender 可能需要 approve。

十一、排错第二类：模型错误

模型错误常见表现：

• 429 rate limit
• quota exceeded
• auth missing
• auth expired
• model_not_found
• context too long
• provider timeout
• OpenAI-compatible backend 兼容性问题

常用检查：

openclaw logs --followopenclaw models statusopenclaw status --usage

如果是本地 OpenAI-compatible backend，文档建议先用小请求确认：

curl http://127.0.0.1:1234/v1/models

再用 OpenClaw 直接推理命令验证：

openclaw infer model run --model <provider/model> --prompt "hi" --json

排查思路：

1. auth 是否存在
2. 模型 id 是否正确
3. provider baseUrl 是否正确
4. 小请求是否成功
5. OpenClaw agent 大 prompt 是否失败
6. 是否是工具 schema / 长上下文压垮后端
7. 是否需要 fallback model

十二、排错第三类：通道错误

通道错误要按 channel 看。

Telegram

常见线索：

• getMe returned 401
• Telegram API network error
• group privacy mode
• mention requirement
• allowlist mismatch

检查：

openclaw channels status --probeopenclaw logs --followopenclaw pairing list telegram

WhatsApp

常见线索：

• QR login timeout
• reconnect loop
• connected but no DM replies
• delays / stale TUI clients

检查：

openclaw channels status --probeopenclaw logs --followopenclaw doctor

Discord / Slack

常见线索：

• bot online but guild silent
• missing intent
• channel allowlist mismatch
• tool answered privately but没发到群
• token unavailable

排查时不要只问“bot 在线吗”。

要问：

这条消息有没有被允许进入 Agent？Agent 的结果有没有被允许发回这个 channel？

十三、排错第四类：工具错误

工具错误常见：

• exec 被 deny
• approval pending
• sandbox jail
• browser timeout
• file permission denied
• node command denied
• camera permission required

建议先把错误归类：

权限类问题优先看第 25 课那套模型：

sandbox → tool policy → elevated → exec approvals

节点类问题优先看第 23 课那套模型：

network → pairing → role=node → connected → capabilities → permissions

十四、排错第五类：权限错误

权限错误不要靠猜。

先跑：

openclaw sandbox explainopenclaw approvals get --gatewayopenclaw nodes status

如果是 node：

openclaw approvals get --node <idOrNameOrIp>openclaw nodes describe --node <idOrNameOrIp>

常见错误含义：

十五、排错第六类：自动化没触发

如果 cron / heartbeat / webhook 没按预期工作，先分清入口。

Cron

查：

openclaw cron listopenclaw cron runs <jobId>openclaw logs --follow

看：

• job 是否 enabled
• schedule 是否正确
• timezone 是否符合预期
• 上次 run 是否失败
• agent id / session key 是否正确

Heartbeat

查：

openclaw logs --followopenclaw status

看：

• HEARTBEAT.md 是否为空
• heartbeat 是否被 Gateway 触发
• agent 是否有响应
• 是否被权限或工具策略拦住

Webhook / hooks

查：

openclaw logs --followopenclaw security audit --deep

看：

• token 是否正确
• path 是否正确
• allowedAgentIds 是否限制过严或过宽
• sessionKey override 是否按预期
• 请求是否真的到达 Gateway

十六、日志里的时间怎么看？

默认日志时间可能是 Gateway 主机时区。

如果你想用本地时间显示：

openclaw logs --local-timeopenclaw logs --follow --local-time

排查异步问题时，时间非常重要。

比如：

• 消息什么时候进来
• Agent 什么时候开始
• 工具什么时候调用
• approval 等了多久
• reply 什么时候发送
• Gateway 是否中间重启

建议复现问题时记录一句：

我在 23:10 左右发送了测试消息“ping”。

这样看日志更容易定位。

图：排错时把用户消息、Gateway 接收、Agent 运行、工具调用、回复发送放到同一条时间线上看。

十七、什么时候用 JSON 日志？

如果你只是人工看，普通输出就够。

如果你要脚本处理，用：

openclaw logs --json

比如你想过滤 error：

openclaw logs --json | jq 'select(.level=="error")'

或者过滤某个 subsystem。

JSON 日志适合：

• CI
• 自动巡检
• 支持工单
• 统计错误频率
• 抽取 request id / run id

但发给别人前仍然要脱敏。

十八、什么时候用 diagnostics export？

如果你要向开发者或社区求助，不要直接发一大坨原始日志。

可以用 diagnostics bundle。

命令：

openclaw gateway diagnostics export

指定输出：

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

JSON：

openclaw gateway diagnostics export --json

它会生成一个 zip，包含：

• summary.md
• diagnostics.json
• manifest.json
• sanitized config shape
• sanitized log summaries
• health / status snapshots
• stability bundle 信息

文档强调：

diagnostics bundle 设计上会省略或脱敏 payload 和 credentials，但分享前仍然要当成敏感材料审查。  

尤其是 bug report 场景，diagnostics 比手动复制一堆日志更规范。

图：遇到复杂问题时，可以导出 diagnostics zip，里面包含脱敏后的状态、日志摘要、配置形状和稳定性信息。

十九、不要在日志里泄露什么？

下面这些不要直接发到群里或公开 issue：

• API key
• Gateway token / password
• Telegram bot token
• Discord / Slack token
• webhook token
• setup code / bootstrap token
• OAuth refresh token
• cookies
• ~/.openclaw/credentials/ 内容
• 原始聊天记录
• 用户手机号、邮箱、真实姓名
• 私有 URL / 内网 IP / 主机名
• 截图里的敏感信息

即使 OpenClaw 有 redaction，也不要完全依赖自动脱敏。

建议：

1. 先用 diagnostics export
2. 再人工检查
3. 只发必要片段
4. token 一旦误发，立刻旋转

图：日志和诊断包分享前要检查敏感信息，尤其是 token、API key、OAuth、cookies、setup code、聊天原文和内网地址。

二十、一个完整排错案例：Telegram 不回复

假设你发现 Telegram 私聊不回复。

第一步：看总状态

openclaw status

如果 Telegram 显示异常，继续 probe。

第二步：看通道 probe

openclaw channels status --probe

如果 token 401，去修 token。

第三步：看日志

openclaw logs --follow --local-time

然后发一条测试消息。

观察是否出现：

• inbound message
• pairing request
• allowlist blocked
• mention required
• agent run started
• model error
• send failed

第四步：看 pairing

openclaw pairing list telegram

如果 sender 没 approve，先 approve。

第五步：看 doctor

openclaw doctor

如果 doctor 提示 token、owner、SecretRef、channel 配置异常，按提示处理。

这个流程比“重启一下试试”可靠很多。

二十一、一个完整排错案例：exec 失败

假设 Agent 说 exec 被拒绝。

第一步：看是不是工具被禁

openclaw sandbox explain

看：

• exec 是否被 tool policy deny
• sandbox tool policy 是否允许 exec
• 当前 session 是否 sandboxed
• elevated 是否可用

第二步：看 approvals

openclaw approvals get --gateway

如果是 node：

openclaw approvals get --node <idOrNameOrIp>

第三步：看日志

openclaw logs --follow

找：

• approval-pending
• allowlist miss
• SYSTEM_RUN_DENIED
• sandbox jail
• elevated unavailable

第四步：不要直接 full

更好的修复是：

• 明确 allowlist 某个只读命令
• 或 ask on-miss
• 或临时 /elevated on
• 尽量不要长期 /elevated full

二十二、一个完整排错案例：节点 camera 失败

先看节点：

openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>

再看日志：

openclaw logs --follow

常见线索：

• CAMERA_DISABLED
• NODE_BACKGROUND_UNAVAILABLE
• *_PERMISSION_REQUIRED
• command policy denied
• node disconnected

处理：

• App 切到前台
• 系统 Camera 权限允许
• 节点设置里打开 camera
• Gateway command policy 允许对应 command
• 确认节点 connected

这就是第 23 / 24 课的组合应用。

二十三、适合新手的排错提问模板

1）通用排错

请帮我排查 OpenClaw 当前问题，只做只读检查。请按 openclaw status、gateway status、logs --follow、doctor、channels status --probe 的顺序检查，并总结问题可能在哪一层。

2）不回复排查

Telegram/WhatsApp 不回复了。请先判断消息有没有进 Gateway，再看是否被 pairing、mention、allowlist、model error 或 send failed 拦住。

3）模型错误排查

Agent 运行失败，疑似模型问题。请查看 logs、models status、status --usage，判断是 auth、quota、429、model_not_found、context too long 还是 provider timeout。

4）工具错误排查

工具调用失败了。请帮我区分是 tool policy、sandbox、elevated、exec approvals、node command policy 还是系统权限问题。

5）导出诊断包

我准备向社区求助。请帮我生成 diagnostics export，并说明这个 zip 里有什么、分享前还需要人工检查哪些敏感信息。

6）日志脱敏提醒

请帮我整理一段可以发给支持人员的错误日志摘要，不要包含 token、API key、聊天原文、手机号、邮箱或内网敏感地址。

二十四、这一课最值得记住的一句话

如果今天只记一句话：

OpenClaw 排错不要先重启，先按 status → gateway status → logs → doctor → channels probe 梯子查。

再记一句安全原则：

日志和 diagnostics 都可能包含敏感运行信息，分享前一定要审查。

二十五、总结

今天这节课，我们讲了 OpenClaw 日志与调试的核心方法：

1. 先用命令梯子排查，不要先乱改配置。
2. openclaw logs --follow 是日常排错最常用入口。
3. Gateway file logs 默认在 /tmp/openclaw/openclaw-YYYY-MM-DD.log。
4. console verbose 不等于提高 file log level。
5. status 看总体，health 看 Gateway 快照，doctor 看配置和服务。
6. channels status –probe 看通道是否真的可用。
7. 没有回复时，先看 pairing、mention、allowlist、model、send failed。
8. 模型错误常见是 auth、quota、429、model id、context、provider timeout。
9. 工具错误要按 sandbox、tool policy、elevated、approvals 分层查。
10. 节点错误要按 pairing、connected、describe、permissions 分层查。
11. 复杂问题可以用 diagnostics export，但分享前仍要审查。
12. 日志不是垃圾输出，而是系统在告诉你它卡在哪一层。

学会看日志后，你会发现 OpenClaw 很多问题都不是“玄学坏了”。

它通常已经在日志里告诉你：

我没收到消息我收到但忽略了我被 allowlist 拦了我模型失败了我工具被拒了我发送失败了

把这些线索读出来，排错就会稳定很多。

下一课预告

下一课我们会讲：

第 28 课：多 Gateway 部署与远程访问

会重点讲：

• 什么时候需要多个 Gateway
• 为什么默认建议一个 host 一个 Gateway
• 多 Gateway 和多 Node 有什么区别
• 如何避免 WhatsApp / browser / credentials 混用
• 远程 Gateway、SSH tunnel、Tailscale、Control UI 怎么组合

🦞 本文由八条撰写，持续更新中。