SMS

​

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

• Официальный плагин SMS, установленный с помощью openclaw plugins install @openclaw/sms.
• Учетная запись Twilio с телефонным номером, поддерживающим SMS, или Twilio Messaging Service.
• Account SID и Auth Token Twilio.
• Общедоступный URL-адрес HTTPS, ведущий к вашему OpenClaw Gateway.
• Выбранная политика отправителей: pairing (по умолчанию) для личного использования, allowlist для предварительно одобренных телефонных номеров или open только для намеренно общедоступного доступа по 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-run
openclaw 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/sms
tailscale funnel status

openclaw gateway

openclaw pairing list sms
openclaw pairing approve sms <CODE>

​

Примеры конфигурации

​

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

{
  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

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

​

Отправитель Messaging Service

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

​

Исходящий получатель по умолчанию

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

​

Управление доступом

• pairing (по умолчанию): неизвестные отправители получают код сопряжения; одобрите его с помощью openclaw pairing approve sms <CODE>.
• allowlist: обрабатываются только отправители из allowFrom. Пустой allowFrom отклоняет всех отправителей (Gateway записывает предупреждение при запуске).
• open: проверка конфигурации требует, чтобы allowFrom содержал "*". Без подстановочного знака общаться могут только указанные номера.
• disabled: все входящие личные сообщения отбрасываются.

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

​

Отправка SMS

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

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

​

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

1. Убедитесь, что в журнале Gateway отображается маршрут Webhook для SMS.
2. Запустите проверку на стороне Twilio (она проверяет настроенные URL и метод Webhook Twilio, а также недавние ошибки входящих запросов):

openclaw channels capabilities --channel sms
openclaw 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

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 <CODE>
imsg send --to "+15551234567" --service sms --text "reply exactly SMS pong" --json

​

Безопасность 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 КБ отклоняются.

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

​

Конфигурация нескольких учётных записей

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

​

Устранение неполадок

​

Twilio возвращает 403 или OpenClaw отклоняет Webhook

​

Запрос на сопряжение не появляется

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

​

Не удаётся отправить исходящие сообщения

​

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