SMS

OpenClaw nhận và gửi SMS qua số điện thoại Twilio hoặc Messaging Service. Gateway đăng ký một tuyến Webhook đến (mặc định /webhooks/sms), mặc định xác thực chữ ký yêu cầu Twilio và gửi phản hồi trở lại qua Messages API của Twilio.

Trạng thái: Plugin chính thức, được cài đặt riêng. Chỉ hỗ trợ văn bản: không hỗ trợ MMS/phương tiện, chỉ hỗ trợ tin nhắn trực tiếp.

Ghép nối

Chính sách DM mặc định cho SMS là ghép nối.

Bảo mật Gateway

Xem xét mức độ công khai của Webhook và các biện pháp kiểm soát quyền truy cập của người gửi.

Khắc phục sự cố kênh

Các quy trình chẩn đoán và khắc phục trên nhiều kênh.

Trước khi bắt đầu

Bạn cần:

• Plugin SMS chính thức được cài đặt bằng openclaw plugins install @openclaw/sms.
• Tài khoản Twilio có số điện thoại hỗ trợ SMS hoặc Twilio Messaging Service.
• Account SID và Auth Token của Twilio.
• URL HTTPS công khai có thể truy cập OpenClaw Gateway của bạn.
• Lựa chọn chính sách người gửi: pairing (mặc định) cho mục đích sử dụng riêng tư, allowlist cho các số điện thoại được phê duyệt trước hoặc chỉ dùng open khi chủ ý cho phép truy cập SMS công khai.

Một số Twilio có thể phục vụ cả SMS và Cuộc gọi thoại nếu có cả hai khả năng. Webhook SMS và Webhook thoại được cấu hình riêng trong Twilio và sử dụng các đường dẫn Gateway riêng biệt; trang này chỉ đề cập đến Webhook SMS.

Thiết lập nhanh

1. Cài đặt Plugin

   openclaw plugins install @openclaw/sms
   
2. Tạo hoặc chọn người gửi Twilio

   Trong Twilio, mở Phone Numbers > Manage > Active numbers và chọn một số hỗ trợ SMS. Lưu lại:

   • Account SID, ví dụ ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   • Auth Token
   • Số điện thoại người gửi, ví dụ [phone]

   Nếu bạn sử dụng Messaging Service thay cho một số người gửi cố định, hãy lưu Messaging Service SID, ví dụ MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

3. Cấu hình kênh SMS

   Lưu nội dung này dưới dạng sms.patch.json5 và thay đổi các phần giữ chỗ:

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

   Áp dụng cấu hình:

   openclaw config patch --file ./sms.patch.json5 --dry-run
   openclaw config patch --file ./sms.patch.json5
   
4. Trỏ Twilio đến Webhook của Gateway

   Trong phần cài đặt số điện thoại Twilio, mở Messaging và đặt A message comes in thành:

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

   Sử dụng HTTP POST. Đường dẫn cục bộ mặc định là /webhooks/sms; thay đổi channels.sms.webhookPath nếu bạn cần một tuyến khác.

5. Công khai chính xác đường dẫn Webhook SMS

   URL công khai của bạn phải định tuyến đường dẫn SMS đến tiến trình Gateway (cổng mặc định 18789). Nếu sử dụng Tailscale Funnel để kiểm thử cục bộ, hãy công khai rõ ràng /webhooks/sms:

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

   Cuộc gọi thoại và SMS sử dụng các đường dẫn Webhook riêng biệt. Nếu cùng một số Twilio xử lý cả hai, hãy duy trì cấu hình cho cả hai tuyến trong Twilio và đường hầm của bạn.

6. Khởi động Gateway và phê duyệt người gửi đầu tiên

   openclaw gateway
   

   Gửi một tin nhắn văn bản đến số Twilio. Tin nhắn đầu tiên sẽ tạo một yêu cầu ghép nối. Phê duyệt yêu cầu đó:

   openclaw pairing list sms
   openclaw pairing approve sms <CODE>
   

   Mã ghép nối hết hạn sau 1 giờ.

Ví dụ cấu hình

Tất cả khóa nằm trong channels.sms (và trong channels.sms.accounts.<id> đối với từng tài khoản):

