渠道故障排查 - 常见问题诊断

本文档提供 OpenClaw 各渠道（Channel）的系统性故障排查指南。当你的 Bot 出现异常时，请按照以下步骤逐一排查。

通用诊断流程

无论使用哪个渠道，遇到问题时请首先执行以下命令：

第一步：验证运行时状态

bash

openclaw status

正常输出应包含：

Runtime:    running
Gateway:    connected
Uptime:     2h 15m
Channels:   5 active, 0 error

第二步：运行系统诊断

bash

openclaw doctor

openclaw doctor 会自动检测常见配置错误、依赖缺失和网络问题。

第三步：渠道探针检测

bash

openclaw channels status --probe

此命令会主动探测每个已启用渠道的连接状态，输出示例：

Channel         Status      Probe       Latency
─────────────────────────────────────────────────
telegram        active      ok          85ms
discord         active      ok          120ms
slack           active      ok          95ms
whatsapp        active      ok          200ms
signal          error       timeout     -

健康基线

一个正常运行的 OpenClaw 实例应满足：

Runtime: running
Gateway: connected
RPC probe: ok
各渠道 Probe: ok，延迟 < 500ms

第四步：查看实时日志

bash

openclaw logs --follow

查看特定渠道日志：

bash

openclaw logs --channel <channel-name> --follow

日志级别

增加日志详细程度以获得更多信息：

bash

openclaw logs --level debug --follow

逐渠道故障排查

已连接但 DM 无回复

确认发送者已通过 Pairing（配对）：openclaw pairing list --channel whatsapp
如未配对，批准配对：openclaw pairing approve whatsapp <code>
检查 dmPolicy 设置是否为 pairing 或 open

群组消息被忽略

检查 requireMention 是否为 true — 如果是，需要 @Bot 才会响应
确认群组在 allowGroups 白名单中，或 allowAll 为 true
查看日志确认消息是否被接收但被过滤

WhatsApp Web 随机断连

确认手机与 Gateway 保持网络连接
重新扫码登录：openclaw channel reconnect whatsapp
检查手机 WhatsApp 是否弹出 "此设备不活跃" 提示
确保不要在其他浏览器中同时打开 WhatsApp Web

/start 无回复

确认发送者已配对：openclaw pairing list --channel telegram
批准配对：openclaw pairing approve telegram <code>
确认 Bot Token 有效：openclaw logs --channel telegram

群组中 Bot 静默

在 BotFather 中发送 /setprivacy 选择 Disable（关闭隐私模式）
或将 Bot 设为群组管理员
确认 groups 配置包含该群组 Chat ID 或使用了 * 通配符

网络连接错误

检查 DNS 解析：nslookup api.telegram.org
检查代理配置：中国大陆必须配置 channels.telegram.proxy
尝试使用 Webhook 模式替代 Polling

Discord

Server 中无回复

确认 Server ID 在 allowGuilds 中，或留空允许所有
确认 Bot 有 Send Messages 和 Read Message History 权限
必须开启 Message Content Intent — 这是最常见的遗漏

群组消息被忽略

需要 @Bot 才会在 Channel 中响应（如配置了 requireMention）
确认 Bot 在目标 Channel 有可见权限

DM 无回复

确认发送者已配对：openclaw pairing list --channel discord
确认 Bot 的 DM 功能未被 Discord 禁用
确认 dmPolicy 配置正确

Slack

Socket Mode 已连接但无响应

确认 Bot Token (xoxb-) 和 App Token (xapp-) 都正确配置
在 Slack App 配置中确认 Event Subscriptions 已启用
确认订阅了 message.im 和 message.channels 事件

DM 被阻止

检查 Pairing 列表：openclaw pairing list --channel slack
批准配对或将用户添加到 allowFrom
确认 Slack App 有 chat:write 和 im:history Scope

Channel 消息被忽略

将 Bot 邀请到目标 Channel：/invite @bot_name
确认 allowChannels 包含目标 Channel ID 或留空
检查 requireMention 设置

iMessage / BlueBubbles

无法接收新消息

确认 BlueBubbles Server 正在运行
确认 Webhook URL 可达：curl https://your-gateway/bluebubbles/webhook
确认 Mac 上的 iMessage 已登录且正常工作

