SMS

​

Voordat je begint

• 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.

​

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-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>

​

Configuratievoorbeelden

​

Configuratiebestand

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

​

Omgevingsvariabelen

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

​

SecretRef-auth-token

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

​

Afzender via Messaging Service

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

​

Standaarddoel voor uitgaande berichten

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

​

Toegangsbeheer

• 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.

{
  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

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

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

​

Installatie verifiëren

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 sms
openclaw 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.

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

​

End-to-endtest vanuit 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 "antwoord exact met SMS pong" --json

​

Webhookbeveiliging

• 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.

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

​

Configuratie met meerdere accounts

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

​

Problemen oplossen

​

Twilio retourneert 403 of OpenClaw weigert de Webhook

​

Er verschijnt geen koppelingsverzoek

• 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.

​

Uitgaande verzendingen mislukken

​

Berichten komen aan, maar de agent antwoordt niet