Mattermost 配置

Hermes Agent 以机器人身份集成到 Mattermost，让你可以通过私信或团队频道与 AI 助手对话。Mattermost 是一款自托管的开源 Slack 替代品——你在自己的基础设施上运行它，完全掌控数据。机器人通过 Mattermost REST API（v4）和 WebSocket 连接以获取实时事件，将消息通过 Hermes Agent 管道（包括工具调用、记忆和推理）处理后实时响应。支持文本、文件附件、图片和斜杠命令。

无需额外的 Mattermost 库——适配器使用 aiohttp，该库已是 Hermes 的依赖项。

在开始配置之前，先了解 Hermes 接入后的行为。

Hermes 的行为

场景	行为
私信	Hermes 回复每条消息，无需 @提及。每个私信会话独立。
公开/私有频道	Hermes 仅在被 @提及 时响应。没有提及时忽略消息。
话题	如果设置 MATTERMOST_REPLY_MODE=thread，Hermes 会在你的消息下以话题形式回复。话题上下文与父频道隔离。
多用户共享频道	默认情况下，Hermes 按用户隔离频道内的会话历史。同一频道中的两个用户不共享对话记录，除非你明确禁用该功能。

提示

如果你希望 Hermes 以嵌套话题（在原始消息下方）的形式回复，请设置 MATTERMOST_REPLY_MODE=thread。默认值为 off，即在频道中发送普通消息。

Mattermost 中的会话模型

默认情况下：

• 每个私信拥有独立会话
• 每个话题拥有独立的会话命名空间
• 共享频道中的每个用户在该频道内拥有独立会话

通过 config.yaml 控制：

group_sessions_per_user: true

仅当你明确希望整个频道共享同一对话时才设置为 false：

group_sessions_per_user: false

共享会话在协作频道中很有用，但也意味着：

• 用户共享上下文增长和 Token 消耗
• 一个人执行工具密集型任务可能会撑大所有人的上下文
• 一个人正在进行的任务可能会打断同一频道中另一个人的后续操作

本指南将引导你完成完整的配置流程——从在 Mattermost 上创建机器人到发送第一条消息。

步骤 1：启用机器人账户

在创建机器人账户之前，必须先在 Mattermost 服务器上启用此功能。

1. 以系统管理员身份登录 Mattermost。
2. 前往 系统控制台 → 集成 → 机器人账户。
3. 将启用机器人账户创建设置为 true。
4. 点击保存。

信息

如果你没有系统管理员权限，请联系 Mattermost 管理员启用机器人账户并为你创建一个。

步骤 2：创建机器人账户

1. 在 Mattermost 中，点击 ☰ 菜单（左上角）→ 集成 → 机器人账户。
2. 点击添加机器人账户。
3. 填写详细信息：
   • 用户名：例如 hermes
   • 显示名称：例如 Hermes Agent
   • 描述：可选
   • 角色：成员 即可
4. 点击创建机器人账户。
5. Mattermost 会显示机器人 Token。立即复制。

Token 仅显示一次

机器人 Token 只在创建机器人账户时显示一次。如果丢失，需要在机器人账户设置中重新生成。切勿公开分享你的 Token 或将其提交到 Git——任何持有该 Token 的人都能完全控制机器人。

将 Token 保存到安全位置（例如密码管理器）。步骤 5 中需要用到它。

提示

你也可以使用个人访问 Token 代替机器人账户。前往 个人资料 → 安全 → 个人访问 Token → 创建 Token。如果你希望 Hermes 以你自己的用户名发帖而非独立的机器人用户，这个方式很有用。

步骤 3：将机器人添加到频道

机器人需要成为其需要响应的任何频道的成员：

1. 打开你希望添加机器人的频道。
2. 点击频道名称 → 添加成员。
3. 搜索机器人用户名（例如 hermes）并添加。

对于私信，只需与机器人开启私聊——它可以立即响应。

步骤 4：获取你的 Mattermost 用户 ID

Hermes Agent 使用你的 Mattermost 用户 ID 来控制谁可以与机器人交互。查找方式：

1. 点击头像（左上角）→ 个人资料。
2. 用户 ID 显示在个人资料对话框中——点击即可复制。

你的用户 ID 是一个 26 位字母数字字符串，例如 3uo8dkh1p7g1mfk49ear5fzs5c。

注意

你的用户 ID 不是用户名。用户名是 @ 后面的部分（例如 @alice）。用户 ID 是 Mattermost 内部使用的长字母数字标识符。

替代方式：也可以通过 API 获取用户 ID：

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-mattermost-server/api/v4/users/me | jq .id

提示

获取频道 ID：点击频道名称 → 查看信息。信息面板中会显示频道 ID。如果你想手动设置主频道，需要用到它。

步骤 5：配置 Hermes Agent

方式 A：交互式设置（推荐）

运行引导式设置命令：

hermes gateway setup

在提示中选择 Mattermost，然后按要求粘贴服务器 URL、机器人 Token 和用户 ID。

方式 B：手动配置

在 ~/.hermes/.env 文件中添加以下内容：

# 必需
MATTERMOST_URL=https://mm.example.com
MATTERMOST_TOKEN=***
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c

# 多个允许用户（逗号分隔）
# MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e

# 可选：回复模式（thread 或 off，默认：off）
# MATTERMOST_REPLY_MODE=thread

# 可选：无需 @提及 即可响应（默认：true = 需要提及）
# MATTERMOST_REQUIRE_MENTION=false

# 可选：无需 @提及 即可响应的频道（逗号分隔的频道 ID）
# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2

