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：对同一个人回复之间的最小间隔，如果即时回复显得过于机械，此设置会很有用。

故障排除

另见

• 谁可以与代理通信（对等组）
• Slack
• 通道概述