Configuración de Permisos de Claude Code

Claude Code utiliza un sistema de permisos jerárquico para equilibrar funcionalidad y seguridad, compatible con reglas de permisos de grano fino, modos de permisos y políticas de sandbox para controlar las operaciones a las que Claude puede acceder y ejecutar. Configurar los permisos adecuadamente no solo permite que la IA complete tareas de manera eficiente, sino que también evita que operaciones accidentales dañen el código o filtren archivos confidenciales.

A partir de Claude Code v1.1.1, se recomienda utilizar el nuevo método de configuración de permisos. El antiguotoolsLa configuración booleana aún es compatible, pero se recomienda migrar a la nueva sintaxis de reglas de permisos.

Descripción general del sistema de permisos

El sistema de permisos de Claude Code clasifica las operaciones en tres tipos, y los diferentes tipos de operaciones tienen diferentes políticas de permisos predeterminadas:

Tipo de herramienta Ejemplos ¿Requiere aprobación? Comportamiento permitido permanentemente
Operaciones de solo lectura Lectura de archivos, búsqueda Grep no No aplica
Comandos Bash Ejecución de comandos Shell Sí Válido permanentemente para cada directorio de proyecto y comando
Modificación de archivos Archivos Edit/Write Sí Hasta el final de la sesión

Tres acciones de permisos

Cada regla de permisos se resuelve finalmente en una de las siguientes tres acciones:

Acción Efecto Escenarios aplicables
"allow" Sin aprobación, se ejecuta automáticamente directamente Operaciones de bajo riesgo y alta frecuencia, como git status, npm run build
"ask" Muestra un aviso de aprobación, tú decides si permitirlo Operaciones con cierto riesgo, como escritura de archivos, ejecución de comandos peligrosos
"deny" Bloquea directamente, no se ejecuta ni se muestra aviso Operaciones peligrosas explícitamente no permitidas, como git push, rm -rf

Prioridad de reglas: deny → ask → allow.La primera regla que coincida gana, por lo que las reglas deny siempre tienen prioridad sobre allow y ask.

Modos de permisos

Los modos de permisos controlan si Claude pregunta al usuario antes de ejecutar una operación. Diferentes tareas requieren diferentes niveles de autonomía.

1. Seis modos disponibles

Modo Descripción Escenario más adecuado
default Comportamiento estándar: solicita permiso la primera vez que se usa cada herramienta Aprendizaje inicial, trabajos sensibles que requieren supervisión completa
acceptEdits Acepta automáticamente los permisos de edición de archivos de la sesión, excepto en directorios protegidos Iterar sobre código que se está revisando
plan Modo Plan: Claude puede analizar pero no puede modificar archivos ni ejecutar comandos Explorar el código base, planificar refactorizaciones
auto Aprueba automáticamente las llamadas a herramientas y realiza comprobaciones de seguridad en segundo plano (vista previa de investigación) Tareas de larga duración, reducir la fatiga de avisos
dontAsk Rechaza automáticamente las llamadas a herramientas, a menos que estén preaprobadas mediante reglas de permisos Entornos bloqueados, canalizaciones CI
bypassPermissions Omite los avisos de permisos, pero las escrituras en directorios protegidos aún solicitan confirmación Solo contenedores aislados y VM

Nota sobre directorios protegidos:Independientemente del modo, la escritura en.git、.vscode、.idea、.huskyy.claudenunca se aprobará automáticamente, excepto.claude/commands、.claude/agentsy.claude/skills。

2. Cambiar de modo de permisos

Cambiar durante la sesión:segúnShift+TabAlternar cíclicamentedefault → acceptEdits → plan → auto

Especificar el modo al inicio:

claude --permission-mode plan
claude --permission-mode bypassPermissions

Establecer como modo predeterminado (settings.json):

Ejemplos

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Sintaxis de las reglas de permisos

1. Formato básico

Las reglas de permisos siguen el formatoTooloTool(specifier)：

Ejemplos

{
  "permissions": {
    "allow": ["Bash", "WebFetch", "Read"],
    "deny": ["Edit"]
  }
}

2. Coincidir con todos los usos de herramientas

Las reglas sin especificador coinciden con todos los usos de esa herramienta:

Regla Efecto
Bash Coincide con todos los comandos Bash
WebFetch Coincide con todas las solicitudes de fetch de red
Read Coincide con todas las lecturas de archivos
Edit Coincide con todas las ediciones de archivos

Bash(*)Equivale aBash, ambos tienen el mismo efecto.

