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âmetro | Descriçã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 |
--json | Saída em formato JSON. Obrigatório para chamadas programáticas |
--dry-run | Visualizaçã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
--topadrão é ouserIddo arquivo da conta (usuário vinculado)- Definir a variável de ambiente
WXCLAW_TOKENsubstitui 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
| Erro | Significado | Tratamento |
|---|---|---|
ret=-2 | Limite 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=-14 | Sessão expirada | Faça login novamente pelo openclaw |
| Nenhuma conta encontrada | Credenciais ausentes | Execute wxclawbot accounts para depurar |
| Erro de upload CDN | Falha no upload do arquivo | Verifique tamanho/formato do arquivo e tente novamente |
| Request timeout | Problema 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}
errorKind | Significado | retryable |
|---|---|---|
timeout | Requisição excedeu 15 segundos | true |
dns | Falha na resolução DNS | true |
connection | Conexão reiniciada / socket hang up | true |
network | Conexão recusada / host inalcançável / fetch falhou | true |
tls | Erro de certificado ou TLS | false |
unknown | Erro não classificado | false |
Use o campo retryable para decidir se deve tentar novamente ou falhar definitivamente.
Armadilhas comuns
- Use
--jsonobrigatoriamente — 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ável | Finalidade |
|---|---|
WXCLAW_TOKEN | Substitui o token do bot ([email protected]:seu-token) |
WXCLAW_BASE_URL | Substitui o endpoint da API (padrão: https://ilinkai.weixin.qq.com) |
Para a interface programática, veja references/programmatic-api.md.