SpyBara
Go Premium

settings.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 83 additions and 83 deletions.

2026
Tue 6 23:59 Wed 7 23:59 Fri 9 23:02 Sat 10 23:01 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Tue 27 22:59 Wed 28 23:57

Archivos de configuración y precedencia

Cambie la configuración de Claude Code, elija el ámbito al que pertenece una clave, verifique el cambio y aprenda qué valor usa Claude Code cuando una clave se establece en varios lugares.

Las configuraciones son las claves JSON que cambian cómo se comporta Claude Code: qué modelo inicia, qué puede ejecutar sin preguntar, qué archivos no puede leer, cómo se ve en su terminal y qué aplica su organización.

[!TIP]

Para buscar una clave específica, vaya a Todas las configuraciones, que enumera cada clave con el archivo en el que la establece, su valor predeterminado y un ejemplo.

Claude Code lee configuraciones de archivos de configuración JSON como ~/.claude/settings.json. Las busca en algunos lugares, y el archivo del que lee una configuración decide a quién se aplica. Esta página cubre esos archivos: en cuál poner una configuración, cómo cambiar una configuración y confirmar que se aplicó, y qué valor usa Claude Code cuando la misma clave se establece en más de un archivo. Configurar permisos cubre qué puede ejecutar Claude Code sin preguntar y cómo escribir reglas allow, ask y deny.

[!NOTE]

Esta página cubre Claude Code ejecutándose en su máquina: la terminal, las extensiones de VS Code y JetBrains, y la aplicación de escritorio, que todas leen los mismos archivos de configuración. Una sesión en la nube en Claude Code en la web se ejecuta en una máquina diferente y lee solo algunos de ellos; vea Configuraciones en sesiones en la nube.

Archivos de configuración y a quién afectan

Claude Code lee la configuración de cuatro archivos, y una organización también puede entregar configuración administrada desde la consola de claude.ai. Cada fuente tiene un alcance: el conjunto de personas y proyectos a los que se aplica un ajuste guardado en ella, ya seas solo tú, todos en un proyecto o todos en tu organización.

Alcance Archivo A quién afecta Úsalo para
Usuario ~/.claude/settings.json Tú, en cada proyecto en esta máquina Preferencias personales: tema, modo de editor, modelo predeterminado, tus propias reglas de permisos
Proyecto compartido .claude/settings.json Todos los que trabajan en la carpeta que lo contiene. En un repositorio de git, haz commit del archivo para que tus compañeros de equipo lo obtengan Permisos de equipo, hooks, plugins y las variables de entorno que el proyecto necesita
Proyecto local .claude/settings.local.json Tú, solo en este proyecto. Claude Code lo mantiene fuera de git cuando crea el archivo; si lo creas a mano, agrégalo a .gitignore tú mismo Sobrescrituras personales para un proyecto y pruebas antes de compartir
Administrado managed-settings.json y otras fuentes administradas Todos aquellos a quienes tu organización lo implementa; Precedencia de la configuración indica qué puede sobrescribirlo Políticas de seguridad y requisitos de cumplimiento

En la columna Archivo, ~/.claude es la carpeta .claude en tu directorio home, y un .claude simple es la carpeta .claude dentro de tu proyecto.

Compara el alcance de cada archivo de configuración

Supón que tienes tres proyectos en tu máquina, website/, api/ y acme-app/, un compañero de equipo tiene su propio clon de acme-app/, e inicias una sesión en la nube en acme-app/.

El gráfico a continuación muestra en cuáles de esas carpetas se aplica un ajuste cuando inicias Claude Code desde ellas. Haz clic en un archivo de configuración para ver las carpetas que alcanza.

Settings file

Your machine

A teammate’s machine

A cloud session

  • ~/.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

Instalar Claude Code no crea ningún archivo de configuración. Si tu máquina o proyecto ya tiene uno, vino de una de estas fuentes:

  • 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.

[!NOTE]

