SMS

OpenClaw menerima dan mengirim SMS melalui nomor telepon Twilio atau Messaging Service. Gateway mendaftarkan rute Webhook masuk (default /webhooks/sms), memvalidasi tanda tangan permintaan Twilio secara default, dan mengirim balasan kembali melalui Messages API Twilio.

Status: Plugin resmi, dipasang secara terpisah. Hanya teks: tanpa MMS/media, hanya pesan langsung.

Sebelum memulai

Anda memerlukan:

• Plugin SMS resmi yang dipasang dengan openclaw plugins install @openclaw/sms.
• Akun Twilio dengan nomor telepon yang mendukung SMS, atau Twilio Messaging Service.
• Account SID dan Auth Token Twilio.
• URL HTTPS publik yang dapat menjangkau Gateway OpenClaw Anda.
• Pilihan kebijakan pengirim: pairing (default) untuk penggunaan pribadi, allowlist untuk nomor telepon yang telah disetujui sebelumnya, atau open hanya untuk akses SMS yang sengaja dibuka untuk publik.

Satu nomor Twilio dapat melayani SMS dan Panggilan Suara jika memiliki kedua kemampuan tersebut. Webhook SMS dan Webhook Suara dikonfigurasi secara terpisah di Twilio dan menggunakan jalur Gateway yang berbeda; halaman ini hanya membahas Webhook SMS.

Penyiapan Cepat

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>

Contoh Konfigurasi

Semua kunci berada di bawah channels.sms (dan untuk setiap akun di bawah channels.sms.accounts.<id>):

Berkas konfigurasi

Gunakan penyiapan berkas konfigurasi jika Anda ingin definisi saluran disertakan bersama konfigurasi Gateway:

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

Variabel lingkungan

Variabel lingkungan hanya berlaku untuk akun default; nilai konfigurasi lebih diutamakan daripada nilai lingkungan.

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"

Kemudian aktifkan saluran dalam konfigurasi:

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

Auth Token SecretRef

authToken dapat berupa SecretRef (source: "env" | "file" | "exec"). Gunakan ini jika Gateway harus menguraikan Auth Token Twilio dari runtime rahasia OpenClaw alih-alih menyimpan konfigurasi dalam teks biasa:

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

Variabel lingkungan atau penyedia rahasia yang dirujuk harus terlihat oleh runtime Gateway. Mulai ulang proses Gateway terkelola setelah mengubah variabel lingkungan hos.

Pengirim Messaging Service

Gunakan messagingServiceSid alih-alih fromNumber jika Twilio harus memilih pengirim melalui Messaging Service:

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

Jika fromNumber dan messagingServiceSid keduanya tersedia setelah penguraian konfigurasi dan lingkungan, fromNumber digunakan.

Target keluar default

Atur defaultTo jika otomatisasi atau pengiriman yang dimulai agen harus memiliki tujuan default ketika alur pengiriman tidak menyertakan target eksplisit:

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

Kontrol akses

channels.sms.dmPolicy mengontrol akses SMS langsung:

• pairing (default): pengirim yang tidak dikenal mendapatkan kode pemasangan; setujui dengan openclaw pairing approve sms <CODE>.
• allowlist: hanya pengirim dalam allowFrom yang diproses. allowFrom kosong menolak setiap pengirim (Gateway mencatat peringatan saat dimulai).
• open: validasi konfigurasi mengharuskan allowFrom menyertakan "*". Tanpa wildcard, hanya nomor yang tercantum yang dapat mengobrol.
• disabled: semua DM masuk dibuang.

Entri allowFrom harus berupa nomor telepon E.164 seperti +15551234567. Awalan sms: dan twilio-sms: diterima dan dinormalisasi. Untuk asisten pribadi, pilih dmPolicy: "allowlist" dengan nomor telepon eksplisit:

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

Mengirim SMS

Dengan saluran SMS dipilih, target menerima nomor E.164 polos atau awalan sms::

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

