Configuración de Claude Code

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

Ámbitos de configuración

​

Ámbitos disponibles

​

Cuándo usar cada ámbito

• 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
• Estandarizar herramientas entre colaboradores

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

​

Cómo interactúan los ámbitos

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 ámbitos

​

Archivos de configuración

• Configuraciones de usuario se definen en ~/.claude/settings.json y se aplican a todos los proyectos.
• Configuraciones de proyecto se guardan 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.
• Configuraciones administradas: Para organizaciones que necesitan control centralizado, Claude Code admite múltiples mecanismos de entrega para configuraciones administradas. Todos utilizan el mismo formato JSON y no pueden ser anulados por configuraciones de usuario o proyecto:
  • Configuraciones administradas por servidor: entregadas desde los servidores de Anthropic a través de la consola de administración de Claude.ai. Consulte configuraciones administradas por servidor.
  • Políticas de MDM/nivel de SO: entregadas a través de administración de dispositivos nativa en macOS y Windows:
    • macOS: dominio de preferencias administradas com.anthropic.claudecode. El plist de nivel superior refleja las claves de managed-settings.json, con configuraciones anidadas como diccionarios y matrices como matrices de plist. Implemente a través de perfiles de configuración en Jamf, Iru (Kandji) u herramientas MDM similares.
    • Windows: clave de registro HKLM\SOFTWARE\Policies\ClaudeCode con un valor Settings (REG_SZ o REG_EXPAND_SZ) que contiene JSON (implementado a través de Política de grupo o Intune)
    • Windows (nivel de usuario): HKCU\SOFTWARE\Policies\ClaudeCode (prioridad de política más baja, solo se usa cuando no existe una fuente a nivel de administrador)
  • Basado en archivos: managed-settings.json y managed-mcp.json implementados en directorios del sistema:
    • macOS: /Library/Application Support/ClaudeCode/
    • Linux y WSL: /etc/claude-code/
    • Windows: C:\Program Files\ClaudeCode\
    La ruta heredada de Windows C:\ProgramData\ClaudeCode\managed-settings.json ya no se admite a partir de v2.1.75. Los administradores que implementaron configuraciones en esa ubicación deben migrar archivos a C:\Program Files\ClaudeCode\managed-settings.json.
    Las configuraciones administradas basadas en archivos también admiten un directorio de entrega en managed-settings.d/ en el mismo directorio del sistema junto a managed-settings.json. Esto permite que equipos separados implementen fragmentos de política independientes sin coordinar ediciones a un único archivo. Siguiendo la convención de systemd, managed-settings.json se fusiona primero como base, luego todos los archivos *.json en el directorio de entrega se ordenan alfabéticamente y se fusionan encima. Los archivos posteriores anulan los anteriores para valores escalares; las matrices se concatenan y se deduplicán; los objetos se fusionan profundamente. Se ignoran los archivos ocultos que comienzan con .. Use prefijos numéricos para controlar el orden de fusión, por ejemplo 10-telemetry.json y 20-security.json.
  Consulte configuraciones administradas y Configuración de MCP administrada para obtener detalles. Este repositorio incluye plantillas de implementación de inicio para Jamf, Iru (Kandji), Intune y Política de grupo. Use estas como puntos de partida y ajústelas para que se adapten a sus necesidades.
  Las implementaciones administradas también pueden restringir adiciones de marketplace de plugins usando strictKnownMarketplaces. Para obtener más información, consulte Restricciones de marketplace administradas.
• Otra configuración se almacena en ~/.claude.json. Este archivo contiene su sesión OAuth, configuraciones de MCP server para ámbitos de usuario y local, estado por proyecto (herramientas permitidas, configuración de confianza) y varios cachés. Los MCP servers con ámbito 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 config global

​

Configuración de worktrees

​

Configuración de permisos

​

Sintaxis de regla de permiso

​

Configuración de sandbox

​

Prefijos de ruta de sandbox

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "deniedDomains": ["uploads.github.com"],
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  }
}

• Configuraciones sandbox.filesystem (mostradas arriba): Controlan rutas en el límite del sandbox a nivel de SO. Estas restricciones se aplican a todos los comandos de subproceso (por ejemplo, kubectl, terraform, npm), no solo a las herramientas de archivo de Claude.
• Reglas de permiso: Use reglas de permiso Edit permitidas/denegadas para controlar el acceso a la herramienta de archivo de Claude, reglas de denegación Read para bloquear lecturas, y reglas de permiso WebFetch permitidas/denegadas para controlar dominios de red. Las rutas de estas reglas también se fusionan en la configuración del sandbox.

​

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.6 <noreply@anthropic.com>

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

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
    "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 cargan hooks de plugins forzadamente habilitados en la configuración administrada enabledPlugins. Esto permite que los administradores distribuyan hooks verificados a través de un marketplace de organización mientras bloquean todo lo demás. La confianza se otorga por ID completo de plugin@marketplace, por lo que un plugin con el mismo nombre de un marketplace diferente permanece bloqueado
• Se bloquean hooks de usuario, proyecto y todos los demás plugins

{
  "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
}

