Zalo Personal (não oficial)¶

Status: experimental. Esta integração automatiza uma conta pessoal do Zalo via zca-cli.

Aviso: Esta é uma integração não oficial e pode resultar em suspensão/banimento da conta. Use por sua conta e risco.

Plugin necessário¶

O Zalo Personal é distribuído como um plugin e não vem incluído na instalação principal.

• Instalar via CLI: openclaw plugins install @openclaw/zalouser
• Ou a partir de um checkout do código-fonte: openclaw plugins install ./extensions/zalouser
• Detalhes: Plugins

Pré-requisito: zca-cli¶

A máquina do Gateway deve ter o binário zca disponível em PATH.

• Verificar: zca --version
• Se estiver ausente, instale o zca-cli (veja extensions/zalouser/README.md ou a documentação oficial do zca-cli).

Configuração rápida (iniciante)¶

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

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

4. Reinicie o Gateway (ou finalize a integração inicial).
5. O acesso por DM usa pareamento por padrão; aprove o código de pareamento no primeiro contato.

O que é¶

• Usa zca listen para receber mensagens de entrada.
• Usa zca msg ... para enviar respostas (texto/mídia/link).
• Projetado para casos de uso de “conta pessoal”, onde a API oficial de Bot do Zalo não está disponível.

Nomenclatura¶

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

Encontrando IDs (diretório)¶

Use a CLI de diretório para descobrir contatos/grupos e seus IDs:

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 do Zalo).
• O streaming é bloqueado por padrão.

Controle de acesso (DMs)¶

channels.zalouser.dmPolicy oferece suporte a: pairing | allowlist | open | disabled (padrão: pairing). channels.zalouser.allowFrom aceita IDs de usuário ou nomes. O assistente resolve nomes para IDs via zca friend find quando disponível.

Aprove via:

• 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 sobrescrever o padrão quando não estiver definido.
• Restrinja a uma lista de permissões com:
• channels.zalouser.groupPolicy = "allowlist"
• channels.zalouser.groups (as chaves são IDs ou nomes de grupos)
• Bloquear 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 nas listas de permissões para IDs e registra o mapeamento; entradas não resolvidas são mantidas como digitadas.

Exemplo:

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

Multi-conta¶

As contas mapeiam para perfis do zca. Exemplo:

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

Solução de problemas¶

zca não encontrado:

• Instale o zca-cli e garanta que ele esteja em PATH para o processo do Gateway.

O login não persiste:

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