Mattermost Hermes Agent — 自架團隊聊天

Mattermost Hermes Agent — 自架團隊聊天

如果你的團隊使用 Mattermost，你應該已經知道它的迷人之處：外觀和操作起來就像 Slack，但伺服器——以及資料——都留在你自己的基礎架構上。Hermes Agent 以機器人的身分接入，透過 Mattermost 的 REST API（v4）加上 WebSocket 接收即時事件來連線，讓你的助理能在私訊和團隊頻道中回覆，而所有內容都不會離開你的網路。

不需要額外安裝任何函式庫：轉接器使用的是 aiohttp，Hermes 已經內建。Mattermost Team Edition（免費版）和 Enterprise Edition 都能用。

Hermes 在 Mattermost 中的行為

你在哪裡跟它對話	會發生什麼事
私訊	Hermes 會回覆每一則訊息——不需要 @mention。每個私訊都有獨立的 session。
頻道	當你 @mention 它時，Hermes 才會回覆。沒有 mention 的話，它會忽略訊息。
討論串	設定 MATTERMOST_REPLY_MODE=thread 後，回覆會嵌套在你的訊息底下，並與母頻道隔離。
共用頻道	預設情況下，session 歷史紀錄會依使用者隔離，所以同一個頻道裡的兩個人不會共用對話紀錄。

最後一項行為由 config.yaml 中的 group_sessions_per_user 控制：

group_sessions_per_user: true   # each person keeps their own context

只有在你想讓整個頻道刻意共用一段對話時，才將它設為 false。共用 session 意味著所有人共享上下文成長和 token 成本，而且某個人長時間、大量使用工具的任務，可能會讓其他人的執行膨脹或中斷。

---

步驟 1：啟用機器人帳號（管理端）

你必須先在伺服器上開啟機器人帳號功能，才能建立一個：

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

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

步驟 2：建立機器人帳號

1. 點擊 ☰ 選單（左上角）→ Integrations → Bot Accounts → Add Bot Account。
2. 填寫詳細資料：Username 例如 hermes、Display Name 例如 Hermes Agent，以及 Role——Member 就夠了。
3. 點擊 Create Bot Account，然後立刻複製 token——它只會顯示一次。弄丟了的話，你得從機器人帳號設定重新產生。

⚠️ 絕對不要分享 token，也不要把它提交到 Git。任何持有它的人都能完全控制這個機器人。

想讓 agent 以你自己的使用者身分發文，而不是用一個獨立的機器人嗎？在 Profile → Security → Personal Access Tokens → Create Token 底下建立一個個人存取權杖。

步驟 3：邀請機器人加入頻道

機器人只會在它所屬的頻道中回應：

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

至於私訊，只要直接開啟與機器人的私訊對話即可——不需要邀請。

步驟 4：找到你的 Mattermost 使用者 ID

Hermes 使用你的使用者 ID——而不是你的使用者名稱——來決定誰可以跟機器人對話：

1. 點擊你的頭像（左上角）→ Profile。
2. 對話框會顯示你的使用者 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

然後啟動 gateway：

hermes gateway

機器人會在幾秒內連上你的 Mattermost 伺服器。傳一則私訊給它，或在它已被加入的頻道中 @mention 它來測試。

步驟 6：選用的行為開關

設定	作用
MATTERMOST_REPLY_MODE	off（預設）發送平面訊息；thread 將回覆嵌套在你的訊息底下，讓忙碌的頻道保持整潔。
MATTERMOST_REQUIRE_MENTION	預設為 true。設為 false 即可回應所有頻道訊息（私訊一律有效）。
MATTERMOST_FREE_RESPONSE_CHANNELS	即使需要 mention，這些頻道 ID 仍可跳過 mention 要求。
MATTERMOST_HOME_CHANNEL	主動訊息的去處——cron 輸出、提醒、通知。或在頻道中輸入 /sethome。
mattermost.allowed_channels	將機器人限制在一組頻道 ID；來自其他地方的訊息都會被丟棄。私訊不受此限。
mattermost.channel_prompts	為每個頻道注入一段臨時的系統提示——每一輪都會套用，但永遠不會存入對話歷史紀錄。

當機器人被 @mentioned 時，mention 會在處理前從訊息中移除，所以 @hermes summarize this thread 會以乾淨的指令形式送達。

疑難排解

症狀	可能原因	修正方式
機器人在頻道中忽略你	它不在該頻道中，或你的使用者 ID 不在 MATTERMOST_ALLOWED_USERS 裡	將機器人加入頻道、確認那 26 個字元的使用者 ID、重新啟動 gateway
機器人無法發文	token 無效，或機器人在該頻道中沒有權限	檢查 MATTERMOST_TOKEN、確認帳號處於啟用狀態且是頻道成員
不斷斷線	WebSocket 中斷、伺服器重新啟動，或代理/防火牆問題	轉接器會以指數退避重新連線（2 秒 → 60 秒）；使用 nginx 的話，請確認已設定 WebSocket upgrade 標頭
完全沒有任何反應	Gateway 沒有在執行，或 URL/token 有誤	檢查 hermes gateway 的輸出，並確認 MATTERMOST_URL 包含 https:// 且結尾沒有斜線

直接用以下指令測試 token：

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

保護機器人

一定要設定 MATTERMOST_ALLOWED_USERS。沒有設定的話，gateway 基於安全考量會預設拒絕所有使用者——而獲授權的使用者能完整取用 agent 的各項能力，包括工具使用和系統存取，所以請把名單控制得越精簡越好。若想更全面地了解如何強化部署，請參閱官方安全指南。

---

接下來呢？

Gateway 啟動後，Mattermost 的行為就跟其他任何 Hermes 頻道一樣：斜線指令、檔案上傳、語音訊息、cron 輸出傳送到你的 home 頻道——全都跑在你掌控的基礎架構上。如果你偏好使用託管選項，Slack 整合涵蓋了 Socket Mode 這條路徑；如果你在多台機器上執行 gateway，Hermes Relay能將它們連接起來。