En Windows, ~/.claude significa %USERPROFILE%\.claude. Para mantener los archivos del directorio home en otro lugar, establece CLAUDE_CONFIG_DIR; Claude Code entonces almacena tu configuración, historial de sesiones y plugins allí.

Claude Code también mantiene un quinto archivo, ~/.claude.json, que escribe para sí mismo; no necesitas editarlo. Contiene los datos de tu cuenta, configuraciones de servidores MCP, estado por proyecto como decisiones de confianza, y las claves de configuración global que /config escribe por ti.

Comparte la configuración con tu equipo

Haz commit de .claude/settings.json para que todos los que clonen el repositorio obtengan los mismos permisos, hooks y plugins. Cada compañero de equipo aún puede sobrescribirlo para sí mismo en su propio .claude/settings.local.json, por lo que las excepciones personales no necesitan un commit. Para un archivo de equipo completo, consulta la configuración compartida de un equipo.

Parte de lo que incluyes en el commit espera hasta que cada compañero de equipo confíe en la carpeta, y algunas claves nunca surten efecto desde un archivo del repositorio; Solucionar un ajuste que no se aplica cubre ambos casos.

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

Para cambiar un ajuste solo para ti en un proyecto sin cambiarlo para tus compañeros de equipo, guárdalo en .claude/settings.local.json dentro del proyecto. Claude Code aplica ese archivo sobre el .claude/settings.json con commit, por lo que si el archivo de tu equipo establece "model": "claude-sonnet-5" y tú quieres Opus, pon "model": "claude-opus-5-5" en tu archivo local y solo tus sesiones cambian.

Claude Code también escribe en este archivo, lo mantiene fuera de tus commits y aplica sus reglas allow sin el paso de confianza:

  • 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 Claude pide permiso para ejecutar un comando Bash y eliges "Sí, y no preguntes de nuevo", Claude Code guarda esa aprobación como una regla allow en .claude/settings.local.json. Si inicias Claude Code en un subdirectorio de un repositorio de git, lee y escribe ese archivo en la raíz del repositorio y aplica la aprobación en todo el repositorio. En un worktree, usa el archivo en la raíz del checkout principal.

Dos reglas matizan la ubicación en la raíz:

  • 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.

Antes de v2.1.211, Claude Code mantenía el archivo en el directorio donde lo iniciaste. Aún lee un archivo que una versión anterior dejó allí junto al archivo de la raíz; donde ambos establecen la misma clave, se aplica el valor de la raíz, y se aplican las reglas de permisos de ambos archivos. El helper resolveSettings() del Agent SDK siempre lee el archivo desde el directorio donde se inició.

Claude Code lee el .claude/settings.json compartido desde el directorio de trabajo principal de la sesión, así que para usar un archivo con commit en la raíz del repositorio, inicia Claude Code allí. Después de mover la sesión con /cd, Claude Code lee ambos archivos de proyecto desde el nuevo directorio, ubicando el archivo local según las mismas reglas. Leerlos desde el directorio al que te moviste requiere Claude Code v2.1.246 o posterior. Para una sesión de worktree que inicias desde la aplicación de escritorio, consulta Qué comparten los worktrees con el checkout principal.

Verifica qué impone tu organización

Si tu organización administra Claude Code, algunos ajustes se deciden por ti y nada de lo que pongas en tus propios archivos los cambia. Para ver cuáles, ejecuta /status: la línea Setting sources nombra la fuente administrada que se te aplica. La configuración administrada se aplica dondequiera que Claude Code se ejecute en esta máquina; Lo que un desarrollador puede cambiar cubre los derechos de administrador local y las herramientas distintas de Claude Code.

La configuración administrada te llega a través de los mecanismos de entrega de la página de configuración administrada, más comúnmente:

En una sesión de Cowork que se ejecuta en tu máquina en la aplicación Claude Desktop, Claude Code no obtiene la configuración administrada por servidor de la consola de administración de claude.ai, y lee la política implementada en tu dispositivo a menos que la configuración de Claude Desktop de tu organización establezca requireCoworkFullVmSandbox. Dónde y cuándo se aplica una política cubre Cowork y las sesiones en la nube.

