<!-- Source: https://hermesbible.com/docs/user-guide/messaging/whatsapp -->

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

WhatsApp 設定

Hermes 透過內建的 Baileys 橋接器連線到 WhatsApp。其運作方式是模擬一個 WhatsApp Web session ——不是透過官方的 WhatsApp Business API。不需要 Meta 開發者帳號或商業驗證。

執行 hermes gateway setup 並選擇 WhatsApp，即可透過引導式流程完成設定。

小提示 — 兩種 WhatsApp 整合方式

本頁面介紹的是 Baileys 橋接器 ——設定快速、使用個人帳號、不需要公開 URL，但有被封鎖的風險。

如果你正在運行正式的商業機器人且需要穩定性，請改為參考 WhatsApp Business Cloud API 指南。這是官方支援的路徑：沒有帳號被封鎖的風險，但需要 Meta 商業帳號和公開的 webhook URL。

這兩種適配器也可以針對不同的電話號碼同時運行，如果你有需要的話。

警告 — 非官方 API — 封鎖風險

WhatsApp 不官方支援 Business API 以外的第三方機器人。使用第三方橋接器有帳號被限制的風險。為了降低風險：

• 使用專用的電話號碼作為機器人（不要用你的個人號碼）
• 不要發送大量/垃圾訊息 ——保持使用方式以對話為主
• 不要自動化發送訊息給沒有先傳訊息的人

警告 — WhatsApp Web 協定更新

WhatsApp 會定期更新其 Web 協定，這可能暫時破壞與第三方橋接器的相容性。當這種情況發生時，Hermes 會更新橋接器的依賴套件。如果機器人在 WhatsApp 更新後停止運作，請取得最新版本的 Hermes 並重新配對。

兩種模式

---

前置需求

• Node.js v18+ 與 npm ——WhatsApp 橋接器以 Node.js 程序運行
• 一台安裝了 WhatsApp 的手機（用於掃描 QR code）

與舊版基於瀏覽器的橋接器不同，目前的 Baileys 橋接器不需要本機的 Chromium 或 Puppeteer 依賴套件。

---

步驟 1：執行設定精靈

hermes whatsapp

設定精靈將會：

1. 詢問你想使用哪種模式（bot 或 self-chat）
2. 在需要時安裝橋接器的依賴套件
3. 在你的終端機中顯示一個 QR code
4. 等待你掃描它

掃描 QR code 的方法：

1. 在你的手機上開啟 WhatsApp
2. 前往 設定 → 已連結的裝置
3. 點選 連結裝置
4. 將鏡頭對準終端機中的 QR code

配對完成後，設定精靈會確認連線並退出。你的 session 會自動儲存。

小提示

如果 QR code 看起來亂碼，請確保你的終端機至少有 60 個欄寬，並且支援 Unicode。 你也可以嘗試使用不同的終端機模擬器。

---

步驟 2：取得第二支電話號碼（Bot 模式）

對於 bot 模式，你需要一支尚未註冊 WhatsApp 的電話號碼。有三種選擇：

取得號碼後：

1. 在手機上安裝 WhatsApp（或使用支援雙 SIM 的 WhatsApp Business app）
2. 用新號碼註冊 WhatsApp
3. 執行 hermes whatsapp 並掃描來自該 WhatsApp 帳號的 QR code

---

步驟 3：設定 Hermes

在你的 ~/.hermes/.env 檔案中加入以下內容：

# Required
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot                          # "bot" or "self-chat"

# Access control — pick ONE of these options:
WHATSAPP_ALLOWED_USERS=15551234567         # Comma-separated phone numbers (with country code, no +)
# WHATSAPP_ALLOWED_USERS=*                 # OR use * to allow everyone
# WHATSAPP_ALLOW_ALL_USERS=true            # OR set this flag instead (same effect as *)

小提示 — 允許所有人的簡寫

設定 WHATSAPP_ALLOWED_USERS=* 會允許所有寄件者（等同於 WHATSAPP_ALLOW_ALL_USERS=true）。 這與 Signal 群組允許名單的行為一致。 若要改用配對流程，請移除這兩個變數並依賴 DM 配對系統。

~/.hermes/config.yaml 中的可選行為設定：

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

• unauthorized_dm_behavior: pair 是全域預設值。未知的 DM 寄件者會收到配對碼。
• whatsapp.unauthorized_dm_behavior: ignore 讓 WhatsApp 對未授權的 DM 保持靜默，這通常是私密號碼更好的選擇。

然後啟動 gateway：

hermes gateway              # Foreground
hermes gateway install      # Install as a user service
sudo hermes gateway install --system   # Linux only: boot-time system service