Saat pemilihan saluran bersifat implisit, awalan twilio-sms: memilih saluran ini tanpa mengambil alih awalan layanan sms:, yang digunakan iMessage untuk memilih pengiriman SMS operator bagi targetnya sendiri:

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

CLI memerlukan --target eksplisit. defaultTo ditujukan untuk jalur otomatisasi dan pengiriman yang dimulai agen, tempat target dapat diuraikan dari konfigurasi saluran.

Balasan agen dari percakapan SMS masuk secara otomatis dikirim kembali kepada pengirim melalui pengirim Twilio yang dikonfigurasi.

Keluaran SMS berupa teks biasa. OpenClaw menghapus markdown, meratakan blok kode berpagar, menulis ulang tautan sebagai label (url), dan membagi balasan panjang menjadi potongan yang masing-masing berisi paling banyak textChunkLimit karakter (nilai bawaan 1500) sebelum mengirimkannya melalui Twilio.

Verifikasi Penyiapan

Setelah Gateway dimulai:

1. Pastikan log Gateway menampilkan rute Webhook SMS.
2. Jalankan pemeriksaan dari sisi Twilio (memeriksa URL/metode Webhook Twilio yang dikonfigurasi dan galat masuk terbaru):

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

3. Kirim SMS ke nomor Twilio dari ponsel Anda.
4. Jalankan openclaw pairing list sms.
5. Setujui kode pemasangan dengan openclaw pairing approve sms <CODE>.
6. Kirim SMS lainnya dan pastikan agen membalas.

Untuk pengujian khusus keluar, gunakan:

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

Pengujian menyeluruh dari iMessage/SMS macOS

Pada Mac yang dapat mengirim SMS operator melalui Messages, Anda dapat menggunakan imsg untuk menjalankan sisi pengirim tanpa menyentuh ponsel:

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

Pesan pertama seharusnya membuat permintaan pemasangan. Pesan kedua seharusnya menerima balasan agen melalui Twilio.

Keamanan Webhook

