8.5 Discord集成

通过官方 Discord Bot Gateway 实现 OpenClaw 与 Discord 的集成，支持私信和服务器文字频道访问。

概述

Discord 集成已就绪，支持通过官方 Discord Bot Gateway 访问私信（DM）和服务器文字频道。该集成提供了完整的机器人功能，包括消息路由、权限管理、斜杠命令等。

快速设置（新手指南）

1. 在 Discord 开发者门户创建 Discord Bot 并复制其 Token
2. 启用 Message Content Intent（必需）和 Server Members Intent（推荐）
3. 通过环境变量 DISCORD_BOT_TOKEN 或配置项 channels.discord.token 设置 Token（配置项优先）
4. 使用消息权限邀请机器人到服务器
5. 启动网关
6. 首次联系时，私信配对默认启用，需批准配对码

最小配置

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN"
    }
  }
}

工作原理

消息路由

• 私信（DM）：合并到 agent:main:main 会话
• 服务器频道：隔离为 agent::discord:channel: 会话
• 群组私信：默认忽略；通过 channels.discord.dm.groupEnabled 启用
• 回复始终返回到源频道

必需的 Intents

• Message Content：读取消息文本（必需）
• Server Members：用于允许列表和用户查找（推荐）

私信策略选项

• "pairing"（默认）：配对模式，1小时后过期
• "open"：配合 allowFrom:["*"] 开放访问
• "allowlist"：仅允许列表中的用户
• "disabled"：禁用私信

服务器（Guild）配置

通过 channels.discord.guilds 按 ID 或简称配置服务器。支持每个频道的细粒度设置：

{
  "channels": {
    "discord": {
      "guilds": {
        "123456789012345678": {
          "channels": {
            "general": {
              "requireMention": true,
              "users": ["allowed_user_id"],
              "skills": ["skill_name"],
              "systemPrompt": "custom prompt"
            }
          }
        }
      }
    }
  }
}

注意：线程（Thread）继承父频道配置，除非明确覆盖。

原生斜杠命令

• commands.native 在 Discord 中默认为 "auto"
• /config set|unset 默认允许；通过 channels.discord.configWrites: false 禁用
• 命令使用隔离的会话键（agent::discord:slash:），而非 main

反应（Reactions）和工具

• Agent 使用 discord 工具处理反应、贴纸、投票、线程、置顶等
• channels.discord.actions.* 控制各项功能；例如 roles: false、moderation: false 默认禁用
• 确认反应由 messages.ackReaction 和 messages.removeAckAfterReply 控制

重试策略

出站调用在遇到 429 错误时，使用 Discord 的 retry_after 进行重试，采用指数退避和抖动算法。可通过 channels.discord.retry 配置。

PluralKit 支持

• 通过 pluralkit.enabled: true 启用；可选 token 用于私有系统
• PK 代理的消息解析为 Member (PK:System)；允许列表接受 pk: 前缀
• 查找依赖原始消息 ID — 仅在 PK 的 30 分钟窗口内有效

故障排除

• "Used disallowed intents"：启用 Message Content Intent 并重启
• 服务器无回复：检查权限、requireMention 或允许列表范围
• 私信失败：验证 dm.enabled、dm.policy 和配对批准
• 始终运行 openclaw doctor 和 openclaw channels status --probe

功能和限制

• 支持文字频道和线程（不支持语音）
• 分块：textChunkLimit（2000字符）、maxLinesPerMessage（17行）、chunkMode="newline" 用于段落拆分
• 文件上传最大 mediaMaxMb（默认 8 MB）
• 回复标签：[[reply_to_current]] 或 [[reply_to:<id>]]，由 replyToMode（off/first/all）控制

安全和运维

重要注意事项

• 顶层的 channels.discord.requireMention 会被忽略 — 必须在 guilds 下设置
• 简称键（如 "help"）为小写，空格用短横线；频道名称省略 #
• channels.discord.guilds.*.channels 默认拒绝未列出的频道
• 默认忽略机器人创作的消息；谨慎设置 allowBots=true
• 如果允许回复其他机器人，需防止机器人间的回复循环

常用命令

# 检查 Discord 渠道状态
openclaw channels status --probe

# 列出配对请求
openclaw pairing list discord

# 批准配对
openclaw pairing approve discord <code>

# 运行诊断
openclaw doctor