跳到主要內容

WhatsApp 設置

Hermes 通過基於 Baileys 的內置橋接器連接 WhatsApp。該方式通過模擬 WhatsApp Web 會話實現——並非通過官方的 WhatsApp Business API。無需 Meta 開發者賬號或商業驗證。

非官方 API —— 賬號封禁風險

WhatsApp 不官方支持除 Business API 之外的第三方機器人。使用第三方橋接器存在一定的賬號限制風險。為降低風險，請：

  • 使用專用手機號碼作為機器人（不要使用你的個人號碼）
  • 不要發送批量/垃圾消息——保持使用場景為對話式交流
  • 不要自動向未主動發消息的人發送消息
WhatsApp Web 協議更新

WhatsApp 會定期更新其 Web 協議，這可能導致第三方橋接器暫時不兼容。發生這種情況時，Hermes 將更新橋接依賴。如果在 WhatsApp 更新後機器人無法工作，請拉取最新版 Hermes 並重新配對。

兩種模式​

模式工作方式適用場景
獨立機器人號碼（推薦）為機器人專用一個手機號碼。用戶直接向該號碼發送消息。清晰的用戶體驗、多用戶支持、更低的封禁風險
個人自聊模式使用你自己的 WhatsApp。通過給自己發消息與 Agent 交互。快速設置、單用戶、測試用途

前提條件​

  • Node.js v18+ 和 npm —— WhatsApp 橋接器以 Node.js 進程運行
  • 一部安裝了 WhatsApp 的手機（用於掃描二維碼）

與舊版基於瀏覽器的橋接器不同，當前基於 Baileys 的橋接器 不需要本地 Chromium 或 Puppeteer 依賴棧。

第一步：運行設置嚮導​

hermes whatsapp

嚮導將執行以下操作：

  1. 詢問你希望使用的模式（bot 或 self-chat）
  2. 如需，安裝橋接依賴
  3. 在終端中顯示一個 二維碼
  4. 等待你掃描

掃描二維碼的方法：

  1. 在手機上打開 WhatsApp
  2. 進入 設置 → 已連接的設備
  3. 點擊 連接設備
  4. 將攝像頭對準終端中的二維碼

配對成功後，嚮導會確認連接並退出。你的會話將自動保存。

提示

如果二維碼顯示混亂，請確保你的終端寬度至少為 60 列，並支持 Unicode。你也可以嘗試使用其他終端模擬器。

第二步：獲取第二個手機號碼（機器人模式）​

在機器人模式下，你需要一個尚未在 WhatsApp 上註冊的手機號碼。有三種選擇：

選項成本說明
Google Voice免費僅限美國地區。訪問 voice.google.com 獲取號碼。通過 Google Voice 應用接收短信完成 WhatsApp 驗證。
預付費 SIM 卡一次性 5–15 美元任意運營商。激活後，驗證 WhatsApp，之後 SIM 卡可存放於抽屜中。號碼必須保持活躍（每 90 天打一次電話）。
VoIP 服務免費–每月 5 美元TextNow、TextFree 等。部分 VoIP 號碼被 WhatsApp 屏蔽——若首個號碼無效，可嘗試其他號碼。

獲取號碼後：

  1. 在手機上安裝 WhatsApp（或使用雙卡版 WhatsApp Business 應用）
  2. 使用新號碼註冊 WhatsApp
  3. 運行 hermes whatsapp 並從該 WhatsApp 賬號掃描二維碼

第三步：配置 Hermes​

將以下內容添加到你的 ~/.hermes/.env 文件中：

# 必填
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot                          # “0”或“1”

# 訪問控制 — 從以下選項中選擇 ONE：
WHATSAPP_ALLOWED_USERS=15551234567         # 以逗號分隔的電話號碼（帶國家/地區代碼，無 +）
# WHATSAPP_ALLOWED_USERS=* # 或使用 * 允許所有人
# WHATSAPP_ALLOW_ALL_USERS=true # 或者設置此標誌（與 * 效果相同）
允許所有用戶的簡寫

設置 WHATSAPP_ALLOWED_USERS=* 可允許 所有 發送者（等同於 WHATSAPP_ALLOW_ALL_USERS=true）。這與 Signal 群組允許列表 保持一致。若想使用配對流程，請移除這兩個變量，並依賴 私信配對系統。

