Claude Code — Configuración · Agentes de IA para programar

Claude Code se configura con archivos settings.json en capas, más variables de entorno. Añadir "$schema": "https://json.schemastore.org/claude-code-settings.json" a un archivo de ajustes activa el autocompletado en el editor.

Dónde viven los ajustes y en qué orden mandan

De mayor a menor prioridad:

Prioridad	Ámbito	Ubicación
1 (la más alta)	Gestionado (empresa)	macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`; Linux/WSL: `/etc/claude-code/managed-settings.json`; Windows: `C:\Program Files\ClaudeCode\managed-settings.json`
2	Argumentos de línea de comandos	Sobrescriben sólo esa sesión (ver Flags del CLI)
3	Proyecto, local	`.claude/settings.local.json` (se ignora en git automáticamente)
4	Proyecto	`.claude/settings.json` (súbelo a git para compartirlo con el equipo)
5 (la más baja)	Usuario	`~/.claude/settings.json`

Los ajustes gestionados no se pueden sobrescribir — así es como las empresas imponen su política.

El resto del estado vive en ~/.claude.json: preferencias, la sesión OAuth, los servidores MCP de ámbito usuario/local y el estado por proyecto, como las herramientas permitidas y la confianza. Claude Code guarda copias de seguridad con marca de tiempo (las 5 más recientes) de los archivos de configuración.

Ajustes clave

Un settings.json representativo:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "cleanupPeriodDays": 30,
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "120000"
  },
  "permissions": {
    "defaultMode": "plan",
    "allow": ["Bash(npm run *)", "Read"],
    "deny": ["Read(./.env)"],
    "additionalDirectories": ["../shared-lib"]
  },
  "enabledPlugins": {
    "my-plugin@my-marketplace": true
  },
  "statusLine": { "type": "command", "command": "my-statusline.sh" }
}

Claves de uso frecuente (todas verificadas en la referencia de ajustes):

Clave	Para qué sirve
`model`	Modelo por defecto
`apiKeyHelper`	Comando auxiliar que proporciona una API key
`cleanupPeriodDays`	Retención de sesiones (30 por defecto; `0` las borra todas al arrancar)
`env`	Variables de entorno que se aplican a todas las sesiones
`permissions`	`allow` / `ask` / `deny` / `additionalDirectories` / `defaultMode` / `disableBypassPermissionsMode` — ver Permisos
`hooks`	Hooks de eventos; `disableAllHooks` los apaga todos
`attribution`	`commit`, `pr` — sustituye al obsoleto `includeCoAuthoredBy`
`outputStyle`	Estilo de salida (por ejemplo `Explanatory`)
`statusLine`	Comando para una línea de estado personalizada
`respectGitignore`	Respetar `.gitignore` en las operaciones con archivos
`fileSuggestion`	Comportamiento de las sugerencias de archivo en las menciones con `@`
`enableAllProjectMcpServers`	Activa automáticamente los servidores de `.mcp.json`
`enabledMcpjsonServers` / `disabledMcpjsonServers`	Listas de permitidos/denegados por servidor de `.mcp.json`
`forceLoginMethod`	`claudeai` o `console`
`forceLoginOrgUUID`	Fija el login a una organización
`autoUpdatesChannel`	`stable` o `latest`
`plansDirectory`	Dónde se guardan los planes del modo plan (por defecto `~/.claude/plans`)
`language`	Idioma de las respuestas
`showTurnDuration` / `spinnerVerbs` / `spinnerTipsEnabled`	Detalles cosméticos de la TUI
`terminalProgressBarEnabled` / `prefersReducedMotion`	Comportamiento de la TUI
`teammateMode`	Modo de visualización de los equipos de agentes
`awsAuthRefresh` / `awsCredentialExport`	Gestión de credenciales de Bedrock
`alwaysThinkingEnabled`	Mantiene siempre activo el razonamiento extendido
`companyAnnouncements`	Anuncios que se muestran a los usuarios

Claves sólo para ajustes gestionados (política de empresa): allowManagedHooksOnly, allowManagedPermissionRulesOnly, allowedMcpServers, deniedMcpServers, strictKnownMarketplaces.

Claves de plugins: enabledPlugins (formato "plugin@marketplace": true/false), extraKnownMarketplaces.

Las claves del sandbox (sandbox.enabled, autoAllowBashIfSandboxed, reglas de red, …) se cubren en Permisos.

Variables de entorno

Todas se pueden fijar también dentro de settings.json, bajo env.

Variable	Para qué sirve
`ANTHROPIC_API_KEY`	Autenticación por API key
`ANTHROPIC_AUTH_TOKEN`	Token de autenticación personalizado
`ANTHROPIC_CUSTOM_HEADERS`	Cabeceras adicionales en las peticiones a la API
`ANTHROPIC_MODEL`	Modelo por defecto
`ANTHROPIC_DEFAULT_HAIKU_MODEL` / `_OPUS_MODEL` / `_SONNET_MODEL`	Sobrescribe el modelo de cada gama
`CLAUDE_CODE_USE_BEDROCK` / `_VERTEX` / `_FOUNDRY`	Enruta a través de una nube de terceros
`AWS_BEARER_TOKEN_BEDROCK`	Bearer token de Bedrock
`CLAUDE_CODE_SUBAGENT_MODEL`	Modelo que usan los subagentes
`CLAUDE_CODE_MAX_OUTPUT_TOKENS`	Tope de tokens de salida (32.000 por defecto; máximo 64.000)
`MAX_THINKING_TOKENS`	Presupuesto de razonamiento (31.999 por defecto; `0` lo desactiva)
`CLAUDE_CODE_EFFORT_LEVEL`	`low` / `medium` / `high` (Opus 4.6+)
`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`	Porcentaje que dispara la compactación automática (~95 por defecto)
`BASH_DEFAULT_TIMEOUT_MS` / `BASH_MAX_TIMEOUT_MS` / `BASH_MAX_OUTPUT_LENGTH`	Límites de la herramienta Bash
`CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR`	Mantiene Bash en el directorio del proyecto
`CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD`	Carga también los `CLAUDE.md` de los directorios de `--add-dir`
`CLAUDE_CODE_DISABLE_AUTO_MEMORY`	Desactiva la memoria automática (ver Instrucciones de proyecto (CLAUDE.md))
`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`	Desactiva las tareas en segundo plano
`CLAUDE_CONFIG_DIR`	Cambia el directorio de configuración
`DISABLE_AUTOUPDATER`	Apaga las actualizaciones automáticas
`DISABLE_TELEMETRY` / `DISABLE_ERROR_REPORTING` / `DISABLE_COST_WARNINGS`	Interruptores de privacidad y experiencia de uso
`ENABLE_TOOL_SEARCH`	Búsqueda de herramientas (`auto` por defecto; se activa al 10% del contexto)
`MAX_MCP_OUTPUT_TOKENS`	Tope de salida de las herramientas MCP (25.000 por defecto)
`MCP_TIMEOUT` / `MCP_TOOL_TIMEOUT`	Timeouts de arranque de MCP y de llamada a herramienta
`MCP_OAUTH_CALLBACK_PORT`	Puerto del callback OAuth para la autenticación MCP
`SLASH_COMMAND_TOOL_CHAR_BUDGET`	Presupuesto para los metadatos de las skills (2% de la ventana de contexto; 16.000 caracteres de reserva)
`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`	Configuración del proxy
`CLAUDE_ENV_FILE`	Archivo que se carga antes de cada comando de Bash (se puede fijar con hooks SessionStart)
`CLAUDE_CODE_SHELL` / `CLAUDE_CODE_SHELL_PREFIX`	Elección del shell y su envoltura
`USE_BUILTIN_RIPGREP`	Usa el ripgrep incluido

Obsoletos: ANTHROPIC_SMALL_FAST_MODEL y includeCoAuthoredBy (un ajuste, sustituido por attribution).

Notas

Edita los ajustes de forma interactiva con /config, o fija un valor directamente desde el prompt: /config model=opus.
El antiguo subcomando claude config ya no aparece en la referencia actual del CLI — ? No se ha podido verificar; usa /config o edita los archivos JSON.
Flags como --settings y --setting-sources permiten superponer ajustes extra en cada sesión (ver Flags del CLI).

Última verificación: 2026-09-07

Fuentes oficiales:

Las herramientas de IA para programar evolucionan rápido. Si encuentras información desactualizada, abre un issue o un pull request.