SMS

O OpenClaw recebe e envia SMS por meio de um número de telefone ou Messaging Service da Twilio. O Gateway registra uma rota de Webhook de entrada (padrão /webhooks/sms), valida as assinaturas de solicitação da Twilio por padrão e envia as respostas pela Messages API da Twilio.

Status: Plugin oficial, instalado separadamente. Somente texto: sem MMS/mídia, apenas mensagens diretas.

Antes de começar

É necessário ter:

• O Plugin oficial de SMS instalado com openclaw plugins install @openclaw/sms.
• Uma conta da Twilio com um número de telefone compatível com SMS ou um Twilio Messaging Service.
• O Account SID e o Auth Token da Twilio.
• Uma URL HTTPS pública que alcance o Gateway do OpenClaw.
• Uma política de remetentes: pairing (padrão) para uso privado, allowlist para números de telefone pré-aprovados ou open somente para acesso público a SMS configurado intencionalmente.

Um número da Twilio pode atender tanto SMS quanto Chamada de voz se tiver ambos os recursos. O Webhook de SMS e o Webhook de voz são configurados separadamente na Twilio e usam caminhos distintos do Gateway; esta página aborda somente o Webhook de SMS.

Configuração 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>

Exemplos de configuração

Todas as chaves ficam em channels.sms (e, para cada conta, em channels.sms.accounts.<id>):

Arquivo de configuração

Use a configuração por arquivo quando quiser que a definição do canal acompanhe a configuração do Gateway:

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

Variáveis de ambiente

As variáveis de ambiente se aplicam somente à conta padrão; os valores da configuração têm precedência sobre os valores do ambiente.

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"

Em seguida, ative o canal na configuração:

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

Auth Token com SecretRef

authToken pode ser uma SecretRef (source: "env" | "file" | "exec"). Use essa opção quando o Gateway precisar resolver o Auth Token da Twilio pelo runtime de segredos do OpenClaw, em vez de armazenar a configuração em texto simples:

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

A variável de ambiente ou o provedor de segredos referenciado deve estar visível para o runtime do Gateway. Reinicie os processos gerenciados do Gateway após alterar as variáveis de ambiente do host.

Remetente do Messaging Service

Use messagingServiceSid em vez de fromNumber quando a Twilio precisar escolher o remetente por meio de um Messaging Service:

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

Se fromNumber e messagingServiceSid estiverem presentes após a resolução da configuração e do ambiente, fromNumber será usado.

Alvo de saída padrão

Defina defaultTo quando a automação ou a entrega iniciada pelo agente precisar ter um destino padrão caso um fluxo de envio omita um alvo explícito:

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

Controle de acesso

channels.sms.dmPolicy controla o acesso direto por SMS:

• pairing (padrão): remetentes desconhecidos recebem um código de pareamento; aprove com openclaw pairing approve sms <CODE>.
• allowlist: somente remetentes em allowFrom são processados. Um allowFrom vazio rejeita todos os remetentes (o Gateway registra um aviso na inicialização).
• open: a validação da configuração exige que allowFrom inclua "*". Sem o curinga, somente os números listados podem conversar.
• disabled: todas as MDs de entrada são descartadas.

As entradas de allowFrom devem ser números de telefone no formato E.164, como +15551234567. Os prefixos sms: e twilio-sms: são aceitos e normalizados. Para um assistente privado, prefira dmPolicy: "allowlist" com números de telefone 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"],    },  },}

Envio de SMS

Com o canal de SMS selecionado, os alvos aceitam números E.164 simples ou o prefixo sms::

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

Quando a seleção do canal é implícita, o prefixo twilio-sms: seleciona este canal sem substituir o prefixo de serviço sms:, que o iMessage usa para escolher a entrega de SMS pela operadora para seus próprios alvos:

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

A CLI exige um --target explícito. defaultTo destina-se a caminhos de automação e entrega iniciada pelo agente nos quais o alvo pode ser resolvido pela configuração do canal.

As respostas do agente em conversas de SMS recebidas retornam automaticamente ao remetente por meio do remetente da Twilio configurado.

A saída de SMS é texto simples. O OpenClaw remove o Markdown, achata blocos de código delimitados, reescreve links como label (url) e divide respostas longas em partes de, no máximo, textChunkLimit caracteres (padrão: 1500) antes de enviá-las pela Twilio.

Verificar a configuração

Após o Gateway iniciar:

1. Confirme se o log do Gateway mostra a rota do Webhook de SMS.
2. Execute uma verificação no lado da Twilio (verifica a URL/o método do Webhook da Twilio configurado e erros recentes de entrada):

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

3. Envie um SMS do seu telefone para o número da Twilio.
4. Execute openclaw pairing list sms.
5. Aprove o código de pareamento com openclaw pairing approve sms <CODE>.
6. Envie outro SMS e confirme se o agente responde.

Para testes somente de saída, use:

openclaw message send --channel sms --target sms:+15557654321 --message "Teste de SMS do OpenClaw"

Teste de ponta a ponta pelo iMessage/SMS do macOS

Em um Mac que possa enviar SMS da operadora pelo Mensagens, é possível usar imsg para controlar o lado do remetente sem tocar no telefone:

imsg send --to "+15551234567" --service sms --text "E2E de SMS do OpenClaw $(date -u +%Y%m%dT%H%M%SZ)" --jsonopenclaw pairing list smsopenclaw pairing approve sms <CODE>imsg send --to "+15551234567" --service sms --text "responda exatamente SMS pong" --json

A primeira mensagem deve criar uma solicitação de pareamento. A segunda mensagem deve receber a resposta do agente pela Twilio.

Segurança do Webhook

Por padrão, o OpenClaw valida X-Twilio-Signature usando publicWebhookUrl e authToken. Mantenha a parte do endpoint de publicWebhookUrl idêntica, byte por byte, à URL configurada na Twilio, incluindo esquema, host, caminho e string de consulta. O OpenClaw exclui da computação da assinatura os fragmentos de substituição de conexão da Twilio (#...), conforme exigido pela Twilio.

A rota do Webhook também impõe, independentemente da validação da assinatura:

• Somente POST.
• Orçamento de solicitações com falha de 300 solicitações por minuto, por conta de SMS, rota do Webhook e endereço de cliente resolvido. Todas as solicitações são contabilizadas nesse orçamento, mas o HTTP 429 só é aplicado depois que uma solicitação falha na análise do corpo, na validação da Twilio ou na correspondência de AccountSid.
• Limite de taxa de callbacks despacháveis de 30 callbacks aceitos por minuto, por conta de SMS, rota do Webhook e endereço de cliente resolvido, após essas verificações serem aprovadas (HTTP 429 acima desse limite). Se a validação da assinatura estiver desativada, esse limite de 30/min será o teto de despacho não autenticado.
• Os endereços dos clientes são resolvidos pelas regras compartilhadas de proxies confiáveis do Gateway. Se gateway.trustedProxies contiver o proxy reverso que encaminha os callbacks da Twilio, o OpenClaw associa esses limites ao endereço de cliente encaminhado; caso contrário, recorre ao endereço direto do soquete.
• O AccountSid da carga útil deve corresponder ao accountSid configurado (caso contrário, HTTP 403).
• Valores de MessageSid repetidos são desduplicados por 10 minutos.
• O cache de repetição de cada conta de SMS retém até 10.000 SIDs de mensagens ativas. Quando todos os espaços estão ativos, novos Webhooks dessa conta são rejeitados de forma segura com HTTP 429 e um cabeçalho Retry-After até que o espaço mais antigo expire.
• Corpos de solicitações com mais de 32 KB são rejeitados.

Por padrão, a Twilio não repete solicitações HTTP 429 nem documenta suporte a Retry-After. As substituições de conexão #rp=4xx e #rp=all habilitam repetições para erros 4xx, mas a Twilio limita a transação completa de repetição a 15 segundos; portanto, as repetições ainda podem terminar antes que um espaço do cache de repetição expire. Configure uma URL alternativa quando outro manipulador precisar receber entregas com falha; trate um 429 como uma rejeição segura em caso de falha, não como contrapressão confiável.

Somente para testes com túnel local, é possível definir:

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

Não use a validação de assinatura desativada em um Gateway público.

Configuração de várias contas

Use accounts ao operar mais de um número da 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 conta deve usar um webhookPath distinto; o Gateway se recusa a registrar uma rota de Webhook cujo caminho já pertença a outra conta. Os fallbacks de ambiente TWILIO_*/SMS_* aplicam-se somente à conta padrão; defina defaultAccount para alterar qual conta é a padrão.

Solução de problemas

A Twilio retorna 403 ou o OpenClaw rejeita o Webhook

Verifique se publicWebhookUrl corresponde exatamente à URL configurada na Twilio, incluindo esquema, host, caminho e string de consulta. A Twilio assina a string da URL pública; portanto, reescritas feitas pelo proxy e nomes de host alternativos podem interromper a validação da assinatura.

Um erro 403 com Invalid account significa que o AccountSid da carga útil recebida não corresponde ao accountSid configurado; verifique se o Webhook aponta para a conta proprietária do número.

Nenhuma solicitação de pareamento aparece

Verifique a URL e o método do Webhook de Messaging do número da Twilio. Ele deve apontar para a URL do Webhook de SMS e usar POST. Confirme também se o Gateway está acessível pela internet pública ou pelo seu túnel.

Se o log de mensagens da Twilio mostrar o erro 11200, a Twilio aceitou o SMS recebido, mas não conseguiu acessar seu Webhook. Verifique:

• Na Twilio, Messaging > A message comes in aponta para publicWebhookUrl.
• O método é POST.
• O túnel ou proxy reverso expõe o webhookPath exato; para o Tailscale Funnel, execute tailscale funnel status e confirme se /webhooks/sms está listado.
• publicWebhookUrl usa o mesmo esquema, host, caminho e string de consulta enviados pela Twilio, para que a validação da assinatura possa reproduzir a URL assinada.

openclaw channels status --channel sms --probe apresenta tanto configurações incompatíveis do Webhook da Twilio quanto erros recentes de 11200.

Falha nos envios de saída

Confirme se accountSid, authToken e fromNumber ou messagingServiceSid estão resolvidos. Se você usar uma conta de avaliação da Twilio, talvez seja necessário verificar o número de destino na Twilio antes que o SMS de saída possa ser enviado.

As mensagens chegam, mas o agente não responde

Verifique dmPolicy e allowFrom. Com a política padrão pairing, o remetente deve ser aprovado antes que as interações normais do agente sejam processadas.