Slack

将你的 ZeroClaw 代理作为 Slack 机器人运行。本指南将逐步引导你完成操作。完成后，你的工作区中将拥有一个机器人，当有人向它发送消息或 @ 提及它时，它会做出回应。

谁可以与代理通信

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

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

在何处设置：

快速开始

Slack 需要两个令牌：一个 bot token（机器人用来发言的令牌）和一个 app token（让机器人无需你托管公开 URL 即可连接）。两者都来自同一个应用页面。

1. 创建 Slack 应用

1. 前往 api.slack.com/apps，然后点击 Create New App -> From scratch。
2. 命名应用，选择工作区，然后点击 Create App。

2. 添加机器人所需的权限

1. 在左侧边栏中，打开 OAuth & Permissions。
2. 在 Scopes -> Bot Token Scopes 下，添加：app_mentions:read、channels:history、chat:write 和 channels:read。（如果你需要私信功能，也请添加 im:history 和 im:write。）

3. 开启 Socket Mode 并获取应用令牌

1. 在左侧边栏中，打开 Socket Mode 并将其切换为 on。
2. Slack 会提示你创建一个 app-level token。为其命名，授予 connections:write 权限范围，然后点击 Generate。
3. 复制以 xapp- 开头的令牌。这就是你的 app_token。

套接字模式（Socket Mode）让机器人与 Slack 保持一个出站连接，因此你无需公共 webhook URL 或任何端口转发。这是最简单的方式。

4. 安装应用并获取机器人令牌

1. 在侧边栏中打开 Install App，点击 Install to Workspace，然后点击 Allow。
2. 回到 OAuth & Permissions 页面，复制以 xoxb- 开头的 Bot User OAuth Token。这就是你的 bot_token。

5. 将两个令牌信息告知 ZeroClaw

这两个令牌都是机密信息，因此请通过对其进行加密的接口进行设置：

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

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

用相同的方式设置 app_token（即第 3 步中的 xapp- 令牌）。

环境变量替代方案。 两个令牌都可以从守护进程的环境变量中提供，而非配置文件：bot_token 先从 ZEROCLAW_SLACK_BOT_TOKEN 解析，再从 SLACK_BOT_TOKEN 解析；app_token 先从 ZEROCLAW_SLACK_APP_TOKEN 解析，再从 SLACK_APP_TOKEN 解析。配置文件中的值优先于环境变量。这样你就可以完全从 config.toml 中省略 bot_token（例如用于注入环境变量的密钥管理器），而不会导致配置加载失败。

6. 邀请机器人并测试

在 Slack 中，进入一个频道并输入 /invite @YourBotName。然后发送一条消息或 @ 提及该机器人。启动 ZeroClaw（zeroclaw service restart 或 zeroclaw daemon），它应该会回复。如果没有，请参阅故障排除。

配置

完整字段列表派生自实时架构。对于基本的 Socket Mode 机器人，您只需设置 bot_token 和 app_token。

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

export ZEROCLAW_channels__slack__<alias>__app_token=

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

export ZEROCLAW_channels__slack__<alias>__approval_timeout_secs=

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

export ZEROCLAW_channels__slack__<alias>__bot_token=

zeroclaw config set channels.slack.<alias>.cancel_reaction <value>

export ZEROCLAW_channels__slack__<alias>__cancel_reaction=

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

export ZEROCLAW_channels__slack__<alias>__channel_ids=

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

export ZEROCLAW_channels__slack__<alias>__draft_update_interval_ms=

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

export ZEROCLAW_channels__slack__<alias>__excluded_tools=

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

export ZEROCLAW_channels__slack__<alias>__interrupt_on_new_message=

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

export ZEROCLAW_channels__slack__<alias>__mention_only=

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

export ZEROCLAW_channels__slack__<alias>__proxy_url=

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

export ZEROCLAW_channels__slack__<alias>__reply_min_interval_secs=

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

export ZEROCLAW_channels__slack__<alias>__reply_queue_depth_max=

zeroclaw config set channels.slack.<alias>.stream_drafts <value>

