OpenClaw

OpenClaw Discord 渠道

即时通讯
简单

通过 discord.js Bot Gateway API 将 OpenClaw 连接到 Discord。在 Discord 开发者门户中创建机器人，启用所需的 Intent 权限，邀请机器人到你的服务器，AI 助手即可在 Discord 上运行。支持私信、服务器频道对话、表情回应、线程、斜杠命令和富媒体。是最容易设置的渠道之一。

快速信息
难度简单
分类即时通讯
支持功能数5 / 6

Discord 支持的功能

文本消息

支持

媒体与文件

支持

消息反应

支持

消息线程

支持

语音消息

不支持

群聊

支持

Discord 前置条件

  • 拥有 Discord 开发者门户访问权限的 Discord 账号
  • Discord 开发者门户的 Bot Token（Applications → New Application → Bot）
  • 在 Privileged Gateway Intents 中启用 Message Content Intent
  • OpenClaw Gateway 已运行并配置

Discord 快速设置

1

创建 Discord 机器人并启用 Intent

前往 Discord 开发者门户（discord.com/developers），创建新应用，添加 Bot 用户并复制 Bot Token。在 Privileged Gateway Intents 中，启用 'Message Content Intent'（必需）和 'Server Members Intent'（推荐用于成员查询）。

2

添加 Discord 渠道配置

在 ~/.openclaw/openclaw.json 中添加 Discord 渠道配置。设置 token（或使用 DISCORD_BOT_TOKEN 环境变量），并配置 dm.policy 来控制谁可以私信机器人。

3

邀请机器人到服务器并测试

在开发者门户中，前往 OAuth2 → URL Generator。选择 scopes 'bot' 和 'applications.commands'。选择权限：View Channels、Send Messages、Read Message History、Embed Links、Attach Files、Add Reactions。打开生成的 URL 邀请机器人到你的服务器。发送 '@机器人名称 hello' 进行测试。

Discord 配置示例

config.json
{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_DISCORD_BOT_TOKEN",
      "dm": {
        "policy": "pairing"
      }
    }
  }
}

Discord 深入了解

架构概述

OpenClaw 通过 discord.js 库连接到 Discord —— 这是一个强大的 Node.js 模块，用于与 Discord Bot Gateway API 交互。机器人通过 WebSocket 连接到 Discord 的网关，实时接收消息、表情回应和其他交互事件。 会话路由因上下文而异：私信对话合并到代理的主会话（agent:main:main），而服务器频道对话为每个频道创建隔离的会话（agent:<agentId>:discord:channel:<channelId>）。斜杠命令按用户拥有独立的隔离会话。群组私信默认禁用。
Bot Token 可以通过 DISCORD_BOT_TOKEN 环境变量设置，也可以在配置文件的 channels.discord.token 字段中设置。
在 Discord 中启用开发者模式（用户设置 → 高级），即可通过右键菜单轻松复制服务器 ID、频道 ID 和用户 ID。

创建你的机器人

设置 Discord 机器人需要在 Discord 开发者门户中创建应用： 1. 前往 discord.com/developers/applications 2. 点击 'New Application' 并命名 3. 进入 Bot 部分，点击 'Add Bot' 4. 复制 Bot Token —— 妥善保存 5. 在 Privileged Gateway Intents 中启用： • Message Content Intent（必需 —— 没有它机器人无法读取消息内容） • Server Members Intent（推荐用于成员/角色查询） 6. 前往 OAuth2 → URL Generator 7. 选择 scopes：'bot' 和 'applications.commands' 8. 选择权限：View Channels、Send Messages、Read Message History、Embed Links、Attach Files、Add Reactions 9. 复制生成的 URL 并打开它来邀请机器人到你的服务器
除非调试需要，否则避免授予 Administrator 权限。使用最小所需权限以提高安全性。
请保管好你的 Bot Token。任何拥有该 Token 的人都可以控制你的机器人。如果泄露，请在开发者门户中重新生成。
Message Content Intent 是机器人读取消息文本的必要条件。没有它，机器人虽然可以连接，但无法看到任何消息内容。

