Risoluzione problemi

Tre controlli che risolvono quasi tutto#

1. Il plugin risponde? Apri https://your-site.example/wp-json/wpcb/v1/health nel browser. Dovresti vedere "status":"ok" e la versione del plugin. Un 404 vuol dire che il plugin non è attivo, oppure che l’API REST è bloccata da un plugin di sicurezza o dal server.
2. Il token è valido? In Xaflo → Tokens controlla che non sia scaduto o revocato. Nel dubbio, creane uno nuovo.
3. Il client è stato riavviato? I client AI avviano i server MCP quando partono. Dopo ogni modifica alla configurazione chiudi del tutto il client e riaprilo. In Claude Code, /mcp mostra ogni server e se si è collegato.

Dopo l’aggiornamento alla 1.7.0#

Il plugin 1.7.0 ha cambiato alcune regole di proposito. Se qualcosa ha smesso di funzionare subito dopo l’aggiornamento, probabilmente è uno di questi casi. Tutti i passaggi sono in Aggiornare alla 1.7.0.

Tutti i token rispondono 401#

È previsto dopo Ruota chiave: la rotazione invalida tutti i token. Creane di nuovi in Xaflo → Token e sostituiscili in ogni client. Finché non ruoti, i token vecchi continuano a funzionare, ma la rotazione è obbligatoria.

403 xaflo_fs_outside_uploads#

site:write ora cambia file solo dentro wp-content/uploads, e solo documenti, immagini, audio, video e archivi. Per cambiare file di temi o plugin, o qualsiasi altra cosa fuori da uploads, il token deve avere anche fs:admin, e serve un account amministratore. I file protetti come wp-config.php e .env non cambiano mai.

/db/query risponde 409, o rifiuta una query che prima funzionava#

• Le scritture richiedono che le tabelle users, usermeta, options e dei token usino InnoDB.
• L’intera route viene rifiutata quando MySQL gira con NO_BACKSLASH_ESCAPES o ANSI_QUOTES, con una connessione big5, cp932, gbk, gb18030 o sjis, o quando queste impostazioni non si possono leggere. Chiedi al tuo hosting quale modalità SQL usa.
• Con params si accettano solo %s, %d e %f semplici; codici come unsupported_placeholder vogliono dire che un % va passato come valore.
• La route richiede un account amministratore, e gli hash delle password tornano come [redacted: password hash].

La lista di IP consentiti non viene applicata#

Una lista salvata con la 1.6.0 viene applicata solo dopo averla salvata di nuovo da Xaflo → Impostazioni. La pagina mostra se è applicata, salvata ma non applicata, o spenta.

Un token creato da un Editor o da un Autore viene rifiutato#

Ogni route con token ora controlla una capability di WordPress. I contenuti continuano a funzionare, ma database, file, backup, manutenzione e route simili richiedono un token creato da un amministratore.

“Apri wp-admin” non mi fa entrare#

L’accesso rapido richiede il plugin 1.7.0, un token con admin:login creato da un amministratore, e HTTPS (altrimenti 426). Viene rifiutato mentre è attivo un plugin noto di accesso a due fattori (409 wpcb_login_link_2fa), e quando il tuo indirizzo è fuori dalla lista di IP consentiti. Ogni link funziona una volta, per 60 secondi.

Il Deploy o l’installazione da zip viene rifiutato#

wpcb_hash_mismatch: lo zip è cambiato per strada. wpcb_too_large: oltre 20 MB o oltre il limite di caricamento del server. wpcb_invalid_package: non contiene esattamente una cartella di plugin con l’intestazione Plugin Name:. Sostituire un plugin già installato chiede prima conferma.

Errori dell’API#

401 wpcb_unauthorized#

La richiesta non aveva un token valido: mancante, copiato male, scaduto, revocato o emesso da un altro sito.

• Copia di nuovo il token; viene mostrato una volta sola, quindi se l’hai perso creane uno nuovo.
• Alcuni hosting tolgono l’header Authorization prima che arrivi a PHP. Il plugin accetta il token anche in X-WPCB-Authorization e legge le variabili che Apache usa per un header inoltrato. Su Apache puoi far passare l’header con questa riga in .htaccess:

SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

“Issuer mismatch”#

Il token è stato creato su un altro indirizzo del sito: con o senza www, una copia di staging, oppure un sito che ha cambiato dominio. I token valgono solo per l’indirizzo che li ha emessi. Crea un nuovo token sul sito così com’è adesso.

403 wpcb_forbidden#

Il token è valido ma non ha il permesso per questa operazione. Gli manca lo scope, oppure l’utente WordPress che l’ha creato non ha la capability (un Editor non può installare plugin, qualunque cosa dica il token). Crea un token con lo scope giusto, oppure crealo da amministratore. Le route riservate agli amministratori, come il registro, rispondono “Admin only.”

426 wpcb_upgrade_required#

La richiesta è arrivata in HTTP semplice. Il plugin accetta solo HTTPS, tranne sugli host di sviluppo locale (localhost, 127.0.0.1, *.localhost, *.test, *.local). Usa l’indirizzo https:// del sito nella configurazione e assicurati che il sito stesso sia servito in HTTPS.

