二、消息平台问题
📌 本节包含 10 个问题：Q16: WhatsApp 频繁断开 | Q17: Telegram Bot 不响应 | Q18: Telegram 群组不回复 | Q19: Discord Bot 无法加入 | Q20: 消息延迟严重 | Q21: rate limited | Q22: 飞书收不到消息 | Q23: 控制面板打不开 | Q24: 多账号接入 | Q25: 图片文件处理
Q1: WhatsApp 扫码后频繁断开
现象： 扫码配对成功，但过一会儿就断开，需要反复扫码。
原因： WhatsApp Web 协议要求手机端保持在线。如果手机网络不稳定或 WhatsApp 应用被系统杀后台，连接就会断。
解决方案：
# 第一步：把 Gateway 安装为系统服务，保持持续运行
openclaw daemon
# 第二步：检查连接状态
openclaw channels status whatsapp
# 第三步：如果断开了，重新连接
openclaw channels logout whatsapp
openclaw channels login whatsapp
# 第四步：查看断开原因
openclaw logs --limit 50 | grep whatsapp其他注意事项：
- 确保手机上的 WhatsApp 没有被省电模式限制后台运行
- 一个 WhatsApp 账号只能同时连接一个 Web 客户端，如果你在浏览器里也开了 WhatsApp Web，会冲突
- 建议用一个专门的手机号来跑 OpenClaw
Q2: Telegram Bot 不响应消息
现象： 给 Telegram Bot 发消息，没有任何回复。
原因： 可能是 Bot Token 配置错误、Bot 没有接收消息的权限、或者 Gateway 没有正常运行。
解决方案：
# 第一步：确认 Gateway 在运行
openclaw status
# 第二步：确认 Bot Token 正确
openclaw config get channels.telegram.botToken
# 去 @BotFather 核对 Token 是否一致
# 第三步：确认 Bot 的隐私模式
# 在 @BotFather 中：
# /mybots → 选择你的 Bot → Bot Settings → Group Privacy → Turn off
# 关闭隐私模式后，Bot 才能接收群组中的所有消息
# 第四步：检查日志
openclaw logs --limit 50 | grep telegram
# 第五步：重新连接
openclaw channels logout telegram
openclaw channels login telegramQ3: Telegram Bot 在群组中不回复
现象： Bot 在私聊中正常回复，但在群组中不响应。
原因： Telegram Bot 默认开启隐私模式，在群组中只能收到 @提及 和 /命令。
解决方案：
- 在 @BotFather 中关闭隐私模式（见 Q17）
- 或者在群组中 @提及 Bot 来触发回复
- 在群组配置中设置激活模式（通过聊天命令
/activation mention或/activation always切换）
Q4: Discord Bot 无法加入服务器
现象： 用邀请链接添加 Bot 时报错 Missing Permissions。
原因： Bot 的 OAuth2 权限配置不完整。
解决方案：
- 去 Discord Developer Portal
- 选择你的应用 → OAuth2 → URL Generator
- 勾选以下权限：
botapplications.commandsSend MessagesRead Message HistoryEmbed LinksAttach Files
- 用生成的新链接重新邀请 Bot
# 配置 Discord Bot Token（注意：Discord 用的字段是 token，不是 botToken）
openclaw config set channels.discord.token "your-discord-bot-token"
openclaw channels logout discord
openclaw channels login discordQ5: 消息延迟严重（发了好久才回复）
现象： 发消息后要等 10 秒甚至更久才收到回复。
原因： 延迟可能来自多个环节 — 网络、模型 API 响应时间、消息队列积压。
解决方案：
# 第一步：排查是哪个环节慢
openclaw logs --limit 20
# 看日志中的时间戳，判断延迟发生在哪里
# 第二步：测试模型 API 延迟
openclaw health
# 如果 API 延迟高，考虑换模型或换提供商
# 第三步：检查是否有消息积压
openclaw sessions list
# 第四步：优化措施
# 使用更快的模型
openclaw config set agents.defaults.model "openai/gpt-5.2-mini"
# 减少系统提示词长度（Token 越少，响应越快）
# 精简 ~/.openclaw/workspace/SOUL.md 的内容Q6: 消息发送失败，提示 "rate limited"
现象： 发消息时报错 429 Too Many Requests 或 rate limited。
原因： 消息平台有发送频率限制。WhatsApp 尤其严格，短时间内发太多消息会被限流。
解决方案：
# 消息平台的限流是平台侧限制，OpenClaw 没有内置速率限制配置
# 解决方案：
# 1. 减少消息发送频率，避免触发平台限流
# 2. 等待限流解除后自动重试
# 3. 如果是 API 限流（429），参考 Q27 配置模型故障转移Q7: 飞书（Feishu/Lark）接入后收不到消息
现象： 飞书 Bot 配置完成，但收不到用户消息。
原因： 飞书的事件订阅配置不完整，或者回调地址不可达。
解决方案：
# 第一步：确认 Gateway 的公网地址可达
curl https://your-domain.com:18789/health
# 第二步：在飞书开放平台配置事件订阅
# 事件订阅 URL：https://your-domain.com:18789/webhook/feishu
# 需要订阅的事件：im.message.receive_v1
# 第三步：检查日志
openclaw logs --limit 50 | grep feishu
# 第四步：确认 Bot 权限
# 飞书开放平台 → 应用权限 → 确保开启了：
# - 获取与发送单聊、群组消息
# - 读取用户信息Q8: 控制面板（Dashboard）打不开
现象： 浏览器访问 http://localhost:18789 显示无法连接。
原因： Gateway 没有运行，或者端口被防火墙拦截。
解决方案：
# 第一步：确认 Gateway 在运行
openclaw status
# 如果没运行，启动它
openclaw gateway --port 18789
# 第二步：检查端口
# Linux / macOS
lsof -i :18789
# Windows
netstat -an | findstr 18789
# 第三步：如果是远程服务器，检查防火墙
# Ubuntu
sudo ufw allow 18789
# CentOS
sudo firewall-cmd --add-port=18789/tcp --permanent
sudo firewall-cmd --reload
# 第四步：重启 Gateway（停止后重新启动，或使用聊天命令 /restart）
openclaw gateway --port 18789Q9: 同一个平台能接入多个账号吗？
说明： 可以。OpenClaw 支持同一平台的多个 Channel 实例。
# 添加第二个 WhatsApp 账号
openclaw channels add whatsapp --name "work-whatsapp"
openclaw channels add whatsapp --name "personal-whatsapp"
# 查看所有 Channel
openclaw channels list每个 Channel 独立运行，有自己的配对状态和消息队列。
Q10: 消息中的图片/文件 AI 能处理吗？
说明： 取决于你使用的模型和当前 provider 目录。支持多模态的模型可以处理图片；具体型号不要背教程，以 openclaw 当前 models / onboarding 显示为准。
# 多模态能力取决于你使用的模型，不需要额外配置
# 支持多模态的模型会自动处理图片；具体型号以当前模型目录为准
# 文件大小限制取决于消息平台本身的限制不支持多模态的模型收到图片时，会提示用户发送文字。