SMS

​

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

• Офіційний Plugin SMS, установлений за допомогою openclaw plugins install @openclaw/sms.
• Обліковий запис Twilio з номером телефону, що підтримує SMS, або Twilio Messaging Service.
• Account SID і Auth Token Twilio.
• Загальнодоступна 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 відображається маршрут SMS Webhook.
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"

​

Наскрізне тестування з macOS iMessage/SMS

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-адресу.

​

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

​

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