Gateway 會自動使用已儲存的 session 啟動 WhatsApp 橋接器。

---

Session 持久化

Baileys 橋接器將其 session 儲存在 ~/.hermes/platforms/whatsapp/session。這意味著：

• Session 在重啟後仍然存在 ——你不需要每次都重新掃描 QR code
• Session 資料包含加密金鑰和裝置憑證
• 不要分享或提交這個 session 目錄 ——它提供了對 WhatsApp 帳號的完整存取權限

---

重新配對

如果 session 中斷（手機重設、WhatsApp 更新、手動解除連結），你會在 gateway 日誌中看到連線錯誤。修復方法：

hermes whatsapp

這會產生一個新的 QR code。再次掃描即可重新建立 session。Gateway 會自動處理暫時性的斷線（網路閃斷、手機短暫離線），具備自動重連邏輯。

---

語音訊息

Hermes 支援 WhatsApp 上的語音功能：

• 接收： 語音訊息（.ogg opus）會使用已設定的 STT 提供者自動轉錄：本地 faster-whisper、Groq Whisper（GROQ_API_KEY）或 OpenAI Whisper（VOICE_TOOLS_OPENAI_KEY）
• 傳送： TTS 回覆會以 MP3 音訊檔案附件形式傳送
• Agent 的回覆預設會加上「⚕ Hermes Agent」前綴。你可以在 config.yaml 中自訂或停用：

# ~/.hermes/config.yaml
whatsapp:
  reply_prefix: ""                          # Empty string disables the header
  # reply_prefix: "🤖 *My Bot*\n──────\n"  # Custom prefix (supports \n for newlines)

---

訊息格式與傳送

WhatsApp 支援串流（漸進式）回覆 ——機器人會在 AI 產生文字時即時編輯其訊息，就像 Discord 和 Telegram 一樣。在內部，WhatsApp 被歸類為 TIER_MEDIUM 平台的傳送能力。

分段

較長的回覆會自動分割成多個訊息，每個區塊最多 4,096 個字元（WhatsApp 的實際顯示限制）。你不需要進行任何設定 ——gateway 會處理分割並依序傳送各區塊。

WhatsApp 相容的 Markdown

AI 回覆中的標準 Markdown 會自動轉換為 WhatsApp 的原生格式：

程式碼區塊和行內程式碼會原樣保留，因為 WhatsApp 原生支援三反引號格式。

工具執行進度

當 agent 呼叫工具（網路搜尋、檔案操作等）時，WhatsApp 會顯示即時進度指示器，顯示目前正在執行哪個工具。此功能預設啟用 ——無需設定。

訊息批次（防抖動）

WhatsApp 會逐一傳送每個訊息，因此一連串快速的訊息（轉發的批次、貼上分割的內容、多行文字）會導致每個片段觸發一次獨立的 agent 呼叫 ——造成 token 浪費並產生多個不連貫的回覆。適配器會緩衝來自同一個聊天室的連續文字訊息，並在短暫的安靜期後作為一個合併的請求送出（預設 5 秒，對於接近分割閾值的超長片段會延長至 10 秒）。可透過 config.yaml 調整：

# ~/.hermes/config.yaml
gateway:
  platforms:
    whatsapp:
      extra:
        text_batch_delay_seconds: 5.0         # quiet period before flushing a batch
        text_batch_split_delay_seconds: 10.0  # extended delay near the split threshold

設定 text_batch_delay_seconds: 0 可立即送出每條訊息（停用批次處理）。

---

疑難排解

---

安全性

警告

在上線前設定存取控制。 設定 WHATSAPP_ALLOWED_USERS 並指定具體的電話號碼 （含國碼、不含 +），使用 * 允許所有人，或設定 WHATSAPP_ALLOW_ALL_USERS=true。如果都沒有設定，gateway 會作為安全措施 拒絕所有傳入訊息。

預設情況下，未授權的 DM 仍會收到配對碼回覆。如果你希望一個私密的 WhatsApp 號碼對陌生人完全保持靜默，請設定：

whatsapp:
  unauthorized_dm_behavior: ignore

• ~/.hermes/platforms/whatsapp/session 目錄包含完整的 session 憑證 ——請像保護密碼一樣保護它
• 設定檔案權限：chmod 700 ~/.hermes/platforms/whatsapp/session
• 使用專用的電話號碼作為機器人，以將風險與你的個人帳號隔離
• 如果你懷疑遭到入侵，請在 WhatsApp → 設定 → 已連結的裝置中取消裝置的連結
• 日誌中的電話號碼會被部分遮蔽，但請檢視你的日誌保留策略

---

---

Signal