Descubre por qué un mod no hace nada
Cuando un mod no hace nada, dos verificaciones encuentran la razón: qué lee Claude Code de los archivos del mod y la línea que escribe cuando omite algo. Para la primera, en tu shell ejecutaclaude plugin validate con el directorio del mod, como en claude plugin validate ./first-mod. Detecta un evento mal escrito, un manifiesto incorrecto y un módulo que Claude Code no puede leer, sin iniciar una sesión.
Cuando un módulo no se carga, se omite un hook o otro mod rechaza el tuyo, Claude Code escribe una línea que nombra tu mod. Dónde lees esa línea depende de la sesión:
- Una sesión que recarga en caliente un directorio de plugins: una línea tenue en la transcripción. Esa es una sesión interactiva que iniciaste con
--plugin-dir, o una donde habilitaste la recarga en caliente para mods que Claude escribió. - Cualquier otra sesión interactiva, como una que ejecuta un mod que instalaste desde un marketplace: el registro de depuración solamente. Para obtener uno, inicia la sesión con
claude --debug. - Una ejecución
claude -pcon--plugin-dir: stderr, en el formato de salida de texto predeterminado. Un rechazo por otro mod va al registro de depuración solamente.
Verifica si los mods pueden cargarse
Para verificar si tu configuración permite que los mods se carguen en absoluto, sin instalar uno, ejecutaclaude plugin test en tu shell, desde un directorio que no contenga un mod. No necesitas una sesión. El mensaje que imprime te dice el estado:
Una organización también puede establecer
allowManagedModsOnly para permitir solo sus propios mods, que este comando no reporta. En ese caso, un mod que instales no se carga, y un mensaje dice por qué.
El mod no se carga
Nada de lo que agrega el mod aparece: ningún comando, ningún dibujo y ningún cambio de comportamiento.Tu versión es anterior a 2.1.287
claude --version imprime una versión anterior a 2.1.287. Tu versión es anterior a que los mods estén activados de forma predeterminada.
Actualiza Claude Code.
La línea mods active no nombra el mod
Nada de lo que agrega el mod aparece, y la línea mods active en /plugin no lo nombra. El módulo hooks no se cargó. Cuando Claude Code lo rechazó, el registro de depuración tiene una línea que comienza con hooks module, el nombre del mod y not loaded:, como en hooks module first-mod@inline not loaded: disableAllHooks in managed settings para un mod cargado con --plugin-dir.
Lee la razón después de los dos puntos. La sección refusal messages enumera cada una. Si el registro no tiene tal línea, trabaja a través de las otras entradas en este grupo.
Una ejecución claude -p imprime hooks module not loaded
La línea comienza con el nombre del mod y va a stderr. El módulo hooks fue rechazado. Una ejecución no interactiva no tiene transcripción, por lo que el mensaje va a stderr.
Lee la razón después de los dos puntos. La sección refusal messages enumera cada una.
Mensajes de rechazo
Cada uno de estos sigue ahooks module, el nombre del mod y not loaded: en el registro de depuración.
Mensajes del guardia integrado
En una máquina con configuración administrada, o para un usuario que inició sesión con un plan de Team o Enterprise, el guardia integrado puede rechazar un mod o una de sus respuestas. Cada mensaje nombra la opción que el administrador de tu organización establece para cambiar la regla.validate pasa y no enumera ninguna línea hooks
hooks/hooks.json no tiene una clave modules, o la clave está mal escrita.
Agrega "modules": ["./register.js"].
hooks module did not load
La línea comienza con el nombre del mod, luego hooks module did not load: y una razón, que proporciona el archivo y la línea cuando el problema está en tu código. Claude Code no pudo cargar el módulo, por ejemplo porque su código de nivel superior lanzó una excepción.
Corrige el error que la razón nombra.
options do not fit plugin.json userConfig
La línea comienza con el nombre del mod, luego hooks module did not load: options do not fit plugin.json userConfig: y una razón. Una opción no se ajusta a su campo userConfig, como un número por encima del max del campo, o un campo requerido no tiene valor.
Establece o cambia el valor. El final de la línea nombra su entrada pluginConfigs en settings.json.
Ningún mod se carga en un directorio que abriste por primera vez
No has respondido al aviso de confianza para el directorio. Inicia una sesión interactiva en ese directorio conclaude y acepta el aviso de confianza que abre.
Ningún plugin instalado se carga en absoluto
Iniciaste Claude Code con--safe-mode.
Inicia sin la bandera.
Se omite un hook o se descarga un mod
El mod se cargó y luego Claude Code omitió uno de sus hooks o lo descargó.hook skipped
La línea nombra el mod y el evento, luego dice hook skipped: y una razón, como en first-mod: tool.call hook skipped: threw Error: boom. Un hook lanzó una excepción, se ejecutó más allá de su límite de tiempo de 10 segundos, o devolvió un resultado de forma incorrecta. La línea aparece una vez para cada evento y tipo de fallo hasta que el mod se recarga.
Corrige el error. El registro de depuración tiene una línea para cada ocurrencia.
it crashed the hooks worker
La línea comienza con el nombre del mod, como en first-mod was unloaded: it crashed the hooks worker. Los mods instalados comparten un hilo de trabajo. El trabajador dejó de responder o se bloqueó, y Claude Code rastreó eso a este mod y lo descargó. Un hook que bloquea el hilo, como un bucle que nunca espera, es una causa.
Corrige el hook.
mods that run in the hooks worker are off for this session
La línea dice hooks: mods that run in the hooks worker are off for this session: it crashed 3 times. El trabajador se detuvo tres veces y Claude Code no pudo rastrear las paradas a un mod, por lo que descargó cada mod que no es integrado, incluidos los mods que tu organización instala. Esta línea llega a la transcripción en cada sesión interactiva.
Ejecuta /reload-plugins para cargarlos de nuevo.
Se deniega una llamada de herramienta
El mod se cargó y sus hooks se ejecutan, y se rechaza una llamada de herramienta que tocó.a hook changed this call's input after the model wrote it
En modo automático, una llamada de herramienta denegada da esta razón. Un hook cambió la entrada de la llamada de herramienta después de que el clasificador del lado del servidor la revisó, por lo que esa revisión no cubre lo que se ejecutaría. El hook puede ser un hook tool.call o turn.step de un mod, o un hook de configuración PreToolUse. El mensaje no dice cuál.
El mensaje le dice a Claude que emita la llamada una vez más como se registró. Si también se deniega, el hook cambia la entrada cada vez, así que desactiva el mod o el hook, o sal del modo automático y aprueba la llamada tú mismo.
Un mensaje sobre las reglas de denegación en tu configuración
tried to lift a deny rule in your settings y the deny rules in your settings could not be checked for this call, so it is refused ambos provienen del guardia integrado.
Búscalos en Messages from the built-in guard.
Un dibujo no aparece o no responde
El mod se cargó y su panel, banda o controles no se comportan como esperas.Un panel o banda está vacío o muestra el contenido habitual de Claude Code
El árbol que devolvió tu hook no se validó. Con--plugin-dir, la transcripción dice ui.render (Pane) refused: con la razón, como en first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own. El registro de depuración tiene a hook returned a tree that does not validate con la misma razón.
Lee la razón en esa línea. Las causas comunes son una propiedad que el elemento no toma y un elemento que la aplicación no tiene.
$.ui.open se ejecuta y no aparece ningún panel
La llamada no provino de algo que el usuario hizo, y la terminal es más estrecha que 144 columnas.
Abre el panel desde un comando o un botón, o verifica el resultado isPlaced de la llamada. Consulta Open a pane at the right time.
Las teclas de acceso rápido no hacen nada
Tu panel no tiene el enfoque del teclado. Presiona Ctrl+X luego Tab, o haz clic en el panel. Ábrelo confocus: true desde un comando.
Un dibujo funciona en la terminal y no en la aplicación de escritorio
El sitio o elemento no está disponible allí. Verifica las render sites y las tablas de elements.Se pierde una edición o un valor
El mod se ejecuta y un cambio que hiciste o un valor que mantuvo no está allí.Tus ediciones no tienen efecto
Estás editando un plugin que instalaste. Claude Code ejecuta la copia en caché para la versión instalada. Desarrolla con--plugin-dir apuntando a tu copia de trabajo, como en claude --plugin-dir ./first-mod, que se recarga cuando guardas.
Un valor se reinicia cuando el módulo se recarga
Las variables a nivel de módulo se reinicializan en cada recarga. Mantén el valor en$.state o $.store.
Un valor se reinicia después de /clear, /resume o /branch
Un valor se reinicia, o un valor guardado se reemplaza por su predeterminado. Cada uno de esos comandos reinicia $.state a sus valores predeterminados, y session.start no se dispara de nuevo.
Carga el valor guardado de nuevo en un hook classic.SessionStart.
Lee el registro de depuración
El registro de depuración tiene una línea para cada módulo que Claude Code carga o rechaza, cada hook que falla y cada resultado que rechaza, por lo que es donde buscar cuando la transcripción no muestra nada. Para escribir uno, en tu shell inicia Claude Code con--debug, o con --debug-file <path> para elegir dónde va:
--plugin-dir aparece bajo su nombre seguido de @inline:
$.ui.log con un segundo argumento, como en $.ui.log('message', { to: 'debug' }). Sin el segundo argumento, $.ui.log agrega una línea tenue a la transcripción.
Mientras editas un mod cargado con --plugin-dir, la transcripción muestra una línea para cada recarga que nombra el mod y enumera sus hooks. Si un guardado rompe el módulo, la línea dice reload failed, the previous version stays loaded: con la razón, y la última versión que funcionó sigue ejecutándose.
Próximos pasos
- Test a mod: detecta problemas antes de que lleguen a una sesión
- Troubleshoot plugins: problemas con la instalación y carga de un plugin que no son específicos de los mods