SMS

OpenClaw empfängt und sendet SMS über eine Twilio-Telefonnummer oder einen Messaging Service. Der Gateway registriert eine eingehende Webhook-Route (standardmäßig /webhooks/sms), validiert standardmäßig Twilio-Anfragesignaturen und sendet Antworten über die Messages API von Twilio zurück.

Status: offizielles Plugin, separat installiert. Nur Text: keine MMS/Medien, nur Direktnachrichten.

Voraussetzungen

Sie benötigen:

• Das offizielle SMS-Plugin, installiert mit openclaw plugins install @openclaw/sms.
• Ein Twilio-Konto mit einer SMS-fähigen Telefonnummer oder einem Twilio Messaging Service.
• Die Twilio Account SID und das Auth Token.
• Eine öffentliche HTTPS-URL, über die Ihr OpenClaw Gateway erreichbar ist.
• Eine Auswahl für die Absenderrichtlinie: pairing (Standard) für die private Nutzung, allowlist für vorab genehmigte Telefonnummern oder open nur für einen absichtlich öffentlichen SMS-Zugriff.

Eine Twilio-Nummer kann sowohl SMS als auch Sprachanrufe unterstützen, wenn sie über beide Funktionen verfügt. Der SMS-Webhook und der Sprach-Webhook werden in Twilio separat konfiguriert und verwenden separate Gateway-Pfade; diese Seite behandelt ausschließlich den SMS-Webhook.

Schnelleinrichtung

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>

Konfigurationsbeispiele

Alle Schlüssel befinden sich unter channels.sms (und je Konto unter channels.sms.accounts.<id>):

Konfigurationsdatei

Verwenden Sie die Einrichtung per Konfigurationsdatei, wenn die Kanaldefinition zusammen mit der Gateway-Konfiguration übertragen werden soll:

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

Umgebungsvariablen

Umgebungsvariablen gelten nur für das Standardkonto; Konfigurationswerte haben Vorrang vor Umgebungswerten.

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"

Aktivieren Sie anschließend den Kanal in der Konfiguration:

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

SecretRef-Auth-Token

authToken kann eine SecretRef (source: "env" | "file" | "exec") sein. Verwenden Sie diese Option, wenn der Gateway das Twilio Auth Token über die Secrets-Laufzeit von OpenClaw auflösen soll, anstatt es als Klartextkonfiguration zu speichern:

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

Die referenzierte Umgebungsvariable oder der Secret-Provider muss für die Gateway-Laufzeit sichtbar sein. Starten Sie verwaltete Gateway-Prozesse nach Änderungen an den Umgebungsvariablen des Hosts neu.

Messaging-Service-Absender

Verwenden Sie messagingServiceSid anstelle von fromNumber, wenn Twilio den Absender über einen Messaging Service auswählen soll:

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

Wenn nach der Auflösung von Konfiguration und Umgebungsvariablen sowohl fromNumber als auch messagingServiceSid vorhanden sind, wird fromNumber verwendet.

Standardziel für ausgehende Nachrichten

Legen Sie defaultTo fest, wenn Automatisierungen oder vom Agenten initiierte Zustellungen ein Standardziel verwenden sollen, falls ein Sendeablauf kein ausdrückliches Ziel angibt:

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

Zugriffskontrolle

channels.sms.dmPolicy steuert den direkten SMS-Zugriff:

• pairing (Standard): Unbekannte Absender erhalten einen Kopplungscode; genehmigen Sie ihn mit openclaw pairing approve sms <CODE>.
• allowlist: Nur Absender in allowFrom werden verarbeitet. Ein leeres allowFrom weist jeden Absender ab (der Gateway protokolliert beim Start eine Warnung).
• open: Die Konfigurationsvalidierung erfordert, dass allowFrom den Wert "*" enthält. Ohne den Platzhalter können nur aufgeführte Nummern chatten.
• disabled: Alle eingehenden DMs werden verworfen.

Einträge in allowFrom sollten Telefonnummern im E.164-Format sein, beispielsweise +15551234567. Die Präfixe sms: und twilio-sms: werden akzeptiert und normalisiert. Bevorzugen Sie für einen privaten Assistenten dmPolicy: "allowlist" mit ausdrücklich angegebenen Telefonnummern:

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

SMS senden

Wenn der SMS-Kanal ausgewählt ist, akzeptieren Ziele reine E.164-Nummern oder das Präfix sms::

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

