Section: Messaging Platforms · URL: https://hermesbible.com/docs/user-guide/messaging/mattermost

Mattermost 設定

Hermes Agent 可以作為機器人整合到 Mattermost，讓你透過私人訊息或團隊頻道與 AI 助手聊天。Mattermost 是一個自架式、開源的 Slack 替代方案——你可以把它部署在自己的基礎設施上，完全掌控你的資料。機器人透過 Mattermost 的 REST API（v4）和 WebSocket 連接以取得即時事件，透過 Hermes Agent 管線處理訊息（包括工具使用、記憶和推理），並即時回應。支援文字、檔案附件、圖片和斜線指令。

不需要額外安裝 Mattermost 函式庫——連接器使用的是 aiohttp，它已經是 Hermes 的相依套件。

在開始設定之前，大多數人最想知道的是：Hermes 接入你的 Mattermost 實例後會有什麼行為。

Hermes 的行為方式

情境	行為
私人訊息	Hermes 會回應每一則訊息，不需要 `@提及`。每則私人訊息都有獨立的 session。
公開/私密頻道	當你用 `@提及` 時 Hermes 才會回應。若未提及，Hermes 會忽略訊息。
討論串	若設定 `MATTERMOST_REPLY_MODE=thread`，Hermes 會在你的訊息下方以討論串回覆。討論串的 context 與父頻道互相隔離。
多人共用的頻道	預設情況下，Hermes 會為頻道中的每個使用者隔離 session 歷史。在同一個頻道中對話的兩個人不會共用同一份對話紀錄，除非你明確關閉此設定。

提示

若你希望 Hermes 以討論串方式回覆（嵌套在你的原始訊息下方），請設定 MATTERMOST_REPLY_MODE=thread。預設為 off，會在頻道中直接發送平面訊息。

Mattermost 中的 Session 模型

預設情況下：

每則私人訊息都有獨立的 session
每個討論串都有獨立的 session 命名空間
共用頻道中的每個使用者都有各自的 session

這由 config.yaml 控制：

group_sessions_per_user: true

只有在你明確希望整個頻道共用一段對話時，才設為 false：

group_sessions_per_user: false

共用 session 對協作頻道來說可能有幫助，但也代表：

使用者會共享 context 增長和 token 成本
某人進行一項需要大量工具的長任務時，可能會膨脹其他人的 context
某人正在執行中的任務可能會干擾同頻道中其他人的後續操作

本指南將帶你完成完整的設定流程——從在 Mattermost 上建立你的機器人到發送第一則訊息。

步驟一：啟用機器人帳號

在建立機器人帳號之前，必須先在你的 Mattermost 伺服器上啟用此功能。

以系統管理員身分登入 Mattermost。
前往 System Console → Integrations → Bot Accounts。
將 Enable Bot Account Creation 設為 true。
點擊 Save。

資訊

如果你沒有系統管理員權限，請請你的 Mattermost 管理員啟用機器人帳號並幫你建立一個。

步驟二：建立機器人帳號

在 Mattermost 中，點擊 ☰ 選單（左上角）→ Integrations → Bot Accounts。
點擊 Add Bot Account。
填入詳細資訊：
- Username：例如 hermes
- Display Name：例如 Hermes Agent
- Description：選填
- Role：Member 即可
點擊 Create Bot Account。
Mattermost 會顯示 bot token。請立即複製。

:::warning[Token 僅顯示一次] Bot token 在建立機器人帳號時只會顯示一次。如果你遺失了，需要從機器人帳號設定中重新產生。請勿公開分享你的 token 或將其提交到 Git——任何取得此 token 的人都可以完全控制這個機器人。 :::

將 token 儲存在安全的地方（例如密碼管理器）。在步驟五中會用到。

提示

你也可以使用個人存取 token 來取代機器人帳號。前往 Profile → Security → Personal Access Tokens → Create Token。這在你希望 Hermes 以你自己的使用者身分發言而非獨立的機器人使用者時很有用。

步驟三：將機器人加入頻道

機器人需要成為任何你希望它回應的頻道的成員：

開啟你要加入機器人的頻道。
點擊頻道名稱 → Add Members。
搜尋你的機器人使用者名稱（例如 hermes）並加入。

對於私人訊息，直接與機器人開啟一段對話即可——它會立即能夠回應。

步驟四：找到你的 Mattermost User ID

Hermes Agent 使用你的 Mattermost User ID 來控制誰可以與機器人互動。找到它的方式：

點擊你的頭像（左上角）→ Profile。
你的 User ID 會顯示在個人檔案對話框中——點擊即可複製。

你的 User ID 是一個 26 字元的字母數字字串，例如 3uo8dkh1p7g1mfk49ear5fzs5c。

警告

你的 User ID 不是你的使用者名稱。使用者名稱是 @ 後面顯示的名稱（例如 @alice）。User ID 是 Mattermost 內部使用的一串字母數字識別碼。

替代方式：你也可以透過 API 取得你的 User ID：

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

提示

若要取得頻道 ID：點擊頻道名稱 → View Info。頻道 ID 會顯示在資訊面板中。如果你要手動設定主頻道，就需要這個 ID。

