Discord

将你的 ZeroClaw 智能体作为 Discord 机器人运行。本指南将逐步带你完成操作，无需任何机器人开发经验。完成后，你将拥有一个驻留在服务器中的机器人，当有人与它对话时它会作出回复。

谁可以与代理通信

入站发送方会根据为绑定代理解析出的对等集合进行限制，该集合来自代理所属的 peer_groups 配置。匹配时会去除开头的 @，并对通道的原生发送方标识符执行不区分大小写的比对。空集合会拒绝所有人；包含 "*" 的集合会接受所有人；否则仅接受列出的外部对等方（以及对等代理）。这与网关配对（gateway.require_pairing）不同，后者验证的是 HTTP/WebSocket 客户端，而非聊天通道的发送方。

用于 discord 的对等组将 channel 设置为 discord，在 external_peers 中列出允许的发送者（对于 discord，即 Discord 用户 ID（snowflake）；["*"] 接受任何人），可选地命名对等 agents 以进行跨代理调度、一个 ignore 屏蔽列表，以及一个 output_modality（mirror、voice 或 text）。字段参考请参见 Peer Groups。

在何处设置：

快速开始

五个步骤：创建机器人、复制它的令牌、打开两个开关、邀请它，然后启动 ZeroClaw。

1. 创建机器人

1. 前往 Discord 开发者门户。
2. 单击 New Application，为其命名，然后单击 Create。
3. 在左侧边栏中，单击 Bot。
4. 点击 Reset Token，然后点击 Copy。这串很长的字符就是你的 bot_token。请妥善保存以备第 3 步使用，之后你将无法再次查看（只能重置）。

机器人令牌是你的机器人的密码。任何拥有它的人都可以控制你的机器人。切勿将其粘贴到公开聊天、截图中，或提交到 git。

2. 开启机器人所需的两个开关

仍在 Bot 页面，向下滚动到 Privileged Gateway Intents，并将这两个选项都开启：

• Message Content Intent，使机器人能够读取用户输入的内容。
• 服务器成员意图（Server Members Intent），以便它能查看服务器中有哪些成员。

点击 Save Changes。如果跳过此步骤，机器人虽然能连接但无法接收任何消息，这正是“机器人毫无反应”最常见的原因。

3. 将机器人信息告知 ZeroClaw

将步骤 1 中的令牌放入你的配置。该令牌是机密信息，因此请通过可以加密它的方式进行设置，而不要直接键入到 config.toml 中：

channels.discord.<alias>.bot_token 是一项机密信息。 它以加密形式存储，绝不会以明文形式保存在 config.toml 中。请通过以下方式之一进行设置，这些方式会在写入时进行加密：

zeroclaw config set channels.discord.<alias>.bot_token    # 提示输入掩码内容，以加密形式存储

4. 邀请机器人加入你的服务器

1. 回到 Developer Portal，打开 OAuth2 -> URL Generator。
2. 在 Scopes 下，勾选 bot。
3. 在 Bot Permissions 下，至少勾选 Send Messages、Read Message History 和 View Channels。
4. 复制底部的 URL，在浏览器中打开它，选择你的服务器，然后点击 Authorize。

机器人现在会显示在你的成员列表中（在你启动 ZeroClaw 之前显示为离线状态）。

5. 启动并测试

启动 ZeroClaw（zeroclaw service restart 或 zeroclaw daemon），然后在机器人可见的频道中发送一条消息。它应该会回复。如果没有回复，请跳转到故障排查。

配置

完整字段列表派生自实时架构。大多数字段都有合理的默认值；对于基本的机器人，你只需设置 bot_token。

zeroclaw config set channels.discord.<alias>.approval_timeout_secs <value>

export ZEROCLAW_channels__discord__<alias>__approval_timeout_secs=

zeroclaw config set channels.discord.<alias>.archive <value>

export ZEROCLAW_channels__discord__<alias>__archive=