Bei impliziter Kanalauswahl wählt das Präfix twilio-sms: diesen Kanal aus, ohne das Dienstpräfix sms: zu übernehmen, das iMessage zur Auswahl der SMS-Zustellung über den Mobilfunkanbieter für seine eigenen Ziele verwendet:

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

Die CLI erfordert ein ausdrückliches --target. defaultTo ist für Automatisierungen und vom Agenten initiierte Zustellpfade vorgesehen, bei denen das Ziel aus der Kanalkonfiguration aufgelöst werden kann.

Antworten des Agenten auf eingehende SMS-Unterhaltungen werden automatisch über den konfigurierten Twilio-Absender an den Absender zurückgesendet.

Die SMS-Ausgabe besteht aus reinem Text. OpenClaw entfernt Markdown, vereinfacht mit Code-Fences umschlossene Codeblöcke, schreibt Links als label (url) um und teilt lange Antworten vor dem Versand über Twilio in Abschnitte mit höchstens textChunkLimit Zeichen (Standardwert: 1500) auf.

Einrichtung überprüfen

Nach dem Start des Gateway:

1. Vergewissern Sie sich, dass das Gateway-Protokoll die SMS-Webhook-Route anzeigt.
2. Führen Sie eine Twilio-seitige Prüfung aus (überprüft die konfigurierte Twilio-Webhook-URL/-Methode und aktuelle Fehler bei eingehenden Nachrichten):

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

3. Senden Sie von Ihrem Telefon eine SMS an die Twilio-Nummer.
4. Führen Sie openclaw pairing list sms aus.
5. Genehmigen Sie den Kopplungscode mit openclaw pairing approve sms <CODE>.
6. Senden Sie eine weitere SMS und vergewissern Sie sich, dass der Agent antwortet.

Verwenden Sie für Tests, die nur ausgehende Nachrichten betreffen:

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

Ende-zu-Ende-Test über macOS iMessage/SMS

Auf einem Mac, der über Nachrichten Mobilfunk-SMS senden kann, können Sie imsg verwenden, um die Absenderseite zu steuern, ohne Ihr Telefon zu verwenden:

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

Die erste Nachricht sollte eine Kopplungsanfrage erstellen. Die zweite Nachricht sollte die Antwort des Agenten über Twilio empfangen.

Webhook-Sicherheit

