Mattermost 部署

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

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

在开始设置之前，这里是最让人关心的部分：Hermes 在您的 Mattermost 实例中运行后的表现。

Hermes 的行为表现

上下文	行为
私信 (DMs)	Hermes 对每条消息都作出响应，无需 `@mention`。每个私信会话独立。
公开/私有频道	只有在您 `@mention` 它时，Hermes 才会响应。未被提及的消息，Hermes 会忽略。
线程 (Threads)	如果设置 `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 上创建机器人到发送第一条消息。

第一步：启用机器人账户

在创建机器人之前，必须在您的 Mattermost 服务器上启用机器人账户。

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

信息

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

第二步：创建机器人账户

在 Mattermost 中，点击左上角的 ☰ 菜单 → 集成 → 机器人账户。
点击 添加机器人账户。
填写以下信息：
- 用户名：例如 hermes
- 显示名称：例如 Hermes Agent
- 描述：可选
- 角色：成员 即可
点击 创建机器人账户。
Mattermost 将显示 机器人令牌。请立即复制。

令牌仅显示一次

机器人令牌仅在创建机器人账户时显示一次。如果丢失，您需要从机器人账户设置中重新生成。切勿将令牌公开分享或提交到 Git —— 任何人持有此令牌即可完全控制该机器人。

请将令牌安全存储（例如密码管理器中）。您将在第 5 步中用到。

提示

您也可以使用 个人访问令牌 而非机器人账户。前往 个人资料 → 安全 → 个人访问令牌 → 创建令牌。如果您希望 Hermes 以您自己的用户身份发布消息，而不是作为独立的机器人用户，此方法非常有用。

第三步：将机器人添加到频道

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

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

对于私信，只需打开与机器人的直接消息——它将立即能够回复。

第四步：获取您的 Mattermost 用户 ID

Hermes Agent 使用您的 Mattermost 用户 ID 来控制谁可以与机器人交互。获取方法如下：

点击您的头像（左上角）→ 个人资料。
在个人资料对话框中，您的用户 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 会显示在信息面板中。如果您希望手动设置主频道，将需要此 ID。

第五步：配置 Hermes Agent

选项 A：交互式设置（推荐）

运行引导式设置命令：

hermes gateway setup

在提示时选择 Mattermost，然后按要求粘贴你的服务器 URL、机器人令牌和用户 ID。

选项 B：手动配置

将以下内容添加到你的 ~/.hermes/.env 文件中：

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

# Multiple allowed users (comma-separated)
# MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e

# Optional: reply mode (thread or off, default: off)
# MATTERMOST_REPLY_MODE=thread

# Optional: respond without @mention (default: true = require mention)
# MATTERMOST_REQUIRE_MENTION=false

# Optional: channels where bot responds without @mention (comma-separated channel IDs)
# 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 列表，机器人在这些频道中无需 `@mention` 也能响应，即使 `require_mention` 为 true 时也适用。

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

当机器人被 @提及 时，提及部分会在处理前自动从消息中移除。

故障排除

机器人不响应消息

原因：机器人未加入该频道，或 MATTERMOST_ALLOWED_USERS 中未包含你的用户 ID。

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

403 禁止错误

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

修复：检查 .env 文件中的 MATTERMOST_TOKEN 是否正确。确保机器人账户未被停用。确认机器人已添加到频道中。如果使用个人访问令牌，请确保你的账户具有所需权限。

WebSocket 断开 / 重连循环

原因：网络不稳定、Mattermost 服务器重启，或 WebSocket 连接存在防火墙/代理问题。

修复：适配器会自动以指数退避方式重连（2 秒 → 60 秒）。检查服务器的 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;
}

启动时“认证失败”

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

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

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

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

机器人离线

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

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

“用户不允许” / 机器人忽略你

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

修复：将你的用户 ID 添加到 ~/.hermes/.env 中的 MATTERMOST_ALLOWED_USERS，然后重启网关。注意：用户 ID 是一个 26 位的字母数字字符串，不是你的 @用户名。

安全性

注意

始终设置 MATTERMOST_ALLOWED_USERS 以限制谁可以与机器人交互。如果没有设置，网关默认会拒绝所有用户，这是一种安全措施。仅添加你信任的人员的用户 ID——授权用户拥有对代理功能的完全访问权限，包括工具使用和系统访问。

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

注意事项

支持自托管：可与任何自托管的 Mattermost 实例配合使用。无需 Mattermost Cloud 账户或订阅。
无额外依赖：该适配器使用 aiohttp 进行 HTTP 和 WebSocket 操作，而 aiohttp 已包含在 Hermes Agent 中。
兼容团队版：支持 Mattermost 团队版（免费）和企业版。

Hermes 的行为表现​

Mattermost 中的会话模型​

第一步：启用机器人账户​

第二步：创建机器人账户​

第三步：将机器人添加到频道​

第四步：获取您的 Mattermost 用户 ID​

第五步：配置 Hermes Agent​

选项 A：交互式设置（推荐）​

选项 B：手动配置​

启动网关​

主频道​

使用斜杠命令​

手动配置​

回复模式​

提及行为​

故障排除​

机器人不响应消息​

403 禁止错误​

WebSocket 断开 / 重连循环​

启动时“认证失败”​

机器人离线​

“用户不允许” / 机器人忽略你​

安全性​

注意事项​