SMS

OpenClaw odbiera i wysyła wiadomości SMS za pośrednictwem numeru telefonu Twilio lub usługi Messaging Service. Gateway rejestruje trasę przychodzącego Webhooka (domyślnie /webhooks/sms), domyślnie weryfikuje podpisy żądań Twilio i wysyła odpowiedzi za pośrednictwem interfejsu Messages API firmy Twilio.

Stan: oficjalny plugin, instalowany oddzielnie. Tylko tekst: bez MMS-ów i multimediów, wyłącznie wiadomości bezpośrednie.

Zanim zaczniesz

Potrzebujesz:

• Oficjalnego pluginu SMS zainstalowanego poleceniem openclaw plugins install @openclaw/sms.
• Konta Twilio z numerem telefonu obsługującym SMS-y lub usługi Twilio Messaging Service.
• Identyfikatora Account SID i tokenu Auth Token Twilio.
• Publicznego adresu URL HTTPS prowadzącego do Twojego Gatewaya OpenClaw.
• Wybranej zasady nadawców: pairing (domyślna) do użytku prywatnego, allowlist dla wstępnie zatwierdzonych numerów telefonów albo open wyłącznie w przypadku celowo publicznego dostępu przez SMS.

Jeden numer Twilio może obsługiwać zarówno SMS-y, jak i połączenia głosowe, jeśli ma obie funkcje. Webhook SMS i Webhook połączeń głosowych konfiguruje się w Twilio oddzielnie i używają one osobnych ścieżek Gatewaya; ta strona opisuje tylko Webhook SMS.

Szybka konfiguracja

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>

Przykłady konfiguracji

Wszystkie klucze znajdują się w channels.sms (a dla poszczególnych kont w channels.sms.accounts.<id>):

Plik konfiguracyjny

Użyj konfiguracji w pliku, jeśli definicja kanału ma być przechowywana razem z konfiguracją Gatewaya:

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

Zmienne środowiskowe

Zmienne środowiskowe dotyczą wyłącznie konta domyślnego; wartości konfiguracji mają pierwszeństwo przed wartościami zmiennych środowiskowych.

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"

Następnie włącz kanał w konfiguracji:

{  channels: {    sms: {      enabled: true,      dmPolicy: "pairing",    },  },}

Token uwierzytelniający SecretRef

authToken może być odwołaniem SecretRef (source: "env" | "file" | "exec"). Użyj go, jeśli Gateway ma pobierać Auth Token Twilio z mechanizmu obsługi sekretów OpenClaw zamiast przechowywać go w konfiguracji jako zwykły tekst:

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

Wskazana zmienna środowiskowa lub dostawca sekretów musi być dostępny dla środowiska wykonawczego Gatewaya. Po zmianie zmiennych środowiskowych hosta uruchom ponownie zarządzane procesy Gatewaya.

Nadawca Messaging Service

Użyj messagingServiceSid zamiast fromNumber, jeśli Twilio ma wybierać nadawcę za pośrednictwem usługi Messaging Service:

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

Jeśli po rozstrzygnięciu wartości z konfiguracji i zmiennych środowiskowych występują zarówno fromNumber, jak i messagingServiceSid, używany jest fromNumber.

Domyślny odbiorca wiadomości wychodzących

Ustaw defaultTo, jeśli automatyzacja lub dostarczanie inicjowane przez agenta ma używać domyślnego odbiorcy, gdy przepływ wysyłania nie określa jawnego celu:

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

Kontrola dostępu

channels.sms.dmPolicy steruje bezpośrednim dostępem przez SMS:

• pairing (domyślna): nieznani nadawcy otrzymują kod parowania; zatwierdź go poleceniem openclaw pairing approve sms <CODE>.
• allowlist: przetwarzane są wyłącznie wiadomości od nadawców wymienionych w allowFrom. Puste allowFrom odrzuca każdego nadawcę (Gateway rejestruje ostrzeżenie podczas uruchamiania).
• open: walidacja konfiguracji wymaga, aby allowFrom zawierało "*". Bez symbolu wieloznacznego rozmawiać mogą tylko numery znajdujące się na liście.
• disabled: wszystkie przychodzące wiadomości bezpośrednie są odrzucane.

