Qual e a diferenca entre Zalo e Zalo Personal?

O canal Zalo utiliza a API oficial da plataforma Zalo Bot com um Bot Token: e seguro, estavel, mas limitado (sem chats em grupo). O Zalo Personal utiliza a ferramenta nao oficial zca-cli com uma conta pessoal real: suporta chats em grupo e midias, mas apresenta risco de banimento da conta por utilizar automacao nao oficial.

Minha conta pessoal do Zalo pode ser banida?

Sim. Esta integracao utiliza uma ferramenta nao oficial (zca-cli) para automatizar uma conta pessoal. O Zalo pode detectar isso como automacao nao autorizada e suspender ou banir a conta. Use uma conta secundaria dedicada em vez da sua conta pessoal principal.

O Zalo Personal suporta chats em grupo?

Sim. Diferente da integracao com a plataforma Zalo Bot, o Zalo Personal suporta completamente chats em grupo. A politica groupPolicy padrao e 'open' (responde em todos os grupos). Voce pode restringir a grupos especificos com 'allowlist' ou desativar respostas em grupo com 'disabled'.

Como encontro os IDs de grupo para a lista de permissao?

Use 'openclaw directory groups list --channel zalouser --query "termo de busca"' para pesquisar grupos por nome. O comando retornara IDs de grupo que voce pode usar na configuracao de groups. Voce tambem pode referenciar grupos pelo nome exato.

Preciso de um Bot Token para o Zalo Personal?

Nao. O Zalo Personal autentica via escaneamento de QR code -- nenhum API Token ou Bot Token e necessario. Basta executar 'openclaw channels login --channel zalouser' e escanear o QR code com seu aplicativo movel do Zalo.

Posso usar o Zalo e o Zalo Personal ao mesmo tempo?

Sim. Sao canais separados com IDs diferentes (zalo e zalouser). Voce pode habilitar ambos na sua configuracao. O canal Zalo utiliza uma conta de bot enquanto o Zalo Personal utiliza sua conta pessoal.

OpenClaw GuideOpenClaw

Começar

Canal Zalo Personal do OpenClaw

Mensagens

Médio

Conecte o OpenClaw a sua conta pessoal do Zalo usando a ferramenta nao oficial zca-cli. Diferente da integracao com a plataforma Zalo Bot, este canal permite que seu assistente de IA opere atraves de uma conta pessoal real do Zalo, com suporte para chats em grupo, midias e listas de amigos. A autenticacao e feita escaneando um QR code, assim como ao vincular um novo dispositivo.

Info rápida

DificuldadeMédio

CategoriaMensagens

Recursos suportados3 / 6

Zalo Personal Recursos suportados

Mensagens de texto

Suportado

Mídia e arquivos

Suportado

Reações

Não suportado

Threads

Não suportado

Mensagens de voz

Não suportado

Chat em grupo

Suportado

Zalo Personal Pré-requisitos

Uma conta pessoal do Zalo (conta padrao, nao um Official Account)
O binario zca instalado e disponivel no PATH do seu sistema
OpenClaw Gateway em execucao e configurado
Aplicativo movel do Zalo para escanear o QR code durante o login

Zalo Personal Configuração rápida

Instalar o plugin zalouser e o zca-cli

Instale o plugin do OpenClaw com 'openclaw plugins install @openclaw/zalouser'. Em seguida, instale a ferramenta zca-cli e certifique-se de que ela esta no seu PATH. Verifique com 'zca --version'.

Fazer login via QR code

Execute 'openclaw channels login --channel zalouser' para exibir um QR code no seu terminal. Abra o aplicativo Zalo no seu celular e escaneie o QR code para autenticar a sessao.

Configurar e comecar a conversar

Adicione a configuracao do canal zalouser em ~/.openclaw/openclaw.json com suas preferencias de dmPolicy e groupPolicy. Inicie o Gateway com 'openclaw start' e envie uma mensagem para sua conta do Zalo para testar.

Zalo Personal Exemplo de configuração

config.json

{
  "channels": {
    "zalouser": {
      "enabled": true,
      "dmPolicy": "pairing",
      "groupPolicy": "open"
    }
  }
}

Zalo Personal Documentação Detalhada

Visao geral da arquitetura

O OpenClaw se conecta ao Zalo atraves da ferramenta zca-cli, um cliente de linha de comando nao oficial para contas pessoais do Zalo. Diferente da integracao com a plataforma Zalo Bot (que utiliza APIs HTTP), este canal usa o binario zca para escutar mensagens recebidas e enviar respostas. O Gateway executa 'zca listen' como um processo em segundo plano para receber mensagens em tempo real e usa 'zca msg' para enviar respostas. Essa abordagem funciona inteiramente de forma local -- nenhuma URL publica, Webhook ou certificado HTTPS e necessario. Como utiliza uma conta pessoal, o bot pode participar de chats em grupo, acessar listas de amigos e enviar midias -- recursos nao disponiveis atraves da plataforma Bot oficial.

