SMS

OpenClaw 可以透過 Twilio 電話號碼或 Messaging Service 接收與傳送 SMS。閘道會註冊入站網路鉤子路由，預設驗證 Twilio 請求簽章，並透過 Twilio 的 Messages API 回傳回覆。

開始之前

你需要：

• 已安裝官方 SMS 外掛，使用 openclaw plugins install @openclaw/sms。
• 具備可使用 SMS 的電話號碼，或 Twilio Messaging Service 的 Twilio 帳戶。
• Twilio Account SID 與 Auth Token。
• 可連到你的 OpenClaw 閘道的公開 HTTPS URL。
• 寄件者政策選擇：私人使用選 pairing、預先核准的電話號碼選 allowlist，或僅在有意開放公開 SMS 存取時選 open。

如果號碼同時具備 SMS 與 Voice Call 功能，SMS 和 Voice Call 可使用同一個 Twilio 號碼。在 Twilio 中分別設定 SMS 網路鉤子與 Voice 網路鉤子；本頁只涵蓋 SMS 網路鉤子。

快速設定

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: {      enabled: true,      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",      authToken: "twilio-auth-token",      fromNumber: "+15551234567",      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",      dmPolicy: "pairing",    },  },}

環境變數

針對密鑰來自主機環境的單帳戶部署，使用 env 設定：

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",    },  },}

TWILIO_SMS_FROM 可作為 TWILIO_PHONE_NUMBER 的別名。當 Twilio 應從 Messaging Service 選擇寄件者時，使用 TWILIO_MESSAGING_SERVICE_SID 取代電話號碼寄件者。

SecretRef 驗證權杖

authToken 可以是 SecretRef。當閘道應從 OpenClaw secrets runtime 解析 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",    },  },}

被參照的環境變數或 secret provider 必須對閘道執行階段可見。變更主機環境變數後，請重新啟動受管理的閘道程序。

僅限允許清單的私人號碼

當只有已知電話號碼應能與代理對話時，使用 allowlist：

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

Messaging Service 寄件者

當 Twilio 應透過 Messaging Service 選擇寄件者時，使用 messagingServiceSid 取代 fromNumber：

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

如果在設定與 env 解析後同時存在 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（預設）
• allowlist（需要 allowFrom 中至少有一個寄件者）
• open（需要 allowFrom 包含 "*"）
• disabled

allowFrom 項目應為 E.164 電話號碼，例如 +15551234567。sms: 前綴會被接受並正規化。對於私人助理，建議使用 dmPolicy: "allowlist" 並明確列出電話號碼。

傳送 SMS

出站 SMS 目標在選定 SMS 頻道時，使用 sms: 服務前綴：

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

當頻道選擇是隱含的，twilio-sms:+15551234567 會選擇此頻道，且不會接管 iMessage 使用的現有頻道所擁有的 sms: 服務前綴。

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

命令列介面需要明確的 --target。defaultTo 適用於可從頻道設定解析目標的自動化與代理主動發送路徑。

來自入站 SMS 對話的代理回覆會透過已設定的 Twilio 寄件者自動傳回寄件者。

SMS 輸出為純文字。OpenClaw 會移除 markdown、展平圍欄式程式碼區塊、保留可讀連結，並在透過 Twilio 傳送前將長回覆分段。

驗證設定

閘道啟動後：

1. 確認閘道日誌顯示 SMS 網路鉤子路由。
2. 執行 Twilio 端探測：

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

3. 從你的手機傳送 SMS 到 Twilio 號碼。
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 進行端對端測試

在可透過 Messages 傳送電信業者 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

第一則訊息應建立配對請求。第二則訊息應透過 Twilio 接收代理回覆。

網路鉤子安全性

OpenClaw 預設會使用 publicWebhookUrl 與 authToken 驗證 X-Twilio-Signature。請讓 publicWebhookUrl 與 Twilio 中設定的 URL 逐位元組一致，包含 scheme、host、path 與 query string。

僅針對本機通道測試，你可以設定：

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

請勿在公開閘道上使用停用的簽章驗證。

多帳戶設定

當你操作多個 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。

疑難排解

Twilio 回傳 403 或 OpenClaw 拒絕網路鉤子

檢查 publicWebhookUrl 是否與 Twilio 中設定的 URL 完全相符，包含 scheme、host、path 與 query string。Twilio 會簽署公開 URL 字串，因此代理重寫與替代主機名稱可能會破壞簽章驗證。

沒有出現配對請求

檢查 Twilio 號碼的 Messaging 網路鉤子 URL 與方法。它必須指向 SMS 網路鉤子 URL 並使用 POST。也請確認閘道可從公開網際網路或透過你的通道連線。

如果 Twilio 訊息日誌顯示錯誤 11200，表示 Twilio 已接受入站 SMS，但無法連到你的網路鉤子。檢查：

• Twilio Messaging > A message comes in 指向 publicWebhookUrl。
• 方法是 POST。
• 通道或反向代理暴露確切的 webhookPath；對於 Tailscale Funnel，執行 tailscale funnel status 並確認列出 /webhooks/sms。
• publicWebhookUrl 使用 Twilio 傳送時相同的 scheme、host、path 與 query string，因此簽章驗證可以重現已簽署的 URL。

出站傳送失敗

確認 accountSid、authToken，以及 fromNumber 或 messagingServiceSid 其中之一已解析。如果你使用 Twilio 試用帳戶，目的地號碼可能需要先在 Twilio 中驗證，才能傳送出站 SMS。

訊息已送達但代理沒有回覆

檢查 dmPolicy 和 allowFrom。使用預設的 pairing 政策時，寄件者必須先獲得核准，才會處理一般的代理程式回合。