Errores de permisos en Claude Code: guía completa para solucionarlos (2026)

Claude Code es uno de los asistentes de programación con IA más potentes disponibles en 2026, pero los errores de permisos siguen siendo la mayor fuente de frustración para los desarrolladores que lo usan a diario. Tanto si te topas con denegaciones de acceso al sistema de archivos, te quedas atascado en bucles interminables de aprobación de tools o te enfrentas a fallos crípticos de clave de API, esta guía te lleva a través de cada error de permisos común con mensajes de error exactos, causas raíz y soluciones probadas.

Tabla de contenidos

1. Acceso al sistema de archivos denegado
2. Prompts de sudo y permisos elevados
3. Desajustes de permisos de directorio
4. Errores de clave de API y autenticación
5. Errores de límite de uso y cuota
6. Fatiga de aprobación de tools
7. Permisos de node_modules y gestor de paquetes
8. Fallos de permisos de Git y SSH
9. Cómo gestiona SuperBuilder los permisos
10. Consejos de gestión segura de permisos

1. Acceso al sistema de archivos denegado

Mensaje de error:

Error: EACCES: permission denied, open '/path/to/file'

o

Claude does not have permission to read/write this file. Please approve the tool use.

Causa: Claude Code opera dentro de un entorno en sandbox y requiere aprobación explícita para leer o modificar archivos fuera de sus directorios permitidos. Esto suele ocurrir cuando apuntas Claude Code a un directorio de proyecto que pertenece a otro usuario, o cuando los archivos tienen permisos restrictivos establecidos (p. ej., chmod 600).

Pasos para solucionarlo:

1. Comprueba los permisos del archivo:

ls -la /path/to/file

1. Si el archivo pertenece a otro usuario, cambia la propiedad o añade tu usuario al grupo del archivo:

# Change ownership to your user
sudo chown $(whoami) /path/to/file

# Or fix group permissions
sudo chmod 664 /path/to/file

1. Si trabajas dentro de un contenedor Docker o una VM, asegúrate de que el volumen montado tenga los permisos correctos. Un error común es montar con ro (solo lectura) cuando Claude Code necesita acceso de escritura:

# Wrong: read-only mount
docker run -v /my/project:/app:ro ...

# Correct: read-write mount
docker run -v /my/project:/app:rw ...

1. Cuando Claude Code te pida aprobar el acceso a un archivo, revisa la ruta con cuidado y apruébala. Si estás cansado de aprobar cada operación de archivo, consulta más abajo la sección sobre Fatiga de aprobación de tools.

2. Prompts de sudo y permisos elevados

Mensaje de error:

This operation requires elevated permissions. Run with sudo or adjust directory permissions.

o

Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/...'

Causa: Claude Code intenta ejecutar un comando que modifica directorios a nivel de sistema (como /usr/local, /etc u /opt). Esto sucede con mayor frecuencia durante instalaciones de paquetes globales, cambios de configuración del sistema, o cuando tu proyecto referencia accidentalmente rutas absolutas del sistema.

Pasos para solucionarlo:

1. Nunca ejecutes Claude Code en sí con sudo. Esto crea archivos propiedad de root dentro de tu proyecto, lo que provoca errores de permisos en cascada más adelante.

2. Para instalaciones globales de npm, configura npm para usar un directorio a nivel de usuario:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
# Add to your shell profile (.zshrc or .bashrc):
export PATH=~/.npm-global/bin:$PATH

1. Si ya tienes archivos propiedad de root en tu proyecto por un error de sudo anterior, arréglalos:

sudo chown -R $(whoami):$(id -gn) /path/to/project

1. Para operaciones que de verdad necesitan acceso elevado (editar /etc/hosts, vincularse al puerto 80), ejecuta esos comandos manualmente en una terminal aparte en lugar de a través de Claude Code.

3. Desajustes de permisos de directorio

Mensaje de error:

Error: EACCES: permission denied, scandir '/path/to/directory'

o

Cannot access project directory. Check that the path exists and you have read permissions.

Causa: El directorio del proyecto o uno de sus directorios padre carece del permiso de ejecución (x) para tu usuario. En sistemas Unix, necesitas permiso de ejecución sobre un directorio para listar su contenido, incluso si los archivos de dentro son legibles. Esto también ocurre cuando un enlace simbólico apunta a un directorio al que no tienes acceso.

Pasos para solucionarlo:

1. Comprueba los permisos del directorio y de todos los directorios padre:

namei -l /path/to/your/project

