Las claves JSON que deciden con qué modelo arranca Claude Code, qué puede hacer sin preguntar, qué archivos no puede leer, cómo se ve y qué impone tu organización. Aquí aprendes dónde poner cada una y cuál gana cuando chocan.
SETTINGS · 1
Settings, en simple
En simplePiensa en capas de reglas, como en una casa: las reglas del edificio (organización) mandan sobre las de la familia (equipo), que mandan sobre tus preferencias (usuario). Y para una sola noche, puedes hacer una excepción (línea de comandos). Claude Code lee varias capas y, si dos dicen cosas distintas, gana la más alta.
settings.jsonComportamiento de Claude Code: modelo, permisos, hooks, sandbox, interfaz. Lo aplica el programa.
CLAUDE.mdInstrucciones para el modelo: convenciones, comandos de build. Es contexto, no configuración.
Variables de entornoAlgunas tienen pareja en settings (ANTHROPIC_MODEL ↔ model); quién gana se decide por cada par.
Los archivos son JSON estricto: un comentario // o una coma final es error de sintaxis. Agrega "$schema": "https://json.schemastore.org/claude-code-settings.json" y tu editor te dará autocompletado y validación.
SETTINGS · 2
Los archivos y a quién afectan
Tienes tres proyectos en tu máquina, un compañero con su copia de acme-app y una sesión en la nube sobre acme-app. Toca un archivo para ver hasta dónde llega:
Alcance de cada archivo
Scope
Archivo
Afecta a
Úsalo para
Usuario
~/.claude/settings.json
Tú, en todos tus proyectos
Tema, modelo por defecto, tus reglas personales
Proyecto compartido
.claude/settings.json
Todos en el repo (commitéalo)
Permisos, hooks, plugins y env del equipo
Proyecto local
.claude/settings.local.json
Tú, solo en este proyecto
Excepciones personales; pruebas antes de compartir
Managed
managed-settings.json, MDM, consola de claude.ai
Toda la organización
Políticas de seguridad y cumplimiento
Instalar Claude Code no crea ningún archivo. Se crean cuando cambias algo en /config (usuario) o eliges "Yes, and don't ask again" en un prompt (local).
Claude Code agrega settings.local.json a tus exclusiones globales de git la primera vez que lo escribe. Si lo creas a mano, agrégalo tú a .gitignore.
Hay un quinto archivo, ~/.claude.json, que Claude Code mantiene solo: cuenta, servidores MCP de scope local/usuario, estado por proyecto. No necesitas editarlo.
En Windows, ~/.claude es %USERPROFILE%\.claude. Con CLAUDE_CONFIG_DIR lo mueves a otra ruta.
SETTINGS · 3
Precedencia: quién gana
Cuando la misma clave está en varios lugares, gana el nivel más alto que la define. Configura spinnerTipsEnabled en cada nivel y mira el resultado:
Simulador de precedencia
Las listas se combinan, no se reemplazan
Para claves que son listas (como permissions.allow), Claude Code junta las entradas de todos los archivos. Cada archivo puede agregar sin borrar las del otro:
Fusión de permissions.allow
Excepciones a la fusión: fallbackModel y modelPicker se toman enteros del nivel más alto; un availableModels managed se aplica tal cual.
Algunas claves de seguridad respetan el valor más estricto venga de donde venga, aunque managed diga otra cosa: por ejemplo disableClaudeAiConnectors: true, permissions.blockReadsOutsideWorkingDirectories: true o un maxEffortLevel más bajo.
permissions.defaultMode con valor auto o bypassPermissionsno aplica desde archivos de proyecto o locales: ponlo en settings de usuario o pásalo con --permission-mode.
SETTINGS · 4
Cuatro formas de cambiar un setting
¿Cuándo hace efecto?
Claude Code vigila los archivos y recarga la mayoría de los cambios en la sesión en curso, incluidos permissions, hooks y apiKeyHelper. Cada cambio dispara el hook ConfigChange. Excepciones que se leen solo al arrancar: model (usa /model), effortLevel y modelSettings (usa /effort).
SETTINGS · 5
Explorador de claves
Las claves más usadas, agrupadas. La columna Scope dice desde qué archivos funciona: "Cualquiera" incluye el archivo commiteado del proyecto; "Usuario/managed" significa que en el repo se ignora.
Marca lo que quieres y obtén un archivo válido, con $schema incluido.
Generador
SETTINGS · 7
Tres archivos de ejemplo, comentados
SETTINGS · 8
Mi setting no aplica: diagnóstico
Árbol de diagnóstico
Herramientas
Herramienta
Te dice
/status
La línea Setting sources: qué archivos cargó (no qué clave vino de cuál) y si hay managed settings.
claude doctor
Desde la shell: validación de archivos y entradas rechazadas, sin abrir sesión.
Settings Error
JSON inválido o valor rechazado: al iniciar te ofrece arreglarlo con Claude, salir o seguir sin ese archivo.
Settings Warning
Solo algunas entradas fallan (una regla mal escrita, un evento de hook desconocido): se saltan y el resto aplica.
claude --safe-mode
Arranca sin ninguna personalización para descartar que sea tu configuración.
Si rompes ~/.claude.jsonClaude Code guarda una copia del archivo dañado en ~/.claude/backups/ y conserva los cinco respaldos más recientes .claude.json.backup.<timestamp> para restaurar.
SETTINGS · 9
Settings en sesiones en la nube
Una sesión en la nube corre sobre un clon fresco de tu repo en otra máquina, así que no ve todo:
Sí llega.claude/settings.json commiteado (sesión con un repo) y los managed settings servidos desde la consola de claude.ai.
No llega~/.claude/settings.json, settings.local.json, ni un managed-settings.json o MDM de tu equipo.
Cómo configurarVariables de entorno del entorno cloud, o commitear la clave en el settings del repo. /config en claude.ai/code abre tu página de ajustes.