步驟五：設定 Hermes Agent

選項 A：互動式設定（建議）

執行引導式設定指令：

hermes gateway setup

在提示時選擇 Mattermost，然後在要求時貼上你的伺服器 URL、bot token 和 user 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 可讓每個參與者在共用頻道和討論串中的 context 保持隔離

啟動 Gateway

設定完成後，啟動 Mattermost gateway：

hermes gateway

機器人應在幾秒內連接到你的 Mattermost 伺服器。發送一則訊息來測試——可以是私人訊息，也可以在它已被加入的頻道中發送。

提示

你可以將 hermes gateway 放在背景執行，或作為 systemd 服務以實現持續運作。詳情請參閱部署文件。

主頻道

你可以指定一個「主頻道」，機器人會在此發送主動訊息（例如排程任務輸出、提醒和通知）。有兩種設定方式：

使用斜線指令

在機器人所在的任何 Mattermost 頻道中輸入 /sethome。該頻道就會成為主頻道。

手動設定

在你的 ~/.hermes/.env 中加入：

MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn

將 ID 替換為實際的頻道 ID（點擊頻道名稱 → View Info → 複製 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，在這些頻道中機器人無需 `@提及` 就會回應，即使 require_mention 為 true 也是如此。

在 Mattermost 中找到頻道 ID：開啟頻道，點擊頻道名稱標題，即可在 URL 或頻道詳情中找到 ID。

當機器人被 @提及 時，提及標記會在處理前自動從訊息中移除。

頻道白名單（`allowed_channels`）

限制機器人只能在指定的 Mattermost 頻道中運作。設定後，機器人只會在 ID 出現於列表中的頻道回應——來自任何其他頻道的訊息都會被靜默忽略，即使機器人被 @提及 也是如此。

私人訊息不受此過濾器限制，因此授權使用者始終可以透過私人訊息與機器人互動。

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

或透過環境變數設定（以逗號分隔）：

MATTERMOST_ALLOWED_CHANNELS="abc123def456ghi789jkl012mno,xyz987uvw654rst321opq098nml"

行為：

空值或未設定 → 無限制（完全向後相容）。
有值 → 頻道 ID 必須在列表中，否則訊息會在其他門檻機制（提及要求、MATTERMOST_FREE_RESPONSE_CHANNELS 等）運作之前就被丟棄。
透過 Mattermost UI → 頻道標題 → "View Info" 可找到頻道 ID，或從頻道 URL 中讀取。

另請參閱：admin/user 斜線指令分割。

疑難排解

機器人沒有回應訊息

原因：機器人不是該頻道的成員，或 MATTERMOST_ALLOWED_USERS 中沒有包含你的 User ID。

修復：將機器人加入頻道（頻道名稱 → Add Members → 搜尋機器人）。確認你的 User ID 在 MATTERMOST_ALLOWED_USERS 中。重新啟動 gateway。

403 Forbidden 錯誤

原因：bot token 無效，或機器人沒有在該頻道發言的權限。

修復：檢查你的 .env 檔案中的 MATTERMOST_TOKEN 是否正確。確保機器人帳號未被停用。確認機器人已被加入該頻道。如果使用個人存取 token，請確保你的帳號有必要的權限。

WebSocket 斷線 / 重連迴圈

原因：網路不穩定、Mattermost 伺服器重新啟動，或 WebSocket 連線的防火牆/代理問題。

修復：連接器會自動以指數退避（2s → 60s）重連。檢查你的伺服器 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"

原因：token 或伺服器 URL 不正確。

修復：確認 MATTERMOST_URL 指向你的 Mattermost 伺服器（包含 https://，末尾無斜線）。檢查 MATTERMOST_TOKEN 是否有效——可用 curl 測試：

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

若返回你的機器人使用者資訊，表示 token 有效。若返回錯誤，請重新產生 token。

機器人離線

原因：Hermes gateway 未在運行，或連線失敗。

修復：檢查 hermes gateway 是否正在運行。查看終端機輸出中的錯誤訊息。常見問題：URL 錯誤、token 過期、Mattermost 伺服器無法連線。

"User not allowed" / 機器人不理你

原因：你的 User ID 不在 MATTERMOST_ALLOWED_USERS 中。

修復：在 ~/.hermes/.env 中的 MATTERMOST_ALLOWED_USERS 加入你的 User ID，然後重新啟動 gateway。請記住：User ID 是一個 26 字元的字母數字字串，不是你的 @username。

每個頻道的提示詞

為特定的 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 來限制誰可以與機器人互動。若未設定，gateway 出於安全考量會預設拒絕所有使用者。只加入你信任的使用者的 User ID——授權使用者可以完全使用 agent 的功能，包括工具使用和系統存取。

如需了解更多關於保護你的 Hermes Agent 部署的資訊，請參閱安全性指南。

備註

自架友好：適用於任何自架式 Mattermost 實例。不需要 Mattermost Cloud 帳號或訂閱。
無額外相依：連接器使用 aiohttp 處理 HTTP 和 WebSocket，它已包含在 Hermes Agent 中。
Team Edition 相容：同時支援 Mattermost Team Edition（免費版）和 Enterprise Edition。