Skip to main content
Questa pagina è pensata per non dover chiedere in giro: per ogni problema trovi il messaggio che vedi, il motivo, il passo per risolverlo e come controlli che ha funzionato. Se il tuo caso non è qui, scrivilo in #mattone-team — vedi in fondo.

​
macOS blocca lo script

Perché succede: lo script non ha una firma Apple a pagamento (Developer ID). macOS blocca per prudenza qualunque script scaricato da internet la prima volta che lo apri.Cosa fare:
  1. Al messaggio, clicca Fine (non Sposta nel Cestino).
  2. Apri Impostazioni di Sistema → Privacy e sicurezza, scorri fino in fondo.
  3. Accanto a “installa.command” è stato bloccato clicca Apri comunque.
  4. Inserisci la password del Mac e conferma Apri.
Su versioni di macOS più vecchie basta un clic destro sul file → Apri → Apri nella finestra che compare.Come verifichi: si apre una finestra del Terminale con scritto “Collegamento di WhatsApp a questo Mac”. Se non si apre nulla, il file è stato spostato dalla cartella del kit: riestrai lo zip.

​
uv mancante (Mac e Windows)

Perché succede: configura-claude.command/configura-claude.ps1 usa uv per preparare i componenti Python del collegamento. È un programma separato, non incluso nel kit.Cosa fare:
  • Mac: lo script stampa il comando ufficiale da incollare nel Terminale (da docs.astral.sh/uv). Incollalo, premi Invio, aspetta che finisca, poi rifai doppio clic su configura-claude.command.
  • Windows: lo script stampa il comando ufficiale da incollare in PowerShell. Eseguilo, aspetta che finisca, poi rilancia configura-claude.ps1.
Non serve riavviare il computer; basta chiudere e riaprire il Terminale/PowerShell perché il nuovo comando venga trovato.Come verifichi: rilanciando lo script, la prima riga diventa “uv trovato: …” invece di fermarsi con l’errore.

​
La porta 8080 è occupata

Perché succede: il collegamento usa sempre la porta 8080 per parlare con Claude. Se un altro programma la sta già usando (spesso un altro collegamento WhatsApp già avviato, o uno strumento di sviluppo lasciato acceso), l’installazione non può ripartire su quella porta.Cosa fare: lo script elenca il programma che la occupa. Chiudilo (o, se è un collegamento WhatsApp installato in precedenza e non ti serve più, esegui prima disinstalla.command) e rilancia installa.command.Come verifichi: l’installazione prosegue oltre il controllo della porta senza fermarsi.
Stesso motivo e stessa soluzione del Mac qui sopra: chiudi il programma indicato (o disinstalla un’installazione precedente con disinstalla.ps1) e rilancia installa.ps1.Se non riconosci il programma indicato, manda uno screenshot di quella finestra in #mattone-team prima di chiudere qualcosa a caso.

​
Il codice è scaduto

Perché succede: il codice di abbinamento vale solo pochi minuti. Se il telefono resta troppo a lungo sulla schermata di inserimento, o la connessione è lenta, scade prima che tu lo inserisca.Cosa fare: non è un errore, è normale. Rilancia lo script di installazione (installa.command su Mac, installa.ps1 su Windows): te ne dà uno nuovo. Tieni il telefono sbloccato e con una connessione stabile prima di far partire lo script, così hai tutto il tempo per inserirlo.Come verifichi: compare un nuovo codice a lettere grandi e, dopo averlo inserito sul telefono, la scritta COLLEGATO!.

​
Il collegamento non risulta collegato (loggedIn falso)

Perché succede: il collegamento vero e proprio con WhatsApp non si è concluso — di solito perché il codice è scaduto prima di essere confermato sul telefono, o la connessione è caduta a metà.Cosa fare:
  1. Controlla di aver confermato il collegamento sul telefono (a volte WhatsApp chiede una seconda conferma dopo il codice: guarda se c’è una notifica in sospeso).
  2. Se sono passati più di 4 minuti dal codice senza che risultasse collegato, rilancia lo script: ne genera uno nuovo.
  3. Se il problema si ripete più volte di fila, esegui disinstalla.command/disinstalla.ps1, cancella la cartella store dentro WhatsAppBridge e riparti dall’installazione da zero (sezione più sotto).