zeroclaw config set channels.discord.<alias>.bot_token    # 掩码输入，加密存储

export ZEROCLAW_channels__discord__<alias>__bot_token=

zeroclaw config set channels.discord.<alias>.channel_ids <value>

export ZEROCLAW_channels__discord__<alias>__channel_ids=

zeroclaw config set channels.discord.<alias>.draft_update_interval_ms <value>

export ZEROCLAW_channels__discord__<alias>__draft_update_interval_ms=

zeroclaw config set channels.discord.<alias>.excluded_tools <value>

export ZEROCLAW_channels__discord__<alias>__excluded_tools=

zeroclaw config set channels.discord.<alias>.guild_ids <value>

export ZEROCLAW_channels__discord__<alias>__guild_ids=

zeroclaw config set channels.discord.<alias>.intents_mask <value>

export ZEROCLAW_channels__discord__<alias>__intents_mask=

zeroclaw config set channels.discord.<alias>.interrupt_on_new_message <value>

export ZEROCLAW_channels__discord__<alias>__interrupt_on_new_message=

zeroclaw config set channels.discord.<alias>.listen_to_bots <value>

export ZEROCLAW_channels__discord__<alias>__listen_to_bots=

zeroclaw config set channels.discord.<alias>.mention_only <value>

export ZEROCLAW_channels__discord__<alias>__mention_only=

zeroclaw config set channels.discord.<alias>.multi_message_delay_ms <value>

export ZEROCLAW_channels__discord__<alias>__multi_message_delay_ms=

zeroclaw config set channels.discord.<alias>.proxy_url <value>

export ZEROCLAW_channels__discord__<alias>__proxy_url=

zeroclaw config set channels.discord.<alias>.reaction_notifications <value>

export ZEROCLAW_channels__discord__<alias>__reaction_notifications=

zeroclaw config set channels.discord.<alias>.reply_min_interval_secs <value>

export ZEROCLAW_channels__discord__<alias>__reply_min_interval_secs=

zeroclaw config set channels.discord.<alias>.reply_queue_depth_max <value>

export ZEROCLAW_channels__discord__<alias>__reply_queue_depth_max=

zeroclaw config set channels.discord.<alias>.slash_command_scope <value>

export ZEROCLAW_channels__discord__<alias>__slash_command_scope=

zeroclaw config set channels.discord.<alias>.slash_commands <value>

export ZEROCLAW_channels__discord__<alias>__slash_commands=

zeroclaw config set channels.discord.<alias>.stall_timeout_secs <value>

export ZEROCLAW_channels__discord__<alias>__stall_timeout_secs=

zeroclaw config set channels.discord.<alias>.stream_mode <value>

export ZEROCLAW_channels__discord__<alias>__stream_mode=

缩小机器人监听的范围

默认情况下，机器人会在它被邀请加入的每个服务器以及它能看到的每个频道中进行监听。要缩小其作用范围：

• guild_ids：将该机器人限制在特定服务器（公会）中。留空表示所有服务器。
• channel_ids：将其限制为特定频道。留空表示所有可见频道。

若要查找 ID，请在 Discord 中启用开发者模式（用户设置 -> 高级），然后右键单击服务器或频道并选择复制 ID。

线程与上下文

当 Discord 对话发生在某个帖子（thread）中时，该帖子即为一个独立的对话。ZeroClaw 会为每个帖子派生出不同的会话密钥，因此每个帖子都拥有独立的上下文窗口和历史记录：某个帖子中的消息绝不会渗入另一个帖子，且智能体也无法看到同级帖子中较早的对话轮次。对于 Discord 而言，帖子是原生频道，因此每个帖子本身就是一个独立的对话：无需设置任何开关。