私信策略

私信（DM）策略控制谁可以与你的 AI 助手进行私聊。OpenClaw 支持四种策略： • pairing（默认）—— 未知发送者会收到一个限时配对码（1 小时后过期）。在终端通过 'openclaw pairing approve discord <code>' 审批。审批后即可自由聊天。 • allowlist —— 只有 dm.allowFrom 中明确列出的用户 ID 可以给机器人发消息。其他人将被静默忽略。 • open —— 任何私信机器人的人都会收到回复。需要 dm.allowFrom=["*"] 才能生效。请谨慎使用。 • disabled —— 完全关闭私信处理。机器人不会响应任何私信。
openclaw.json
{
  "channels": {
    "discord": {
      "dm": {
        "policy": "pairing",
        "allowFrom": ["123456789012345678"]
      }
    }
  }
}

服务器频道配置

服务器（Guild）频道是大多数 Discord 交互发生的地方。OpenClaw 提供细粒度的控制，可以管理机器人在哪些服务器和频道中运行。 顶层设置： • groupPolicy —— 控制服务器频道的处理方式。选项：open（在所有频道中响应）、disabled（忽略所有服务器消息）、allowlist（限制为已配置的服务器） 每服务器配置可为每个服务器自定义行为： • slug —— 用于显示的友好标识符 • users —— 用户白名单（ID 或名称） • requireMention —— 是否需要 @提及 机器人 • reactionNotifications —— 控制表情回应事件通知（off、own、all、allowlist） 每频道规则可在服务器内提供更精细的控制： • allow —— 启用/禁用该频道 • requireMention —— 频道级别的提及要求 • users —— 频道用户白名单 • skills —— 技能过滤器（省略则全部可用） • systemPrompt —— 为 AI 提供的额外上下文指令
openclaw.json
{
  "channels": {
    "discord": {
      "groupPolicy": "open",
      "guilds": {
        "YOUR_GUILD_ID": {
          "slug": "my-server",
          "requireMention": true,
          "channels": {
            "CHANNEL_ID": {
              "allow": true,
              "requireMention": false,
              "systemPrompt": "You are a helpful assistant in this channel."
            }
          }
        }
      }
    }
  }
}
在 Discord 中启用开发者模式（用户设置 → 高级），即可右键复制服务器、频道和用户 ID。
每频道 systemPrompt 可以让 AI 在不同频道拥有不同的角色或指令。

表情回应与消息确认

OpenClaw 支持 Discord 的表情回应系统，用于消息确认和接收回应通知。 消息确认回应：机器人可以在收到消息时用表情回应来表示正在处理。通过 messages.ackReaction 配置。回应可以在 AI 回复后通过 messages.removeAckAfterReply 自动移除。 回应通知：可以按服务器配置哪些回应触发代理通知： • off —— 不通知 • own —— 仅机器人消息的回应 • all —— 频道中所有回应 • allowlist —— 仅白名单用户的回应
openclaw.json
{
  "channels": {
    "discord": {
      "messages": {
        "ackReaction": "👀",
        "removeAckAfterReply": true
      },
      "guilds": {
        "GUILD_ID": {
          "reactionNotifications": "own"
        }
      }
    }
  }
}

消息格式与分块

Discord 有 2,000 字符的消息限制。OpenClaw 通过自动分块来处理较长的 AI 回复。 关键设置： • textChunkLimit —— 每个消息块的最大字符数（默认：2000） • maxLinesPerMessage —— 每条消息的软行数限制（默认：17） • chunkMode —— 分割策略：'length'（默认，硬字符限制）或 'newline'（按段落边界分割） 机器人还会注入最近的服务器消息作为上下文（通过 historyLimit 配置，默认 20 条消息），这样 AI 可以自然地参与正在进行的对话。
openclaw.json
{
  "channels": {
    "discord": {
      "textChunkLimit": 2000,
      "chunkMode": "newline",
      "historyLimit": 20
    }
  }
}

