--- read_when: - Anda ingin menghubungkan OpenClaw ke SMS melalui Twilio - Anda memerlukan penyiapan webhook SMS atau daftar izin summary: Penyiapan kanal SMS Twilio, kontrol akses, dan konfigurasi webhook title: SMS x-i18n: generated_at: "2026-07-12T14:00:45Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 1ae0e0fee978a9837fc75ef7e9122bd06009df0d44de35fe9dff8aab120d5404 source_path: channels/sms.md workflow: 16 --- 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. Kebijakan DM bawaan untuk SMS adalah pemasangan. Tinjau paparan Webhook dan kontrol akses pengirim. Diagnostik lintas saluran dan panduan perbaikan. ## 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](/id/plugins/voice-call) 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 ```bash openclaw plugins install @openclaw/sms ``` Di Twilio, buka **Phone Numbers > Manage > Active numbers** dan pilih nomor yang mendukung SMS. Simpan: - Account SID, misalnya `ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` - Auth Token - Nomor telepon pengirim, misalnya `+15551234567` Jika Anda menggunakan Messaging Service alih-alih nomor pengirim tetap, simpan Messaging Service SID, misalnya `MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`. Simpan ini sebagai `sms.patch.json5` dan ubah placeholder: ```json5 { channels: { sms: { enabled: true, accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", authToken: "twilio-auth-token", fromNumber: "+15551234567", publicWebhookUrl: "https://gateway.example.com/webhooks/sms", dmPolicy: "pairing", }, }, } ``` Terapkan: ```bash openclaw config patch --file ./sms.patch.json5 --dry-run openclaw config patch --file ./sms.patch.json5 ``` Di pengaturan nomor telepon Twilio, buka **Messaging** dan atur **A message comes in** ke: ```text https://gateway.example.com/webhooks/sms ``` Gunakan HTTP `POST`. Jalur lokal bawaan adalah `/webhooks/sms`; ubah `channels.sms.webhookPath` jika Anda memerlukan rute yang berbeda. URL publik Anda harus merutekan jalur SMS ke proses Gateway (port bawaan `18789`). Jika menggunakan Tailscale Funnel untuk pengujian lokal, publikasikan `/webhooks/sms` secara eksplisit: ```bash tailscale funnel --bg --set-path /webhooks/sms http://127.0.0.1:/webhooks/sms tailscale funnel status ``` Panggilan Suara dan SMS menggunakan jalur Webhook yang berbeda. Jika nomor Twilio yang sama menangani keduanya, pertahankan konfigurasi kedua rute di Twilio dan terowongan Anda. ```bash openclaw gateway ``` Kirim pesan teks ke nomor Twilio. Pesan pertama membuat permintaan pemasangan. Setujui: ```bash openclaw pairing list sms openclaw pairing approve sms ``` Kode pemasangan kedaluwarsa setelah 1 jam. ## Contoh Konfigurasi Semua kunci berada di bawah `channels.sms` (dan untuk setiap akun di bawah `channels.sms.accounts.`): | Kunci | Bawaan | Tujuan | | --------------------------------------- | --------------- | -------------------------------------------------------------------- | | `enabled` | `true` | Mengaktifkan atau menonaktifkan saluran/akun. | | `accountSid` | — | Account SID Twilio (`AC...`). | | `authToken` | — | Auth Token Twilio; string teks biasa atau SecretRef. | | `fromNumber` | — | Nomor pengirim E.164. | | `messagingServiceSid` | — | Messaging Service SID (`MG...`) yang digunakan jika tidak ada `fromNumber` yang ditemukan. | | `defaultTo` | — | Tujuan bawaan ketika alur pengiriman tidak menyertakan target eksplisit. | | `webhookPath` | `/webhooks/sms` | Jalur HTTP Gateway untuk Webhook Twilio masuk. | | `publicWebhookUrl` | — | URL publik yang dikonfigurasi di Twilio; diperlukan untuk validasi tanda tangan. | | `dangerouslyDisableSignatureValidation` | `false` | Melewati pemeriksaan `X-Twilio-Signature`; hanya untuk pengujian terowongan lokal. | | `dmPolicy` | `"pairing"` | `pairing`, `allowlist`, `open`, atau `disabled`. | | `allowFrom` | `[]` | Nomor pengirim yang diizinkan dalam format E.164, atau `"*"` dengan `dmPolicy: "open"`. | | `textChunkLimit` | `1500` | Jumlah maksimum karakter per potongan SMS keluar. | | `accounts`, `defaultAccount` | — | Peta multiakun dan id akun bawaan. | ### Berkas konfigurasi Gunakan penyiapan melalui berkas konfigurasi jika Anda ingin definisi saluran disertakan bersama konfigurasi Gateway: ```json5 { 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. | Variabel | Dipetakan ke | | ----------------------------------------------- | --------------------------------------------------- | | `TWILIO_ACCOUNT_SID` | `accountSid` | | `TWILIO_AUTH_TOKEN` | `authToken` | | `TWILIO_PHONE_NUMBER` (alias `TWILIO_SMS_FROM`) | `fromNumber` | | `TWILIO_MESSAGING_SERVICE_SID` | `messagingServiceSid` | | `SMS_PUBLIC_WEBHOOK_URL` | `publicWebhookUrl` | | `SMS_WEBHOOK_PATH` | `webhookPath` | | `SMS_ALLOWED_USERS` | `allowFrom` (dipisahkan koma) | | `SMS_TEXT_CHUNK_LIMIT` | `textChunkLimit` | | `SMS_DANGEROUSLY_DISABLE_SIGNATURE_VALIDATION` | `dangerouslyDisableSignatureValidation` (`"true"`) | ```bash export TWILIO_ACCOUNT_SID="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" export TWILIO_AUTH_TOKEN="" export TWILIO_PHONE_NUMBER="+15551234567" export SMS_PUBLIC_WEBHOOK_URL="https://gateway.example.com/webhooks/sms" ``` Kemudian aktifkan saluran dalam konfigurasi: ```json5 { 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: ```json5 { 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: ```json5 { 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: ```json5 { 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 `. - `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: ```json5 { 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:`: ```bash 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: ```bash 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): ```bash openclaw channels capabilities --channel sms openclaw 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 `. 6. Kirim SMS lagi dan pastikan agen membalas. Untuk pengujian khusus pesan keluar, gunakan: ```bash 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: ```bash 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 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](https://www.twilio.com/docs/usage/webhooks/webhooks-connection-overrides) 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: ```json5 { channels: { sms: { dangerouslyDisableSignatureValidation: true, }, }, } ``` Jangan menonaktifkan validasi tanda tangan pada Gateway publik. ## Konfigurasi multiakun Gunakan `accounts` saat Anda mengoperasikan lebih dari satu nomor Twilio: ```json5 { 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.