Configuración de Claude Code

Claude Code ofrece una variedad de ajustes para configurar su comportamiento según tus necesidades. Puedes configurar Claude Code ejecutando claude config en tu terminal, o el comando /config cuando uses el REPL interactivo.

​

Jerarquía de configuración

El nuevo archivo settings.json es nuestro mecanismo oficial para configurar Claude Code a través de ajustes jerárquicos.

Los ajustes de usuario se definen en ~/.claude/settings.json y se aplican a todos los proyectos.

Los ajustes del proyecto se guardan en tu directorio de proyecto bajo .claude/settings.json para ajustes compartidos, y .claude/settings.local.json para ajustes locales del proyecto. Claude Code configurará git para ignorar .claude/settings.local.json cuando se cree.

Para implementaciones empresariales de Claude Code, también admitimos ajustes de políticas gestionadas por la empresa. Estos tienen prioridad sobre los ajustes de usuario y proyecto. Los administradores del sistema pueden implementar políticas en /Library/Application Support/ClaudeCode/policies.json en macOS y /etc/claude-code/policies.json en Linux y Windows a través de WSL.

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

​

Precedencia de ajustes

Los ajustes se aplican en orden de precedencia, con las fuentes posteriores anulando las fuentes anteriores:

• Ajustes de usuario
• Ajustes compartidos del proyecto
• Ajustes locales del proyecto
• Argumentos de línea de comandos
• Políticas empresariales

​

Opciones de configuración

Claude Code admite configuración global y a nivel de proyecto.

Para gestionar tus configuraciones, usa los siguientes comandos:

• Listar ajustes: claude config list
• Ver un ajuste: claude config get <key>
• Cambiar un ajuste: claude config set <key> <value>
• Agregar a un ajuste (para listas): claude config add <key> <value>
• Eliminar de un ajuste (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>:

​

Configuración del proyecto

Gestiona la configuración del proyecto con claude config set <key> <value> (sin la bandera -g):

Por ejemplo:

# Permitir que npm test se ejecute sin aprobación
claude config add allowedTools "Bash(npm test)"

# Permitir que npm test y cualquiera de sus subcomandos se ejecuten sin aprobación
claude config add allowedTools "Bash(npm test:*)"

# Instruir a Claude para ignorar node_modules
claude config add ignorePatterns node_modules
claude config add ignorePatterns "node_modules/**"

​

Permisos

Puedes gestionar los permisos de herramientas de Claude Code con /allowed-tools. Esta interfaz lista todas las reglas de permisos y el archivo settings.json del que provienen.

• Las reglas Allow permitirán que Claude Code use la herramienta especificada sin aprobación manual adicional.
• Las reglas Deny impedirán que Claude Code use la herramienta especificada. Las reglas Deny tienen prioridad sobre las reglas Allow.

Las reglas de permisos usan el formato: Tool(optional-specifier).

Por ejemplo, agregar WebFetch a la lista de reglas allow permitiría cualquier uso de la herramienta de búsqueda web sin requerir aprobación del usuario. Consulta la lista de herramientas disponibles para Claude (usa el nombre entre paréntesis cuando se proporcione).

Algunas herramientas usan el especificador opcional para controles de permisos más detallados. Por ejemplo, una regla allow con WebFetch(domain:example.com) permitiría búsquedas en example.com pero no en otras URLs.

Las reglas Bash pueden ser coincidencias exactas como Bash(npm run build), o coincidencias de prefijo cuando terminan con :* como Bash(npm run test:*)

Las reglas Read() y Edit() siguen la especificación gitignore. Los patrones se resuelven relativos al directorio que contiene .claude/settings.json. Para referenciar una ruta absoluta, usa //. Para una ruta relativa a tu directorio home, usa ~/. Por ejemplo Read(//tmp/build_cache) o Edit(~/.zshrc). Claude también hará un mejor esfuerzo para aplicar reglas Read y Edit a otras herramientas relacionadas con archivos como Grep, Glob y LS.

Los nombres de herramientas MCP siguen el formato: mcp__server_name__tool_name donde:

• server_name es el nombre del servidor MCP configurado en Claude Code
• tool_name es la herramienta específica proporcionada por ese servidor

Más ejemplos:

​

Opciones de permisos del auto-actualizador

Cuando Claude Code detecta que no tiene suficientes permisos para escribir en tu directorio de prefijo npm global (requerido para actualizaciones automáticas), verás una advertencia que apunta a esta página de documentación. Para soluciones detalladas a problemas del auto-actualizador, consulta la guía de solución de problemas.

​

Recomendado: Crear un nuevo prefijo npm escribible por el usuario

# Primero, guarda una lista de tus paquetes globales existentes para migración posterior
npm list -g --depth=0 > ~/npm-global-packages.txt

# Crea un directorio para tus paquetes globales
mkdir -p ~/.npm-global

# Configura npm para usar la nueva ruta de directorio
npm config set prefix ~/.npm-global

# Nota: Reemplaza ~/.bashrc con ~/.zshrc, ~/.profile, u otro archivo apropiado para tu shell
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# Aplica la nueva configuración PATH
source ~/.bashrc

# Ahora reinstala Claude Code en la nueva ubicación
npm install -g @anthropic-ai/claude-code

# Opcional: Reinstala tus paquetes globales anteriores en la nueva ubicación
# Mira ~/npm-global-packages.txt e instala los paquetes que quieras mantener
# npm install -g package1 package2 package3...

Por qué recomendamos esta opción:

• Evita modificar los permisos del directorio del sistema
• Crea una ubicación limpia y dedicada para tus paquetes npm globales
• Sigue las mejores prácticas de seguridad

Dado que Claude Code está en desarrollo activo, recomendamos configurar las actualizaciones automáticas usando la opción recomendada anterior.

​

Deshabilitar el auto-actualizador

Si prefieres deshabilitar el auto-actualizador en lugar de arreglar los permisos, puedes usar:

claude config set -g autoUpdaterStatus disabled

​

Optimiza tu configuración de terminal

Claude Code funciona mejor cuando tu terminal está correctamente configurada. Sigue estas pautas para optimizar tu experiencia.

Shells soportados:

• Bash
• Zsh
• Fish

​

Temas y apariencia

Claude no puede controlar el tema de tu terminal. Eso lo maneja tu aplicación de terminal. Puedes hacer coincidir el tema de Claude Code con tu terminal durante la configuración inicial o en cualquier momento a través del comando /config

​

Saltos de línea

Tienes varias opciones para ingresar saltos de línea en Claude Code:

• Escape rápido: Escribe \ seguido de Enter para crear una nueva línea
• Atajo de teclado: Presiona Option+Enter (Meta+Enter) con la configuración adecuada

Para configurar Option+Enter en tu terminal:

Para Mac Terminal.app:

1. Abre Configuración → Perfiles → Teclado
2. Marca “Usar Option como tecla Meta”

Para iTerm2 y terminal de VSCode:

1. Abre Configuración → Perfiles → Teclas
2. En General, establece la tecla Option izquierda/derecha en “Esc+”

Consejo para usuarios de iTerm2 y VSCode: Ejecuta /terminal-setup dentro de Claude Code para configurar automáticamente Shift+Enter como una alternativa más intuitiva.

​

Configuración de notificaciones

Nunca te pierdas cuando Claude complete una tarea con la configuración adecuada de notificaciones:

​

Notificaciones de campana de terminal

Habilita alertas sonoras cuando se completen las tareas:

claude config set --global preferredNotifChannel terminal_bell

Para usuarios de macOS: No olvides habilitar los permisos de notificación en Configuración del Sistema → Notificaciones → [Tu App de Terminal].

​

Notificaciones del sistema iTerm 2

Para alertas de iTerm 2 cuando se completen las tareas:

1. Abre Preferencias de iTerm 2
2. Navega a Perfiles → Terminal
3. Habilita “Silenciar campana” y “Enviar notificación cuando esté inactivo”
4. Establece tu retraso de notificación preferido

Ten en cuenta que estas notificaciones son específicas de iTerm 2 y no están disponibles en la Terminal predeterminada de macOS.

​

Manejo de entradas grandes

Cuando trabajes con código extenso o instrucciones largas:

• Evita el pegado directo: Claude Code puede tener dificultades con contenido pegado muy largo
• Usa flujos de trabajo basados en archivos: Escribe contenido en un archivo y pide a Claude que lo lea
• Ten en cuenta las limitaciones de VS Code: La terminal de VS Code es particularmente propensa a truncar pegados largos

​

Modo Vim

Claude Code admite un subconjunto de atajos de teclado de Vim que se pueden habilitar con /vim o configurar a través de /config.

El subconjunto admitido incluye:

• Cambio de modo: Esc (a NORMAL), i/I, a/A, o/O (a INSERT)
• Navegación: h/j/k/l, w/e/b, 0/$/^, gg/G
• Edición: x, dw/de/db/dd/D, cw/ce/cb/cc/C, . (repetir)

​

Variables de entorno

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