Mattermost

REST v4 轮询和 WebSocket 客户端。默认情况下，机器人每 3 秒轮询一次频道以获取新帖子；设置 listen_mode = "websocket" 可通过持久 WebSocket 连接实现近实时事件推送。无论采用哪种监听模式，回复帖子始终通过 POST /api/v4/posts 发送。

谁可以与代理通信

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

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

在何处设置：

如需将特定用户加入允许列表，请从 System Console → User Management 中复制其用户 ID。Mattermost 匹配的是用户 UUID，而非用户名，并且不会在接收消息时解析用户名。

快速开始

通过下面的某个界面配置 Mattermost 频道（url 加上 bot_token 密钥，参见身份验证）。仅此一项即可为你提供：

1. 自动发现机器人在其所属的每个团队中可读取的所有频道。
2. DM 和群组 DM 频道会与团队频道一起自动发现并轮询。
3. 新私信（在机器人启动后创建）将在下一次 60 秒发现刷新时被识别。
4. mention_only 在私信和群组私信频道中被忽略（因此一对一对话无需 @ 提及机器人）。

如需限制此机器人，可使用 channel_ids、team_ids 或 discover_dms 进行范围缩小。

配置

bot_token 和 password 是机密信息：

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

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

字段参考

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

export ZEROCLAW_channels__mattermost__<alias>__approval_timeout_secs=

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

export ZEROCLAW_channels__mattermost__<alias>__bot_token=

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

export ZEROCLAW_channels__mattermost__<alias>__channel_ids=

zeroclaw config set channels.mattermost.<alias>.discover_dms <value>

export ZEROCLAW_channels__mattermost__<alias>__discover_dms=

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

export ZEROCLAW_channels__mattermost__<alias>__excluded_tools=

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

export ZEROCLAW_channels__mattermost__<alias>__interrupt_on_new_message=

zeroclaw config set channels.mattermost.<alias>.listen_mode <value>

export ZEROCLAW_channels__mattermost__<alias>__listen_mode=

zeroclaw config set channels.mattermost.<alias>.login_id <value>

export ZEROCLAW_channels__mattermost__<alias>__login_id=

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

export ZEROCLAW_channels__mattermost__<alias>__mention_only=

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

export ZEROCLAW_channels__mattermost__<alias>__password=

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

export ZEROCLAW_channels__mattermost__<alias>__proxy_url=

zeroclaw config set channels.mattermost.<alias>.purpose_as_instructions <value>

export ZEROCLAW_channels__mattermost__<alias>__purpose_as_instructions=

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

export ZEROCLAW_channels__mattermost__<alias>__reply_min_interval_secs=

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

export ZEROCLAW_channels__mattermost__<alias>__reply_queue_depth_max=

zeroclaw config set channels.mattermost.<alias>.team_ids <value>

export ZEROCLAW_channels__mattermost__<alias>__team_ids=

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

export ZEROCLAW_channels__mattermost__<alias>__thread_replies=

zeroclaw config set channels.mattermost.<alias>.url <value>

export ZEROCLAW_channels__mattermost__<alias>__url=

频道发现

有两种作用域模式。

1. 自动发现（当 channel_ids 为空或为 ["*"] 时）。在启动时以及之后每隔 60 秒，机器人会调用 GET /api/v4/users/me/channels，按 team_ids（公共/私有频道）和 discover_dms（私信/群组私信）过滤结果，并轮询每个保留下来的频道。运行期间新建的私信会在下一次刷新时出现。
2. 显式模式（当 channel_ids 是一个非空的 ID 列表，且不为 * 时）。启动时，机器人会为每个条目调用 GET /api/v4/channels/{id} 以获取其 type（以便识别哪些是用于 mention_only 绕过的私信），然后持续轮询这些指定的频道。不会进行周期性的重新发现。

在两种模式下，每个频道都有自己的 since 游标：机器人会跟踪每个频道已处理的最大 create_at，并在下一次 GET /api/v4/channels/{id}/posts 调用中将其作为 since=<ms> 传入。游标不会在频道之间泄漏，因此低速频道不会抑制繁忙频道中的帖子。

WebSocket 模式

将 listen_mode = "websocket" 设置为从 REST 轮询切换到持久化 WebSocket 连接（wss://<server>/api/v4/websocket）。WebSocket 模式：

• 以近实时方式推送新帖子（无需 3 秒轮询延迟）。
• 降低 Mattermost 服务器的 HTTP 负载（一个连接，而非每 3 秒进行 N 次轮询）。
• 将失败的会话返回给共享通道管理器，由其使用配置的 reliability.channel_initial_backoff_secs 和 reliability.channel_max_backoff_secs 值以有界指数退避方式重新连接。
• 需要 Mattermost v4.0+（/api/v4/websocket 端点）。

频道发现、mention_only、thread_replies、音频转录和对等组授权在两种模式下的工作方式完全相同。

权衡取舍：

