Zalo pessoal

​

Instalação

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

​

Como encontrar 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 2.000 caracteres (limite do cliente do Zalo).
• Não há suporte a streaming.

​

Controle de acesso (mensagens diretas)

• 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.

{
  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.

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

​

Várias contas

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

​

Variáveis de ambiente

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.

​

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

• 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 grupos em groups. Se você precisar intencionalmente de nomes exatos de amigos/grupos, ative channels.zalouser.dangerouslyAllowNameMatching: true.

• 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