← 返回目录

Discord（Bot API）

状态：已支持通过官方 Discord 机器人网关进行私信和服务器文字频道通信。

快速设置（新手）

  1. 创建 Discord 机器人并复制机器人令牌。
  2. 在 Discord 应用设置中启用 Message Content Intent（如果你计划使用允许列表或名称查找，还需启用 Server Members Intent）。
  3. 为 OpenClaw 设置令牌：
  4. 使用消息权限邀请机器人到你的服务器（如果你只想使用私信，可以创建一个私人服务器）。
  5. 启动 Gateway 网关。
  6. 私信访问默认采用配对模式；首次联系时需批准配对码。

最小配置：

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

目标

工作原理

  1. 创建 Discord 应用程序 → Bot，启用你需要的意图（私信 + 服务器消息 + 消息内容），并获取机器人令牌。
  2. 使用所需权限邀请机器人到你的服务器，以便在你想使用的地方读取/发送消息。
  3. 使用 channels.discord.token 配置 OpenClaw（或使用 DISCORD_BOT_TOKEN 作为回退）。
  4. 运行 Gateway 网关；当令牌可用（配置优先，环境变量回退）且 channels.discord.enabled 不为 false 时，它会自动启动 Discord 渠道。
  5. 直接聊天：发送时使用 user:<id>（或 <@id> 提及）；所有对话都进入共享的 main 会话。纯数字 ID 是模糊的，会被拒绝。
  6. 服务器频道：发送时使用 channel:<channelId>。默认需要提及，可以按服务器或按频道设置。
  7. 直接聊天：默认通过 channels.discord.dm.policy 进行安全保护（默认："pairing"）。未知发送者会收到配对码（1 小时后过期）；通过 openclaw pairing approve discord <code> 批准。
  8. 群组私信默认被忽略；通过 channels.discord.dm.groupEnabled 启用，并可选择通过 channels.discord.dm.groupChannels 进行限制。
  9. 可选服务器规则：设置 channels.discord.guilds，以服务器 ID（首选）或 slug 为键，并包含每个频道的规则。
  10. 可选原生命令：commands.native 默认为 "auto"（Discord/Telegram 开启，Slack 关闭）。使用 channels.discord.commands.native: true|false|"auto" 覆盖；false 会清除之前注册的命令。文本命令由 commands.text 控制，必须作为独立的 /... 消息发送。使用 commands.useAccessGroups: false 可跳过命令的访问组检查。
  11. 可选服务器上下文历史：设置 channels.discord.historyLimit（默认 20，回退到 messages.groupChat.historyLimit）以在回复提及时包含最近 N 条服务器消息作为上下文。设置 0 禁用。
  12. 表情反应：智能体可以通过 discord 工具触发表情反应（受 channels.discord.actions.* 控制）。
  13. 原生命令使用隔离的会话键（agent:<agentId>:discord:slash:<userId>）而不是共享的 main 会话。

注意：名称 → ID 解析使用服务器成员搜索，需要 Server Members Intent；如果机器人无法搜索成员，请使用 ID 或 <@id> 提及。 注意：Slug 为小写，空格替换为 -。频道名称的 slug 不包含前导 #。 注意：服务器上下文 [from:] 行包含 author.tag + id，便于进行可提及的回复。

配置写入

默认情况下，允许 Discord 写入由 /config set|unset 触发的配置更新（需要 commands.config: true）。

禁用方式：

{
  channels: { discord: { configWrites: false } },
}

如何创建自己的机器人

这是在服务器（guild）频道（如 #help）中运行 OpenClaw 的"Discord 开发者门户"设置。

1）创建 Discord 应用 + 机器人用户

  1. Discord 开发者门户 → Applications → New Application
  2. 在你的应用中：

2）启用 OpenClaw 需要的网关意图

Discord 会阻止"特权意图"，除非你明确启用它们。

在 Bot → Privileged Gateway Intents 中启用：

你通常不需要 Presence Intent。

3）生成邀请 URL（OAuth2 URL Generator）

在你的应用中：OAuth2 → URL Generator

Scopes

Bot Permissions（最小基线）

除非你在调试并完全信任机器人，否则避免使用 Administrator。

复制生成的 URL，打开它，选择你的服务器，然后安装机器人。

4）获取 ID（服务器/用户/频道）