Si eres el administrador, Configurar Claude Code para tu organización te guía para elegir qué imponer, y Implementar la configuración administrada cubre la entrega y cómo confirmar que una política está en vigor. Para la advertencia que puede mostrar el editor de configuración administrada en la consola de administración de claude.ai, consulta Configurar la configuración administrada por servidor.

Cambie una configuración

Puede cambiar una configuración desde el menú /config, editando un archivo de configuración, o para una sesión desde la línea de comandos.

El indicador del sistema de Claude Code no se publica. Para dar a Claude instrucciones permanentes, use archivos CLAUDE.md o la bandera --append-system-prompt.

Use el menú /config

Ejecute /config dentro de Claude Code y abra la pestaña Config. Enumera un conjunto corto de opciones personales como tema, modo de editor y salida detallada, no cada clave de configuración. Seleccione una opción para cambiarla; Claude Code la guarda para usted:

  • 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

Para establecer una opción sin el menú, pase key=value, como /config verbose=true.

[!NOTE]

/config es parte de la interfaz de terminal. El panel de chat de VS Code y la aplicación de escritorio no lo abren; cambie las configuraciones allí editando un archivo de configuración o a través de las configuraciones propias de esas aplicaciones.

Edite un archivo de configuración

Abra el archivo de configuración para el ámbito que desea en su editor y agregue o cambie una clave. Los archivos de configuración son JSON estricto: un comentario // o una coma final es un error de sintaxis, y Claude Code reporta el archivo como un Error de configuración al siguiente inicio. Por ejemplo, para permitir que Claude Code ejecute sus comandos de lint y prueba sin preguntar y evitar que lea archivos .env, agregue esto a ~/.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.*)"
    ]
  }
}

Cada entrada bajo permissions es una regla que nombra una herramienta y qué puede hacer; Configurar permisos explica la sintaxis. La línea $schema apunta al esquema JSON publicado para configuraciones de Claude Code, que le da autocompletado y validación en línea en VS Code, Cursor y cualquier otro editor que admita esquema JSON. El esquema puede quedarse atrás de los lanzamientos de CLI más recientes, por lo que una advertencia de validación en una clave documentada recientemente no significa que su configuración sea inválida.

Después de guardar, ejecute /status dentro de Claude Code para confirmar que el archivo se cargó; Confirme qué se cargó dice qué muestra la línea Setting sources y cómo se reporta un archivo roto.

Para un archivo personal completo, archivo de equipo y archivo de organización, cada uno mostrado con un comentario en cada clave que establece, vea los archivos de configuración de ejemplo.

Cambie una configuración para una sesión

Para probar un valor sin guardarlo, establézcalo cuando inicie Claude Code. El valor se aplica a esa sesión y sus archivos de configuración permanecen como estaban. Tiene tres formas de hacerlo:

  • --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.

La entrada de cada clave en la referencia de configuración enumera sus anulaciones por sesión y cuál tiene precedencia, así que verifique la entrada para la clave que desea cambiar.

Los comandos que ejecuta dentro de una sesión principalmente guardan su elección: cuando cambia una configuración en /config, Claude Code la escribe en sus archivos de configuración, y /model guarda el valor como su predeterminado para nuevas sesiones.

Si presiona s en el selector /model, Claude Code cambia el modelo sin guardarlo como su predeterminado de usuario. Ajuste el nivel de esfuerzo dice qué selecciones de /effort Claude Code guarda como su predeterminado para el modelo que está usando y cuáles se aplican solo a la sesión actual.

Por ejemplo, para iniciar una sesión en Opus sin cambiar su predeterminado:

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

Cuándo surten efecto las ediciones

Claude Code observa sus archivos de configuración y los recarga cuando cambian, por lo que aplica la mayoría de ediciones a la sesión en ejecución sin un reinicio, incluyendo ediciones a permissions, hooks y asistentes de credenciales como apiKeyHelper. Claude Code también carga un archivo de configuración que crea a mitad de sesión si su carpeta existía cuando la sesión comenzó. Para la carpeta .claude/ del proyecto, carga el archivo incluso cuando crea la carpeta en la misma sesión.