Khóa	Mặc định	Mục đích
enabled	true	Bật hoặc tắt kênh/tài khoản.
accountSid	—	Account SID của Twilio (AC...).
authToken	—	Auth Token của Twilio; chuỗi văn bản thuần hoặc SecretRef.
fromNumber	—	Số người gửi theo định dạng E.164.
messagingServiceSid	—	Messaging Service SID (MG...) được dùng khi không phân giải được fromNumber.
defaultTo	—	Đích mặc định khi luồng gửi không chỉ định đích rõ ràng.
webhookPath	/webhooks/sms	Đường dẫn HTTP của Gateway cho các Webhook Twilio đến.
publicWebhookUrl	—	URL công khai được cấu hình trong Twilio; bắt buộc để xác thực chữ ký.
dangerouslyDisableSignatureValidation	false	Bỏ qua kiểm tra X-Twilio-Signature; chỉ dành cho kiểm thử đường hầm cục bộ.
dmPolicy	"pairing"	pairing, allowlist, open hoặc disabled.
allowFrom	[]	Các số người gửi được phép theo E.164 hoặc "*" với dmPolicy: "open".
textChunkLimit	1500	Số ký tự tối đa trong mỗi phần SMS gửi đi.
accounts, defaultAccount	—	Ánh xạ nhiều tài khoản và mã định danh tài khoản mặc định.

Tệp cấu hình

Sử dụng thiết lập bằng tệp cấu hình khi bạn muốn định nghĩa kênh được phân phối cùng cấu hình Gateway:

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

Biến môi trường

Các biến môi trường chỉ áp dụng cho tài khoản mặc định; giá trị cấu hình được ưu tiên hơn giá trị biến môi trường.

Biến	Ánh xạ đến
TWILIO_ACCOUNT_SID	accountSid
TWILIO_AUTH_TOKEN	authToken
TWILIO_PHONE_NUMBER (bí danh TWILIO_SMS_FROM)	fromNumber
TWILIO_MESSAGING_SERVICE_SID	messagingServiceSid
SMS_PUBLIC_WEBHOOK_URL	publicWebhookUrl
SMS_WEBHOOK_PATH	webhookPath
SMS_ALLOWED_USERS	allowFrom (phân tách bằng dấu phẩy)
SMS_TEXT_CHUNK_LIMIT	textChunkLimit
SMS_DANGEROUSLY_DISABLE_SIGNATURE_VALIDATION	dangerouslyDisableSignatureValidation ("true")

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

Sau đó bật kênh trong cấu hình:

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

Auth Token dạng SecretRef

authToken có thể là một SecretRef (source: "env" | "file" | "exec"). Sử dụng tùy chọn này khi Gateway cần phân giải Auth Token của Twilio từ môi trường bí mật OpenClaw thay vì lưu cấu hình dưới dạng văn bản thuần:

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

Biến môi trường hoặc nhà cung cấp bí mật được tham chiếu phải hiển thị với môi trường chạy Gateway. Khởi động lại các tiến trình Gateway được quản lý sau khi thay đổi biến môi trường của máy chủ.

Người gửi Messaging Service

Sử dụng messagingServiceSid thay cho fromNumber khi Twilio cần chọn người gửi thông qua Messaging Service:

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

Nếu cả fromNumber và messagingServiceSid đều hiện diện sau khi phân giải cấu hình và biến môi trường, fromNumber sẽ được sử dụng.

Đích gửi đi mặc định

Đặt defaultTo khi hoạt động tự động hóa hoặc gửi do tác nhân khởi tạo cần có một đích mặc định nếu luồng gửi không chỉ định đích rõ ràng:

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

Kiểm soát quyền truy cập

channels.sms.dmPolicy kiểm soát quyền truy cập SMS trực tiếp:

• pairing (mặc định): người gửi không xác định nhận được mã ghép nối; phê duyệt bằng openclaw pairing approve sms <CODE>.
• allowlist: chỉ xử lý người gửi có trong allowFrom. allowFrom trống sẽ từ chối mọi người gửi (Gateway ghi nhật ký cảnh báo khi khởi động).
• open: quá trình xác thực cấu hình yêu cầu allowFrom phải chứa "*". Nếu không có ký tự đại diện, chỉ các số được liệt kê mới có thể trò chuyện.
• disabled: tất cả DM đến đều bị loại bỏ.

Các mục allowFrom phải là số điện thoại E.164, chẳng hạn như [phone]. Các tiền tố sms: và twilio-sms: được chấp nhận và chuẩn hóa. Đối với trợ lý riêng tư, ưu tiên dmPolicy: "allowlist" với các số điện thoại được chỉ định rõ ràng:

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

Gửi SMS

Khi chọn kênh SMS, đích chấp nhận số E.164 thuần hoặc tiền tố sms::