Wpisami allowFrom powinny być numery telefonów w formacie E.164, takie jak +15551234567. Prefiksy sms: i twilio-sms: są akceptowane i normalizowane. W przypadku prywatnego asystenta preferuj dmPolicy: "allowlist" z jawnie podanymi numerami telefonów:

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

Wysyłanie wiadomości SMS

Po wybraniu kanału SMS jako cele można podawać same numery w formacie E.164 lub używać prefiksu sms::

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

Gdy wybór kanału jest niejawny, prefiks twilio-sms: wybiera ten kanał bez przejmowania prefiksu usługi sms:, którego iMessage używa do wyboru dostarczania przez sieć komórkową SMS dla własnych celów:

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

CLI wymaga jawnego parametru --target. defaultTo służy do automatyzacji i ścieżek dostarczania inicjowanych przez agenta, w których cel może zostać ustalony z konfiguracji kanału.

Odpowiedzi agenta w przychodzących rozmowach SMS są automatycznie wysyłane z powrotem do nadawcy za pośrednictwem skonfigurowanego nadawcy Twilio.

Wiadomości SMS są wysyłane jako zwykły tekst. OpenClaw usuwa składnię Markdown, spłaszcza blokowe fragmenty kodu, przekształca odnośniki do postaci etykieta (url) i przed wysłaniem przez Twilio dzieli długie odpowiedzi na fragmenty o maksymalnej długości textChunkLimit znaków (domyślnie 1500).

Weryfikacja konfiguracji

Po uruchomieniu Gatewaya:

1. Potwierdź, że dziennik Gateway zawiera trasę webhooka SMS.
2. Uruchom test po stronie Twilio (sprawdza skonfigurowany adres URL/metodę webhooka Twilio oraz ostatnie błędy wiadomości przychodzących):

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

3. Wyślij SMS ze swojego telefonu na numer Twilio.
4. Uruchom openclaw pairing list sms.
5. Zatwierdź kod parowania za pomocą openclaw pairing approve sms <CODE>.
6. Wyślij kolejny SMS i potwierdź, że agent odpowiada.

Do testowania wyłącznie wiadomości wychodzących użyj:

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

Kompleksowy test z macOS iMessage/SMS

Na komputerze Mac, który może wysyłać SMS-y operatora za pośrednictwem aplikacji Messages, możesz użyć imsg, aby sterować stroną nadawcy bez korzystania z telefonu:

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

Pierwsza wiadomość powinna utworzyć żądanie parowania. Druga wiadomość powinna otrzymać odpowiedź agenta za pośrednictwem Twilio.

Bezpieczeństwo webhooka

