Zalo

​

Plugin incluído

• Instalar: openclaw plugins install @openclaw/zalo
• Versão fixada: openclaw plugins install @openclaw/zalo@2026.6.11
• De um checkout local: openclaw plugins install ./path/to/local/zalo-plugin
• Detalhes: Plugins

​

Configuração rápida

1. Crie um token de bot em https://bot.zaloplatforms.com (entre na conta, crie um bot e defina as configurações). O token tem o formato numeric_id:secret; para bots do Marketplace, o token utilizável em tempo de execução pode aparecer na mensagem de boas-vindas do bot.
2. Defina o token como a variável de ambiente ZALO_BOT_TOKEN=... (somente para a conta padrão) ou na configuração.
3. Reinicie o Gateway.
4. Aprove o código de pareamento no primeiro contato por mensagem direta (a política padrão de mensagens diretas é o pareamento).

{
  channels: {
    zalo: {
      enabled: true,
      accounts: {
        default: {
          botToken: "12345689:abc-xyz",
          dmPolicy: "pairing",
        },
      },
    },
  },
}

​

O que é

​

Como funciona

• As mensagens recebidas são normalizadas no envelope compartilhado do canal, com espaços reservados para mídia.
• As respostas sempre são roteadas de volta à mesma conversa do Zalo; respostas com citação não são usadas (replyToMode permanece desativado).
• Por padrão, usa sondagem longa (getUpdates); o modo Webhook está disponível por meio de channels.zalo.webhookUrl.
• Em grupos, é necessário mencionar o bot com @ para acioná-lo; isso não pode ser configurado por canal.

​

Limites

​

Controle de acesso

​

Mensagens diretas

• channels.zalo.dmPolicy: pairing (padrão) | allowlist | open | disabled.
• Pareamento: remetentes desconhecidos recebem um código de pareamento; as mensagens são ignoradas até a aprovação. Os códigos expiram após 1 hora.
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • Detalhes: Pareamento
• channels.zalo.allowFrom aceita IDs numéricos de usuários do Zalo (sem consulta por nome de usuário). open exige "*".

​

Grupos

• channels.zalo.groupPolicy: open | allowlist | disabled.
• channels.zalo.groupAllowFrom restringe quais IDs de remetentes podem acionar o bot em grupos; quando não definido, usa allowFrom.
• Resolução padrão: quando channels.zalo está configurado, um groupPolicy não definido é resolvido como open. Quando channels.zalo está completamente ausente, o tempo de execução aplica allowlist como opção segura.
• Ressalva relatada em uso real: em algumas configurações de bots do Marketplace, não foi possível adicionar o bot a nenhum grupo. Se isso acontecer, verifique as configurações do seu bot na Zalo Bot Platform; trata-se de uma restrição da plataforma, não de uma política do OpenClaw.

​

Sondagem longa versus Webhook

• Padrão: sondagem longa (não requer URL pública).
• Modo Webhook: defina channels.zalo.webhookUrl e channels.zalo.webhookSecret.
  • A URL do Webhook deve usar HTTPS.
  • O segredo do Webhook deve ter entre 8 e 256 caracteres.
  • O Zalo envia eventos com um cabeçalho X-Bot-Api-Secret-Token, verificado por meio de uma comparação em tempo constante.
  • O HTTP do Gateway processa as solicitações de Webhook em channels.zalo.webhookPath (o padrão é o caminho da URL do Webhook).
  • As solicitações devem usar Content-Type: application/json (ou um tipo de mídia +json).
  • A sondagem por getUpdates e o Webhook são mutuamente exclusivos, conforme a documentação da API do Zalo.

​

Tipos de mensagem compatíveis

• Texto: compatibilidade total, dividido em blocos de 2.000 caracteres.
• Mídia: recebimento e envio, limitados por mediaMaxMb.
• Reações, tópicos, enquetes e comandos nativos: não são compatíveis com o Plugin.
• Transmissão contínua: o Plugin declara o recurso de transmissão em blocos, mas o Zalo não possui opções específicas para ajustar a fila de envio ou a mesclagem de texto (ao contrário de alguns outros canais regionais); verifique o comportamento atual no seu ambiente se isso for importante para seu caso de uso.

​

Recursos

​

Destinos de entrega (CLI/Cron)

openclaw message send --channel zalo --target 123456789 --message "hi"

​

Solução de problemas

• Verifique o token: openclaw channels status --probe
• Verifique se o remetente está aprovado (pareamento ou allowFrom)
• Verifique os logs do Gateway: openclaw logs --follow

• Confirme que a URL do Webhook usa HTTPS
• Confirme que o segredo tem entre 8 e 256 caracteres
• Confirme que o endpoint HTTP do Gateway está acessível no caminho configurado
• Confirme que a sondagem por getUpdates também não está em execução (eles são mutuamente exclusivos)
• Uma rajada de solicitações pode retornar HTTP 429 (120 solicitações / 60 s por caminho+IP); aguarde e tente novamente

​

Referência de configuração

​

Relacionados

• Visão geral dos canais - todos os canais compatíveis
• Pareamento - autenticação de mensagens diretas e fluxo de pareamento
• Grupos - comportamento de conversas em grupo e exigência de menções
• Roteamento de canais - roteamento de sessões para mensagens
• Segurança - modelo de acesso e proteção