OpenClaw 运行诊断与故障排查：从 status、日志到渠道与会话的完整链路 原创

2026-10-19 OpenClaw 浏览 (8)
温馨提示：
本文最后更新于 2026-10-19，已超过 0 天没有更新。 若文章内的图片失效（无法正常加载），请留言反馈或直接 联系我。

OpenClaw 跑久了会遇到「Web 聊天没响应」「子代理卡住」「Token 消耗异常」「某条渠道发不出消息」等问题。这篇把诊断路径捋成一条命令链：status → 日志 → 网关配置 → 渠道状态 → 会话历史，每层该用什么工具、看哪些字段、什么结果算异常，全部讲清楚。

一、第一步：openclaw status 一眼总览

别跳过这步直接看日志——status 给的字段都是诊断的「坐标」：

$ openclaw status
Gateway:   running (pid 12345, uptime 3d 4h)
Config:    /home/pp/.openclaw/config.yaml (valid)
Channels:  webchat ✓  telegram ✓  discord ✗ (token expired)
Sessions:  5 active, 12 idle
Model:     volcengine-coding/ark-code-latest
Tokens:    today 1.2M in / 340K out
Memory:    482 MB

一眼能看出的异常：

  • Gateway 状态不是 running → 直接看 systemd 日志
  • Config 显示 invalid → yaml 语法错或字段名错
  • 某渠道 ✗ → 这个渠道后面所有消息都不会通
  • Token 今日消耗远超预期 → 有 session 在死循环

二、日志：三个文件分工明确

文件 看什么 常见异常关键字
~/.openclaw/logs/gateway.log 主进程事件、启动、崩溃 ERROR、FATAL、UnhandledRejection
~/.openclaw/logs/sessions/<key>.log 单会话工具调用、模型响应 tool error、rate limit、timeout
~/.openclaw/logs/channels/<name>.log 渠道适配器收发 401/403/429、connection reset

实战命令组合：

# 启动失败时先看末尾
tail -n 100 ~/.openclaw/logs/gateway.log

# 跟踪正在发生的错误
tail -f ~/.openclaw/logs/gateway.log | grep -E 'ERROR|WARN'

# 找某个具体报错的所有出现
grep -rn 'rate_limit' ~/.openclaw/logs/

# 按时间段过滤（最近的崩溃）
awk '/2026-10-19 10:5/,/2026-10-19 11:0/' ~/.openclaw/logs/gateway.log

三、网关配置：常见错配清单

openclaw config validate 只能查语法，逻辑错配要逐项核：

$ openclaw config get gateway.model
$ openclaw config get channels.telegram
$ openclaw config get gateway.security

高频踩坑：

  1. model 字段写错：provider/model 之间的分隔符、provider 名拼错（volcengine vs volcano）→ 启动后所有请求 401
  2. 渠道 token 是 SecretRef 但 vault 里没配：日志显示 secret not found，但配置 yaml 看起来正常
  3. session timeout 太短：默认 30 分钟，长任务被中断；调到 4h 需同时调整 token budget
  4. maxTokens 限制过小：长文档被截断但模型不报错，看起来像「回答不完整」
  5. CORS / allowedOrigins：Web 控制台跨域访问被拒

四、渠道专项排查

4.1 Telegram

# 验证 token 有效
curl https://api.telegram.org/bot<TOKEN>/getMe

# 看 webhook 状态（如果用 webhook 模式）
curl https://api.telegram.org/bot<TOKEN>/getWebhookInfo

# 看 polling 是否抢消息
# 同一 token 在两处使用会冲突，表现是「消息时有时无」

4.2 Discord

常见症状是「机器人已上线但不响应」：90% 是 Privileged Intents 没开（Message Content Intent 必需）。去 Discord Developer Portal → Bot → Privileged Gateway Intents 打开。

4.3 Web 控制台（Control UI）

# 端口监听
ss -tlnp | grep openclaw

# 端口被防火墙拦
sudo iptables -L -n | grep 3000

# WebSocket 升级失败 → 看 nginx 反代配置
grep -E 'Upgrade|Connection' /etc/nginx/sites-enabled/openclaw

五、会话级诊断：sessions 系列工具

当某个具体会话行为异常（卡住、失忆、循环）：

# 列出活跃会话
openclaw sessions list

# 看指定会话的 token 消耗
openclaw sessions status <sessionKey>

# 导出最近 20 条消息检查模型响应
openclaw sessions history <sessionKey> --last 20

# 卡死的会话直接终止
openclaw sessions stop <sessionKey>

判断「失忆」的真假：先看 history 里的 context 字段是否被压缩，再核对 session 的 maxTokens 是否被调小。如果都不是，那就是模型本身没正确拿到 MEMORY.md——检查 workspace 路径和文件权限。

六、Token 异常消耗的根因排查

某天 token 突然 10 倍，按这个顺序查：

  1. openclaw sessions list --sort tokens 找最大的 session
  2. 看该 session 的 history：是不是陷入了「工具调用 → 失败 → 重试」循环
  3. 检查是否有 cron job 或 heartbeat 配错频率（每分钟唤醒 vs 每小时）
  4. 检查是否有子代理在递归调用（a 调 b，b 又调 a）
  5. 检查 system prompt 是否被异常注入了大量内容（比如把整个 MEMORY.md 重复拼接）

七、一页决策表

症状 第一怀疑 验证命令
Web 聊天打不开 Gateway 没起 openclaw status / ss -tlnp
某渠道静默 token 失效 openclaw status 看 Channels
回复突然变慢 模型端 429 grep rate_limit logs/sessions/
回答被截断 maxTokens 太小 openclaw config get gateway.maxTokens
Memory 失效 workspace 路径错 ls ~/.openclaw/workspace/MEMORY.md
子代理卡住 死循环调用 openclaw sessions history
Token 飙升 定时任务频率错 openclaw automations list

结语

OpenClaw 的诊断难点不在工具，在于它的组件跨进程、跨网络、跨服务——同一症状可能来自模型端、网关、渠道适配器或会话本身。按「status → 日志 → 配置 → 渠道 → 会话」的顺序逐层排除，配合本文的决策表，90% 的问题能在十分钟内定位到具体组件。剩下 10% 通常需要看上游 LLM 服务的状态，那不在 OpenClaw 范围内，但本文教的排查路径能帮你确认这一点。

相关文章