跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

已可通过官方 Discord Gateway 网关用于私信和公会频道。

配对

Discord 私信默认进入配对模式。

斜杠命令

原生命令行为和命令目录。

渠道故障排除

跨渠道诊断和修复流程。

​
快速设置

你需要创建一个带有机器人的新应用，将机器人添加到你的服务器，并将它与 OpenClaw 配对。我们建议将你的机器人添加到你自己的私人服务器。如果你还没有服务器，请先创建一个（选择 Create My Own > For me and my friends）。
1

创建 Discord 应用和机器人

前往 Discord Developer Portal，然后点击 New Application。将它命名为类似 “OpenClaw” 的名称。点击侧边栏中的 Bot。将 Username 设置为你的 OpenClaw 智能体名称。
2

启用特权 intents

仍在 Bot 页面上，向下滚动到 Privileged Gateway Intents 并启用：
  • Message Content Intent（必需）
  • Server Members Intent（推荐；角色 allowlist 和名称到 ID 匹配需要）
  • Presence Intent（可选；仅在需要在线状态更新时才需要）
3

复制你的机器人令牌

在 Bot 页面向上滚动回去，然后点击 Reset Token。
虽然名称如此，但这会生成你的第一个令牌 —— 并不会“重置”任何内容。
复制令牌并将其保存到某个位置。这是你的 Bot Token，稍后会用到。
4

生成邀请 URL 并将机器人添加到你的服务器

点击侧边栏中的 OAuth2。你将生成一个带有正确权限的邀请 URL，用于将机器人添加到你的服务器。向下滚动到 OAuth2 URL Generator 并启用：
  • bot
  • applications.commands
下方会出现 Bot Permissions 部分。至少启用：General Permissions
  • View Channels Text Permissions
  • Send Messages
  • Read Message History
  • Embed Links
  • Attach Files
  • Add Reactions（可选）
这是普通文本频道的基线权限集。如果你计划在 Discord 线程中发帖，包括创建或继续线程的论坛或媒体频道工作流，也请启用 Send Messages in Threads。 复制底部生成的 URL，将其粘贴到浏览器中，选择你的服务器，然后点击 Continue 进行连接。现在你应该能在 Discord 服务器中看到你的机器人。
5

启用 Developer Mode 并收集你的 ID

回到 Discord 应用中，你需要启用 Developer Mode，这样才能复制内部 ID。
  1. 点击 User Settings（头像旁边的齿轮图标）→ Advanced → 打开 Developer Mode
  2. 右键点击侧边栏中的 server icon → Copy Server ID
  3. 右键点击你自己的 own avatar → Copy User ID
将你的 Server ID 和 User ID 与 Bot Token 一起保存 —— 下一步你会将这三项发送给 OpenClaw。
6

允许来自服务器成员的私信

为了让配对正常工作，Discord 需要允许你的机器人给你发送私信。右键点击你的 server icon → Privacy Settings → 打开 Direct Messages。这会允许服务器成员（包括机器人）向你发送私信。如果你想通过 OpenClaw 使用 Discord 私信，请保持此项启用。如果你只计划使用公会频道，可以在配对后禁用私信。
7

安全设置你的机器人令牌（不要在聊天中发送）

你的 Discord 机器人令牌是机密（类似密码）。在给你的智能体发送消息之前，请在运行 OpenClaw 的机器上设置它。
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 Mac 应用重启它，或停止并重新启动 openclaw gateway run 进程。 对于托管服务安装，请在存在 DISCORD_BOT_TOKEN 的 shell 中运行 openclaw gateway install，或将该变量存储在 ~/.openclaw/.env 中，这样服务在重启后就能解析 env SecretRef。 如果你的主机被 Discord 的启动应用查询阻止或限速，请从 Developer Portal 设置 Discord 应用/客户端 ID，这样启动时就能跳过该 REST 调用。默认账号使用 channels.discord.applicationId；运行多个 Discord 机器人时使用 channels.discord.accounts.<accountId>.applicationId。
8

配置 OpenClaw 并配对

在任意现有渠道（例如 Telegram）与你的 OpenClaw 智能体聊天并告诉它。如果 Discord 是你的第一个渠道，请改用 CLI / 配置标签页。
“我已经在配置中设置了 Discord 机器人令牌。请使用 User ID <user_id> 和 Server ID <server_id> 完成 Discord 设置。”
9

批准首次私信配对