Secara bawaan, OpenClaw memvalidasi X-Twilio-Signature menggunakan publicWebhookUrl dan authToken. Pastikan bagian titik akhir dari publicWebhookUrl sama persis byte demi byte dengan URL yang dikonfigurasi di Twilio, termasuk skema, host, jalur, dan string kueri. OpenClaw mengecualikan fragmen penggantian koneksi Twilio (#...) dari penghitungan tanda tangan, sebagaimana diwajibkan oleh Twilio.

Rute Webhook juga memberlakukan hal berikut, secara independen dari validasi tanda tangan:

• POST saja.
• Batas permintaan gagal sebanyak 300 permintaan per menit untuk setiap akun SMS, rute Webhook, dan alamat klien yang ditentukan. Semua permintaan dihitung dalam batas ini, tetapi HTTP 429 hanya diterapkan setelah permintaan gagal mengurai isi, memvalidasi Twilio, atau mencocokkan AccountSid.
• Batas laju panggilan balik yang dapat diteruskan sebanyak 30 panggilan balik yang diterima per menit untuk setiap akun SMS, rute Webhook, dan alamat klien yang ditentukan setelah pemeriksaan tersebut lolos (HTTP 429 jika melampaui batas tersebut). Jika validasi tanda tangan dinonaktifkan, batas 30/menit ini menjadi batas maksimum penerusan tanpa autentikasi.
• Alamat klien ditentukan melalui aturan proksi tepercaya bersama milik Gateway. Jika gateway.trustedProxies berisi proksi terbalik yang meneruskan panggilan balik Twilio, OpenClaw mendasarkan batas ini pada alamat klien yang diteruskan; jika tidak, OpenClaw menggunakan alamat soket langsung.
• AccountSid dalam muatan harus cocok dengan accountSid yang dikonfigurasi (jika tidak, HTTP 403).
• Nilai MessageSid yang diputar ulang dideduplikasi selama 10 menit.
• Cache pemutaran ulang setiap akun SMS menyimpan hingga 10,000 SID pesan aktif. Ketika semua slot masih aktif, Webhook baru untuk akun tersebut ditolak secara tertutup dengan HTTP 429 dan header Retry-After hingga slot terlama kedaluwarsa.
• Isi permintaan yang melebihi 32 KB ditolak.

Secara bawaan, Twilio tidak mencoba ulang HTTP 429 maupun mendokumentasikan dukungan untuk Retry-After. Penggantian koneksi #rp=4xx dan #rp=all mengaktifkan percobaan ulang untuk 4xx, tetapi Twilio membatasi keseluruhan transaksi percobaan ulang hingga 15 detik, sehingga percobaan ulang masih dapat berakhir sebelum slot cache pemutaran ulang kedaluwarsa. Konfigurasikan URL cadangan ketika penangan lain harus menerima pengiriman yang gagal; perlakukan 429 sebagai penolakan tertutup saat gagal, bukan tekanan balik yang andal.

Khusus untuk pengujian terowongan lokal, Anda dapat menetapkan:

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

Jangan gunakan validasi tanda tangan yang dinonaktifkan pada Gateway publik.

Konfigurasi Multiakun

Gunakan accounts jika Anda mengoperasikan lebih dari satu nomor Twilio:

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

Setiap akun harus menggunakan webhookPath yang berbeda; Gateway menolak mendaftarkan rute Webhook yang jalurnya sudah dimiliki akun lain. Nilai cadangan lingkungan TWILIO_*/SMS_* hanya berlaku untuk akun bawaan; tetapkan defaultAccount untuk mengubah akun yang menjadi akun bawaan.

Pemecahan Masalah

Twilio mengembalikan 403 atau OpenClaw menolak Webhook

Pastikan publicWebhookUrl sama persis dengan URL yang dikonfigurasi di Twilio, termasuk skema, host, jalur, dan string kueri. Twilio menandatangani string URL publik, sehingga penulisan ulang oleh proksi dan nama host alternatif dapat menggagalkan validasi tanda tangan.

Respons 403 dengan Invalid account berarti AccountSid dalam muatan masuk tidak cocok dengan accountSid yang dikonfigurasi; pastikan Webhook mengarah ke akun yang memiliki nomor tersebut.

Permintaan pemasangan tidak muncul

Periksa URL dan metode Webhook Messaging milik nomor Twilio. URL tersebut harus mengarah ke URL Webhook SMS dan menggunakan POST. Pastikan juga Gateway dapat dijangkau dari internet publik atau melalui terowongan Anda.

Jika log pesan Twilio menampilkan galat 11200, Twilio menerima SMS masuk tetapi tidak dapat menjangkau Webhook Anda. Periksa:

• Twilio Messaging > A message comes in mengarah ke publicWebhookUrl.
• Metodenya adalah POST.
• Terowongan atau proksi terbalik mengekspos webhookPath yang tepat; untuk Tailscale Funnel, jalankan tailscale funnel status dan pastikan /webhooks/sms tercantum.
• publicWebhookUrl menggunakan skema, host, jalur, dan string kueri yang sama dengan yang dikirim Twilio, sehingga validasi tanda tangan dapat mereproduksi URL yang ditandatangani.

openclaw channels status --channel sms --probe menampilkan ketidakcocokan pengaturan Webhook Twilio dan galat 11200 terbaru.

Pengiriman keluar gagal

Pastikan accountSid, authToken, serta fromNumber atau messagingServiceSid telah ditentukan. Jika Anda menggunakan akun uji coba Twilio, nomor tujuan mungkin perlu diverifikasi di Twilio sebelum SMS keluar dapat dikirim.

Pesan tiba tetapi agen tidak menjawab

Periksa dmPolicy dan allowFrom. Dengan kebijakan pairing bawaan, pengirim harus disetujui sebelum giliran agen normal diproses.