WeChat

OpenClaw si connette a WeChat tramite il plugin di canale esterno @tencent-weixin/openclaw-weixin di Tencent.

Stato: plugin esterno, gestito dal team Tencent Weixin. Sono supportate le chat dirette e i contenuti multimediali. Le chat di gruppo non sono indicate nei metadati delle funzionalità del plugin (che dichiara solo le chat dirette).

Nomenclatura

• WeChat è il nome rivolto agli utenti in questa documentazione.
• Weixin è il nome usato dal pacchetto di Tencent e dall'ID del plugin.
• openclaw-weixin è l'ID del canale OpenClaw (weixin e wechat funzionano come alias).
• @tencent-weixin/openclaw-weixin è il pacchetto npm.

Usa openclaw-weixin nei comandi CLI e nei percorsi di configurazione.

Funzionamento

Il codice di WeChat non risiede nel repository principale di OpenClaw. OpenClaw fornisce il contratto generico per i plugin di canale, mentre il plugin esterno fornisce il runtime specifico per WeChat:

1. openclaw plugins install installa @tencent-weixin/openclaw-weixin.
2. Il Gateway rileva il manifesto del plugin e ne carica il punto di ingresso.
3. Il plugin registra l'ID di canale openclaw-weixin.
4. openclaw channels login --channel openclaw-weixin avvia l'accesso tramite codice QR.
5. Il plugin archivia le credenziali dell'account nella directory di stato di OpenClaw (~/.openclaw per impostazione predefinita).
6. All'avvio del Gateway, il plugin avvia il monitor di Weixin per ogni account configurato.
7. I messaggi WeChat in entrata vengono normalizzati tramite il contratto del canale, instradati all'agente OpenClaw selezionato e inviati in risposta tramite il percorso in uscita del plugin.

Questa separazione è importante: il nucleo di OpenClaw rimane indipendente dai canali. L'accesso a WeChat, le chiamate all'API Tencent iLink, il caricamento e lo scaricamento di contenuti multimediali, i token di contesto e il monitoraggio degli account sono gestiti dal plugin esterno.

Installazione

Installazione rapida:

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

Installazione manuale:

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

Riavvia il Gateway dopo l'installazione:

openclaw gateway restart

Accesso

Esegui l'accesso tramite codice QR sulla stessa macchina che esegue il Gateway:

openclaw channels login --channel openclaw-weixin

Scansiona il codice QR con WeChat sul telefono e conferma l'accesso. Dopo una scansione riuscita, il plugin salva localmente il token dell'account.

Per aggiungere un altro account WeChat, esegui di nuovo lo stesso comando di accesso. Per più account, isola le sessioni dei messaggi diretti in base ad account, canale e mittente:

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

Controllo degli accessi

I messaggi diretti usano il normale modello di abbinamento ed elenco consentiti di OpenClaw per i plugin di canale.

Approva i nuovi mittenti:

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

Per il modello completo di controllo degli accessi, consulta Abbinamento.

Compatibilità

Il plugin controlla all'avvio la versione di OpenClaw dell'host.

Se il plugin segnala che la versione di OpenClaw è troppo vecchia, aggiorna OpenClaw oppure installa la serie legacy del plugin:

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

Processo sidecar

Il plugin WeChat può eseguire attività ausiliarie accanto al Gateway mentre monitora l'API Tencent iLink. Nel problema #68451, questo percorso ausiliario ha rivelato un bug nella pulizia generica dei Gateway obsoleti di OpenClaw: un processo figlio poteva tentare di ripulire il processo Gateway padre, causando cicli di riavvio con gestori di processi come systemd.

L'attuale pulizia all'avvio di OpenClaw esclude il processo corrente e i suoi antenati, quindi un processo ausiliario del canale non può terminare il Gateway che lo ha avviato. Questa correzione è generica e non costituisce un percorso specifico per WeChat nel nucleo.

Risoluzione dei problemi

Controlla l'installazione e lo stato:

openclaw plugins listopenclaw channels status --probeopenclaw --version

Se il canale risulta installato ma non si connette, verifica che il plugin sia abilitato e riavvia:

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

Se il Gateway si riavvia ripetutamente dopo l'abilitazione di WeChat, aggiorna sia OpenClaw sia il plugin:

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

Se all'avvio viene segnalato che il pacchetto del plugin installato requires compiled runtime output for TypeScript entry, il pacchetto npm è stato pubblicato senza i file runtime JavaScript compilati necessari a OpenClaw. Aggiorna o reinstalla il plugin dopo che il relativo autore avrà pubblicato un pacchetto corretto, oppure disabilita o disinstalla temporaneamente il plugin.

Disabilitazione temporanea:

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

Documentazione correlata

• Panoramica dei canali: Canali di chat
• Abbinamento: Abbinamento
• Instradamento dei canali: Instradamento dei canali
• Architettura dei plugin: Architettura dei plugin
• SDK per i plugin di canale: SDK per i plugin di canale
• Pacchetto esterno: @tencent-weixin/openclaw-weixin