Ajustes de Claude Code: el manual de settings.json
Cada clave de settings.json que importa: los cuatro archivos de configuración y su precedencia, modelo y effort, reglas allow/deny de permisos, el bloque env y un flujo real de limpieza de settings.local.json — verificado contra la documentación oficial.
TL;DR
- Cuatro archivos, una jerarquía: managed-settings.json gana a la línea de comandos, que gana a .claude/settings.local.json, que gana a .claude/settings.json, que gana a ~/.claude/settings.json. Las listas de allow se combinan entre archivos en vez de sobrescribirse.
- settings.json es JSON estricto: sin comentarios ni comas finales. Añada la línea "$schema": "https://json.schemastore.org/claude-code-settings.json" y su editor autocompletará cada clave.
- Las reglas deny siempre ganan. Una regla deny en cualquier nivel invalida todas las reglas allow — empiece con Read(./.env) y Bash(git push:*) y habrá protegido sus secretos y su remoto en dos líneas.
- settings.local.json es su sandbox solo de esta máquina: prevalece sobre los ajustes compartidos del proyecto y se añade solo al .gitignore, así que las rutas personales y los experimentos nunca llegan al repositorio.
Claude Code Configuration EP1: The Global Files Decoded (settings.json, CLAUDE.md, skills)
Canal: Terminode AI2:31
Learning In Public: Cleaning Up Claude Code Settings
Canal: Ben Nadel5:26
Settings — official documentation
Documentación oficial: code.claude.com/docs
Settings reference — the full key table
Documentación oficial: code.claude.com/docs
Environment variables — official reference
Documentación oficial: code.claude.com/docs
Los datos de esta página están verificados contra la documentación oficial de settings; los dos vídeos de arriba son las fuentes visuales y la inspiración del flujo de auditoría.
Las capturas se atribuyen a sus creadores con enlaces profundos a los minutos exactos. No se usan fotogramas con caras.
Configurar el settings.json de Claude Code, paso a paso
Parte 1 — Trazar el mapa de la configuración
- 1
Conocer los cuatro archivos de ajustes
Claude Code lee ajustes de cuatro ámbitos: ~/.claude/settings.json (usted, en todos los proyectos), .claude/settings.json (compartido con el equipo, hay que versionarlo), .claude/settings.local.json (usted, solo este proyecto) y managed-settings.json (su organización). Todo lo que vive en ~/.claude — CLAUDE.md, projects, skills, agents, plugins — forma parte del mismo mapa.
La capa global de un vistazo: cada archivo que Claude Code lee de ~/.claude al arrancar una sesión.Ver en 2:28 - 2
Abrir o crear ~/.claude/settings.json
En Mac y Linux el archivo vive en ~/.claude/settings.json; en Windows está en %USERPROFILE%\.claude\settings.json. Créelo si no existe — Claude Code lo recoge en la siguiente sesión. Fije CLAUDE_CONFIG_DIR si quiere toda la carpeta de configuración en otro sitio.
settings.json controla temas, elección de modelo, plugins, variables de entorno y permisos en todos los proyectos de su máquina.Ver en 0:20 - 3
Fijar su modelo y su nivel de effort
Ponga "model" en un modelo concreto o en "opusplan" (Opus planifica, Sonnet ejecuta) y se vuelve el valor por defecto de cada sesión nueva — la misma elección que hace /model de forma interactiva. Combínelo con "effortLevel" para limitar cuánto piensa Claude por defecto, y con modelSettings para sobreescrituras por modelo.
- 4
Permitir los comandos en los que confía
Dentro del bloque permissions, "allow" enumera reglas de herramientas que se saltan el prompt de aprobación: "Bash(npm run lint)", "Bash(npm run test *)", "Read(~/.zshrc)". Las reglas son patrones por herramienta — el comodín * necesita un espacio delante ("Bash(git push:*)") para no tragarse nombres de comando más largos.
Una lista de allow real de un settings.local.json: cada entrada fue un prompt de aprobación que no volverá a aparecer.Ver en 0:50
Parte 2 — Permisos, env y sobreescrituras
- 5
Proteger secretos con reglas deny
Las reglas deny se evalúan primero y nada, en ningún nivel, puede invalidarlas. Empiece con "Read(./.env)" y "Read(./.env.*)" para que las claves de API nunca entren en el contexto, más "Bash(git push:*)" para que publicar al remoto siga siendo decisión humana. Luego deje que las reglas ask atrapen la zona gris.
- 6
Guardar las sobreescrituras locales en settings.local.json
Cuando Claude Code registra un permiso por usted, aterriza en .claude/settings.local.json — que además añade solo al .gitignore. Use ese archivo para rutas personales, flags de experimento y todo lo que no quiera imponer a sus compañeros. Las reglas compartidas y deliberadas pertenecen a .claude/settings.json.
- 7
Poner secretos e interruptores en el bloque env
El objeto "env" aplica variables de entorno a cada sesión: "ANTHROPIC_API_KEY", "DISABLE_TELEMETRY": "1", "DISABLE_NON_ESSENTIAL_MODEL_CALLS": "1", o CLAUDE_CODE_MAX_OUTPUT_TOKENS. Una heurística útil de la documentación: las claves EN_MAYÚSCULAS dentro de settings.json casi siempre pertenecen a env.
- 8
No confundir ~/.claude.json con los ajustes
~/.claude.json es estado, no configuración: tokens OAuth, registros de servidores MCP, decisiones de confianza por proyecto e interruptores globales viven ahí. Edite settings.json para expresar la intención; deje que Claude Code gestione .claude.json por su cuenta — y haga copia de ambos, porque cleanupPeriodDays también rige cuánto sobrevive el historial de transcripciones.
Dentro de ~/.claude: feature flags, plugins, snapshots de shell y el archivo de estado .claude.json, fácil de confundir con un archivo de ajustes.Ver en 2:00
Parte 3 — Mantenerlo limpio con el tiempo
- 9
Saber qué más vive en ~/.claude
CLAUDE.md es su archivo global de instrucciones, leído al inicio de cada sesión. projects/ guarda el historial de conversación y la auto-memoria por repositorio, skills/ contiene flujos SKILL.md bajo demanda, agents/ define subagentes, plugins/ registra los plugins instalados y statsig/ cachea feature flags. settings.json orquesta a todos.
CLAUDE.md es el archivo hermano que la gente confunde con los ajustes: lleva preferencias y convenciones, no claves de configuración.Ver en 0:45 - 10
Pedir a Claude que audite su lista de allow
Las listas de allow crecen un prompt cada vez hasta que nadie recuerda qué contienen. Abra Claude Code y pídale que revise .claude/settings.local.json en busca de entradas redundantes, innecesarias y arriesgadas — Claude sabe qué herramientas trae de serie y qué reglas se solapan.
El prompt de auditoría: revisar la lista de allow y señalar qué es redundante, qué duplica herramientas integradas y qué es directamente arriesgado.Ver en 1:40 - 11
Leer el veredicto como quien revisa código
En la auditoría real que esta página captura, Claude encontró 41 entradas y las clasificó: ls, grep, find, echo y cd duplican herramientas integradas; las entradas con comodín ya cubrían comandos explícitos; las rutas absolutas locales sobraban porque Claude conoce su directorio de trabajo; curl fue la única marcada como genuinamente demasiado permisiva.
El veredicto: 41 entradas clasificadas en innecesarias, redundantes y arriesgadas — con el sustituto para cada línea.Ver en 3:05 - 12
Aplicar la limpieza y revisar cada mes
Apruebe las ediciones propuestas y el archivo se reduce de 41 a 15 entradas. Conviértalo en hábito: una lista de allow que nadie puede leer es una superficie de ataque que nadie ve. Repita la auditoría tras los proyectos grandes y prefiera reglas acotadas como Bash(git diff:*) a aprobaciones en bloque.
La limpieza aplicada: curl, rutas explícitas del home y scripts de un solo uso, fuera de la lista de allow.Ver en 4:50
settings.json vs CLAUDE.md vs ~/.claude.json vs /config
Cuatro superficies parecen «los ajustes de Claude Code» — no son intercambiables. Qué archivo controla qué:
- 1settings.json (todos los ámbitos) — configuración declarativa: model, effort, permissions, env, hooks, statusLine, plugins. JSON estricto, validado por esquema, apto para versionar (salvo el .local).
- 2CLAUDE.md — instrucciones y convenciones en lenguaje natural. Moldea el comportamiento, no la configuración; no hay contrato de clave-valor y se lee en cada sesión.
- 3~/.claude.json — estado de la máquina: datos de OAuth y sesión, registros MCP, confianza por proyecto, flags de onboarding. Lo escribe Claude Code; no conviene editarlo a mano.
- 4/config — el panel interactivo. Es una interfaz sobre las mismas claves: la mayoría de interruptores escriben en ~/.claude/settings.json, algunos (como Show tips) van a settings.local.json y las opciones globales aterrizan en ~/.claude.json.
- 5managed-settings.json — la capa de la organización. Invalida todo (con unas pocas excepciones de seguridad donde gana el valor más estricto): por eso su elección de modelo local puede perder en silencio en el ordenador del trabajo.
Regla práctica: el comportamiento va en CLAUDE.md, la configuración en settings.json, y si un valor parece ignorarla, compruebe si ~/.claude.json o un archivo administrado ya tomó la decisión.
¿Los ajustes no se aplican? Primeros auxilios
La mayoría de problemas de settings.json se reducen a cinco causas. Repáselas en orden:
- 1Errores de sintaxis JSON. settings.json es JSON estricto — una coma de más o un comentario // y el archivo entero se rechaza. Péguelo en un validador, o añada la línea $schema para que su editor marque errores mientras escribe.
- 2Una regla más estricta por encima. Los ajustes administrados y las claves sensibles a la seguridad (como disableClaudeAiConnectors o useAutoModeDuringPlan) ganan a su archivo pase lo que pase. Compruebe si el ordenador del trabajo le está sobreescribiendo.
- 3Archivo equivocado, ámbito equivocado. Las reglas de .claude/settings.json solo aplican dentro de ese proyecto; los valores defaultMode auto y bypassPermissions se ignoran a propósito en archivos de nivel de proyecto.
- 4Valores de entorno en el lugar equivocado. Las claves EN_MAYÚSCULAS pertenecen al bloque env, no al nivel superior. Si ANTHROPIC_API_KEY o DISABLE_TELEMETRY parecen ignoradas, probablemente están un nivel más arriba de donde tocan.
- 5Entradas rechazadas en silencio. Ejecute claude doctor para listar las entradas de settings que no pasaron la validación, y /status en una sesión para ver qué archivos se cargaron de verdad.
¿Sigue atascado? Borre su última edición, confirme con /status que el archivo carga, y vuelva a aplicar el cambio clave a clave — partir el archivo en dos gana a quedarse mirándolo.