概述

一、排查思路

遇到渠道问题时，按以下顺序排查：

1. Gateway 是否运行？
    ↓ 否
    → openclaw gateway start
    ↓ 是
2. 该渠道配置是否正确？
    ↓ 否
    → 重新配置渠道
    ↓ 是
3. 该渠道是否已启用？
    → 检查 enabled: true
4. 权限配置是否正确？
    → 检查 dmPolicy 和 allowFrom
5. 运行诊断命令
    → openclaw doctor

二、所有渠道通用排查

2.1 检查 Gateway 状态

openclaw gateway status

如果 Gateway 未运行： 

openclaw gateway start

如果 Gateway 异常： 

openclaw gateway restart

2.2 运行完整诊断

openclaw doctor

预期输出： 

✅ Gateway: OK
✅ Config: OK
✅ Feishu: OK
✅ DingTalk: OK
...

2.3 查看日志

# 查看最近的错误日志
tail -100 ~/.openclaw/logs/error.log

三、飞书问题排查

问题原因解决方法
飞书消息不回复用户不在白名单将 Open ID 加入 allowFrom
飞书消息不回复机器人未发布飞书开放平台 → 版本管理 → 发布应用
飞书消息不回复事件订阅未配置飞书开放平台 → 事件订阅 → 开启
认证失败App Secret 错误重新获取 App Secret
机器人回复"不认识你"白名单配置问题检查 allowFrom 列表
检查飞书事件订阅是否配置： 飞书开放平台 → 应用 → 事件订阅 → 确认已开启"使用长连接接收事件"

四、钉钉问题排查

问题原因解决方法
钉钉消息不回复Stream 模式断开重启 Gateway
消息发送失败加签密钥错误检查 signKey 配置
机器人无权限CorpId 不匹配检查 corpId 配置
Stream 连接不稳定服务器 IP 变化钉钉要求固定出口 IP

五、企业微信问题排查

问题原因解决方法
企微消息不回复应用未发布企业微信后台 → 应用管理 → 发布
CorpId 错误企业 ID 填错在"我的企业"重新获取
Secret 过期Secret 有有效期重新获取 Secret

六、Telegram 问题排查

问题原因解决方法
Bot 不响应Token 错误重新获取 Bot Token
Bot 不响应需要代理配置 Telegram 代理
Bot 不响应未 @ Bot配置 requireMention: true
消息延迟代理网络慢更换更稳定的代理
检查代理配置： 
"channels": {
  "telegram": {
    "proxy": {
      "enabled": true,
      "url": "http://proxy:1080"
    }
  }
}

七、Discord 问题排查

问题原因解决方法
Bot 不响应缺少权限服务器设置 → 角色 → 分配权限
Bot 不响应Prefix 错误检查 prefix 配置
Bot 不响应Bot 未加入服务器重新邀请 Bot
消息回复慢网络延迟检查代理配置

八、网络问题排查

8.1 测试网络连通性

# 测试到飞书服务器
curl -I https://open.feishu.cn
# 测试到钉钉服务器
curl -I https://api.dingtalk.com
# 测试到 MiniMax API
curl -I https://api.minimaxi.com

8.2 代理设置

如果需要代理，在配置文件中添加：

"proxy": {
  "enabled": true,
  "url": "http://proxy.example.com:8080",
  "username": "user",
  "password": "pass"
}

九、诊断命令汇总

命令用途
openclaw gateway status查看 Gateway 运行状态
openclaw gateway start启动 Gateway
openclaw gateway restart重启 Gateway
openclaw doctor运行完整诊断
openclaw configure重新配置渠道

十、无法解决怎么办

如果以上排查都无法解决：

1. 查看完整日志：~/.openclaw/logs/ 2. 重启 Gateway：openclaw gateway restart 3. 在群里提问：提供 openclaw doctor 的输出和具体问题描述

十一，问题记录模板

提问时请提供以下信息：

【问题描述】
发送 XX 消息后，AI 不回复
【错误信息】
（如果有的话，截图或复制错误信息）
【openclaw doctor 输出】
（运行诊断命令的完整输出）
【已尝试的解决方法】
1. 重启 Gateway ✅/❌
2. 检查白名单 ✅/❌
3. ...

十二，下一步学什么

  • 第四章：模型配置 → 了解更多模型配置
  • 第六章：进阶功能 → 了解更多高级功能
  • 第七章：实战案例 → 学习实际应用场景

遇到问题不要慌，80%的问题通过以上排查都能解决！解决不了的在群里问 💪

常见问题

Q: 问题排查顺序？
A: 网络 → 凭证 → 权限 → 日志。