SMS

OpenClaw ontvangt en verzendt sms-berichten via een Twilio-telefoonnummer of Messaging Service. De Gateway registreert een inkomende Webhook-route (standaard /webhooks/sms), valideert standaard de handtekeningen van Twilio-verzoeken en verzendt antwoorden via Twilio's Messages API.

Status: officiële Plugin, afzonderlijk geïnstalleerd. Alleen tekst: geen mms/media, alleen directe berichten.

Voordat je begint

Je hebt het volgende nodig:

• De officiële sms-Plugin, geïnstalleerd met openclaw plugins install @openclaw/sms.
• Een Twilio-account met een telefoonnummer dat sms ondersteunt, of een Twilio Messaging Service.
• De Twilio Account SID en Auth Token.
• Een openbare HTTPS-URL die je OpenClaw Gateway bereikt.
• Een keuze voor het afzenderbeleid: pairing (standaard) voor privégebruik, allowlist voor vooraf goedgekeurde telefoonnummers, of open uitsluitend voor bewust openbare sms-toegang.

Eén Twilio-nummer kan zowel sms als spraakoproepen ondersteunen als het over beide mogelijkheden beschikt. De sms-Webhook en spraak-Webhook worden afzonderlijk geconfigureerd in Twilio en gebruiken afzonderlijke Gateway-paden; deze pagina behandelt alleen de sms-Webhook.

Snelle configuratie

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>

Configuratievoorbeelden

Alle sleutels staan onder channels.sms (en per account onder channels.sms.accounts.<id>):

Configuratiebestand

Gebruik configuratie via een bestand als je wilt dat de kanaaldefinitie deel uitmaakt van de Gateway-configuratie:

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

Omgevingsvariabelen

Omgevingsvariabelen zijn alleen van toepassing op het standaardaccount; configuratiewaarden hebben voorrang op omgevingswaarden.

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"

Schakel vervolgens het kanaal in de configuratie in:

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

SecretRef-auth-token

authToken kan een SecretRef (source: "env" | "file" | "exec") zijn. Gebruik dit wanneer de Gateway de Twilio Auth Token via de OpenClaw-secretsruntime moet ophalen in plaats van deze als platte tekst in de configuratie op te slaan:

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

De omgevingsvariabele of geheime provider waarnaar wordt verwezen, moet zichtbaar zijn voor de Gateway-runtime. Start beheerde Gateway-processen opnieuw nadat je omgevingsvariabelen van de host hebt gewijzigd.

Afzender via Messaging Service

Gebruik messagingServiceSid in plaats van fromNumber wanneer Twilio de afzender via een Messaging Service moet kiezen:

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

Als zowel fromNumber als messagingServiceSid aanwezig zijn nadat configuratie- en omgevingswaarden zijn verwerkt, wordt fromNumber gebruikt.

Standaarddoel voor uitgaande berichten

Stel defaultTo in wanneer automatisering of door een agent geïnitieerde bezorging een standaardbestemming moet hebben als een verzendproces geen expliciet doel opgeeft:

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

Toegangsbeheer

channels.sms.dmPolicy beheert directe sms-toegang:

• pairing (standaard): onbekende afzenders ontvangen een koppelingscode; keur deze goed met openclaw pairing approve sms <CODE>.
• allowlist: alleen afzenders in allowFrom worden verwerkt. Een lege allowFrom weigert elke afzender (de Gateway registreert een opstartwaarschuwing).
• open: configuratievalidatie vereist dat allowFrom "*" bevat. Zonder het jokerteken kunnen alleen vermelde nummers chatten.
• disabled: alle inkomende DM's worden verwijderd.

Vermeldingen in allowFrom moeten E.164-telefoonnummers zijn, zoals +15551234567. De voorvoegsels sms: en twilio-sms: worden geaccepteerd en genormaliseerd. Geef voor een privéassistent de voorkeur aan dmPolicy: "allowlist" met expliciete telefoonnummers:

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