Discord 到处使用数字 ID；OpenClaw 配置优先使用 ID。

  1. Discord（桌面/网页）→ 用户设置 → 高级 → 启用 开发者模式
  2. 右键点击：

5）配置 OpenClaw

令牌

通过环境变量设置机器人令牌（服务器上推荐）：

或通过配置：

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

多账户支持：使用 channels.discord.accounts，每个账户有自己的令牌和可选的 name。参见 gateway/configuration 了解通用模式。

允许列表 + 频道路由

示例"单服务器，只允许我，只允许 #help"：

{
  channels: {
    discord: {
      enabled: true,
      dm: { enabled: false },
      guilds: {
        YOUR_GUILD_ID: {
          users: ["YOUR_USER_ID"],
          requireMention: true,
          channels: {
            help: { allow: true, requireMention: true },
          },
        },
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

注意：

6）验证是否工作

  1. 启动 Gateway 网关。
  2. 在你的服务器频道中发送：@Krill hello（或你的机器人名称）。
  3. 如果没有反应：查看下面的故障排除。

故障排除

功能和限制

重试策略

出站 Discord API 调用在速率限制（429）时使用 Discord retry_after（如果可用）进行重试，采用指数退避和抖动。通过 channels.discord.retry 配置。参见重试策略。

配置

{
  channels: {
    discord: {
      enabled: true,
      token: "abc.123",
      groupPolicy: "allowlist",
      guilds: {
        "*": {
          channels: {
            general: { allow: true },
          },
        },
      },
      mediaMaxMb: 8,
      actions: {
        reactions: true,
        stickers: true,
        emojiUploads: true,
        stickerUploads: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        channels: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off",
      dm: {
        enabled: true,
        policy: "pairing", // pairing | allowlist | open | disabled
        allowFrom: ["123456789012345678", "steipete"],
        groupEnabled: false,
        groupChannels: ["openclaw-dm"],
      },
      guilds: {
        "*": { requireMention: true },
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          reactionNotifications: "own",
          users: ["987654321098765432", "steipete"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["search", "docs"],
              systemPrompt: "Keep answers short.",
            },
          },
        },
      },
    },
  },
}

确认表情反应通过 messages.ackReaction + messages.ackReactionScope 全局控制。使用 messages.removeAckAfterReply 在机器人回复后清除确认表情反应。

表情反应通知使用 guilds.<id>.reactionNotifications：

PluralKit（PK）支持

启用 PK 查找，以便代理消息解析到底层系统 + 成员。启用后，OpenClaw 使用成员身份进行允许列表匹配，并将发送者标记为 Member (PK:System) 以避免意外的 Discord 提及。

{
  channels: {
    discord: {
      pluralkit: {
        enabled: true,
        token: "pk_live_...", // 可选；私有系统需要
      },
    },
  },
}

允许列表注意事项（启用 PK 时）：

工具操作默认值

| 操作组 | 默认 | 说明 | | -------------- | ---- | ----------------------------------- | | reactions | 启用 | 表情反应 + 列出表情反应 + emojiList | | stickers | 启用 | 发送贴纸 | | emojiUploads | 启用 | 上传表情 | | stickerUploads | 启用 | 上传贴纸 | | polls | 启用 | 创建投票 | | permissions | 启用 | 频道权限快照 | | messages | 启用 | 读取/发送/编辑/删除 | | threads | 启用 | 创建/列出/回复 | | pins | 启用 | 置顶/取消置顶/列出 | | search | 启用 | 消息搜索（预览功能） | | memberInfo | 启用 | 成员信息 | | roleInfo | 启用 | 角色列表 | | channelInfo | 启用 | 频道信息 + 列表 | | channels | 启用 | 频道/类别管理 | | voiceStatus | 启用 | 语音状态查询 | | events | 启用 | 列出/创建预定事件 | | roles | 禁用 | 角色添加/移除 | | moderation | 禁用 | 超时/踢出/封禁 |

回复标签

要请求线程回复，模型可以在其输出中包含一个标签：

行为由 channels.discord.replyToMode 控制：

允许列表匹配注意事项：

原生命令注意事项：

工具操作

智能体可以使用以下操作调用 discord：

Discord 消息 ID 在注入的上下文中显示（[discord message id: …] 和历史行），以便智能体可以定位它们。 表情可以是 unicode（例如 ✅）或自定义表情语法如 <:party_blob:1234567890>。

安全与运维