macOS 权限问题

重新授权 Full Disk Access：System Settings > Privacy > Full Disk Access
重新授权 Accessibility：System Settings > Privacy > Accessibility
重启 BlueBubbles Server 后生效

DM 被阻止

确认发送者已配对：openclaw pairing list --channel bluebubbles
批准配对或检查 allowFrom 列表

Signal

Daemon 可达但无响应

确认 signal-cli daemon 正在运行且 Socket 路径正确
验证 daemon URL/Socket：ls -la /tmp/signal-cli.sock
确认 signal-cli 账号已注册或关联

DM 被阻止

检查 Pairing 列表：openclaw pairing list --channel signal
批准配对或添加到 allowFrom

群组消息不响应

确认群组 ID 在 allowGroups 中
添加群组或发送者：openclaw groups add signal <group-id>
查看群组列表：signal-cli -a +1234567890 listGroups

Matrix

忽略房间消息

确认 Room ID 在 allowRooms 列表中或 allowAll 为 true
确认 groupPolicy 配置包含该房间
确认 Bot 已加入该房间

DM 无回复

确认发送者 Matrix ID 已配对或在 allowFrom 中
批准配对：openclaw pairing approve matrix <code>

加密房间消息无法解读

确认 encryption: true 已启用
完成 Device Verification（在 Element 中验证 Bot 设备）
检查加密密钥存储：ls ~/.openclaw/matrix-store/

飞书 (Feishu)

收不到事件

确认事件订阅模式正确（推荐 长连接模式）
如使用 Webhook 模式，确认回调地址可达且通过了验证
在飞书开放平台检查事件订阅是否已启用

API 权限不足

确认应用拥有必要的权限范围（Scope）
常见所需权限：im:message、im:message.group_at_msg
在飞书管理后台确认应用已发布并被可见

企业微信 (WeCom)

回调验证失败

确认 Token 和 EncodingAESKey 与企业微信后台配置一致
确认回调 URL 可从公网访问
检查是否有 URL 编码问题

无法接收消息

确认服务器 IP 在企业微信的 IP 白名单 中
进入应用管理 > 企业可信 IP 添加 Gateway 的公网 IP
确认应用的可见范围包含目标用户

钉钉 (DingTalk)

签名验证失败

确认 appSecret 与钉钉开放平台配置一致
检查服务器时钟是否同步（时间偏差超过 1 小时会验证失败）
重新生成签名密钥

回调响应超时

钉钉回调要求 3 秒内 返回响应
确保 Gateway 先返回 200 再异步处理消息
检查 Gateway 到 AI 模型的响应时间

日志分析

常见日志模式

bash

# 查看错误日志
openclaw logs --level error --follow

# 查看特定渠道的调试日志
openclaw logs --channel telegram --level debug --follow

# 导出日志到文件
openclaw logs --since 1h > /tmp/openclaw-debug.log

常见错误码

错误码	含义	解决方案
`CHAN_AUTH_FAILED`	渠道认证失败	检查 Token/密钥是否正确
`CHAN_CONN_TIMEOUT`	连接超时	检查网络和代理配置
`CHAN_RATE_LIMITED`	被平台限流	降低消息频率，等待限流解除
`CHAN_WEBHOOK_FAIL`	Webhook 回调失败	检查回调 URL 可达性
`PAIR_NOT_FOUND`	配对记录不存在	用户需先发起配对
`PAIR_REJECTED`	配对被拒绝	检查配对策略和白名单
`MSG_TOO_LONG`	消息超过平台限制	启用自动分段或减少响应长度
`SESSION_EXPIRED`	会话/Token 过期	刷新 Token 或重新登录

网络诊断

bash

# 检查 Gateway 到外部服务的连通性
openclaw doctor --network

# 测试特定渠道的网络连通性
openclaw channels test <channel-name>

# DNS 解析检查
nslookup api.telegram.org
nslookup discord.com
nslookup slack.com

代理问题排查

如果使用代理访问外部服务：

bash

# 验证代理连通性
curl -x http://your-proxy:port https://api.telegram.org/bot<token>/getMe

# 环境变量代理（全局）
export HTTP_PROXY="http://your-proxy:port"
export HTTPS_PROXY="http://your-proxy:port"