Standardmäßig validiert OpenClaw X-Twilio-Signature mithilfe von publicWebhookUrl und authToken. Der Endpunktteil von publicWebhookUrl muss Byte für Byte mit der in Twilio konfigurierten URL übereinstimmen, einschließlich Schema, Host, Pfad und Abfragezeichenfolge. OpenClaw schließt Twilio-Verbindungsüberschreibungs-Fragmente (#...) von der Signaturberechnung aus, wie von Twilio vorgeschrieben.

Die Webhook-Route erzwingt unabhängig von der Signaturvalidierung außerdem:

• Nur POST.
• Budget für fehlgeschlagene Anfragen von 300 Anfragen pro Minute und SMS-Konto, Webhook-Route sowie aufgelöster Clientadresse. Alle Anfragen werden auf dieses Budget angerechnet, HTTP 429 wird jedoch erst angewendet, nachdem das Parsen des Anfragetexts, die Twilio-Validierung oder der Abgleich der AccountSid einer Anfrage fehlgeschlagen ist.
• Ratenbegrenzung für weiterleitbare Rückrufe von 30 akzeptierten Rückrufen pro Minute und SMS-Konto, Webhook-Route sowie aufgelöster Clientadresse, nachdem diese Prüfungen erfolgreich waren (darüber HTTP 429). Wenn die Signaturvalidierung deaktiviert ist, stellt dieses Limit von 30 pro Minute die Obergrenze für nicht authentifizierte Weiterleitungen dar.
• Clientadressen werden anhand der gemeinsamen Regeln des Gateway für vertrauenswürdige Proxys aufgelöst. Wenn gateway.trustedProxies den Reverse-Proxy enthält, der Twilio-Rückrufe weiterleitet, verwendet OpenClaw für diese Begrenzungen die weitergeleitete Clientadresse; andernfalls wird auf die direkte Socketadresse zurückgegriffen.
• AccountSid in den Nutzdaten muss mit dem konfigurierten accountSid übereinstimmen (andernfalls HTTP 403).
• Wiederholte MessageSid-Werte werden 10 Minuten lang dedupliziert.
• Der Wiederholungscache jedes SMS-Kontos bewahrt bis zu 10.000 aktive Nachrichten-SIDs auf. Wenn alle Plätze aktiv sind, werden neue Webhooks für dieses Konto mit HTTP 429 und einem Retry-After-Header abgelehnt, bis der älteste Platz abläuft.
• Anfragetexte über 32 KB werden abgelehnt.

Twilio wiederholt HTTP 429 standardmäßig nicht und dokumentiert keine Unterstützung für Retry-After. Die Verbindungsüberschreibungen #rp=4xx und #rp=all aktivieren Wiederholungsversuche bei 4xx-Antworten, Twilio begrenzt die gesamte Wiederholungstransaktion jedoch auf 15 Sekunden. Daher können die Wiederholungsversuche abgeschlossen sein, bevor ein Platz im Wiederholungscache abläuft. Konfigurieren Sie eine Fallback-URL, wenn ein anderer Handler fehlgeschlagene Zustellungen empfangen muss; behandeln Sie eine 429-Antwort als sicher ablehnende Zurückweisung und nicht als zuverlässigen Rückstau.

Nur für lokale Tunneltests können Sie Folgendes festlegen:

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

Verwenden Sie auf einem öffentlichen Gateway keine deaktivierte Signaturvalidierung.

Konfiguration mehrerer Konten

Verwenden Sie accounts, wenn Sie mehr als eine Twilio-Nummer betreiben:

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

Jedes Konto muss einen eigenen webhookPath verwenden; das Gateway verweigert die Registrierung einer Webhook-Route, deren Pfad bereits einem anderen Konto zugeordnet ist. Die Umgebungs-Fallbacks TWILIO_*/SMS_* gelten nur für das Standardkonto; legen Sie defaultAccount fest, um das Standardkonto zu ändern.

Fehlerbehebung

Twilio gibt 403 zurück oder OpenClaw lehnt den Webhook ab

Prüfen Sie, ob publicWebhookUrl exakt mit der in Twilio konfigurierten URL übereinstimmt, einschließlich Schema, Host, Pfad und Abfragezeichenfolge. Twilio signiert die öffentliche URL-Zeichenfolge, sodass Proxy-Umschreibungen und alternative Hostnamen die Signaturvalidierung beeinträchtigen können.

Eine 403-Antwort mit Invalid account bedeutet, dass AccountSid in den eingehenden Nutzdaten nicht mit dem konfigurierten accountSid übereinstimmt; prüfen Sie, ob der Webhook auf das Konto verweist, dem die Nummer gehört.

Es erscheint keine Kopplungsanfrage

Prüfen Sie die Messaging-Webhook-URL und -Methode der Twilio-Nummer. Sie muss auf die SMS-Webhook-URL verweisen und POST verwenden. Vergewissern Sie sich außerdem, dass das Gateway über das öffentliche Internet oder Ihren Tunnel erreichbar ist.

Wenn das Twilio-Nachrichtenprotokoll den Fehler 11200 anzeigt, hat Twilio die eingehende SMS akzeptiert, konnte Ihren Webhook jedoch nicht erreichen. Prüfen Sie Folgendes:

• Twilio Messaging > A message comes in verweist auf publicWebhookUrl.
• Die Methode lautet POST.
• Der Tunnel oder Reverse-Proxy stellt exakt webhookPath bereit; führen Sie für Tailscale Funnel tailscale funnel status aus und vergewissern Sie sich, dass /webhooks/sms aufgeführt ist.
• publicWebhookUrl verwendet dasselbe Schema, denselben Host, Pfad und dieselbe Abfragezeichenfolge, die Twilio sendet, damit die Signaturvalidierung die signierte URL reproduzieren kann.

openclaw channels status --channel sms --probe zeigt sowohl nicht übereinstimmende Twilio-Webhook-Einstellungen als auch aktuelle 11200-Fehler an.

Ausgehende Sendungen schlagen fehl

Vergewissern Sie sich, dass accountSid, authToken und entweder fromNumber oder messagingServiceSid aufgelöst werden. Wenn Sie ein Twilio-Testkonto verwenden, muss die Zielnummer möglicherweise in Twilio verifiziert werden, bevor ausgehende SMS gesendet werden können.

Nachrichten treffen ein, aber der Agent antwortet nicht

Prüfen Sie dmPolicy und allowFrom. Bei der standardmäßigen pairing-Richtlinie muss der Absender genehmigt sein, bevor normale Agenteninteraktionen verarbeitet werden.