Mattermost

Hermes Agent 可作为 bot 接入 Mattermost，让你通过私聊或团队频道与 AI 助手对话。Mattermost 是一个可自托管、开源的 Slack 替代方案。bot 通过 Mattermost 的 REST API（v4）和 WebSocket 接收实时事件，经由 Hermes Agent 流水线处理后即时回复，支持文本、文件附件、图片和 slash commands。

Hermes 不依赖额外的 Mattermost 专用库；适配器直接使用 aiohttp，而它本身已经是 Hermes 的依赖之一。

Hermes 的行为方式

Context	Behavior
DMs	每条消息都会回复，无需 `@mention`。每个 DM 拥有独立会话。
Public/private channels	只有当你 `@mention` 它时才会回复；未提及时会忽略。
Threads	若 `MATTERMOST_REPLY_MODE=thread`，Hermes 会在线程中回复，thread 上下文与父频道隔离。
Shared channels with multiple users	默认按用户隔离同一频道中的会话历史。

提示

如果你希望 Hermes 总是以线程方式回复，把 MATTERMOST_REPLY_MODE=thread 加到配置里即可。默认值是 off，表示直接在频道中平铺回复。

Mattermost 中的会话模型

默认情况下：

每个 DM 是独立会话
每个 thread 拥有自己的会话命名空间
同一共享频道中，每个用户在频道内也拥有独立会话

由 config.yaml 控制：

group_sessions_per_user: true

如果你明确希望整个频道共享一段会话，可改为：

group_sessions_per_user: false

共享会话意味着：

用户共享上下文增长与 token 成本
某个人的长时间工具任务会拖大其他人的上下文
某个人正在运行的任务可能打断同频道里另一人的后续消息

第 1 步：启用 Bot Accounts

在创建 bot 之前，Mattermost 服务器必须先启用 bot accounts：

以 System Admin 身份登录 Mattermost
打开 System Console → Integrations → Bot Accounts
把 Enable Bot Account Creation 设为 true
点击 Save

信息

如果你没有 System Admin 权限，请让 Mattermost 管理员帮你启用 bot accounts 并创建 bot。

第 2 步：创建 Bot Account

打开 Integrations → Bot Accounts
点击 Add Bot Account
填写用户名、显示名、描述等
点击 Create Bot Account
Mattermost 会显示 bot token，请立即复制

Token 只展示一次

如果遗失，只能在 bot account 设置里重新生成。不要公开分享 token，也不要提交到 Git。

提示

你也可以使用 personal access token 而不是 bot account。进入 Profile → Security → Personal Access Tokens → Create Token。如果你希望 Hermes 以你自己的身份发言，这是个实用选项。

第 3 步：把 Bot 加入频道

bot 必须加入你希望它响应的频道：

打开目标频道
点击频道名 → Add Members
搜索并添加 bot

对于私聊，直接和 bot 打开一个 DM 即可。

第 4 步：找到你的 Mattermost User ID

Hermes Agent 使用 Mattermost User ID 控制谁可以与 bot 交互。获取方式：

点击头像 → Profile
User ID 会显示在资料对话框中，点击即可复制

它通常是像 3uo8dkh1p7g1mfk49ear5fzs5c 这样的 26 位字母数字串。

注意

User ID 不是你的用户名。用户名是 @alice 这种形式，而 User ID 是 Mattermost 内部使用的长字符串。

你也可以通过 API 获取：

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

提示

如果你还需要 Channel ID，可点击频道名 → View Info，在信息面板中查看。

第 5 步：配置 Hermes Agent

Option A: Interactive Setup (Recommended)

hermes gateway setup

选择 Mattermost，然后按提示填写服务器 URL、bot token 和你的 user ID。

Option B: Manual Configuration

把以下内容加入 ~/.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 会在共享频道和线程中按参与者隔离上下文

Start the Gateway

hermes gateway

几秒内 bot 就会连接到 Mattermost。你可以发一条私聊消息，或者在 bot 已加入的频道里发消息进行测试。

提示

你也可以把 hermes gateway 作为后台进程或 systemd 服务运行，实现长期驻留。具体可参见部署文档。

Home Channel

你可以指定一个 “home channel”，让 bot 主动发送消息（如 cron 结果、提醒和通知）。

Using the Slash Command

在任意 bot 所在的 Mattermost 频道输入 /sethome，该频道就会成为 home channel。

Manual Configuration

把以下内容加入 ~/.hermes/.env：

MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn

把 ID 替换成实际 Channel ID 即可。

Reply Mode

MATTERMOST_REPLY_MODE 控制 Hermes 的回复方式：

Mode	Behavior
`off` (default)	直接在频道中平铺回复，就像普通用户发言一样
`thread`	在你的原消息下方以 thread 方式回复，更适合频繁来回对话

MATTERMOST_REPLY_MODE=thread

Mention Behavior

默认情况下，bot 只会在被 @mention 时在频道里回复。可通过以下配置调整：

Variable	Default	Description
`MATTERMOST_REQUIRE_MENTION`	`true`	设为 `false` 时，会在频道中对所有消息都回复（DM 不受影响）
`MATTERMOST_FREE_RESPONSE_CHANNELS`	(none)	即使 `require_mention=true`，这些频道中也无需 `@mention`

当 bot 被 @mention 时，mention 文本会在送入 agent 前自动从消息中移除。

Per-Channel Prompts

你可以为特定 Mattermost 频道配置临时系统提示。该提示会在每轮运行时注入，但不会写入 transcript 历史，因此修改会立刻生效。

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.

key 是 Mattermost channel ID。匹配频道中的所有消息都会获得相应的临时系统提示。

Troubleshooting

Problem	Solution
Bot 不响应	确认 bot 已加入频道，且 `MATTERMOST_ALLOWED_USERS` 包含你的 User ID
403 Forbidden	检查 token 是否有效，以及 bot 是否有在该频道发言的权限
WebSocket 反复断开重连	检查网络，以及反向代理（如 nginx / Apache）的 WebSocket 升级配置
启动时报认证失败	检查 `MATTERMOST_URL` 和 `MATTERMOST_TOKEN` 是否正确
Bot 离线	检查 `hermes gateway` 是否在运行，以及服务器是否可达
`User not allowed`	你的 User ID 不在 `MATTERMOST_ALLOWED_USERS` 中

Security

注意

务必设置 MATTERMOST_ALLOWED_USERS 来限制谁可以与 bot 交互。否则，出于安全考虑，网关默认会拒绝所有用户。只应授权你信任的人，因为被授权用户拥有 agent 的全部能力，包括工具调用和系统访问。

关于如何保护你的 Hermes Agent 部署，请参见 Security Guide。

Notes

适合自托管：可与任意自托管 Mattermost 实例配合使用
无额外依赖：适配器直接使用 aiohttp 处理 HTTP 与 WebSocket
兼容 Team Edition：同时适用于 Mattermost Team Edition 和 Enterprise Edition

Hermes 的行为方式​

Mattermost 中的会话模型​

第 1 步：启用 Bot Accounts​

第 2 步：创建 Bot Account​

第 3 步：把 Bot 加入频道​

第 4 步：找到你的 Mattermost User ID​

第 5 步：配置 Hermes Agent​

Option A: Interactive Setup (Recommended)​

Option B: Manual Configuration​

Start the Gateway​

Home Channel​

Using the Slash Command​

Manual Configuration​

Reply Mode​

Mention Behavior​

Per-Channel Prompts​

Troubleshooting​

Security​

Notes​