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 文件中：

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

# 多個允許用戶（用逗號分隔）
# MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e

# 可選：回覆模式（線程或關閉，默認：關閉）
# MATTERMOST_REPLY_MODE=螺紋

# 可選：回覆時不帶 @mention（默認值：true = 需要提及）
# MATTERMOST_REQUIRE_MENTION=假

# 可選：機器人在沒有 @mention 的情況下響應的頻道（以逗號分隔的頻道 ID）
# MATTERMOST_FREE_RESPONSE_CHANNELS=通道_id_1,通道_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 連接存在防火牆/Agent 問題。

修復：適配器會自動以指數退避方式重連（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——授權用戶擁有對 Agent 功能的完全訪問權限，包括工具使用和系統訪問。

有關保護你的 Hermes Agent 部署的更多信息，請參閱安全指南。

注意事項

支持自託管：可與任何自託管的 Mattermost 實例配合使用。無需 Mattermost Cloud 賬戶或訂閱。
無額外依賴：該適配器使用 aiohttp 進行 HTTP 和 WebSocket 操作，而 aiohttp 已包含在 Hermes Agent 中。
兼容團隊版：支持 Mattermost 團隊版（免費）和企業版。

Hermes 的行為表現​

Mattermost 中的會話模型​

第一步：啟用機器人賬戶​

第二步：創建機器人賬戶​

第三步：將機器人添加到頻道​

第四步：獲取您的 Mattermost 用戶 ID​

第五步：配置 Hermes Agent​

選項 A：交互式設置（推薦）​

選項 B：手動配置​

啟動網關​

主頻道​

使用斜槓命令​

手動配置​

回覆模式​

提及行為​

故障排除​

機器人不響應消息​

403 禁止錯誤​

WebSocket 斷開 / 重連循環​

啟動時“認證失敗”​

機器人離線​

“用戶不允許” / 機器人忽略你​

安全性​

注意事項​