Esto muestra la cadena de permisos desde la raíz hasta tu directorio objetivo. Busca cualquier directorio al que le falte el flag x para tu usuario.

1. Arregla el directorio específico:

chmod 755 /path/to/directory

1. Si trabajas con enlaces simbólicos, verifica que el destino exista y sea accesible:

readlink -f /path/to/symlink
ls -la $(readlink -f /path/to/symlink)

1. En macOS, comprueba Ajustes del Sistema > Privacidad y Seguridad > Archivos y Carpetas. Tu app de terminal (Terminal, iTerm2 o la terminal integrada de tu IDE) puede necesitar permiso explícito para acceder a las carpetas Escritorio, Documentos o Descargas. Claude Code hereda los permisos de su proceso de terminal padre.

4. Errores de clave de API y autenticación

Mensaje de error:

Error: Invalid API key provided. Please check your ANTHROPIC_API_KEY.

o

Authentication failed: 401 Unauthorized

o

Error: API key not found. Set ANTHROPIC_API_KEY in your environment.

Causa: Claude Code requiere una clave de API de Anthropic válida para funcionar. Estos errores aparecen cuando la clave falta, ha expirado, tiene un formato incorrecto, o cuando hay un desajuste entre la clave y el endpoint de la API (p. ej., usar una clave de producción contra un endpoint de staging).

Pasos para solucionarlo:

1. Verifica que tu clave de API esté configurada:

echo $ANTHROPIC_API_KEY

Si está vacía, configúrala en tu perfil de shell:

# Add to ~/.zshrc or ~/.bashrc
export ANTHROPIC_API_KEY="sk-ant-api03-..."

1. Comprueba el formato de la clave. Las claves de API válidas de Anthropic empiezan por sk-ant-. Si la tuya tiene otro aspecto, puede que tengas una clave obsoleta de una versión anterior de la API.

2. Prueba la clave directamente:

curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}' \
  | head -c 200

Si obtienes una respuesta JSON válida, la clave funciona. Si obtienes un 401, regenera la clave desde la Anthropic Console.

1. Si estás detrás de un proxy corporativo o VPN, la llamada a la API puede estar bloqueada. Consulta con tu administrador de red o prueba:

curl -v https://api.anthropic.com 2>&1 | grep "HTTP/"

1. Para configuraciones de equipo donde la clave se gestiona vía un gestor de secretos, asegúrate de que la clave esté disponible en la sesión de shell donde se ejecuta Claude Code, no solo en tu pipeline de CI.

5. Errores de límite de uso y cuota

Mensaje de error:

Error 429: Rate limit exceeded. Please retry after X seconds.

o

Error: You have exceeded your monthly usage quota.

o

RateLimitError: Number of request tokens has exceeded your per-minute rate limit.

Causa: Anthropic aplica límites de uso por clave de API según el nivel de tu plan. Claude Code puede consumir tokens rápidamente durante tareas complejas, especialmente cuando lee archivos grandes, realiza refactorizaciones de varios pasos o se ejecuta en un bucle reintentando operaciones fallidas. Cada llamada a una tool (lectura de archivo, comando bash, etc.) cuenta para tu uso de tokens.

Pasos para solucionarlo:

1. Comprueba tu uso actual en console.anthropic.com. Revisa tanto las cuotas por minuto como las mensuales.

2. Si alcanzas los límites por minuto, la solución más simple es esperar y reintentar. Claude Code suele gestionar esto automáticamente con retroceso exponencial, pero si no lo hace:

# Check your rate limit headers
curl -sI https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" 2>&1 | grep -i "rate\|limit\|retry"

1. Reduce el consumo de tokens siendo específico en tus prompts. En lugar de "refactoriza toda esta base de código", apunta a archivos o funciones concretos. Esto reduce el número de lecturas de archivos y llamadas a tools que Claude Code necesita hacer.

2. Si alcanzas los límites de forma constante, sube el nivel de tu plan o solicita un aumento del límite de uso a través de la Anthropic Console.

3. Para equipos, usa claves de API separadas por desarrollador para evitar que el uso intenso de una persona bloquee a todo el equipo.

6. Fatiga de aprobación de tools

Mensaje de error:

Esto no es un error tradicional, sino más bien el flujo constante de prompts de aprobación:

Claude wants to run: bash("npm install lodash")
Allow? [y/n/always]

Claude wants to edit: src/components/App.tsx
Allow? [y/n/always]