等到 Gateway 网关运行后，在 Discord 中给你的机器人发送私信。它会回复一个配对码。
在你的现有渠道中将配对码发送给你的智能体：
“批准这个 Discord 配对码：<CODE>”
配对码会在 1 小时后过期。现在你应该可以通过私信在 Discord 中与你的智能体聊天。
令牌解析支持按账号处理。配置中的令牌值优先于 env 回退。DISCORD_BOT_TOKEN 仅用于默认账号。 如果两个已启用的 Discord 账号解析到同一个机器人令牌，OpenClaw 只会为该令牌启动一个 Gateway 网关监视器。来自配置的令牌优先于默认 env 回退；否则第一个启用的账号胜出，重复账号会被报告为已禁用。 对于高级出站调用（消息工具/渠道操作），显式的按调用 token 会用于该调用。这适用于发送和读取/探测类操作（例如读取/搜索/获取/线程/pins/权限）。账号策略/重试设置仍来自活动运行时快照中选定的账号。

​
推荐：设置公会工作区

私信可用后，你可以将 Discord 服务器设置为完整工作区，其中每个频道都会获得自己的智能体会话，并拥有自己的上下文。对于只有你和你的机器人的私人服务器，推荐这样做。
1

将你的服务器添加到公会 allowlist

这会让你的智能体可以在服务器上的任意频道中响应，而不仅是私信。
“将我的 Discord Server ID <server_id> 添加到公会 allowlist”
2

允许无需 @mention 即可响应

默认情况下，只有在公会频道中被 @mentioned 时，你的智能体才会响应。对于私人服务器，你可能希望它响应每条消息。在公会频道中，普通助手最终回复默认保持私密。可见的 Discord 输出必须使用 message 工具显式发送，因此智能体默认可以静默观察，只在判断频道回复有用时才发帖。这意味着选定的模型必须能可靠调用工具。如果 Discord 显示正在输入，日志显示有令牌用量，但没有发布消息，请检查会话日志中是否有带 didSendViaMessagingTool: false 的助手文本。这表示模型生成了私密最终答案，而不是调用 message(action=send)。请切换到更强的工具调用模型，或使用下面的配置恢复旧版自动最终回复。
“允许我的智能体在这个服务器上响应，而不必被 @mentioned”
3

规划公会频道中的记忆

默认情况下，长期记忆（MEMORY.md）只会在私信会话中加载。公会频道不会自动加载 MEMORY.md。
“当我在 Discord 频道中提问时，如果你需要 MEMORY.md 中的长期上下文，请使用 memory_search 或 memory_get。”
现在在你的 Discord 服务器上创建一些频道并开始聊天。你的智能体可以看到频道名称，并且每个频道都会获得自己的隔离会话 —— 因此你可以设置 #coding、#home、#research，或任何适合你工作流的频道。

​
运行时模型

  • Gateway 网关拥有 Discord 连接。
  • 回复路由是确定性的：Discord 入站回复会回到 Discord。
  • Discord guild/渠道元数据会作为不受信任的上下文添加到模型提示中，而不是作为用户可见的回复前缀。如果模型把该包络复制回来，OpenClaw 会从出站回复和未来的回放上下文中剥离复制的元数据。
  • 默认情况下（session.dmScope=main），直接聊天共享智能体主会话（agent:main:main）。
  • Guild 渠道使用隔离的会话键（agent:<agentId>:discord:channel:<channelId>）。
  • 群组私信默认会被忽略（channels.discord.dm.groupEnabled=false）。
  • 原生斜杠命令在隔离的命令会话中运行（agent:<agentId>:discord:slash:<userId>），同时仍携带 CommandTargetSessionKey 到已路由的对话会话。
  • 面向 Discord 的纯文本 cron/heartbeat 通告投递会使用最终的助手可见答案一次。媒体和结构化组件载荷在智能体发出多个可投递载荷时仍保持多消息形式。

​
论坛渠道

Discord 论坛和媒体渠道只接受线程帖子。OpenClaw 支持两种创建方式：
  • 向论坛父级（channel:<forumId>）发送消息以自动创建线程。线程标题使用你消息中的第一个非空行。
  • 使用 openclaw message thread create 直接创建线程。不要为论坛渠道传入 --message-id。
示例：发送到论坛父级以创建线程 
openclaw message send --channel discord --target channel:<forumId> \
  --message "Topic title\nBody of the post"
示例：显式创建论坛线程 
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 容器。使用带有 components 载荷的消息工具。交互结果会作为普通入站消息路由回智能体，并遵循现有 Discord replyToMode 设置。 支持的区块：
  • text、section、separator、actions、media-gallery、file
  • Action rows 最多允许 5 个按钮或一个选择菜单
  • 选择类型：string、user、role、mentionable、channel
