Configuración de Claude Code

​

Á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. Cuando Claude Code crea .claude/settings.local.json, configura git para ignorar el archivo. Si crea el archivo usted mismo, agréguelo a su gitignore manualmente. Debido a que este archivo es suyo en lugar del repositorio, sus reglas de permiso allow entran en vigor sin el paso de confianza del espacio de trabajo que requieren las reglas de permiso allow de .claude/settings.json. Si el repositorio suministra el archivo, por ejemplo al confirmarlo, la confianza del espacio de trabajo aún se aplica.
• 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 remotamente al iniciar sesión, ya sea desde los servidores de Anthropic a través de la consola de administración de claude.ai o desde una puerta de aplicaciones Claude autohospedada. 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. Las claves de nivel superior del plist reflejan 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"
  ]
}

​

Cuándo entran en vigor las ediciones

• model: use /model para cambiar en mitad de sesión
• outputStyle: parte del indicador del sistema, que se reconstruye en /clear o reinicio

​

Entradas inválidas en configuraciones administradas

• Las sesiones interactivas muestran un diálogo al inicio que enumera las entradas inválidas.
• Las ejecuciones sin interfaz con -p imprimen un resumen en stderr.
• claude doctor enumera cada entrada inválida con su fuente y campo.

​

Configuraciones disponibles

​

Ajustes 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 (una regla de denegación Read también bloquea la herramienta Edit en las rutas coincidentes), 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

Co-Authored-By: Claude Sonnet 5 <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')
# Replace your-repo-file-index with your own file search command
your-repo-file-index --query "$query" | head -20

​

Insignias de enlace de pie de página

{
  "footerLinksRegexes": [
    {
      "type": "regex",
      "pattern": "\\b(?<key>PROJ-\\d+)\\b",
      "url": "https://issues.example.com/browse/{key}",
      "label": "{key}"
    }
  ]
}

​

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, solo se usa una fuente y las otras se ignoran en lugar de fusionarse. Precedencia, de mayor a menor:
     • Salida de policyHelper: cuando se configura, esta es la única fuente administrada utilizada
     • Remota (configuraciones administradas por servidor de claude.ai o políticas entregadas por puerta de aplicaciones Claude)
     • Políticas de MDM/nivel de SO
     • Basada en archivos (managed-settings.d/*.json y managed-settings.json, fusionadas juntas)
     • Registro HKCU (solo Windows)
   • Algunas claves son excepciones, honradas cuando cualquier fuente administrada controlada por administrador las establece en lugar de solo la fuente ganadora. La fuente de registro HKCU escribible por el usuario se excluye. Las claves de excepción son:
     • las claves de bloqueo de sandbox sandbox.network.allowManagedDomainsOnly y sandbox.filesystem.allowManagedReadPathsOnly, con sus listas blancas asociadas
     • allowAllClaudeAiMcps
     • las rutas binarias de sandbox sandbox.bwrapPath y sandbox.socatPath
     • forceRemoteSettingsRefresh
   • Los hosts de incrustación como Claude Desktop pueden suministrar política a través de la opción SDK managedSettings. De forma predeterminada, esto se ignora cuando está presente cualquier fuente administrada implementada por administrador: configuraciones administradas por servidor, una política de MDM o nivel de SO, o un archivo de configuración administrado. El fallback de registro HKCU escribible por el usuario no cuenta como una fuente administrada implementada por administrador. Los administradores pueden optar por establecer parentSettingsBehavior en "merge". Los valores del incrustador se filtran para que puedan restringir la política administrada pero no flexibilizarla.
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, con dos excepciones descritas en la Nota de fusión de matriz

​

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 compartibles con su equipo

​

Configuración de plugins

​

Ajustes 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, ignoradas por git cuando Claude Code las crea
• 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
  }
}

​

pluginConfigs

{
  "pluginConfigs": {
    "deployer@acme-tools": {
      "options": {
        "api_endpoint": "https://api.example.com"
      }
    }
  }
}

​

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 y sistema de archivos, por lo que 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, por lo que los usuarios pueden agregar cualquier marketplace
• Matriz vacía []: bloqueo completo, por lo que 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

​

strictPluginOnlyCustomization

{
  "strictPluginOnlyCustomization": ["skills", "hooks"]
}

​

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