古法编程

Appearance

Discord（Bot API） ​

状态：通过官方 Discord Gateway 支持私信和服务器频道。

快速设置 ​

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

第一步：创建 Discord 应用和 Bot ​

前往 Discord Developer Portal 点击 New Application，命名为 "OpenClaw" 之类的名称。

点击侧边栏的 Bot，将 Username 设置为你的 OpenClaw Agent 名称。

第二步：启用特权 Intent ​

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

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

第三步：复制 Bot Token ​

在 Bot 页面向上滚动，点击 Reset Token。

尽管名为"Reset"，这实际上是生成你的第一个 Token，并不是在重置任何东西。

复制 Token 并妥善保存，这就是你的 Bot Token，稍后会用到。

第四步：生成邀请 URL 并添加 Bot 到服务器 ​

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

  • bot
  • applications.commands

下方会出现 Bot Permissions 区域，启用：

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

复制底部生成的 URL，粘贴到浏览器，选择你的服务器，点击 Continue 完成连接。你现在应该能在 Discord 服务器中看到你的 Bot 了。

第五步：启用开发者模式并收集 ID ​

在 Discord 应用中启用开发者模式：

  1. 点击头像旁的用户设置（齿轮图标）→ Advanced → 开启 Developer Mode
  2. 右键点击侧边栏的服务器图标 → Copy Server ID
  3. 右键点击自己的头像 → Copy User ID

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

第六步：允许服务器成员发私信 ​

为使配对正常工作，Discord 需要允许 Bot 向你发私信。右键点击服务器图标 → Privacy Settings → 开启 Direct Messages。

这允许服务器成员（包括 Bot）向你发私信。如果只打算使用服务器频道，配对完成后可以关闭。

第七步：安全设置 Bot Token（不要在聊天中发送） ​

你的 Discord Bot Token 是密钥（像密码一样），在发消息给 Agent 之前先在运行 OpenClaw 的机器上设置它：

bash
export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set channels.discord.enabled true --strict-json
openclaw gateway

若 OpenClaw 已作为后台服务运行，使用 openclaw gateway restart。

第八步：配置 OpenClaw 并配对 ​

通过 Agent 配置：

在任意现有渠道（如 Telegram）和 Agent 聊天，告诉它：

"我已在配置中设置了 Discord Bot Token，请用 User ID <user_id> 和 Server ID <server_id> 完成 Discord 设置。"

通过配置文件：

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

环境变量回退（默认账号）：DISCORD_BOT_TOKEN=...

明文 token 值和 SecretRef 值（env/file/exec 提供商）均支持。详见 Secrets 管理。

第九步：审批第一次私信配对 ​

等 Gateway 启动后，在 Discord 中向你的 Bot 发私信，Bot 会回复一个配对码。

通过 Agent 审批：

"审批这个 Discord 配对码：<CODE>"

通过 CLI：

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

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

Token 解析支持账号感知。配置中的 Token 值优先于环境变量回退。DISCORD_BOT_TOKEN 仅用于默认账号。

推荐：设置服务器工作空间 ​

私信正常工作后，你可以将 Discord 服务器设置为完整工作空间，让每个频道都有独立的 Agent 会话和上下文。这对只有你和 Bot 的私人服务器特别推荐。

将服务器添加到 Guild 白名单 ​

启用后，Agent 可以在服务器的任意频道中回复，而不仅限于私信。

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

允许无 @提及回复 ​

默认情况下，Agent 只在被 @提及时在服务器频道中回复。对于私人服务器，你可能希望它对所有消息都回复：

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

规划服务器频道中的记忆 ​

默认情况下，长期记忆（MEMORY.md）只在私信会话中加载，服务器频道不会自动加载。

若需要在每个频道中使用共享上下文，将稳定的指令放在 AGENTS.md 或 USER.md 中（它们会为每个会话注入），长期笔记放在 MEMORY.md 中，按需通过记忆工具访问。