斜杠命令与工具操作

OpenClaw 在机器人启动时自动注册 Discord 原生斜杠命令（默认：auto，可通过 commands.native 配置）。将 commands.native 设为 false 会清除之前注册的命令。命令遵循与消息相同的白名单规则 —— 未授权用户在 Discord UI 中可以看到命令，但会收到'未授权'的回复。 会话隔离：斜杠命令使用独立的会话键（agent:<agentId>:discord:slash:<userId>），而非共享的 main 会话，提供按用户隔离的体验。 代理支持丰富的工具操作来与 Discord 交互： • 消息 —— 发送、编辑、删除、置顶/取消置顶消息、搜索消息 • 线程 —— 创建线程、列出线程、在线程中回复 • 回应 —— 对消息发送表情回应、列出回应 • 管理 —— 禁言、踢出、封禁成员（默认禁用） • 服务器信息 —— 成员信息、角色信息、频道信息、表情列表 • 状态 —— 设置机器人状态（默认禁用） 回复标签允许模型控制消息线程： • [[reply_to_current]] —— 回复触发消息 • [[reply_to:<id>]] —— 回复指定消息 ID
确保 OAuth2 邀请 URL 中包含 'applications.commands' scope，斜杠命令才会显示。
管理工具（禁言、踢出、封禁）和角色管理默认禁用。如需使用，请在配置中明确启用。

媒体与文件处理

OpenClaw 支持通过 Discord 发送和接收媒体文件。默认最大上传大小为 8 MB（可通过 mediaMaxMb 配置）。 支持的操作： • 接收用户的图片和文件附件 • 在回复中发送图片、文档和其他文件 • 嵌入链接的富文本预览 机器人需要 'Attach Files' 权限才能在服务器频道中发送媒体。
Discord 的文件大小限制取决于服务器的 Boost 等级。默认为 8 MB（无 Boost），Level 2 为 50 MB，Level 3 为 100 MB。

PluralKit 集成

OpenClaw 可选支持 PluralKit 代理消息解析，允许机器人正确识别来自 PluralKit 系统的消息。 启用后，机器人会将代理消息解析回其原始 PluralKit 成员身份。这对使用 PluralKit 进行系统/多重身份消息路由的社区非常有用。 关键细节： • 在白名单中使用 pk:<memberId> 前缀来匹配 PluralKit 成员 • 成员名称也可通过显示名称或 slug 进行匹配 • 查询使用原始 Discord 消息 ID，有效期为 PluralKit 的 30 分钟窗口 • 如果查询失败，代理消息被视为机器人消息（除非 allowBots=true，否则会被丢弃）
openclaw.json
{
  "channels": {
    "discord": {
      "pluralkit": {
        "enabled": true,
        "token": "pk_live_..."
      }
    }
  }
}
私有 PluralKit 系统需要 pluralkit.token 来解析成员。没有它，代理消息会被视为机器人消息并丢弃。
在白名单中使用 pk:<memberId> 前缀来精确匹配 PluralKit 成员。

执行审批（按钮 UI）

Discord 支持基于按钮的执行操作审批流程。启用后，机器人会在私信中向指定审批者发送交互按钮（允许一次、始终允许、拒绝）。 这取代了基于命令的 /approve 流程，提供更友好的界面。要求： • execApprovals.enabled 必须为 true • 审批者的 Discord 用户 ID 必须在 execApprovals.approvers 列表中 • 可选的 agentFilter 和 sessionFilter 数组限制哪些代理/会话触发审批 注意：/approve <id> 命令仅用于转发的审批。Discord 按钮 UI 在直接交互中优先于基于命令的审批。
openclaw.json
{
  "channels": {
    "discord": {
      "execApprovals": {
        "enabled": true,
        "approvers": ["USER_ID_1", "USER_ID_2"],
        "agentFilter": [],
        "sessionFilter": []
      }
    }
  }
}
如果审批按钮未出现或看到'unknown approval id'错误，请确认用户 ID 已列入 execApprovals.approvers 且 execApprovals.enabled 为 true。