Domyślnie OpenClaw weryfikuje X-Twilio-Signature przy użyciu publicWebhookUrl i authToken. Część adresu publicWebhookUrl określającą punkt końcowy musi być identyczna bajt po bajcie z adresem URL skonfigurowanym w Twilio, łącznie ze schematem, hostem, ścieżką i ciągiem zapytania. Zgodnie z wymaganiami Twilio OpenClaw wyklucza fragmenty nadpisywania parametrów połączenia Twilio (#...) z obliczania podpisu.

Trasa webhooka wymusza również, niezależnie od weryfikacji podpisu:

• Wyłącznie POST.
• Limit 30 żądań na minutę dla każdego źródłowego adresu IP (po przekroczeniu HTTP 429).
• Wartość AccountSid w danych musi być zgodna ze skonfigurowanym accountSid (w przeciwnym razie HTTP 403).
• Powtórzone wartości MessageSid są deduplikowane przez 10 minut.
• Pamięć podręczna powtórzeń każdego konta SMS przechowuje maksymalnie 10 000 aktywnych identyfikatorów SID wiadomości. Gdy wszystkie miejsca są zajęte przez aktywne wpisy, nowe webhooki dla tego konta są odrzucane w trybie zamkniętym z kodem HTTP 429 i nagłówkiem Retry-After, dopóki najstarszy wpis nie wygaśnie.
• Treści żądań większe niż 32 KB są odrzucane.

Twilio domyślnie nie ponawia żądań zakończonych kodem HTTP 429 ani nie dokumentuje obsługi nagłówka Retry-After. Nadpisania parametrów połączenia #rp=4xx i #rp=all włączają ponawianie dla kodów 4xx, ale Twilio ogranicza całą transakcję ponawiania do 15 sekund, więc próby mogą zakończyć się przed wygaśnięciem miejsca w pamięci podręcznej powtórzeń. Skonfiguruj zapasowy adres URL, jeśli inny moduł obsługi musi odbierać nieudane dostarczenia; traktuj kod 429 jako odrzucenie w trybie zamkniętym, a nie jako niezawodny mechanizm kontroli napływu.

Wyłącznie do lokalnego testowania tunelu możesz ustawić:

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

Nie wyłączaj weryfikacji podpisu w publicznym Gateway.

Konfiguracja wielu kont

Użyj accounts, jeśli obsługujesz więcej niż jeden numer 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"],        },      },    },  },}

Każde konto musi używać odrębnej wartości webhookPath; Gateway odmawia zarejestrowania trasy webhooka, której ścieżka należy już do innego konta. Zastępcze wartości ze zmiennych środowiskowych TWILIO_*/SMS_* dotyczą wyłącznie konta domyślnego; ustaw defaultAccount, aby wskazać inne konto domyślne.

Rozwiązywanie problemów

Twilio zwraca kod 403 lub OpenClaw odrzuca webhook

Sprawdź, czy publicWebhookUrl dokładnie odpowiada adresowi URL skonfigurowanemu w Twilio, łącznie ze schematem, hostem, ścieżką i ciągiem zapytania. Twilio podpisuje ciąg publicznego adresu URL, dlatego przepisywanie adresu przez serwer proxy i alternatywne nazwy hostów mogą uniemożliwić weryfikację podpisu.

Kod 403 z komunikatem Invalid account oznacza, że wartość AccountSid w danych przychodzących nie jest zgodna ze skonfigurowanym accountSid; sprawdź, czy webhook wskazuje konto będące właścicielem numeru.

Żądanie parowania nie pojawia się

Sprawdź adres URL i metodę webhooka Messaging numeru Twilio. Musi wskazywać adres URL webhooka SMS i używać metody POST. Potwierdź także, że Gateway jest dostępny z publicznego internetu lub przez tunel.

Jeśli dziennik wiadomości Twilio zawiera błąd 11200, Twilio zaakceptowało przychodzący SMS, ale nie mogło połączyć się z webhookiem. Sprawdź:

• W Twilio opcja Messaging > A message comes in wskazuje publicWebhookUrl.
• Metoda to POST.
• Tunel lub odwrotne proxy udostępnia dokładną ścieżkę webhookPath; w przypadku Tailscale Funnel uruchom tailscale funnel status i potwierdź, że na liście znajduje się /webhooks/sms.
• publicWebhookUrl używa tego samego schematu, hosta, ścieżki i ciągu zapytania, które wysyła Twilio, aby weryfikacja podpisu mogła odtworzyć podpisany adres URL.

Polecenie openclaw channels status --channel sms --probe wykrywa zarówno niezgodne ustawienia webhooka Twilio, jak i ostatnie błędy 11200.

Wysyłanie wiadomości wychodzących kończy się niepowodzeniem

Potwierdź, że wartości accountSid, authToken oraz fromNumber lub messagingServiceSid zostały rozpoznane. Jeśli korzystasz z próbnego konta Twilio, przed wysłaniem wychodzącego SMS-a może być konieczne zweryfikowanie numeru docelowego w Twilio.

Wiadomości docierają, ale agent nie odpowiada

Sprawdź dmPolicy i allowFrom. Przy domyślnej zasadzie pairing nadawca musi zostać zatwierdzony, zanim zwykłe interakcje z agentem zostaną przetworzone.