Come verifichi: dopo l’abbinamento riuscito, lo script stampa «Collegamento attivo» (o, su Windows, «Collegamento attivo e con avvio automatico»).

​
Claude Desktop non vede lo strumento WhatsApp

Perché succede: quasi sempre non hai chiuso Claude Desktop del tutto dopo aver incollato la configurazione — resta attivo in background e continua a usare la configurazione vecchia.Cosa fare:
  1. Mac: chiudi Claude Desktop con Cmd+Q (non basta chiudere la finestra), controlla che non compaia più nel Dock, poi riaprilo.
  2. Windows: chiudi Claude Desktop anche dall’icona vicino all’orologio (tasto destro → Esci), non solo dalla finestra, poi riaprilo.
  3. Rilancia configura-claude.command/configura-claude.ps1: deve dire che la configurazione è già valida. Se dice il contrario, il testo copiato non è finito nel punto giusto del file: segui di nuovo l’indicazione che stampa lo script.
Come verifichi: apri la lista degli strumenti in Claude Desktop e cerca whatsapp.

​
Il telefono è rimasto offline più di 14 giorni

Perché succede: è una regola di WhatsApp, non del kit: se il telefono con il numero collegato non viene usato per più di 14 giorni, WhatsApp scollega tutti i dispositivi collegati, compreso questo.Cosa fare: riparti dall’installazione da zero (sezione sotto). Non c’è un modo per “ricollegare” senza rifare l’abbinamento: è una scelta di sicurezza di WhatsApp.Come verifichi: dopo aver reinstallato, sul telefono in Dispositivi collegati torna a comparire Chrome (Linux).

​
Reinstallare da capo

Serve quando il telefono si è scollegato da solo (14 giorni offline, o 30 giorni di inattività del collegamento), o dopo più tentativi falliti di abbinamento.Mac:
  1. Doppio clic su disinstalla.command (nel kit o dentro ~/WhatsAppBridge).
  2. Nella cartella Inizio → WhatsAppBridge, cancella la cartella store.
  3. Rilancia installa.command come alla prima installazione.
Windows:
  1. Clic destro su disinstalla.ps1 → Esegui con PowerShell.
  2. In %USERPROFILE%\WhatsAppBridge, cancella la cartella store.
  3. Rilancia installa.ps1 come alla prima installazione.
Come verifichi: ottieni un nuovo codice di abbinamento e, dopo averlo inserito, la scritta COLLEGATO!.

​
Gli strumenti WhatsApp dell’MCP Mattone Platform dicono «non raggiungibile da questa macchina»

Perché succede: l’MCP Mattone Platform cerca l’MCP WhatsApp sullo stesso computer. Se non lo trova, è quasi sempre uno di questi tre casi:
  • l’MCP WhatsApp non è installato su questo computer (magari è installato su un altro);
  • è installato ma non è mai stato collegato con un numero (l’abbinamento non è arrivato in fondo — vedi “Il collegamento non risulta collegato” qui sopra);
  • il collegamento è stato spostato fuori dalla cartella che il kit crea di default.
Cosa fare: installa (o reinstalla nella cartella di default) l’MCP WhatsApp seguendo Installazione — Mac o Installazione — Windows, poi chiudi e riapri Claude Code: lo trova al riavvio successivo, senza bisogno di reinstallare l’MCP Mattone Platform.Come verifichi: vedi Collegarlo all’MCP Mattone Platform.

​
Non risolto qui?

Scrivilo in #mattone-team con:
  • se sei su Mac o Windows;
  • il messaggio esatto che vedi (uno screenshot va benissimo, controlla prima che non si vedano chat, numeri o nomi di altre persone);
  • a che passo dell’installazione sei arrivato.
Se una risposta di questa pagina non ti risolve il problema, dillo in #mattone-team: vuol dire che la pagina va corretta o completata. Vedi Manutenzione docs.