默认情况下，组件只能使用一次。设置 components.reusable=true 以允许按钮、选择框和表单在过期前多次使用。 要限制谁可以点击按钮，请在该按钮上设置 allowedUsers（Discord 用户 ID、标签或 *）。配置后，不匹配的用户会收到一条 ephemeral 拒绝消息。 /model 和 /models 斜杠命令会打开一个交互式模型选择器，其中包含提供商、模型和兼容运行时下拉框以及一个提交步骤。/models add 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。选择器回复是 ephemeral，且只有调用用户可以使用它。 文件附件：
  • file 区块必须指向附件引用（attachment://<filename>）
  • 通过 media/path/filePath 提供附件（单个文件）；多个文件请使用 media-gallery
  • 当上传名称应与附件引用匹配时，使用 filename 覆盖上传名称
模态表单：
  • 添加 components.modal，最多包含 5 个字段
  • 字段类型：text、checkbox、radio、select、role-select、user-select
  • OpenClaw 会自动添加触发按钮
示例： 
{
  channel: "discord",
  action: "send",
  to: "channel:123456789012345678",
  message: "Optional fallback text",
  components: {
    reusable: true,
    text: "Choose a path",
    blocks: [
      {
        type: "actions",
        buttons: [
          {
            label: "Approve",
            style: "success",
            allowedUsers: ["123456789012345678"],
          },
          { label: "Decline", style: "danger" },
        ],
      },
      {
        type: "actions",
        select: {
          type: "string",
          placeholder: "Pick an option",
          options: [
            { label: "Option A", value: "a" },
            { label: "Option B", value: "b" },
          ],
        },
      },
    ],
    modal: {
      title: "Details",
      triggerLabel: "Open form",
      fields: [
        { type: "text", label: "Requester" },
        {
          type: "select",
          label: "Priority",
          options: [
            { label: "Low", value: "low" },
            { label: "High", value: "high" },
          ],
        },
      ],
    },
  },
}

​
访问控制和路由

channels.discord.dmPolicy 控制私信访问。channels.discord.allowFrom 是规范的私信允许列表。
  • pairing（默认）
  • allowlist
  • open（要求 channels.discord.allowFrom 包含 "*"）
  • disabled
如果私信策略不是开放的，未知用户会被阻止（或在 pairing 模式下提示配对）。多账号优先级：
  • channels.discord.accounts.default.allowFrom 仅适用于 default 账号。
  • 对于单个账号，allowFrom 优先于旧版 dm.allowFrom。
  • 当命名账号自身的 allowFrom 和旧版 dm.allowFrom 未设置时，它们会继承 channels.discord.allowFrom。
  • 命名账号不会继承 channels.discord.accounts.default.allowFrom。
旧版 channels.discord.dm.policy 和 channels.discord.dm.allowFrom 仍会为兼容性读取。openclaw doctor --fix 会在不改变访问权限的情况下，将它们迁移到 dmPolicy 和 allowFrom。用于投递的私信目标格式：
  • user:<id>
  • <@id> 提及
当渠道默认值处于活动状态时，裸数字 ID 通常会解析为渠道 ID，但账号有效私信 allowFrom 中列出的 ID 会为了兼容性被视为用户私信目标。

​
基于角色的智能体路由

使用 bindings[].match.roles 按角色 ID 将 Discord guild 成员路由到不同智能体。基于角色的绑定仅接受角色 ID，并在 peer 或 parent-peer 绑定之后、guild-only 绑定之前求值。如果绑定还设置了其他匹配字段（例如 peer + guildId + roles），则所有已配置字段都必须匹配。 
{
  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 应用中移除它们。
  • 原生命令鉴权使用与普通消息处理相同的 Discord allowlist/策略。
  • 对未授权的用户，命令可能仍会在 Discord UI 中可见；执行时仍会强制应用 OpenClaw 鉴权，并返回 “not authorized”。
请参阅斜杠命令，了解命令目录和行为。 默认斜杠命令设置：
  • ephemeral: true

​
功能详情

Discord 支持在智能体输出中使用回复标签：
  • [[reply_to_current]]
  • [[reply_to:<id>]]
由 channels.discord.replyToMode 控制：
  • off（默认）
  • first
  • all
  • batched
注意：off 会禁用隐式回复串联。显式 [[reply_to_*]] 标签仍会生效。 first 始终会把隐式原生回复引用附加到本轮的第一条出站 Discord 消息。 batched 仅在入站轮次是由多条消息防抖合并成的批次时，才会附加 Discord 的隐式原生回复引用。这适合在你主要想为含义不明确的突发聊天使用原生回复，而不是为每个单消息轮次都使用原生回复时使用。消息 ID 会在上下文/历史中暴露，以便智能体可以定位特定消息。
OpenClaw 可以通过发送临时消息并在文本到达时编辑它，来流式传输草稿回复。channels.discord.streaming 接受 off（默认）| partial | block | progress。progress 会保留一个可编辑的 Status 草稿，并用工具进度更新它，直到最终送达；streamMode 是旧版别名，会自动迁移。默认保持为 off，因为当多个机器人或 Gateway 网关共享一个账号时，Discord 预览编辑会很快触发速率限制。
{
  channels: {
    discord: {
      streaming: "block",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph",
      },
    },
  },
}
  • partial 会在 token 到达时编辑单条预览消息。
  • block 会发出草稿大小的分块（使用 draftChunk 调整大小和断点，并限制在 textChunkLimit 内）。
  • 媒体、错误和显式回复的最终消息会取消待处理的预览编辑。
  • streaming.preview.toolProgress（默认 true）控制工具/进度更新是否复用预览消息。
  • streaming.preview.commandText / streaming.progress.commandText 控制紧凑进度行中的命令/执行详情：raw（默认）或 status（仅工具标签）。
