Referencia a fondo · Settings

Settings

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

ScopeArchivoAfecta aÚsalo para
Usuario~/.claude/settings.jsonTú, en todos tus proyectosTema, modelo por defecto, tus reglas personales
Proyecto compartido.claude/settings.jsonTodos en el repo (commitéalo)Permisos, hooks, plugins y env del equipo
Proyecto local.claude/settings.local.jsonTú, solo en este proyectoExcepciones personales; pruebas antes de compartir
Managedmanaged-settings.json, MDM, consola de claude.aiToda la organizaciónPolí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 bypassPermissions no 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.

Claves de settings

Referencia completa (cientos de claves) en code.claude.com/docs/en/settings-reference.

SETTINGS · 6

Constructor de settings.json

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

HerramientaTe dice
/statusLa línea Setting sources: qué archivos cargó (no qué clave vino de cuál) y si hay managed settings.
claude doctorDesde la shell: validación de archivos y entradas rechazadas, sin abrir sesión.
Settings ErrorJSON inválido o valor rechazado: al iniciar te ofrece arreglarlo con Claude, salir o seguir sin ese archivo.
Settings WarningSolo algunas entradas fallan (una regla mal escrita, un evento de hook desconocido): se saltan y el resto aplica.
claude --safe-modeArranca 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.
QUIZ

Quiz · Settings