Sms verzenden

Als het sms-kanaal is geselecteerd, accepteren doelen kale E.164-nummers of het voorvoegsel sms::

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

Wanneer kanaalselectie impliciet is, selecteert het voorvoegsel twilio-sms: dit kanaal zonder het servicevoorvoegsel sms: over te nemen, dat iMessage gebruikt om sms-bezorging via een provider te kiezen voor zijn eigen doelen:

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

De CLI vereist een expliciete --target. defaultTo is bedoeld voor automatisering en door een agent geïnitieerde bezorgingspaden waarbij het doel uit de kanaalconfiguratie kan worden afgeleid.

Agentantwoorden op inkomende sms-gesprekken worden automatisch via de geconfigureerde Twilio-afzender teruggestuurd naar de afzender.

Sms-uitvoer is platte tekst. OpenClaw verwijdert Markdown, maakt omheinde codeblokken plat, herschrijft links als label (url) en splitst lange antwoorden in delen van maximaal textChunkLimit tekens (standaard 1500) voordat ze via Twilio worden verzonden.

Installatie verifiëren

Nadat de Gateway is gestart:

1. Controleer of het Gateway-logboek de sms-Webhookroute toont.
2. Voer een controle aan de Twilio-zijde uit (controleert de geconfigureerde Twilio-Webhook-URL/-methode en recente fouten bij inkomende berichten):

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

3. Stuur vanaf je telefoon een sms naar het Twilio-nummer.
4. Voer openclaw pairing list sms uit.
5. Keur de koppelingscode goed met openclaw pairing approve sms <CODE>.
6. Stuur nog een sms en controleer of de agent antwoordt.

Gebruik voor tests met alleen uitgaande berichten:

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

End-to-endtest vanuit macOS iMessage/sms

Op een Mac die via Berichten sms-berichten via de provider kan verzenden, kun je imsg gebruiken om de afzenderzijde aan te sturen zonder je telefoon aan te raken:

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 "antwoord exact met SMS pong" --json

Het eerste bericht moet een koppelingsverzoek aanmaken. Het tweede bericht moet het antwoord van de agent via Twilio ontvangen.

Webhookbeveiliging

