H繁中版
文件user-guidesms
<!-- Source: https://hermesbible.com/docs/user-guide/messaging/sms -->

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

SMS 設定（Twilio）

Hermes 透過 Twilio API 連接 SMS。使用者傳送訊息到你的 Twilio 電話號碼，就能收到 AI 回覆——與 Telegram 或 Discord 相同的對話體驗，只是透過一般簡訊進行。

INFO — 共用憑證

SMS 閘道器與選用的 telephony skill 共用憑證。如果你已經為語音通話或一次性 SMS 設定過 Twilio，閘道器會使用相同的 TWILIO_ACCOUNT_SID、TWILIO_AUTH_TOKEN 和 TWILIO_PHONE_NUMBER。

前置需求

  • Twilio 帳號 — 在 twilio.com 註冊（提供免費試用）
  • 一支支援 SMS 的 Twilio 電話號碼
  • 一台公開可存取的伺服器 — Twilio 會在收到 SMS 時向你的伺服器傳送 webhook
  • aiohttp — pip install 'hermes-agent[sms]'

步驟 1：取得你的 Twilio 憑證

  1. 前往 Twilio Console
  2. 從儀表板複製你的 Account SID 和 Auth Token
  3. 前往 Phone Numbers → Manage → Active Numbers — 記下你的電話號碼（E.164 格式，例如 +15551234567）

步驟 2：設定 Hermes

互動式設定（建議）

hermes gateway setup

從平台清單中選擇 SMS (Twilio)。設定精靈會提示你輸入憑證。

手動設定

在 ~/.hermes/.env 中新增：

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+15551234567

# Security: restrict to specific phone numbers (recommended)
SMS_ALLOWED_USERS=+15559876543,+15551112222

# Optional: set a home channel for cron job delivery
SMS_HOME_CHANNEL=+15559876543

步驟 3：設定 Twilio Webhook

Twilio 需要知道將傳入的訊息送往何處。在 Twilio Console 中：

  1. 前往 Phone Numbers → Manage → Active Numbers
  2. 點選你的電話號碼
  3. 在 Messaging → A MESSAGE COMES IN 下設定：
    • Webhook：https://your-server:8080/webhooks/twilio
    • HTTP Method：POST

TIP — 公開你的 Webhook

如果你在本機運行 Hermes，可以使用隧道工具公開 webhook：

# Using cloudflared
cloudflared tunnel --url http://localhost:8080

# Using ngrok
ngrok http 8080

將產生的公開 URL 設定為你的 Twilio webhook。

將 SMS_WEBHOOK_URL 設定為你在 Twilio 中設定的相同 URL。 這是 Twilio 簽章驗證所必需的——沒有設定的話適配器將拒絕啟動：

# Must match the webhook URL in your Twilio Console
SMS_WEBHOOK_URL=https://your-server:8080/webhooks/twilio

Webhook 預設使用 8080 埠。可透過以下方式變更：

SMS_WEBHOOK_PORT=3000

步驟 4：啟動閘道器

hermes gateway

你應該會看到：

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

如果看到 Refusing to start: SMS_WEBHOOK_URL is required，請將 SMS_WEBHOOK_URL 設定為你在 Twilio Console 中設定的公開 URL（參閱步驟 3）。

向你的 Twilio 號碼傳送訊息——Hermes 會透過 SMS 回覆。

環境變數

變數必要說明
TWILIO_ACCOUNT_SID是Twilio Account SID（以 AC 開頭）
TWILIO_AUTH_TOKEN是Twilio Auth Token（也用於 webhook 簽章驗證）
TWILIO_PHONE_NUMBER是你的 Twilio 電話號碼（E.164 格式）
SMS_WEBHOOK_URL是用於 Twilio 簽章驗證的公開 URL——必須與 Twilio Console 中的 webhook URL 一致
SMS_WEBHOOK_PORT否Webhook 監聽埠（預設：8080）
SMS_WEBHOOK_HOST否Webhook 繫結位址（預設：127.0.0.1）
SMS_INSECURE_NO_SIGNATURE否設為 true 可停用簽章驗證（僅限本機開發——不適用於正式環境）
SMS_ALLOWED_USERS否允許對話的電話號碼（逗號分隔，E.164 格式）
SMS_ALLOW_ALL_USERS否設為 true 允許所有人使用（不建議）
SMS_HOME_CHANNEL否用於排程任務 / 通知傳送的電話號碼
SMS_HOME_CHANNEL_NAME否主頻道的顯示名稱（預設：Home）

SMS 特殊行為

  • 僅限純文字 — Markdown 會自動移除，因為 SMS 會將其顯示為字面字元
  • 1600 字元上限 — 較長的回覆會在適當的斷點（換行符，然後是空格）分割為多則訊息
  • 迴圈防護 — 忽略來自你自己的 Twilio 號碼的訊息，以防止迴圈
  • 電話號碼遮蔽 — 日誌中的電話號碼會被遮蔽以保護隱私

安全性

Webhook 簽章驗證

Hermes 透過驗證 X-Twilio-Signature 標頭（HMAC-SHA1）來確認傳入的 webhook 確實來自 Twilio。這可以防止攻擊者偽造訊息。

SMS_WEBHOOK_URL 為必要設定。 請將其設為你在 Twilio Console 中設定的公開 URL。沒有設定的話適配器將拒絕啟動。

如果在本機開發且沒有公開 URL，你可以停用驗證：

# Local dev only — NOT for production
SMS_INSECURE_NO_SIGNATURE=true

使用者允許清單

閘道器預設拒絕所有使用者。 請設定允許清單：

# Recommended: restrict to specific phone numbers
SMS_ALLOWED_USERS=+15559876543,+15551112222

# Or allow all (NOT recommended for bots with terminal access)
SMS_ALLOW_ALL_USERS=true

WARNING

SMS 沒有內建加密。除非你了解安全性影響，否則請勿使用 SMS 進行敏感操作。對於敏感使用場景，建議使用 Signal 或 Telegram。

疑難排解

訊息未送達

  1. 檢查你的 Twilio webhook URL 是否正確且公開可存取
  2. 確認 TWILIO_ACCOUNT_SID 和 TWILIO_AUTH_TOKEN 正確無誤
  3. 前往 Twilio Console → Monitor → Logs → Messaging 檢查送達錯誤
  4. 確保你的電話號碼在 SMS_ALLOWED_USERS 中（或設定 SMS_ALLOW_ALL_USERS=true）

回覆未送出

  1. 檢查 TWILIO_PHONE_NUMBER 是否正確設定（E.164 格式，包含 +）
  2. 確認你的 Twilio 帳號擁有支援 SMS 的號碼
  3. 檢查 Hermes 閘道器日誌是否有 Twilio API 錯誤

Webhook 埠衝突

如果 8080 埠已被占用，請變更：

SMS_WEBHOOK_PORT=3001

並在 Twilio Console 中更新 webhook URL 以保持一致。

Matrix

slackteams meetings