{
  "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
}

​

Calcular configuraciones administradas con un asistente de política

{
  "managedSettings": {
    "permissions": { "deny": ["Read(//etc/secrets/**)"] }
  },
  "claudeMd": "# Organization context\n...",
  "appendSystemPrompt": "Always cite the internal style guide."
}

​

Precedencia de configuración

1. Configuraciones administradas (administradas por servidor, políticas de MDM/nivel de SO, o configuraciones administradas)
   • Políticas implementadas por TI a través de entrega de servidor, perfiles de configuración MDM, políticas de registro o archivos de configuración administrados
   • No pueden ser anuladas por ningún otro nivel, incluyendo argumentos de línea de comandos
   • Dentro del nivel administrado, la precedencia es: administrado por servidor > políticas de MDM/nivel de SO > archivo basado (managed-settings.d/*.json + managed-settings.json) > registro HKCU (solo Windows). Solo se usa una fuente administrada; las fuentes no se fusionan entre niveles. Dentro del nivel basado en archivos, los archivos de entrega y el archivo base se fusionan juntos.
2. Argumentos de línea de comandos
   • Anulaciones temporales para una sesión específica. JSON pasado a través de --settings <file-or-json> se fusiona con configuraciones basadas en archivos usando las mismas reglas que las otras capas: una clave establecida aquí anula la misma clave en configuraciones locales, de proyecto o de usuario, y omitir una clave deja el valor de capa inferior en su lugar
3. Configuraciones de proyecto local (.claude/settings.local.json)
   • Configuraciones personales específicas del proyecto
4. Configuraciones de proyecto compartidas (.claude/settings.json)
   • Configuraciones de proyecto compartidas por el equipo en control de código fuente
5. Configuraciones de usuario (~/.claude/settings.json)
   • Configuraciones personales globales

​

Verificar configuraciones activas

​

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): Configurar permisos, variables de entorno y comportamiento de herramientas
• Skills: Indicaciones personalizadas que se pueden invocar con /skill-name o cargar automáticamente por Claude
• MCP servers: Extender 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 entre ámbitos; los valores escalares de ámbitos de mayor prioridad anulan, y las matrices se concatenan

​

Indicador del sistema

​

Excluyendo archivos sensibles

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

​

Configuración de subagents

• 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": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  }
}

​

enabledPlugins

• Configuraciones de usuario (~/.claude/settings.json): Preferencias personales de plugins
• Configuraciones de proyecto (.claude/settings.json): Plugins específicos del proyecto compartidos con el equipo
• Configuraciones locales (.claude/settings.local.json): Anulaciones por máquina (no confirmadas)
• Configuraciones administradas (managed-settings.json): Anulaciones de política a nivel de organización que bloquean la instalación en todos los ámbitos y ocultan el plugin del marketplace

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

​

extraKnownMarketplaces

1. Los miembros del equipo reciben un aviso para instalar el marketplace cuando confían en la carpeta
2. Los miembros del equipo reciben un aviso para instalar plugins de ese marketplace
3. Los usuarios pueden omitir marketplaces o plugins no deseados (almacenados en configuraciones 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 marketplace (usa hostPattern)
• settings: marketplace en línea declarado directamente en settings.json sin un repositorio alojado separado (usa name y plugins)

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "settings",
        "name": "team-tools",
        "plugins": [
          {
            "name": "code-formatter",
            "source": {
              "source": "github",
              "repo": "acme-corp/code-formatter"
            }
          }
        ]
      }
    }
  }
}

​

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 configuraciones administradas (managed-settings.json)
• No puede ser anulada por configuraciones de usuario o proyecto (precedencia más alta)
• 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 de git), excepto hostPattern y pathPattern, que usan coincidencia regex

• undefined (predeterminado): Sin restricciones - los usuarios pueden agregar cualquier marketplace
• Matriz vacía []: Bloqueo completo - los usuarios no pueden agregar nuevos marketplaces
• Lista de fuentes: Los usuarios solo pueden agregar marketplaces 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://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }

3. Marketplaces 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 nombre de host de la URL (admite formatos HTTPS y SSH)
• url: extrae nombre de host de la URL
• npm, file, directory: no admitido para coincidencia de patrón de host

8. Coincidencia de patrón de ruta:

{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }
{ "source": "pathPattern", "pathPattern": ".*" }

{
  "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 estar sin definir)
• El campo path debe coincidir exactamente (o ambos estar sin definir)

// 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" }
    }
  }
}

{
  "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 en agregar marketplace y en instalar, actualizar, actualizar y auto-actualizar plugins. Un marketplace agregado antes de que se estableciera la política no puede usarse para instalar o actualizar plugins una vez que su fuente ya no coincida con la lista blanca
• Las configuraciones administradas tienen la precedencia más alta y no pueden ser anuladas

​

Gestionar plugins

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

​

Variables de entorno

​

Herramientas disponibles para Claude

​

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
• Depurar su configuración: diagnosticar por qué una configuración, hook o servidor MCP no está surtiendo efecto
• Solucionar problemas de instalación e inicio de sesión: problemas de instalación, autenticación y plataforma