hermes教程-Mattermost 配置

Mattermost 配置

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

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

在配置之前，先介绍大多数人最关心的部分：Hermes 进入你的 Mattermost 实例后的行为表现。

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. 以**系统管理员 (System Admin)**身份登录 Mattermost。
2. 前往系统控制台 (System Console) → 集成 (Integrations) → 机器人账户 (Bot Accounts)。
3. 将**启用机器人账户创建 (Enable Bot Account Creation)**设为 true。
4. 点击保存 (Save)。

信息

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

步骤 2：创建机器人账户

1. 在 Mattermost 中，点击左上角的 ☰ 菜单 → 集成 (Integrations) → 机器人账户 (Bot Accounts)。
2. 点击添加机器人账户 (Add Bot Account)。
3. 填写详细信息：
   • 用户名 (Username)：例如 hermes
   • 显示名称 (Display Name)：例如 Hermes Agent
   • 描述 (Description)：可选
   • 角色 (Role)：Member 即可
4. 点击创建机器人账户 (Create Bot Account)。
5. Mattermost 会显示机器人令牌 (bot token)。请立即复制。

:::warning[令牌仅显示一次] 机器人令牌仅在创建机器人账户时显示一次。如果丢失，你需要在机器人账户设置中重新生成。切勿公开分享你的令牌或将其提交到 Git——任何获得此令牌的人都将完全控制该机器人。 :::

将令牌妥善保存（例如密码管理器）。在步骤 5 中你会用到它。

提示

你也可以使用个人访问令牌 (personal access token)代替机器人账户。前往个人资料 (Profile) → 安全 (Security) → 个人访问令牌 (Personal Access Tokens) → 创建令牌 (Create Token)。如果你希望 Hermes 以你自己的用户身份而非独立的机器人用户发帖，这会很有用。

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

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

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

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

步骤 4：查找你的 Mattermost 用户 ID

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

1. 点击左上角的头像 (avatar) → 个人资料 (Profile)。
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 (Channel ID)：点击频道名称 → 查看信息 (View Info)。频道 ID 会显示在信息面板中。如果你想手动设置主频道，会需要这个。

步骤 5：配置 Hermes Agent

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

运行引导式配置命令：

hermes gateway setup

在提示时选择 Mattermost，然后按提示粘贴你的服务器 URL、机器人令牌和用户 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
## 可选：无需 @mention 即可响应（默认：true = 需要提及）
## MATTERMOST_REQUIRE_MENTION=false
## 可选：机器人无需 @mention 即可响应的频道（逗号分隔的频道 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 服务器。发送一条消息进行测试——可以是私信，也可以是它已被添加到的频道。

提示

你可以在后台或以 systemd 服务的形式运行 hermes gateway，以确保持久运行。详情请参阅部署文档。

主频道 (Home Channel)

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

使用斜杠命令

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

手动配置

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

MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn

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

回复模式 (Reply Mode)

MATTERMOST_REPLY_MODE 设置控制 Hermes 的发帖方式：

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

MATTERMOST_REPLY_MODE=thread

提及行为 (Mention Behavior)

默认情况下，机器人仅在频道中被 @mention 时才会响应。你可以更改此行为：

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

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

频道白名单 (allowed_channels)

将机器人限制在一组固定的 Mattermost 频道中。设置后，机器人仅在 ID 出现在列表中的频道里响应——来自其他任何频道的消息都会被静默忽略，即使机器人被 @mention。

私信不受此过滤器限制，因此授权用户始终可以通过直接消息联系机器人。

mattermost:
  allowed_channels:
    - "abc123def456ghi789jkl012mno"   # #ops
    - "xyz987uvw654rst321opq098nml"   # #incident-response

或通过环境变量设置（逗号分隔）：

MATTERMOST_ALLOWED_CHANNELS="abc123def456ghi789jkl012mno,xyz987uvw654rst321opq098nml"

行为说明：

• 为空 / 未设置 → 无限制（完全向后兼容）。
• 非空 → 频道 ID 必须在列表中，否则消息会在任何其他门控（提及要求、MATTERMOST_FREE_RESPONSE_CHANNELS 等）运行之前被丢弃。
• 通过 Mattermost 界面 → 频道标题 → "查看信息" 获取频道 ID，或从频道 URL 中读取。

另请参阅：admin/user slash command split。

故障排查

机器人不响应消息

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

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

403 Forbidden 错误

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

解决方法：检查 .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;
}

启动时提示 "Failed to authenticate"

原因：令牌或服务器 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 服务器不可达。

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

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

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

按频道提示词 (Per-Channel Prompts)

为特定的 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 中。
• 兼容团队版：同时支持 Mattermost Team Edition（免费版）和 Enterprise Edition。