OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Regional platforms

WeChat

Status: plugin externo, mantido pela equipe Tencent Weixin. Conversas diretas e

O OpenClaw se conecta ao WeChat por meio do plugin de canal externo @tencent-weixin/openclaw-weixin da Tencent.

Status: plugin externo, mantido pela equipe Tencent Weixin. Conversas diretas e mídia são compatíveis. Conversas em grupo não são anunciadas pelos metadados de recursos do plugin (ele declara apenas conversas diretas).

Nomenclatura

  • WeChat é o nome apresentado ao usuário nesta documentação.
  • Weixin é o nome usado pelo pacote da Tencent e pelo id do plugin.
  • openclaw-weixin é o id do canal do OpenClaw (weixin e wechat funcionam como aliases).
  • @tencent-weixin/openclaw-weixin é o pacote npm.

Use openclaw-weixin nos comandos da CLI e nos caminhos de configuração.

Como funciona

O código do WeChat não fica no repositório principal do OpenClaw. O OpenClaw fornece o contrato genérico de plugin de canal, e o plugin externo fornece o ambiente de execução específico do WeChat:

  1. openclaw plugins install instala @tencent-weixin/openclaw-weixin.
  2. O Gateway descobre o manifesto do plugin e carrega o ponto de entrada do plugin.
  3. O plugin registra o id de canal openclaw-weixin.
  4. openclaw channels login --channel openclaw-weixin inicia o login por código QR.
  5. O plugin armazena as credenciais da conta no diretório de estado do OpenClaw (~/.openclaw por padrão).
  6. Quando o Gateway é iniciado, o plugin inicia seu monitor do Weixin para cada conta configurada.
  7. As mensagens recebidas do WeChat são normalizadas pelo contrato de canal, encaminhadas ao agente selecionado do OpenClaw e respondidas pelo caminho de saída do plugin.

Essa separação é importante: o núcleo do OpenClaw permanece independente de canais. O login no WeChat, as chamadas à API Tencent iLink, o envio e recebimento de mídia, os tokens de contexto e o monitoramento de contas são responsabilidade do plugin externo.

Instalação

Instalação rápida:

bash
npx -y @tencent-weixin/openclaw-weixin-cli install

Instalação manual:

bash
openclaw plugins install "@tencent-weixin/openclaw-weixin"openclaw config set plugins.entries.openclaw-weixin.enabled true

Reinicie o Gateway após a instalação:

bash
openclaw gateway restart

Login

Execute o login por código QR na mesma máquina que executa o Gateway:

bash
openclaw channels login --channel openclaw-weixin

Escaneie o código QR com o WeChat no celular e confirme o login. O plugin salva localmente o token da conta após uma leitura bem-sucedida.

Para adicionar outra conta do WeChat, execute novamente o mesmo comando de login. Para várias contas, isole as sessões de mensagens diretas por conta, canal e remetente:

bash
openclaw config set session.dmScope per-account-channel-peer

Controle de acesso

As mensagens diretas usam o modelo normal de pareamento e lista de permissões do OpenClaw para plugins de canal.

Aprove novos remetentes:

bash
openclaw pairing list openclaw-weixinopenclaw pairing approve openclaw-weixin <CODE>

Para conhecer o modelo completo de controle de acesso, consulte Pareamento.

Compatibilidade

O plugin verifica a versão do OpenClaw do host durante a inicialização.

Linha do plugin Versão do OpenClaw Tag npm
2.x >=2026.5.12 (2.4.6 atual; versões 2.x iniciais aceitavam >=2026.3.22) latest
1.x >=2026.1.0 <2026.3.22 legacy

Se o plugin informar que sua versão do OpenClaw é antiga demais, atualize o OpenClaw ou instale a linha legada do plugin:

bash
openclaw plugins install @tencent-weixin/openclaw-weixin@legacy

Processo auxiliar

O plugin do WeChat pode executar tarefas auxiliares ao lado do Gateway enquanto monitora a API Tencent iLink. No issue nº 68451, esse caminho auxiliar expôs um bug na limpeza genérica de Gateways obsoletos do OpenClaw: um processo filho podia tentar limpar o processo pai do Gateway, causando ciclos de reinicialização em gerenciadores de processos como o systemd.

A limpeza atual de inicialização do OpenClaw exclui o processo atual e seus ancestrais, portanto, um auxiliar de canal não pode encerrar o Gateway que o iniciou. Essa correção é genérica; não é um caminho específico do WeChat no núcleo.

Solução de problemas

Verifique a instalação e o status:

bash
openclaw plugins listopenclaw channels status --probeopenclaw --version

Se o canal aparecer como instalado, mas não se conectar, confirme se o plugin está habilitado e reinicie:

bash
openclaw config set plugins.entries.openclaw-weixin.enabled trueopenclaw gateway restart

Se o Gateway reiniciar repetidamente após a ativação do WeChat, atualize o OpenClaw e o plugin:

bash
npm view @tencent-weixin/openclaw-weixin versionopenclaw plugins install "@tencent-weixin/openclaw-weixin" --forceopenclaw gateway restart

Se a inicialização informar que o pacote de plugin instalado requires compiled runtime output for TypeScript entry, o pacote npm foi publicado sem os arquivos compilados do ambiente de execução JavaScript necessários ao OpenClaw. Atualize ou reinstale depois que o publicador do plugin disponibilizar um pacote corrigido, ou desative/desinstale temporariamente o plugin.

Desativação temporária:

bash
openclaw config set plugins.entries.openclaw-weixin.enabled falseopenclaw gateway restart

Documentação relacionada

Was this useful?
On this page

On this page