Qué archivo de settings.json manda en Claude Code

Cambias un ajuste, no pasa nada y no sabes por qué. Lo normal es que la misma clave esté puesta en un segundo archivo que va por encima del tuyo. Esta página lista los archivos y el orden.

Las cuatro fuentes

• Usuario~/.claude/settings.json. Tú, en todos los proyectos de esta máquina. Sirve para preferencias personales y tus propias reglas de permisos.
• Proyecto compartido.claude/settings.json dentro del proyecto. Todos los que trabajan en esa carpeta. En un repositorio git lo subes para que lo tenga tu equipo.
• Proyecto local.claude/settings.local.json. Tú, solo en este proyecto. Para cambios personales y para probar algo antes de compartirlo.
• GestionadoLo despliega una organización. Tú no lo creas ni lo editas.

En Windows, ~/.claude es %USERPROFILE%\.claude. Instalar Claude Code no crea ninguno de estos archivos. El menú /config escribe el archivo de usuario la primera vez que cambias una opción que se guarda ahí, y una aprobación permanente como «Yes, and don't ask again» en un aviso de permiso escribe el archivo local.

Hay un quinto archivo, ~/.claude.json. Lo escribe Claude Code para sí mismo y guarda cosas como los datos de la cuenta, la configuración de servidores MCP y las decisiones de confianza. No hace falta que lo edites.

Cuál gana

Cuando la misma clave está puesta en más de un sitio, Claude Code usa el valor del nivel más alto. De más alto a más bajo:

1. Ajustes gestionados de tu organización.
2. La línea de comandos: JSON que pasas con --settings para una sola sesión.
3. Proyecto local: .claude/settings.local.json.
4. Proyecto compartido: .claude/settings.json.
5. Usuario: ~/.claude/settings.json.

Un ejemplo de la documentación: el archivo compartido de tu equipo activa un consejo y tu archivo de usuario lo desactiva. Gana el valor del proyecto, así que ves el consejo en ese proyecto y en ningún otro. Para recuperar tu valor en ese proyecto, ponlo en .claude/settings.local.json, que va por encima del compartido y no cambia nada a tus compañeros.

Las listas se suman

En las claves de lista, como permissions.allow, Claude Code combina las entradas de todos los archivos en lugar de elegir uno. Cada archivo puede añadir reglas sin quitar las de otro. Unas pocas claves de modelos siguen sus propias reglas, así que mira la entrada de la clave que te interese.

Las variables de entorno no son un nivel

Si manda una variable de la terminal o una clave de ajustes se decide clave por clave, no por nivel. Por ejemplo, ANTHROPIC_MODEL en tu terminal pasa por encima de la clave model de cualquier archivo. La página de cada clave dice cuál se aplica.

Un archivo para empezar

Los archivos de ajustes son JSON estricto. Un comentario o una coma al final es un error. Este ejemplo deja que Claude Code ejecute tus comandos de lint y de tests sin preguntar y le impide leer archivos .env. Ponlo en ~/.claude/settings.json:

{
  "$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 es opcional. Da autocompletado y avisos a los editores que entienden JSON schema. El esquema puede ir por detrás de las últimas versiones, así que un aviso en una clave recién añadida no significa que tu archivo esté mal. Cambia los comandos por los que use de verdad tu proyecto.

Comprueba qué se cargó

• Ejecuta /status. La línea Setting sources lista los archivos de ajustes que Claude Code cargó en esta sesión. No dice qué archivo aportó cada clave.
• Ejecuta claude doctor para ver las entradas que Claude Code rechazó.
• Si un archivo tiene JSON inválido, Claude Code muestra un «Settings Error» al empezar una sesión interactiva. Si fallan solo entradas sueltas, se salta esas y conserva el resto.
• La mayoría de los cambios se aplican a una sesión en marcha sin reiniciar, incluidos permisos y hooks. Unas pocas claves se leen solo una vez al arrancar.

Por qué un ajuste no hace nada

• Un nivel más alto pone la misma clave. Mira el orden de arriba.
• Una regla allow del proyecto espera a que cada compañero confíe en la carpeta. Las reglas deny y ask se aplican al instante.
• Algunas claves nunca surten efecto desde el archivo compartido del proyecto. La documentación las marca en su referencia de ajustes. Los modos de permisos auto y bypassPermissions no surten efecto desde los ajustes de proyecto ni locales.
• El archivo no está donde crees. En una sesión en la nube solo se lee el archivo compartido del proyecto, no el de usuario ni el local.
• /config funciona en la terminal. El panel de chat de VS Code y la app de escritorio no lo abren, así que edita un archivo o usa los ajustes propios de esas apps.

Prueba una sesión sin guardar

claude --settings '{"permissions": {"deny": ["Read(./.env)"]}}'

Eso se aplica a una sola sesión y no escribe nada en disco.

Límites

• Las claves, los valores por defecto y las rutas de los archivos cambian entre versiones. La referencia de ajustes es la que manda.
• El archivo compartido se sube a git, así que lo recibe todo el que clone el repositorio. Deja los cambios personales en el archivo local.
• Es información general sobre una herramienta, no una auditoría de seguridad de tu configuración.

Esta página sigue la documentación de ajustes de Anthropic tal como la leemos en octubre de 2026. No tenemos relación con Anthropic. La escribimos a partir de la documentación y no hemos probado todos los casos.

Para las reglas de dentro de permissions, mira una lista de partida de reglas de permisos. Si quieres una segunda mirada a tu CLAUDE.md y a tus ajustes, el Tune-Up Kit es una lista de comprobación para eso (la ficha está en inglés).

Mira también: Claude Code en un código grande.