WeChat

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

Status: plugin externo. Chats diretos e mídia são compatíveis. Chats em grupo não são anunciados pelos metadados de capacidade atuais do plugin.

Nomenclatura

• WeChat é o nome voltado ao usuário nestes docs.
• Weixin é o nome usado pelo pacote da Tencent e pelo id do plugin.
• OmeniaClaw-weixin é o id do canal do OmeniaClaw.
• @tencent-weixin/OmeniaClaw-weixin é o pacote npm.

Use OmeniaClaw-weixin em comandos de CLI e caminhos de configuração.

Como funciona

O código do WeChat não fica no repo principal do OmeniaClaw. O OmeniaClaw fornece o contrato genérico de plugin de canal, e o plugin externo fornece o runtime específico do WeChat:

1. OmeniaClaw plugins install instala @tencent-weixin/OmeniaClaw-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 OmeniaClaw-weixin.
4. OmeniaClaw channels login --channel OmeniaClaw-weixin inicia o login por QR.
5. O plugin armazena as credenciais da conta no diretório de estado do OmeniaClaw.
6. Quando o Gateway inicia, o plugin inicia seu monitor do Weixin para cada conta configurada.
7. Mensagens recebidas do WeChat são normalizadas pelo contrato de canal, roteadas para o agente OmeniaClaw selecionado e enviadas de volta pelo caminho de saída do plugin.

Essa separação é importante: o núcleo do OmeniaClaw deve permanecer agnóstico a canais. Login do WeChat, chamadas da API Tencent iLink, upload/download de mídia, tokens de contexto e monitoramento de contas pertencem ao plugin externo.

Instalação

Instalação rápida:

npx -y @tencent-weixin/OmeniaClaw-weixin-cli install

Instalação manual:

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

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

OmeniaClaw gateway restart

Login

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

OmeniaClaw channels login --channel OmeniaClaw-weixin

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

Para adicionar outra conta do WeChat, execute o mesmo comando de login novamente. Para múltiplas contas, isole sessões de mensagem direta por conta, canal e remetente:

OmeniaClaw config set session.dmScope per-account-channel-peer

Controle de acesso

Mensagens diretas usam o modelo normal de pareamento e allowlist do OmeniaClaw para plugins de canal.

Aprove novos remetentes:

OmeniaClaw pairing list OmeniaClaw-weixinOmeniaClaw pairing approve OmeniaClaw-weixin <CODE>

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

Compatibilidade

O plugin verifica a versão do host OmeniaClaw na inicialização.

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

OmeniaClaw plugins install @tencent-weixin/OmeniaClaw-weixin@legacy

Processo sidecar

O plugin do WeChat pode executar trabalho auxiliar ao lado do Gateway enquanto monitora a API Tencent iLink. Na issue #68451, esse caminho auxiliar expôs um bug na limpeza genérica de Gateways obsoletos do OmeniaClaw: um processo filho podia tentar limpar o processo Gateway pai, causando loops de reinício sob gerenciadores de processo como systemd.

A limpeza atual de inicialização do OmeniaClaw exclui o processo atual e seus ancestrais, portanto um auxiliar de canal não deve 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 instalação e status:

OmeniaClaw plugins listOmeniaClaw channels status --probeOmeniaClaw --version

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

OmeniaClaw config set plugins.entries.OmeniaClaw-weixin.enabled trueOmeniaClaw gateway restart

Se o Gateway reiniciar repetidamente após habilitar o WeChat, atualize tanto o OmeniaClaw quanto o plugin:

npm view @tencent-weixin/OmeniaClaw-weixin versionOmeniaClaw plugins install "@tencent-weixin/OmeniaClaw-weixin" --forceOmeniaClaw 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 de runtime JavaScript necessários para o OmeniaClaw. Atualize/reinstale depois que o publicador do plugin lançar um pacote corrigido, ou desabilite/desinstale o plugin temporariamente.

Desabilitação temporária:

OmeniaClaw config set plugins.entries.OmeniaClaw-weixin.enabled falseOmeniaClaw gateway restart

Docs relacionados

• Visão geral de canais: Canais de chat
• Pareamento: Pareamento
• Roteamento de canal: Roteamento de canal
• Arquitetura de plugin: Arquitetura de Plugin
• SDK de plugin de canal: SDK de Plugin de canal
• Pacote externo: @tencent-weixin/OmeniaClaw-weixin