Skip to main content
OpenClaw peut recevoir et envoyer des SMS via un numéro de téléphone Twilio ou un service de messagerie. Le Gateway enregistre une route de Webhook entrant, valide les signatures de requête Twilio par défaut et renvoie les réponses via l’API Messages de Twilio.

Pairing

La politique de messages directs par défaut pour les SMS est l’appairage.

Gateway security

Examinez l’exposition du Webhook et les contrôles d’accès des expéditeurs.

Channel troubleshooting

Diagnostics intercanaux et procédures de réparation.

​
Avant de commencer

Vous avez besoin de :
  • Le Plugin SMS officiel installé avec openclaw plugins install @openclaw/sms.
  • Un compte Twilio avec un numéro de téléphone compatible SMS, ou un service de messagerie Twilio.
  • Le SID de compte Twilio et le jeton d’authentification.
  • Une URL HTTPS publique qui atteint votre Gateway OpenClaw.
  • Un choix de politique d’expéditeur : pairing pour un usage privé, allowlist pour les numéros de téléphone préapprouvés, ou open uniquement pour un accès SMS volontairement public.
Utilisez un seul numéro Twilio pour les SMS et les appels vocaux si le numéro dispose des deux capacités. Configurez séparément le Webhook SMS et le Webhook vocal dans Twilio ; cette page couvre uniquement le Webhook SMS.

​
Configuration rapide

1

Installer le plugin

openclaw plugins install @openclaw/sms
2

Créer ou choisir un expéditeur Twilio

Dans Twilio, ouvrez Numéros de téléphone > Gérer > Numéros actifs et choisissez un numéro compatible SMS. Enregistrez :
  • SID du compte, par exemple ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Jeton d’authentification
  • Numéro de téléphone expéditeur, par exemple +15551234567
Si vous utilisez un service de messagerie plutôt qu’un numéro d’expéditeur fixe, enregistrez le SID du service de messagerie, par exemple MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
3

Configurer le canal SMS

Enregistrez ceci sous sms.patch.json5 et modifiez les espaces réservés :
{
  channels: {
    sms: {
      enabled: true,
      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      authToken: "twilio-auth-token",
      fromNumber: "+15551234567",
      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
      dmPolicy: "pairing",
    },
  },
}
Appliquez-le :
openclaw config patch --file ./sms.patch.json5 --dry-run
openclaw config patch --file ./sms.patch.json5
4

Pointer Twilio vers le Webhook du Gateway

Dans les paramètres du numéro de téléphone Twilio, ouvrez Messagerie et définissez Un message arrive sur :
https://gateway.example.com/webhooks/sms
Utilisez HTTP POST. Le chemin local par défaut est /webhooks/sms ; modifiez channels.sms.webhookPath si vous avez besoin d’une route différente.
5

Exposer le chemin exact du Webhook SMS

Votre URL publique doit router le chemin SMS vers le processus Gateway. Si vous utilisez Tailscale Funnel pour les tests locaux, exposez explicitement /webhooks/sms :
tailscale funnel --bg --set-path /webhooks/sms http://127.0.0.1:<gateway-port>/webhooks/sms
tailscale funnel status
Les appels vocaux et les SMS utilisent des chemins de Webhook distincts. Si le même numéro Twilio gère les deux, conservez les deux routes configurées dans Twilio et dans votre tunnel.
6

Démarrer le Gateway et approuver le premier expéditeur

openclaw gateway
Envoyez un SMS au numéro Twilio. Le premier message crée une demande d’appairage. Approuvez-la :
openclaw pairing list sms
openclaw pairing approve sms <CODE>
Les codes d’appairage expirent après 1 heure.

​
Exemples de configuration

​
Fichier de configuration

Utilisez la configuration par fichier lorsque vous voulez que la définition du canal soit transportée avec la configuration du Gateway : 
{
  channels: {
    sms: {
      enabled: true,
      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      authToken: "twilio-auth-token",
      fromNumber: "+15551234567",
      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
      dmPolicy: "pairing",
    },
  },
}

