settings.json en Claude Code: configuración y scopes
settings.json es el archivo de configuración nativo de Claude Code: define idioma, modelo por defecto, hooks, status line, permisos y variables de entorno, y se carga al iniciar la sesión. Lo que confunde a casi todos es que no hay un solo settings.json: hay cinco ubicaciones con una jerarquía de precedencia. Conocerla es la diferencia entre configurar algo y que se aplique, o pelearte sin entender por qué no funciona.
La trampa más común: configuras algo y no se aplica. Casi siempre es porque otro
settings.jsonmás alto en la jerarquía lo está pisando. Una vez que conoces los cinco scopes, dejas de pelearte y empiezas a usarlos como palanca.
Qué es settings.json
Es JSON estándar, se carga automáticamente al iniciar y define cómo se comporta Claude Code: idioma de respuesta, modelo default, hooks activos, status line, output style, permisos, variables de entorno y más opciones de la referencia oficial.
Los cinco scopes (de menor a mayor precedencia)
| # | Scope | Ubicación | Para qué |
|---|---|---|---|
| 1 | User | ~/.claude/settings.json |
Tu config personal global (cualquier proyecto). |
| 2 | Project (versionado) | .claude/settings.json en el repo |
Defaults del equipo (se commitea). |
| 3 | Project (local) | .claude/settings.local.json en el repo |
Tu override personal de ese proyecto (NO se commitea). |
| 4 | Command-line | flags al iniciar (claude --model sonnet) |
Config temporal de una sesión. |
| 5 | Managed | impuesta por el admin (Team/Enterprise) | Pisa todo lo demás. |
Cada nivel pisa a los anteriores: command-line pisa a los archivos, y managed pisa incluso a command-line.
Cómo se resuelven los conflictos
Hay dos reglas, según el tipo de valor:
- Valores escalares (un solo valor, como
model): gana el de mayor precedencia. Si user dicesonnet, project diceopusy local dicehaiku, arranca con Haiku. Si además pasas--model sonnet, gana el command-line. - Valores tipo lista (permisos, hooks): se mergean por unión y deduplicación. Pero hay una excepción crítica de seguridad: en permisos, Deny gana sobre Allow sin importar el nivel. Una negación es más fuerte que cualquier permiso.
Dónde poner cada cosa
- Status line, modelo default, hooks personales, idioma: en user (
~/.claude/settings.json). - Defaults que toca el equipo (modelo recomendado, hooks comunes, permisos base): en project versionado (
.claude/settings.json), que se commitea. - Tus overrides personales de ese proyecto que no quieres imponer al equipo: en project local (
.claude/settings.local.json), que no se commitea.
Nota: existe también
~/.claude.json(con punto, sin carpeta), que es estado interno de Claude Code (MCPs activos por proyecto, recordatorios). No lo edites a mano: no es parte del sistema de scopes que tú configuras.
Preguntas frecuentes
¿Qué es settings.json en Claude Code?
Es el archivo de configuración nativo de Claude Code, en formato JSON, que se carga al iniciar la sesión. Define idioma, modelo por defecto, hooks, status line, permisos y variables de entorno, entre otras opciones.
¿Dónde está el archivo settings.json de Claude Code?
Puede vivir en cinco lugares con distinta precedencia: user (~/.claude/settings.json), project versionado (.claude/settings.json), project local (.claude/settings.local.json), argumentos de línea de comandos y managed (organizacional). El de mayor precedencia gana en los conflictos.
¿Por qué mi configuración de Claude Code no se aplica?
Casi siempre porque otro settings.json más alto en la jerarquía la está pisando. Por ejemplo, un --model en la línea de comandos pisa lo que diga cualquier archivo. Revisa la precedencia: command-line y managed están por encima de los archivos.
¿Qué gana en un conflicto de permisos, Allow o Deny?
Deny. En los permisos, una negación gana sobre un permiso sin importar el nivel donde esté declarada. Es una regla de seguridad: las negaciones son más fuertes que las permisiones.
Recursos relacionados
- Permisos en Claude Code y hooks: dos cosas que se configuran en settings.json.
- Slash commands personalizados.
- Guía completa para dominar Claude Code.
Tu siguiente paso
Los comandos de configuración y decenas más están en la Cheat Sheet de Claude Code: una hoja imprimible, en español.
Descargar la Cheat Sheet gratis
Es el resumen de Ship with Claude Code, la guía de Takren (14 módulos, 190 capítulos, actualizaciones gratuitas).