Esta e uma integracao nao oficial. Seu uso pode resultar na suspensao ou banimento da sua conta do Zalo. Use uma conta dedicada em vez da sua conta pessoal principal.

A ferramenta zca-cli gerencia a camada de protocolo. Mantenha-a atualizada para garantir a compatibilidade com o servico do Zalo.

Esta e uma integracao experimental que utiliza uma ferramenta nao oficial. O Zalo pode suspender ou banir contas que utilizem automacao de terceiros. Use por sua conta e risco.

Instalacao do zca-cli

O binario zca-cli e um pre-requisito para este canal. Ele deve estar instalado e acessivel no PATH do seu sistema antes que o Gateway possa utilizar o canal Zalo Personal. Apos a instalacao, verifique se esta funcionando executando 'zca --version' no seu terminal. Se o comando nao for encontrado, verifique a configuracao do seu PATH ou reinstale a ferramenta.

terminal

zca --version

Se o zca esta instalado mas nao esta no PATH, voce pode adicionar seu diretorio ao PATH no perfil do seu shell (~/.bashrc, ~/.zshrc, etc.).

Autenticacao por QR Code

A autenticacao e feita escaneando um QR code com seu aplicativo movel do Zalo, de forma semelhante a vincular um novo dispositivo. Nenhum API Token ou Bot Token e necessario. Execute o comando de login para exibir o QR code no seu terminal. Abra o Zalo no seu celular, navegue ate o leitor de QR e escaneie o codigo. A sessao sera estabelecida e as credenciais armazenadas localmente. Se o login nao persistir apos uma reinicializacao, tente fazer logout e login novamente para renovar a sessao.

terminal

# Login
openclaw channels login --channel zalouser

# If login doesn't persist, re-authenticate
openclaw channels logout --channel zalouser
openclaw channels login --channel zalouser

Mantenha seu celular conectado a Internet durante o escaneamento do QR code. A sessao e validada atraves dos servidores do Zalo.

Politicas de mensagens diretas

As politicas de DM (mensagens diretas) controlam quem pode interagir com seu assistente de IA por meio de mensagens privadas. O OpenClaw suporta quatro politicas: • pairing (padrao) — Novos contatos recebem um codigo de pareamento ao enviarem a primeira mensagem. Aprove-os com 'openclaw pairing approve zalouser <code>'. Os codigos expiram apos 1 hora. • allowlist — Apenas IDs de usuario ou nomes listados em allowFrom podem enviar mensagens ao bot. Nomes sao resolvidos para IDs via 'zca friend find'. • open — Qualquer pessoa que enviar uma mensagem para a conta recebe uma resposta. • disabled — O tratamento de mensagens diretas e completamente desativado.

openclaw.json

{
  "channels": {
    "zalouser": {
      "dmPolicy": "allowlist",
      "allowFrom": ["123456789", "Friend Name"]
    }
  }
}

A politica 'open' permite que qualquer pessoa interaja com sua conta pessoal. Como se trata de uma conta real do Zalo visivel para seus contatos, use com cautela.

Gerenciamento de chats em grupo

Diferente da integracao com a plataforma Zalo Bot, o Zalo Personal suporta completamente chats em grupo. Por padrao, groupPolicy esta definido como 'open', o que significa que o bot respondera em todas as conversas de grupo. Voce pode restringir o acesso a grupos usando a politica 'allowlist' com um mapeamento de groups. Os grupos podem ser referenciados pelo seu ID numerico ou pelo nome. Defina groupPolicy como 'disabled' para ignorar completamente todas as mensagens de grupo.

openclaw.json

{
  "channels": {
    "zalouser": {
      "groupPolicy": "allowlist",
      "groups": {
        "123456789": { "allow": true },
        "Work Chat": { "allow": true }
      }
    }
  }
}

Use 'openclaw directory groups list --channel zalouser --query "name"' para encontrar IDs e nomes de grupos.

Os nomes de grupo diferenciam maiusculas de minusculas. Use o nome exato conforme exibido no seu aplicativo Zalo.

Tratamento de mensagens

O OpenClaw suporta o envio de mensagens de texto, imagens, arquivos e links atraves do Zalo Personal. Mensagens de texto sao automaticamente divididas em aproximadamente 2.000 caracteres para respeitar os limites do cliente Zalo. Mensagens recebidas de contatos e grupos sao capturadas pelo processo 'zca listen' e encaminhadas para a IA. Respostas sao enviadas usando 'zca msg'. Respostas em streaming sao bloqueadas por padrao devido a restricao do limite de caracteres.

Respostas longas da IA sao automaticamente divididas em multiplas mensagens no limite de aproximadamente 2.000 caracteres.

As capacidades de envio de midia dependem da versao do zca-cli instalada. Mantenha-o atualizado para a melhor compatibilidade.

Configuracao de multiplas contas

O OpenClaw suporta a execucao simultanea de multiplas contas pessoais do Zalo por meio do mapeamento para diferentes perfis do zca. Cada conta possui seu proprio nome de perfil, politica de DM e configuracoes de grupo. Isso e util se voce deseja executar assistentes de IA separados para diferentes finalidades -- por exemplo, uma conta de trabalho e uma conta pessoal.

