Configuración con settings.json

Sistema de configuración por capas

Claude Code gestiona su configuración a través de archivos settings.json organizados en cuatro niveles de alcance. Cada nivel tiene un propósito distinto y una prioridad diferente, lo que permite combinar políticas de la organización con preferencias personales y ajustes específicos del proyecto.

| Alcance | Ubicación | Propósito | Compartido | |---|---|---|---| | Managed | Directorio del sistema operativo | Políticas de la organización, gestionadas por IT | Toda la organización | | Usuario | ~/.claude/settings.json | Preferencias personales para todos los proyectos | Solo contigo | | Proyecto | .claude/settings.json | Configuración del equipo (se sube al repositorio) | Con el equipo via Git | | Local | .claude/settings.local.json | Ajustes personales para un proyecto concreto | Solo contigo |

La prioridad se aplica de menor a mayor: usuario, proyecto, local, argumentos de línea de comandos. Las configuraciones managed tienen la prioridad más alta y no pueden ser sobrescritas por ningún otro nivel.

Cuando el mismo ajuste se define en varios niveles, el más específico prevalece. Por ejemplo, si los settings de usuario permiten Bash(npm run *) pero los del proyecto lo prohíben, la configuración del proyecto tiene prioridad y el comando queda bloqueado.

Los arrays se fusionan entre niveles: si los settings managed definen un path de escritura permitido y los de usuario añaden otro, ambos paths quedan activos en la configuración final.

flowchart TD
    A["Managed<br>(prioridad máxima)"] --> B["Argumentos CLI"]
    B --> C["Local<br>(.claude/settings.local.json)"]
    C --> D["Proyecto<br>(.claude/settings.json)"]
    D --> E["Usuario<br>(~/.claude/settings.json)"]
    E --> F["Configuración final"]

Estructura de un archivo settings.json

Un archivo settings.json típico contiene varias secciones que controlan aspectos distintos del comportamiento de Claude Code:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "model": "claude-sonnet-4-6"
}

La propiedad $schema apunta al esquema JSON oficial de Claude Code. Añadirla al archivo habilita autocompletado y validación en editores como VS Code o Cursor.

Configurar permisos

El bloque permissions en settings.json controla qué herramientas puede usar Claude Code. Tres listas definen el comportamiento:

• allow: herramientas que Claude puede ejecutar sin pedir aprobación.
• ask: herramientas que requieren confirmación del usuario antes de ejecutarse.
• deny: herramientas bloqueadas por completo, Claude no puede usarlas bajo ninguna circunstancia.

Las reglas se evalúan en orden (deny, ask, allow). La primera que coincida con la acción gana. Un ejemplo mínimo sería permitir ciertos comandos y bloquear la lectura de archivos sensibles:

{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git log *)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)"]
  }
}

Modo de permisos por defecto

La propiedad defaultMode dentro de permissions establece el modo de aprobación con el que arranca cada sesión:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

Los modos disponibles son normal (pide aprobación para cada acción de escritura), plan (exploración libre, aprobación solo para modificaciones) y acceptEdits (acepta ediciones automáticamente).

Variables de entorno

El bloque env define variables de entorno que se aplican a cada sesión de Claude Code:

{
  "env": {
    "NODE_ENV": "development",
    "DATABASE_URL": "postgresql://localhost:5432/mydb",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

Las variables definidas aquí están disponibles en todos los comandos Bash que ejecute Claude durante la sesión. Es una forma práctica de configurar el entorno de desarrollo sin depender de archivos .env externos.

Selección de modelo por defecto

La propiedad model establece el modelo de lenguaje que Claude Code utilizará por defecto en todas las sesiones:

{
  "model": "claude-sonnet-4-6"
}

Se puede complementar con availableModels para restringir los modelos que los usuarios pueden seleccionar mediante /model, --model o la interfaz de configuración:

{
  "model": "claude-sonnet-4-6",
  "availableModels": ["sonnet", "opus"]
}

Ajustes adicionales

El archivo settings.json admite una variedad de opciones que abarcan desde la presentación visual hasta la gestión de sesiones.

Idioma de respuesta

La propiedad language configura el idioma en el que Claude responde por defecto:

{
  "language": "spanish"
}

Atribución en commits y pull requests

Claude Code añade una línea de atribución en los commits y pull requests que genera. La propiedad attribution permite personalizar o desactivar esta atribución:

{
  "attribution": {
    "commit": "Generado con Claude Code",
    "pr": ""
  }
}

Asignar una cadena vacía a commit o pr oculta la atribución correspondiente.

Limpieza de sesiones

La propiedad cleanupPeriodDays controla cuántos días se conservan las sesiones inactivas antes de eliminarlas automáticamente al inicio:

{
  "cleanupPeriodDays": 15
}

Sandbox

Claude Code incluye un sistema de sandbox que aísla los comandos Bash del sistema de archivos y la red. La configuración se define dentro del bloque sandbox:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker", "git"],
    "filesystem": {
      "allowWrite": ["//tmp/build"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

Cuando el sandbox está activo, Claude puede ejecutar comandos Bash sin solicitar aprobación (si autoAllowBashIfSandboxed es true), ya que las acciones están confinadas dentro de los límites definidos.

Acceder a la configuración

Existen tres formas de acceder y modificar la configuración:

• /config dentro de una sesión interactiva: abre una interfaz visual con pestañas para ver el estado y modificar opciones.

• /status: muestra qué fuentes de configuración están activas y de dónde provienen, incluyendo cada capa (managed, usuario, proyecto) con su origen.

• Edición directa de los archivos JSON: los archivos se pueden abrir en cualquier editor de texto. Claude Code crea copias de seguridad automáticas con marca temporal, conservando las cinco más recientes.

Cuándo usar cada nivel

La elección del nivel de configuración depende del alcance y la audiencia del ajuste:

• Usuario (~/.claude/settings.json): preferencias que aplican a todos tus proyectos. Claves API, tema visual, plugins personales, modelo favorito.

• Proyecto (.claude/settings.json): configuración compartida con el equipo. Permisos estándar, hooks del proyecto, servidores MCP del equipo, plugins que todos deben tener.

• Local (.claude/settings.local.json): ajustes que solo funcionan en tu máquina o que estás probando antes de compartir. Configuraciones de entorno local, overrides temporales.

• Managed: políticas de la organización que deben aplicarse obligatoriamente. Requisitos de compliance, políticas de seguridad, restricciones de herramientas.

El archivo .claude/settings.json se sube al control de versiones y lo comparte todo el equipo. El archivo .claude/settings.local.json se añade automáticamente al .gitignore para mantenerlo privado.