Configuración de Claude Code

​

Alcances de configuración

​

Alcances disponibles

​

Cuándo usar cada alcance

• Políticas de seguridad que deben aplicarse en toda la organización
• Requisitos de cumplimiento que no se pueden anular
• Configuraciones estandarizadas implementadas por TI/DevOps

• Preferencias personales que desea en todas partes (temas, configuración del editor)
• Herramientas y plugins que utiliza en todos los proyectos
• Claves API y autenticación (almacenadas de forma segura)

• Configuraciones compartidas por el equipo (permisos, hooks, MCP servers)
• Plugins que todo el equipo debe tener
• Estandarización de herramientas entre colaboradores

• Anulaciones personales para un proyecto específico
• Configuraciones de prueba antes de compartir con el equipo
• Configuraciones específicas de la máquina que no funcionarán para otros

​

Cómo interactúan los alcances

1. Managed (más alto) - no puede ser anulado por nada
2. Argumentos de línea de comandos - anulaciones de sesión temporal
3. Local - anula configuraciones de proyecto y usuario
4. Project - anula configuraciones de usuario
5. User (más bajo) - se aplica cuando nada más especifica la configuración

​

Qué usa alcances

​

Archivos de configuración

• Configuración de usuario se define en ~/.claude/settings.json y se aplica a todos los proyectos.
• Configuración de proyecto se guarda en su directorio de proyecto:
  • .claude/settings.json para configuraciones que se verifican en el control de código fuente y se comparten con su equipo
  • .claude/settings.local.json para configuraciones que no se verifican, útil para preferencias personales y experimentación. Claude Code configurará git para ignorar .claude/settings.local.json cuando se cree.
• Configuración administrada: Para organizaciones que necesitan control centralizado, Claude Code admite archivos managed-settings.json y managed-mcp.json que se pueden implementar en directorios del sistema:
  • macOS: /Library/Application Support/ClaudeCode/
  • Linux y WSL: /etc/claude-code/
  • Windows: C:\Program Files\ClaudeCode\
  Estas son rutas de todo el sistema (no directorios de inicio de usuario como ~/Library/...) que requieren privilegios de administrador. Están diseñadas para ser implementadas por administradores de TI.
  Consulte Configuración administrada y Configuración MCP administrada para obtener detalles.
  Las implementaciones administradas también pueden restringir adiciones del mercado de plugins usando strictKnownMarketplaces. Para obtener más información, consulte Restricciones de mercado administradas.
• Otra configuración se almacena en ~/.claude.json. Este archivo contiene sus preferencias (tema, configuración de notificaciones, modo de editor), sesión OAuth, configuraciones de MCP server para alcances de usuario y local, estado por proyecto (herramientas permitidas, configuración de confianza) y varios cachés. Los MCP servers con alcance de proyecto se almacenan por separado en .mcp.json.

{
  "$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": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  },
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs",
    "New security policy in effect"
  ]
}

​

Configuraciones disponibles

​

Configuración de permisos

​

Sintaxis de regla de permiso

​

Configuración de sandbox

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  },
  "permissions": {
    "deny": [
      "Read(.envrc)",
      "Read(~/.aws/**)"
    ]
  }
}

• Use reglas de denegación Read para bloquear a Claude de leer archivos o directorios específicos
• Use reglas de permiso Edit para permitir que Claude escriba en directorios más allá del directorio de trabajo actual
• Use reglas de denegación Edit para bloquear escrituras en rutas específicas
• Use reglas de permiso/denegación WebFetch para controlar qué dominios de red puede acceder Claude

​

Configuración de atribución

• Los commits usan git trailers (como Co-Authored-By) de forma predeterminada, que se pueden personalizar o deshabilitar
• Las descripciones de solicitudes de extracción son texto sin formato

🤖 Generated with [Claude Code](https://claude.com/claude-code)

   Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <[email protected]>",
    "pr": ""
  }
}

​

Configuración de sugerencia de archivo

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

