Zalo pessoal

Status: experimental. Esta integração automatiza uma conta pessoal do Zalo por meio do zca-js nativo, dentro do processo, sem nenhum binário de CLI externo.

Instalação

O Zalo Personal é um plugin externo oficial, não incluído no núcleo. Instale-o antes de usar:

openclaw plugins install @openclaw/zalouser

• Fixar uma versão: openclaw plugins install @openclaw/zalouser@<version>
• A partir de um checkout do código-fonte: openclaw plugins install ./path/to/local/zalouser-plugin
• Detalhes: Plugins

Configuração rápida

1. Instale o plugin (acima).
2. Faça login (via QR, na máquina do Gateway):
   • openclaw channels login --channel zalouser
   • Escaneie o código QR com o aplicativo móvel do Zalo.
3. Ative o canal:

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

4. Reinicie o Gateway (ou conclua a configuração).
5. Por padrão, o acesso por mensagem direta usa pareamento; aprove o código de pareamento no primeiro contato.

O que é

• É executado inteiramente dentro do processo por meio da biblioteca zca-js (sem nenhum binário externo zca/openzca).
• Usa listeners de eventos nativos (message, error) para receber mensagens de entrada.
• Envia respostas diretamente pela API JS (texto/mídia/link).
• Foi projetado para casos de uso com "conta pessoal" nos quais a API de bots do Zalo não está disponível.

Nomenclatura

O ID do canal é zalouser para deixar explícito que esta integração automatiza uma conta pessoal de usuário do Zalo (não oficial). zalo está reservado para uma possível integração futura com a API oficial do Zalo.

Como encontrar IDs (diretório)

openclaw directory self --channel zalouseropenclaw directory peers list --channel zalouser --query "name"openclaw directory groups list --channel zalouser --query "work"

Limites

• O texto de saída é dividido em blocos de 2.000 caracteres (limite do cliente do Zalo).
• Não há suporte a streaming.

Controle de acesso (mensagens diretas)

channels.zalouser.dmPolicy: pairing | allowlist | open | disabled (padrão: pairing).

channels.zalouser.allowFrom deve usar IDs estáveis de usuários do Zalo. Também pode referenciar grupos estáticos de acesso de remetentes (accessGroup:<name>). Durante a configuração interativa, os nomes informados podem ser resolvidos para IDs usando a consulta de contatos executada dentro do processo pelo plugin.

Se um nome bruto permanecer na configuração, a inicialização só o resolverá quando channels.zalouser.dangerouslyAllowNameMatching: true estiver ativado. Sem essa aceitação explícita, as verificações de remetentes em tempo de execução usam somente IDs, e os nomes brutos são ignorados para fins de autorização.

Aprove por meio de:

• openclaw pairing list zalouser
• openclaw pairing approve zalouser <code>

Acesso a grupos (opcional)

• Padrão: channels.zalouser.groupPolicy = "allowlist" (os grupos exigem uma entrada explícita na lista de permissões).
• Abrir todos os grupos: channels.zalouser.groupPolicy = "open".
• Bloquear todos os grupos: channels.zalouser.groupPolicy = "disabled".
• Com groupPolicy = "allowlist":
  • As chaves de channels.zalouser.groups devem ser IDs estáveis de grupos; os nomes são resolvidos para IDs na inicialização somente quando channels.zalouser.dangerouslyAllowNameMatching: true está ativado.
  • channels.zalouser.groupAllowFrom controla quais remetentes nos grupos permitidos podem acionar o bot; grupos estáticos de acesso de remetentes podem ser referenciados com accessGroup:<name>.
