Mattermost Hermes Agent — 自托管团队聊天

如果你的团队使用 Mattermost，你肯定知道它的吸引力：用起来像 Slack，但服务器和数据都留在你自己的基础设施上。Hermes Agent 以机器人身份接入其中，通过 Mattermost 的 REST API（v4）加上用于实时事件的 WebSocket 进行连接，因此你的助手可以在私信和团队频道中回答问题，而一切都不会离开你的网络。

无需安装额外的库：适配器使用 aiohttp，它已经随 Hermes 一起提供。它同时适用于 Mattermost Team Edition（免费）和 Enterprise Edition。

Hermes 在 Mattermost 中的行为

你在哪里与它对话	会发生什么
私信	Hermes 会回复每条消息——无需 `@mention`。每个私信都有自己的会话。
频道	当你 `@mention` 它时，Hermes 才会回复。没有提及，它会忽略该消息。
话题	使用 `MATTERMOST_REPLY_MODE=thread` 时，回复会嵌套在你的消息下，并与父频道保持隔离。
共享频道	默认情况下，会话历史按用户隔离，因此同一频道中的两个人不会共享对话记录。

最后一项行为由 config.yaml 中的 group_sessions_per_user 控制：

group_sessions_per_user: true   # each person keeps their own context

只有在你有意让整个频道共享一段对话时，才将其设置为 false。共享会话意味着所有人共享上下文增长和 token 成本，而且某个人长时间、工具密集的任务可能会膨胀或中断其他人的运行。

第 1 步：启用机器人账户（管理员侧）

在创建机器人账户之前，必须先为服务器开启机器人账户功能：

以系统管理员身份登录 Mattermost。
前往System Console → Integrations → Bot Accounts。
将 Enable Bot Account Creation 设置为 true，然后点击 Save。

没有管理员权限？请让你的 Mattermost 管理员启用机器人账户并为你创建一个。

第 2 步：创建机器人账户

点击 ☰ 菜单（左上角）→ Integrations → Bot Accounts → Add Bot Account。
填写详细信息：Username 例如 hermes，Display Name 例如 Hermes Agent，以及 Role——Member 就足够了。
点击 Create Bot Account，然后立即复制 token——它只会显示一次。如果丢失，你必须从机器人账户设置中重新生成。

⚠️ 切勿分享 token 或将其提交到 Git。任何持有它的人都能完全控制该机器人。

更希望智能体以你自己的用户身份而不是单独的机器人身份发帖？在 Profile → Security → Personal Access Tokens → Create Token 下创建一个个人访问令牌。

第 3 步：邀请机器人加入频道

机器人只会在它所属的频道中响应：

打开频道 → 点击频道名称 → Add Members。
搜索机器人用户名（例如 hermes）并添加它。

对于私信，只需打开与机器人的直接消息——无需邀请。

第 4 步：找到你的 Mattermost 用户 ID

Hermes 使用你的用户 ID——而不是你的用户名——来决定谁可以与机器人对话：

点击你的头像（左上角）→ Profile。
对话框会显示你的用户 ID：一个 26 个字符的字母数字字符串，例如 3uo8dkh1p7g1mfk49ear5fzs5c。点击即可复制。

你也可以从 API 中读取它：

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

你的用户 ID 不是你在消息中看到的 @username。粘贴用户名是机器人保持沉默的最常见原因。

第 5 步：配置 Hermes

运行引导式设置，并在提示时选择 Mattermost——它会询问服务器 URL、机器人 token 和你的用户 ID：

hermes gateway setup

或者在 ~/.hermes/.env 中手动配置：

# Required
MATTERMOST_URL=https://mm.example.com
MATTERMOST_TOKEN=your-bot-token
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c

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

# Optional: reply in a thread instead of flat messages (default: off)
# MATTERMOST_REPLY_MODE=thread

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

# Optional: channels where no @mention is needed (comma-separated channel IDs)
# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2

然后启动网关：

hermes gateway

机器人会在几秒钟内连接到你的 Mattermost 服务器。给它发送一条私信，或者在已添加它的频道中 @mention 它，以进行测试。

第 6 步：可选的行为开关

设置	作用
`MATTERMOST_REPLY_MODE`	`off`（默认）发布平铺消息；`thread` 将回复嵌套在你的消息下，让繁忙的频道保持整洁。
`MATTERMOST_REQUIRE_MENTION`	默认为 `true`。设置为 `false` 可响应所有频道消息（私信始终有效）。
`MATTERMOST_FREE_RESPONSE_CHANNELS`	即使要求提及时也跳过提及要求的频道 ID。
`MATTERMOST_HOME_CHANNEL`	主动消息的去向——cron 输出、提醒、通知。或者在频道中输入 `/sethome`。
`mattermost.allowed_channels`	将机器人限制在频道 ID 列表中；来自其他任何地方的消息都会被丢弃。私信不受限制。
`mattermost.channel_prompts`	为每个频道注入临时的系统提示——每一轮都会应用，但从不保存到对话历史中。

当机器人被 @mentioned 时，提及会在处理前从消息中剥离，因此 @hermes summarize this thread 会作为一条干净的指令到达。

故障排除

症状	可能原因	修复方法
机器人在频道中忽略你	它不在该频道中，或者你的用户 ID 不在 `MATTERMOST_ALLOWED_USERS` 中	将机器人添加到频道，验证 26 个字符的用户 ID，重启网关
机器人无法发帖	token 无效，或者机器人在该频道中缺少权限	检查 `MATTERMOST_TOKEN`，确认账户处于活动状态且是频道成员
不断断开连接	WebSocket 掉线、服务器重启，或代理/防火墙问题	适配器会以指数退避重连（2 秒 → 60 秒）；对于 nginx，请确保配置了 WebSocket 升级头
完全没有反应	网关未运行，或者 URL/token 错误	检查 `hermes gateway` 的输出，以及 `MATTERMOST_URL` 是否包含 `https://` 且没有尾部斜杠

直接用以下命令测试 token：

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

保护机器人安全

始终设置 MATTERMOST_ALLOWED_USERS。如果没有设置，网关默认会拒绝所有用户，作为一项安全措施——而获得授权的用户将完全访问智能体的能力，包括工具使用和系统访问，因此请保持列表精简。如需更全面地了解如何加固部署，请参阅官方安全指南。

接下来做什么？

网关启动后，Mattermost 的行为就像任何其他 Hermes 频道一样：斜杠命令、文件上传、语音消息、cron 输出发送到你的主频道——全部运行在你控制的基础设施上。如果你更愿意使用托管选项，Slack 集成涵盖了 Socket Mode 方式；如果你在多台机器上运行网关，Hermes Relay 可以将它们连接起来。