La recarga cubre configuraciones de usuario, proyecto, local y administradas, y Claude Code ejecuta el hook ConfigChange para cada cambio de archivo de configuración que detecta, no para configuraciones administradas que llegan desde MDM o la consola de claude.ai. Las configuraciones administradas que llegan a través de MDM o de la consola de claude.ai alcanzan una sesión en ejecución en un cronograma en lugar de al guardar; la tabla de entrega lo da por fuente.

Claude Code lee algunas claves solo una vez, al inicio de la sesión, por lo que una edición a una de ellas no alcanza la sesión en ejecución. Las claves del lado del administrador que también esperan un reinicio, como requiredMinimumVersion, se enumeran bajo dónde y cuándo se aplica una política. Las que es más probable que edite a mitad de sesión:

  • 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ó

Ejecute /status dentro de Claude Code para ver qué fuentes de configuración están activas. La pestaña Status incluye una línea Setting sources que enumera cada archivo de configuración que Claude Code cargó para la sesión actual, como User settings o Project local settings. Cuando configuraciones administradas están en vigor, la entrada de configuraciones administradas muestra entre paréntesis cómo llegaron a su máquina.

La línea confirma qué archivos leyó Claude Code; no muestra qué archivo suministró cada clave. Para enumerar entradas que Claude Code rechazó, ejecute claude doctor; para un modelo que configuraciones de proyecto o administradas establecen, el encabezado de inicio nombra el archivo que lo estableció. /status y /config abren el mismo diálogo en pestañas diferentes, y la pestaña Config no es una vista de sus contenidos de settings.json.

Corrija un archivo de configuración roto

Si escribe mal JSON o establece una clave a un valor que Claude Code no acepta, Claude Code se lo dice al inicio de una sesión interactiva. Lo que muestra depende de cuánto del archivo se vea afectado:

  • 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.

Después de continuar, ejecute /status para ver los archivos afectados y claude doctor para los detalles de cada error.

Una ejecución -p no muestra diálogo. A menos que un documento de configuraciones administradas no se pueda analizar, Claude Code omite el archivo o valores rotos y continúa con el resto, por lo que después de una ejecución -p que ignora una configuración, ejecute claude doctor para ver qué descartó.

Precedencia de configuración

Cuando la misma clave aparece en más de un lugar, Claude Code usa el valor del nivel más alto que la establece. La pila a continuación muestra los niveles, con el más alto en la parte superior; una clave en un nivel más alto sobrescribe la misma clave en cualquier lugar debajo de él.

Settings precedence, highest first: managed settings, command line, project local, shared project, user. A key set at a higher level overrides the same key set lower down.

En orden, precedencia más alta primero:

  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 variables de entorno no son un nivel en esta pila. Cuando un comportamiento tiene tanto una variable de shell como una clave de configuración, cuál se aplica se decide por par, no por nivel: ANTHROPIC_MODEL exportada en tu shell se aplica sobre la clave model de cualquier archivo, mientras que ANTHROPIC_DEFAULT_MODEL se aplica solo cuando ningún archivo establece model. La referencia de variables de entorno indica qué claves tienen un par y cuál lee Claude Code primero. Un bloque env dentro de un archivo de configuración es una clave ordinaria y sigue los niveles anteriores.

Para algunas claves sensibles a la seguridad, Claude Code honra un valor más estricto de un nivel inferior sobre un valor administrado; Excepciones a la precedencia de la configuración administrada las enumera.

Las listas se fusionan en lugar de sobrescribirse

Cuando estableces la misma clave de lista, como permissions.allow, en más de un archivo, Claude Code combina las listas en lugar de elegir una, por lo que cada archivo puede agregar entradas sin eliminar las de otro archivo. Cuatro claves que contienen listas de modelos o entradas por modelo siguen sus propias reglas:

  • 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

