Archivos de configuración y precedencia

​

Archivos de configuración y a quién afectan

​

Compara el alcance de cada archivo de configuración

• ~/.claude/settings.json: cada proyecto en tu máquina, y nada en la de tu compañero de equipo ni en la sesión en la nube
• acme-app/.claude/settings.json: tu acme-app/. Alcanza el clon de tu compañero de equipo y la sesión en la nube solo si haces commit del archivo en el control de versiones; hasta entonces, es un archivo en tu disco como cualquier otro y nadie más lo tiene
• acme-app/.claude/settings.local.json: solo tu acme-app/. Claude Code lo agrega a tus exclusiones globales de git la primera vez que escribe el archivo, por lo que se mantiene fuera de tus commits; si creas el archivo a mano, agrégalo a .gitignore tú mismo
• Configuración administrada, ya sea un archivo managed-settings.json, una política MDM o la configuración administrada por servidor desde la consola de claude.ai: cada proyecto en cada máquina en la que tu organización la implementa, o en la que inicias sesión con tu cuenta de organización. Solo la configuración administrada por servidor alcanza la sesión en la nube

​

Encuentra o crea tus archivos de configuración

• Administrado: tu organización lo implementa. Tú no lo creas ni lo editas.
• Proyecto compartido: un proyecto que ya usa Claude Code puede tener uno con commit. Si no, créalo en .claude/settings.json en la carpeta del proyecto.
• Usuario y Proyecto local: créalos tú mismo, o deja que Claude Code los cree. Escribe ~/.claude/settings.json la primera vez que cambias una opción en el menú /config que almacena en la configuración de usuario, como el tema, y .claude/settings.local.json la primera vez que das una aprobación permanente en una solicitud de permiso, como “Sí, y no preguntes de nuevo” para un comando Bash. Algunas opciones de /config, incluida Mostrar consejos, se guardan en .claude/settings.local.json en lugar del archivo de usuario.

​

Comparte la configuración con tu equipo

​

Mantén la configuración personal fuera de un repositorio

• Claude Code también lo escribe. Cuando Claude pide permiso para ejecutar un comando Bash y eliges “Sí, y no preguntes de nuevo”, Claude Code guarda esa aprobación de permiso aquí como una regla allow.
• No necesitas agregarlo a gitignore tú mismo, a menos que lo hayas creado a mano. La primera vez que Claude Code escribe el archivo en un repositorio de git que aún no lo ignora, agrega **/.claude/settings.local.json a tu archivo global de exclusiones de git, por lo que el archivo se mantiene fuera de tus commits en cada repositorio. Ese archivo es core.excludesFile cuando tu configuración global de git lo establece en una ruta absoluta o con prefijo ~; de lo contrario es $XDG_CONFIG_HOME/git/ignore, o ~/.config/git/ignore cuando XDG_CONFIG_HOME no está establecido. Si creaste el archivo a mano y Claude Code aún no ha escrito en él, agrégalo a .gitignore tú mismo.
• Sus reglas allow no esperan confianza mientras el archivo permanezca sin rastrear. Como el archivo es tuyo y no del repositorio, Claude Code aplica sus reglas allow sin el paso de confianza del espacio de trabajo que requiere para el archivo con commit. Si git rastrea el archivo, el paso de confianza también se le aplica; consulta Cuando tu archivo de configuración local necesita confianza.

​

Dónde mantiene Claude Code el archivo local en un repositorio de git

• Cuando el archivo se queda junto a .claude/settings.json: fuera de un repositorio de git, cuando la raíz del repositorio es tu directorio home, en Windows, o cuando la raíz del repositorio o su entrada .git o .claude no es propiedad de tu usuario.
• Las rutas en el archivo no se anclan en la raíz del repositorio: una regla de permisos que comienza con / o una ruta relativa del sandbox se ancla en el directorio de trabajo principal de la sesión.

​

Verifica qué impone tu organización

