Claude Code falla tras un cambio de configuración, cómo encontrar la causa
Con el nuevo safe mode arrancas Claude Code sin todas tus personalizaciones y las vuelves a activar una a una hasta dar con el culpable. Diez pasos contra el error que te saca de quicio.
Todo funcionaba. Entonces añadiste un hook, instalaste una skill, metiste un servidor MCP nuevo, y de repente Claude Code se atasca. Las herramientas no cargan, el arranque tarda una eternidad, un prompt se responde raro o la sesión se corta. Y ya no sabes cuál de tus diez cambios de la última semana fue. Es el tipo de fallo más molesto, porque no tienes un síntoma claro, solo la sensación de que algo en tu setup está torcido.
Desde la versión 2.1.169 hay una herramienta integrada justo para esto. El safe mode. Arranca Claude Code con todas las personalizaciones desactivadas, y desde ahí vas volviendo capa por capa. El mismo método que el modo seguro de Windows, pero para tu CLI. Repaso los diez pasos con los que sabes qué está roto.
1. Primero comprobar la versión
El safe mode existe a partir de Claude Code 2.1.169. Si tu versión es más antigua, falta el flag y tienes que tirar del método bruto de siempre, apartar los ficheros de configuración a mano. Comprueba primero:
claude --version
¿Estás por debajo? Actualiza antes. Cómo hacerlo limpio está en el playbook Estrategia de actualización de Claude Code. Después vuelves aquí.
2. Arrancar en safe mode
Este es el comando alrededor del cual gira todo:
claude --safe-mode
O como variable de entorno, si lo quieres para toda una sesión de shell:
CLAUDE_CODE_SAFE_MODE=1 claude
El safe mode apaga todas tus personalizaciones. En concreto: tu CLAUDE.md, todos los plugins, todas las skills, todos los hooks y todos los servidores MCP. Obtienes un Claude Code desnudo, tal como correría recién instalado. Nada de lo tuyo está activo.
3. Reproducir el fallo en safe mode
Ahora haz exactamente lo que fallaba antes. El mismo prompt, el mismo fichero, el mismo comando de bash. Hay dos desenlaces posibles, y los dos te dicen algo.
Si el fallo desaparece en safe mode, es una de tus personalizaciones. Bien, ese es el caso frecuente, y a partir del paso 4 acotas cuál. Si el fallo sigue también en safe mode, no es tu configuración sino el propio Claude Code, tu instalación o tu red. Entonces salta directo al paso 9.
4. Una capa detrás de otra, no todo de golpe
El reflejo ahora es volver a encender todo a la vez y mirar. No lo hagas. Acabas exactamente donde empezaste y vuelves a no saber nada. El orden que uso va de fuera hacia dentro, de lo que se rompe más fácil a lo que menos veces tiene la culpa:
servidores MCP, luego hooks, luego skills, luego plugins, luego CLAUDE.md. Después de cada capa vuelves a probar. En el momento en que el fallo reaparece, tienes a tu culpable.
5. Empezar por los servidores MCP
Los servidores MCP son la fuente de fallo más habitual, porque arrancan procesos externos, necesitan tokens y hablan por red. Arranca Claude Code normal, pero solo con los servidores MCP que sospechas. Si tienes muchos, comenta en tu configuración MCP todos menos uno y ve subiendo.
Si el fallo vuelve con un servidor concreto, ya lo tienes. Qué hacer entonces está detallado en el playbook Depurar MCP cuando no va nada. A menudo es un token caducado o un servidor que ni siquiera arranca.
6. Después los hooks
Los hooks se disparan en las llamadas a herramientas y pueden bloquear una sesión si un script de hook lanza un error o se queda colgado. Vuelve a activar tus hooks uno a uno. Un hook que aborta con código de salida 2 bloquea la acción, y eso es lo previsto, pero un hook con un bug en el script quizá lo bloquee todo.
Si el culpable es un hook, ve al playbook Depurar hooks cuando no se dispara nada. Cubre tanto el caso inverso, que el hook no se dispare, como este, que se dispare de más.
7. Skills, y el truco de las skills incluidas
Las skills solo se cargan cuando Claude las considera relevantes, así que normalmente casi no cuestan contexto. Aun así, una definición de skill rota puede dar problemas. Vuelve a activar tus propias skills del directorio .claude/skills/ una a una.
Desde 2.1.169 hay además un caso especial. Claude Code trae sus propias skills incluidas, workflows y slash-commands integrados. Si sospechas que una de ellas molesta, puedes ocultarlas con un ajuste sin tocar las tuyas:
{
"disableBundledSkills": true
}
O como variable de entorno CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1. Si con eso desaparece el fallo, era una skill incluida y no la tuya. Más sobre el comportamiento de los triggers en el playbook Depuración de triggers de skills.
8. Plugins y CLAUDE.md al final
Los plugins suelen arrastrar hooks, skills y servidores MCP en un mismo paquete, por eso van los últimos. Actívalos uno a uno. Un plugin de un ZIP o una URL ajena es buen sospechoso, sobre todo si lo instalaste hace poco.
Queda CLAUDE.md. Raramente da problemas duros, pero puede empujar a Claude en una dirección que no querías, o haberse alargado tanto que se come medio contexto. Desde hace poco el aviso de que CLAUDE.md es demasiado larga escala con la ventana de contexto del modelo, así que recibes un aviso cuando pasa el límite. Si ese era tu síntoma, acórtala o saca partes a ficheros referenciados.
9. Si el fallo sigue también en safe mode
Entonces no es tu configuración. Quedan tres sospechosos. Primero la propia instalación, una actualización que se quedó a medias o un binario roto. Aquí suele ayudar una actualización limpia o una reinstalación. Segundo la red, sobre todo si estás detrás de un proxy o una VPN o la API está saturada. Tercero un bug real en la versión que llevas.
Con errores de sobrecarga (overloaded) merece la pena una cadena de modelos de fallback, para que Claude Code pase automáticamente al siguiente cuando uno está saturado. Cómo se hace está en el playbook compañero Modelos de fallback contra la sobrecarga.
10. Dejarlo limpio y anotarlo
Ya tienes al culpable. Ahora quitas el safe mode y arrancas normal, con ese cambio arreglado o fuera. Importante, y esto se me olvida a mí constantemente: apunta brevemente qué era. Un token caducado, una errata en la ruta del hook, una skill que chocaba con otra. La próxima vez te ahorras la ronda entera, porque ya tienes la sospecha de entrada.
El safe mode no sustituye a los playbooks de depuración específicos. Es el escalón previo. Primero acotas con safe mode qué capa tiene el problema, después vas a fondo con el playbook que toca. Si te apetece el cuadro completo, ayuda el playbook Evitar el exceso de herramientas, porque la mayoría de estos fallos vienen sencillamente de haber instalado demasiado de golpe.
Qué sigue
Si tu fallo era un modelo sobrecargado o no disponible, sigue con Modelos de fallback contra la sobrecarga. Si era un servidor MCP, entonces Depurar MCP cuando no va nada. Y si te interesa en general montar un setup que se rompa menos, mira la lección de nivel 4 Hooks y skills.
Source
- Changelog de Claude Code, versión 2.1.169 (--safe-mode, CLAUDE_CODE_SAFE_MODE, disableBundledSkills): https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
- Documentación de Claude Code: https://code.claude.com/docs/en/changelog