运行时问题排查：Gateway 挂了、AI 不回复怎么办

📖 本章目标：遇到问题别慌，用五步诊断法快速定位和解决

---

2.1 五步诊断法（先跑这个）

⚡ 遇到任何问题，先按顺序跑这五条命令

openclaw status --all              # Step 1：全局状态总览
openclaw gateway status            # Step 2：Gateway 状态
openclaw doctor                    # Step 3：配置问题诊断
openclaw channels status --probe   # Step 4：频道连通性探测
openclaw logs --follow             # Step 5：实时日志跟踪

---

2.2 Gateway 常见问题

症状	原因	解决
Gateway 启动后立即退出	pid lock 残留（上次未正常关闭）	rm ~/.openclaw/gateway.pid，再重启
连接被拒绝	Gateway 没在运行	openclaw gateway start
Token 鉴权失败	2026.2.19+ 版本 token 机制变更	openclaw auth refresh，或重新生成 token
origin not allowed	局域网 IP 被拦截	在 openclaw.json 配置 allowedOrigins，或用 Tailscale

---

2.3 频道与消息问题

❌ 踩坑

消息发了，agent 没有任何回应——但 Gateway 是正常的。很容易误判为连接问题，实际上是路由或策略问题。

✅ 诊断步骤

# 诊断频道问题
openclaw channels status --probe   # 探测所有频道连通性
openclaw channels list             # 查看已配置频道

Telegram 特殊问题：already polling

原因：同一 bot token 同时被多个实例 poll
解决：确认只有一个 Gateway 实例运行

openclaw status --all | grep gateway

---

2.4 Cron 任务不执行

按顺序检查日志关键词

日志关键词	含义	解决方向
scheduler disabled	调度器被禁用	检查 openclaw.json 中 cron.enabled 是否为 true
quiet-hours	静默时间段（不执行任务）	检查 quietHours 配置是否包含当前时间
requests-in-flight	并发任务数超上限	等待当前任务完成，或调高 maxConcurrent
unknown accountId	账号 ID 配置错误	重新检查 cron job 的 accountId 字段

💡 关键提示

Cron 任务必须配置 sessionTarget: 'isolated'，否则后台任务的工具输出会追加到主 session 历史，下次对话时 agent 需要处理大量无关数据。

---

2.5 Linux 无头浏览器控制

❌ 踩坑

在无显示器的 Linux 服务器上，浏览器控制功能报错：

cannot open display

✅ 解决：安装虚拟显示器

# 安装并启动虚拟显示器
sudo apt-get install xvfb
Xvfb :99 -screen 0 1024x768x24 &
export DISPLAY=:99
openclaw gateway start

---

← 上一章：安装踩坑 | 返回目录 | 下一章：工作区文件体系 →