• WebSocket 模式必须维持一个持久的 TCP+TLS 连接。
• 在重连窗口期间，发布到频道的消息可能会被漏掉，因为此监听器尚未请求 Mattermost 连接恢复/重放。轮询会通过 since= 游标补上遗漏。
• 轮询模式对短暂的网络中断更具弹性,但代价是持续的 HTTP 流量。

如需回滚，请设置 listen_mode = "polling"（或删除该字段；polling 为默认值）。

通过聊天进行工具审批 (approval_timeout_secs)

当工具需要审批时（它位于 always_ask 中，或风险配置未自动批准该工具），智能体会将审批请求发送到消息来源所在的频道，并等待回应。根据 listen_mode 的设置不同，可用的应答方式也有两种。

请回复 token。 此方法适用于所有监听模式：

需要批准 [a1b2c3]
工具：shell
参数：command: pwd

回复："a1b2c3 yes"、"a1b2c3 no" 或 "a1b2c3 always"

a1b2c3 yes
a1b2c3 no
a1b2c3 always

与待处理令牌匹配的回复会被视为决策并被消费，不会传递给模型。

点击表情回应。 此功能需要 listen_mode = "websocket"。机器人会在其自身的提示消息上添加 ✅ 和 ❌；点击任一表情即可作出回应。表情回应以 reaction_added WebSocket 事件的形式送达机器人，而轮询监听器只读取消息，无法收到这些事件，因此在 listen_mode = "polling" 下不会预置任何表情：安全提示上一个静默无效的按钮，比没有按钮更糟。如果希望使用一键审批，请设置 listen_mode = "websocket"（参见 WebSocket 模式）。

always 故意不带 emoji。它授予的是会话级允许列表条目，而不是只允许单次调用。如果误点到 ✅ 旁边，就会过于轻易地扩大会话权限，因此升级为 always 必须是一个需要手动输入确认的明确决定。

Mattermost 在此不提供交互式消息_按钮_。这些按钮会向集成 URL 发送请求，而这需要一个入站 HTTP 端点，机器人无法从轮询或 WebSocket 客户端暴露此类端点；反应（reactions）是唯一可以通过机器人已保持的连接实现的一键操作方式。

谁可以回答，以及在哪里回答。 令牌只是一个关联标识，而不是密码：它会以明文形式进入频道，因此每个成员都能看到它。因此必须同时满足两个条件。回答的用户必须在该别名的对等组中，这与决定代理会执行哪些用户消息的权限来源相同。并且，回答必须到达发布提示的那个频道。一个机器人服务多个频道，因此即使是经过授权的用户，把令牌带到另一个房间中的回答也不算有效。绑定以频道为单位，而不是以线程为单位，因此在频道中直接回复、而不是在提示所在的线程内回复，是可以的。未通过任一检查的回复或点击会以 WARN 级别记录日志并被忽略，提示保持打开状态，以便经过授权的操作员仍可在正确的位置作出回答。

频道中的所有人都可以查看工具参数。 提示词包含工具名称及其参数摘要。请将审批请求路由到您可以放心让其成员查看这些内容的频道。

approval_timeout_secs 用于限定等待时长。默认值为 300 秒，设为 0 时会立即拒绝，而不是关闭审批，因此设为零的效果是拒绝所有受控工具，而不是无限等待。超时后请求会被拒绝，令牌随之作废，因此之后迟到的回复或点击无法批准已经无人等待的调用。超时或提示无法送达都会被记录为运行时自行拒绝，而不是人工拒绝。

决定已定：移除反应不会撤回答案，并且第一个有效答案会对两条路径同时结束该提示。

如果机器人无法添加表情反应（通常是权限问题），它会以 WARN 级别记录 failed to seed Mattermost approval reaction，但提示仍可通过回复正常工作。

频道用途作为指令（purpose_as_instructions）

默认关闭。启用后，每个房间的 Mattermost 频道用途会作为频道提供的上下文注入到智能体的系统提示词中，这样无需为每个房间单独设置配置条目，一个房间就能让智能体专注于特定用途：

[channels.mattermost.default]
purpose_as_instructions = true

为频道设置用途，描述该房间的用途，例如“用于 AUR 仓库的 Arch Linux 软件包维护”。智能体会将其视为关于该房间的关注重点、语气以及应调用哪些技能的权威信息。

它不具有凌驾于智能体规则之上的权威性。该注入文本被标记为渠道提供的内容，并明确声明无权授予能力、放宽限制或覆盖运行规则；一旦与规则冲突，以规则为准。它无法启用工具、扩大对等组范围或更改自主级别。

这项设置开启后会授予什么权限，以及授予给谁

这项设置是否开启属于信任决策，有必要直截了当地说明它的实际影响，而不是让用户从上面的警告中自行推断。

该用途由 Mattermost 的 manage_public_channel_properties / manage_private_channel_properties 权限控制。在默认权限方案下，这两项权限授予每位频道成员。这一范围通常比有权管理此配置的人员更广，也不一定与别名的 peer_groups 有交集：一位不是已授权 ZeroClaw 对等方、因而无法让智能体直接回应其消息的成员，仍然可以编辑房间的用途。

