古法编程

Appearance

本页提供完整的 OpenClaw Discord 集成步骤：从创建 Discord 应用、获取 Bot Token，到配对私信并配置服务器工作空间。关键操作：设置 DISCORD_BOT_TOKEN 环境变量，使用 openclaw config patch 注入配置，再通过私信完成配对。排查时运行 openclaw doctor 和 openclaw channels status --probe。支持语音频道、交互组件、多账号及基于角色的 Agent 路由。

OpenClaw Discord Bot 配置与故障排查 ​

Discord Bot 集成状态：通过官方 Discord Gateway 支持私信和服务器频道。默认使用配对模式（dmPolicy 为 pairing），服务器频道需配置白名单。

快速设置：创建 Discord Bot 并接入 OpenClaw ​

你需要创建一个带 Bot 的 Discord 应用，添加到你的服务器，然后与 OpenClaw 配对。推荐添加到自己的私人服务器。若没有服务器，先创建一个（选择 Create My Own > For me and my friends）。

1. 创建 Discord 应用和 Bot ​

前往 Discord Developer Portal，点击 New Application，命名为 "OpenClaw" 等名称。侧边栏点击 Bot，设置 Username 为你的 Agent 名称。

2. 启用特权 Intent ​

在 Bot 页面向下滚动到 Privileged Gateway Intents，启用：

  • Message Content Intent（必需）
  • Server Members Intent（推荐；角色白名单和名称-ID 解析需要）
  • Presence Intent（可选，仅用于在线状态更新）

3. 复制 Bot Token ​

在 Bot 页面点击 Reset Token（实际是生成第一个 Token），复制保存。这是你的 Bot Token，稍后用于 OpenClaw 配置。

4. 生成邀请 URL 并添加 Bot 到服务器 ​

侧边栏点击 OAuth2，在 OAuth2 URL Generator 中启用：

  • bot
  • applications.commands

下方 Bot Permissions 至少启用：

  • View Channels
  • Send Messages
  • Read Message History
  • Embed Links
  • Attach Files
  • Add Reactions（可选）

若需要在 Discord 线程中发消息（包括论坛/媒体频道），额外启用 Send Messages in Threads。复制底部 URL 访问，选择你的服务器完成添加。

5. 启用开发者模式并收集 ID ​

在 Discord 应用中：

  1. 用户设置 → Advanced → 开启 Developer Mode
  2. 右键服务器图标 → Copy Server ID
  3. 右键自己头像 → Copy User ID

保存 Server ID 和 User ID，与 Bot Token 一起备用。

6. 允许服务器成员发私信 ​

右键服务器图标 → Privacy Settings → 开启 Direct Messages。配对完成后可关闭（仅用服务器频道时）。

7. 安全设置 Bot Token（不要在聊天中发送） ​

在运行 OpenClaw 的机器上设置环境变量：

bash
export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
cat > discord.patch.json5 <<'JSON5'
{
  channels: {
    discord: {
      enabled: true,
      token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
    },
  },
}
JSON5
openclaw config patch --file ./discord.patch.json5 --dry-run
openclaw config patch --file ./discord.patch.json5
openclaw gateway

若 OpenClaw 已作为后台服务运行，重启服务或执行 openclaw gateway install（确保环境变量可用）。如果主机被 Discord 启动查询限流，设置 channels.discord.applicationId 跳过 REST 调用。

8. 配置 OpenClaw 并配对 ​

通过 Agent 配置（已有其他渠道时）：

"I already set my Discord bot token in config. Please finish Discord setup with User ID &lt;user_id&gt; and Server ID &lt;server_id&gt;."

通过 CLI / 配置文件：

json5
{
  channels: {
    discord: {
      enabled: true,
      token: {
        source: "env",
        provider: "default",
        id: "DISCORD_BOT_TOKEN",
      },
    },
  },
}

环境变量回退：DISCORD_BOT_TOKEN=...。支持 SecretRef 多账号配置（见下）：

json5
{
  channels: {
    discord: {
      enabled: true,
      accounts: {
        personal: {
          token: { source: "env", provider: "default", id: "DISCORD_PERSONAL_TOKEN" },
          applicationId: "111111111111111111",
        },
        work: {
          token: { source: "env", provider: "default", id: "DISCORD_WORK_TOKEN" },
          applicationId: "222222222222222222",
        },
      },
    },
  },
}

9. 审批第一次私信配对 ​

Gateway 启动后，向 Bot 发私信。Bot 会回复一个配对码。将配对码发送给 Agent（通过其他渠道）或使用 CLI：