openclaw message send --channel sms --target sms:[phone] --message "hello"

Khi lựa chọn kênh là ngầm định, tiền tố twilio-sms: sẽ chọn kênh này mà không chiếm dụng tiền tố dịch vụ sms:, vốn được iMessage sử dụng để chọn hình thức gửi SMS qua nhà mạng cho các đích của riêng mình:

openclaw message send --target twilio-sms:[phone] --message "hello"

CLI yêu cầu --target rõ ràng. defaultTo dành cho các đường dẫn tự động hóa và gửi do tác nhân khởi tạo, trong đó đích có thể được phân giải từ cấu hình kênh.

Phản hồi của tác tử từ các cuộc trò chuyện SMS đến sẽ tự động được gửi lại cho người gửi thông qua số gửi Twilio đã cấu hình.

Đầu ra SMS là văn bản thuần túy. OpenClaw loại bỏ markdown, chuyển các khối mã có hàng rào thành một dòng, viết lại liên kết thành label (url), đồng thời chia các phản hồi dài thành các phần tối đa textChunkLimit ký tự (mặc định là 1500) trước khi gửi qua Twilio.

Xác minh thiết lập

Sau khi Gateway khởi động:

1. Xác nhận nhật ký Gateway hiển thị tuyến Webhook SMS.
2. Chạy phép kiểm tra phía Twilio (kiểm tra URL/phương thức Webhook Twilio đã cấu hình và các lỗi đầu vào gần đây):

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

3. Gửi một SMS từ điện thoại của bạn đến số Twilio.
4. Chạy openclaw pairing list sms.
5. Phê duyệt mã ghép nối bằng openclaw pairing approve sms <CODE>.
6. Gửi một SMS khác và xác nhận tác tử phản hồi.

Để chỉ kiểm thử gửi đi, hãy dùng:

openclaw message send --channel sms --target sms:[phone] --message "Kiểm thử SMS OpenClaw"

Kiểm thử đầu cuối từ iMessage/SMS trên macOS

Trên máy Mac có thể gửi SMS của nhà mạng qua Messages, bạn có thể dùng imsg để điều khiển phía người gửi mà không cần thao tác trên điện thoại:

imsg send --to "[phone]" --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 "[phone]" --service sms --text "chỉ trả lời SMS pong" --json

Tin nhắn đầu tiên sẽ tạo một yêu cầu ghép nối. Tin nhắn thứ hai sẽ nhận được phản hồi của tác tử thông qua Twilio.

Bảo mật Webhook

