settings.json de Claude Code: la guía esencial 2026 de rutas y prioridad

settings.json de Claude Code, en resumen: tu archivo personal está en ~/.claude/settings.json, que en Windows es %USERPROFILE%\.claude\settings.json. Cada proyecto puede añadir .claude/settings.json (compartido con el equipo) y .claude/settings.local.json (solo para ti). Tu empresa puede enviar un archivo gestionado que manda sobre todos. Si no encuentras ninguno, es normal: instalar Claude Code no crea ningún archivo de configuración. Revisé cada ruta y cada regla con la documentación oficial de Anthropic el 27 de octubre de 2026 (hora de Pekín).

La respuesta corta

Estos son los cuatro sitios donde puede estar el settings.json de Claude Code:

• Archivo de usuario: ~/.claude/settings.json. Vale para ti en todos los proyectos de este equipo.
• Archivo compartido del proyecto: .claude/settings.json dentro del proyecto. Si lo subes a git, tu equipo lo recibe.
• Archivo local del proyecto: .claude/settings.local.json. Solo tú, solo este proyecto, fuera de git.
• Archivo gestionado: managed-settings.json en una carpeta del sistema, puesto por tu empresa. Nada de lo que escribas lo anula.
• No es un archivo de configuración: ~/.claude.json. Lo escribe Claude Code para sí mismo. No hace falta editarlo.

Dónde está el settings.json de Claude Code en cada sistema

El archivo de usuario vive en la carpeta .claude de tu directorio personal. En macOS y Linux es ~/.claude/settings.json. En Windows, ~/.claude significa %USERPROFILE%\.claude, así que la ruta es %USERPROFILE%\.claude\settings.json.

Puedes moverlo. Si defines la variable de entorno CLAUDE_CONFIG_DIR, Claude Code guarda ahí tu configuración, el historial de sesiones y los plugins.

Los archivos del proyecto no dependen del sistema operativo. Están en una carpeta .claude en la raíz del proyecto: .claude/settings.json y .claude/settings.local.json.

Dónde va el archivo gestionado

Solo el archivo gestionado cambia de sitio según el sistema. Según la documentación de configuración gestionada:

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux y WSL: /etc/claude-code/managed-settings.json
• Windows: C:\Program Files\ClaudeCode\managed-settings.json

Claude Code ya no lee la ruta antigua de Windows, C:\ProgramData\ClaudeCode\managed-settings.json. Junto al archivo gestionado puede haber una carpeta managed-settings.d/. Claude Code lee primero managed-settings.json y después cada archivo .json de esa carpeta en orden alfabético. La configuración gestionada también puede llegar por una política MDM o desde la consola de administración de claude.ai, sin ningún archivo en tu disco.

Por qué no encuentras el archivo

Una instalación nueva no tiene archivos de configuración. Claude Code los crea sobre la marcha:

• Escribe ~/.claude/settings.json la primera vez que cambias en /config una opción que se guarda en la configuración de usuario, como el tema.
• Escribe .claude/settings.local.json la primera vez que eliges «Yes, and don’t ask again» en un aviso de permisos.
• Algunas opciones de /config, como Show tips, van al archivo local.

También puedes crear el settings.json de Claude Code a mano. Tiene que ser JSON estricto: un comentario // o una coma final es un error de sintaxis, y Claude Code muestra un Settings Error en el siguiente arranque.

Este es el ejemplo de la documentación. Deja que Claude Code ejecute lint y tests sin preguntar y le impide leer archivos .env:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

La línea $schema te da autocompletado y validación en VS Code, Cursor y otros editores que leen esquemas JSON. La documentación avisa de que el esquema puede ir por detrás de las versiones nuevas, así que un aviso en una clave recién añadida no siempre significa que te equivocaste.

El archivo local en un repositorio git