该文本会进入系统提示。围绕它的框架说明这段文本由渠道提供，是在描述环境而非向智能体下达指令，并且从不覆盖其规则。但框架只是强先验，而非边界。读起来像指令的文本仍可能影响智能体在该环境中的行为，无论如何转义都无法改变这一点；它是自然语言，模型也会将其当作自然语言来理解。

因此，本功能所做的决定，明确说明如下： 为别名启用 purpose_as_instructions，会使所有有权编辑这些房间用途的人都能在智能体已有权限范围内引导该智能体的行为。仅在这组人员被信任可以使用智能体已配置能力的情况下启用它。若并非如此，请保持关闭（关闭为默认值），或在你的权限方案中限制 manage_*_channel_properties，使其仅授予应当拥有该权限的人员。

目的本身仍无法做到的，是_扩大_这些能力。它不能启用工具、添加对等节点、更改自主级别，或批准自己的工具调用：这些由配置和审批路径决定，而二者都不读取提示文本。

从结构上看，该文本是受限的。注入前，它会被压平为单行，并移除尖括号和控制字符，因此它无法关闭自身所在的段落、开启另一个段落，也无法伪造看起来属于操作员提示词其他部分的 Markdown 标题。它还被限制在 500 个字符以内，高于 Mattermost 对该字段自身的 250 字符限制（频道标题允许 1024 个字符）。这样既不会截断任何合理用途，又能防止被入侵的服务器粘贴完整的提示词。

编辑后的用途会在下一条消息时生效，生效延迟取决于 listen_mode：

清空频道的用途会停止注入，而不是保留之前的值。没有用途的房间不会贡献任何内容。

要回滚，请将 purpose_as_instructions = false（或删除该字段；默认即为关闭）。无需清理任何通道状态，因为未选择启用的别名不会缓存任何内容。

私信

Mattermost 按 type 对频道进行分类：

G 和 D 在 ZeroClaw 中被同等对待：两者都不携带 team_id，都受 discover_dms 控制，且都隐式绕过 mention_only（私密会话不存在需要过滤的环境噪声）。

DM 发送者的授权仍通过频道的对等组解析器处理，与其他任何频道相同。discover_dms 只是一个调节开关，而非安全边界；对等组决定谁有权向该智能体发送消息。

线程

1. 入站消息位于现有话题内（已设置 root_id）→ 无论 thread_replies 如何设置，回复始终发送到该话题中。
2. 入站帖子为顶层帖子且 thread_replies = true（默认）→ 回复将开启一个以该入站帖子为根的话题串。
3. 入站帖子为顶层消息且 thread_replies = false → 回复将发布到频道根级别。

上下文管理

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

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

为任意 surface 设置线程行为：

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

身份验证

两条路径：

1. Bot 令牌（推荐）。在 System Console → Integrations → Bot Accounts 中创建，复制访问令牌，并将其存储在 bot_token 中。令牌在密码轮换后依然有效，且更易于吊销。
2. 登录流程。设置 login_id（邮箱或用户名）和 password。机器人启动时会调用 POST /api/v4/users/login，并将返回的会话令牌缓存在内存中。不会持久化到磁盘。

同时设置时，bot_token 优先。

语音消息

当配置了 [transcription] 且入站帖子包含音频附件（MIME 类型为 audio/* 或扩展名为 ogg/mp3/m4a/wav/opus/flac）且无文本正文时，系统将通过 GET /api/v4/files/{file_id} 下载该音频，并路由至已配置的转录提供程序。转录结果以 [Voice] 为前缀，并作为消息内容。大于 25 MB 或超过 transcription.max_duration_secs 的附件将被丢弃并记录 WARN 日志。

设置

1. 在 Mattermost 中：系统控制台 → 集成 → 机器人账号 → 添加机器人账号。设置用户名（例如 zeroclaw），并启用你需要的权限范围。
2. 复制访问令牌。将其存储在 ZeroClaw 密钥后端中。
3. 邀请机器人加入你希望它在其中运行的任意团队。对于私信自动发现功能，无需额外邀请：任何用户都可以私信该机器人。
4. 通过网关、zerocode 或 zeroclaw config set 创建引用该令牌的 mattermost.<alias> 频道。
5. 通过 channels = ["mattermost.<alias>"] 将该通道绑定到 [agents.<alias>] 中的代理。

操作说明

1. 轮询频率为每个频道 3 秒。发现 N 个频道意味着每 3 秒对 Mattermost 服务器发起 N 次 HTTP 调用。自托管默认配置可轻松应对；如果你使用的是速率限制较严格的共享云租户，建议通过 channel_ids 或 team_ids 缩小范围。
2. Bot 身份通过 GET /api/v4/users/me 获取一次，并在进程生命周期内缓存。用户名变更需要重启。
3. 密码登录流程的会话令牌仅保存在内存中。重启后会重新登录。

另见

• 通道概述
• 对等组
• 参考：配置架构