OpenClaw 频道连接故障排查大全

2026-01-04 · 12 分钟故障排查

通用诊断工具

在排查任何频道问题之前，先运行 OpenClaw 内置的诊断工具：

openclaw doctor

# 全面健康检查
openclaw doctor

# 输出示例：
# ✓ 配置文件: 有效
# ✓ 模型连接: 正常 (anthropic/claude-sonnet-4-20250514)
# ✗ WhatsApp: 未连接 (会话已过期)
# ✓ Discord: 已连接
# ✓ Slack: 已连接
# ✓ 数据库: 正常
# ✓ 磁盘空间: 充足 (剩余 45GB)

openclaw channels status --probe

对所有已配置频道执行主动探测：

# 探测所有频道
openclaw channels status --probe

# 探测特定频道
openclaw channels status --probe whatsapp

# 输出详细诊断信息
openclaw channels status --probe --verbose

输出示例：

频道状态探测结果：
┌──────────┬────────┬──────────┬───────────────┐
│ 频道     │ 状态   │ 延迟     │ 最后消息      │
├──────────┼────────┼──────────┼───────────────┤
│ WhatsApp │ 已断开 │ -        │ 2小时前       │
│ Discord  │ 已连接 │ 45ms     │ 3分钟前       │
│ Slack    │ 已连接 │ 120ms    │ 15分钟前      │
└──────────┴────────┴──────────┴───────────────┘

WhatsApp 故障排查

问题一：频繁断开连接

WhatsApp 频道使用 Web 协议连接，容易因网络波动或会话过期而断开。

症状：

消息无法发送或接收
日志中出现 connection closed 或 stream:error 错误

排查步骤：

# 1. 查看连接日志
openclaw logs --filter whatsapp.connection --tail 50

# 2. 检查网络连通性
curl -s -o /dev/null -w "%{http_code}" https://web.whatsapp.com

# 3. 重新连接
openclaw channels reconnect whatsapp

解决方案：

{
  channels: {
    whatsapp: {
      // 自动重连配置
      reconnect: {
        enabled: true,
        maxRetries: 10,
        retryInterval: 5000,    // 5 秒
        backoffMultiplier: 2    // 指数退避
      },
      // 保持连接心跳
      keepAlive: {
        interval: 30000         // 30 秒心跳
      }
    }
  }
}

问题二：媒体文件发送失败

症状：

图片、文档等媒体消息发送时报错
日志中出现 media upload failed 或超时错误

排查步骤：

# 1. 检查媒体处理服务
openclaw doctor --check media

# 2. 查看媒体相关错误日志
openclaw logs --filter whatsapp.media --level error

# 3. 测试媒体上传
openclaw channels test whatsapp --media /path/to/test-image.jpg

解决方案：

{
  channels: {
    whatsapp: {
      media: {
        // 增大上传超时时间
        uploadTimeout: 60000,
        // 减小文件大小限制（避免超大文件）
        maxFileSize: "16MB",
        // 自动压缩图片
        autoCompress: true,
        compressionQuality: 80
      }
    }
  }
}

问题三：多设备会话冲突

症状：

在其他设备登录 WhatsApp 后，OpenClaw 连接断开
日志出现 replaced 或 conflict 错误

解决方案：

确保 WhatsApp 的 Web/桌面会话不超过设备限制。OpenClaw 使用独立的连接会话，但仍受多设备数量限制。

# 查看当前活跃会话
openclaw channels info whatsapp --sessions

# 强制重新配对
openclaw channels setup whatsapp --force

Discord 故障排查

问题一：机器人不响应消息

症状：

机器人在线但不回复任何消息
没有错误日志

排查步骤：

# 1. 检查机器人网关连接
openclaw channels status discord --verbose

# 2. 查看事件接收日志
openclaw logs --filter discord.gateway --tail 30

# 3. 确认消息意图配置
openclaw channels info discord --intents

常见原因和解决方案：

消息内容意图未启用

Discord 要求显式启用 Message Content Intent：

访问 Discord Developer Portal
选择你的应用 → Bot → Privileged Gateway Intents
启用 Message Content Intent

{
  channels: {
    discord: {
      // 确保启用必要的意图
      intents: [
        "GUILDS",
        "GUILD_MESSAGES",
        "MESSAGE_CONTENT",      // 关键！
        "DIRECT_MESSAGES"
      ]
    }
  }
}

群组中需要 @ 提及

