SMS の設定（Twilio）
目次
Hermes は Twilio の API を通して SMS につながります。相手が Twilio の電話番号にショートメッセージを送ると、AI からの返事がそのまま返ってきます。Telegram や Discord と同じ会話体験を、ふつうのショートメッセージの上で味わえるということです。
前提条件
- Twilio アカウント — twilio.com で登録します（無料トライアルあり）
- SMS を扱える Twilio の電話番号
- 外部から到達できるサーバー — SMS が届いたとき、Twilio はあなたのサーバーへ webhook を送ります
- aiohttp —
cd ~/.hermes/hermes-agent && uv pip install -e ".[sms]"でインストールします
ステップ 1: Twilio の認証情報を取得する
- Twilio コンソールを開きます
- ダッシュボードから Account SID と Auth Token をコピーします
- 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 コンソールで次のように操作します。
- Phone Numbers → Manage → Active Numbers を開きます
- 対象の電話番号をクリックします
- Messaging → A MESSAGE COMES IN で次を設定します
- Webhook:
https://your-server:8080/webhooks/twilio - HTTP Method:
POST
Twilio に設定したものと同じ URL を SMS_WEBHOOK_URL にも指定してください。 Twilio の署名検証に必要なので、これがないとアダプターは起動を拒否します。
# Must match the webhook URL in your Twilio Console
SMS_WEBHOOK_URL=https://your-server:8080/webhooks/twiliowebhook のポートは既定で 8080 です。変えたいときは次のように指定します。
SMS_WEBHOOK_PORT=3000ステップ 4: ゲートウェイを起動する
hermes gateway次のような表示が出れば起動できています。
[sms] Twilio webhook server listening on 127.0.0.1:8080, from: +1555***4567Refusing to start: SMS_WEBHOOK_URL is required と出た場合は、Twilio コンソールに設定した公開 URL を SMS_WEBHOOK_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 コンソールの 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 ならではの挙動
- プレーンテキストのみ — SMS では Markdown が記号のまま表示されてしまうため、自動的に取り除かれます
- 1600 文字の上限 — それより長い返答は、改行、次に空白といった自然な区切りで複数のメッセージに分割されます
- エコー防止 — 自分の Twilio 番号から届いたメッセージは無視され、返信の無限ループを防ぎます
- 電話番号の伏せ字化 — プライバシー保護のため、ログ上の電話番号は伏せられます
セキュリティ
webhook の署名検証
Hermes は X-Twilio-Signature ヘッダー（HMAC-SHA1）を検証し、届いた webhook が本当に Twilio から来たものかを確かめます。これにより、攻撃者が偽のメッセージを流し込むのを防げます。
SMS_WEBHOOK_URL は必須です。 Twilio コンソールに設定した公開 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困ったときは
メッセージが届かない
- Twilio の webhook URL が正しく、外部から到達できるか確かめます
TWILIO_ACCOUNT_SIDとTWILIO_AUTH_TOKENが正しいか確かめます- Twilio コンソールの Monitor → Logs → Messaging で配信エラーが出ていないか見ます
- 自分の電話番号が
SMS_ALLOWED_USERSに入っているか（またはSMS_ALLOW_ALL_USERS=trueか）確かめます
返信が送られない
TWILIO_PHONE_NUMBERが正しく設定されているか確かめます（+付きの E.164 形式）- Twilio アカウントに SMS 対応の番号があるか確かめます
- Hermes ゲートウェイのログに Twilio API のエラーが出ていないか見ます
webhook のポートがぶつかる
ポート 8080 がすでに使われている場合は、別のポートに変えます。
SMS_WEBHOOK_PORT=3001Twilio コンソール側の webhook URL も、同じポートに合わせて更新してください。