Causa: Por defecto, Claude Code pide permiso antes de cada acción potencialmente destructiva: ejecutar comandos de shell, editar archivos, eliminar archivos y hacer peticiones de red. Es una función de seguridad, pero durante las sesiones de desarrollo activo se convierte en un cuello de botella. Los desarrolladores reportan que pasan más tiempo aprobando acciones que revisando los cambios de código reales.

Pasos para solucionarlo:

1. Usa el flag --dangerously-skip-permissions para saltarte todos los prompts de aprobación. Esta es la opción nuclear, apropiada para desarrollo local en proyectos no sensibles:

claude --dangerously-skip-permissions

Ten en cuenta: este flag permite a Claude Code ejecutar cualquier comando, modificar cualquier archivo y hacer cualquier petición de red sin preguntar. Úsalo solo en entornos en sandbox o desechables.

1. Configura una lista de permitidos para tools específicas. Crea o edita ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Bash(npm *)",
      "Bash(git *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

Esto te permite auto-aprobar operaciones seguras mientras sigues requiriendo confirmación para las peligrosas.

1. Usa la opción "always allow" cuando se te pregunte. Cuando Claude Code pida aprobación, responder con "always" recuerda esa decisión para la sesión actual.

2. Considera un wrapper con GUI como SuperBuilder, que ofrece un flujo de aprobación visual con aceptar/rechazar en un clic, haciendo el proceso de aprobación mucho más rápido que escribir y/n en una terminal. Más detalles en la sección de SuperBuilder más abajo.

7. Permisos de node_modules y gestor de paquetes

Mensaje de error:

npm ERR! Error: EACCES: permission denied, access '/path/to/node_modules'

o

Error: EPERM: operation not permitted, rename 'node_modules/.package-lock.json'

Causa: Esto ocurre cuando node_modules fue creado parcialmente por un usuario diferente (a menudo root por un sudo npm install), cuando una instalación anterior se interrumpió, o cuando el archivo de lock de paquetes se ha corrompido. Claude Code ejecuta los comandos de npm/yarn/pnpm como tu usuario, así que cualquier archivo propiedad de root en node_modules provoca fallos en cascada.

Pasos para solucionarlo:

1. Restablece la propiedad de node_modules:

sudo chown -R $(whoami) node_modules

1. Si el error persiste, haz una instalación limpia:

rm -rf node_modules package-lock.json
npm install

1. Para usuarios de pnpm, comprueba los permisos de tu store:

pnpm store path
ls -la $(pnpm store path)

1. Evita que el problema vuelva a ocurrir no usando nunca sudo con tu gestor de paquetes. Si te ves necesitando sudo para las instalaciones, tu prefijo de npm está mal configurado (consulta la sección 2).

8. Fallos de permisos de Git y SSH

Mensaje de error:

git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

o

Error: unable to access 'https://github.com/...': The requested URL returned error: 403

Causa: Cuando Claude Code ejecuta git push, git pull o git clone en tu nombre, usa las credenciales SSH o HTTPS de tu shell. Si tu clave SSH no está cargada, el agente no está configurado, o la clave no tiene acceso al repositorio objetivo, la operación falla.

Pasos para solucionarlo:

1. Comprueba tu agente SSH:

ssh-add -l

Si dice "The agent has no identities", añade tu clave:

ssh-add ~/.ssh/id_ed25519

1. Prueba tu conexión SSH:

ssh -T git@github.com

Deberías ver "Hi username! You've successfully authenticated."

1. Para autenticación HTTPS, asegúrate de que tu credential helper esté configurado:

git config --global credential.helper

En macOS, usa osxkeychain. En Linux, usa store o cache.

1. Si usas personal access tokens (PATs) granulares, asegúrate de que el token tenga los permisos Contents: Read and write y Metadata: Read para el repositorio objetivo.

2. Para organizaciones con SSO, debes autorizar tu clave SSH o PAT para la organización. Visita GitHub > Settings > SSH keys y haz clic en "Configure SSO" junto a tu clave.

9. Cómo gestiona SuperBuilder los permisos

SuperBuilder es una aplicación de escritorio para macOS que envuelve Claude Code con una interfaz visual. Adopta un enfoque diferente para el problema de los permisos que elimina la mayor parte de la fricción descrita arriba.

El flag --dangerously-skip-permissions, gestionado de forma segura. SuperBuilder genera Claude Code con el flag --dangerously-skip-permissions internamente, pero lo envuelve con su propia capa de seguridad visual. En lugar de los prompts binarios de y/n en terminal, obtienes una interfaz rica que muestra exactamente qué quiere hacer Claude Code, con diffs resaltados sintácticamente para las ediciones de archivos y vistas previas completas de los comandos para las operaciones de shell.