在保留紧凑进度行的同时隐藏原始命令/执行文本：
{
  "channels": {
    "discord": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}
预览流式传输仅支持文本；媒体回复会回退到正常送达。当显式启用 block 流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。
公会历史上下文：
  • channels.discord.historyLimit 默认值 20
  • 回退：messages.groupChat.historyLimit
  • 0 禁用
私信历史控制：
  • channels.discord.dmHistoryLimit
  • channels.discord.dms["<user_id>"].historyLimit
线程行为：
  • Discord 线程会作为渠道会话路由，并继承父渠道配置，除非被覆盖。
  • 线程会话会继承父渠道的会话级 /model 选择，作为仅模型回退；线程本地的 /model 选择仍优先，并且不会复制父转录历史，除非启用了转录继承。
  • channels.discord.thread.inheritParent（默认 false）会让新的自动线程选择从父转录播种。按账号覆盖位于 channels.discord.accounts.<id>.thread.inheritParent 下。
  • 消息工具 reaction 可以解析 user:<id> 私信目标。
  • guilds.<guild>.channels.<channel>.requireMention: false 会在回复阶段激活回退期间保留。
渠道主题会作为不受信任上下文注入。allowlist 用于限制谁可以触发智能体，而不是完整的补充上下文脱敏边界。
Discord 可以将线程绑定到会话目标，使该线程中的后续消息继续路由到同一会话（包括子智能体会话）。命令：
  • /focus <target> 将当前/新线程绑定到子智能体/会话目标
  • /unfocus 移除当前线程绑定
  • /agents 显示活跃运行和绑定状态
  • /session idle <duration|off> 查看/更新已聚焦绑定的不活跃自动取消聚焦设置
  • /session max-age <duration|off> 查看/更新已聚焦绑定的硬性最长存续时间
配置：
{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSessions: true,
        defaultSpawnContext: "fork",
      },
    },
  },
}
说明：
  • session.threadBindings.* 设置全局默认值。
  • channels.discord.threadBindings.* 覆盖 Discord 行为。
  • spawnSessions 控制为 sessions_spawn({ thread: true }) 和 ACP 线程生成自动创建/绑定线程。默认：true。
  • defaultSpawnContext 控制线程绑定生成的原生子智能体上下文。默认："fork"。
  • 已弃用的 spawnSubagentSessions/spawnAcpSessions 键会由 openclaw doctor --fix 迁移。
  • 如果某个账号禁用了线程绑定，则 /focus 和相关线程绑定操作不可用。
请参阅子智能体、ACP Agents 和配置参考。
对于稳定的“始终在线” ACP 工作区，请配置顶层类型化 ACP 绑定，目标指向 Discord 对话。配置路径：
  • bindings[]，其中包含 type: "acp" 和 match.channel: "discord"