openclaw.json

{
  "channels": {
    "zalouser": {
      "enabled": true,
      "defaultAccount": "default",
      "accounts": {
        "work": {
          "enabled": true,
          "profile": "work"
        },
        "personal": {
          "enabled": true,
          "profile": "personal"
        }
      }
    }
  }
}

Diretorio e descoberta

O canal Zalo Personal fornece comandos de diretorio para descobrir amigos e grupos na sua conta. Sao uteis para encontrar IDs de usuario para listas de permissao ou IDs de grupo para politicas de grupo. Voce pode visualizar seu proprio perfil, pesquisar amigos por nome e pesquisar grupos por nome -- tudo pela linha de comando.

terminal

# View your profile
openclaw directory self --channel zalouser

# Search friends
openclaw directory peers list --channel zalouser --query "name"

# Search groups
openclaw directory groups list --channel zalouser --query "work"

Zalo Personal Referência de Configuração

Key	Type	Default	Description
enabled	boolean	false	Habilitar ou desabilitar o canal Zalo Personal
dmPolicy	string	"pairing"	Controla quem pode enviar mensagens diretas ao bot. Opcoes: pairing, allowlist, open, disabled
allowFrom	string[]	[]	IDs ou nomes de usuario autorizados a enviar mensagens ao bot (quando dmPolicy e allowlist)
groupPolicy	string	"open"	Controla o comportamento dos chats em grupo. Opcoes: open, allowlist, disabled
groups	object	{}	Mapeamento de IDs ou nomes de grupo para objetos de permissao (quando groupPolicy e allowlist)
defaultAccount	string	"default"	O nome do perfil zca padrao a ser utilizado
accounts.<id>.enabled	boolean	true	Habilitar ou desabilitar uma conta especifica no modo de multiplas contas
accounts.<id>.profile	string	""	O nome do perfil zca para uma conta especifica

enabled

Type: booleanDefault: false

Habilitar ou desabilitar o canal Zalo Personal

dmPolicy

Type: stringDefault: "pairing"

Controla quem pode enviar mensagens diretas ao bot. Opcoes: pairing, allowlist, open, disabled

allowFrom

Type: string[]Default: []

IDs ou nomes de usuario autorizados a enviar mensagens ao bot (quando dmPolicy e allowlist)

groupPolicy

Type: stringDefault: "open"

Controla o comportamento dos chats em grupo. Opcoes: open, allowlist, disabled

groups

Type: objectDefault: {}

Mapeamento de IDs ou nomes de grupo para objetos de permissao (quando groupPolicy e allowlist)

defaultAccount

Type: stringDefault: "default"

O nome do perfil zca padrao a ser utilizado

accounts.<id>.enabled

Type: booleanDefault: true

Habilitar ou desabilitar uma conta especifica no modo de multiplas contas

accounts.<id>.profile

Type: stringDefault: ""

O nome do perfil zca para uma conta especifica

Zalo Personal Perguntas Frequentes

Zalo Personal Solução de Problemas

Comando zca nao encontrado

O binario zca-cli nao esta instalado ou nao esta no PATH do seu sistema.

Instale o zca-cli e certifique-se de que esta no seu PATH. Verifique com 'zca --version'. Se esta instalado mas nao e encontrado, adicione seu diretorio de instalacao ao PATH em ~/.bashrc ou ~/.zshrc.

O login por QR code falha ou a sessao nao persiste

A sessao do Zalo pode ter expirado ou a autenticacao inicial foi incompleta.

Tente fazer logout e login novamente: 'openclaw channels logout --channel zalouser' e depois 'openclaw channels login --channel zalouser'. Certifique-se de que seu celular tenha uma conexao estavel com a Internet durante o escaneamento do QR code.

O bot nao responde a mensagens de grupo

groupPolicy pode estar definido como 'disabled' ou como 'allowlist' sem que o grupo esteja listado.

Verifique sua configuracao de groupPolicy. Se estiver usando 'allowlist', certifique-se de que o ID ou nome do grupo esta listado na configuracao de groups. Use 'openclaw directory groups list --channel zalouser' para encontrar o ID de grupo correto.

Mensagens nao estao sendo recebidas

O processo zca listen pode nao estar em execucao, ou a sessao expirou.

Execute 'openclaw channels status --probe' para diagnosticar a conexao. Se a sessao expirou, autentique-se novamente via login por QR code. Verifique os logs do Gateway para mensagens de erro especificas.

A conta foi suspensa ou banida

O Zalo detectou automacao nao oficial na conta.

Este e um risco conhecido ao usar integracoes nao oficiais. Entre em contato com o suporte do Zalo para tentar recuperar a conta. Considere mudar para a integracao oficial com a plataforma Zalo Bot (canal zalo), que nao apresenta risco de banimento, embora nao suporte chats em grupo.

Ver documentação completa Voltar para todos os canais