緣起：助理不該只在 SSH 裡

我的 VPS 上跑著 Hermes Agent——一個開源的自主 AI 助理，會記住我的偏好、幫我管網站、排定時任務。但它的介面在終端機裡，出門在外想交代事情，得先開 SSH、連上主機、再進 session，實在太繞。

如果 Hermes 能出現在 WhatsApp 呢？手機隨身、訊息即時、語音還能直接講——這才是助理該有的樣子。於是我決定把它接上 WhatsApp。

事前研究：Baileys bridge 是什麼？

查了 Hermes 官方文件（docs 有完整教學），關鍵資訊是：Hermes 用的是內建的 Baileys bridge，原理是模擬一個 WhatsApp Web 連線——不需要 Meta 開發者帳號、不需要 Business 驗證、不需要公開網址。對個人使用來說，這是目前最快的路。

但文件也老實警告：這是非官方 API，有帳號被限制的風險，建議用專用門號、不要發大量訊息、不要主動私訊沒先聯絡你的人。個人低頻使用風險很低，可以接受。

設定前有個關鍵選擇——兩種模式：

• bot 模式：用一個專用門號（Google Voice、預付卡 SIM 或 VoIP），別人直接傳訊息給這個門號。多人可用、風險較低，但要先搞到第二個號碼。
• self-chat 模式：用自己的 WhatsApp，傳訊息給自己就是呼叫助理。最快、單人測試最方便。

我選了 self-chat——先跑通再說，之後要升級 bot 模式隨時可以再配。

環境盤點：開工前的檢查

動手前先盤點環境（都是唯讀指令）：

• Hermes v0.20.0 已安裝
• Node v24.11.0 + npm 11.6.1 就緒（bridge 是 Node.js 程序，需要 Node v18+）
• ~/.hermes/.env 裡已有註解掉的 WhatsApp 設定檔位（# WHATSAPP_ENABLED=false），表示框架早就預留好位置，只需啟用
• 尚未配對（無 session 目錄）

一切就緒，可以開始。

動手實做：四個步驟

步驟一：啟用設定（.env）

在 ~/.hermes/.env 加入三行：

WHATSAPP_ENABLED=true
WHATSAPP_MODE=self-chat
WHATSAPP_ALLOWED_USERS=8869XXXXXXXX   # 你的門號，含國碼、不加 +

第三行是白名單，這是安全關鍵：沒有白名單的話，gateway 會基於安全預設拒絕所有進來的訊息。設定後，只有這個號碼能呼叫助理，陌生訊息一律不理。

小知識：.env 是受保護的憑證檔，一般檔案工具會拒絕存取，必須用終端機編輯——這是設計如此，不是故障。

步驟二：陌生人策略（config.yaml）

設定 whatsapp.unauthorized_dm_behavior: ignore：預設行為是陌生人傳訊息會收到一組「配對碼」回覆，對私人號碼來說沒必要，改成靜默忽略比較乾淨。用 hermes config set 指令設定，不手動改設定檔。

步驟三：QR 配對

執行 hermes whatsapp 啟動配對精靈，它會：

1. 自動偵測 .env 裡設定的 self-chat 模式
2. 安裝 bridge 依賴（npm）
3. 在終端顯示一組 QR code

手機端：WhatsApp → 設定 → 已連結的裝置 → 連結裝置 → 掃描。

兩個小提醒：QR code 約 20 秒就會換一張，掃之前先把手機準備好；終端至少要 60 欄寬才不會顯示成亂碼。

掃描成功後 session 自動存檔，之後重開機都不用再掃。

步驟四：讓 gateway 常駐

最後把訊息 gateway 裝成服務，讓它 24 小時待命：

• hermes gateway install：裝成使用者服務（不需要 sudo）
• 啟用 systemd linger：登出 SSH 也不中斷、重開機自動啟動

這裡踩了一個小坑：啟動後系統提示「gateway 服務定義版本過舊」，跑一次 hermes gateway restart 就自動更新成新定義，然後看到熟悉的綠燈。

驗證：看到 ✅ 的那一刻

檢查 bridge 日誌（~/.hermes/whatsapp/bridge.log）：

🌉 WhatsApp bridge listening on port 3000 (mode: self-chat)
🔒 Allowed users: 8869XXXXXXXX
✅ WhatsApp connected!

連線成功。從手機傳訊息給自己，助理秒回，前面綴著「⚕ Hermes Agent」。之後的使用體驗：

• 訊息格式：回覆的 Markdown 自動轉成 WhatsApp 原生格式（粗體、刪除線、程式碼塊）
• 長回覆：自動在 4,096 字元處分段，一條一條接著送
• 語音：收到的語音訊息自動轉文字（本地 faster-whisper），也可以用 Groq 更快
• 斷線自動重連：網路不穩、手機暫時離線都不用管

踩過的坑（給未來的我）

1. QR code 20 秒過期 — 從背景程序的輸出撈新的一張即可，不用重跑精靈
2. gateway 服務定義過舊 — 裝完服務記得 hermes gateway restart 更新
3. Node PATH 陷阱 — 我的 Node 24 裝在使用者目錄，bridge 安裝依賴前要先 export PATH，否則會抓到系統舊版 Node
4. session 憑證超敏感 — ~/.hermes/whatsapp/session 含有完整帳號憑證（等於 WhatsApp 網頁版的登入鑰匙），權限要設 700，絕對不能進 git 或外流。懷疑被盜就從手機端解除連結裝置
5. 白名單格式 — 門號要含國碼、不加 +（台灣是 886 開頭），寫錯會「收得到訊息但助理不理你」

心得

整個過程比想像中順：從查文件到連線成功大約一個小時，大部分時間花在掃 QR 和等服務啟動。最關鍵的收穫是——官方文件要先讀，文件把環境變數、模式差異、安全預設都寫清楚了，照著做就不會瞎猜。

現在這台 VPS 上的助理從「只能在終端機叫」升級成「手機隨身帶」。排定時任務、請它監控網站、出門在外交代雜事，都從 WhatsApp 一句話搞定。哪天 session 失效（手機重置、WhatsApp 更新），重跑一次 hermes whatsapp 掃 QR 就回來，不需要重新設定。

下一步可以考慮：升級成 bot 模式用專用門號（多人可用、ban 風險更低）、串語音回覆（TTS）、或把它跟修哥筆記的部署流程接起來——助理自己會部署自己的網站，想想還挺有趣。