默认情况下，OpenClaw 在 Discord 群组中需要被 @ 提及才会响应：

{
  channels: {
    discord: {
      trigger: {
        // 群组中需要 @机器人 才响应
        requireMention: true,
        // 或使用前缀触发
        prefix: "!oc",
        // 私聊不需要提及
        dmRequireMention: false
      }
    }
  }
}

问题二：隐私模式问题

症状：

某些频道的消息无法接收
私聊消息不响应

排查步骤：

# 检查机器人权限
openclaw channels info discord --permissions

# 列出机器人可访问的频道
openclaw channels info discord --accessible-channels

解决方案：

确保机器人在目标频道有以下权限：

Read Messages / View Channels
Send Messages
Read Message History
Embed Links（用于发送富文本）
Attach Files（用于发送媒体）

问题三：允许列表配置

{
  channels: {
    discord: {
      // 频道白名单（只响应这些频道的消息）
      allowlist: {
        channels: ["channel-id-1", "channel-id-2"],
        // 或按类别限制
        categories: ["category-id-1"],
        // 用户白名单
        users: ["user-id-1", "user-id-2"]
      }
    }
  }
}

Slack 故障排查

问题一：事件订阅不工作

症状：

Slack 应用已安装但收不到消息
事件订阅验证失败

排查步骤：

# 1. 检查 Slack 连接状态
openclaw channels status slack --verbose

# 2. 验证事件订阅 URL
openclaw channels test slack --event-url

# 3. 查看事件接收日志
openclaw logs --filter slack.events --tail 30

解决方案：

确认事件订阅 URL 可达

如果使用 HTTP 模式（Events API），确保回调 URL 公网可达：

# 检查端口开放
curl -s http://your-server:3000/slack/events

# 如果在 NAT 后面，考虑使用 ngrok
ngrok http 3000

切换到 Socket Mode

推荐使用 Socket Mode 避免公网暴露：

{
  channels: {
    slack: {
      mode: "socket",           // socket | http
      appToken: "${SLACK_APP_TOKEN}",
      botToken: "${SLACK_BOT_TOKEN}"
    }
  }
}

问题二：消息格式异常

症状：

Markdown 格式在 Slack 中显示不正确
代码块或链接格式错乱

解决方案：

Slack 使用自己的标记语言（mrkdwn），OpenClaw 会自动转换，但有时需要调整：

{
  channels: {
    slack: {
      formatting: {
        // 自动将 Markdown 转换为 Slack mrkdwn
        autoConvert: true,
        // 使用 Block Kit 富文本
        useBlocks: true,
        // 长消息拆分
        splitLongMessages: true,
        maxMessageLength: 3000
      }
    }
  }
}

问题三：凭据验证

# 测试 Bot Token
curl -s -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
  https://slack.com/api/auth.test | python3 -m json.tool

# 测试 App Token (Socket Mode)
curl -s -H "Authorization: Bearer $SLACK_APP_TOKEN" \
  https://slack.com/api/auth.test | python3 -m json.tool

# 检查 Bot 权限范围
openclaw channels info slack --scopes

所需的 Bot Token Scopes：

app_mentions:read — 接收 @提及
chat:write — 发送消息
channels:history — 读取频道历史
files:read — 读取文件
files:write — 上传文件
im:history — 读取私聊历史

通用排查清单

当遇到任何频道问题时，按以下顺序检查：

# 1. 运行全面诊断
openclaw doctor

# 2. 检查配置文件语法
openclaw config validate

# 3. 查看最近的错误日志
openclaw logs --level error --tail 50

# 4. 检查系统资源
openclaw status --resources

# 5. 确认网络连通性
openclaw channels status --probe --verbose

# 6. 尝试重启特定频道
openclaw channels restart whatsapp
openclaw channels restart discord
openclaw channels restart slack

# 7. 完全重启 OpenClaw
openclaw restart

日志分析技巧

过滤特定频道日志

# 按频道过滤
openclaw logs --filter discord --tail 100

# 按日志级别过滤
openclaw logs --level error --since "1h ago"

# 按关键词搜索
openclaw logs --grep "timeout" --since "24h ago"

# 导出日志用于分析
openclaw logs --since "7d ago" --output /tmp/openclaw-debug.log

保持 OpenClaw 和各频道依赖库的更新，定期运行 openclaw doctor 检查系统健康状态，可以预防大多数连接问题。