SMS

OpenClaw 透過 Twilio 電話號碼或 Messaging Service 接收及傳送 SMS。閘道會註冊傳入網路鉤子路由（預設為 /webhooks/sms）、預設驗證 Twilio 請求簽章，並透過 Twilio 的 Messages API 傳回回覆。

狀態：官方外掛，需另行安裝。僅支援文字：不支援 MMS／媒體，且僅支援私訊。

開始之前

你需要：

• 使用 openclaw plugins install @openclaw/sms 安裝官方 SMS 外掛。
• 擁有包含支援 SMS 電話號碼的 Twilio 帳戶，或 Twilio Messaging Service。
• Twilio Account SID 與 Auth Token。
• 可連線至 OpenClaw 閘道的公用 HTTPS URL。
• 選擇傳送者政策：私人使用採用 pairing（預設）、預先核准的電話號碼採用 allowlist，只有刻意公開 SMS 存取時才採用 open。

如果同一個 Twilio 號碼同時具備兩種功能，便可同時用於 SMS 與語音通話。SMS 網路鉤子與語音網路鉤子須在 Twilio 中分別設定，並使用不同的閘道路徑；本頁僅涵蓋 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 之下（每個帳戶則位於 channels.sms.accounts.<id> 之下）：

設定檔

如果希望頻道定義隨閘道設定一併移轉，請使用設定檔方式：

{  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"）。當閘道應從 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",    },  },}

閘道執行階段必須能存取所參照的環境變數或密鑰提供者。變更主機環境變數後，請重新啟動受管理的閘道程序。

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

如果解析設定與環境變數後同時存在 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 會拒絕所有傳送者（閘道會記錄啟動警告）。
• open：設定驗證要求 allowFrom 包含 "*"。若沒有萬用字元，只有列出的號碼可以聊天。
• disabled：捨棄所有傳入私訊。

allowFrom 項目應為 E.164 電話號碼，例如 +15551234567。系統接受並會正規化 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 傳送：

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

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

代理程式對傳入 SMS 對話的回覆，會自動透過已設定的 Twilio 傳送者傳回給原傳送者。

SMS 輸出為純文字。OpenClaw 會移除 Markdown 格式、攤平圍欄程式碼區塊、將連結改寫為 label (url)，並在透過 Twilio 傳送前，將較長的回覆分割成每段最多 textChunkLimit 個字元（預設為 1500）。

驗證設定

閘道啟動後：

1. 確認閘道日誌顯示 SMS 網路鉤子路由。
2. 執行 Twilio 端探測（檢查已設定的 Twilio 網路鉤子 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

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

網路鉤子安全性

OpenClaw 預設會使用 publicWebhookUrl 和 authToken 驗證 X-Twilio-Signature。請確保 publicWebhookUrl 的端點部分與 Twilio 中設定的 URL 逐位元組一致，包括通訊協定、主機、路徑和查詢字串。依 Twilio 要求，OpenClaw 會在簽章計算時排除 Twilio 的連線覆寫片段（#...）。

網路鉤子路由還會獨立於簽章驗證，強制執行以下規則：

• 僅允許 POST。
• 每個來源 IP 每分鐘最多 30 個請求（超過時回傳 HTTP 429）。
• 承載資料中的 AccountSid 必須與設定的 accountSid 相符（否則回傳 HTTP 403）。
• 重複使用的 MessageSid 值會在 10 分鐘內進行去重。
• 每個 SMS 帳戶的重播快取最多保留 10,000 個仍有效的訊息 SID。當所有位置都仍有效時，該帳戶的新網路鉤子會採取封閉式失敗，回傳 HTTP 429 與 Retry-After 標頭，直到最舊的位置到期。
• 超過 32 KB 的請求主體會遭拒絕。

Twilio 預設不會重試 HTTP 429，也未記載支援 Retry-After。#rp=4xx 和 #rp=all 連線覆寫可啟用 4xx 重試，但 Twilio 將完整重試交易限制在 15 秒內，因此重試仍可能在重播快取位置到期前結束。若其他處理常式必須接收傳遞失敗的項目，請設定備援 URL；應將 429 視為封閉式失敗拒絕，而非可靠的背壓機制。

僅限本機通道測試時，可以設定：

{  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_*／SMS_* 環境變數備援僅適用於預設帳戶；設定 defaultAccount 可變更預設帳戶。

疑難排解

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

請確認 publicWebhookUrl 與 Twilio 中設定的 URL 完全相符，包括通訊協定、主機、路徑和查詢字串。Twilio 會對公開 URL 字串簽章，因此 Proxy 重寫和替代主機名稱可能破壞簽章驗證。

出現包含 Invalid account 的 403，表示傳入承載資料的 AccountSid 與設定的 accountSid 不符；請確認網路鉤子指向擁有該號碼的帳戶。

未出現配對請求

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

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

• Twilio 的 Messaging > A message comes in 指向 publicWebhookUrl。
• 方法為 POST。
• 通道或反向 Proxy 公開了完全一致的 webhookPath；若使用 Tailscale Funnel，請執行 tailscale funnel status，並確認列出了 /webhooks/sms。
• publicWebhookUrl 使用與 Twilio 傳送時相同的通訊協定、主機、路徑和查詢字串，以便簽章驗證重現已簽章的 URL。

openclaw channels status --channel sms --probe 會顯示 Twilio 網路鉤子設定不符及近期的 11200 錯誤。

傳出訊息失敗

確認已解析 accountSid、authToken，以及 fromNumber 或 messagingServiceSid。如果使用 Twilio 試用帳戶，可能必須先在 Twilio 中驗證目的地號碼，才能傳送 SMS。

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

檢查 dmPolicy 和 allowFrom。使用預設的 pairing 原則時，必須先核准傳送者，才會處理一般的代理程式回合。