Communitygithub.com

wxclawbot-cli

CLI para envio proativo de mensagens do Weixin para agentes OpenClaw.

O que é wxclawbot-cli?

O wxclawbot-cli resolve a limitação do iLink Bot, que só responde passivamente a mensagens, permitindo que agentes de IA (como OpenClaw) enviem notificações proativas, como lembretes, alertas e relatórios via Weixin. Ele suporta o envio de texto, imagens, vídeos e arquivos, e pode ser integrado com cron para tarefas agendadas. O CLI gerencia automaticamente a descoberta de contas e o context_token necessário para push real, garantindo que as mensagens cheguem mesmo que o usuário não esteja na conversa. É compatível com Node.js >= 20 e requer o pacote `@claw-lab/wxclawbot-cli` instalado globalmente, além de uma sessão ativa do openclaw-weixin.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add lroolle/wxclawbot-cli

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

wxclawbot-send

O que este skill resolve

O robô do Weixin (iLink Bot) só pode responder passivamente a mensagens dos usuários, não consegue iniciar conversas ativamente. Isso significa que agentes não conseguem realizar cenários de alcance ativo como lembretes programados, envio de alertas ou relatórios.

Este skill, através da CLI wxclawbot, permite que agentes enviem mensagens ativamente para usuários do Weixin, incluindo texto, imagens, vídeos e arquivos. Combinado com cron, possibilita tarefas agendadas.

Pré-requisitos

  • Node.js >= 20
  • npm install -g @claw-lab/wxclawbot-cli
  • openclaw-weixin já logado (credenciais em ~/.openclaw/openclaw-weixin/accounts/)

Verificação: wxclawbot accounts --json

Início rápido

wxclawbot send --text "conteúdo da mensagem" --json
wxclawbot send --file ./foto.jpg --json
wxclawbot send --file ./relatorio.pdf --text "Confira, por favor" --json

Quando usar o quê

Enviar mensagem de texto ativamente  → wxclawbot send --text "msg" --json
Enviar arquivo/imagem ativamente     → wxclawbot send --file ./caminho --json
Verificar status da conta            → wxclawbot accounts --json
Chamada programática                 → veja references/programmatic-api.md

Referência de comandos

send

wxclawbot send --text "mensagem" --json
wxclawbot send --to "[email protected]" --text "Olá" --json
wxclawbot send --file ./foto.jpg --json
wxclawbot send --file ./relatorio.pdf --text "Confira, por favor" --json
wxclawbot send --file "https://exemplo.com/img.png" --json
echo "Relatório diário gerado" | wxclawbot send --json
wxclawbot send --text "teste" --dry-run
ParâmetroDescrição
--text <msg>Texto da mensagem. "-" lê explicitamente de stdin
--file <caminho>Arquivo local ou URL (imagem / vídeo / arquivo)
--to <userId>ID do usuário de destino. Padrão: usuário vinculado à conta
--account <id>Especifica a conta. Padrão: primeira disponível
--jsonSaída em formato JSON. Obrigatório para chamadas programáticas
--dry-runVisualização, não envia

O tipo de mídia é identificado automaticamente pela extensão:

  • Imagens: .png .jpg .jpeg .gif .webp .bmp
  • Vídeos: .mp4 .mov .webm .mkv .avi
  • Arquivos: todos os outros

accounts

wxclawbot accounts --json

Retorna: [{"id":"<botId>-im-bot","configured":true,"baseUrl":"..."}]

Mecanismo de descoberta de contas

A CLI descobre automaticamente as contas a partir de ~/.openclaw/openclaw-weixin/accounts/*.json. Cada arquivo contém token, baseUrl, userId (destino padrão para --to).

  • O Bot ID é extraído do token em tempo de execução (não é hardcoded)
  • O ID da conta pode mudar após upgrade ou novo registro do openclaw-weixin
  • --to padrão é o userId do arquivo da conta (usuário vinculado)
  • Definir a variável de ambiente WXCLAW_TOKEN substitui a descoberta por arquivos

Context Token (chave para push ativo)

O Weixin exige um context_token para enviar mensagens ativamente. Sem ele, as mensagens ficam no servidor até que o usuário abra a janela de chat — o que não é considerado "push ativo".

A CLI lê automaticamente {accountId}.context-tokens.json (no mesmo diretório dos arquivos de conta). Este arquivo é mantido pelo openclaw-weixin e contém um mapeamento de userId → contextToken. Não é necessária configuração manual — após o usuário enviar uma mensagem ao robô, o openclaw-weixin salva automaticamente.

Se o context_token estiver ausente (novo usuário, token expirado), a mensagem ainda será enviada com sucesso (ok:true), mas não será notificada ativamente.

Após atualizar o openclaw-weixin, sempre verifique com wxclawbot accounts --json.

Integração com Agente

Chamadas programáticas devem usar --json. Analise o JSON para determinar sucesso.

resultado=$(wxclawbot send --text "Tarefa concluída" --json)
resultado=$(wxclawbot send --file ./grafico.png --text "Métrica diária" --json)
  • Sucesso: {"ok":true,"to":"[email protected]","clientId":"..."}
  • Falha: {"ok":false,"error":"..."}
  • Código de saída: 0 = CLI executou com sucesso, 1 = falha

Nota: exit 0 significa apenas que a CLI terminou, não que a mensagem foi entregue. Verifique o campo ok.

Tratamento de erros

ErroSignificadoTratamento
ret=-2Limite de frequência (cerca de 7 mensagens / 5 minutos por bot, compartilhado entre todos os clientes)Aguarde 60-120 segundos e tente novamente; evite loops apertados
ret=-14Sessão expiradaFaça login novamente pelo openclaw
Nenhuma conta encontradaCredenciais ausentesExecute wxclawbot accounts para depurar
Erro de upload CDNFalha no upload do arquivoVerifique tamanho/formato do arquivo e tente novamente
Request timeoutProblema de rede (timeout de 15 segundos)Tente novamente

O limite de frequência é do lado do servidor; a cota é compartilhada entre todos os clientes com o mesmo token do bot.

Erros estruturados de transmissão (v0.5.1+)

No modo --json, falhas na camada de transmissão incluem campos adicionais:

{"ok":false,"error":"falha no envio: ...","errorKind":"timeout","retryable":true}
errorKindSignificadoretryable
timeoutRequisição excedeu 15 segundostrue
dnsFalha na resolução DNStrue
connectionConexão reiniciada / socket hang uptrue
networkConexão recusada / host inalcançável / fetch falhoutrue
tlsErro de certificado ou TLSfalse
unknownErro não classificadofalse

Use o campo retryable para decidir se deve tentar novamente ou falhar definitivamente.

Armadilhas comuns

  • Use --json obrigatoriamente — sem ele, a saída é legível por humanos e não pode ser analisada
  • Verifique o campo ok — exit 0 significa apenas que a CLI rodou, não que a mensagem chegou
  • Evite loops apertados com ret=-2 — espere pelo menos 5-10 segundos
  • Texto grande use stdin — echo "..." | wxclawbot send --json, evita problemas com aspas do shell
  • Arquivos são criptografados e enviados para o CDN do Weixin — arquivos grandes podem demorar

Variáveis de ambiente

VariávelFinalidade
WXCLAW_TOKENSubstitui o token do bot ([email protected]:seu-token)
WXCLAW_BASE_URLSubstitui o endpoint da API (padrão: https://ilinkai.weixin.qq.com)

Para a interface programática, veja references/programmatic-api.md.

Habilidades Relacionadas