操作权限门控

OpenClaw 提供细粒度的控制来管理代理可以执行哪些 Discord 工具操作。操作通过 channels.discord.actions.<action>（true/false）进行门控。 默认启用： • reactions、stickers、emojiUploads、stickerUploads、polls、permissions、messages、threads、pins、search、memberInfo、roleInfo、channelInfo、voiceStatus、events、channels 默认禁用： • roles —— 角色管理（分配/移除角色） • moderation —— 禁言、踢出、封禁成员 • presence —— 设置机器人状态/活动 禁用特定操作可以减少机器人的功能范围并降低风险。例如，设置 channels.discord.actions.moderation=false 确保代理永远不会踢出或封禁成员。
遵循最小权限原则：只启用你的用例实际需要的操作。
通过 guilds.<id>.tools 和 guilds.<id>.channels.<id>.tools 可以实现按服务器和按频道的工具权限覆盖，提供更精细的控制。

白名单解析与匹配

OpenClaw 支持多种格式来指定白名单中的用户和频道： • 数字 ID（推荐）—— 例如 "123456789012345678" • Discord 用户/频道名称 —— 例如 "username"、"#channel-name" • 提及格式 —— 例如 "<@userId>"、"<#channelId>" • 前缀格式 —— discord:、user:、channel:、pk:（用于 PluralKit 成员） • 通配符 —— "*" 表示无限制访问 启动时，当机器人可以搜索成员时（需要 Server Members Intent），OpenClaw 会将名称解析为 ID。映射会被记录；未解析的条目保持原样。 所有者检测：当按服务器或按频道的 users 白名单匹配到发送者时，OpenClaw 会在系统提示中将发送者视为所有者。全局所有者通过 commands.ownerAllowFrom 配置。 线程继承：线程继承父频道的配置（白名单、requireMention、skills、prompts），除非使用线程的频道 ID 单独配置。
尽可能使用数字 ID 以确保可靠匹配。基于名称的解析需要 Server Members Intent，在大型服务器中可能失败。
Slug 格式为小写且空格替换为连字符（例如 #my-help → slug my-help）。
服务器频道主题会作为上下文注入，但不会作为系统提示 —— 请将其视为不可信输入。

Discord 配置参考

enabled
Type: booleanDefault: true

启用或禁用 Discord 渠道

token
Type: stringDefault: ""

Discord Bot Token。也可使用 DISCORD_BOT_TOKEN 环境变量

dm.policy
Type: stringDefault: "pairing"

控制谁可以私信机器人。选项：pairing、allowlist、open、disabled

dm.allowFrom
Type: string[]Default: []

允许私信机器人的 Discord 用户 ID（当 dm.policy 为 allowlist 时）

groupPolicy
Type: stringDefault: "allowlist"

服务器频道处理策略。选项：open、disabled、allowlist

guilds
Type: objectDefault: {}

按服务器 ID 索引的每服务器配置。包含 slug、users、channels、requireMention 等

requireMention
Type: booleanDefault: true

机器人在服务器频道中是否需要 @提及 才回复

messages.ackReaction
Type: stringDefault: ""

处理消息时用于确认的表情回应

messages.removeAckAfterReply
Type: booleanDefault: false

AI 回复后是否移除确认表情回应

textChunkLimit
Type: numberDefault: 2000

每个消息块的最大字符数（Discord 限制为 2000）

chunkMode
Type: stringDefault: "length"

长回复的分割方式。选项：length（硬字符限制）、newline（按段落分割）

historyLimit
Type: numberDefault: 20

作为 AI 上下文包含的最近服务器消息数量

mediaMaxMb
Type: numberDefault: 8

媒体文件上传的最大大小（MB）

replyToMode
Type: stringDefault: "off"

回复线程模式。选项：off、first（仅首个块作为回复）、all（所有块都作为回复）

configWrites
Type: booleanDefault: true