428 wpcb_confirmation_required#

Non è un errore: l’operazione è distruttiva e richiede un secondo passaggio esplicito. La risposta contiene un confirmation_token e un riepilogo di cosa succederà. L’assistente ti mostra il riepilogo e ripete la chiamata con il token. Come funziona la conferma.

wpcb_confirmation_invalid vuol dire che il token di conferma è scaduto (dopo 5 minuti), è già stato usato o appartiene a un’altra operazione. Ricomincia l’operazione.

429 wpcb_rate_limited#

Il token ha fatto troppe richieste in un minuto: 60 di default, meno per gli scope delicati. Aspetta i secondi indicati nell’header Retry-After e riprendi. Se un lavoro lungo sbatte sempre contro il limite, chiedi all’assistente di procedere a blocchi più piccoli, oppure alza il limite nelle impostazioni del plugin. Limiti per scope.

Problemi di installazione#

“A signing secret must be added to wp-config.php before API tokens can be issued.”#

Nessun token può essere creato finché non esiste WPCB_JWT_SECRET. Vai su Xaflo → Settings e installa la chiave, oppure aggiungi tu la riga suggerita in wp-config.php. Passo per passo.

I tool non compaiono in Claude o ChatGPT#

• Chiudi e riapri il client: ricaricare una finestra non basta.
• Xaflo Desktop 2.0.1 e successivi contengono il server MCP e all’avvio riparano le voci rotte: aggiornalo, poi usa di nuovo Configura Claude e ChatGPT sul sito. Senza Desktop, controlla che il server sia installato: npm ls -g claude-wp-mcp deve elencarlo.
• Controlla --site e --token nella configurazione, e che il JSON sia valido.
• Senza Xaflo Desktop, il server MCP ha bisogno di Node.js 18 o successivo: node --version.

La pagina Audit Log dice “Request failed”, o Maintenance dice “Missing authorization header”#

Risolto nel plugin 1.5.1: quelle pagine dell’amministrazione ora accettano la tua sessione. Aggiorna il plugin da Plugin; la versione attuale è la 1.7.0.

WordPress non propone la nuova versione#

WordPress controlla gli aggiornamenti dei plugin con i suoi tempi. Usa il link Check for updates sulla riga del plugin in Plugin, oppure installa lo zip dalla pagina Scarica sopra quello vecchio.

Problemi con i contenuti#

Ho chiesto di pubblicare ed è stato salvato come bozza#

Il token ha content:write ma non content:publish. In questo caso creare o aggiornare con stato “publish” salva una bozza, per scelta. Aggiungi content:publish al token, oppure pubblica da WordPress.

Script, stili o attributi sono spariti dalla pagina#

WordPress ha filtrato il markup perché l’utente dietro al token non può pubblicare HTML non filtrato. La risposta lo segnala con content_filtered: true. I token creati da un amministratore (che ha unfiltered_html) salvano il markup così com’è. Per evitare che WordPress aggiunga paragrafi attorno a un layout, invia content_format: "html", che lo avvolge in un blocco HTML personalizzato.

I tool multilingua non trovano lingue#

Oggi i tool multilingua funzionano con WPML. Su un sito senza WPML, wp_multilingual_detect indica l’adattatore null e gli altri tool multilingua non hanno nulla su cui lavorare. L’endpoint di salute mostra lo stesso nel campo multilingual.

I tool di analytics non restituiscono nulla#

I tool di analytics leggono da un plugin di statistiche già presente sul sito. Chiedi prima all’assistente di eseguire wp_analytics_detect: ti dice quale fonte ha trovato, se ne ha trovata una.

Strumenti avanzati#

wp_cli_exec dice che WP-CLI è disattivato#

È spento su ogni sito finché il proprietario non lo attiva (opzione wpcb_cli_enabled) e WP-CLI non è installato sul server. Anche allora esegue solo un elenco di comandi ammessi, come cache flush, transient delete --all, option get o core version. Dalla 1.7.0 il comando deve coincidere esattamente con una voce, con i valori in args e solo le opzioni ammesse per quel comando. Richiede lo scope cli:exec e un token di amministratore.

Una query SQL viene rifiutata#

La protezione SQL accetta un’istruzione alla volta, solo su tabelle con il prefisso del tuo sito, e solo SELECT a meno che la chiamata non chieda la modalità di scrittura con db:write, che poi chiede conferma. Le modifiche di struttura (DROP, ALTER, CREATE…), l’accesso ai file, le funzioni di attesa, altri database, WITH e i commenti eseguibili sono sempre rifiutati, ognuno con il suo codice. Una SELECT senza LIMIT restituisce al massimo 1000 righe. Vedi anche /db/query risponde 409.

Ancora bloccato?#

Guarda in Xaflo → Audit Log: ogni chiamata è lì con il risultato e il messaggio di errore. Poi scrivici con il codice di errore, la versione del plugin indicata da /health e cosa avevi chiesto all’assistente.