跳到主要內容

SMS 設置（Twilio）

Hermes 通過 Twilio API 連接短信服務。用戶向你的 Twilio 電話號碼發送短信，即可收到 AI 回覆 —— 與 Telegram 或 Discord 相同的對話體驗，但通過標準短信實現。

共享憑證

SMS 網關與可選的 電話技能 共享憑證。如果你已為語音通話或一次性短信配置了 Twilio，網關可使用相同的 TWILIO_ACCOUNT_SID、TWILIO_AUTH_TOKEN 和 TWILIO_PHONE_NUMBER。

先決條件​

  • Twilio 賬戶 — 在 twilio.com 註冊（提供免費試用）
  • 一個具備短信功能的 Twilio 電話號碼
  • 一個公網可訪問的服務器 — Twilio 在收到短信時會向你的服務器發送 Webhook
  • aiohttp — pip install 'hermes-agent[sms]'

第一步：獲取你的 Twilio 憑證​

  1. 訪問 Twilio 控制檯
  2. 從儀表板複製你的 Account SID 和 Auth Token
  3. 進入 Phone Numbers → Manage → Active Numbers — 注意你的電話號碼的 E.164 格式（例如：+15551234567）

第二步：配置 Hermes​

hermes gateway setup

從平臺列表中選擇 SMS (Twilio)。嚮導將提示你輸入憑證。

手動設置​

將以下內容添加到 ~/.hermes/.env：

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+15551234567

# 安全性：僅限特定電話號碼（推薦）
SMS_ALLOWED_USERS=+15559876543,+15551112222

# 可選：設置 cron 作業交付的主通道
SMS_HOME_CHANNEL=+15559876543

第三步：配置 Twilio Webhook​

Twilio 需要知道在收到短信時應發送到何處。在 Twilio 控制檯 中：

  1. 進入 Phone Numbers → Manage → Active Numbers
  2. 點擊你的電話號碼
  3. 在 Messaging → A MESSAGE COMES IN 下設置：
    • Webhook: https://your-server:8080/webhooks/twilio
    • HTTP Method: POST
暴露你的 Webhook

如果你在本地運行 Hermes，請使用隧道工具暴露 Webhook：

# 使用 cloudflared
cloudflared tunnel --url http://localhost:8080

# 使用ngrok
ngrok http 8080

將生成的公共 URL 設置為你的 Twilio Webhook。

Webhook 端口默認為 8080。可通過以下方式覆蓋：

SMS_WEBHOOK_PORT=3000

第四步：啟動網關​

hermes gateway

你應該會看到：

[sms] Twilio webhook server listening on port 8080, from: +1555***4567

向你的 Twilio 號碼發送短信 —— Hermes 將通過短信回覆。

環境變量​

變量是否必需描述
TWILIO_ACCOUNT_SID是Twilio 賬戶 SID（以 AC 開頭）
TWILIO_AUTH_TOKEN是Twilio 認證令牌
TWILIO_PHONE_NUMBER是你的 Twilio 電話號碼（E.164 格式）
SMS_WEBHOOK_PORT否Webhook 監聽端口（默認：8080）
SMS_ALLOWED_USERS否允許聊天的 E.164 格式電話號碼，用逗號分隔
SMS_ALLOW_ALL_USERS否設置為 true 以允許所有人（不推薦）
SMS_HOME_CHANNEL否定時任務 / 通知投遞的電話號碼
SMS_HOME_CHANNEL_NAME否主頻道的顯示名稱（默認：Home）

SMS 特定行為​

  • 僅支持純文本 —— Markdown 會自動被移除，因為 SMS 會將其渲染為原始字符
  • 1600 字符限制 —— 更長的回覆會在自然邊界（換行符，然後是空格）處拆分為多條消息
  • 防止回聲 —— 來自你自己的 Twilio 號碼的消息會被忽略，以防止循環
  • 電話號碼脫敏 —— 為保護隱私，日誌中會脫敏電話號碼

安全性​

網關默認拒絕所有用戶。 請配置允許列表：

# 建議：限制特定電話號碼
SMS_ALLOWED_USERS=+15559876543,+15551112222

# 或者允許全部（對於具有終端訪問權限的機器人，建議使用 NOT）
SMS_ALLOW_ALL_USERS=true
注意

SMS 無內置加密。除非你瞭解安全影響，否則不要用於敏感操作。對於敏感場景，建議使用 Signal 或 Telegram。

故障排除​

消息未到達​

  1. 檢查你的 Twilio Webhook URL 是否正確且公網可訪問
  2. 確認 TWILIO_ACCOUNT_SID 和 TWILIO_AUTH_TOKEN 是否正確
  3. 在 Twilio 控制檯 → Monitor → Logs → Messaging 中檢查交付錯誤
  4. 確保你的電話號碼在 SMS_ALLOWED_USERS 中（或設置 SMS_ALLOW_ALL_USERS=true）

回覆未發送​

  1. 檢查 TWILIO_PHONE_NUMBER 是否正確設置（E.164 格式，帶 +）
  2. 確認你的 Twilio 賬戶擁有短信功能的號碼
  3. 檢查 Hermes 網關日誌中是否存在 Twilio API 錯誤

Webhook 端口衝突​

如果端口 8080 已被佔用，請更改端口：

SMS_WEBHOOK_PORT=3001

並在 Twilio 控制檯中更新 Webhook URL 以匹配新端口。