Mientras Claude trabaja, Claude Code muestra un consejo de una línea bajo el spinner, como "Use /config to change your default permission mode (including Plan Mode)". Supón que quieres desactivar esos consejos, así que estableces spinnerTipsEnabled en false en ~/.claude/settings.json. Cada escenario a continuación es algo que puede volver a activarlos, junto con lo que puedes hacer al respecto.

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

El .claude/settings.json de tu equipo lo establece en true. Claude Code usa el valor del proyecto porque el proyecto compartido está por encima del usuario, así que ves consejos en ese proyecto y en ningún otro lugar.

Puedes recuperar tu valor: agrega "spinnerTipsEnabled": false a .claude/settings.local.json en ese proyecto. El proyecto local está por encima del proyecto compartido, así que tus sesiones allí dejan de mostrar consejos y las sesiones de tus compañeros de equipo no cambian.

La configuración de la organización sobrescribe todo

La configuración administrada de tu organización lo establece en true. Nada de lo que pongas en la configuración de usuario, de proyecto o local desactiva los consejos, y --settings tampoco. La configuración administrada es el nivel superior.

No puedes recuperar tu valor. Ejecuta /status para ver qué fuente administrada se aplica, y pregunta a tu administrador si la política debería cambiar.

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

Iniciaste la sesión con claude --settings '{"spinnerTipsEnabled": true}'. La línea de comandos está por encima de todos los archivos excepto la configuración administrada, así que esa sesión muestra consejos aunque tus archivos digan false.

Recuperas tu valor en la siguiente sesión; --settings dura una sesión y no escribe en ningún archivo.

Un flag o una variable de entorno establece lo mismo

Algunas claves tienen un flag de línea de comandos o una variable de entorno que sobrescribe el valor de configuración sin importar qué archivo lo estableció: ANTHROPIC_MODEL sobrescribe el ajuste model, y --model sobrescribe ambos para una sesión.

Si puedes recuperar tu valor depende de la clave: quita la variable o deja de usar el flag, y consulta la entrada de la clave en la referencia de configuración y la fila de la variable en la referencia de variables de entorno para saber cuál usa Claude Code.

Solucionar un ajuste que no se aplica

Cuando estableces una clave y Claude Code no se comporta como si lo hubieras hecho, empieza con /status para ver qué archivos cargó y luego busca tu síntoma a continuación. Depura tu configuración cubre las verificaciones más amplias, incluida una prueba con una configuración limpia.

Un valor que estableces se ignora

Algo más está estableciendo la misma clave, el archivo no puede establecer ese valor o el archivo no se cargó:

  • 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

Cuando guardas una elección para nuevas sesiones desde dentro de Claude Code, como un modelo predeterminado con /model, Claude Code la escribe en tu archivo de configuración de usuario, ~/.claude/settings.json. Si no puedes escribir en ese archivo, por ejemplo porque otra herramienta lo genera o lo vincula a una copia de solo lectura, el cambio se aplica a la sesión actual y desaparece en la siguiente. Establece la clave en la herramienta que genera el archivo, o reemplaza el archivo por uno en el que puedas escribir.

Si puedes escribir en el archivo y el cambio aún no persiste, verifica si el cambio fue solo para una sesión o si un nivel más alto establece la misma clave. Para la clave model, Una nueva sesión comienza con un modelo diferente al que elegiste enumera más causas.

Un cambio administrado no te ha llegado

Las fuentes administradas llegan a una sesión en ejecución según el calendario de la tabla de entrega, así que primero reinicia la sesión. Si luego /status nombra una fuente diferente a la que cambió tu administrador, se aplica una fuente de mayor prioridad; Cómo Claude Code combina fuentes administradas indica el orden.

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

Dos cosas impiden que una clave en .claude/settings.json se aplique para todos los que lo clonan:

  • 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

Para algunas claves cuyos valores restringen una sesión, Claude Code honra un valor restrictivo de un alcance que de otro modo no podría sobrescribir la configuración administrada. Busca la clave en esta tabla para ver qué valor honra y de dónde.

