SMS

OpenClaw отримує та надсилає SMS через номер телефону Twilio або Messaging Service. Gateway реєструє маршрут вхідного Webhook (типово /webhooks/sms), типово перевіряє підписи запитів Twilio та надсилає відповіді через Messages API Twilio.

Статус: офіційний Plugin, установлюється окремо. Лише текст: без MMS і медіафайлів, лише особисті повідомлення.

Перед початком

Вам потрібні:

• Офіційний Plugin SMS, установлений за допомогою openclaw plugins install @openclaw/sms.
• Обліковий запис Twilio з номером телефону, що підтримує SMS, або Twilio Messaging Service.
• Account SID і Auth Token Twilio.
• Загальнодоступна URL-адреса HTTPS, через яку можна підключитися до вашого OpenClaw Gateway.
• Вибір політики відправників: pairing (типово) для приватного використання, allowlist для попередньо схвалених номерів телефону або open лише для навмисно загальнодоступного доступу через SMS.

Один номер Twilio може обслуговувати як SMS, так і голосові виклики, якщо підтримує обидві можливості. Webhook SMS і Webhook голосових викликів налаштовуються у Twilio окремо та використовують окремі шляхи Gateway; ця сторінка описує лише Webhook SMS.

Швидке налаштування

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>

Приклади конфігурації

Усі ключі розміщено в channels.sms (а для окремих облікових записів — у channels.sms.accounts.<id>):

Файл конфігурації

Використовуйте налаштування через файл конфігурації, якщо потрібно, щоб визначення каналу зберігалося разом із конфігурацією Gateway:

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

Змінні середовища

Змінні середовища застосовуються лише до типового облікового запису; значення конфігурації мають пріоритет над значеннями змінних середовища.

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

Auth Token як SecretRef

authToken може бути SecretRef (source: "env" | "file" | "exec"). Використовуйте це, коли Gateway має отримувати Auth Token Twilio із середовища виконання секретів OpenClaw замість зберігання конфігурації у вигляді звичайного тексту:

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

Зазначена змінна середовища або постачальник секретів має бути доступним для середовища виконання Gateway. Після зміни змінних середовища хоста перезапустіть керовані процеси Gateway.

Відправник Messaging Service

Використовуйте messagingServiceSid замість fromNumber, коли Twilio має вибирати відправника через Messaging Service:

{  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 відхиляє кожного відправника (Gateway записує попередження під час запуску).
• 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"

CLI вимагає явно вказувати --target. defaultTo призначений для автоматизації та шляхів доставлення, ініційованого агентом, де ціль можна визначити з конфігурації каналу.

Відповіді агента у вхідних розмовах через SMS автоматично надсилаються відправнику через налаштованого відправника Twilio.

Вихідні SMS містять звичайний текст. OpenClaw видаляє форматування Markdown, перетворює огороджені блоки коду на звичайний текст, переписує посилання у форматі мітка (url) і перед надсиланням через Twilio розділяє довгі відповіді на фрагменти розміром не більше textChunkLimit символів (типово 1500).

Перевірка налаштування

Після запуску Gateway:

1. Переконайтеся, що в журналі Gateway відображається маршрут SMS Webhook.
2. Запустіть перевірку на стороні Twilio (вона перевіряє налаштовані URL-адресу й метод Webhook Twilio, а також нещодавні помилки вхідних повідомлень):

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

3. Надішліть SMS на номер Twilio зі свого телефону.
4. Виконайте openclaw pairing list sms.
5. Схваліть код сполучення командою openclaw pairing approve sms <CODE>.
6. Надішліть ще одне SMS і переконайтеся, що агент відповідає.

Для тестування лише вихідних повідомлень використовуйте:

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

Наскрізний тест із macOS iMessage/SMS

На Mac, який може надсилати операторські SMS через Messages, можна використати imsg, щоб керувати стороною відправника, не торкаючись телефона:

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

Перше повідомлення має створити запит на сполучення. У відповідь на друге повідомлення має надійти відповідь агента через Twilio.

Безпека Webhook

За замовчуванням OpenClaw перевіряє X-Twilio-Signature за допомогою publicWebhookUrl і authToken. Частина кінцевої точки в publicWebhookUrl має побайтово збігатися з URL-адресою, налаштованою у Twilio, включно зі схемою, хостом, шляхом і рядком запиту. OpenClaw виключає фрагменти перевизначення з’єднання Twilio (#...) з обчислення підпису, як того вимагає Twilio.

Незалежно від перевірки підпису маршрут Webhook також забезпечує такі обмеження:

• Лише POST.
• Обмеження частоти: 30 запитів на хвилину для кожної IP-адреси джерела (понад цей ліміт повертається HTTP 429).
• Значення AccountSid у корисному навантаженні має збігатися з налаштованим accountSid (інакше повертається HTTP 403).
• Повторно надіслані значення MessageSid дедуплікуються протягом 10 хвилин.
• Кеш повторів кожного облікового запису SMS зберігає до 10 000 активних SID повідомлень. Коли всі комірки активні, нові Webhook для цього облікового запису відхиляються за принципом безпечної відмови з HTTP 429 і заголовком Retry-After, доки не спливе термін дії найстарішої комірки.
• Тіла запитів розміром понад 32 КБ відхиляються.

За замовчуванням Twilio не повторює запити після HTTP 429 і не документує підтримку Retry-After. Перевизначення з’єднання #rp=4xx і #rp=all вмикають повторні спроби для помилок 4xx, але Twilio обмежує повну транзакцію повторних спроб 15 секундами, тому спроби все одно можуть завершитися до звільнення комірки кешу повторів. Налаштуйте резервну URL-адресу, якщо інший обробник має отримувати повідомлення, доставити які не вдалося; сприймайте 429 як відхилення за принципом безпечної відмови, а не як надійний зворотний тиск.

Лише для локального тестування через тунель можна встановити:

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

Не вимикайте перевірку підпису на загальнодоступному Gateway.

Конфігурація кількох облікових записів

Використовуйте accounts, якщо ви керуєте кількома номерами 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"],        },      },    },  },}

Кожен обліковий запис має використовувати окремий webhookPath; Gateway відмовляється реєструвати маршрут Webhook, шлях якого вже належить іншому обліковому запису. Резервні значення середовища TWILIO_*/SMS_* застосовуються лише до облікового запису за замовчуванням; установіть defaultAccount, щоб змінити цей обліковий запис.

Усунення несправностей

Twilio повертає 403 або OpenClaw відхиляє Webhook

Перевірте, чи publicWebhookUrl точно збігається з URL-адресою, налаштованою у Twilio, включно зі схемою, хостом, шляхом і рядком запиту. Twilio підписує рядок загальнодоступної URL-адреси, тому перезаписування проксі-сервером і альтернативні імена хостів можуть порушити перевірку підпису.

Помилка 403 із повідомленням Invalid account означає, що AccountSid у вхідному корисному навантаженні не збігається з налаштованим accountSid; перевірте, чи Webhook спрямовано до облікового запису, якому належить номер.

Запит на сполучення не з’являється

Перевірте URL-адресу й метод Webhook Messaging для номера Twilio. Він має вказувати на URL-адресу SMS Webhook і використовувати POST. Також переконайтеся, що Gateway доступний із загальнодоступного інтернету або через ваш тунель.

Якщо журнал повідомлень Twilio показує помилку 11200, Twilio прийняв вхідне SMS, але не зміг зв’язатися з вашим Webhook. Перевірте:

• У Twilio Messaging > A message comes in вказує на publicWebhookUrl.
• Використовується метод POST.
• Тунель або зворотний проксі-сервер надає доступ до точного webhookPath; для Tailscale Funnel виконайте tailscale funnel status і переконайтеся, що /webhooks/sms є у списку.
• publicWebhookUrl використовує ті самі схему, хост, шлях і рядок запиту, які надсилає Twilio, щоб перевірка підпису могла відтворити підписану URL-адресу.

openclaw channels status --channel sms --probe виявляє як невідповідні налаштування Webhook Twilio, так і нещодавні помилки 11200.

Не вдається надіслати вихідні повідомлення

Переконайтеся, що визначено accountSid, authToken і одне зі значень: fromNumber або messagingServiceSid. Якщо ви використовуєте пробний обліковий запис Twilio, номер одержувача, можливо, потрібно перевірити у Twilio, перш ніж можна буде надсилати вихідні SMS.

Повідомлення надходять, але агент не відповідає

Перевірте dmPolicy і allowFrom. За стандартної політики pairing відправника потрібно схвалити, перш ніж оброблятимуться звичайні звернення до агента.