• Configuración administrada por servidor, que Claude Code obtiene de la consola de administración de claude.ai o de un gateway de aplicaciones de Claude autohospedado
• Políticas MDM o a nivel del sistema operativo, y archivos managed-settings.json en un directorio del sistema
• Un host de incrustación como Claude Desktop, a través de la opción managedSettings del SDK; consulta Controlar la política desde un host de incrustación

​

Cambie una configuración

​

Use el menú /config

• La mayoría de opciones: ~/.claude/settings.json
• Algunas opciones, como Mostrar consejos: .claude/settings.local.json
• Las opciones de configuración global: ~/.claude.json

​

Edite un archivo de configuración

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

​

Cambie una configuración para una sesión

• --settings: pase una clave como JSON, en línea o como una ruta a un archivo. Claude Code la aplica sobre sus archivos de usuario, proyecto y local y debajo de las configuraciones administradas. Puede establecer cualquier clave que su archivo de configuración de usuario pueda establecer; no puede establecer claves Managed o Global config.
• Una bandera para esa clave: algunas claves tienen su propia bandera, como --model para model y --effort para effortLevel y modelSettings.
• Una variable de entorno: exporte la variable emparejada de la clave antes de ejecutar claude, como ANTHROPIC_MODEL para model.

claude --settings '{"model": "claude-opus-5-5"}'

​

Cuándo surten efecto las ediciones

• model: use /model para cambiar a mitad de sesión. Cada modelo tiene su propio caché de indicador, por lo que la primera solicitud después de un cambio relee toda la conversación sin caché; vea Cambiar modelos
• effortLevel y modelSettings: use /effort para cambiar esfuerzo a mitad de sesión

​

Confirme qué se cargó

​

Corrija un archivo de configuración roto

• Error de configuración: un archivo de usuario, proyecto o local tiene JSON inválido o un valor que el esquema rechaza. Al inicio de una sesión interactiva Claude Code muestra un diálogo que le permite corregir el archivo con la ayuda de Claude, salir o continuar sin las configuraciones rotas.
• Advertencia de configuración: solo entradas individuales fallan, como una regla de permiso malformada o un nombre de evento de hook desconocido. Claude Code omite esos valores y mantiene el resto del archivo en vigor.
• Configuraciones administradas: Claude Code continúa aplicando el resto del archivo. Entradas inválidas en configuraciones administradas dice qué descarta y qué claves recurren a un valor más estricto hasta que las corrija. Para un documento de configuraciones administradas que no es JSON válido, vea No se pudo analizar el documento de configuraciones administradas.
• Error de configuración: ~/.claude.json no se puede analizar. Claude Code copia el archivo roto a ~/.claude/backups/.claude.json.corrupted.<timestamp> y pregunta si salir y corregirlo a mano o restablecer a la configuración predeterminada; una ejecución -p imprime el error y sale. Para recuperar su estado anterior, copie uno de los cinco archivos .claude.json.backup.<timestamp> más recientes en ~/.claude/backups/, que Claude Code guarda antes de escribir el archivo.

​

Precedencia de configuración

1. Configuración administrada: configuración que tu organización implementa mediante un archivo managed-settings.json, una política MDM o configuración administrada por el servidor desde la consola de claude.ai. Nada en tus propios archivos de configuración ni en --settings sobrescribe una clave administrada, y un flag como --model solo elige entre los modelos que tu organización permite. Un model administrado es un valor predeterminado inicial, no un bloqueo; los bloqueos son availableModels y deniedModels. Cuando tu organización entrega más de una fuente administrada, las reglas de precedencia dentro del nivel administrado indican qué lee Claude Code de cada una.
2. Línea de comandos: JSON que pasas con --settings <file-or-json> al iniciar claude, solo para esa sesión; consulta Cambiar un ajuste para una sesión. Una clave que estableces ahí sobrescribe la misma clave en tus archivos de configuración de proyecto y de usuario, y una clave que omites conserva su valor de esos archivos. Otros flags, como --model, establecen una sola cosa para la sesión y no forman parte de esta pila; la entrada de cada clave en la referencia de configuración indica qué flags la sobrescriben.
3. Configuración local del proyecto (.claude/settings.local.json): tu configuración personal para este proyecto.
4. Configuración compartida del proyecto (.claude/settings.json): configuración que tu equipo registra en el control de código fuente.
5. Configuración de usuario (~/.claude/settings.json): tu configuración personal para todos los proyectos.