{"query": "src/comp"}

src/components/Button.tsx
src/components/Modal.tsx
src/components/Form.tsx

#!/bin/bash
query=$(cat | jq -r '.query')
your-repo-file-index --query "$query" | head -20

​

Configuración de hooks

• Se cargan hooks administrados y hooks SDK
• Se bloquean hooks de usuario, proyecto y plugin

{
  "allowManagedHooksOnly": true
}

​

Precedencia de configuración

1. Configuración administrada (managed-settings.json)
   • Políticas implementadas por TI/DevOps en directorios del sistema
   • No pueden ser anuladas por configuraciones de usuario o proyecto
2. Argumentos de línea de comandos
   • Anulaciones temporales para una sesión específica
3. Configuración de proyecto local (.claude/settings.local.json)
   • Configuraciones personales específicas del proyecto
4. Configuración de proyecto compartida (.claude/settings.json)
   • Configuraciones de proyecto compartidas por el equipo en control de código fuente
5. Configuración de usuario (~/.claude/settings.json)
   • Configuraciones globales personales

​

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
• Skills: Mensajes personalizados que se pueden invocar con /skill-name o cargar automáticamente por Claude
• MCP servers: Extienden Claude Code con herramientas e integraciones adicionales
• Precedencia: Las configuraciones de nivel superior (Managed) anulan las de nivel inferior (User/Project)
• Herencia: Las configuraciones se fusionan, con configuraciones más específicas agregando o anulando las más amplias

​

Mensaje del sistema

​

Exclusión de archivos sensibles

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

​

Configuración de subagent

• Subagents de usuario: ~/.claude/agents/ - Disponibles en todos sus proyectos
• Subagents de proyecto: .claude/agents/ - Específicos de su proyecto y se pueden compartir con su equipo

​

Configuración de plugins

​

Configuración de plugins

{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "deployer@acme-tools": true,
    "analyzer@security-plugins": false
  },
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": "github",
      "repo": "acme-corp/claude-plugins"
    }
  }
}

​

enabledPlugins

• Configuración de usuario (~/.claude/settings.json): Preferencias personales de plugins
• Configuración de proyecto (.claude/settings.json): Plugins específicos del proyecto compartidos con el equipo
• Configuración local (.claude/settings.local.json): Anulaciones por máquina (no confirmadas)

{
  "enabledPlugins": {
    "code-formatter@team-tools": true,
    "deployment-tools@team-tools": true,
    "experimental-features@personal": false
  }
}

​

extraKnownMarketplaces

1. Se solicita a los miembros del equipo que instalen el mercado cuando confían en la carpeta
2. Luego se solicita a los miembros del equipo que instalen plugins de ese mercado
3. Los usuarios pueden omitir mercados o plugins no deseados (almacenados en configuración de usuario)
4. La instalación respeta límites de confianza y requiere consentimiento explícito

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    },
    "security-plugins": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/security/plugins.git"
      }
    }
  }
}

• github: Repositorio de GitHub (usa repo)
• git: Cualquier URL de git (usa url)
• directory: Ruta del sistema de archivos local (usa path, solo para desarrollo)
• hostPattern: Patrón regex para coincidir con hosts de mercado (usa hostPattern)

​

strictKnownMarketplaces

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux y WSL: /etc/claude-code/managed-settings.json
• Windows: C:\Program Files\ClaudeCode\managed-settings.json

• Solo disponible en configuración administrada (managed-settings.json)
• No puede ser anulada por configuraciones de usuario o proyecto (máxima precedencia)
• Se aplica antes de operaciones de red/sistema de archivos (las fuentes bloqueadas nunca se ejecutan)
• Usa coincidencia exacta para especificaciones de fuente (incluyendo ref, path para fuentes git), excepto hostPattern, que usa coincidencia regex

