SMS

OpenClaw は Twilio の電話番号または Messaging Service を介して SMS を受信および送信します。Gateway は受信用 Webhook ルート（デフォルトは /webhooks/sms）を登録し、デフォルトで Twilio リクエスト署名を検証して、Twilio の Messages API を介して返信を送信します。

ステータス: 公式 Plugin、別途インストール。テキストのみ: MMS/メディアには非対応、ダイレクトメッセージのみ。

始める前に

以下が必要です。

• openclaw plugins install @openclaw/sms で公式 SMS Plugin がインストールされていること。
• SMS 対応の電話番号または Twilio Messaging Service を持つ Twilio アカウント。
• Twilio Account SID と Auth Token。
• OpenClaw Gateway に到達する公開 HTTPS URL。
• 送信者ポリシーの選択: 個人利用には pairing（デフォルト）、事前承認済みの電話番号には allowlist、意図的に公開する SMS アクセスの場合に限り open。

1 つの Twilio 番号が両方の機能に対応していれば、SMS と 音声通話 の両方に使用できます。SMS Webhook と音声 Webhook は Twilio で個別に設定し、それぞれ別の Gateway パスを使用します。このページでは SMS Webhook のみを扱います。

クイックセットアップ

openclaw plugins install @openclaw/sms

{channels: {sms: {  enabled: true,  accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",  authToken: "twilio-auth-token",  fromNumber: "+15551234567",  publicWebhookUrl: "https://gateway.example.com/webhooks/sms",  dmPolicy: "pairing",},},}

openclaw config patch --file ./sms.patch.json5 --dry-runopenclaw config patch --file ./sms.patch.json5

https://gateway.example.com/webhooks/sms

tailscale funnel --bg --set-path /webhooks/sms http://127.0.0.1:<gateway-port>/webhooks/smstailscale funnel status

openclaw gateway

openclaw pairing list smsopenclaw pairing approve sms <CODE>

設定例

すべてのキーは channels.sms 配下（アカウントごとの場合は channels.sms.accounts.<id> 配下）に配置します。

設定ファイル

チャンネル定義を Gateway 設定に含めて管理する場合は、設定ファイルによるセットアップを使用します。

{  channels: {    sms: {      enabled: true,      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",      authToken: "twilio-auth-token",      fromNumber: "+15551234567",      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",      dmPolicy: "pairing",    },  },}

環境変数

環境変数はデフォルトアカウントにのみ適用されます。設定値は環境変数の値より優先されます。

export TWILIO_ACCOUNT_SID="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"export TWILIO_AUTH_TOKEN="<twilio-auth-token>"export TWILIO_PHONE_NUMBER="+15551234567"export SMS_PUBLIC_WEBHOOK_URL="https://gateway.example.com/webhooks/sms"

次に、設定でチャンネルを有効にします。

{  channels: {    sms: {      enabled: true,      dmPolicy: "pairing",    },  },}

SecretRef 認証トークン

authToken には SecretRef（source: "env" | "file" | "exec"）を指定できます。Gateway がプレーンテキストの設定を保存する代わりに、OpenClaw のシークレットランタイムから Twilio Auth Token を解決する必要がある場合に使用します。

{  channels: {    sms: {      enabled: true,      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",      authToken: { source: "env", provider: "default", id: "TWILIO_AUTH_TOKEN" },      fromNumber: "+15551234567",      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",      dmPolicy: "pairing",    },  },}

参照先の環境変数またはシークレットプロバイダーは、Gateway ランタイムから参照できる必要があります。ホストの環境変数を変更した後は、管理対象の Gateway プロセスを再起動します。

Messaging Service の送信元

Twilio が Messaging Service を介して送信元を選択する場合は、fromNumber の代わりに messagingServiceSid を使用します。

{  channels: {    sms: {      enabled: true,      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",      authToken: "twilio-auth-token",      messagingServiceSid: "MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",      dmPolicy: "pairing",    },  },}

設定と環境変数の解決後に fromNumber と messagingServiceSid の両方が存在する場合は、fromNumber が使用されます。

デフォルトの送信先

送信フローで明示的な宛先が省略された場合に、オートメーションまたはエージェント主導の配信でデフォルトの送信先を使用するには、defaultTo を設定します。

{  channels: {    sms: {      enabled: true,      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",      authToken: "twilio-auth-token",      fromNumber: "+15551234567",      defaultTo: "+15557654321",      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",    },  },}

アクセス制御

channels.sms.dmPolicy は SMS のダイレクトアクセスを制御します。

• pairing（デフォルト）: 未知の送信者にはペアリングコードが送られます。openclaw pairing approve sms <CODE> で承認します。
• allowlist: allowFrom に含まれる送信者のみを処理します。allowFrom が空の場合はすべての送信者を拒否します（Gateway は起動時に警告を記録します）。
• open: 設定検証では、allowFrom に "*" が含まれている必要があります。ワイルドカードがなければ、一覧に記載された番号のみがチャットできます。
• disabled: 受信したすべての DM を破棄します。

allowFrom のエントリには、+15551234567 のような E.164 形式の電話番号を使用してください。sms: および twilio-sms: プレフィックスも受け付けられ、正規化されます。個人用アシスタントでは、明示的な電話番号を指定した dmPolicy: "allowlist" を推奨します。

{  channels: {    sms: {      enabled: true,      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",      authToken: "twilio-auth-token",      fromNumber: "+15551234567",      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",      dmPolicy: "allowlist",      allowFrom: ["+15557654321"],    },  },}

SMS の送信

SMS チャンネルが選択されている場合、宛先にはプレフィックスなしの E.164 番号または sms: プレフィックスを使用できます。

openclaw message send --channel sms --target sms:+15551234567 --message "hello"

チャンネルが暗黙的に選択される場合、twilio-sms: プレフィックスを使用すると、sms: サービスプレフィックスを奪うことなくこのチャンネルを選択できます。iMessage は、この sms: サービスプレフィックスを使用して、自身の宛先への通信事業者 SMS 配信を選択します。

openclaw message send --target twilio-sms:+15551234567 --message "hello"

CLI では明示的な --target が必要です。defaultTo は、チャンネル設定から宛先を解決できるオートメーションおよびエージェント主導の配信経路向けです。

受信 SMS 会話に対するエージェントの返信は、設定済みの Twilio 送信元を介して自動的に送信者へ返されます。

SMS の出力はプレーンテキストです。OpenClaw は Markdown を除去し、フェンス付きコードブロックを平坦化し、リンクを label (url) として書き換え、長い返信を最大 textChunkLimit 文字（デフォルトは 1500）のチャンクに分割してから Twilio 経由で送信します。

セットアップの確認

Gateway の起動後:

1. Gateway ログに SMS Webhook ルートが表示されていることを確認します。
2. Twilio 側のプローブを実行します（設定された Twilio Webhook の URL／メソッドと、最近の受信エラーを確認します）。

openclaw channels capabilities --channel smsopenclaw channels status --channel sms --probe --json

3. 自分の電話から Twilio 番号に SMS を送信します。
4. openclaw pairing list sms を実行します。
5. openclaw pairing approve sms <CODE> でペアリングコードを承認します。
6. もう一度 SMS を送信し、エージェントが返信することを確認します。

送信のみをテストする場合は、次を使用します。

openclaw message send --channel sms --target sms:+15557654321 --message "OpenClaw SMS test"

macOS の iMessage／SMS からのエンドツーエンドテスト

「メッセージ」を介して通信事業者の SMS を送信できる Mac では、電話に触れずに imsg を使用して送信側を操作できます。

imsg send --to "+15551234567" --service sms --text "OpenClaw SMS E2E $(date -u +%Y%m%dT%H%M%SZ)" --jsonopenclaw pairing list smsopenclaw pairing approve sms <CODE>imsg send --to "+15551234567" --service sms --text "reply exactly SMS pong" --json

最初のメッセージでペアリング要求が作成されます。2 番目のメッセージでは、Twilio 経由でエージェントからの返信を受信します。

Webhook のセキュリティ

デフォルトでは、OpenClaw は publicWebhookUrl と authToken を使用して X-Twilio-Signature を検証します。publicWebhookUrl のエンドポイント部分は、スキーム、ホスト、パス、クエリ文字列を含め、Twilio に設定された URL とバイト単位で完全に一致させてください。Twilio の要件に従い、OpenClaw は署名の計算から Twilio の接続オーバーライドフラグメント（#...）を除外します。

Webhook ルートでは、署名検証とは独立して次の制約も適用されます。

• POST のみ。
• 送信元 IP ごとに 1 分間 30 リクエストのレート制限（超過時は HTTP 429）。
• ペイロードの AccountSid は、設定された accountSid と一致する必要があります（一致しない場合は HTTP 403）。
• 再送された MessageSid 値は、10 分間重複排除されます。
• 各 SMS アカウントの再送キャッシュには、最大 10,000 件の有効なメッセージ SID が保持されます。すべてのスロットが有効な場合、そのアカウントへの新しい Webhook は、最も古いスロットが期限切れになるまで、HTTP 429 と Retry-After ヘッダーを返してフェイルクローズします。
• 32 KB を超えるリクエスト本文は拒否されます。

Twilio はデフォルトで HTTP 429 を再試行せず、Retry-After のサポートも文書化していません。#rp=4xx と #rp=all の接続オーバーライドを使用すると 4xx の再試行が有効になりますが、Twilio は再試行トランザクション全体を 15 秒に制限しているため、再送キャッシュのスロットが期限切れになる前に再試行が終了する可能性があります。失敗した配信を別のハンドラーで受信する必要がある場合は、フォールバック URL を設定してください。429 は信頼できるバックプレッシャーではなく、フェイルクローズによる拒否として扱ってください。

ローカルトンネルでのテストに限り、次のように設定できます。

{  channels: {    sms: {      dangerouslyDisableSignatureValidation: true,    },  },}

公開 Gateway では署名検証を無効にしないでください。

複数アカウントの設定

複数の Twilio 番号を運用する場合は、accounts を使用します。

{  channels: {    sms: {      accounts: {        support: {          enabled: true,          accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",          authToken: "twilio-auth-token",          fromNumber: "+15551234567",          publicWebhookUrl: "https://gateway.example.com/webhooks/sms/support",          webhookPath: "/webhooks/sms/support",          dmPolicy: "allowlist",          allowFrom: ["+15557654321"],        },      },    },  },}

各アカウントは個別の webhookPath を使用する必要があります。Gateway は、別のアカウントがすでに所有しているパスの Webhook ルート登録を拒否します。TWILIO_*／SMS_* 環境変数によるフォールバックは、デフォルトアカウントにのみ適用されます。対象となるアカウントを変更するには、defaultAccount を設定します。

トラブルシューティング

Twilio が 403 を返す、または OpenClaw が Webhook を拒否する

publicWebhookUrl が、スキーム、ホスト、パス、クエリ文字列を含め、Twilio に設定された URL と完全に一致していることを確認してください。Twilio は公開 URL の文字列に署名するため、プロキシによる書き換えや別のホスト名を使用すると、署名検証が失敗する可能性があります。

Invalid account を伴う 403 は、受信ペイロードの AccountSid が設定された accountSid と一致していないことを示します。Webhook が、その番号を所有するアカウントを参照していることを確認してください。

ペアリング要求が表示されない

Twilio 番号の Messaging Webhook URL とメソッドを確認してください。SMS Webhook URL を参照し、POST を使用する必要があります。また、Gateway に公開インターネットまたはトンネル経由でアクセスできることを確認してください。

Twilio のメッセージログにエラー 11200 が表示される場合、Twilio は受信 SMS を受け付けましたが、Webhook に到達できませんでした。次を確認してください。

• Twilio の Messaging > A message comes in が publicWebhookUrl を参照している。
• メソッドが POST である。
• トンネルまたはリバースプロキシが正確な webhookPath を公開している。Tailscale Funnel の場合は tailscale funnel status を実行し、/webhooks/sms が一覧に表示されていることを確認する。
• 署名検証で署名対象 URL を再現できるように、publicWebhookUrl が Twilio の送信時と同じスキーム、ホスト、パス、クエリ文字列を使用している。

openclaw channels status --channel sms --probe では、Twilio の Webhook 設定の不一致と最近の 11200 エラーの両方が表示されます。

送信に失敗する

accountSid、authToken、および fromNumber または messagingServiceSid のいずれかが解決されていることを確認してください。Twilio のトライアルアカウントを使用している場合、SMS を送信する前に、宛先番号を Twilio で検証する必要がある場合があります。

メッセージは届くが、エージェントが応答しない

dmPolicy と allowFrom を確認してください。デフォルトの pairing ポリシーでは、通常のエージェント処理が実行される前に、送信者を承認する必要があります。