3. Control de grano fino mediante especificadores

Ejemplos

{
  "permissions": {
    "allow": [
      "Bash(npm run build)",     // Coincide con el comando exacto
      "Read(./.env)",             // Coincide con la lectura del archivo .env en el directorio actual
      "WebFetch(domain:example.com)"  // Coincide con solicitudes de fetch a example.com
    ]
  }
}

4. Patrones comodín

Las reglas Bash admiten patrones glob con*Los comodines pueden aparecer en cualquier posición del comando:

Ejemplos

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",         // Coincide con npm run build, npm run test, etc.
      "Bash(git commit *)",      // Coincide con git commit -m "message", etc.
      "Bash(git * main)",        // Coincide con git checkout main, git merge main, etc.
      "Bash(* --version)",       // Coincide con cualquier comando con el parámetro --version
      "Bash(* --help *)"         // Coincide con cualquier comando con el parámetro --help
    ],
    "deny": [
      "Bash(git push *)"         // Bloquea todas las operaciones git push
    ]
  }
}

Presta atención a los espacios antes de los comodines:Bash(ls *)Coincide conls -lapero no coincide conlsof；Bash(ls*)Coincide con ambos.

Reglas de permisos específicas de herramientas

1. Comandos Bash

Regla Ejemplos de coincidencia
Bash(npm run build) solamentenpm run build
Bash(npm run test *) npm run test、npm run test --coverage
Bash(npm *) Cualquier comando que comience con npm
Bash(* install) Cualquier comando que termine en install
Bash(git * main) git checkout main、git merge main

Limitación importante:Los modos de permisos Bash que intentan restringir los argumentos de los comandos pueden ser frágiles. Las opciones antes de la URL, diferentes protocolos, redirecciones, variables y espacios adicionales pueden causar discrepancias. Se recomienda utilizar la herramienta WebFetch junto condomain:permisos para filtrar URL.

2. Read y Edit (operaciones de archivos)

Las rutas de archivos admiten varios modos de prefijo de ruta:

Prefijo del patrón Significado Ejemplo
//path Ruta absoluta (desde la raíz del sistema de archivos) Read(//Users/alice/secrets/**)Coincide con/Users/alice/secrets/**
~/path Ruta del directorio principal Read(~/Documents/*.pdf)Coincide con/Users/alice/Documents/*.pdf
/path Relativa a la raíz del proyecto Edit(/src/**/*.ts)Coincide con<project root>/src/**/*.ts
patho./path Relativa al directorio actual Read(*.env)Coincide con<cwd>/*.env

Ejemplos

{
  "permissions": {
    "allow": [
      "Edit(/docs/**)",          // Permite editar archivos en el directorio docs del proyecto
      "Read(~/.zshrc)",         // Permite leer .zshrc del directorio personal
      "Edit(//tmp/scratch.txt)", // Permite editar archivos temporales con ruta absoluta
      "Read(src/**)"            // Permite leer archivos del subdirectorio src del directorio actual
    ],
    "deny": [
      "Read(*.env)",            // Bloquea la lectura de archivos .env (evita la filtración de claves)
      "Edit(//etc/**)"          // Bloquea la edición de archivos en directorios del sistema
    ]
  }
}

Nota:Las reglas de denegación de Read y Edit no se aplican a los subprocesos de Bashcat .env. Para obtener aplicación a nivel de sistema operativo, se debe habilitar la sandbox.

3. WebFetch (solicitudes de red)

Ejemplos

{
  "permissions": {
    "allow": [
      "WebFetch(domain:github.com)",    // Permite acceder a GitHub
      "WebFetch(domain:api.example.com)" // Permite acceder a la API interna
    ],
    "deny": [
      "WebFetch(domain:untrusted.com)"  // Bloquea el acceso a dominios no confiables
    ]
  }
}

4. MCP (Protocolo de Contexto de Modelo)

Ejemplos

{
  "permissions": {
    "allow": [
      "mcp__puppeteer",                      // Permite cualquier herramienta proporcionada por el servidor puppeteer
      "mcp__puppeteer__*"                    // Permite todas las herramientas del servidor puppeteer
    ],
    "deny": [
      "mcp__puppeteer__puppeteer_navigate"  // Bloquea herramientas específicas
    ]
  }
}

5. Agent (subagente)

Ejemplos

{
  "permissions": {
    "allow": [
      "Agent(Explore)",           // Permite usar el subagente Explore
      "Agent(Plan)"               // Permite usar el subagente Plan
    ],
    "deny": [
      "Agent(my-custom-agent)"    // Bloquea subagentes personalizados
    ]
  }
}

Configuración del directorio de trabajo

De forma predeterminada, Claude Code solo permite el acceso al directorio de trabajo y sus subdirectorios al iniciar. Si necesita acceder a rutas fuera del directorio del proyecto, debe configurarlo explícitamente.

1. Métodos de acceso ampliado

  • Durante el inicio:Usar--add-dir <path>parámetros de CLI
  • Durante la sesión:Usar/add-dircomando
  • Configuración persistente:Agregar a settings.json enadditionalDirectories

Ejemplos

{
  "additionalDirectories": [
    "~/projects/personal/**",    // Permite acceder al directorio de proyectos personales
    "~/projects/work/**",        // Permite acceder al directorio de proyectos de trabajo
    "~/dotfiles/**"               // Permite acceder al directorio de archivos de configuración
  ]
}

2. Excepciones

Lo siguiente sigue siendo accesible después de configurar directorios adicionales, sin necesidad de configuración adicional:

  • .claude/skills/Skills en (con recarga en vivo)
  • .claude/settings.jsonConfiguración de complementos en (soloenabledPluginsyextraKnownMarketplaces）
  • archivos CLAUDE.md y.claude/rules/(solo cuando se estableceCLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1)

Modo automático (Auto Mode)

El modo automático es un nuevo mecanismo introducido por Claude Code que reemplaza la aprobación humana mediante un clasificador impulsado por modelos, controlando los riesgos mientras se garantiza la eficiencia.

1. Condiciones disponibles

  • Solo planes Team, Enterprise y API
  • Requiere Claude Sonnet 4.6 o Claude Opus 4.6
  • No disponible en Haiku, modelos claude-3 ni proveedores de terceros
  • Los administradores deben habilitarlo en la configuración de administración de Claude Code

2. Cómo funciona

Antes de que se ejecute cada operación, un modelo clasificador independiente revisa la conversación y decide si la operación coincide con lo que el usuario solicitó.

Capas de defensa:

  1. Los sondeos del lado del servidor escanean los resultados de las herramientas entrantes
  2. El clasificador nunca ve los resultados de las herramientas, lo que evita que las instrucciones inyectadas afecten la decisión

Orden de evaluación de operaciones:

  1. Las operaciones que coinciden con reglas de permitir o denegar se resuelven de inmediato
  2. Las operaciones de solo lectura y la edición de archivos en el directorio de trabajo se aprueban automáticamente (excepto en directorios protegidos)
  3. Todo lo demás se envía al clasificador
  4. Si el clasificador bloquea, Claude recibe el motivo e intenta un método alternativo

3. Comportamiento predeterminado del clasificador

Tipo de operación Comportamiento
Bloqueado por defecto
Descargar y ejecutar código curl | bashesperar
Enviar datos confidenciales a endpoints externos Riesgo de fuga de datos
Despliegues y migraciones de producción Modificaciones en entornos de producción
Eliminación a gran escala en almacenamiento en la nube Riesgo de pérdida de datos
Otorgar permisos de IAM o de repositorio Riesgo de escalada de privilegios
Modificar infraestructura compartida Afecta a otros usuarios
Destruir archivos de forma irreversible Archivos existentes antes del inicio de la sesión
Operaciones destructivas de control de código fuente Push forzado, push directo a main
Permitido por defecto
Operaciones de archivos locales en el directorio de trabajo Dentro del ámbito seguro
Instalar dependencias declaradas Dependencias ya presentes en package.json
Leer .env y enviar credenciales Enviar a la API correspondiente
Solicitudes HTTP de solo lectura Solicitudes GET
Push a la rama de inicio Operaciones seguras de ramas

4. Configuración del modo automático

Ejemplos

{
  "autoMode": {
    "environment": [
      "Source control: github.example.com/acme-corp and all repos under it",
      "Trusted cloud buckets: s3://acme-build-artifacts, gs://acme-ml-datasets",
      "Trusted internal domains: *.corp.example.com, api.internal.example.com",
      "Key internal services: Jenkins at ci.example.com, Artifactory at artifacts.example.com"
    ],
    "allow": [
      "Deploying to the staging namespace is allowed",
      "Writing to s3://acme-scratch/ is allowed"
    ],
    "soft_deny": [
      "Never run database migrations outside the migrations CLI",
      "Never modify files under infra/terraform/prod/: production infrastructure changes go through the review workflow"
    ]
  }
}

5. Mecanismo de retroceso (fallback)

Si el clasificador bloquea operaciones 3 veces seguidas, o 20 veces en total en una sesión, el modo automático se pausa y Claude Code vuelve a solicitar confirmación para cada operación.

/permissions  # 在 "最近拒绝" 选项卡查看被拒绝的操作

Relación entre sandbox y permisos

La sandbox y los permisos son capas de seguridad complementarias que trabajan en conjunto:

Aspecto Permisos Sandbox
Objeto de control Controla qué herramientas puede usar Claude Code Limita el sistema de archivos y el contenido de red al que pueden acceder los comandos Bash
Momento de evaluación Se evalúa antes de que se ejecute cualquier herramienta Solo se aplica a comandos Bash y sus subprocesos
Ámbito de aplicación Todas las herramientas: Bash, Read, Edit, WebFetch, MCP, etc. Solo comandos Bash

1. Habilitar sandbox

/sandbox

Ejecutar/sandboxEl comando habilita la sandbox y abre un menú para elegir el modo de sandbox.

2. Configurar sandbox

Ejemplos

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"],    // Permite escribir en estas rutas
      "denyWrite": ["~/important/**"],            // Bloquea la escritura en directorios importantes
      "denyRead": ["~/"]                           // Bloquea la lectura del directorio personal
    },
    "network": {
      "httpProxyPort": 8080,                       // Puerto del proxy HTTP
      "socksProxyPort": 8081                       // Puerto del proxy SOCKS
    }
  }
}

Defensa en profundidad:Los permisos y la sandbox deben habilitarse al mismo tiempo. Las reglas de denegación de permisos impiden que Claude intente acceder a recursos restringidos, y las limitaciones de la sandbox evitan que los comandos Bash alcancen recursos fuera de los límites definidos.

Uso de Hooks para ampliar permisos

Los hooks PreToolUse se ejecutan antes del aviso de permisos y pueden:

  • Rechazar la llamada a la herramienta
  • Forzar el aviso
  • Omitir el aviso y permitir que la llamada continúe

Ejemplos

#!/bin/bash
# Ejemplo de hook PreToolUse: interceptar comandos peligrosos
COMMAND=$(cat | jq -r '.tool_input.command // empty')

if echo "$COMMAND" | grep -qE 'rm\s+(-[rf]+\s+)*(\/|~|\.\.\/)'; then
    echo "BLOCKED: rm on sensitive path"
    exit 2  # El código de salida 2 bloquea la llamada a la herramienta
fi
exit 0  # Permitir continuar

Importante:Omitir el aviso no elude las reglas de permisos. Las reglas de Deny y ask se siguen evaluando después de que el hook devuelva "allow". Cuando un hook de bloqueo sale con el código de salida 2, detiene la llamada a la herramienta antes de que se evalúen las reglas de permisos.

Establecer prioridades

La configuración de Claude Code se aplica con la siguiente prioridad (de mayor a menor):

  1. Configuración administrada- No puede ser anulada por ningún otro nivel (control del administrador)
  2. Parámetros de línea de comandos- Anulación temporal de la sesión
  3. Configuración local del proyecto (.claude/settings.local.json)
  4. Configuración compartida del proyecto (.claude/settings.json)
  5. Configuración de usuario (~/.claude/settings.json)

Regla clave:Si una herramienta se deniega en cualquier nivel, ningún otro nivel puede permitirla.

Ejemplos prácticos de configuración

Ejemplo 1: Modo conservador (todas las operaciones requieren aprobación)

Adecuado para quienes se acercan por primera vez a Claude Code o cuando se trabaja en proyectos importantes:

Ejemplos

{
  "permissions": {
    "defaultMode": "default"
  }
}

Ejemplo 2: Configuración común de desarrollo (operaciones de lectura abiertas, aprobación de ejecución de comandos)

Adecuado para el desarrollo diario: permite a Claude leer y buscar código libremente, pero requiere confirmación al modificar archivos y ejecutar comandos:

Ejemplos

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Bash(git status *)",      // Ver el estado de git
      "Bash(git log *)",         // Ver el registro de git
      "Bash(git diff *)",       // Ver el diff de git
      "Bash(npm run *)",         // Ejecutar scripts de npm
      "Bash(npm test *)",        // Ejecutar pruebas
      "Bash(ls *)",              // Listar directorios
      "Bash(grep *)"             // Buscar contenido
    ],
    "deny": [
      "Bash(rm *)",              // Eliminar archivos: bloquear directamente
      "Bash(git push *)",        // Enviar código: bloquear directamente
      "Bash(mkdir / *)",         // Crear directorios del sistema: bloquear directamente
      "Edit(*.env)"              // Bloquear la edición de archivos .env
    ]
  }
}

Ejemplo 3: Configuración de entorno bloqueado (solo se permiten operaciones preaprobadas)

Adecuado para canalizaciones de CI o entornos que requieren un control estricto:

Ejemplos

{
  "permissions": {
    "defaultMode": "dontAsk",
    "allow": [
      "Read(*)",                  // Permitir lectura de todos los archivos
      "Bash(npm run build *)",    // Permitir comandos de compilación
      "Bash(npm test *)"          // Permitir ejecutar pruebas
    ],
    "deny": [
      "Edit(*)",                  // Prohibir toda edición de archivos
      "Bash(git *)",              // Prohibir todas las operaciones de git
      "Bash(curl *)",             // Prohibir solicitudes de red
      "Bash(ssh *)"               // Prohibir conexiones SSH
    ]
  }
}

Ejemplo 4: Permitir acceso a múltiples proyectos

Cuando Claude necesita trabajar en múltiples directorios de proyectos:

Ejemplos

{
  "permissions": {
    "allow": [
      "Edit(/src/**)",            // Permitir editar el directorio src
      "Edit(/docs/**)"            // Permitir editar el directorio de documentación
    ],
    "deny": [
      "Edit(/docs/**/*.md)"       // Prohibir editar archivos de documentación (solo lectura)
    ]
  },
  "additionalDirectories": [
    "~/projects/personal/**",     // Permitir acceso a proyectos personales
    "~/projects/work/**",         // Permitir acceso a proyectos de trabajo
    "~/dotfiles/**"               // Permitir acceso a archivos de configuración
  ]
}