bash
openclaw pairing list discord
openclaw pairing approve discord <CODE>

配对码 1 小时后过期。完成后即可在 Discord 私信中与 Agent 聊天。

Token 解析：配置中的 Token 值优先于环境变量回退。DISCORD_BOT_TOKEN 仅用于默认账号。若两个启用的 Discord 账号解析到相同 Token，OpenClaw 只启动一个 Gateway 监听器。

推荐：配置 Discord 服务器工作区 ​

私信正常工作后，将 Discord 服务器设置为完整工作区，每个频道拥有独立 Agent 会话和上下文。

1. 将服务器加入 Guild 白名单 ​

json5
{
  channels: {
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        YOUR_SERVER_ID: {
          requireMention: true,
          users: ["YOUR_USER_ID"],
        },
      },
    },
  },
}

2. 允许无 @提及回复 ​

默认只对 @提及回复。私人服务器可取消：

json5
{
  channels: {
    discord: {
      guilds: {
        YOUR_SERVER_ID: {
          requireMention: false,
        },
      },
    },
  },
}

若需要 Agent 潜伏并在认为有用时才回复，设置 messages.groupChat.visibleReplies: "message_tool"（需要最新模型支持）。

3. 规划频道内存 ​

长期记忆（MEMORY.md）默认只在私信会话加载。服务器频道不会自动加载。可将稳定指令放在 AGENTS.md 或 USER.md 中（注入所有会话），长期笔记放在 MEMORY.md 中通过记忆工具按需访问。

运行时模型 ​

  • Gateway 拥有 Discord 连接
  • 回复路由确定：Discord 入站回复回到 Discord
  • 私信共享 Agent 主会话（session.dmScope=main 下）
  • 服务器频道使用独立会话密钥：agent:<agentId>:discord:channel:<channelId>
  • 群组私信默认忽略（channels.discord.dm.groupEnabled=false）
  • 原生 Slash 命令在独立命令会话中运行，但携带 CommandTargetSessionKey 到路由对话

论坛频道 ​

Discord 论坛和媒体频道只接受线程帖子。两种创建方式：

  • 向论坛父频道发消息（channel:<forumId>）自动创建线程，标题使用消息第一个非空行
  • 使用 openclaw message thread create 直接创建（不要传 --message-id）

示例：

bash
openclaw message send --channel discord --target channel:<forumId> \
  --message "Topic title\nBody of the post"

论坛父频道不接受 Discord 组件；如需组件，向线程本身发送（channel:<threadId>）。

交互组件 ​

OpenClaw 支持 Discord Components v2 容器。通过消息工具发送 components 载荷，交互结果作为普通入站消息路由回 Agent。

支持的块类型：text、section、separator、actions、media-gallery、file。操作行最多 5 个按钮或一个选择菜单（类型：string、user、role、mentionable、channel）。

默认组件单次使用。设置 components.reusable=true 允许多次使用。allowedUsers 限制按钮点击者。

组件回调默认 30 分钟过期，可通过 channels.discord.agentComponents.ttlMs 调整（最大 86400000 毫秒）。

/model 和 /models 命令打开交互式模型选择器。模态表单支持 text、checkbox、radio、select、role-select、user-select 字段。

完整示例见原文。

访问控制和路由 ​

DM 策略 ​

channels.discord.dmPolicy 控制私信访问（旧版 channels.discord.dm.policy 仍兼容）：

  • pairing（默认）
  • allowlist
  • open（需 allowFrom 包含 "*"）
  • disabled

DM 目标格式：user:&lt;id&gt; 或 <@id>。裸数字 ID 在 DM 上下文中被作为用户目标处理（当列在 allowFrom 时）。

访问组（Access Groups） ​

支持动态和静态访问组。例如，允许 #maintainers 频道可见的用户发私信：

json5
{
  accessGroups: {
    maintainers: {
      type: "discord.channelAudience",
      guildId: "1456350064065904867",
      channelId: "1456744319972282449",
    },
  },
  channels: {
    discord: {
      dmPolicy: "allowlist",
      allowFrom: ["accessGroup:maintainers"],
    },
  },
}

需要启用 Server Members Intent。

Guild 策略 ​

channels.discord.groupPolicy：

  • open
  • allowlist（推荐，存在 channels.discord 时默认）
  • disabled

allowlist 行为：guild 必须匹配 channels.discord.guilds 中的 ID 或 slug；可选用户/角色白名单；若配置了 channels，未列出频道被拒绝。

基于角色的 Agent 路由 ​