可選的行為設置項，位於 ~/.hermes/config.yaml 中：

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore
  • unauthorized_dm_behavior: pair 是全局默認值。未知私信發送者將收到配對碼。
  • whatsapp.unauthorized_dm_behavior: ignore 會使 WhatsApp 對未經授權的私信保持靜默，對於私有號碼而言通常是更優選擇。

然後啟動網關：

hermes gateway              # 前景
hermes gateway install      # 安裝為用戶服務
sudo hermes gateway install --system   # 僅限 Linux：啟動時系統服務

網關將自動使用已保存的會話啟動 WhatsApp 橋接器。

會話持久化​

Baileys 橋接器將會話數據保存在 ~/.hermes/platforms/whatsapp/session 目錄下。這意味著：

  • 會話在重啟後依然有效——你無需每次重啟都重新掃描二維碼
  • 會話數據包含加密密鑰和設備憑證
  • 切勿共享或提交此會話目錄——它將賦予對 WhatsApp 賬號的完全訪問權限

重新配對​

如果會話中斷（手機重置、WhatsApp 更新、手動解除綁定），你將在網關日誌中看到連接錯誤。修復方法如下：

hermes whatsapp

這將生成一個新的二維碼。再次掃描後，會話將重新建立。網關會自動處理 臨時 斷開連接（網絡波動、手機短暫離線）的情況，具備重連邏輯。

語音消息​

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: ""                          # 空字符串禁用標題
  # reply_prefix: "🤖 *My Bot*\n──────\n" # 自定義前綴（支持換行符 \n）

故障排除​

問題解決方案
二維碼無法掃描確保終端寬度足夠（至少 60 列）。嘗試使用其他終端。確認您正在掃描正確的 WhatsApp 賬號（機器人號碼，而非個人賬號）。
二維碼過期二維碼每約 20 秒刷新一次。如果超時，請重啟 hermes whatsapp。
會話無法持久化檢查 ~/.hermes/platforms/whatsapp/session 是否存在且可寫。若容器化部署，請將其掛載為持久化卷。
意外登出WhatsApp 在長時間無活動後會解除設備綁定。請保持手機開機並連接網絡，如需可重新使用 hermes whatsapp 配對。
網關崩潰或陷入重連循環重啟網關，更新 Hermes，並在會話因 WhatsApp 協議變更被無效化時重新配對。
WhatsApp 更新後機器人停止工作更新 Hermes 以獲取最新網橋版本，然後重新配對。
macOS：提示“未安裝 Node.js”但終端中 node 可用launchd 服務不會繼承您的 shell PATH。運行 hermes gateway install 以將當前 PATH 重新快照到 plist 文件中，然後運行 hermes gateway start。詳情請參見 網關服務文檔。
消息未被接收確認 WHATSAPP_ALLOWED_USERS 包含發送者號碼（含國家代碼，不帶 + 或空格），或設置為 * 以允許所有人。在 .env 中設置 WHATSAPP_DEBUG=true 並重啟網關，可在 bridge.log 中查看原始消息事件。
機器人向陌生人回覆配對碼若希望未授權的私信被靜默忽略，請在 ~/.hermes/config.yaml 中設置 whatsapp.unauthorized_dm_behavior: ignore。

安全性​

注意

上線前請配置訪問控制。通過設置 WHATSAPP_ALLOWED_USERS 並指定具體電話號碼（含國家代碼，不含 +），使用 * 允許所有人，或設置 WHATSAPP_ALLOW_ALL_USERS=true。若未設置以上任一選項，網關將拒絕所有入站消息，作為安全措施。

默認情況下，未授權的私信仍會收到配對碼回覆。若希望私有 WhatsApp 號碼對陌生人完全靜默，可設置：

whatsapp:
  unauthorized_dm_behavior: ignore
  • ~/.hermes/platforms/whatsapp/session 目錄包含完整的會話憑據，請像保護密碼一樣保護它
  • 設置文件權限：chmod 700 ~/.hermes/platforms/whatsapp/session
  • 使用專用電話號碼作為機器人，以隔離與個人賬號的風險
  • 若懷疑憑證洩露，請在 WhatsApp 中解綁設備 → 設置 → 已鏈接設備
  • 日誌中的電話號碼已部分脫敏，但仍需審查您的日誌保留策略