​
Variables d’environnement

Utilisez la configuration par variables d’environnement pour les déploiements à compte unique où les secrets proviennent de l’environnement hôte : 
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"
Activez ensuite le canal dans la configuration : 
{
  channels: {
    sms: {
      enabled: true,
      dmPolicy: "pairing",
    },
  },
}
TWILIO_SMS_FROM est accepté comme alias de TWILIO_PHONE_NUMBER. Utilisez TWILIO_MESSAGING_SERVICE_SID au lieu d’un expéditeur par numéro de téléphone lorsque Twilio doit choisir l’expéditeur à partir d’un service de messagerie.

​
Jeton d’authentification SecretRef

authToken peut être une SecretRef. Utilisez ceci lorsque le Gateway doit résoudre le jeton d’authentification Twilio depuis l’environnement d’exécution des secrets OpenClaw au lieu de stocker la configuration en texte clair : 
{
  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",
    },
  },
}
La variable d’environnement ou le fournisseur de secrets référencé doit être visible par l’environnement d’exécution du Gateway. Redémarrez les processus Gateway gérés après avoir modifié les variables d’environnement de l’hôte.

​
Numéro privé uniquement sur liste d’autorisation

Utilisez allowlist lorsque seuls des numéros de téléphone connus doivent pouvoir parler à l’agent : 
{
  channels: {
    sms: {
      enabled: true,
      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      authToken: "twilio-auth-token",
      fromNumber: "+15551234567",
      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
      dmPolicy: "allowlist",
      allowFrom: ["+15557654321"],
    },
  },
}

​
Expéditeur via service de messagerie

Utilisez messagingServiceSid au lieu de fromNumber lorsque Twilio doit choisir l’expéditeur via un service de messagerie : 
{
  channels: {
    sms: {
      enabled: true,
      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      authToken: "twilio-auth-token",
      messagingServiceSid: "MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
      dmPolicy: "pairing",
    },
  },
}
Si fromNumber et messagingServiceSid sont tous deux présents après la résolution de la configuration et des variables d’environnement, fromNumber est utilisé.

​
Cible sortante par défaut

Définissez defaultTo lorsque l’automatisation ou la livraison initiée par l’agent doit avoir une destination par défaut si un flux d’envoi omet une cible explicite : 
{
  channels: {
    sms: {
      enabled: true,
      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      authToken: "twilio-auth-token",
      fromNumber: "+15551234567",
      defaultTo: "+15557654321",
      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
    },
  },
}

​
Contrôle d’accès

channels.sms.dmPolicy contrôle l’accès direct par SMS :
  • pairing (par défaut)
  • allowlist (nécessite au moins un expéditeur dans allowFrom)
  • open (nécessite que allowFrom inclue "*")
  • disabled
Les entrées allowFrom doivent être des numéros de téléphone E.164 comme +15551234567. Les préfixes sms: sont acceptés et normalisés. Pour un assistant privé, privilégiez dmPolicy: "allowlist" avec des numéros de téléphone explicites.

​
Envoyer des SMS

Les cibles SMS sortantes utilisent le préfixe de service sms: avec le canal SMS sélectionné : 
openclaw message send --channel sms --target sms:+15551234567 --message "hello"
Lorsque la sélection du canal est implicite, twilio-sms:+15551234567 sélectionne ce canal sans prendre le contrôle du préfixe de service sms: existant, détenu par le canal et utilisé par iMessage. 
openclaw message send --target twilio-sms:+15551234567 --message "hello"
La CLI nécessite un --target explicite. defaultTo est destiné aux chemins d’automatisation et de livraison initiée par l’agent où la cible peut être résolue depuis la configuration du canal. Les réponses de l’agent issues de conversations SMS entrantes retournent automatiquement à l’expéditeur via l’expéditeur Twilio configuré. La sortie SMS est du texte brut. OpenClaw supprime le markdown, aplatit les blocs de code clôturés, préserve les liens lisibles et découpe les longues réponses avant de les envoyer via Twilio.