使用 bindings[].match.roles 按角色 ID 路由：

json5
{
  bindings: [
    {
      agentId: "opus",
      match: { channel: "discord", guildId: "123456789012345678", roles: ["111111111111111111"] },
    },
    { agentId: "sonnet", match: { channel: "discord", guildId: "123456789012345678" } },
  ],
}

原生命令和命令授权 ​

  • commands.native 默认 "auto"，Discord 已启用
  • 覆盖：channels.discord.commands.native
  • 禁用原生命令不会自动删除已注册的命令，需手动在 Discord 应用管理移除
  • 授权与普通消息相同的白名单/策略

Slash 命令默认 ephemeral: true。详细目录见 Slash 命令。

功能详情 ​

回复标签和原生回复 ​

支持 [[reply_to_current]] 和 [[reply_to:&lt;id&gt;]]。channels.discord.replyToMode 控制：

  • off（默认）：禁用隐式回复串，但显式标签仍生效
  • first：仅第一则消息附加原生回复
  • all
  • batched：仅在入站是批次聚合时附加

链接预览 ​

默认 OpenClaw 抑制 Discord 自动生成的 URL 嵌入。设置 channels.discord.suppressEmbeds: false 允许展开。消息工具可单次覆盖。

实时流式预览 ​

channels.discord.streaming 控制流式编辑：off（默认）| partial | block | progress。progress 模式支持工具进度显示。详细配置见原文。

历史上下文和线程 ​

  • Guild 频道历史限制：channels.discord.historyLimit（默认 20），回退 messages.groupChat.historyLimit
  • DM 历史限制：channels.discord.dmHistoryLimit
  • 线程继承父频道配置，但不会自动复制父会话历史
  • channels.discord.thread.inheritParent 控制新线程是否从父会话转录种子

线程绑定会话（Subagents） ​

通过 /focus &lt;target&gt; 绑定线程到子 Agent 或 ACP 会话。配置：

json5
{
  session: {
    threadBindings: { enabled: true, idleHours: 24, maxAgeHours: 0 },
  },
  channels: {
    discord: {
      threadBindings: { enabled: true, idleHours: 24, maxAgeHours: 0, spawnSessions: true, defaultSpawnContext: "fork" },
    },
  },
}

确认反应（Ack Reaction） ​

ackReaction 发送处理中的表情。解析顺序：账号级 → 渠道级 → messages.ackReaction → Agent 身份 emoji。设为 "" 禁用。

网关代理 ​

channels.discord.proxy 设置 HTTP(S) 代理，路由 WebSocket 和 REST 流量。

PluralKit 支持 ​

启用后映射代理消息到系统成员身份。channels.discord.pluralkit.enabled = true，可选 token 用于私有系统。白名单支持 pk:<memberId>。

提及别名 ​

channels.discord.mentionAliases 让 Agent 输出时使用可读别名替代用户 ID。

在线状态配置 ​

设置 channels.discord.status（如 idle）和 activity（如 "Focus time" 等）。autoPresence 根据运行时健康状态自动切换（online/idle/dnd）。

审批（Exec Approvals） ​

支持按钮审批。配置 channels.discord.execApprovals.enabled，目标可选 dm（默认）、channel、both。需要至少一个审批者（来自 execApprovals.approvers 或 commands.ownerAllowFrom）。

工具和动作门控 ​

动作门控位于 channels.discord.actions.*。默认：

  • reactions、messages、threads、pins、polls、search、memberInfo、roleInfo、channelInfo、channels、voiceStatus、events、stickers 等：启用
  • roles、moderation、presence：禁用

Components v2 UI ​

OpenClaw 使用 Discord Components v2 容器。可配置强调色 channels.discord.ui.components.accentColor。组件回调 TTL 通过 agentComponents.ttlMs 控制。

语音频道 ​

支持实时语音频道和语音消息附件。

语音频道要求 ​

  1. 启用 Message Content Intent 和 Server Members Intent
  2. 使用 bot + applications.commands 作用域邀请 Bot
  3. 目标语音频道需 Connect、Speak、Send Messages、Read Message History 权限
  4. 启用原生命令
  5. 配置 channels.discord.voice

使用原生命令 /vc join、/vc leave、/vc status 控制。自动加入示例：

json5
{
  channels: {
    discord: {
      voice: {
        enabled: true,
        model: "openai-codex/gpt-5.5",
        autoJoin: [{ guildId: "123456789012345678", channelId: "234567890123456789" }],
        realtime: { provider: "openai", model: "gpt-realtime-2", voice: "cedar" },
      },
    },
  },
}

