Skip to main content
OpenClaw 透過 Twilio 電話號碼或 Messaging Service 接收與傳送 SMS。閘道會註冊傳入網路鉤子路由（預設為 /webhooks/sms）、預設驗證 Twilio 請求簽章，並透過 Twilio 的 Messages API 回送回覆。 狀態：官方外掛，需另行安裝。僅文字：不支援 MMS/媒體，僅支援直接訊息。

配對

SMS 的預設私訊政策是配對。

閘道安全性

檢閱網路鉤子暴露範圍與寄件者存取控制。

頻道疑難排解

跨頻道診斷與修復手冊。

​
開始之前

你需要：
  • 已使用 openclaw plugins install @openclaw/sms 安裝官方 SMS 外掛。
  • 具備可用於 SMS 的電話號碼，或 Twilio Messaging Service 的 Twilio 帳戶。
  • Twilio Account SID 與 Auth Token。
  • 可連到你的 OpenClaw 閘道的公開 HTTPS URL。
  • 寄件者政策選擇：pairing（預設）用於私人使用、allowlist 用於預先核准的電話號碼，或僅在刻意公開 SMS 存取時使用 open。
只要同時具備兩種能力，一個 Twilio 號碼可同時服務 SMS 和 語音通話。SMS 網路鉤子與語音網路鉤子會在 Twilio 中分別設定，並使用不同的閘道路徑；本頁僅涵蓋 SMS 網路鉤子。

​
快速設定

1

安裝外掛

openclaw plugins install @openclaw/sms
2

建立或選擇 Twilio 寄件者

在 Twilio 中開啟 Phone Numbers > Manage > Active numbers，並選擇可用於 SMS 的號碼。儲存：
  • Account SID，例如 ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Auth Token
  • 寄件者電話號碼，例如 +15551234567
如果你使用 Messaging Service 而不是固定寄件者號碼，請儲存 Messaging Service SID，例如 MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx。
3

設定 SMS 頻道

將此儲存為 sms.patch.json5 並變更預留位置：
{
  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-run
openclaw config patch --file ./sms.patch.json5
4

將 Twilio 指向閘道網路鉤子

在 Twilio 電話號碼設定中，開啟 Messaging 並將 A message comes in 設為：
https://gateway.example.com/webhooks/sms
使用 HTTP POST。預設本機路徑是 /webhooks/sms；如果你需要不同路由，請變更 channels.sms.webhookPath。
5

暴露確切的 SMS 網路鉤子路徑

你的公開 URL 必須將 SMS 路徑路由到閘道程序（預設連接埠 18789）。如果你使用 Tailscale Funnel 進行本機測試，請明確暴露 /webhooks/sms：
tailscale funnel --bg --set-path /webhooks/sms http://127.0.0.1:<gateway-port>/webhooks/sms
tailscale funnel status
語音通話和 SMS 使用不同的網路鉤子路徑。如果同一個 Twilio 號碼同時處理兩者，請在 Twilio 和你的通道中保持兩個路由皆已設定。
6

啟動閘道並核准第一位寄件者

openclaw gateway
傳送文字訊息到 Twilio 號碼。第一則訊息會建立配對請求。核准它：
openclaw pairing list sms
openclaw pairing approve sms <CODE>
配對碼會在 1 小時後過期。

​
設定範例

所有鍵都位於 channels.sms 下（每個帳戶則位於 channels.sms.accounts.<id> 下）：
鍵預設用途
enabledtrue啟用或停用頻道/帳戶。
accountSid—Twilio Account SID (AC...)。
authToken—Twilio Auth Token；純文字字串或 SecretRef。
fromNumber—E.164 寄件者號碼。
messagingServiceSid—未解析出 fromNumber 時使用的 Messaging Service SID (MG...)。
defaultTo—傳送流程省略明確目標時的預設目的地。
webhookPath/webhooks/sms用於傳入 Twilio 網路鉤子的閘道 HTTP 路徑。
publicWebhookUrl—在 Twilio 中設定的公開 URL；簽章驗證需要它。
dangerouslyDisableSignatureValidationfalse略過 X-Twilio-Signature 檢查；僅限本機通道測試。
dmPolicy"pairing"pairing、allowlist、open 或 disabled。
allowFrom[]E.164 中允許的寄件者號碼，或搭配 dmPolicy: "open" 的 "*"。
textChunkLimit1500每個外送 SMS 分段的最大字元數。
accounts, defaultAccount—多帳戶對應表與預設帳戶 ID。

​
設定檔

當你希望頻道定義隨閘道設定一起保存時，請使用設定檔設定： 
{
  channels: {
    sms: {
      enabled: true,
      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      authToken: "twilio-auth-token",
      fromNumber: "+15551234567",
      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
      dmPolicy: "pairing",
    },
  },
}

​
環境變數

環境變數只套用於預設帳戶；設定值優先於環境變數值。
變數對應至
TWILIO_ACCOUNT_SIDaccountSid
TWILIO_AUTH_TOKENauthToken
TWILIO_PHONE_NUMBER（別名 TWILIO_SMS_FROM）fromNumber
TWILIO_MESSAGING_SERVICE_SIDmessagingServiceSid
SMS_PUBLIC_WEBHOOK_URLpublicWebhookUrl
SMS_WEBHOOK_PATHwebhookPath
SMS_ALLOWED_USERSallowFrom（逗號分隔）
SMS_TEXT_CHUNK_LIMITtextChunkLimit
SMS_DANGEROUSLY_DISABLE_SIGNATURE_VALIDATIONdangerouslyDisableSignatureValidation ("true")
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 sms
openclaw channels status --channel sms --probe --json
  1. 從你的手機傳送一則 SMS 到 Twilio 號碼。
  2. 執行 openclaw pairing list sms。
  3. 使用 openclaw pairing approve sms <CODE> 核准配對碼。
  4. 再傳送一則 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)" --json
openclaw pairing list sms
openclaw 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。 網路鉤子路由也會強制執行以下規則，且不受簽章驗證影響：
  • 僅限 POST。
  • 每個來源 IP 每分鐘 30 個請求的速率限制（超過則 HTTP 429）。
  • 負載中的 AccountSid 必須符合已設定的 accountSid（否則 HTTP 403）。
  • 重播的 MessageSid 值會在 10 分鐘內去重。
  • 超過 32 KB 的請求本文會被拒絕。
僅限本機通道測試時，你可以設定： 
{
  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 完全相符，包括 scheme、host、path 與 query string。Twilio 會簽署公開 URL 字串，因此代理重寫與替代主機名稱可能會破壞簽章驗證。 帶有 Invalid account 的 403 表示傳入負載的 AccountSid 與已設定的 accountSid 不符；請檢查網路鉤子是否指向擁有該號碼的帳戶。

​
沒有出現配對請求

檢查 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。
openclaw channels status --channel sms --probe 會顯示不相符的 Twilio 網路鉤子設定與近期的 11200 錯誤。

​
傳出傳送失敗

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

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

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