~/.hermes/config.yaml 中的可选行为设置：

group_sessions_per_user: true

• group_sessions_per_user: true 在共享频道和话题中保持每个参与者的上下文隔离

启动网关

配置完成后，启动 Mattermost 网关：

hermes gateway

机器人应在几秒内连接到你的 Mattermost 服务器。向机器人发送消息——无论是私信还是已添加机器人的频道——进行测试。

提示

你可以在后台运行 hermes gateway 或将其作为 systemd 服务长期运行。详见部署文档。

主频道

你可以指定一个"主频道"，机器人会主动向该频道发送消息（例如定时任务输出、提醒和通知）。有两种设置方式：

使用斜杠命令

在机器人所在的任意 Mattermost 频道中输入 /sethome，该频道即成为主频道。

手动配置

在 ~/.hermes/.env 中添加：

MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn

将 ID 替换为实际频道 ID（点击频道名称 → 查看信息 → 复制 ID）。

回复模式

MATTERMOST_REPLY_MODE 设置控制 Hermes 如何发送响应：

模式	行为
off（默认）	Hermes 在频道中以普通消息发帖，类似普通用户。
thread	Hermes 在你的原始消息下以话题形式回复。当来回交流较多时，保持频道整洁。

在 ~/.hermes/.env 中设置：

MATTERMOST_REPLY_MODE=thread

提及行为

默认情况下，机器人只在被 @提及 时才响应频道消息。可以更改此行为：

变量	默认值	描述
MATTERMOST_REQUIRE_MENTION	true	设置为 false 可响应频道中的所有消息（私信始终有效）。
MATTERMOST_FREE_RESPONSE_CHANNELS	（无）	机器人无需 @提及 即可响应的频道 ID（逗号分隔），即使 require_mention 为 true 也适用。

在 Mattermost 中获取频道 ID：打开频道，点击频道名称标题，在 URL 或频道详情中查找 ID。

当机器人被 @提及 时，提及内容会在处理消息之前自动去除。

故障排除

机器人不响应消息

原因：机器人不是该频道的成员，或 MATTERMOST_ALLOWED_USERS 中未包含你的用户 ID。

解决方法：将机器人添加到频道（频道名称 → 添加成员 → 搜索机器人）。验证你的用户 ID 是否在 MATTERMOST_ALLOWED_USERS 中。重启网关。

403 禁止访问错误

原因：机器人 Token 无效，或机器人没有权限在该频道发帖。

解决方法：检查 .env 文件中的 MATTERMOST_TOKEN 是否正确。确保机器人账户未被停用。验证机器人是否已添加到频道。如果使用个人访问 Token，确保你的账户有相应权限。

WebSocket 断开 / 重连循环

原因：网络不稳定、Mattermost 服务器重启，或防火墙/代理对 WebSocket 连接的限制。

解决方法：适配器会使用指数退避（2s → 60s）自动重连。检查服务器的 WebSocket 配置——反向代理（nginx、Apache）需要配置 WebSocket 升级头部。验证没有防火墙阻止 Mattermost 服务器上的 WebSocket 连接。

对于 nginx，确保配置中包含：

location /api/v4/websocket {
    proxy_pass http://mattermost-backend;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 600s;
}

启动时出现 "Failed to authenticate"

原因：Token 或服务器 URL 不正确。

解决方法：验证 MATTERMOST_URL 指向你的 Mattermost 服务器（包含 https://，无尾部斜杠）。检查 MATTERMOST_TOKEN 是否有效——用 curl 测试：

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-server/api/v4/users/me

如果返回机器人的用户信息，Token 有效。如果返回错误，请重新生成 Token。

机器人离线

原因：Hermes 网关未运行，或连接失败。

解决方法：检查 hermes gateway 是否正在运行。查看终端输出中的错误信息。常见问题：URL 错误、Token 过期、Mattermost 服务器无法访问。

"User not allowed" / 机器人忽略你

原因：你的用户 ID 不在 MATTERMOST_ALLOWED_USERS 中。

解决方法：将你的用户 ID 添加到 ~/.hermes/.env 的 MATTERMOST_ALLOWED_USERS 中，然后重启网关。记住：用户 ID 是一个 26 位字母数字字符串，不是你的 @用户名。

按频道设置提示词

为特定 Mattermost 频道分配临时系统提示词。提示词在每次对话轮次中在运行时注入——永远不会持久化到对话记录中——因此更改会立即生效。

mattermost:
  channel_prompts:
    "channel_id_abc123": |
      You are a research assistant. Focus on academic sources,
      citations, and concise synthesis.
    "channel_id_def456": |
      Code review mode. Be precise about edge cases and
      performance implications.

键为 Mattermost 频道 ID（在频道 URL 或通过 API 获取）。匹配频道中的所有消息都会注入该提示词作为临时系统指令。

安全

注意

始终设置 MATTERMOST_ALLOWED_USERS 来限制谁可以与机器人交互。没有此设置，网关默认会拒绝所有用户作为安全措施。只添加你信任的人的用户 ID——授权用户可以完全访问 Agent 的功能，包括工具调用和系统访问权限。

有关保护 Hermes Agent 部署安全的更多信息，请参阅安全指南。

说明

• 自托管友好：适用于任何自托管的 Mattermost 实例，无需 Mattermost Cloud 账户或订阅。
• 无需额外依赖：适配器使用 aiohttp 进行 HTTP 和 WebSocket 通信，已包含在 Hermes Agent 中。
• Team Edition 兼容：同时适用于 Mattermost Team Edition（免费版）和 Enterprise Edition。