语音模式：

  • agent-proxy（默认）：实时语音前端处理时序和中断，实际回答委托给 OpenClaw Agent
  • stt-tts：传统批量转写 + TTS
  • bidi：实时模型直接对话，但仍可咨询 OpenClaw

跟随用户模式：voice.followUsers 让 Bot 自动加入用户所在的语音频道。

语音消息附件 ​

发送 OGG/Opus 格式语音消息，需要 ffmpeg 和 ffprobe。提供本地文件路径（URL 被拒绝），省略文本内容。OpenClaw 自动生成波形预览。

故障排除 ​

Discord Bot 收不到消息或看不到服务器消息 ​

  • 确认已启用 Message Content Intent 和 Server Members Intent
  • 重启 Gateway 后重试
  • 运行 openclaw doctor 和 openclaw channels status --probe

服务器消息被意外阻止 ​

  • 检查 groupPolicy 是否为 allowlist
  • 检查 channels.discord.guilds 是否包含正确的服务器 ID
  • 如果 guilds 下有 channels 映射，只有列出的频道允许访问
  • 确认 requireMention 设置正确

要求不提及但 Bot 仍不回复 ​

常见原因：

  • groupPolicy="allowlist" 但没有匹配的 guild/channel 白名单
  • requireMention 配置在了错误位置（必须在 channels.discord.guilds 或频道条目下）
  • 发送者被 users 或 roles 白名单阻止

长时间运行的处理超时或重复回复 ​

增加 listener 超时：

json5
{
  channels: {
    discord: {
      accounts: {
        default: {
          eventQueue: { listenerTimeout: 120000 },
        },
      },
    },
  },
}

语音频道无法加入或声音问题 ​

  • 确认 Bot 有 Connect + Speak 权限
  • 运行 openclaw channels capabilities --channel discord --target channel:&lt;voice-channel-id&gt; 检查权限
  • 刷新 Gateway 后重试
  • 若出现解密失败（DecryptionFailed），保持 DAVE 加密启用，调整 decryptionFailureTolerance

DM 或配对失败 ​

  • 检查 channels.discord.dm.enabled 未设为 false
  • 检查 dmPolicy 未设为 disabled
  • 配对码过期（1 小时），重新发送私信获取新码

Gateway 元数据查找超时 ​

设置 channels.discord.gatewayInfoTimeoutMs（默认 30000ms，最大 120000ms）。

Gateway READY 超时重启 ​

有多个账号时可能需要更长等待时间。调整 gatewayReadyTimeoutMs（默认 15000ms）或 gatewayRuntimeReadyTimeoutMs（默认 30000ms）。

配置参考 ​

主要参考：配置参考 - Discord。

高信号字段：

  • enabled、token、accounts.*、allowBots
  • groupPolicy、dmPolicy、guilds.*、guilds.*.channels.*
  • commands.native、configWrites
  • eventQueue.listenerTimeout、eventQueue.maxQueueSize
  • gatewayInfoTimeoutMs、gatewayReadyTimeoutMs
  • replyToMode、historyLimit、dmHistoryLimit
  • streaming、draftChunk
  • mediaMaxMb（默认 100MB）、retry
  • actions.*、activity、status
  • ui.components.accentColor
  • threadBindings、pluralkit、execApprovals

安全和运维 ​

  • 将 Bot Token 当密钥处理，建议使用环境变量 DISCORD_BOT_TOKEN
  • 授予最小必要权限
  • 若命令部署状态异常，重启 Gateway 并用 openclaw channels status --probe 检查

常见问题 ​

Discord Bot 如何正确设置 Token 而不在聊天中泄露？ ​

在运行 OpenClaw 的机器上通过环境变量设置 DISCORD_BOT_TOKEN，然后使用 openclaw config patch 注入 SecretRef 配置。切勿直接在聊天中发送 Token。

怎样允许 Bot 在频道中无需 @提及回复？ ​

在 guild 配置中将 requireMention 设为 false。例如：

json5
{
  channels: {
    discord: {
      guilds: {
        "YOUR_SERVER_ID": {
          requireMention: false,
        },
      },
    },
  },
}

若是公共频道，考虑使用 messages.groupChat.visibleReplies: "message_tool" 模式。

语音频道加入后听不到声音或声音中断 ​

检查 Bot 在语音频道的权限（Connect、Speak、View Channels）。确保启用了原生命令，并正确配置了 voice 块。如果使用实时模式，确认 voice.realtime.provider 和模型可用。查看 Gateway 日志中的 discord voice: 消息排查。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策