Configuración de Claude Code

Claude Code ofrece una variedad de configuraciones para configurar su comportamiento según tus necesidades. Puedes configurar Claude Code ejecutando el comando /config cuando uses el REPL interactivo.

​

Archivos de configuración

El archivo settings.json es nuestro mecanismo oficial para configurar Claude Code a través de configuraciones jerárquicas:

• Configuraciones de usuario se definen en ~/.claude/settings.json y se aplican a todos los proyectos.
• Configuraciones de proyecto se guardan en tu directorio de proyecto:
  • .claude/settings.json para configuraciones que se incluyen en el control de código fuente y se comparten con tu equipo
  • .claude/settings.local.json para configuraciones que no se incluyen, útiles para preferencias personales y experimentación. Claude Code configurará git para ignorar .claude/settings.local.json cuando se cree.
• Para implementaciones empresariales de Claude Code, también admitimos configuraciones de política gestionada empresarial. Estas tienen precedencia sobre las configuraciones de usuario y proyecto. Los administradores del sistema pueden implementar políticas en:
  • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
  • Linux y WSL: /etc/claude-code/managed-settings.json
  • Windows: C:\ProgramData\ClaudeCode\managed-settings.json

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

​

Configuraciones disponibles

settings.json admite varias opciones:

​

Configuraciones de permisos

​

Precedencia de configuraciones

Las configuraciones se aplican en orden de precedencia (de mayor a menor):

1. Políticas gestionadas empresariales (managed-settings.json)

   • Implementadas por IT/DevOps
   • No pueden ser anuladas

2. Argumentos de línea de comandos

   • Anulaciones temporales para una sesión específica

3. Configuraciones locales del proyecto (.claude/settings.local.json)

   • Configuraciones personales específicas del proyecto

4. Configuraciones compartidas del proyecto (.claude/settings.json)

   • Configuraciones del proyecto compartidas por el equipo en control de código fuente

5. Configuraciones de usuario (~/.claude/settings.json)

   • Configuraciones globales personales

Esta jerarquía asegura que las políticas de seguridad empresariales siempre se apliquen mientras permite que los equipos e individuos personalicen su experiencia.

​

Puntos clave sobre el sistema de configuración

• Archivos de memoria (CLAUDE.md): Contienen instrucciones y contexto que Claude carga al inicio
• Archivos de configuración (JSON): Configuran permisos, variables de entorno y comportamiento de herramientas
• Comandos slash: Comandos personalizados que pueden invocarse durante una sesión con /nombre-comando
• Servidores MCP: Extienden Claude Code con herramientas e integraciones adicionales
• Precedencia: Las configuraciones de nivel superior (Empresarial) anulan las de nivel inferior (Usuario/Proyecto)
• Herencia: Las configuraciones se fusionan, con configuraciones más específicas agregando o anulando las más amplias

​

Disponibilidad del prompt del sistema

​

Excluyendo archivos sensibles

Para evitar que Claude Code acceda a archivos que contienen información sensible (por ejemplo, claves de API, secretos, archivos de entorno), usa la configuración permissions.deny en tu archivo .claude/settings.json:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Read(./build)"
    ]
  }
}

Esto reemplaza la configuración obsoleta ignorePatterns. Los archivos que coincidan con estos patrones serán completamente invisibles para Claude Code, evitando cualquier exposición accidental de datos sensibles.

​

Configuración de subagentes

Claude Code admite subagentes de IA personalizados que pueden configurarse tanto a nivel de usuario como de proyecto. Estos subagentes se almacenan como archivos Markdown con frontmatter YAML:

• Subagentes de usuario: ~/.claude/agents/ - Disponibles en todos tus proyectos
• Subagentes de proyecto: .claude/agents/ - Específicos de tu proyecto y pueden compartirse con tu equipo

Los archivos de subagentes definen asistentes de IA especializados con prompts personalizados y permisos de herramientas. Aprende más sobre crear y usar subagentes en la documentación de subagentes.

​

Variables de entorno

Claude Code admite las siguientes variables de entorno para controlar su comportamiento:

​

Opciones de configuración

Para gestionar tus configuraciones, usa los siguientes comandos:

• Listar configuraciones: claude config list
• Ver una configuración: claude config get <key>
• Cambiar una configuración: claude config set <key> <value>
• Agregar a una configuración (para listas): claude config add <key> <value>
• Remover de una configuración (para listas): claude config remove <key> <value>

Por defecto config cambia tu configuración de proyecto. Para gestionar tu configuración global, usa la bandera --global (o -g).

​

Configuración global

Para establecer una configuración global, usa claude config set -g <key> <value>:

​

Herramientas disponibles para Claude

Claude Code tiene acceso a un conjunto de herramientas poderosas que le ayudan a entender y modificar tu base de código:

Las reglas de permisos pueden configurarse usando /allowed-tools o en configuraciones de permisos. Ver también Reglas de permisos específicas de herramientas.

​

Extendiendo herramientas con hooks

Puedes ejecutar comandos personalizados antes o después de que cualquier herramienta se ejecute usando hooks de Claude Code.

Por ejemplo, podrías ejecutar automáticamente un formateador de Python después de que Claude modifique arch ivos de Python, o evitar modificaciones a archivos de configuración de producción bloqueando operaciones de Write a ciertas rutas.

​

Ver también

• Gestión de Identidad y Acceso - Aprende sobre el sistema de permisos de Claude Code
• IAM y control de acceso - Gestión de políticas empresariales
• Solución de problemas - Soluciones para problemas comunes de configuración