Scopri perché un mod non fa nulla
Quando un mod non fa nulla, due controlli trovano il motivo: cosa Claude Code legge dai file del mod e la riga che scrive quando salta qualcosa. Per il primo, nella tua shell eseguiclaude plugin validate con la directory del mod, come in claude plugin validate ./first-mod. Cattura un evento scritto male, un manifest errato e un modulo che Claude Code non riesce a leggere, senza avviare una sessione.
Quando un modulo non si carica, un hook viene saltato o un altro mod rifiuta il tuo, Claude Code scrive una riga che nomina il tuo mod. Dove leggi quella riga dipende dalla sessione:
- Una sessione che ricarica a caldo una directory di plugin: una riga attenuata nella trascrizione. È una sessione interattiva che hai avviato con
--plugin-dir, oppure una in cui hai abilitato il ricaricamento a caldo per i mod che Claude ha scritto. - Qualsiasi altra sessione interattiva, come una che esegue un mod che hai installato da un marketplace: il debug log solo. Per ottenerne uno, avvia la sessione con
claude --debug. - Un’esecuzione
claude -pcon--plugin-dir: stderr, nel formato di output di testo predefinito. Un rifiuto da parte di un altro mod va al debug log solo.
Controlla se i mod possono caricarsi
Per verificare se la tua configurazione consente ai mod di caricarsi affatto, senza installarne uno, eseguiclaude plugin test nella tua shell, da una directory che non contiene un mod. Non hai bisogno di una sessione. Il messaggio che stampa ti dice lo stato:
Un’organizzazione può anche impostare
allowManagedModsOnly per consentire solo i suoi mod, che questo comando non segnala. In quel caso un mod che installi non si carica e un messaggio spiega perché.
Il mod non si carica
Nulla di ciò che il mod aggiunge appare: nessun comando, nessun disegno e nessun cambiamento nel comportamento.La tua versione è più vecchia di 2.1.287
claude --version stampa una versione più vecchia di 2.1.287. La tua versione è precedente ai mod attivi per impostazione predefinita.
Aggiorna Claude Code.
La riga mods active non nomina il mod
Nulla di ciò che il mod aggiunge appare e la riga mods active in /plugin non lo nomina. Il modulo hooks non si è caricato. Quando Claude Code lo ha rifiutato, il debug log ha una riga che inizia con hooks module, il nome del mod e not loaded:, come in hooks module first-mod@inline not loaded: disableAllHooks in managed settings per un mod caricato con --plugin-dir.
Leggi il motivo dopo i due punti. La sezione refusal messages elenca ognuno. Se il log non ha tale riga, esamina le altre voci in questo gruppo.
Un’esecuzione claude -p stampa hooks module not loaded
La riga inizia con il nome del mod e va a stderr. Il modulo hooks è stato rifiutato. Un’esecuzione non interattiva non ha trascrizione, quindi il messaggio va a stderr.
Leggi il motivo dopo i due punti. La sezione refusal messages elenca ognuno.
Refusal messages
Ognuno di questi seguehooks module, il nome del mod e not loaded: nel debug log.
Messages from the built-in guard
Su una macchina con impostazioni gestite, o per un utente connesso con un piano Team o Enterprise, la built-in guard può rifiutare un mod o una delle sue risposte. Ogni messaggio nomina l’opzione che l’amministratore della tua organizzazione imposta per modificare la regola.validate passa e non elenca alcuna riga hooks
hooks/hooks.json non ha una chiave modules, oppure la chiave è scritta male.
Aggiungi "modules": ["./register.js"].
hooks module did not load
La riga inizia con il nome del mod, quindi hooks module did not load: e un motivo, che fornisce il file e la riga quando il problema è nel tuo codice. Claude Code non ha potuto caricare il modulo, ad esempio perché il suo codice di livello superiore ha lanciato un’eccezione.
Correggi l’errore che il motivo nomina.
options do not fit plugin.json userConfig
La riga inizia con il nome del mod, quindi hooks module did not load: options do not fit plugin.json userConfig: e un motivo. Un’opzione non si adatta al suo campo userConfig, come un numero superiore al max del campo, oppure un campo obbligatorio non ha valore.
Imposta o modifica il valore. La fine della riga nomina la sua voce pluginConfigs in settings.json.
Nessun mod si carica in una directory che hai aperto per la prima volta
Non hai risposto al prompt di fiducia per la directory. Avvia una sessione interattiva in quella directory conclaude e accetta il prompt di fiducia che apre.
Nessun plugin installato si carica affatto
Hai avviato Claude Code con--safe-mode.
Avvia senza il flag.
Un hook viene saltato o un mod viene scaricato
Il mod si è caricato e poi Claude Code ha saltato uno dei suoi hooks o lo ha scaricato.hook skipped
La riga nomina il mod e l’evento, quindi dice hook skipped: e un motivo, come in first-mod: tool.call hook skipped: threw Error: boom. Un hook ha lanciato un’eccezione, ha superato il suo limite di tempo di 10 secondi, oppure ha restituito un risultato di forma sbagliata. La riga appare una volta per ogni evento e tipo di errore fino al ricaricamento del mod.
Correggi l’errore. Il debug log ha una riga per ogni occorrenza.
it crashed the hooks worker
La riga inizia con il nome del mod, come in first-mod was unloaded: it crashed the hooks worker. I mod installati condividono un thread di lavoro. Il worker ha smesso di rispondere o si è bloccato e Claude Code ha tracciato che ciò è dovuto a questo mod e lo ha scaricato. Un hook che blocca il thread, come un ciclo che non attende mai, è una causa.
Correggi l’hook.
mods that run in the hooks worker are off for this session
La riga legge hooks: mods that run in the hooks worker are off for this session: it crashed 3 times. Il worker si è fermato tre volte e Claude Code non ha potuto tracciare gli arresti a un mod, quindi ha scaricato ogni mod che non è built-in, inclusi i mod che la tua organizzazione installa. Questa riga raggiunge la trascrizione in ogni sessione interattiva.
Esegui /reload-plugins per caricarli di nuovo.
Una chiamata di strumento viene negata
Il mod si è caricato e i suoi hooks vengono eseguiti e una chiamata di strumento che ha toccato viene rifiutata.a hook changed this call's input after the model wrote it
In modalità auto, una chiamata di strumento negata fornisce questo motivo. Un hook ha modificato l’input della chiamata di strumento dopo che il classificatore lato server lo ha esaminato, quindi quella revisione non copre ciò che verrebbe eseguito. L’hook può essere il tool.call o il turn.step hook del mod, oppure un hook di impostazioni PreToolUse. Il messaggio non dice quale.
Il messaggio dice a Claude di emettere la chiamata ancora una volta come registrata. Se viene negata anche quella, l’hook cambia l’input ogni volta, quindi disattiva il mod o l’hook, oppure esci dalla modalità auto e approva la chiamata tu stesso.
Un messaggio sulle regole di negazione nelle tue impostazioni
tried to lift a deny rule in your settings e the deny rules in your settings could not be checked for this call, so it is refused provengono entrambi dalla built-in guard.
Cercali in Messages from the built-in guard.
Un disegno non appare o non risponde
Il mod si è caricato e il tuo riquadro, banda o controlli non si comportano come ti aspetti.Un riquadro o una banda è vuoto o mostra il solito contenuto di Claude Code
L’albero che il tuo hook ha restituito non ha convalidato. Con--plugin-dir, la trascrizione dice ui.render (Pane) refused: con il motivo, come in first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own. Il debug log ha a hook returned a tree that does not validate con lo stesso motivo.
Leggi il motivo su quella riga. Le cause comuni sono una prop che l’elemento non accetta e un elemento che l’app non ha.
$.ui.open viene eseguito e nessun riquadro appare
La chiamata non è venuta da qualcosa che l’utente ha fatto e il terminale è più stretto di 144 colonne.
Apri il riquadro da un comando o un pulsante, oppure controlla il risultato isPlaced della chiamata. Vedi Open a pane at the right time.
I tasti di scelta rapida non fanno nulla
Il tuo riquadro non ha il focus della tastiera. Premi Ctrl+X quindi Tab, oppure fai clic sul riquadro. Aprilo confocus: true da un comando.
Un disegno funziona nel terminale e non nell’app Desktop
Il sito o l’elemento non è disponibile lì. Controlla le render sites e le tabelle elements.Una modifica o un valore viene perso
Il mod viene eseguito e una modifica che hai fatto o un valore che ha mantenuto non è lì.Le tue modifiche non hanno effetto
Stai modificando un plugin che hai installato. Claude Code esegue la copia memorizzata nella cache per la versione installata. Sviluppa con--plugin-dir puntato alla tua copia di lavoro, come in claude --plugin-dir ./first-mod, che ricarica quando salvi.
Un valore si ripristina quando il modulo si ricarica
Le variabili a livello di modulo vengono reinizializzate ad ogni ricaricamento. Mantieni il valore in$.state o $.store.
Un valore si ripristina dopo /clear, /resume o /branch
Un valore si ripristina, oppure un valore salvato viene sostituito dal suo valore predefinito. Ognuno di questi comandi ripristina $.state ai suoi valori predefiniti e session.start non si attiva di nuovo.
Carica il valore salvato di nuovo in un hook classic.SessionStart.
Read the debug log
Il debug log ha una riga per ogni modulo che Claude Code carica o rifiuta, ogni hook che fallisce e ogni risultato che rifiuta, quindi è dove guardare quando la trascrizione non mostra nulla. Per scriverne uno, nella tua shell avvia Claude Code con--debug, oppure con --debug-file <path> per scegliere dove va:
--plugin-dir appare sotto il suo nome seguito da @inline:
$.ui.log con un secondo argomento, come in $.ui.log('message', { to: 'debug' }). Senza il secondo argomento, $.ui.log aggiunge una riga attenuata alla trascrizione.
Mentre modifichi un mod caricato con --plugin-dir, la trascrizione mostra una riga per ogni ricaricamento che nomina il mod ed elenca i suoi hooks. Se un salvataggio interrompe il modulo, la riga dice reload failed, the previous version stays loaded: con il motivo e l’ultima versione funzionante continua a essere eseguita.
Next steps
- Test a mod: cattura i problemi prima che raggiungano una sessione
- Troubleshoot plugins: problemi con l’installazione e il caricamento di un plugin che non sono specifici dei mod