SMS

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

Статус: официальный плагин, устанавливается отдельно. Только текст: без MMS и медиафайлов, только личные сообщения.

Перед началом

Вам потребуется:

• Официальный плагин 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, преобразует блоки кода в обычный текст, переписывает ссылки в виде label (url) и перед отправкой через Twilio разбивает длинные ответы на части размером не более textChunkLimit символов (по умолчанию 1500).

Проверка настройки

После запуска Gateway:

1. Убедитесь, что в журнале Gateway отображается маршрут Webhook для SMS.
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"

Сквозное тестирование из iMessage/SMS в macOS

На компьютере 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, включая схему, хост, путь и строку запроса. В соответствии с требованиями Twilio OpenClaw исключает фрагменты переопределения подключения (#...) из вычисления подписи.

Независимо от проверки подписи маршрут Webhook также применяет следующие ограничения:

• Только POST.
• Лимит неудачных запросов — 300 запросов в минуту для каждой комбинации учётной записи SMS, маршрута Webhook и определённого адреса клиента. Все запросы учитываются в этом лимите, но HTTP 429 возвращается только после того, как запрос не прошёл разбор тела, проверку Twilio или сопоставление AccountSid.
• Ограничение частоты обрабатываемых обратных вызовов — 30 принятых обратных вызовов в минуту для каждой комбинации учётной записи SMS, маршрута Webhook и определённого адреса клиента после успешного прохождения этих проверок (при превышении возвращается HTTP 429). Если проверка подписи отключена, этот лимит 30/мин является максимальной частотой обработки неаутентифицированных запросов.
• Адреса клиентов определяются с помощью общих правил доверенных прокси Gateway. Если gateway.trustedProxies содержит обратный прокси, перенаправляющий обратные вызовы Twilio, OpenClaw применяет эти ограничения по переданному адресу клиента; в противном случае используется адрес непосредственного сокет-соединения.
• Значение 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 Webhook SMS и использовать 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, перед отправкой исходящих SMS может потребоваться подтвердить номер получателя в Twilio.

Сообщения приходят, но агент не отвечает

Проверьте dmPolicy и allowFrom. При политике pairing, используемой по умолчанию, отправитель должен быть одобрен до обработки обычных обращений к агенту.