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.
export const SettingsPrecedence = () => {
const LEVELS = [{
n: 1,
name: 'Managed settings',
file: 'managed-settings.json, MDM, or the claude.ai console',
who: 'Your organization',
w: 390
}, {
n: 2,
name: 'Command line',
file: 'claude --settings',
who: 'You, this session',
w: 420
}, {
n: 3,
name: 'Project local',
file: '.claude/settings.local.json',
who: 'You, this project',
w: 480
}, {
n: 4,
name: 'Shared project',
file: '.claude/settings.json',
who: 'Everyone in the project',
w: 540
}, {
n: 5,
name: 'User',
file: '~/.claude/settings.json',
who: 'You, every project',
w: 600
}];
const W = 760;
const ROW = 58;
const GAP = 8;
const TOP = 34;
const H = TOP + LEVELS.length * (ROW + GAP) + 30;
const cx = W / 2;
const mono = 'var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace)';
const sans = 'var(--font-sans, system-ui, -apple-system, sans-serif)';
return
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.
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.
Archivos de configuración y a quién afectan
Claude Code lee configuraciones de cuatro archivos, y una organización también puede entregar configuraciones administradas desde la consola de claude.ai. Cada fuente tiene un ámbito: el conjunto de personas y proyectos a los que se aplica una configuración guardada en ella, ya sea solo usted, todos en un proyecto o todos en su organización.
Ámbito
Archivo
A quién afecta
Úselo para
Usuario
~/.claude/settings.json
Usted, en cada proyecto en esta máquina
Preferencias personales: tema, modo de editor, modelo predeterminado, sus propias reglas de permiso
Proyecto compartido
.claude/settings.json
Todos los que trabajan en la carpeta que lo contiene. En un repositorio de git, confirme para que los 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
Usted, solo en este proyecto. Claude Code lo mantiene fuera de git cuando crea el archivo; si lo crea a mano, agréguelo a .gitignore usted mismo
Anulaciones personales para un proyecto y pruebas antes de compartir
Política de seguridad y requisitos de cumplimiento
En la columna Archivo, ~/.claude es la carpeta .claude en su directorio de inicio, y un .claude simple es la carpeta .claude dentro de su proyecto.
Compare el ámbito de cada archivo de configuración
Suponga que tiene tres proyectos en su máquina, website/, api/ y acme-app/, un compañero de equipo tiene su propio clon de acme-app/, e inicia una sesión en la nube en acme-app/.
El gráfico a continuación muestra a cuál de esas carpetas se aplica una configuración cuando inicia Claude Code desde ellas. Haga clic en un archivo de configuración para ver las carpetas que alcanza.
~/.claude/settings.json: cada proyecto en su máquina, y nada en la de su compañero de equipo o en la sesión en la nube
acme-app/.claude/settings.json: su acme-app/. Alcanza el clon de su compañero de equipo y la sesión en la nube solo si confirma el archivo en el control de versiones; hasta entonces, es un archivo en su disco como cualquier otro y nadie más lo tiene
acme-app/.claude/settings.local.json: su acme-app/ solo. Claude Code lo agrega a sus exclusiones globales de git la primera vez que escribe el archivo, por lo que se mantiene fuera de sus confirmaciones; si crea el archivo a mano, agréguelo a .gitignore usted mismo
Configuraciones administradas, ya sea un archivo managed-settings.json, una política MDM, o configuraciones administradas por servidor desde la consola de claude.ai: cada proyecto en cada máquina en la que su organización lo implementa, o en la que inicia sesión con su cuenta de organización. Solo las configuraciones administradas por servidor alcanzan la sesión en la nube
Encuentre o cree sus archivos de configuración
Instalar Claude Code no crea ningún archivo de configuración. Si su máquina o proyecto ya tiene uno, vino de una de estas fuentes:
Administrado: su organización lo implementa. Usted no lo crea ni lo edita.
Proyecto compartido: un proyecto que ya usa Claude Code puede tener uno confirmado. Si no, créelo en .claude/settings.json en la carpeta del proyecto.
Usuario y Proyecto local: créelos usted mismo, o deje que Claude Code los cree. Escribe ~/.claude/settings.json la primera vez que cambia una opción en el menú /config que almacena en configuraciones de usuario, como el tema, y .claude/settings.local.json la primera vez que da una aprobación permanente en un aviso de permiso, como "Sí, y no preguntes de nuevo" para un comando Bash. Algunas opciones de /config, incluyendo Mostrar consejos, se guardan en .claude/settings.local.json en su lugar.
Claude Code también mantiene un quinto archivo, ~/.claude.json, que escribe para sí mismo; no necesita editarlo. Contiene su sesión de inicio de sesión, configuraciones de servidor MCP, estado por proyecto como decisiones de confianza, y las claves de configuración global que /config escribe para usted.
Comparta configuraciones con su equipo
Confirme .claude/settings.json para que todos los que clonan el repositorio obtengan los mismos permisos, hooks, telemetría y plugins. Cada compañero de equipo aún puede anularlo para sí mismo en su propio .claude/settings.local.json, por lo que las excepciones personales no necesitan una confirmación. Para un archivo de equipo completo, vea configuraciones compartidas de un equipo.
Mantenga las configuraciones personales fuera de un repositorio
Para cambiar una configuración para usted en un proyecto sin cambiarla para sus compañeros de equipo, guárdela en .claude/settings.local.json dentro del proyecto. Claude Code aplica ese archivo sobre el .claude/settings.json confirmado, por lo que si el archivo de su equipo establece "model": "claude-sonnet-5" y usted quiere Opus, ponga "model": "claude-opus-5-5" en su archivo local y solo sus sesiones cambian.
Claude Code también escribe en este archivo, lo mantiene fuera de sus confirmaciones, 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 elige "Sí, y no preguntes de nuevo", Claude Code guarda esa aprobación de permiso aquí como una regla allow.
No necesita gitignore usted mismo, a menos que lo haya 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 su archivo de exclusiones global de git, por lo que el archivo se mantiene fuera de sus confirmaciones en cada repositorio. Ese archivo es core.excludesFile cuando su 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 creó el archivo a mano y Claude Code aún no ha escrito en él, agréguelo a .gitignore usted mismo.
Sus reglas allow no esperan confianza mientras el archivo permanece sin rastrear. Porque el archivo es suyo y no del repositorio, Claude Code aplica sus reglas allow sin el paso de confianza del espacio de trabajo que requiere para el archivo confirmado. Si el archivo es rastreado por git, el paso de confianza también se aplica a él; vea Cuando su archivo de configuración local necesita confianza.
Dónde Claude Code mantiene el archivo local en un repositorio de git
Cuando Claude pide permiso para ejecutar un comando Bash y elige "Sí, y no preguntes de nuevo", Claude Code guarda esa aprobación como una regla allow en .claude/settings.local.json. Si inicia 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 califican la ubicación raíz:
Cuando el archivo se queda con .claude/settings.json en su lugar: fuera de un repositorio de git, cuando la raíz del repositorio es su directorio de inicio, en Windows, o cuando la raíz del repositorio o su entrada .git o .claude no es propiedad de su usuario.
Antes de v2.1.211, Claude Code mantenía el archivo en el directorio de inicio. Aún lee un archivo que una versión anterior dejó allí junto al archivo raíz; donde ambos establecen la misma clave, se aplica el valor de la raíz, y las reglas de permiso de ambos archivos se aplican. El asistente resolveSettings() del Agent SDK siempre lee el archivo desde el directorio de inicio.
Claude Code lee el .claude/settings.json compartido desde el directorio de trabajo principal de la sesión, por lo que para usar un archivo confirmado en la raíz del repositorio, inicie Claude Code allí. Después de mover la sesión con /cd, Claude Code lee ambos archivos de proyecto desde el nuevo directorio en su lugar, colocando el archivo local por las mismas reglas. Leerlos desde el directorio al que se movió requiere Claude Code v2.1.246 o posterior.
Verifique qué aplica su organización
Si su organización administra Claude Code, algunas configuraciones se deciden para usted y nada de lo que ponga en sus propios archivos las cambia. Para ver cuáles, ejecute /status: la línea Setting sources nombra la fuente administrada que se aplica a usted. Las configuraciones administradas se aplican dondequiera que Claude Code se ejecute en esta máquina; Lo que un desarrollador puede cambiar cubre derechos de administrador local y herramientas distintas de Claude Code.
Las configuraciones administradas lo alcanzan a través de los mecanismos de entrega en la página de configuraciones administradas, más comúnmente:
En una sesión de Cowork que se ejecuta en su máquina en la aplicación Claude Desktop, Claude Code no obtiene configuraciones administradas por servidor de la consola de administrador de claude.ai, y lee la política implementada en su dispositivo a menos que la configuración de Claude Desktop de su organización establezca requireCoworkFullVmSandbox. Dónde y cuándo se aplica una política cubre Cowork y sesiones en la nube.
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
Para establecer una opción sin el menú, pase key=value, como /config verbose=true.
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
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.
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, más alto en la parte superior; una clave en un nivel más alto anula la misma clave en cualquier lugar debajo.
En orden, precedencia más alta primero:
Configuraciones administradas: configuraciones que su organización implementa, por un archivo managed-settings.json, una política MDM, o configuraciones administradas por servidor de la consola de claude.ai. Nada de lo que establezca las anula: una clave que pasa con --settings no anula la misma clave administrada, y una bandera como --model elige solo de los modelos que su organización permite. Una model administrada establece el modelo con el que cada sesión comienza, y aún puede cambiar con /model; el bloqueo es availableModels, que restringe /model, --model y la clave model en sus propios archivos. Cuando su organización entrega más de una fuente administrada, las reglas para precedencia dentro del nivel administrado dicen qué lee Claude Code de cada una.
Argumentos de línea de comandos: banderas que pasa cuando inicia claude desde una terminal, para una sesión; vea Cambie una configuración para una sesión. Claude Code fusiona JSON que pasa con --settings <file-or-json> con sus archivos de configuración por las mismas reglas que los otros niveles: toma una clave que establece aquí sobre la misma clave en configuraciones locales, de proyecto o de usuario, y mantiene el valor de nivel inferior para una clave que omite.
Configuraciones locales de proyecto (.claude/settings.local.json): sus configuraciones personales para este proyecto.
Configuraciones compartidas de proyecto (.claude/settings.json): configuraciones que su equipo verifica en el control de código fuente.
Configuraciones de usuario (~/.claude/settings.json): sus configuraciones personales para cada proyecto.
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 su 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 dice 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.
Cuando establece 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 más alto de configuraciones administradas, --settings y configuraciones de usuario que la define, e ignora la clave en configuraciones de proyecto y local. Requiere Claude Code v2.1.242 o posterior.
availableModels: cuando las configuraciones administradas que Claude Code aplica la definen, Claude Code aplica esa lista tal cual e ignora entradas que agrega en configuraciones de usuario, proyecto o local, a menos que una aplicación que incrusta Claude Code suministre su propia lista de modelos; vea Excepciones a la precedencia de configuraciones administradas. Entre fuentes administradas la lista nunca se fusiona tampoco; cómo Claude Code combina fuentes administradas dice qué lista de fuente se aplica. Entre ámbitos 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 qué archivo de valor 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 para cambiar su modo de permiso predeterminado (incluyendo Plan Mode)". Suponga que desea esos consejos apagados, por lo que establece spinnerTipsEnabled en false en ~/.claude/settings.json. Cada escenario a continuación es algo que puede encenderlos de nuevo, y qué puede hacer al respecto.
Las configuraciones de equipo anulan las configuraciones personales
El .claude/settings.json de su equipo lo establece en true. Claude Code usa el valor del proyecto porque el proyecto compartido se sienta sobre el usuario, por lo que ve consejos en ese proyecto y en ningún otro lugar.
Puede recuperar su valor: agregue "spinnerTipsEnabled": false a .claude/settings.local.json en ese proyecto. El proyecto local se sienta sobre el proyecto compartido, por lo que sus sesiones allí dejan de mostrar consejos y las sesiones de sus compañeros de equipo no cambian.
Las configuraciones de la organización anulan todo
Las configuraciones administradas de su organización lo establecen en true. Nada de lo que ponga en configuraciones de usuario, proyecto o local apaga los consejos, y tampoco --settings. Administrado es el nivel superior.
No puede recuperar su valor. Ejecute /status para ver qué fuente administrada se aplica, y pregunte a su administrador si la política debería cambiar.
La línea de comandos anula sus archivos para una sesión
Inició la sesión con claude --settings '{"spinnerTipsEnabled": true}'. La línea de comandos se sienta sobre cada archivo excepto administrado, por lo que esa sesión muestra consejos aunque sus archivos digan false.
Recupera su valor en la siguiente sesión; --settings dura una sesión y no escribe en ningún archivo.
Una bandera o variable de entorno establece lo mismo
Algunas claves tienen una bandera de línea de comandos o una variable de entorno que anula el valor de configuración independientemente de qué archivo lo estableció: ANTHROPIC_MODEL anula la configuración model, y --model anula ambas para una sesión.
Si puede recuperar su valor depende de la clave: desexporte la variable o suelte la bandera, y verifique 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 cuál usa Claude Code.
Solucione una configuración que no se aplica
Cuando establece una clave y Claude Code no se comporta como si lo hubiera hecho, comience con /status para ver qué archivos cargó, luego encuentre su síntoma a continuación. Depure su configuración cubre las verificaciones más amplias, incluyendo una prueba de configuración limpia.
Un valor que establece 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, una bandera --settings, o una fuente administrada establece la clave por encima de la suya; la pila dice cuál. Una bandera o variable de entorno también puede anular la clave por su cuenta, decidido clave por clave; la entrada de la clave en la referencia de configuración dice cuál usa Claude Code, y la entrada env cubre un valor env administrado versus una exportación de shell.
El archivo no puede establecer ese valor. Los valores permissions.defaultModeauto y bypassPermissions no surten efecto desde configuraciones de proyecto o local; establézcalos en configuraciones de usuario o administradas en su lugar, o pase --permission-mode para una sesión. Antes de v2.1.257, bypassPermissions surtía efecto desde cualquier archivo.
Un cambio que hizo en Claude Code se pierde en nuevas sesiones
Cuando guarda una elección para nuevas sesiones desde dentro de Claude Code, como un modelo predeterminado con /model, Claude Code lo escribe en su archivo de configuración de usuario, ~/.claude/settings.json. Si no puede 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 se pierde en la siguiente. Establezca la clave en la herramienta que genera el archivo, o reemplace el archivo con uno en el que pueda escribir.
Las fuentes administradas alcanzan una sesión en ejecución en el cronograma en la tabla de entrega, por lo que reinicie la sesión primero. Si /status entonces nombra una fuente diferente a la que su administrador cambió, una fuente de mayor prioridad se aplica; Cómo Claude Code combina fuentes administradas da el orden.
Una clave confirmada no alcanza a los compañeros de equipo
Dos cosas mantienen una clave en .claude/settings.json de aplicarse para todos los que la clonan:
Claude Code ignora la clave en un archivo de repositorio. Busque User, local, or managed, User or managed, Managed, o Global config en la columna Scope del índice de configuración. Esas claves nunca se aplican desde el archivo compartido, aparte de algunas que un archivo de repositorio aún puede apagar. Cada una de esas entradas lo dice en su línea de Scope. Las claves Global config se aplican solo desde ~/.claude.json.
La clave espera confianza. Las reglas permissions.allow, permissions.additionalDirectories, extraKnownMarketplaces y la mayoría de valores env se aplican solo después de que cada compañero de equipo confíe en la carpeta. Hasta entonces aún ven avisos y no obtienen plugins de un marketplace que el archivo declara. Las reglas deny y ask se aplican de inmediato.
Las reglas de permiso se combinan diferente a lo que esperaba
Eligió "Sí, y no preguntes de nuevo" en un aviso de permiso pero aún recibe avisos para la misma herramienta. Esa elección guardó una regla allow en su archivo local, y una regla allow allí no supera una regla ask de un archivo de proyecto o administrado; cómo se combinan las reglas de permiso explica el orden. En la extensión de VS Code la tarjeta de aprobación le permite elegir el archivo de destino, incluyendo el archivo compartido del proyecto, que cambia la regla para todos; en la CLI, Claude Code escribe solo en su archivo local.
Las reglas allow de su organización aún se aplican junto con las suyas. Eso es esperado: Claude Code fusiona permissions.allow entre ámbitos, a menos que su organización establezca allowManagedPermissionRulesOnly.
Excepciones a la precedencia de configuraciones administradas
Para algunas claves cuyos valores restringen una sesión, Claude Code honra un valor restrictivo de un ámbito que de otra manera no podría anular configuraciones administradas. Encuentre la clave en esta tabla para ver qué valor honra y de dónde.
false de cualquier ámbito, y disableArtifact: true de cualquier ámbito
Honrado incluso cuando una fuente administrada establece true; nada enciende la herramienta Artifact de nuevo. Requiere Claude Code v2.1.242 o posterior
Un límite más bajo de cualquier ámbito, incluyendo --settings
Honrado incluso cuando las configuraciones administradas que Claude Code aplica establecen 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 sobre las claves model, fallbackModel, modelPicker, y modelOverrides de cada fuente administrada, y sobre las variables de selección de modelo en un bloque env administrado, como ANTHROPIC_MODEL y la familia ANTHROPIC_DEFAULT_*_MODEL. Claude Code mantiene una lista blanca availableModels administrada en vigor 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:
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. Confirme una configuración allí para aplicarla en esas sesiones. Una sesión con varios repositorios comienza por encima de los clones y lee solo las claves enabledPlugins y extraKnownMarketplaces de cada .claude/settings.json del repositorio, no reglas de permisos, hooks, env u otras claves. Los mercados y plugins que esas dos claves declaran aún no se cargan en una sesión en la nube.
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.
/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.
468 Mantenga las configuraciones personales fuera de un repositorio468 Mantenga las configuraciones personales fuera de un repositorio
469</h3>469</h3>
470470
471Para cambiar una configuración para usted en un proyecto sin cambiarla para sus compañeros de equipo, guárdela en `.claude/settings.local.json` dentro del proyecto. Claude Code aplica ese archivo sobre el `.claude/settings.json` confirmado, por lo que si el archivo de su equipo establece `"model": "claude-sonnet-5"` y usted quiere Opus, ponga `"model": "claude-opus-4-8"` en su archivo local y solo sus sesiones cambian.471Para cambiar una configuración para usted en un proyecto sin cambiarla para sus compañeros de equipo, guárdela en `.claude/settings.local.json` dentro del proyecto. Claude Code aplica ese archivo sobre el `.claude/settings.json` confirmado, por lo que si el archivo de su equipo establece `"model": "claude-sonnet-5"` y usted quiere Opus, ponga `"model": "claude-opus-5-5"` en su archivo local y solo sus sesiones cambian.
472472
473Claude Code también escribe en este archivo, lo mantiene fuera de sus confirmaciones, y aplica sus reglas allow sin el paso de confianza:473Claude Code también escribe en este archivo, lo mantiene fuera de sus confirmaciones, y aplica sus reglas allow sin el paso de confianza:
474474
598Por ejemplo, para iniciar una sesión en Opus sin cambiar su predeterminado:598Por ejemplo, para iniciar una sesión en Opus sin cambiar su predeterminado:
804Una [sesión en la nube](/docs/es/claude-code-on-the-web) se ejecuta en un [entorno en la nube](/docs/es/cloud-environments) en un clon fresco de su repositorio, no en su máquina. Eso cambia qué configuraciones lo alcanzan:804Una [sesión en la nube](/docs/es/claude-code-on-the-web) se ejecuta en un [entorno en la nube](/docs/es/cloud-environments) en un clon fresco de su repositorio, no en su máquina. Eso cambia qué configuraciones lo alcanzan:
805805
806* **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. Confirme una configuración allí para aplicarla en esas sesiones. Una sesión con varios repositorios comienza por encima de los clones,porloque de cada `.claude/settings.json` del repositorio solo carga los plugins y mercados que el archivo declara, no reglas de permisos, hooks, `env` u otras claves;consulte[Lo que se transfieredesuconfiguración](/docs/es/cloud-environments#what-carries-over-from-your-setup).806* **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. Confirme una configuración allí para aplicarla en esas sesiones. Una sesión con varios repositorios comienza por encima de los clones yleesololas claves `enabledPlugins` y `extraKnownMarketplaces` de cada `.claude/settings.json` del repositorio, no reglas de permisos, hooks, `env` u otras claves.Losmercadosy plugins que esas dos claves declaran aún [no se carganenunasesión en la nube](/docs/es/cloud-environments#what-carries-over-from-your-setup).
807* **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.807* **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.
808* **Configuraciones administradas**: solo [configuraciones administradas por servidor](/docs/es/server-managed-settings) alcanzan una sesión en la nube; un archivo `managed-settings.json` o perfil MDM en su dispositivo no. Un [entorno autohospedado](/docs/es/self-hosted-environments) también lee el archivo de configuraciones administradas en su imagen de ejecutor. [Cómo Claude Code combina fuentes administradas](/docs/es/managed-settings#how-claude-code-combines-managed-sources) dice cuándo se aplica ese archivo.808* **Configuraciones administradas**: solo [configuraciones administradas por servidor](/docs/es/server-managed-settings) alcanzan una sesión en la nube; un archivo `managed-settings.json` o perfil MDM en su dispositivo no. Un [entorno autohospedado](/docs/es/self-hosted-environments) también lee el archivo de configuraciones administradas en su imagen de ejecutor. [Cómo Claude Code combina fuentes administradas](/docs/es/managed-settings#how-claude-code-combines-managed-sources) dice cuándo se aplica ese archivo.
809* **`/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](/docs/es/cloud-environments#set-environment-variables) en el entorno, o en una sesión con un repositorio, confirme la clave en el `.claude/settings.json` de ese repositorio.809* **`/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](/docs/es/cloud-environments#set-environment-variables) en el entorno, o en una sesión con un repositorio, confirme la clave en el `.claude/settings.json` de ese repositorio.