允许通过 Discord /config set|unset 命令发起的配置更新

allowBots
Type: booleanDefault: false

是否处理其他机器人的消息。请谨慎使用以避免循环

retry.attempts
Type: numberDefault: 3

Discord API 调用失败时的重试次数

retry.minDelayMs
Type: numberDefault: 500

重试之间的最小延迟毫秒数

retry.maxDelayMs
Type: numberDefault: 30000

重试之间的最大延迟毫秒数

retry.jitter
Type: numberDefault: 0.1

应用于重试延迟的抖动因子

dm.enabled
Type: booleanDefault: true

是否接受私信

dm.groupEnabled
Type: booleanDefault: false

启用群组私信处理

dm.groupChannels
Type: string[]Default: []

群组私信频道白名单

dmHistoryLimit
Type: numberDefault: -

每用户私信历史记录限制覆盖

maxLinesPerMessage
Type: numberDefault: 17

每条消息块的软行数限制

commands.native
Type: string | booleanDefault: "auto"

原生斜杠命令注册。选项：auto（Discord 默认启用）、true、false

commands.text
Type: objectDefault: {}

文本命令配置，要求独立的 /... 消息

commands.useAccessGroups
Type: booleanDefault: false

是否对命令执行访问组检查

actions.*
Type: booleanDefault: varies

工具操作权限门控。大部分默认启用；roles、moderation 和 presence 默认禁用

pluralkit.enabled
Type: booleanDefault: false

启用 PluralKit 代理消息解析

Discord 常见问题

Discord 故障排查

机器人已连接但不回复消息

Message Content Intent 未启用、机器人缺少频道权限，或提及要求配置不正确。

在 Discord 开发者门户中确认 Message Content Intent 已启用（Bot → Privileged Gateway Intents）。确认机器人拥有 View Channels、Send Messages 和 Read Message History 权限。检查 requireMention 是否设为 true 而机器人未被 @提及。
私信不工作

配置中可能禁用了私信处理，或配对审批仍在等待中。

检查 dm.policy 是否设为 'disabled'。如果使用 pairing 模式，通过 'openclaw pairing list' 查看待审批的配对请求，并通过 'openclaw pairing approve discord <code>' 审批。如果使用 allowlist 模式，确保用户的 Discord ID 在 dm.allowFrom 中。
斜杠命令在 Discord 中不可见

机器人的 OAuth2 邀请 URL 中未包含 'applications.commands' scope。

前往开发者门户 → OAuth2 → URL Generator，确保同时选中 'bot' 和 'applications.commands' scopes，生成新的邀请 URL 并重新邀请机器人到你的服务器。斜杠命令与普通消息受相同的白名单规则约束。
机器人被限速或卡住

触发了 Discord API 速率限制，或网关连接处于异常状态。

使用 'openclaw gateway --force' 重启网关。OpenClaw 内置了指数退避重试逻辑来处理速率限制（429 响应）。如果问题持续存在，检查 channels.discord.retry 下的重试配置。
requireMention 设为 false 但机器人仍然不回复

groupPolicy 默认值为 'allowlist'，机器人只在明确配置的服务器/频道中响应。

将 groupPolicy 设为 'open' 以在所有频道中响应，或将特定的服务器和频道 ID 添加到 guilds 配置中。确保服务器条目包含 allow: true 的频道。
执行审批按钮未在私信中出现

execApprovals 未启用，或用户的 Discord ID 未列在 approvers 数组中。

在 Discord 渠道配置中将 execApprovals.enabled 设为 true。将用户的数字 Discord ID 添加到 execApprovals.approvers 数组中。使用按钮 UI（而非 /approve 命令）进行直接 Discord 审批。
查看完整文档返回所有渠道

相关渠道

WhatsApp

Medium

OpenClaw 通过 Baileys 协议扫码连接

配置指南

Telegram

Easy

OpenClaw 通过 grammY 框架的 Bot API 集成

配置指南

Signal

Hard

OpenClaw 通过 signal-cli 的隐私优先连接

配置指南