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 Twilio-aanvraaghandtekeningen en verzendt antwoorden terug via de Messages API van Twilio.

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

Voordat u begint

U 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 uw 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 verwerken 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 installatie

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 bevinden zich onder channels.sms (en per account onder channels.sms.accounts.<id>):

Configuratiebestand

Gebruik configuratie via een bestand als u wilt dat de kanaaldefinitie onderdeel is 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 voor het authenticatietoken

authToken kan een SecretRef zijn (source: "env" | "file" | "exec"). Gebruik dit wanneer de Gateway het Twilio Auth Token via de OpenClaw-runtime voor geheimen moet ophalen in plaats van configuratie als leesbare tekst 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 provider van geheimen waarnaar wordt verwezen, moet zichtbaar zijn voor de Gateway-runtime. Start beheerde Gateway-processen opnieuw nadat u 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 de configuratie en omgevingsvariabelen zijn verwerkt, wordt fromNumber gebruikt.

Standaarddoel voor uitgaande berichten

Stel defaultTo in wanneer automatisering of door een agent geïnitieerde aflevering een standaardbestemming moet hebben als een verzendstroom 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 krijgen 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 waarschuwing bij het opstarten).
• open: configuratievalidatie vereist dat allowFrom "*" bevat. Zonder het jokerteken kunnen alleen vermelde nummers chatten.
• disabled: alle inkomende directe berichten worden genegeerd.

Vermeldingen in allowFrom moeten E.164-telefoonnummers zijn, zoals +15551234567. De voorvoegsels sms: en twilio-sms: worden geaccepteerd en genormaliseerd. Gebruik voor een privéassistent bij voorkeur 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-berichten verzenden

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

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

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

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

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

Antwoorden van agents 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 koppelingen als label (url) en splitst lange antwoorden in segmenten 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-Webhook-route weergeeft.
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 uw 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 Messages sms-berichten over het mobiele netwerk kan verzenden, kunt u imsg gebruiken om de verzendende kant aan te sturen zonder uw 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 "reply exactly SMS pong" --json

Het eerste bericht hoort een koppelingsverzoek te maken. Het tweede bericht hoort via Twilio het antwoord van de agent te ontvangen.

Webhook-beveiliging

OpenClaw valideert standaard X-Twilio-Signature met publicWebhookUrl en authToken. Zorg dat het eindpuntgedeelte van publicWebhookUrl byte voor byte overeenkomt met de in Twilio geconfigureerde URL, inclusief schema, host, pad en querytekenreeks. OpenClaw sluit Twilio-fragmenten voor verbindingsoverschrijvingen (#...) uit van de handtekeningberekening, zoals Twilio vereist.

De Webhook-route dwingt daarnaast, onafhankelijk van handtekeningvalidatie, het volgende af:

• Alleen POST.
• Een limiet van 30 verzoeken per minuut per bron-IP-adres (daarboven HTTP 429).
• AccountSid in de payload moet overeenkomen met de geconfigureerde accountSid (anders HTTP 403).
• Opnieuw afgespeelde MessageSid-waarden worden gedurende 10 minuten gededupliceerd.
• De replaycache van elk sms-account bewaart maximaal 10.000 actieve bericht-SID's. Wanneer elke positie actief is, worden nieuwe Webhooks voor dat account standaard geweigerd met HTTP 429 en een Retry-After-header totdat de oudste positie verloopt.
• Verzoeklichamen 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 voor 4xx-fouten in, maar Twilio beperkt de volledige transactie met nieuwe pogingen tot 15 seconden. Daardoor kunnen de pogingen nog steeds eindigen voordat een positie in de replaycache verloopt. Configureer een terugval-URL wanneer een andere afhandelaar mislukte leveringen moet ontvangen; behandel een 429 als een standaardweigering, niet als betrouwbare tegendruk.

Alleen voor lokale tests via een tunnel kunt u het volgende instellen:

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

Gebruik uitgeschakelde handtekeningvalidatie niet op een openbare Gateway.

Configuratie voor meerdere accounts

Gebruik accounts wanneer u 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 afzonderlijk webhookPath gebruiken; de Gateway weigert een Webhook-route te registreren waarvan het pad al eigendom is van een ander account. Terugvalwaarden uit de omgevingsvariabelen TWILIO_*/SMS_* zijn alleen van toepassing op het standaardaccount; stel defaultAccount in om te wijzigen welk account dat is.

Probleemoplossing

Twilio retourneert 403 of OpenClaw weigert de Webhook

Controleer of publicWebhookUrl exact overeenkomt met de in Twilio geconfigureerde URL, 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 Webhook-URL en -methode onder Messaging voor het Twilio-nummer. Deze moet verwijzen naar de SMS-Webhook-URL en POST gebruiken. Controleer ook of de Gateway bereikbaar is vanaf het openbare internet of via uw tunnel.

Als het Twilio-berichtenlogboek fout 11200 weergeeft, heeft Twilio de inkomende sms geaccepteerd, maar kon het uw 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 het exacte 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 als Twilio verzendt, zodat de handtekeningvalidatie de ondertekende URL kan reproduceren.

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

Uitgaande verzendingen mislukken

Controleer of accountSid, authToken en fromNumber of messagingServiceSid zijn herleid. Als u 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 agentinteracties worden verwerkt.