Zalo pessoal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Plugin incluído

• Instale via CLI: openclaw plugins install @openclaw/zalouser
• Versão fixada: openclaw plugins install @openclaw/zalouser@2026.5.2
• Ou a partir de um checkout do código-fonte: openclaw plugins install ./path/to/local/zalouser-plugin
• Detalhes: Plugins

​

Configuração rápida (iniciante)

1. Garanta que o plugin Zalo Personal esteja disponível.
   • As versões empacotadas atuais do OpenClaw já o incluem.
   • Instalações mais antigas/personalizadas podem adicioná-lo manualmente com os comandos acima.
2. Faça login (QR, na máquina do Gateway):
   • openclaw channels login --channel zalouser
   • Escaneie o código QR com o app móvel do Zalo.
3. Habilite o canal:

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

4. Reinicie o Gateway (ou conclua a configuração).
5. O acesso por DM usa emparelhamento por padrão; aprove o código de emparelhamento no primeiro contato.

​

O que é

• Executa inteiramente no processo via zca-js.
• Usa listeners de eventos nativos para receber mensagens de entrada.
• Envia respostas diretamente pela API JS (texto/mídia/link).
• Projetado para casos de uso de “conta pessoal” em que a API de Bot do Zalo não está disponível.

​

Nomeação

​

Encontrando IDs (diretório)

openclaw directory self --channel zalouser
openclaw 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 ~2000 caracteres (limites do cliente Zalo).
• Streaming é bloqueado por padrão.

​

Controle de acesso (DMs)

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

​

Acesso a grupos (opcional)

• Padrão: channels.zalouser.groupPolicy = "open" (grupos permitidos). Use channels.defaults.groupPolicy para substituir o padrão quando não definido.
• Restrinja a uma lista de permissões com:
  • channels.zalouser.groupPolicy = "allowlist"
  • channels.zalouser.groups (as chaves devem ser IDs estáveis de grupo; nomes são resolvidos para IDs na inicialização somente quando channels.zalouser.dangerouslyAllowNameMatching: true está habilitado)
  • 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>)
• Bloqueie todos os grupos: channels.zalouser.groupPolicy = "disabled".
• O assistente de configuração pode solicitar listas de permissões de grupos.
• Na inicialização, o OpenClaw resolve nomes de grupos/usuários em listas de permissões para IDs e registra o mapeamento somente quando channels.zalouser.dangerouslyAllowNameMatching: true está habilitado.
• A correspondência da lista de permissões de grupos usa apenas IDs por padrão. Nomes não resolvidos são ignorados para autenticação, a menos que channels.zalouser.dangerouslyAllowNameMatching: true esteja habilitado.
• channels.zalouser.dangerouslyAllowNameMatching: true é um modo de compatibilidade de emergência que reabilita a resolução mutável de nomes na inicialização e a correspondência de nomes de grupos em tempo de execução.
• Se groupAllowFrom não estiver definido, o tempo de execução usa allowFrom como fallback para verificações de remetentes de grupo.
• As verificações de remetente se aplicam tanto a mensagens normais de grupo quanto a comandos de controle (por exemplo, /new, /reset).

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

​

Controle de menção em grupos

• channels.zalouser.groups.<group>.requireMention controla se respostas em grupo exigem uma menção.
• Ordem de resolução: id/nome exato do grupo -> slug normalizado do grupo -> * -> padrão (true).
• Isso se aplica tanto a grupos em lista de permissões quanto ao modo de grupo aberto.
• Citar uma mensagem do bot conta como uma menção implícita para ativação em grupo.
• Comandos de controle autorizados (por exemplo, /new) podem contornar o controle de menção.
• Quando uma mensagem de grupo é ignorada porque uma menção é exigida, o OpenClaw a armazena como histórico pendente do grupo e a inclui na próxima mensagem de grupo processada.
• O limite de histórico de grupo usa como padrão messages.groupChat.historyLimit (fallback 50). Você pode substituir por conta com channels.zalouser.historyLimit.

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

​

Várias contas

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

​

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

• O OpenClaw envia um evento de digitação antes de despachar uma resposta (melhor esforço).
• A ação de reação de mensagem react é compatível com zalouser em ações de canal.
  • Use remove: true para remover um emoji de reação específico de uma mensagem.
  • Semântica de reações: Reações
• Para mensagens de entrada que incluem metadados de evento, o OpenClaw envia confirmações de entregue + visto (melhor esforço).

​

Solução de problemas

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

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

• Remova quaisquer suposições antigas sobre processo externo zca.
• O canal agora executa totalmente no OpenClaw sem binários CLI externos.

​

Relacionados

• Visão geral de canais — todos os canais compatíveis
• Emparelhamento — autenticação por DM e fluxo de emparelhamento
• Grupos — comportamento de chat em grupo e controle de menção
• Roteamento de canais — roteamento de sessões para mensagens
• Segurança — modelo de acesso e reforço de segurança