Clave Valor que Claude Code honra Notas
disableClaudeAiConnectors true de cualquier alcance Honrado incluso cuando una fuente administrada establece false
enableArtifact false de cualquier alcance, y disableArtifact: true de cualquier alcance Honrado incluso cuando una fuente administrada establece true; nada vuelve a activar la herramienta Artifact. Requiere Claude Code v2.1.242 o posterior
isolatePeerMachines true de cualquier alcance Honrado incluso cuando una fuente administrada establece false
permissions.blockReadsOutsideWorkingDirectories true de cualquier alcance Honrado incluso cuando una fuente administrada establece false. Requiere Claude Code v2.1.257 o posterior
autoMode.classifyAllShell true de ~/.claude/settings.json o --settings Honrado incluso cuando una fuente administrada establece false
remoteControlAtStartup false de .claude/settings.json o .claude/settings.local.json Honrado incluso cuando una fuente administrada establece true; un true de proyecto o local se ignora
crossSessionInbound Un valor más estricto de .claude/settings.json o .claude/settings.local.json, en la escala accept < hold < refuse Honrado sobre los valores administrados, de --settings y de usuario; un valor de proyecto o local que no sea más estricto se ignora
useAutoModeDuringPlan false de cualquier fuente administrada, --settings, ~/.claude/settings.json o .claude/settings.local.json Honrado incluso cuando la fuente administrada ganadora establece true; un false en .claude/settings.json se ignora
syncClaudeAiSkills false de cualquier fuente administrada, --settings, ~/.claude/settings.json o .claude/settings.local.json Honrado incluso cuando la fuente administrada ganadora establece true; un false en .claude/settings.json se ignora
syncClaudeAiPlugins false de cualquier fuente administrada, --settings, ~/.claude/settings.json o .claude/settings.local.json Honrado incluso cuando la fuente administrada ganadora establece true; un false en .claude/settings.json se ignora
maxEffortLevel Un límite más bajo de cualquier alcance, incluido --settings Honrado incluso cuando la configuración administrada que Claude Code aplica establece un límite más alto; se aplica el límite más bajo. Requiere Claude Code v2.1.267 o posterior

Una aplicación que ejecuta Claude Code dentro de sí misma y establece CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST también es una excepción. Claude Code toma la configuración de modelo de esa aplicación por encima de las claves model, fallbackModel, modelPicker y modelOverrides de cada fuente administrada, y por encima de las variables de selección de modelo en un bloque env administrado, como ANTHROPIC_MODEL y la familia ANTHROPIC_DEFAULT_*_MODEL. Claude Code mantiene en vigor una lista de permitidos availableModels administrada, a menos que la aplicación suministre la suya.

Configuraciones en sesiones en la nube

Una sesión en la nube se ejecuta en un entorno en la nube en un clon fresco de su repositorio, no en su máquina. Eso cambia qué configuraciones lo alcanzan:

  • Hilos en la nube en un proyecto: en un hilo en la nube en un proyecto, no se aplica ninguna de las reglas de permisos, hooks ni env del .claude/settings.json de un repositorio, sin importar cuántos repositorios tenga el proyecto. Lo que los hilos toman de tus repositorios enumera qué usar en su lugar.
  • Configuraciones compartidas de proyecto (.claude/settings.json): se leen en una sesión con un repositorio fuera de los hilos de un proyecto, 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.
  • Configuraciones compartidas de proyecto con varios repositorios: 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 tu navegador en claude.ai/code, abre la sección Claude Code de tu configuración de claude.ai en lugar de cambiar un valor. Para cambiar un ajuste para una sesión en la nube, establece una variable de entorno en el entorno. En una sesión con un repositorio fuera de los hilos de un proyecto, en su lugar puedes hacer commit de la clave en el .claude/settings.json de ese repositorio.

Lo que se transfiere de su configuración enumera el resto: CLAUDE.md, skills, servidores MCP, plugins y credenciales.

Qué sigue