OpenClaw valideert standaard X-Twilio-Signature met publicWebhookUrl en authToken. Houd het eindpuntgedeelte van publicWebhookUrl byte voor byte gelijk aan de URL die in Twilio is geconfigureerd, inclusief schema, host, pad en querytekenreeks. OpenClaw sluit Twilio-connection-override-fragmenten (#...) uit van de handtekeningberekening, zoals Twilio vereist.

De Webhookroute dwingt daarnaast, onafhankelijk van handtekeningvalidatie, het volgende af:

• Alleen POST.
• Budget voor mislukte aanvragen van 300 aanvragen per minuut per sms-account, Webhookroute en herleid clientadres. Alle aanvragen tellen mee voor dit budget, maar HTTP 429 wordt pas toegepast nadat het parseren van de aanvraagbody, de Twilio-validatie of de AccountSid-controle mislukt.
• Snelheidslimiet voor doorstuurbare callbacks van 30 geaccepteerde callbacks per minuut per sms-account, Webhookroute en herleid clientadres nadat deze controles zijn geslaagd (daarboven HTTP 429). Als handtekeningvalidatie is uitgeschakeld, is deze limiet van 30/min de bovengrens voor niet-geverifieerde doorsturing.
• Clientadressen worden herleid via de gedeelde regels voor vertrouwde proxy's van de Gateway. Als gateway.trustedProxies de reverse proxy bevat die Twilio-callbacks doorstuurt, baseert OpenClaw deze limieten op het doorgestuurde clientadres; anders wordt teruggevallen op het directe socketadres.
• De AccountSid in de payload moet overeenkomen met de geconfigureerde accountSid (anders HTTP 403).
• Opnieuw afgespeelde waarden van MessageSid worden gedurende 10 minuten gededupliceerd.
• De replaycache van elk sms-account bewaart maximaal 10.000 actieve bericht-SID's. Wanneer alle plaatsen bezet zijn, worden nieuwe Webhooks voor dat account standaard geweigerd met HTTP 429 en een Retry-After-header totdat de oudste plaats verloopt.
• Aanvraagbody's groter dan 32 KB worden geweigerd.

Twilio probeert HTTP 429 standaard niet opnieuw en documenteert geen ondersteuning voor Retry-After. De verbindingsoverschrijvingen #rp=4xx en #rp=all schakelen nieuwe pogingen bij 4xx-fouten in, maar Twilio beperkt de volledige transactie met nieuwe pogingen tot 15 seconden. Daardoor kunnen de pogingen nog steeds eindigen voordat een plaats in de replaycache verloopt. Configureer een fallback-URL wanneer een andere handler mislukte leveringen moet ontvangen; behandel een 429 als een standaardweigering, niet als betrouwbare tegendruk.

Alleen voor lokale tunnelingtests kun je het volgende instellen:

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

Gebruik uitgeschakelde handtekeningvalidatie niet op een openbare Gateway.

Configuratie met meerdere accounts

Gebruik accounts wanneer je meer dan één Twilio-nummer beheert:

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

Elk account moet een afzonderlijke webhookPath gebruiken; de Gateway weigert een Webhookroute te registreren waarvan het pad al eigendom is van een ander account. Omgevingsfallbacks voor TWILIO_*/SMS_* zijn alleen van toepassing op het standaardaccount; stel defaultAccount in om te wijzigen welk account dat is.

Problemen oplossen

Twilio retourneert 403 of OpenClaw weigert de Webhook

Controleer of publicWebhookUrl exact overeenkomt met de URL die in Twilio is geconfigureerd, inclusief schema, host, pad en querytekenreeks. Twilio ondertekent de openbare URL-tekenreeks, waardoor herschrijvingen door proxy's en alternatieve hostnamen de handtekeningvalidatie kunnen verstoren.

Een 403 met Invalid account betekent dat de AccountSid van de inkomende payload niet overeenkomt met de geconfigureerde accountSid; controleer of de Webhook verwijst naar het account dat eigenaar is van het nummer.

Er verschijnt geen koppelingsverzoek

Controleer de Messaging-Webhook-URL en -methode van het Twilio-nummer. Deze moet naar de sms-Webhook-URL verwijzen en POST gebruiken. Controleer ook of de Gateway bereikbaar is vanaf het openbare internet of via je tunnel.

Als het Twilio-berichtenlogboek fout 11200 toont, heeft Twilio de inkomende sms geaccepteerd, maar kon het je Webhook niet bereiken. Controleer het volgende:

• Twilio Messaging > A message comes in verwijst naar publicWebhookUrl.
• De methode is POST.
• De tunnel of reverse proxy stelt exact webhookPath beschikbaar; voer voor Tailscale Funnel tailscale funnel status uit en controleer of /webhooks/sms wordt vermeld.
• publicWebhookUrl gebruikt hetzelfde schema, dezelfde host, hetzelfde pad en dezelfde querytekenreeks die Twilio verzendt, zodat handtekeningvalidatie de ondertekende URL kan reproduceren.

openclaw channels status --channel sms --probe toont zowel niet-overeenkomende Twilio-Webhookinstellingen als recente 11200-fouten.

Uitgaande verzendingen mislukken

Controleer of accountSid, authToken en fromNumber of messagingServiceSid zijn herleid. Als je een proefaccount van Twilio gebruikt, moet het bestemmingsnummer mogelijk in Twilio worden geverifieerd voordat uitgaande sms-berichten kunnen worden verzonden.

Berichten komen aan, maar de agent antwoordt niet

Controleer dmPolicy en allowFrom. Met het standaardbeleid pairing moet de afzender zijn goedgekeurd voordat normale agentbeurten worden verwerkt.