OpenClaw 教程 OpenClaw Gateway Troubleshooting 运维日志调试

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

Kai2026-05-132026-05-14

这是「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 status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

我建议你把它记下来。

它对应的是五层问题：

命令	主要看什么
`openclaw status`	总体状态、通道、会话、更新、运行概览
`openclaw gateway status`	Gateway 是否运行、连接是否正常
`openclaw logs --follow`	实时日志，找错误签名
`openclaw doctor`	配置、服务、依赖、迁移、常见问题
`openclaw channels status --probe`	各消息通道是否真的可用

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

它们是一个排错梯子。

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

二、`openclaw logs` 是什么？

openclaw logs 用来查看 Gateway file logs。

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

常用命令：

openclaw logs
openclaw logs --follow
openclaw logs --limit 500
openclaw logs --json
openclaw logs --plain
openclaw logs --local-time

最常用的是：

1	openclaw logs --follow

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

比如你可以这样做：

开一个终端：

1	openclaw logs --follow --local-time

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

三、日志文件在哪里？

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

1	/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：

Console output
File logs

Console output

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

比如：

1	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 status
openclaw status --all
openclaw status --deep
openclaw status --usage

普通 status

1	openclaw status

适合快速看：

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

deep status

1	openclaw status --deep

会跑 live probes。

适合：

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

usage

1	openclaw status --usage

适合看 provider 使用额度窗口。

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

七、用 health 看 Gateway 快照

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

常用：

openclaw health
openclaw health --json
openclaw health --verbose
openclaw health --timeout 2500

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

适合：

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

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

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

常用：

openclaw doctor
openclaw doctor --deep
openclaw doctor --repair
openclaw doctor --repair --non-interactive

它会检查很多常见问题：

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

注意：

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

日常排查先跑只读：

1	openclaw doctor

真要修，再考虑 repair。

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

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

这时用：

1	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 看消息通道是否真的可用。

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

症状：

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

不要第一反应重启。

按顺序查：

openclaw status
openclaw channels status --probe
openclaw logs --follow
openclaw doctor

看日志里的关键字

常见方向：

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

常见原因

原因	表现
DM pairing 未批准	陌生私聊不进 Agent
群聊需要 mention	群里没 @ bot，所以忽略
allowlist 不匹配	sender / group 被拦截
channel token 错	启动或 probe 报 auth error
model 失败	消息进 Agent，但生成失败
工具调用卡住	Agent 开始跑，但工具失败或等待 approval

典型日志线索

比如你看到：

1	drop guild message (mention required)

这不是模型坏了。

是群聊 mention gating 生效。

如果看到：

1	pairing request

说明 sender 可能需要 approve。

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

模型错误常见表现：

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

常用检查：

1
2
3

openclaw logs --follow
openclaw models status
openclaw status --usage

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

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

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

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

排查思路：

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

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

通道错误要按 channel 看。

常见线索：

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

检查：

1
2
3

openclaw channels status --probe
openclaw logs --follow
openclaw pairing list telegram

常见线索：

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

检查：

1
2
3

openclaw channels status --probe
openclaw logs --follow
openclaw 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

建议先把错误归类：

工具类型	常用排查
exec	`/exec`、approvals、sandbox、elevated
browser	browser 状态、登录态、refs、timeout
file tools	workspace、路径、sandbox access
nodes	nodes status、describe、command policy
media	文件大小、provider、权限、前台状态

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

1	sandbox → tool policy → elevated → exec approvals

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

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

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

权限错误不要靠猜。

先跑：

1
2
3

openclaw sandbox explain
openclaw approvals get --gateway
openclaw nodes status

如果是 node：

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

常见错误含义：

线索	大概率原因
tool blocked	tool policy / sandbox tool policy
approval-pending	等待用户批准
allowlist miss	命令不在 allowlist
SYSTEM_RUN_DENIED	node 或 gateway exec approvals 拒绝
NODE_BACKGROUND_UNAVAILABLE	移动端 App 在后台
*_PERMISSION_REQUIRED	OS 权限缺失

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

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

Cron

查：

1
2
3

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

看：

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

Heartbeat

查：

1 2	openclaw logs --follow openclaw status

看：

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

Webhook / hooks

查：

1 2	openclaw logs --follow openclaw security audit --deep

看：

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

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

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

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

1 2	openclaw logs --local-time openclaw logs --follow --local-time

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

比如：

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

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

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

这样看日志更容易定位。

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

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

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

如果你要脚本处理，用：

1	openclaw logs --json

比如你想过滤 error：

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

或者过滤某个 subsystem。

JSON 日志适合：

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

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

十八、什么时候用 diagnostics export？

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

可以用 diagnostics bundle。

命令：

1	openclaw gateway diagnostics export

指定输出：

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

JSON：

1	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，也不要完全依赖自动脱敏。

建议：

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

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

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

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

第一步：看总状态

1	openclaw status

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

第二步：看通道 probe

1	openclaw channels status --probe

如果 token 401，去修 token。

第三步：看日志

1	openclaw logs --follow --local-time

然后发一条测试消息。

观察是否出现：

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

第四步：看 pairing

1	openclaw pairing list telegram

如果 sender 没 approve，先 approve。

第五步：看 doctor

1	openclaw doctor

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

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

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

假设 Agent 说 exec 被拒绝。

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

1	openclaw sandbox explain

看：

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

第二步：看 approvals

1	openclaw approvals get --gateway

如果是 node：

1	openclaw approvals get --node <idOrNameOrIp>

第三步：看日志

1	openclaw logs --follow

找：

approval-pending
allowlist miss
SYSTEM_RUN_DENIED
sandbox jail
elevated unavailable

第四步：不要直接 full

更好的修复是：

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

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

先看节点：

1 2	openclaw nodes status openclaw nodes describe --node <idOrNameOrIp>

再看日志：

1	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）不回复排查

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

3）模型错误排查

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

4）工具错误排查

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

5）导出诊断包

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

6）日志脱敏提醒

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

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

如果今天只记一句话：

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

再记一句安全原则：

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

二十五、总结

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

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

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

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

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

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

下一课预告

下一课我们会讲：

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

会重点讲：

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

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

一、先记住排错命令梯子

二、openclaw logs 是什么？

三、日志文件在哪里？

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

Console output

File logs

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

六、先用 status 看“大方向”

普通 status

deep status

usage

七、用 health 看 Gateway 快照

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

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

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

看日志里的关键字

常见原因

典型日志线索

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

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

Telegram

WhatsApp

Discord / Slack

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

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

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

Cron

Heartbeat

Webhook / hooks

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

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

十八、什么时候用 diagnostics export？

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

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

第一步：看总状态

第二步：看通道 probe

第三步：看日志

第四步：看 pairing

第五步：看 doctor

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

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

第二步：看 approvals

第三步：看日志

第四步：不要直接 full

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

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

1）通用排错

2）不回复排查

3）模型错误排查

4）工具错误排查

5）导出诊断包

6）日志脱敏提醒

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

二十五、总结

下一课预告

Kai

二、`openclaw logs` 是什么？