Flujo de aprobación visual. Cada llamada a una tool aparece en una tarjeta clara y legible. Las ediciones de archivos muestran un diff de antes/después. Los comandos bash muestran el comando exacto con sus argumentos. Puedes aprobar o rechazar con un solo clic, o aprobar en lote varias operaciones seguras a la vez. Esto convierte el cuello de botella de la aprobación en un rápido escaneo visual.

Gestión automática de claves de API. SuperBuilder gestiona la configuración de la clave de API a través de su panel de configuración. Introduces tu clave una vez y se almacena de forma segura y se inyecta en cada sesión de Claude Code. Sin malabares con variables de entorno, sin editar perfiles de shell.

Permisos acotados al proyecto. Cada proyecto en SuperBuilder se ejecuta en su propio contexto aislado. Claude Code solo puede acceder a archivos dentro del directorio del proyecto activo, reduciendo la superficie de riesgo en comparación con ejecutar con skip-permissions global en una terminal.

Conciencia de costes integrada. SuperBuilder rastrea el uso de tokens por sesión y muestra una estimación de coste acumulado. Cuando una sola llamada a una tool supera los 0,10 $, muestra una tarjeta de aviso para que decidas si proceder. Esto evita los costes de API descontrolados que a veces acompañan al modo de saltar permisos.

Si pasas más tiempo gestionando los permisos de Claude Code que escribiendo código, descarga SuperBuilder y prueba el flujo de trabajo visual.

10. Consejos de gestión segura de permisos

Independientemente de si usas Claude Code directamente en la terminal o a través de una herramienta como SuperBuilder, estas prácticas mantendrán tus proyectos seguros minimizando la fricción de permisos.

Usa solo directorios a nivel de proyecto

Ejecuta siempre Claude Code desde la raíz de tu proyecto. Evita apuntarlo a /, a tu directorio home o a rutas del sistema. Cuanto más estrecho sea el directorio de trabajo, menos daño puede causar un comando mal aprobado.

Audita tu .claude.json con regularidad

Claude Code almacena la configuración en ~/.claude.json, incluyendo conexiones a servidores MCP y anulaciones de permisos. Revisa este archivo periódicamente:

cat ~/.claude.json | python3 -m json.tool

Busca cualquier servidor MCP o entrada de permisos que no reconozcas.

Usa el control de versiones como red de seguridad

Antes de empezar una sesión larga de Claude Code, asegúrate de que tu árbol de trabajo esté limpio:

git status
git stash  # if needed

Después de la sesión, revisa todos los cambios antes de hacer commit:

git diff

Si Claude Code hizo cambios no deseados, siempre puedes revertir:

git checkout -- .

Configura protecciones para archivos críticos

Para archivos que nunca quieres que Claude Code modifique (.env, credentials.json, configuraciones de producción), hazlos de solo lectura:

chmod 444 .env
chmod 444 config/production.json

Claude Code no podrá escribir en estos archivos ni siquiera con skip-permissions activado.

Rota las claves de API periódicamente

Si usas --dangerously-skip-permissions con regularidad, rota tu clave de API de Anthropic mensualmente. Si la clave se filtra a través de una ejecución de comando comprometida, el radio de impacto es limitado.

Usa claves separadas para desarrollo y CI

Nunca uses la misma clave de API para el desarrollo local y los pipelines de CI/CD. Crea claves dedicadas para cada contexto para poder revocar una sin afectar a la otra.

Referencia rápida: búsqueda de error a solución

Conclusión

Los errores de permisos en Claude Code casi siempre se pueden resolver con el diagnóstico correcto. Las causas raíz más comunes se reducen a tres cosas: desajustes de propiedad de archivos por uso accidental de sudo, claves de API faltantes o expiradas, y la sobrecarga del flujo de aprobación por defecto.

Para los desarrolladores que quieren centrarse en construir en lugar de gestionar permisos, SuperBuilder ofrece una alternativa optimizada con aprobaciones visuales, gestión automática de claves y sandboxing acotado al proyecto. Mantiene las garantías de seguridad del sistema de permisos de Claude Code mientras elimina la fricción que te ralentiza.

Sea cual sea el enfoque que elijas, el principio clave es el mismo: mantén tus permisos lo más estrechos posible, usa el control de versiones como red de seguridad y nunca ejecutes herramientas de programación con IA con privilegios elevados que no darías a un desarrollador junior de tu equipo.