运行时模型 ​

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

论坛频道 ​

Discord 论坛和媒体频道只接受话题串帖子。OpenClaw 支持两种创建方式：

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

示例：向论坛父频道发送消息创建话题串

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

示例：明确创建论坛话题串

bash
openclaw message thread create --channel discord --target channel:<forumId> \
  --thread-name "Topic title" --message "Body of the post"

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

交互组件 ​

OpenClaw 支持 Discord Components v2 容器用于 Agent 消息。通过消息工具发送 components 载荷，交互结果作为普通入站消息路由回 Agent，并遵循现有 Discord replyToMode 设置。

支持的块类型：

  • text、section、separator、actions、media-gallery、file
  • 操作行最多允许 5 个按钮或一个选择菜单
  • 选择类型：string、user、role、mentionable、channel

默认情况下，组件是一次性的。设置 components.reusable=true 允许按钮、选择和表单在过期前多次使用。

要限制谁可以点击按钮，在该按钮上设置 allowedUsers（Discord 用户 ID、标签或 *），不匹配的用户会收到临时拒绝提示。

/model 和 /models Slash 命令会打开带有提供商和模型下拉菜单以及提交步骤的交互模型选择器，选择器回复是临时的且只有调用用户可以使用。

模态表单：

  • 在 components.modal 中添加最多 5 个字段
  • 字段类型：text、checkbox、radio、select、role-select、user-select
  • OpenClaw 自动添加触发按钮

示例：

json5
{
  channel: "discord",
  action: "send",
  to: "channel:123456789012345678",
  message: "Optional fallback text",
  components: {
    reusable: true,
    text: "选择一条路",
    blocks: [
      {
        type: "actions",
        buttons: [
          {
            label: "Approve",
            style: "success",
            allowedUsers: ["123456789012345678"],
          },
          { label: "Decline", style: "danger" },
        ],
      },
    ],
  },
}

访问控制和路由 ​

私信策略 ​

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

  • pairing（默认）
  • allowlist
  • open（需要 channels.discord.allowFrom 包含 "*"）
  • disabled

若私信策略不是 open，未知用户会被阻止（或在 pairing 模式下提示配对）。

私信投递目标格式：

  • user:<id>
  • <@id> 提及

裸数字 ID 是模糊的，除非提供明确的 user/channel 目标类型，否则会被拒绝。

Guild 策略 ​

Guild 处理由 channels.discord.groupPolicy 控制：

  • open
  • allowlist
  • disabled

存在 channels.discord 时的安全基线是 allowlist。

allowlist 行为：

  • Guild 必须匹配 channels.discord.guilds（推荐使用 id，接受 slug）
  • 可选发送者白名单：users（推荐使用稳定 ID）和 roles（仅角色 ID）；若其中一个已配置，发送者匹配 users 或 roles 任一即被允许
  • 直接名称/标签匹配默认禁用；仅在紧急情况下启用 channels.discord.dangerouslyAllowNameMatching: true
  • 若 Guild 配置了 channels，未列出的频道会被拒绝

示例：

json5
{
  channels: {
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        "123456789012345678": {
          requireMention: true,
          ignoreOtherMentions: true,
          users: ["987654321098765432"],
          roles: ["123456789012345678"],
          channels: {
            general: { allow: true },
            help: { allow: true, requireMention: true },
          },
        },
      },
    },
  },
}

基于角色的 Agent 路由 ​

使用 bindings[].match.roles 按角色 ID 将 Discord 服务器成员路由到不同 Agent：

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
  • commands.native=false 明确清除之前注册的 Discord 原生命令
  • 原生命令授权使用与普通消息处理相同的 Discord 白名单/策略
  • 命令对未授权用户可能在 Discord UI 中可见，但执行时 OpenClaw 仍会强制认证并返回"未授权"

Slash 命令默认设置：

  • ephemeral: true

详见 Slash 命令。