export ZEROCLAW_channels__slack__<alias>__stream_drafts=

zeroclaw config set channels.slack.<alias>.strict_mention_in_thread <value>

export ZEROCLAW_channels__slack__<alias>__strict_mention_in_thread=

zeroclaw config set channels.slack.<alias>.thread_context_max_messages <value>

export ZEROCLAW_channels__slack__<alias>__thread_context_max_messages=

zeroclaw config set channels.slack.<alias>.thread_replies <value>

export ZEROCLAW_channels__slack__<alias>__thread_replies=

zeroclaw config set channels.slack.<alias>.use_markdown_blocks <value>

export ZEROCLAW_channels__slack__<alias>__use_markdown_blocks=

Socket Mode 与 HTTP 对比

设置 app_token 后，机器人使用 Socket Mode：它会主动连接到 Slack，因此无需公网 URL。这是推荐的设置方式，也是上面快速入门所采用的方式。如果没有 app_token，Slack 必须通过 HTTP 访问你的机器人，这意味着需要托管一个公开的事件端点，需要更多的设置工作，也有更多需要保护的内容。

线程与上下文

当 Slack 对话发生在某个话题串（thread）中时，该话题串本身就是一个独立的对话。ZeroClaw 会为每个话题串派生出不同的会话键（session key），因此每个话题串都拥有独立的上下文窗口和历史记录：一个话题串中的消息绝不会渗入另一个话题串，智能体也看不到同级话题串中较早的对话轮次。对于 Slack，此行为由 thread_replies 控制：当其开启时，顶层消息会开启一个话题串，且每个话题串都是一个独立的对话；当其关闭时，回复会发布在频道根部，历史记录将按发送者和目标进行键控，而非按话题串。

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

为任意 surface 设置线程行为：

zeroclaw config set channels.slack.<alias>.thread_replies true     线程回复开启
zeroclaw config set channels.slack.<alias>.thread_replies false    # 频道根目录的回复

strict_mention_in_thread 会进一步收紧此限制：当设为 true 时，机器人仅在线程内有消息 @ 提及它时才会回复，而不是回复它所参与线程中的每一条消息。

在现有线程中 ZeroClaw 处理的第一条消息时，它会获取之前的回复，并在前面添加一个有上限的 [Thread context] 块，以便代理能够结合之前的讨论作答。thread_context_max_messages 控制在获取窗口内可用的最新历史消息中包含多少条，同时保持时间顺序。默认值为 0，最大值为 50，而 0 会禁用此自动填充。设置一个明确的非零值即可选择启用该功能。

一次补全最多进行三次 conversations.replies 尝试，包括 HTTP 429 响应后的重试。只要请求预算尚有余量，ZeroClaw 就会遵循 Slack 的 Retry-After 值，然后再进行重试。如果较长的线程仍有下一页，ZeroClaw 会使用受限的部分上下文，添加省略标记，并将该线程记录为已补全，以便后续回复不会重新开始扫描。Slack API 失败不会丢弃当前消息；系统会跳过补全并释放预留，以便下一个符合条件的回复可以重试。

提及和格式

• mention_only：当设为 true 时，机器人仅回复 @ 提及它的消息，从而在繁忙的频道中保持安静。
• use_markdown_blocks：使用 Slack Block Kit 格式渲染回复，以实现更丰富的布局。关闭后则使用纯文本。

流式传输

Slack 通过 stream_drafts 布尔值流式传输回复：

• false（默认）：整个回复在 agent 完成后作为一条消息发送。
• true：机器人会立即发布一条占位消息，并在答案以流式方式传入时就地编辑该消息。draft_update_interval_ms 用于控制编辑的频率；如果 Slack 对其进行限流，请调高该值。

将其放置在任何表面上：

zeroclaw config set channels.slack.<alias>.stream_drafts <value>

draft_update_interval_ms 控制流式草稿的编辑频率（如果 Slack 对编辑进行限流，可调高该值），而 cancel_reaction 设置一个表情符号，用户可以通过它来取消正在处理中的回复。

故障排除

另见

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