• 隔离正是关键所在。 每个线程的上下文都是自包含的：它不会泄漏到线程之外，线程之外的任何内容也不会泄漏进来。并行线程持有各自独立的对话状态，因此互不相关的任务永远不会相互干扰。
• 长线程会增大上下文。 线程在保持活动状态期间会累积历史记录，因此与其他长对话一样，过长的线程最终会填满模型的上下文窗口。开始新线程即可重置。
• 进行中的工作以线程为单位进行隔离。 在某个线程中发送新消息不会取消另一个线程中进行中的响应；每个线程的任务都是独立的。

归档和搜索

将 archive = true 设置为开启后，该频道会打开一个附属的 discord.db 记忆存储，记录它所看到的每一条消息，并注册一个 discord_search 工具供代理用来查找过去的对话。如果你不需要历史搜索，可以将其保持关闭；无论哪种方式，机器人仍会正常回复。

流式传输

Discord 通过 stream_mode 设置来流式传输回复：

• off（默认）：整条回复在 agent 完成后作为一条消息发送。最简单，且永远不会显示写到一半的答案。
• partial：机器人会立即发布一条草稿，并在答案流式传输的过程中就地编辑它。draft_update_interval_ms 用于控制编辑的节奏；如果 Discord 对编辑进行速率限制，请调高此值。
• multi_message：每个段落作为独立消息发送，以 multi_message_delay_ms 间隔分隔。适用于较长的回答，避免内容堆积成一大段文字。

将其放置在任何表面上：

zeroclaw config set channels.discord.<alias>.stream_mode <value>

让人感觉自然的回复

• mention_only：设置为 true 时，机器人仅回复 @ 提及它的消息，从而在繁忙的频道中保持安静。
• reply_min_interval_secs：对同一个人回复之间的最小间隔，如果即时回复显得过于机械，此设置会很有用。

故障排除

以插件形式运行 Discord（实验性）

以上内容使用的是编译进 ZeroClaw 的内置 Discord 渠道。Discord 也可以作为可安装的 WASM 渠道插件使用，即插件注册表中的 discord 包。该插件运行在插件沙箱中，只能访问你授予的主机。它处于实验阶段，仅处理文本消息。内置渠道仍是默认选项。

为每个 bot token 只能选择内置通道或插件其中一个，二者不能同时使用。Discord 会将每个事件投递给使用该 token 建立的每个连接，因此两者会同时回复每条消息。将 bot 迁移到插件之前，请先删除其 [channels.discord.<alias>] 表。插件不会读取该表。

你需要的内容

• 一个 zeroclaw 二进制文件，其插件宿主可编译 .wasm 组件，即使用 plugins-wasm-cranelift 功能构建的版本（参见构建功能）。在不包含插件宿主的二进制文件上，zeroclaw plugin 命令不存在。zeroclaw plugin install 会在安装任何内容之前，先检查该软件包能否在当前主机上加载。
• 快速入门中创建的机器人：需要其令牌，已开启 Message Content Intent，并已将该机器人邀请到你的服务器。
• 在私有频道中，机器人（或其所属的某个角色）需要在该频道拥有 查看频道、发送消息 和 阅读消息历史 权限。对于机器人无法查看的频道，Discord 不会发送任何事件，插件也不会记录任何日志：机器人会显示为已连接且运行正常，但永远看不到任何消息。channel_ids 中指定了机器人无法查看的频道时，情况同样如此。
• 每个允许与智能体对话的用户的数字用户 ID。请启用 Developer Mode（用户设置 -> Advanced），右键点击该用户，然后点击 Copy User ID。

1. 安装软件包并绑定实例

为该实例选择一个别名（此处为 main），并将软件包绑定到该别名上进行安装：

zeroclaw plugin install discord --channel-alias main --egress declared

该命令从注册表下载 discord，验证它，写入一个 [channels.plugin.main] 绑定，并为该实例创建配置记录。--egress declared 授予软件包声明的主机访问权限：REST API 使用 discord.com，网关 WebSocket 使用 *.discord.gg，因为 Discord 在该域名下分配网关和恢复（resume）主机。若改用 --egress none，则该实例在你授予权限之前没有任何网络访问能力。