La versión local del settings.json de Claude Code tiene algunos detalles. Si arrancas Claude Code en una subcarpeta de un repositorio git, lee y escribe el archivo local en la raíz del repositorio. En un worktree usa la raíz del checkout principal. Esto cambió en la v2.1.211. Antes, el archivo se quedaba en la carpeta donde arrancabas.

Hay excepciones. El archivo se queda junto a .claude/settings.json fuera de un repositorio git, cuando la raíz del repositorio es tu carpeta personal, en Windows, o cuando la raíz no pertenece a tu usuario.

La primera vez que Claude Code escribe el archivo local, añade **/.claude/settings.local.json a tus exclusiones globales de git. Si lo creaste a mano, añádelo tú a .gitignore.

El .claude/settings.json compartido funciona distinto. Claude Code lo lee de la carpeta donde arrancaste la sesión. Para usar el que está en la raíz del repositorio, arranca Claude Code ahí.

Qué archivo manda

Cuando la misma clave aparece en varios archivos, el settings.json de Claude Code que gana es el del nivel más alto. De arriba abajo:

• Configuración gestionada: tu empresa. Nada por debajo la anula.
• Línea de comandos: claude --settings con un archivo o JSON en línea, para una sola sesión.
• Proyecto local: .claude/settings.local.json.
• Proyecto compartido: .claude/settings.json.
• Usuario: ~/.claude/settings.json.

Las listas como permissions.allow se combinan en lugar de sustituirse, así que cada archivo puede añadir reglas sin borrar las de otro. Las variables de entorno no son un nivel de esta pila. Por ejemplo, ANTHROPIC_MODEL exportada en tu shell se aplica por encima de la clave model de cualquier archivo. Un bloque env dentro de un archivo sigue el orden normal.

Algunas claves ignoran ciertos archivos a propósito. permissions.defaultMode con auto o bypassPermissions no funciona desde la configuración del proyecto ni la local. Ponlo en la de usuario o en la gestionada, o usa --permission-mode para una sesión.

Cómo comprobar qué se cargó

Después de editar el settings.json de Claude Code, comprueba que se leyó. Ejecuta /status dentro de Claude Code. La línea Setting sources muestra cada archivo de configuración cargado en la sesión, y el origen gestionado si lo hay. No dice qué archivo puso cada clave. Para ver las entradas rechazadas, ejecuta claude doctor.

La mayoría de los cambios se aplican sin reiniciar, porque Claude Code vigila los archivos. Unas pocas claves solo se leen al arrancar, como model y effortLevel. Para cambiarlas a mitad de sesión usa /model y /effort.

Un detalle más: una sesión en la nube no lee tu archivo de usuario ni el local. Solo ve lo que está en el repositorio y la configuración gestionada desde el servidor.

Qué archivo editar

Para decidir qué settings.json de Claude Code tocar:

• Preferencias personales, como el tema, el modo de edición o tus propias reglas de permisos: el archivo de usuario.
• Permisos, hooks y plugins del equipo: el archivo compartido del proyecto, subido a git.
• Una excepción personal en un proyecto: el archivo local.
• Política de empresa: la configuración gestionada, que despliega un administrador.

Si quieres usar otro proveedor de modelos con el bloque env, lo expliqué en Claude Code con DeepSeek. Los hooks y plugins de estos archivos salen en Claude Code skills vs MCP, y los niveles de esfuerzo en Claude Code effort xhigh.

Lo que no pude confirmar

• La carpeta personal en WSL. La documentación da la ruta del archivo gestionado en WSL. No aclara qué carpeta personal usa el archivo de usuario dentro de WSL, así que no lo voy a suponer.
• Cobertura del esquema. Anthropic dice que el esquema JSON puede ir por detrás de las versiones nuevas. No comprobé qué claves le faltan hoy.

Las reglas del settings.json de Claude Code cambian entre versiones, como muestra el cambio de la v2.1.211. Si algo no coincide con lo que ves, ejecuta /status y revisa la página oficial.