SMS

OpenClaw recibe y envía SMS mediante un número de teléfono de Twilio o un Messaging Service. El Gateway registra una ruta de Webhook entrante (de forma predeterminada, /webhooks/sms), valida de forma predeterminada las firmas de las solicitudes de Twilio y envía las respuestas mediante la API Messages de Twilio.

Estado: Plugin oficial, instalado por separado. Solo texto: sin MMS ni contenido multimedia; únicamente mensajes directos.

Antes de comenzar

Se necesita:

• El Plugin oficial de SMS instalado con openclaw plugins install @openclaw/sms.
• Una cuenta de Twilio con un número de teléfono compatible con SMS o un Twilio Messaging Service.
• El Account SID y el Auth Token de Twilio.
• Una URL HTTPS pública que llegue al Gateway de OpenClaw.
• Una política de remitentes: pairing (predeterminada) para uso privado, allowlist para números de teléfono aprobados previamente o open únicamente para un acceso por SMS intencionadamente público.

Un número de Twilio puede servir tanto para SMS como para llamadas de voz si dispone de ambas capacidades. El Webhook de SMS y el Webhook de voz se configuran por separado en Twilio y utilizan rutas distintas del Gateway; esta página solo aborda el Webhook de SMS.

Configuración rápida

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>

Ejemplos de configuración

Todas las claves se encuentran en channels.sms (y, para cada cuenta, en channels.sms.accounts.<id>):

Archivo de configuración

Utilice la configuración mediante archivo cuando quiera que la definición del canal forme parte de la configuración del Gateway:

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

Variables de entorno

Las variables de entorno solo se aplican a la cuenta predeterminada; los valores de configuración tienen prioridad sobre los valores del entorno.

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"

Después, active el canal en la configuración:

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

Auth Token mediante SecretRef

authToken puede ser una SecretRef (source: "env" | "file" | "exec"). Utilice esta opción cuando el Gateway deba resolver el Auth Token de Twilio mediante el entorno de ejecución de secretos de OpenClaw en lugar de almacenarlo como configuración en texto sin formato:

{  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 de entorno o el proveedor de secretos al que se hace referencia debe ser visible para el entorno de ejecución del Gateway. Reinicie los procesos administrados del Gateway después de cambiar las variables de entorno del host.

Remitente mediante Messaging Service

Utilice messagingServiceSid en lugar de fromNumber cuando Twilio deba elegir el remitente mediante un Messaging Service:

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

Si tanto fromNumber como messagingServiceSid están presentes después de resolver la configuración y el entorno, se utiliza fromNumber.

Destino saliente predeterminado

Establezca defaultTo cuando la automatización o las entregas iniciadas por agentes deban tener un destino predeterminado si un flujo de envío omite un destino explícito:

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

Control de acceso

channels.sms.dmPolicy controla el acceso directo mediante SMS:

• pairing (predeterminado): los remitentes desconocidos reciben un código de emparejamiento; apruébelo con openclaw pairing approve sms <CODE>.
• allowlist: solo se procesan los remitentes incluidos en allowFrom. Un allowFrom vacío rechaza a todos los remitentes (el Gateway registra una advertencia al iniciarse).
• open: la validación de la configuración exige que allowFrom incluya "*". Sin el comodín, solo pueden conversar los números enumerados.
• disabled: se descartan todos los mensajes directos entrantes.

Las entradas de allowFrom deben ser números de teléfono en formato E.164, como +15551234567. Se aceptan y normalizan los prefijos sms: y twilio-sms:. Para un asistente privado, se recomienda dmPolicy: "allowlist" con números de teléfono explícitos:

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

Envío de SMS

Con el canal SMS seleccionado, los destinos aceptan números E.164 sin prefijo o con el prefijo sms::

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

Cuando la selección del canal es implícita, el prefijo twilio-sms: selecciona este canal sin reemplazar el prefijo de servicio sms:, que iMessage utiliza para elegir la entrega de SMS del operador para sus propios destinos:

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

La CLI exige un --target explícito. defaultTo está destinado a las rutas de automatización y entrega iniciadas por agentes en las que el destino puede resolverse a partir de la configuración del canal.

Las respuestas del agente a conversaciones SMS entrantes se devuelven automáticamente al remitente a través del remitente de Twilio configurado.

La salida de SMS es texto sin formato. OpenClaw elimina Markdown, aplana los bloques de código delimitados, reescribe los enlaces como label (url) y divide las respuestas largas en fragmentos de textChunkLimit caracteres como máximo (1500 de forma predeterminada) antes de enviarlos a través de Twilio.

Verificar la configuración

Después de que se inicie el Gateway:

1. Confirme que el registro del Gateway muestre la ruta del Webhook de SMS.
2. Ejecute una comprobación desde Twilio (comprueba la URL y el método del Webhook de Twilio configurado, así como los errores entrantes recientes):

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

3. Envíe un SMS al número de Twilio desde su teléfono.
4. Ejecute openclaw pairing list sms.
5. Apruebe el código de vinculación con openclaw pairing approve sms <CODE>.
6. Envíe otro SMS y confirme que el agente responda.

Para realizar pruebas solo de salida, use:

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

Prueba integral desde iMessage/SMS de macOS

En un Mac que pueda enviar SMS del operador mediante Mensajes, puede usar imsg para controlar el lado del remitente sin tocar el teléfono:

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

El primer mensaje debería crear una solicitud de vinculación. El segundo mensaje debería recibir la respuesta del agente a través de Twilio.

Seguridad del Webhook

De forma predeterminada, OpenClaw valida X-Twilio-Signature mediante publicWebhookUrl y authToken. Mantenga la parte del endpoint de publicWebhookUrl idéntica byte por byte a la URL configurada en Twilio, incluidos el esquema, el host, la ruta y la cadena de consulta. OpenClaw excluye de la generación de la firma los fragmentos de anulación de conexión de Twilio (#...), tal como exige Twilio.

La ruta del Webhook también aplica, con independencia de la validación de firmas:

• Solo POST.
• Un límite de solicitudes fallidas de 300 solicitudes por minuto para cada cuenta de SMS, ruta del Webhook y dirección de cliente resuelta. Todas las solicitudes cuentan para este límite, pero HTTP 429 solo se aplica después de que una solicitud no supere el análisis del cuerpo, la validación de Twilio o la comprobación de coincidencia de AccountSid.
• Un límite de frecuencia de callbacks procesables de 30 callbacks aceptados por minuto para cada cuenta de SMS, ruta del Webhook y dirección de cliente resuelta una vez superadas esas comprobaciones (HTTP 429 por encima de ese límite). Si la validación de firmas está desactivada, este límite de 30/min es el máximo de procesamiento sin autenticar.
• Las direcciones de cliente se resuelven mediante las reglas compartidas de proxies de confianza del Gateway. Si gateway.trustedProxies contiene el proxy inverso que reenvía los callbacks de Twilio, OpenClaw determina estos límites a partir de la dirección de cliente reenviada; de lo contrario, recurre a la dirección directa del socket.
• El valor AccountSid de la carga útil debe coincidir con el valor accountSid configurado (de lo contrario, HTTP 403).
• Los valores MessageSid repetidos se deduplican durante 10 minutos.
• La caché de repeticiones de cada cuenta de SMS conserva hasta 10,000 SID de mensajes activos. Cuando todas las posiciones están activas, los nuevos Webhooks de esa cuenta se rechazan de forma segura con HTTP 429 y un encabezado Retry-After hasta que caduque la posición más antigua.
• Se rechazan los cuerpos de solicitud que superen los 32 KB.

Twilio no vuelve a intentar las solicitudes HTTP 429 de forma predeterminada ni documenta compatibilidad con Retry-After. Las anulaciones de conexión #rp=4xx y #rp=all habilitan los reintentos de errores 4xx, pero Twilio limita la transacción de reintento completa a 15 segundos, por lo que los reintentos pueden finalizar antes de que caduque una posición de la caché de repeticiones. Configure una URL de respaldo cuando otro controlador deba recibir las entregas fallidas; considere un error 429 como un rechazo de cierre seguro, no como contrapresión fiable.

Solo para realizar pruebas con un túnel local, puede establecer:

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

No use la validación de firmas desactivada en un Gateway público.

Configuración de varias cuentas

Use accounts cuando gestione más de un número de 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"],        },      },    },  },}

Cada cuenta debe usar un valor webhookPath distinto; el Gateway se niega a registrar una ruta del Webhook cuya ruta ya pertenezca a otra cuenta. Las alternativas de entorno TWILIO_*/SMS_* solo se aplican a la cuenta predeterminada; establezca defaultAccount para cambiar qué cuenta lo es.

Solución de problemas

Twilio devuelve 403 u OpenClaw rechaza el Webhook

Compruebe que publicWebhookUrl coincida exactamente con la URL configurada en Twilio, incluidos el esquema, el host, la ruta y la cadena de consulta. Twilio firma la cadena de la URL pública, por lo que las reescrituras del proxy y los nombres de host alternativos pueden impedir la validación de la firma.

Un error 403 con Invalid account significa que el valor AccountSid de la carga útil entrante no coincide con el valor accountSid configurado; compruebe que el Webhook apunte a la cuenta propietaria del número.

No aparece ninguna solicitud de vinculación

Compruebe la URL y el método del Webhook de Messaging del número de Twilio. Debe apuntar a la URL del Webhook de SMS y usar POST. Confirme también que se pueda acceder al Gateway desde la red pública de Internet o a través del túnel.

Si el registro de mensajes de Twilio muestra el error 11200, Twilio aceptó el SMS entrante, pero no pudo acceder al Webhook. Compruebe lo siguiente:

• La opción Messaging > A message comes in de Twilio apunta a publicWebhookUrl.
• El método es POST.
• El túnel o proxy inverso expone el valor webhookPath exacto; para Tailscale Funnel, ejecute tailscale funnel status y confirme que /webhooks/sms figure en la lista.
• publicWebhookUrl usa el mismo esquema, host, ruta y cadena de consulta que envía Twilio, de modo que la validación de la firma pueda reproducir la URL firmada.

openclaw channels status --channel sms --probe muestra tanto los ajustes del Webhook de Twilio que no coinciden como los errores 11200 recientes.

Los envíos salientes fallan

Confirme que se hayan resuelto accountSid, authToken y fromNumber o messagingServiceSid. Si usa una cuenta de prueba de Twilio, puede que sea necesario verificar el número de destino en Twilio antes de poder enviar SMS salientes.

Los mensajes llegan, pero el agente no responde

Compruebe dmPolicy y allowFrom. Con la política pairing predeterminada, se debe aprobar al remitente antes de procesar las interacciones normales del agente.