Configuración de Claude Code

​

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 tu directorio de proyecto:
  • .claude/settings.json para configuraciones que se verifican en el control de código fuente y se comparten con tu 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.
• Para implementaciones empresariales de Claude Code, también admitimos configuraciones de política administrada empresarial. Estas tienen precedencia sobre la configuración 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
• Las implementaciones empresariales también pueden configurar servidores MCP administrados que anulan los servidores configurados por el usuario. Consulta Configuración empresarial de MCP:
  • macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
  • Linux y WSL: /etc/claude-code/managed-mcp.json
  • Windows: C:\ProgramData\ClaudeCode\managed-mcp.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

​

Configuración de permisos

​

Configuración de sandbox

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

• Las reglas de denegación de Read bloquean lecturas de archivos en sandbox
• Las reglas de permiso de Edit permiten escrituras de archivos (además de los predeterminados, por ejemplo, el directorio de trabajo actual)
• Las reglas de denegación de Edit bloquean escrituras dentro de rutas permitidas

• Las reglas de permiso de WebFetch permiten dominios de red
• Las reglas de denegación de WebFetch bloquean dominios de red

​

Precedencia de configuración

1. Políticas administradas empresariales (managed-settings.json)
   • Implementadas por TI/DevOps
   • No se pueden anular
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 con 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 iniciar
• Archivos de configuración (JSON): Configuran permisos, variables de entorno y comportamiento de herramientas
• Comandos de barra: Comandos personalizados que se pueden invocar durante una sesión con /command-name
• 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 indicador del sistema

​

Exclusión de archivos sensibles

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

​

Configuración de subagentos

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

​

Configuración de complementos

​

Configuración de complementos

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

​

enabledPlugins

• Configuración de usuario (~/.claude/settings.json): Preferencias personales de complementos
• Configuración de proyecto (.claude/settings.json): Complementos 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 complementos de ese mercado
3. Los usuarios pueden omitir mercados o complementos no deseados (almacenados en configuración de usuario)
4. La instalación respeta límites de confianza y requiere consentimiento explícito

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "company-org/claude-plugins"
      }
    },
    "security-plugins": {
      "source": {
        "source": "git",
        "url": "https://git.company.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)

​

Gestión de complementos

• Explora complementos disponibles de mercados
• Instala/desinstala complementos
• Habilita/deshabilita complementos
• Ver detalles de complementos (comandos, agentes, hooks proporcionados)
• Agregar/eliminar mercados

​

Variables de entorno

​

Herramientas disponibles para Claude

​

Extensión de herramientas con hooks

​

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 de configuración comunes