SMS

OpenClaw empfängt und sendet SMS über eine Twilio-Telefonnummer oder einen Messaging Service. Das 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.

Bevor Sie beginnen

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 der Absenderrichtlinie: pairing (Standard) für die private Nutzung, allowlist für vorab genehmigte Telefonnummern oder open nur für bewusst öffentlichen SMS-Zugriff.

Eine Twilio-Nummer kann sowohl SMS als auch Sprachanrufe bedienen, wenn sie beide Funktionen unterstützt. Der SMS-Webhook und der Sprach-Webhook werden in Twilio separat konfiguriert und verwenden separate Gateway-Pfade; diese Seite behandelt nur 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 pro 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-Authentifizierungstoken

authToken kann eine SecretRef (source: "env" | "file" | "exec") sein. Verwenden Sie dies, wenn das Gateway das Twilio Auth Token über die OpenClaw-Secrets-Laufzeit auflösen soll, anstatt eine 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 neu, nachdem Sie Host-Umgebungsvariablen geändert haben.

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 Umgebung 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 lehnt jeden Absender ab (das Gateway protokolliert beim Start eine Warnung).
• open: Die Konfigurationsvalidierung erfordert, dass allowFrom "*" enthält. Ohne Platzhalter können nur aufgeführte Nummern chatten.
• disabled: Alle eingehenden DMs werden verworfen.

Einträge in allowFrom sollten Telefonnummern im E.164-Format wie +15551234567 sein. Die Präfixe sms: und twilio-sms: werden akzeptiert und normalisiert. Bevorzugen Sie für einen privaten Assistenten dmPolicy: "allowlist" mit ausdrücklichen 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"

Wenn die Kanalauswahl implizit erfolgt, wählt das Präfix twilio-sms: diesen Kanal aus, ohne das Dienstpräfix sms: zu übernehmen, das iMessage verwendet, um für seine eigenen Ziele die SMS-Zustellung über den Mobilfunkanbieter auszuwählen:

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

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

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

Die SMS-Ausgabe besteht aus reinem Text. OpenClaw entfernt Markdown, wandelt mit Codezäunen versehene Codeblöcke in Fließtext um, schreibt Links als label (url) um und teilt lange Antworten vor dem Versand über Twilio in Abschnitte mit höchstens textChunkLimit Zeichen (standardmäßig 1500) auf.

Einrichtung überprüfen

Nach dem Start des Gateways:

1. Vergewissern Sie sich, dass im Gateway-Protokoll die SMS-Webhook-Route angezeigt wird.
2. Führen Sie eine Twilio-seitige Prüfung aus (prü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 ausschließlich ausgehender Nachrichten:

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

End-to-End-Test über macOS iMessage/SMS

Auf einem Mac, der über Nachrichten Mobilfunk-SMS senden kann, können Sie mit imsg die Absenderseite 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 bytegenau 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.

Unabhängig von der Signaturvalidierung erzwingt die Webhook-Route außerdem Folgendes:

• Nur POST.
• Ratenbegrenzung auf 30 Anfragen pro Minute und Quell-IP (darüber HTTP 429).
• AccountSid in der Nutzlast muss mit dem konfigurierten accountSid übereinstimmen (andernfalls HTTP 403).
• Wiederholte MessageSid-Werte werden 10 Minuten lang dedupliziert.
• Der Wiederholungs-Cache jedes SMS-Kontos behält bis zu 10.000 aktive Nachrichten-SIDs. Wenn alle Plätze aktiv sind, werden neue Webhooks für dieses Konto bis zum Ablauf des ältesten Platzes mit HTTP 429 und einem Retry-After-Header abgewiesen.
• Anfragetexte mit mehr als 32 KB werden abgewiesen.

Twilio wiederholt HTTP-429-Anfragen standardmäßig nicht und dokumentiert keine Unterstützung für Retry-After. Die Verbindungsüberschreibungen #rp=4xx und #rp=all aktivieren Wiederholungen bei 4xx-Fehlern, Twilio begrenzt die gesamte Wiederholungstransaktion jedoch auf 15 Sekunden. Daher können die Wiederholungen abgeschlossen sein, bevor ein Platz im Wiederholungs-Cache abläuft. Konfigurieren Sie eine Fallback-URL, wenn ein anderer Handler fehlgeschlagene Zustellungen empfangen muss. Behandeln Sie einen 429-Status als geschlossene Ablehnung bei Fehlern und nicht als zuverlässigen Rückstau.

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

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

Verwenden Sie keine deaktivierte Signaturvalidierung auf einem öffentlichen Gateway.

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 mit defaultAccount fest, welches Konto das Standardkonto ist.

Fehlerbehebung

Twilio gibt 403 zurück oder OpenClaw weist 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 Umschreibungen durch Proxys und alternative Hostnamen die Signaturvalidierung beeinträchtigen können.

Ein 403-Status mit Invalid account bedeutet, dass AccountSid in der eingehenden Nutzlast 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 Webhook-URL und -Methode unter Messaging für die 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 im Twilio-Nachrichtenprotokoll der Fehler 11200 angezeigt wird, 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 ist POST.
• Der Tunnel oder Reverse-Proxy stellt den exakten 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.

Das Senden ausgehender Nachrichten schlägt 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 werden, bevor normale Agent-Durchläufe verarbeitet werden.