​

Las listas se fusionan en lugar de sobrescribirse

• fallbackModel es una cadena ordenada donde la posición tiene significado, por lo que Claude Code toma el valor completo del archivo de mayor precedencia que la define.
• modelPicker contiene una lista ordenada de filas más una bandera de reemplazo, por lo que Claude Code nunca fusiona filas de dos fuentes. Toma el valor completo del nivel más alto, entre la configuración administrada, --settings y la configuración de usuario, que la define, e ignora la clave en la configuración de proyecto y local. Requiere Claude Code v2.1.242 o posterior.
• availableModels: cuando la configuración administrada que Claude Code aplica la define, Claude Code aplica esa lista tal cual e ignora las entradas que agregas en la configuración de usuario, de proyecto o local, a menos que una aplicación que incrusta Claude Code suministre su propia lista de modelos; consulta Excepciones a la precedencia de la configuración administrada. Entre fuentes administradas la lista tampoco se fusiona nunca; cómo Claude Code combina fuentes administradas indica la lista de qué fuente se aplica. Entre alcances no administrados, Claude Code fusiona las matrices como de costumbre.
• modelSettings: Claude Code la resuelve un modelo a la vez, junto con effortLevel. La entrada modelSettings indica el valor de qué archivo se aplica a un modelo.

​

Ejemplos de precedencia

​

La configuración del equipo sobrescribe la configuración personal

​

La configuración de la organización sobrescribe todo

​

La línea de comandos sobrescribe tus archivos para una sesión

​

Un flag o una variable de entorno establece lo mismo

​

Solucionar un ajuste que no se aplica

​

Un valor que estableces se ignora

• Un nivel más alto lo establece. Otro archivo de configuración, un flag --settings o una fuente administrada establece la clave por encima de la tuya; la pila indica cuál. Un flag o una variable de entorno también puede sobrescribir la clave por su cuenta, según cada clave; la entrada de la clave en la referencia de configuración indica cuál usa Claude Code, y la entrada env cubre un valor env administrado frente a una exportación del shell.
• Una clave de seguridad mantiene su valor estricto. Para algunas claves, Claude Code honra el valor restrictivo de cualquier archivo, así que un true de proyecto para disableClaudeAiConnectors permanece activado; consulta Excepciones a la precedencia de la configuración administrada.
• El archivo no puede establecer ese valor. Los valores auto y bypassPermissions de permissions.defaultMode no surten efecto desde la configuración de proyecto o local; establécelos en la configuración de usuario o administrada, o pasa --permission-mode para una sesión. Antes de v2.1.257, bypassPermissions surtía efecto desde cualquier archivo. Una variable de exportación de telemetría en un bloque env tampoco surte efecto desde la configuración de proyecto o local, salvo algunos valores de desactivación. Variables que Claude Code ignora en env enumera las variables y esos valores.
• El archivo está dañado. Un JSON no válido o un valor rechazado hace que Claude Code omita el archivo o la entrada; consulta Corregir un archivo de configuración dañado.

​

Un cambio que hiciste en Claude Code se pierde en nuevas sesiones

​

Un cambio administrado no te ha llegado

​

Una clave confirmada no llega a los compañeros de equipo