功能详情 ​

回复标签和原生回复 ​

Discord 支持 Agent 输出中的回复标签：

  • [[reply_to_current]]
  • [[reply_to:<id>]]

由 channels.discord.replyToMode 控制：

  • off（默认）
  • first
  • all

注意：off 禁用隐式回复串；显式 [[reply_to_*]] 标签仍会被遵守。

实时流式预览 ​

OpenClaw 可以通过发送临时消息并在文本生成时编辑它来流式传输草稿回复。

  • channels.discord.streaming 控制预览流式传输（off | partial | block | progress，默认：off）
  • 默认保持 off 是因为 Discord 预览编辑可能快速触发速率限制，特别是当多个 Bot 或 Gateway 共享同一账号或服务器流量时

示例：

json5
{
  channels: {
    discord: {
      streaming: "partial",
    },
  },
}

历史记录、上下文和话题串行为 ​

服务器历史记录上下文：

  • channels.discord.historyLimit 默认 20
  • 回退：messages.groupChat.historyLimit
  • 0 禁用

话题串绑定会话（子 Agent） ​

Discord 可以将话题串绑定到会话目标，使该话题串中的后续消息持续路由到同一会话（包括子 Agent 会话）：

  • /focus <target> 将当前/新话题串绑定到子 Agent/会话目标
  • /unfocus 移除当前话题串绑定
  • /agents 显示活跃运行和绑定状态

配置：

json5
{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // 需要明确启用
      },
    },
  },
}

回应通知 ​

按 Guild 配置回应通知模式：

  • off
  • own（默认）
  • all
  • allowlist（使用 guilds.<id>.users）

Ack 回应 ​

ackReaction 在 OpenClaw 处理入站消息时发送确认 Emoji。

注意：Discord 接受 Unicode Emoji 或自定义 Emoji 名称；使用 "" 为特定渠道或账号禁用回应。

网关代理 ​

通过 channels.discord.proxy 将 Discord Gateway WebSocket 流量和启动 REST 查询路由到 HTTP(S) 代理：

json5
{
  channels: {
    discord: {
      proxy: "http://proxy.example:8080",
    },
  },
}

工具和操作门控 ​

Discord 消息操作包括消息、频道管理、审核、在线状态和元数据操作。

默认门控行为：

操作组默认
reactions、messages、threads、pins、polls、search、memberInfo、roleInfo、channelInfo、channels、voiceStatus、events、stickers启用
roles禁用
moderation禁用
presence禁用

语音频道 ​

OpenClaw 可以加入 Discord 语音频道进行实时连续对话（与语音消息附件不同）。

要求：

  • 启用原生命令（commands.native 或 channels.discord.commands.native）
  • 配置 channels.discord.voice
  • Bot 需要目标语音频道的 Connect + Speak 权限

使用仅限 Discord 的原生命令 /vc join|leave|status 控制会话。

自动加入示例：

json5
{
  channels: {
    discord: {
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
    },
  },
}

故障排除 ​

使用了不允许的 Intent 或 Bot 看不到服务器消息：

  • 启用 Message Content Intent
  • 需要用户/成员解析时启用 Server Members Intent
  • 更改 Intent 后重启 Gateway

服务器消息被意外阻止：

  • 检查 groupPolicy
  • 检查 channels.discord.guilds 下的 Guild 白名单
  • 若 Guild channels 映射存在，只有列出的频道被允许

有用的检查命令：

bash
openclaw doctor
openclaw channels status --probe
openclaw logs --follow

长时间运行的处理程序超时或重复回复：

推荐基线：

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

安全和运维 ​

  • 将 Bot Token 视为密钥（建议在受监管环境中使用 DISCORD_BOT_TOKEN）
  • 给 Discord 授予最小权限
  • 若命令部署/状态陈旧，重启 Gateway 并用 openclaw channels status --probe 重新检查

相关文档 ​

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

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策