快速修复清单

重启前检查

在重启 Gateway 之前，先确认问题不是配置错误。盲目重启可能导致 Session 丢失（如 WhatsApp、Zalo）。

检查配置：openclaw config validate — 验证配置文件语法
检查状态：openclaw status — 确认 Runtime 运行正常
检查渠道：openclaw channels status --probe — 探测各渠道连接
检查配对：openclaw pairing list — 确认用户配对状态
查看日志：openclaw logs --level debug --follow — 查找具体错误
重启渠道：openclaw channel reconnect <name> — 重连单个渠道
重启 Gateway：openclaw gateway restart — 最后手段

🇨🇳 中国用户须知

中国大陆用户在排查网络问题时需特别注意以下几点：

国际渠道代理：Telegram、Discord、Signal、WhatsApp、LINE、Twitch 等国际平台在中国大陆无法直接访问或访问不稳定，务必配置代理。

国内渠道优先：企业微信、钉钉、飞书等国内平台无需代理，且在国内网络环境下延迟最低。

DNS 污染：部分国际域名可能受 DNS 污染影响，建议使用 DoH（DNS over HTTPS）或指定可靠的 DNS 服务器。

服务器部署建议：

仅使用国内渠道 → 国内云服务器
仅使用国际渠道 → 海外云服务器
混合使用 → 海外服务器 + 国内渠道通过公网回调

常用诊断命令：

bash

# 测试代理连通性
curl -x socks5://127.0.0.1:1080 https://api.telegram.org

# 检查端口是否被封
telnet api.telegram.org 443

# 查看实际出口 IP
curl ifconfig.me

渠道故障排查 - 常见问题诊断 ​

通用诊断流程 ​

第一步：验证运行时状态 ​

第二步：运行系统诊断 ​

第三步：渠道探针检测 ​

第四步：查看实时日志 ​

逐渠道故障排查 ​

WhatsApp ​

已连接但 DM 无回复 ​

群组消息被忽略 ​

WhatsApp Web 随机断连 ​

Telegram ​

/start 无回复 ​

群组中 Bot 静默 ​

网络连接错误 ​

Discord ​

Server 中无回复 ​

群组消息被忽略 ​

DM 无回复 ​

Slack ​

Socket Mode 已连接但无响应 ​

DM 被阻止 ​

Channel 消息被忽略 ​

iMessage / BlueBubbles ​

无法接收新消息 ​

macOS 权限问题 ​

DM 被阻止 ​

Signal ​

Daemon 可达但无响应 ​

DM 被阻止 ​

群组消息不响应 ​

Matrix ​

忽略房间消息 ​

DM 无回复 ​

加密房间消息无法解读 ​

飞书 (Feishu) ​

收不到事件 ​

API 权限不足 ​

企业微信 (WeCom) ​

回调验证失败 ​

无法接收消息 ​

钉钉 (DingTalk) ​

签名验证失败 ​

回调响应超时 ​

日志分析 ​

常见日志模式 ​

常见错误码 ​

网络诊断 ​

代理问题排查 ​

快速修复清单 ​

渠道故障排查 - 常见问题诊断

通用诊断流程

第一步：验证运行时状态

第二步：运行系统诊断

第三步：渠道探针检测

第四步：查看实时日志

逐渠道故障排查

WhatsApp

已连接但 DM 无回复

群组消息被忽略

WhatsApp Web 随机断连

Telegram

/start 无回复

群组中 Bot 静默

网络连接错误

Discord

Server 中无回复

群组消息被忽略

DM 无回复

Slack

Socket Mode 已连接但无响应

DM 被阻止

Channel 消息被忽略

iMessage / BlueBubbles

无法接收新消息

macOS 权限问题

DM 被阻止

Signal

Daemon 可达但无响应

DM 被阻止

群组消息不响应

Matrix

忽略房间消息

DM 无回复

加密房间消息无法解读

飞书 (Feishu)

收不到事件

API 权限不足

企业微信 (WeCom)

回调验证失败

无法接收消息

钉钉 (DingTalk)

签名验证失败

回调响应超时

日志分析

常见日志模式

常见错误码

网络诊断

代理问题排查

快速修复清单