🦞OpenClaw ClawBook
文档导航

故障排查

遇到问题时，按照以下流程快速定位根因。大多数问题都可以在 60 秒内确定方向。

60 秒诊断流程

按优先级依次执行，每一步都能排除一类问题：

# 1. 总体状态（最重要的第一步）
openclaw status
openclaw status --all

# 2. 网关探测
openclaw gateway probe
openclaw gateway status

# 3. 全面诊断
openclaw doctor

# 4. 渠道连接检查
openclaw channels status --probe

# 5. 实时日志（看最新错误）
openclaw logs --follow

Bot 不回复消息

检查清单

  1. Gateway 是否运行？
    openclaw gateway status — 如果没有运行，启动它
  2. 渠道是否连接？
    openclaw channels status --probe — 检查目标渠道是否在线
  3. 模型认证是否有效？
    openclaw models status — API Key 可能过期或额度用完
  4. 是否被 DM Policy 拦截？
    如果设置了 pairing，新用户需要先完成配对：openclaw pairing list
  5. 群聊是否需要 @mention？
    大部分渠道群聊默认需要 @mention 触发，检查 requireMention 配置

Gateway 无法启动

  • 配置校验失败：Gateway 对未知字段零容忍。 运行 openclaw doctor --fix 修复，或 openclaw config validate 查看具体错误
  • 端口被占用：默认 18789 可能被其他进程占用。 用 lsof -i :18789 检查，或换端口 --port 18790
  • 权限问题：检查 ~/.openclaw 目录权限，确保当前用户可读写
  • Secret 解析失败：活跃的 SecretRef 未能解析会阻止启动。 运行 openclaw secrets audit --check

Dashboard 无法连接

  • 确认 Gateway 正在运行：openclaw gateway status
  • 确认端口正确：默认 http://127.0.0.1:18789
  • 检查是否有认证问题：首次访问需要输入凭据
  • 远程访问需要通过 Tailscale / SSH 隧道，不能直接用公网 IP

渠道相关问题

WhatsApp

  • QR 码过期：重新运行 openclaw channels login whatsapp
  • 已关联但断开连接：运行 openclaw doctor 或重启 Gateway
  • Bun 运行时不可靠，请使用 Node 运行 Gateway
  • 详细指南：WhatsApp 接入

Telegram

  • Bot Token 无效：在 @BotFather 中检查或重新生成
  • 群组不响应：检查 /setprivacy 是否 Disable，机器人是否重新添加
  • IPv6 问题导致静默停止：在 /etc/hosts 中添加 IPv4 解析
  • 详细指南：Telegram 接入

Discord

  • Bot 权限不足：确认 Bot 有 MESSAGE_CONTENT Intent 和对应频道权限
  • Gateway Intent 未开启：Discord Developer Portal 中需要手动开启
  • requireMention 必须放在 guilds 下，顶层会被忽略
  • 详细指南：Discord 接入

飞书

  • 确认应用已发布并审批通过
  • 检查事件订阅配置了 im.message.receive_v1 且选择了长连接模式
  • 详细指南：飞书接入

模型认证问题

401 错误 / Token 失效

  • Anthropic 订阅：重新运行 claude setup-token 并在 Gateway 主机上粘贴
  • OpenAI Codex：重新运行 openclaw models auth login --provider openai-codex
  • API Key：检查额度是否用完，用 openclaw models status --check 验证

No API key found

认证是按 Agent 的，新 Agent 不会继承密钥。为该 Agent 重新运行引导。

All profiles in cooldown

检查 openclaw models status --json 中的 unusableProfiles，添加备用 Provider 或等待冷却。

调试工具

高级调试手段：

# 运行时调试覆盖
/debug                  # 在聊天中发送

# Gateway watch 模式（快速迭代）
openclaw gateway --watch

# Dev Profile 隔离
openclaw gateway --dev

# 原始流日志
openclaw logs --follow --raw

# 重置（全新开始）
openclaw reset

Cron / Heartbeat 问题

  • openclaw cron list 检查任务状态，被禁用的任务不会执行
  • 永久错误（如认证失败）会自动禁用任务，需修复后手动重新启用
  • 检查 cron.enabled: true 是否在配置中开启
  • Heartbeat 需要配置目标渠道才能投递

浏览器工具问题

  • 确认 Chrome/Chromium 已安装且可被发现
  • Linux 无头服务器需安装 chromium-browser 和相关依赖库
  • 沙箱内使用浏览器需要在 Docker 镜像中包含 Chromium
  • 端口范围 18800-18899 被浏览器 Profile 使用，确保未被占用

实用诊断命令汇总

# 综合诊断
openclaw doctor
openclaw doctor --fix

# 状态总览
openclaw status --all

# 渠道探测
openclaw channels status --probe

# 模型认证检查
openclaw models status --check

# 安全审计
openclaw security audit --deep

# Secret 审计
openclaw secrets audit --check

# 实时日志
openclaw logs --follow

# 版本检查
openclaw --version

排障心法

  • 永远从 openclaw status 开始，它能展示 90% 的问题
  • openclaw doctor --fix 能自动修复大多数配置和环境问题
  • 渠道问题先检查登录态和 Token，再检查网络
  • 配置修改后不生效？检查热更新模式，或手动重启 Gateway
  • 日志是最终真相——openclaw logs --follow 看实时错误
← CLI 参考返回文档总览