Ejemplo 5: Usar sandbox para restringir operaciones Bash

Habilitar el sandbox proporciona protección adicional a nivel de sistema operativo:

Ejemplos

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/projects/myapp/**"],
      "denyRead": ["~/secrets/**"]
    },
    "network": {
      "httpProxyPort": 8080
    }
  },
  "permissions": {
    "allow": [
      "Bash(*)",                  // Permitir todos los comandos dentro del sandbox
      "WebFetch(domain:api.github.com)"
    ],
    "deny": [
      "WebFetch(domain:untrusted.com)"
    ]
  }
}

Configuración administrada (configuración de administrador)

Los administradores pueden implementar configuraciones administradas que no pueden ser anuladas por la configuración del usuario o del proyecto.

Configuración Descripción
allowManagedHooksOnly Evita cargar hooks de usuarios, proyectos y complementos
allowManagedMcpServersOnly Solo respeta los servidores MCP de configuración administrada
allowManagedPermissionRulesOnly Evita que la configuración del usuario y del proyecto definan reglas de permisos
sandbox.filesystem.allowManagedReadPathsOnly Solo respeta las rutas de lectura de configuración administrada
sandbox.network.allowManagedDomainsOnly Solo respeta los dominios permitidos de configuración administrada
permissions.disableBypassPermissionsMode Establecer en "disable" evita el uso del modo bypassPermissions
permissions.disableAutoMode Establecer en "disable" evita el uso del modo automático

Mejores prácticas de seguridad

  1. Comience con restricciones: Comience con el mínimo privilegio y amplíe según sea necesario
  2. Use sandbox: El sandbox proporciona protección adicional a nivel de sistema operativo y debe habilitarse al mismo tiempo
  3. Proteja archivos confidenciales: Usedenyreglas para bloquear el acceso.env, archivos de claves, etc.
  4. Restrinja el acceso a la red: Solo permita el acceso a dominios necesarios para evitar la fuga de datos
  5. Evite bypassPermissions: Úselo solo en entornos aislados (contenedores, máquinas virtuales)
  6. Use soft_deny del modo auto: Proporciona orientación de seguridad sin restricciones excesivas
  7. Revise la configuración periódicamente: Revise los intentos de violación del sandbox y las acciones denegadas

Advertencia de seguridad:bypassPermissionsEl modo no proporciona protección contra la inyección de prompts u operaciones accidentales. Para una alternativa más segura que aún mantiene comprobaciones de seguridad en segundo plano, se debe utilizar el modo auto.

Otras extensiones