如果软件包已安装，请单独绑定别名：

zeroclaw plugin bind discord --channel-alias main --egress declared

绑定通道实例介绍了这两个命令及其输出的报告。

该实例的设置保存在一个键下，该键由包、channel 能力和别名共同派生。对于别名 main，键为 zpi1_WyJkaXNjb3JkIiwiY2hhbm5lbCIsIm1haW4iXQ；运行 zeroclaw plugin info discord 会打印每个已绑定别名的键。

2. 设置 Bot Token

令牌是机密信息。请勿将值写在命令行中，zeroclaw config set 会以不回显的方式提示输入，并以加密形式存储：

zeroclaw config set plugins.entries.zpi1_WyJkaXNjb3JkIiwiY2hhbm5lbCIsIm1haW4iXQ.config.bot_token

其他设置与令牌一起位于 .config. 下，均为可选项：guild_ids 和 channel_ids 用于限定机器人的监听范围（参见限定机器人的监听范围），mention_only 和 listen_to_bots 接受 true 或 false。ZeroClaw 会加密存储所有插件设置，因此 zeroclaw config set 与处理令牌时一样，会逐项提示输入每个设置；若要在命令行中设置非机密的设置项，请传入 --no-interactive。将列表设置为 JSON 文本：

zeroclaw config set --no-interactive plugins.entries.zpi1_WyJkaXNjb3JkIiwiY2hhbm5lbCIsIm1haW4iXQ.config.channel_ids '["123456789012345678"]'

3. 启用它并将其路由到代理

Binding 从不启用插件系统，也从不将实例分配给代理。请启用插件系统：

zeroclaw config set plugins.enabled true

然后将 plugin.main 添加到负责应答的 agent 的 channels 列表中，保留其已有的渠道，并通过同一渠道上的 peer group 允许你的用户接入：

[agents.assistant]
channels = ["plugin.main"]

[peer_groups.discord_plugin]
channel = "plugin.main"
external_peers = ["111111111111111111"]

插件会按数字用户 ID 报告每个发送者，而插件渠道是精确匹配发送者的，因此请列出用户 ID，而不是用户名。请重启 ZeroClaw（zeroclaw service restart）以启动实例。

4. 检查其是否正常运行

• zeroclaw plugin info discord 用于检查该软件包能否在当前主机上加载，输出实例密钥，并列出实例启动前仍需满足的各项要求。
• 启动时，守护进程的通道列表中包含 plugin.main，网关的 /health 快照中也会列出 channel:plugin.main 组件。当插件的轮询失败时，该组件状态为 error；否则，其状态跟随插件自身的健康检查结果，ZeroClaw 大约每 30 秒请求一次该检查。检查涵盖的内容由插件决定。因此，机器人已连接到 Discord 的证明是：已获准的用户发送的消息能够到达智能体，并且智能体的回复出现在 Discord 中。
• 来自已准入用户的消息会被记录为 channel inbound message，并带有 zeroclaw.channel = plugin.main。来自其他任何人的消息会被丢弃，并记录 error_key = plugin_channel_sender_denied。
• 到授权范围之外的主机的连接会被拒绝。被拒绝的 HTTP 请求会记录 error_key = plugin_egress_denied、被拒绝的主机，以及用于授予该权限的 zeroclaw config set 命令。被拒绝的网关连接目前不会记录日志，因此如果修改 egress_hosts 后机器人一直处于离线状态，很可能是丢失了 *.discord.gg。

插件与内置渠道的区别

对话按频道名称分别保存，因此将机器人从 discord.main 迁移到 plugin.main 后会开始新的对话。

另见

• 谁可以与代理通信（对等组）
• 插件（安装和绑定渠道插件）
• Slack
• 通道概述