• Claude Code ignora la clave en un archivo de repositorio. Busca User, local, or managed, User or managed, User, Managed o Global config en la columna Scope del índice de configuración. Esas claves nunca se aplican desde el archivo compartido, salvo algunas que un archivo de repositorio aún puede desactivar. Cada una de esas entradas lo indica en su línea Scope. Las claves Global config se aplican solo desde ~/.claude.json. Dentro de la clave env, las variables de exportación de telemetría tampoco se aplican nunca desde el archivo compartido, salvo algunos valores de desactivación; consulta Variables que Claude Code ignora en env.
• La clave espera la confianza. Las reglas permissions.allow, permissions.additionalDirectories, extraKnownMarketplaces y la mayoría de los valores de env se aplican solo después de que cada compañero de equipo confíe en la carpeta. Hasta entonces, siguen viendo solicitudes de permiso y no obtienen plugins de un marketplace que el archivo declara. Las reglas deny y ask se aplican de inmediato.

​

Las reglas de permisos se combinan de forma distinta a lo que esperabas

• Elegiste “Sí, y no preguntes de nuevo” en una solicitud de permiso, pero se te sigue pidiendo confirmación para la misma herramienta. Esa elección guardó una regla allow en tu archivo local, y una regla allow allí no tiene prioridad sobre una regla ask de un archivo de proyecto o administrado; cómo se combinan las reglas de permisos explica el orden. En la extensión de VS Code, la tarjeta de aprobación te permite elegir el archivo de destino, incluido el archivo compartido del proyecto, lo que cambia la regla para todos; en la CLI, Claude Code escribe solo en tu archivo local.
• Las reglas allow de tu organización aún se aplican junto con las tuyas. Es lo esperado: Claude Code fusiona permissions.allow entre alcances, a menos que tu organización establezca allowManagedPermissionRulesOnly.

​

Excepciones a la precedencia de la configuración administrada

​

Configuraciones en sesiones en la nube

• Configuraciones compartidas de proyecto (.claude/settings.json): se leen en una sesión con un repositorio, porque el archivo es parte del clon y la sesión comienza dentro de él. Haz commit de un ajuste allí para aplicarlo en esas sesiones. En un entorno alojado por Anthropic, una sesión con varios repositorios comienza por encima de los clones y lee solo las claves enabledPlugins y extraKnownMarketplaces del .claude/settings.json de cada repositorio, no reglas de permisos, hooks, env u otras claves. Los marketplaces y plugins que esas dos claves declaran aún no se cargan en una sesión en la nube. Para un entorno autohospedado, consulta qué configuración del repositorio se aplica.
• Configuraciones de usuario y proyecto local (~/.claude/settings.json y .claude/settings.local.json): no se leen. Ambas permanecen en su máquina, y el archivo local no está en el clon.
• Configuraciones administradas: un archivo managed-settings.json o perfil MDM en su dispositivo no alcanza una sesión en la nube. Las configuraciones administradas por servidor de su organización sí; cobertura de superficie enumera qué sesiones en la nube las reciben. Un entorno autohospedado también lee el archivo de configuraciones administradas en su imagen de ejecutor. Cómo Claude Code combina fuentes administradas dice cuándo se aplica ese archivo.
• /config: en su navegador en claude.ai/code, abre la sección Claude Code de su configuración de claude.ai en lugar de cambiar un valor. Para cambiar una configuración para una sesión en la nube, establezca una variable de entorno en el entorno, o en una sesión con un repositorio, confirme la clave en el .claude/settings.json de ese repositorio.

​

Qué sigue

• Todas las configuraciones: cada clave, con dónde la establece y un ejemplo
• Archivos de configuración de ejemplo: un archivo personal, un archivo de equipo y un archivo administrado de una organización
• Configurar permisos: reglas allow, ask y deny, y qué ejecuta Claude Code sin preguntar
• Variables de entorno: las variables que lee Claude Code y el bloque env
• Depure su configuración: cuando una configuración no se aplica
• Referencia del directorio Claude: cada archivo que lee Claude Code, incluyendo subagentes, servidores MCP, plugins y CLAUDE.md