SMS

OpenClaw menerima dan mengirim SMS melalui nomor telepon atau Messaging Service Twilio. Gateway mendaftarkan rute Webhook masuk (bawaan /webhooks/sms), memvalidasi tanda tangan permintaan Twilio secara bawaan, 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 (bawaan) 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 melalui 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 bawaan; nilai konfigurasi lebih diutamakan daripada nilai variabel 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 mengambil Auth Token Twilio dari runtime rahasia OpenClaw alih-alih menyimpan konfigurasi dalam bentuk 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 dapat diakses 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 sama-sama tersedia setelah resolusi konfigurasi dan variabel lingkungan, fromNumber digunakan.

Target keluar bawaan

Atur defaultTo jika otomatisasi atau pengiriman yang dimulai agen harus memiliki tujuan bawaan 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 (bawaan): 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 karakter pengganti tersebut, 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, utamakan 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 tanpa awalan atau dengan awalan sms::

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

Ketika 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 yang eksplisit. defaultTo ditujukan untuk jalur otomatisasi dan pengiriman yang dimulai agen, tempat target dapat ditentukan 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 paling banyak textChunkLimit karakter (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 kesalahan pesan 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 lagi dan pastikan agen membalas.

Untuk pengujian khusus pesan 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 mengendalikan 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 default, OpenClaw memvalidasi X-Twilio-Signature menggunakan publicWebhookUrl dan authToken. Pastikan bagian titik akhir 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.

Terlepas dari validasi tanda tangan, rute Webhook juga menerapkan:

• Hanya POST.
• Batas laju 30 permintaan per menit per alamat IP sumber (HTTP 429 jika melebihi batas).
• 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 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 default, 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 selesai sebelum slot cache pemutaran ulang kedaluwarsa. Konfigurasikan URL cadangan jika penangan lain harus menerima pengiriman yang gagal; perlakukan 429 sebagai penolakan tertutup, bukan tekanan balik yang andal.

Khusus untuk pengujian terowongan lokal, Anda dapat menetapkan:

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

Jangan menonaktifkan validasi tanda tangan pada Gateway publik.

Konfigurasi multiakun

Gunakan accounts saat 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 alternatif lingkungan TWILIO_*/SMS_* hanya berlaku untuk akun default; tetapkan defaultAccount untuk mengubah akun tersebut.

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 tersebut, sehingga penulisan ulang oleh proksi dan nama host alternatif dapat merusak validasi tanda tangan.

Respons 403 dengan Invalid account berarti AccountSid pada muatan pesan 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 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 kesalahan 11200, Twilio menerima SMS masuk tetapi tidak dapat menjangkau Webhook Anda. Periksa:

• Messaging > A message comes in di Twilio 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 agar validasi tanda tangan dapat mereproduksi URL yang ditandatangani.

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

Pengiriman pesan keluar gagal

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

Pesan tiba tetapi agen tidak menjawab

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