Solucionar problemas de um mod
Descubra por que um mod Claude Code não faz nada: corresponda o sintoma ou mensagem à sua causa, procure mensagens de recusa e leia o log de depuração.
Quando um módulo de um mod ou um de seus hooks falha, Claude Code o ignora e a sessão continua, então um mod quebrado pode parecer um que não faz nada. Comece verificando o que Claude Code leu do seu mod e onde ele relata um problema, depois encontre o sintoma ou mensagem que você tem.
Descubra por que um mod não faz nada
Quando um mod não faz nada, duas verificações encontram o motivo: o que Claude Code lê dos arquivos do mod e a linha que ele escreve quando ignora algo. Para a primeira, em seu shell execute claude plugin validate com o diretório do mod, como em claude plugin validate ./first-mod. Isso detecta um evento digitado incorretamente, um manifesto ruim e um módulo que Claude Code não consegue ler, sem iniciar uma sessão.
Quando um módulo não carrega, um hook é ignorado ou outro mod recusa o seu, Claude Code escreve uma linha que nomeia seu mod. Onde você lê essa linha depende da sessão:
- Uma sessão que recarrega dinamicamente um diretório de plugin: uma linha fraca na transcrição. Essa é uma sessão interativa que você iniciou com
--plugin-dir, ou uma onde você habilitou o recarregamento dinâmico para mods que Claude escreveu. - Qualquer outra sessão interativa, como uma que executa um mod que você instalou de um marketplace: o log de depuração apenas. Para obter um, inicie a sessão com
claude --debug. - Uma execução
claude -pcom--plugin-dir: stderr, no formato de saída de texto padrão. Uma recusa por outro mod vai apenas para o log de depuração.
Verifique se os mods podem carregar
Para verificar se sua configuração permite que os mods carreguem, sem instalar um, execute claude plugin test em seu shell, a partir de um diretório que não contenha um mod. Você não precisa de uma sessão. A mensagem que ele imprime informa o estado:
| A mensagem inclui | O que significa |
|---|---|
no hooks module to load |
Os mods podem carregar. O comando não encontrou nenhum mod para testar neste diretório. |
hooks modules are turned off here |
Uma configuração está mantendo seus mods fora: disableAllHooks em suas próprias configurações, ou a política de sua organização |
hooks modules are turned off in this process |
A Anthropic desativou os mods instalados remotamente. Nenhuma configuração em sua máquina os ativa novamente. |
Uma organização também pode definir allowManagedModsOnly para permitir apenas seus próprios mods, o que este comando não relata. Nesse caso, um mod que você instala não carrega, e uma mensagem diz por quê.
O mod não carrega
Nada que o mod adiciona aparece: nenhum comando, nenhum desenho e nenhuma mudança de comportamento.
Sua versão é mais antiga que 2.1.287
claude --version imprime uma versão mais antiga que 2.1.287. Sua versão é anterior aos mods estarem ativados por padrão.
A linha `mods active` não nomeia o mod
Nada que o mod adiciona aparece, e a linha mods active em /plugin não o nomeia. O módulo hooks não carregou. Quando Claude Code o recusou, o log de depuração tem uma linha que começa com hooks module, o nome do mod e not loaded:, como em hooks module first-mod@inline not loaded: disableAllHooks in managed settings para um mod carregado com --plugin-dir.
Leia o motivo após os dois pontos. A seção mensagens de recusa lista cada uma. Se o log não tiver tal linha, trabalhe através das outras entradas neste grupo.
Uma execução `claude -p` imprime `hooks module not loaded`
A linha começa com o nome do mod e vai para stderr. O módulo hooks foi recusado. Uma execução não interativa não tem transcrição, então a mensagem vai para stderr.
Leia o motivo após os dois pontos. A seção mensagens de recusa lista cada uma.
Mensagens de recusa
Cada uma delas segue hooks module, o nome do mod e not loaded: no log de depuração.
| A mensagem começa com | O que significa |
|---|---|
hooks modules are turned off for installed plugins in this process |
A Anthropic desativou os mods instalados remotamente. Nenhuma configuração em sua máquina os ativa novamente. |
disableAllHooks in managed settings |
Sua organização desativou hooks de plugins instalados |
only managed plugins and built-in plugins run |
allowManagedHooksOnly está definido, ou disableAllHooks está definido em um arquivo de configurações diferente de configurações gerenciadas |
installed plugins that are not managed load no hooks module in this mode (--bare) |
Você iniciou Claude Code com --bare |
another plugin of that name loads first |
Dois plugins compartilham um nome. O gerenciado, ou o carregado primeiro, é usado. |
Mensagens do guarda integrado
Em uma máquina com configurações gerenciadas, ou para um usuário conectado com um plano Team ou Enterprise, o guarda integrado pode recusar um mod ou uma de suas respostas. Cada mensagem nomeia a opção que o administrador de sua organização define para alterar a regra.
| A mensagem contém | O que significa | Onde aparece |
|---|---|---|
mods are limited to your organization's by policy (allowManagedModsOnly) |
Sua organização permite apenas seus próprios mods, então o seu não foi carregado | O log de depuração e a transcrição em uma sessão que recarrega dinamicamente um diretório de plugin |
tried to lift a deny rule in your settings |
O hook tool.check do seu mod aprovou uma chamada que uma regra deny recusa. A chamada permanece recusada. |
A transcrição e o log de depuração, uma vez para cada mod em uma sessão. Em uma execução claude -p, apenas o log de depuração. |
the deny rules in your settings could not be checked for this call, so it is refused |
O guarda falhou ao verificar uma chamada que um mod aprovou, então recusou a chamada | O motivo que Claude lê para a chamada recusada |
`validate` passa e não lista nenhuma linha `hooks`
hooks/hooks.json não tem uma chave modules, ou a chave está digitada incorretamente.
Adicione "modules": ["./register.js"].
`hooks module did not load`
A linha começa com o nome do mod, depois hooks module did not load: e um motivo, que fornece o arquivo e a linha quando o problema está em seu código. Claude Code não conseguiu carregar o módulo, por exemplo porque seu código de nível superior lançou.
Corrija o erro que o motivo nomeia.
`options do not fit plugin.json userConfig`
A linha começa com o nome do mod, depois hooks module did not load: options do not fit plugin.json userConfig: e um motivo. Uma opção não se encaixa em seu campo userConfig, como um número acima do max do campo, ou um campo obrigatório não tem valor.
Defina ou altere o valor. O final da linha nomeia sua entrada pluginConfigs em settings.json.
Nenhum mod carrega em um diretório que você abriu pela primeira vez
Você não respondeu ao prompt de confiança para o diretório.
Inicie uma sessão interativa nesse diretório com claude e aceite o prompt de confiança que ele abre.
Nenhum plugin instalado carrega
Você iniciou Claude Code com --safe-mode.
Inicie sem a flag.
Um hook é ignorado ou um mod é descarregado
O mod carregou e então Claude Code ignorou um de seus hooks ou o descarregou.
`hook skipped`
A linha nomeia o mod e o evento, depois diz hook skipped: e um motivo, como em first-mod: tool.call hook skipped: threw Error: boom. Um hook lançou, executou além de seu limite de tempo de 10 segundos, ou retornou um resultado de forma incorreta. A linha aparece uma vez para cada evento e tipo de falha até o mod recarregar.
Corrija o erro. O log de depuração tem uma linha para cada ocorrência.
`it crashed the hooks worker`
A linha começa com o nome do mod, como em first-mod was unloaded: it crashed the hooks worker. Os mods instalados compartilham um thread de worker. O worker parou de responder ou travou, e Claude Code rastreou isso para este mod e o descarregou. Um hook que bloqueia a thread, como um loop que nunca aguarda, é uma causa.
Corrija o hook.
`mods that run in the hooks worker are off for this session`
A linha lê hooks: mods that run in the hooks worker are off for this session: it crashed 3 times. O worker parou três vezes e Claude Code não conseguiu rastrear as paradas para um mod, então descarregou cada mod que não é integrado, incluindo mods que sua organização instala. Esta linha chega à transcrição em cada sessão interativa.
Execute /reload-plugins para carregá-los novamente.
Uma chamada de ferramenta é recusada
O mod carregou e seus hooks executam, e uma chamada de ferramenta que ele tocou é recusada.
`a hook changed this call's input after the model wrote it`
Em modo automático, uma chamada de ferramenta recusada fornece este motivo. Um hook alterou a entrada da chamada de ferramenta após o classificador do lado do servidor revisá-la, então essa revisão não cobre o que seria executado. O hook pode ser um tool.call ou turn.step hook do mod, ou um hook de configurações PreToolUse. A mensagem não diz qual.
A mensagem diz a Claude para emitir a chamada novamente conforme registrado. Se isso também for recusado, o hook altera a entrada toda vez, então desative o mod ou hook, ou saia do modo automático e aprove a chamada você mesmo.
Uma mensagem sobre as regras de negação em suas configurações
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 ambas vêm do guarda integrado.
Procure-as em Mensagens do guarda integrado.
Um desenho não aparece ou responde
O mod carregou e seu painel, banda ou controles não se comportam como você espera.
Um painel ou banda está vazio ou mostra o conteúdo usual de Claude Code
A árvore que seu hook retornou não validou. Com --plugin-dir, a transcrição diz ui.render (Pane) refused: com o motivo, como em first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own. O log de depuração tem a hook returned a tree that does not validate com o mesmo motivo.
Leia o motivo nessa linha. As causas comuns são uma prop que o elemento não aceita e um elemento que o aplicativo não tem.
`$.ui.open` executa e nenhum painel aparece
A chamada não veio de algo que o usuário fez, e o terminal é mais estreito que 144 colunas.
Abra o painel a partir de um comando ou botão, ou verifique o resultado isPlaced da chamada. Veja Abrir um painel no momento certo.
Hotkeys não fazem nada
Seu painel não tem foco de teclado.
Pressione Ctrl+X depois Tab, ou clique no painel. Abra-o com focus: true a partir de um comando.
Um desenho funciona no terminal e não no aplicativo Desktop
O site ou elemento não está disponível lá.
Verifique as render sites e tabelas de elementos.
Uma edição ou um valor é perdido
O mod executa e uma mudança que você fez ou um valor que ele manteve não está lá.
Suas edições não entram em vigor
Você está editando um plugin que instalou. Claude Code executa a cópia em cache para a versão instalada.
Desenvolva com --plugin-dir apontado para sua cópia de trabalho, como em claude --plugin-dir ./first-mod, que recarrega quando você salva.
Um valor é redefinido quando o módulo recarrega
Variáveis de nível de módulo são reinicializadas em cada recarregamento.
Mantenha o valor em $.state ou $.store.
Um valor é redefinido após `/clear`, `/resume` ou `/branch`
Um valor é redefinido, ou um valor salvo é substituído por seu padrão. Cada um desses comandos redefine $.state para seus padrões, e session.start não dispara novamente.
Carregue o valor salvo novamente em um hook classic.SessionStart.
Leia o log de depuração
O log de depuração tem uma linha para cada módulo que Claude Code carrega ou recusa, cada hook que falha e cada resultado que recusa, então é onde procurar quando a transcrição não mostra nada. Para escrever um, em seu shell inicie Claude Code com --debug, ou com --debug-file <path> para escolher onde ele vai:
claude --debug-file ./mod-debug.log --plugin-dir ./first-mod
Em outro terminal, siga o arquivo e filtre pelo nome do seu mod:
tail -f ./mod-debug.log | grep first-mod
Um mod que carregou tem uma linha que o nomeia e lista os eventos que ele conecta. Um mod carregado com --plugin-dir aparece sob seu nome seguido por @inline:
hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render
Um desenho que não validou conta como um resultado recusado e também recebe uma linha. Para escrever suas próprias linhas no log, chame $.ui.log com um segundo argumento, como em $.ui.log('message', { to: 'debug' }). Sem o segundo argumento, $.ui.log adiciona uma linha fraca à transcrição.
Enquanto você edita um mod carregado com --plugin-dir, a transcrição mostra uma linha para cada recarregamento que nomeia o mod e lista seus hooks. Se um salvamento quebrar o módulo, a linha diz reload failed, the previous version stays loaded: com o motivo, e a última versão de trabalho continua executando.
Próximas etapas
- Teste um mod: detecte problemas antes que eles cheguem a uma sessão
- Solucionar problemas de plugins: problemas com instalação e carregamento de um plugin que não são específicos de mods