• undefined (predeterminado): Sin restricciones - los usuarios pueden agregar cualquier mercado
• Matriz vacía []: Bloqueo completo - los usuarios no pueden agregar nuevos mercados
• Lista de fuentes: Los usuarios solo pueden agregar mercados que coincidan exactamente

1. Repositorios de GitHub:

{ "source": "github", "repo": "acme-corp/approved-plugins" }
{ "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }

2. Repositorios de Git:

{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }
{ "source": "git", "url": "https://bitbucket.org/acme-corp/plugins.git", "ref": "production" }
{ "source": "git", "url": "ssh://[email protected]/plugins.git", "ref": "v3.1", "path": "approved" }

3. Mercados basados en URL:

{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }
{ "source": "url", "url": "https://cdn.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }

4. Paquetes NPM:

{ "source": "npm", "package": "@acme-corp/claude-plugins" }
{ "source": "npm", "package": "@acme-corp/approved-marketplace" }

5. Rutas de archivo:

{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }
{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }

6. Rutas de directorio:

{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }
{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }

7. Coincidencia de patrón de host:

{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
{ "source": "hostPattern", "hostPattern": "^gitlab\\.internal\\.example\\.com$" }

• github: siempre coincide contra github.com
• git: extrae el nombre de host de la URL (admite formatos HTTPS y SSH)
• url: extrae el nombre de host de la URL
• npm, file, directory: no admitido para coincidencia de patrón de host

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    },
    {
      "source": "npm",
      "package": "@acme-corp/compliance-plugins"
    }
  ]
}

{
  "strictKnownMarketplaces": []
}

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

• El repo o url debe coincidir exactamente
• El campo ref debe coincidir exactamente (o ambos ser indefinidos)
• El campo path debe coincidir exactamente (o ambos ser indefinidos)

// Estas son fuentes DIFERENTES:
{ "source": "github", "repo": "acme-corp/plugins" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }

// Estas también son DIFERENTES:
{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }
{ "source": "github", "repo": "acme-corp/plugins" }

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ]
}

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}

• Las restricciones se verifican ANTES de cualquier solicitud de red u operación del sistema de archivos
• Cuando se bloquea, los usuarios ven mensajes de error claros indicando que la fuente está bloqueada por política administrada
• La restricción se aplica solo a agregar NUEVOS mercados; los mercados instalados previamente permanecen accesibles
• La configuración administrada tiene la máxima precedencia y no puede ser anulada

​

Gestión de plugins

• Examinar plugins disponibles de mercados
• Instalar/desinstalar plugins
• Habilitar/deshabilitar plugins
• Ver detalles de plugins (comandos, agentes, hooks proporcionados)
• Agregar/eliminar mercados

​

Variables de entorno

​

Herramientas disponibles para Claude

​

Comportamiento de herramienta Bash

• El directorio de trabajo persiste: Cuando Claude cambia el directorio de trabajo (por ejemplo, cd /path/to/dir), los comandos Bash posteriores se ejecutarán en ese directorio. Puede usar CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 para restablecer al directorio del proyecto después de cada comando.
• Las variables de entorno NO persisten: Las variables de entorno establecidas en un comando Bash (por ejemplo, export MY_VAR=value) no están disponibles en comandos Bash posteriores. Cada comando Bash se ejecuta en un entorno de shell fresco.

conda activate myenv
# o: source /path/to/venv/bin/activate
claude

export CLAUDE_ENV_FILE=/path/to/env-setup.sh
claude

conda activate myenv
# o: source /path/to/venv/bin/activate
# o: export MY_VAR=value

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup",
      "hooks": [{
        "type": "command",
        "command": "echo 'conda activate myenv' >> \"$CLAUDE_ENV_FILE\""
      }]
    }]
  }
}

​

Extensión de herramientas con hooks

​

Ver también

• Permisos: sistema de permisos, sintaxis de regla, patrones específicos de herramientas y políticas administradas
• Autenticación: configurar acceso de usuario a Claude Code
• Solución de problemas: soluciones para problemas de configuración comunes