Theo mặc định, OpenClaw xác thực X-Twilio-Signature bằng publicWebhookUrl và authToken. Hãy giữ phần điểm cuối của publicWebhookUrl khớp từng byte với URL được cấu hình trong Twilio, bao gồm lược đồ, máy chủ, đường dẫn và chuỗi truy vấn. OpenClaw loại trừ các phân mảnh ghi đè kết nối của Twilio (#...) khỏi phép tính chữ ký, theo yêu cầu của Twilio.

Độc lập với việc xác thực chữ ký, tuyến Webhook cũng thực thi:

• Chỉ POST.
• Hạn mức yêu cầu thất bại là 300 yêu cầu mỗi phút cho mỗi tài khoản SMS, tuyến Webhook và địa chỉ máy khách đã phân giải. Mọi yêu cầu đều được tính vào hạn mức này, nhưng HTTP 429 chỉ được áp dụng sau khi yêu cầu không thể phân tích cú pháp nội dung, xác thực Twilio hoặc đối chiếu AccountSid.
• Giới hạn tốc độ lệnh gọi lại có thể phân phối là 30 lệnh gọi lại được chấp nhận mỗi phút cho mỗi tài khoản SMS, tuyến Webhook và địa chỉ máy khách đã phân giải sau khi vượt qua các bước kiểm tra đó (HTTP 429 nếu vượt quá). Nếu xác thực chữ ký bị tắt, giới hạn 30/phút này là mức trần phân phối không xác thực.
• Địa chỉ máy khách được phân giải thông qua các quy tắc proxy tin cậy dùng chung của Gateway. Nếu gateway.trustedProxies chứa proxy ngược chuyển tiếp các lệnh gọi lại Twilio, OpenClaw xác định các giới hạn này theo địa chỉ máy khách được chuyển tiếp; nếu không, OpenClaw dùng địa chỉ socket trực tiếp.
• AccountSid trong tải trọng phải khớp với accountSid đã cấu hình (nếu không sẽ trả về HTTP 403).
• Các giá trị MessageSid được phát lại sẽ được loại bỏ trùng lặp trong 10 phút.
• Bộ nhớ đệm phát lại của mỗi tài khoản SMS lưu tối đa 10.000 SID tin nhắn còn hiệu lực. Khi mọi vị trí đều còn hiệu lực, các Webhook mới của tài khoản đó sẽ bị từ chối theo cơ chế đóng an toàn với HTTP 429 và tiêu đề Retry-After cho đến khi vị trí cũ nhất hết hạn.
• Nội dung yêu cầu lớn hơn 32 KB sẽ bị từ chối.

Theo mặc định, Twilio không thử lại HTTP 429 và cũng không ghi nhận hỗ trợ cho Retry-After. Các ghi đè kết nối #rp=4xx và #rp=all cho phép thử lại lỗi 4xx, nhưng Twilio giới hạn toàn bộ giao dịch thử lại ở 15 giây, vì vậy quá trình thử lại vẫn có thể kết thúc trước khi một vị trí trong bộ nhớ đệm phát lại hết hạn. Hãy cấu hình URL dự phòng khi một trình xử lý khác phải nhận các lần phân phối thất bại; coi 429 là một lần từ chối theo cơ chế đóng an toàn, không phải cơ chế tạo áp lực ngược đáng tin cậy.

Chỉ để kiểm thử đường hầm cục bộ, bạn có thể đặt:

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

Không sử dụng chế độ tắt xác thực chữ ký trên Gateway công khai.

Cấu hình nhiều tài khoản

Dùng accounts khi bạn vận hành nhiều hơn một số Twilio:

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

Mỗi tài khoản phải dùng một webhookPath riêng biệt; Gateway từ chối đăng ký tuyến Webhook có đường dẫn đã thuộc về tài khoản khác. Các giá trị dự phòng từ môi trường TWILIO_*/SMS_* chỉ áp dụng cho tài khoản mặc định; đặt defaultAccount để thay đổi tài khoản mặc định.

Khắc phục sự cố

Twilio trả về 403 hoặc OpenClaw từ chối Webhook

Kiểm tra để đảm bảo publicWebhookUrl khớp chính xác với URL được cấu hình trong Twilio, bao gồm lược đồ, máy chủ, đường dẫn và chuỗi truy vấn. Twilio ký chuỗi URL công khai, vì vậy việc proxy viết lại URL và các tên máy chủ thay thế có thể làm hỏng quá trình xác thực chữ ký.

Lỗi 403 kèm Invalid account có nghĩa là AccountSid trong tải trọng đầu vào không khớp với accountSid đã cấu hình; hãy kiểm tra để đảm bảo Webhook trỏ đến tài khoản sở hữu số đó.

Không xuất hiện yêu cầu ghép nối

Kiểm tra URL và phương thức Webhook Messaging của số Twilio. URL phải trỏ đến URL Webhook SMS và dùng POST. Đồng thời xác nhận Gateway có thể được truy cập từ Internet công cộng hoặc thông qua đường hầm của bạn.

Nếu nhật ký tin nhắn Twilio hiển thị lỗi 11200, Twilio đã chấp nhận SMS đến nhưng không thể kết nối với Webhook của bạn. Hãy kiểm tra:

• Mục Messaging > A message comes in của Twilio trỏ đến publicWebhookUrl.
• Phương thức là POST.
• Đường hầm hoặc proxy ngược công khai chính xác webhookPath; đối với Tailscale Funnel, hãy chạy tailscale funnel status và xác nhận /webhooks/sms được liệt kê.
• publicWebhookUrl sử dụng cùng lược đồ, máy chủ, đường dẫn và chuỗi truy vấn mà Twilio gửi, để quá trình xác thực chữ ký có thể tái tạo URL đã ký.

openclaw channels status --channel sms --probe hiển thị cả các cài đặt Webhook Twilio không khớp và các lỗi 11200 gần đây.

Gửi đi thất bại

Xác nhận accountSid, authToken và một trong fromNumber hoặc messagingServiceSid đã được phân giải. Nếu bạn dùng tài khoản Twilio dùng thử, số đích có thể cần được xác minh trong Twilio trước khi có thể gửi SMS đi.

Tin nhắn đến nhưng tác tử không trả lời

Kiểm tra dmPolicy và allowFrom. Với chính sách pairing mặc định, người gửi phải được phê duyệt trước khi các lượt tương tác thông thường của tác tử được xử lý.