示例：
{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "discord",
        accountId: "default",
        peer: { kind: "channel", id: "222222222222222222" },
      },
      acp: { label: "codex-main" },
    },
  ],
  channels: {
    discord: {
      guilds: {
        "111111111111111111": {
          channels: {
            "222222222222222222": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}
说明：
  • /acp spawn codex --bind here 会就地绑定当前渠道或线程，并让未来消息保持在同一个 ACP 会话上。线程消息会继承父渠道绑定。
  • 在已绑定的渠道或线程中，/new 和 /reset 会就地重置同一个 ACP 会话。临时线程绑定在活跃时可以覆盖目标解析。
  • spawnSessions 通过 --thread auto|here 控制子线程创建/绑定。
请参阅 ACP Agents 了解绑定行为详情。
按公会设置 reaction 通知模式：
  • off
  • own（默认）
  • all
  • allowlist（使用 guilds.<id>.users）
Reaction 事件会转换为系统事件，并附加到已路由的 Discord 会话。
ackReaction 会在 OpenClaw 处理入站消息时发送确认 emoji。解析顺序：
  • channels.discord.accounts.<accountId>.ackReaction
  • channels.discord.ackReaction
  • messages.ackReaction
  • 智能体身份 emoji 回退（agents.list[].identity.emoji，否则为 ”👀”）
说明：
  • Discord 接受 Unicode emoji 或自定义 emoji 名称。
  • 使用 "" 可为某个渠道或账号禁用 reaction。
渠道发起的配置写入默认启用。这会影响 /config set|unset 流程（当命令功能启用时）。禁用：
{
  channels: {
    discord: {
      configWrites: false,
    },
  },
}
使用 channels.discord.proxy 通过 HTTP(S) 代理路由 Discord gateway WebSocket 流量和启动时 REST 查询（应用 ID + allowlist 解析）。
{
  channels: {
    discord: {
      proxy: "http://proxy.example:8080",
    },
  },
}
按账号覆盖：
{
  channels: {
    discord: {
      accounts: {
        primary: {
          proxy: "http://proxy.example:8080",
        },
      },
    },
  },
}
启用 PluralKit 解析，将代理消息映射到系统成员身份：
{
  channels: {
    discord: {
      pluralkit: {
        enabled: true,
        token: "pk_live_...", // optional; needed for private systems
      },
    },
  },
}
说明：
  • allowlist 可以使用 pk:<memberId>
  • 仅当 channels.discord.dangerouslyAllowNameMatching: true 时，才会按名称/slug 匹配成员显示名
  • 查询使用原始消息 ID，并受时间窗口限制
  • 如果查询失败，代理消息会被视为机器人消息并丢弃，除非 allowBots=true
当智能体需要对已知 Discord 用户进行确定性的出站提及时，请使用 mentionAliases。键是不带前导 @ 的 handle；值是 Discord 用户 ID。未知 handle、@everyone、@here 以及 Markdown 代码 span 内的提及会保持不变。
{
  channels: {
    discord: {
      mentionAliases: {
        Vladislava: "123456789012345678",
      },
      accounts: {
        ops: {
          mentionAliases: {
            OpsLead: "234567890123456789",
          },
        },
      },
    },
  },
}
当你设置 Status 或 activity 字段，或启用自动在线状态时，会应用在线状态更新。仅 Status 示例：
{
  channels: {
    discord: {
      status: "idle",
    },
  },
}
Activity 示例（自定义 Status 是默认 activity 类型）：
{
  channels: {
    discord: {
      activity: "Focus time",
      activityType: 4,
    },
  },
}
流式传输示例：
{
  channels: {
    discord: {
      activity: "Live coding",
      activityType: 1,
      activityUrl: "https://twitch.tv/openclaw",
    },
  },
}
Activity 类型映射：
  • 0：正在玩
  • 1：流式传输（需要 activityUrl）
  • 2：正在听
  • 3：正在观看
  • 4：自定义（使用 activity 文本作为 Status 状态；emoji 可选）
  • 5：正在竞赛
自动在线状态示例（运行时健康信号）：
{
  channels: {
    discord: {
      autoPresence: {
        enabled: true,
        intervalMs: 30000,
        minUpdateIntervalMs: 15000,
        exhaustedText: "token exhausted",
      },
    },
  },
}
自动状态会将运行时可用性映射到 Discord 状态：healthy => online，degraded 或 unknown => idle，exhausted 或 unavailable => dnd。可选文本覆盖：
  • autoPresence.healthyText
  • autoPresence.degradedText
  • autoPresence.exhaustedText（支持 {reason} 占位符）
Discord 支持在私信中基于按钮处理审批，也可以选择在原始渠道中发布审批提示。配置路径：
  • channels.discord.execApprovals.enabled
  • channels.discord.execApprovals.approvers（可选；可能时回退到 commands.ownerAllowFrom）
  • channels.discord.execApprovals.target（dm | channel | both，默认：dm）
  • agentFilter、sessionFilter、cleanupAfterResolve
当 enabled 未设置或为 "auto"，且至少可以从 execApprovals.approvers 或 commands.ownerAllowFrom 解析出一个审批人时，Discord 会自动启用原生 exec 审批。Discord 不会从渠道 allowFrom、旧版 dm.allowFrom 或直接消息 defaultTo 推断 exec 审批人。设置 enabled: false 可明确禁用 Discord 作为原生审批客户端。对于 /diagnostics 和 /export-trajectory 等敏感的仅所有者群组命令，OpenClaw 会私下发送审批提示和最终结果。当调用的所有者有 Discord 所有者路由时，它会优先尝试 Discord 私信；如果不可用，则回退到 commands.ownerAllowFrom 中第一个可用的所有者路由，例如 Telegram。当 target 为 channel 或 both 时，审批提示会在渠道中可见。只有已解析的审批人可以使用按钮；其他用户会收到一条临时拒绝消息。审批提示包含命令文本，因此只应在受信任的渠道中启用渠道投递。如果无法从会话键派生渠道 ID，OpenClaw 会回退到私信投递。Discord 还会渲染其他聊天渠道使用的共享审批按钮。原生 Discord 适配器主要添加审批人私信路由和渠道扇出。 当这些按钮存在时，它们是主要审批用户体验；OpenClaw 只有在工具结果表明聊天审批不可用，或手动审批是唯一路径时， 才应包含手动 /approve 命令。 如果 Discord 原生审批运行时未激活，OpenClaw 会保持 本地确定性的 /approve <id> <decision> 提示可见。如果 运行时已激活但无法向任何目标投递原生卡片， OpenClaw 会在同一聊天中发送回退通知，其中包含待处理审批中的精确 /approve 命令。Gateway 网关认证和审批解析遵循共享 Gateway 网关客户端契约（plugin: ID 通过 plugin.approval.resolve 解析；其他 ID 通过 exec.approval.resolve 解析）。审批默认在 30 分钟后过期。参见 Exec 审批。

​
工具和操作门禁

Discord 消息操作包括消息、渠道管理、审核、状态和元数据操作。 核心示例：
  • 消息：sendMessage、readMessages、editMessage、deleteMessage、threadReply
  • 表情回应：react、reactions、emojiList
  • 审核：timeout、kick、ban
  • 状态：setPresence
event-create 操作接受可选的 image 参数（URL 或本地文件路径），用于设置定时事件封面图片。 操作门禁位于 channels.discord.actions.* 下。 默认门禁行为：
操作组默认值
reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissionsenabled
rolesdisabled
moderationdisabled
presencedisabled

​
Components v2 UI

OpenClaw 对 exec 审批和跨上下文标记使用 Discord components v2。Discord 消息操作也可以接受 components 以实现自定义 UI（高级；需要通过 discord 工具构造组件载荷），旧版 embeds 仍可使用，但不推荐。
  • channels.discord.ui.components.accentColor 设置 Discord 组件容器使用的强调色（十六进制）。
  • 使用 channels.discord.accounts.<id>.ui.components.accentColor 为每个账号设置。
  • 当 components v2 存在时，embeds 会被忽略。
示例： 
{
  channels: {
    discord: {
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
    },
  },
}

​
语音

Discord 有两个不同的语音表面：实时 语音频道（连续对话）和 语音消息附件（波形预览格式）。Gateway 网关同时支持两者。

​
语音频道

设置检查清单：
  1. 在 Discord Developer Portal 中启用 Message Content Intent。
  2. 使用角色/用户允许列表时，启用 Server Members Intent。
  3. 使用 bot 和 applications.commands scopes 邀请机器人。
  4. 在目标语音频道中授予 Connect、Speak、Send Messages 和 Read Message History 权限。
  5. 启用原生命令（commands.native 或 channels.discord.commands.native）。
  6. 配置 channels.discord.voice。
使用 /vc join|leave|status 控制会话。该命令使用账号默认智能体，并遵循与其他 Discord 命令相同的允许列表和群组策略规则。 
/vc join channel:<voice-channel-id>
/vc status
/vc leave
自动加入示例： 
{
  channels: {
    discord: {
      voice: {
        enabled: true,
        model: "openai/gpt-5.4-mini",
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        connectTimeoutMs: 30000,
        reconnectGraceMs: 15000,
        tts: {
          provider: "openai",
          openai: { voice: "onyx" },
        },
      },
    },
  },
}
说明：
  • voice.tts 仅针对语音播放覆盖 messages.tts。
  • voice.model 仅覆盖用于 Discord 语音频道响应的 LLM。保持未设置可继承已路由的智能体模型。
  • STT 使用 tools.media.audio；voice.model 不影响转录。
  • 每个渠道的 Discord systemPrompt 覆盖会应用于该语音频道的语音转录轮次。
  • 语音转录轮次会从 Discord allowFrom（或 dm.allowFrom）派生所有者状态；非所有者说话者无法访问仅所有者工具（例如 gateway 和 cron）。
  • Discord 语音对于纯文本配置是选择加入；设置 channels.discord.voice.enabled=true（或保留现有 channels.discord.voice 块）以启用 /vc 命令、语音运行时和 GuildVoiceStates gateway intent。
  • channels.discord.intents.voiceStates 可以显式覆盖 voice-state intent 订阅。保持未设置时，该 intent 会跟随有效的语音启用状态。
  • voice.daveEncryption 和 voice.decryptionFailureTolerance 会透传给 @discordjs/voice 加入选项。
  • 如果未设置，@discordjs/voice 默认值为 daveEncryption=true 和 decryptionFailureTolerance=24。
  • voice.connectTimeoutMs 控制 /vc join 和自动加入尝试的初始 @discordjs/voice Ready 等待时间。默认值：30000。
  • voice.reconnectGraceMs 控制 OpenClaw 在销毁已断开的语音会话前，等待其开始重新连接的时长。默认值：15000。
  • OpenClaw 还会监视接收端解密失败，并在短时间窗口内重复失败后通过离开/重新加入语音频道自动恢复。
  • 如果更新后接收日志反复显示 DecryptionFailed(UnencryptedWhenPassthroughDisabled)，请收集依赖报告和日志。内置的 @discordjs/voice 行包含来自 discord.js PR #11449 的上游填充修复，该修复关闭了 discord.js issue #11419。
语音频道流水线：
  • Discord PCM 捕获会转换为 WAV 临时文件。
  • tools.media.audio 处理 STT，例如 openai/gpt-4o-mini-transcribe。
  • 转录会通过 Discord 入口和路由发送，同时响应 LLM 会使用语音输出策略运行，该策略隐藏智能体 tts 工具并要求返回文本，因为 Discord 语音负责最终 TTS 播放。
  • 设置 voice.model 时，它仅覆盖此语音频道轮次的响应 LLM。
  • voice.tts 会合并覆盖 messages.tts；生成的音频会在已加入的频道中播放。
凭证按组件解析：voice.model 的 LLM 路由认证、tools.media.audio 的 STT 认证，以及 messages.tts/voice.tts 的 TTS 认证。

​
语音消息

Discord 语音消息会显示波形预览，并要求 OGG/Opus 音频。OpenClaw 会自动生成波形，但需要 gateway 主机上的 ffmpeg 和 ffprobe 来检查和转换。
  • 提供 本地文件路径（URL 会被拒绝）。
  • 省略文本内容（Discord 会拒绝同一载荷中的文本 + 语音消息）。
  • 接受任意音频格式；OpenClaw 会按需转换为 OGG/Opus。
message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true)

​
故障排除

  • 启用 Message Content Intent
  • 当你依赖用户/成员解析时，启用 Server Members Intent
  • 更改 intents 后重启 gateway
  • 验证 groupPolicy
  • 验证 channels.discord.guilds 下的服务器允许列表
  • 如果服务器 channels 映射存在，则只允许列出的渠道
  • 验证 requireMention 行为和提及模式
有用的检查：
openclaw doctor
openclaw channels status --probe
openclaw logs --follow
常见原因：
  • groupPolicy="allowlist" 但没有匹配的服务器/渠道允许列表
  • requireMention 配置在了错误位置（必须位于 channels.discord.guilds 或渠道条目下）
  • 发送者被服务器/渠道 users 允许列表阻止
典型日志：
  • Slow listener detected ...
  • stuck session: sessionKey=agent:...:discord:... state=processing ...
Discord gateway 队列调节项：
  • 单账号：channels.discord.eventQueue.listenerTimeout
  • 多账号：channels.discord.accounts.<accountId>.eventQueue.listenerTimeout
  • 这只控制 Discord gateway 监听器工作，而不是智能体轮次生命周期
Discord 不会对排队的智能体轮次应用渠道拥有的超时。消息监听器会立即交接，排队的 Discord 运行会保持每个会话的顺序，直到会话/工具/运行时生命周期完成或中止工作。
{
  channels: {
    discord: {
      accounts: {
        default: {
          eventQueue: {
            listenerTimeout: 120000,
          },
        },
      },
    },
  },
}
OpenClaw 会在连接前获取 Discord /gateway/bot 元数据。短暂故障会回退到 Discord 的默认网关 URL，并在日志中限频记录。元数据超时配置项：
  • 单账号：channels.discord.gatewayInfoTimeoutMs
  • 多账号：channels.discord.accounts.<accountId>.gatewayInfoTimeoutMs
  • 配置未设置时的环境变量回退：OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS
  • 默认值：30000（30 秒），最大值：120000
OpenClaw 会在启动期间以及运行时重连后等待 Discord 的网关 READY 事件。带启动错峰的多账号设置可能需要比默认值更长的启动 READY 等待窗口。READY 超时配置项：
  • 启动单账号：channels.discord.gatewayReadyTimeoutMs
  • 启动多账号：channels.discord.accounts.<accountId>.gatewayReadyTimeoutMs
  • 配置未设置时的启动环境变量回退：OPENCLAW_DISCORD_READY_TIMEOUT_MS
  • 启动默认值：15000（15 秒），最大值：120000
  • 运行时单账号：channels.discord.gatewayRuntimeReadyTimeoutMs
  • 运行时多账号：channels.discord.accounts.<accountId>.gatewayRuntimeReadyTimeoutMs
  • 配置未设置时的运行时环境变量回退：OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS
  • 运行时默认值：30000（30 秒），最大值：120000
channels status --probe 权限检查仅适用于数字渠道 ID。如果你使用 slug 键，运行时匹配仍可工作，但探测无法完整验证权限。
  • 私信已禁用：channels.discord.dm.enabled=false
  • 私信策略已禁用：channels.discord.dmPolicy="disabled"（旧版：channels.discord.dm.policy）
  • 在 pairing 模式中等待配对批准
默认情况下会忽略机器人发送的消息。如果你设置 channels.discord.allowBots=true，请使用严格的提及和允许列表规则来避免循环行为。 优先使用 channels.discord.allowBots="mentions"，仅接受提及该机器人的机器人消息。
{
  channels: {
    discord: {
      accounts: {
        mantis: {
          // Mantis listens to other bots only when they mention her.
          allowBots: "mentions",
        },
        molty: {
          // Molty listens to all bot-authored Discord messages.
          allowBots: true,
          mentionAliases: {
            // Lets Molty write "@Mantis" and send a real Discord mention.
            Mantis: "MANTIS_DISCORD_USER_ID",
          },
        },
      },
    },
  },
}
  • 保持 OpenClaw 为最新版本（openclaw update），确保包含 Discord 语音接收恢复逻辑
  • 确认 channels.discord.voice.daveEncryption=true（默认）
  • 从 channels.discord.voice.decryptionFailureTolerance=24（上游默认值）开始，仅在需要时调整
  • 在日志中留意：
    • discord voice: DAVE decrypt failures detected
    • discord voice: repeated decrypt failures; attempting rejoin
  • 如果自动重新加入后故障仍继续，请收集日志，并与 discord.js #11419 和 discord.js #11449 中的上游 DAVE 接收历史进行对比

​
配置参考

主要参考：配置参考 - Discord。
  • 启动/身份验证：enabled、token、accounts.*、allowBots
  • 策略：groupPolicy、dm.*、guilds.*、guilds.*.channels.*
  • 命令：commands.native、commands.useAccessGroups、configWrites、slashCommand.*
  • 事件队列：eventQueue.listenerTimeout（监听器预算）、eventQueue.maxQueueSize、eventQueue.maxConcurrency
  • 网关：gatewayInfoTimeoutMs、gatewayReadyTimeoutMs、gatewayRuntimeReadyTimeoutMs
  • 回复/历史记录：replyToMode、historyLimit、dmHistoryLimit、dms.*.historyLimit
  • 发送：textChunkLimit、chunkMode、maxLinesPerMessage
  • 流式传输：streaming（旧版别名：streamMode）、streaming.preview.toolProgress、draftChunk、blockStreaming、blockStreamingCoalesce
  • 媒体/重试：mediaMaxMb（限制传出的 Discord 上传，默认 100MB）、retry
  • 操作：actions.*
  • 在线状态：activity、status、activityType、activityUrl
  • UI：ui.components.accentColor
  • 功能：threadBindings、顶层 bindings[]（type: "acp"）、pluralkit、execApprovals、intents、agentComponents、heartbeat、responsePrefix

​
安全和运维

  • 将机器人令牌视为机密（在受管环境中优先使用 DISCORD_BOT_TOKEN）。
  • 只授予最低必要的 Discord 权限。
  • 如果命令部署/状态已过期，请重启 Gateway 网关，并用 openclaw channels status --probe 重新检查。

​
相关

配对

将一个 Discord 用户配对到 Gateway 网关。

群组

群聊和允许列表行为。

渠道路由

将传入消息路由到智能体。

安全

威胁模型和加固。

多智能体路由

将服务器和渠道映射到智能体。

斜杠命令

原生命令行为。