SMS

​

Voraussetzungen

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

​

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

​

Konfigurationsbeispiele

​

Konfigurationsdatei

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

​

Umgebungsvariablen

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

​

Messaging-Service-Absender

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

​

Standardziel für ausgehende Nachrichten

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

​

Zugriffskontrolle

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

{
  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

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

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

​

Einrichtung überprüfen

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

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

​

Ende-zu-Ende-Test über 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 "reply exactly SMS pong" --json

​

Webhook-Sicherheit

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

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

​

Konfiguration mehrerer Konten

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

​

Fehlerbehebung

​

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

​

Es erscheint keine Kopplungsanfrage

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

​

Ausgehende Sendungen schlagen fehl

​

Nachrichten treffen ein, aber der Agent antwortet nicht