• O assistente de configuração pode solicitar listas de permissões de grupos.
• Por padrão, a correspondência com a lista de permissões de grupos usa somente IDs. Nomes não resolvidos são ignorados para autenticação, a menos que channels.zalouser.dangerouslyAllowNameMatching: true esteja ativado.
• channels.zalouser.dangerouslyAllowNameMatching: true é um modo de compatibilidade emergencial que reativa a resolução de nomes mutáveis na inicialização e a correspondência de nomes de grupos em tempo de execução.
• groupAllowFrom não recorre a allowFrom para mensagens normais de grupo: deixá-lo vazio em um grupo incluído na lista de permissões abre esse grupo para qualquer remetente. Comandos de controle autorizados (por exemplo, /new) são a exceção; as verificações do remetente do comando recorrem a allowFrom quando groupAllowFrom está vazio.

Exemplo:

{  channels: {    zalouser: {      groupPolicy: "allowlist",      groupAllowFrom: ["1471383327500481391"],      groups: {        "123456789": { enabled: true },        "Work Chat": { enabled: true },      },    },  },}

Controle por menção em grupos

• channels.zalouser.groups.<group>.requireMention controla se as respostas em grupo exigem uma menção.
• Ordem de resolução: ID do grupo -> alias group:<id> -> nome/slug do grupo (candidatos baseados em nome só se aplicam quando dangerouslyAllowNameMatching: true) -> * -> padrão (true).
• Aplica-se tanto aos grupos incluídos na lista de permissões quanto ao modo de grupos abertos.
• Citar uma mensagem do bot conta como uma menção implícita para ativar o grupo.
• Comandos de controle autorizados (por exemplo, /new) podem ignorar o controle por menção.
• Quando uma mensagem de grupo é ignorada porque uma menção é obrigatória, o OpenClaw a armazena como histórico pendente do grupo e a inclui na próxima mensagem de grupo processada.
• Limite do histórico de grupos: channels.zalouser.historyLimit, depois messages.groupChat.historyLimit e, por fim, o valor alternativo 50.

Exemplo:

{  channels: {    zalouser: {      groupPolicy: "allowlist",      groups: {        "*": { enabled: true, requireMention: true },        "Work Chat": { enabled: true, requireMention: false },      },    },  },}

Várias contas

As contas são mapeadas para perfis zalouser no estado do OpenClaw. Exemplo:

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

Variáveis de ambiente

A seleção do perfil também pode vir de variáveis de ambiente:

Os nomes dos perfis selecionam as credenciais de login salvas do Zalo no estado do OpenClaw. Ordem de resolução:

1. profile explícito na configuração.
2. ZALOUSER_PROFILE.
3. ZCA_PROFILE.
4. O ID da conta para contas que não são a padrão, ou default para a conta padrão.

Para configurações com várias contas, prefira definir profile em cada conta na configuração para que uma única variável de ambiente não faça várias contas compartilharem a mesma sessão de login.

Digitação, reações e confirmações de entrega

• O OpenClaw envia um evento de digitação antes de despachar uma resposta (em caráter de melhor esforço).
• Há suporte à ação de reação a mensagens react para zalouser nas ações do canal.
  • Use remove: true para remover um emoji de reação específico de uma mensagem.
  • Semântica das reações: Reações
• Para mensagens de entrada que incluem metadados do evento, o OpenClaw envia confirmações de entrega e visualização (em caráter de melhor esforço).

Solução de problemas

O login não persiste:

• openclaw channels status --probe
• Faça login novamente: openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

O nome da lista de permissões/do grupo não foi resolvido:

• Use IDs numéricos em allowFrom/groupAllowFrom e IDs estáveis de grupos em groups. Se você precisar intencionalmente de nomes exatos de amigos/grupos, ative channels.zalouser.dangerouslyAllowNameMatching: true.

Atualização a partir de uma configuração antiga baseada em zca externo/CLI:

• Remova quaisquer pressupostos sobre um processo externo zca; agora o canal é executado inteiramente dentro do processo por meio do zca-js, sem nenhum binário de CLI externo.

Conteúdo relacionado

• 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 controle por menção
• Roteamento de canais - roteamento de sessões para mensagens
• Segurança - modelo de acesso e proteção