​
Vérifier la configuration

Après le démarrage du Gateway :
  1. Confirmez que le journal du Gateway affiche la route du Webhook SMS.
  2. Exécutez une sonde côté Twilio :
openclaw channels capabilities --channel sms
openclaw channels status --channel sms --probe --json
  1. Envoyez un SMS au numéro Twilio depuis votre téléphone.
  2. Exécutez openclaw pairing list sms.
  3. Approuvez le code d’appairage avec openclaw pairing approve sms <CODE>.
  4. Envoyez un autre SMS et confirmez que l’agent répond.
Pour les tests sortants uniquement, utilisez : 
openclaw message send --channel sms --target sms:+15557654321 --message "OpenClaw SMS test"

​
Test de bout en bout depuis macOS iMessage/SMS

Sur un Mac capable d’envoyer des SMS opérateur via Messages, vous pouvez utiliser imsg pour piloter le côté expéditeur sans toucher à votre téléphone : 
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
Le premier message doit créer une demande d’appairage. Le second message doit recevoir la réponse de l’agent via Twilio.

​
Sécurité du Webhook

Par défaut, OpenClaw valide X-Twilio-Signature à l’aide de publicWebhookUrl et authToken. Gardez publicWebhookUrl aligné octet pour octet avec l’URL configurée dans Twilio, y compris le schéma, l’hôte, le chemin et la chaîne de requête. Pour les tests de tunnel local uniquement, vous pouvez définir : 
{
  channels: {
    sms: {
      dangerouslyDisableSignatureValidation: true,
    },
  },
}
N’utilisez pas la validation de signature désactivée sur un Gateway public.

​
Configuration multi-comptes

Utilisez accounts lorsque vous exploitez plusieurs numéros Twilio : 
{
  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"],
        },
      },
    },
  },
}
Chaque compte doit utiliser un webhookPath distinct.

​
Dépannage

​
Twilio renvoie 403 ou OpenClaw rejette le Webhook

Vérifiez que publicWebhookUrl correspond exactement à l’URL configurée dans Twilio, y compris le schéma, l’hôte, le chemin et la chaîne de requête. Twilio signe la chaîne d’URL publique ; les réécritures de proxy et les noms d’hôte alternatifs peuvent donc casser la validation de signature.

​
Aucune demande d’appairage n’apparaît

Vérifiez l’URL et la méthode du Webhook Messagerie du numéro Twilio. Il doit pointer vers l’URL du Webhook SMS et utiliser POST. Confirmez également que le Gateway est accessible depuis Internet public ou via votre tunnel. Si le journal des messages Twilio affiche l’erreur 11200, Twilio a accepté le SMS entrant mais n’a pas pu atteindre votre Webhook. Vérifiez :
  • Messagerie > Un message arrive dans Twilio pointe vers publicWebhookUrl.
  • La méthode est POST.
  • Le tunnel ou le proxy inverse expose le webhookPath exact ; pour Tailscale Funnel, exécutez tailscale funnel status et confirmez que /webhooks/sms est répertorié.
  • publicWebhookUrl utilise les mêmes schéma, hôte, chemin et chaîne de requête que ceux envoyés par Twilio, afin que la validation de signature puisse reproduire l’URL signée.

​
Les envois sortants échouent

Confirmez que accountSid, authToken, et soit fromNumber soit messagingServiceSid sont résolus. Si vous utilisez un compte Twilio d’essai, le numéro de destination devra peut-être être vérifié dans Twilio avant que les SMS sortants puissent être envoyés.

​
Les messages arrivent mais l’agent ne répond pas

Vérifiez dmPolicy et allowFrom. Avec la stratégie pairing par défaut, l’expéditeur doit être approuvé avant que les tours d’agent normaux soient traités.