Qué hacer si no se instala: solución de problemas al empezar, verificación rápida de 60 segundos
Terminaste los comandos de la lección de instalación, escribes claude y no responde—no te apresures a reinstalar. Las fallas de instalación de Claude Code casi siempre se atascan en cuatro etapas: descarga, instalación, disponibilidad del comando, inicio de sesión, y los errores de cada etapa se ven distintos. Esta página organiza los errores frecuentes de la documentación oficial de solución de problemas por «coincidencia de texto original»: primero localiza la etapa con la verificación rápida de 60 segundos, luego sigue la entrada correspondiente para reparar.
Cómo usar esta página: copia literalmente el error que encontraste y hazlo coincidir con el texto original de los encabezados H4 de abajo, luego ve directo a la entrada de «causa + solución». Si no encuentras uno idéntico, ejecuta primero la verificación rápida de 60 segundos para acotar el problema. (Verificación de hechos 2026-11-04; los comandos y errores cambian con las versiones, prevalece la documentación oficial de solución de problemas.)
💡 Los errores que aparecen después de instalar no están en esta página
Esta página cubre «no se instala, no se inicia sesión». Si ya puedes conversar con normalidad y el error surgió durante la ejecución (errores del modelo, herramientas que fallan), ve a bucle de errores: alimenta el mensaje de error tal cual.
Qué podrás hacer al terminar
- Localizar en 60 segundos, con 4 comandos, en qué etapa se atascó: disponibilidad del comando, archivos de instalación, red, salud de la instalación
- Reparar
claude command not found/'claude' is not recognized(configuración única del PATH, una vez lista no hay que volver a tocarla) - Distinguir los errores de descarga (403, TLS, script convertido en página web) y decidir si reintentar, revisar la red o cambiar de canal de instalación
- Manejar los tres grandes fallos de instalación con npm: permisos
EACCES, npm 12 omitiendo postinstall, directorios residualesENOTEMPTY - Cuando el inicio de sesión se atasca, aplicar la tríada «cerrar sesión → reabrir → volver a iniciar sesión» y distinguir los síntomas de la suscripción, el rol y la sobrescritura por API key
Tu situación actual
- Terminaste el comando de instalación, escribes
claudey dice command not found—¿se instaló o no? - El error es una larga cadena en inglés y no sabes si reintentar en el sitio, revisar la red o probar otro método de instalación desde cero
- La instalación sí funcionó, pero la página de inicio de sesión gira o da error y no logras entrar
Cuándo usar esta técnica
Cuando necesitas:
- Reparar errores atascados en instalación de Claude Code o en métodos de instalación alternativos
- Antes de publicar pidiendo ayuda, invertir tú mismo 60 segundos en localizar en qué etapa está el problema
Y no quieres:
- Ir al foro a publicar y esperar respuestas al primer error—la verificación rápida resuelve la mayoría de los problemas de instalación
- Tratar «fallo de descarga» como «no se instaló» y reinstalar sin parar, empeorando el desorden
🎒 Preparativos antes de empezar
- Haber ejecutado la instalación de Claude Code (no importa si se atascó, esta página es justamente para desatascar)
- Saber qué terminal tienes abierto: en macOS / Linux es la ventana del terminal; en Windows se distingue PowerShell (el prompt incluye
PS) de CMD (no lo incluye) - Copiar literalmente el texto del error—hacer coincidir el texto original es mucho más rápido que describirlo traducido
Idea central: las cuatro etapas de la instalación fallida de Claude Code
Primero localiza la etapa y luego mira el error. Desde ejecutar el comando de instalación hasta poder conversar, hay que superar cuatro etapas en orden, y los errores de cada etapa tienen un aspecto diferente:
| Etapa | Síntoma de bloqueo | Error típico | Grupo correspondiente de esta página |
|---|---|---|---|
| 1. Descarga | El comando de instalación no termina, o lo descargado es una página web | curl: (22) The requested URL returned error: 403, syntax error near unexpected token '<' | Problemas de descarga y red |
| 2. Instalación | Se usó el shell equivocado, el directorio no tiene permisos, npm se quedó a medias | 'irm' is not recognized, EACCES, npm error code ENOTEMPTY | Problemas del comando de instalación de Windows / instalación con npm |
| 3. Comando disponible | Se instaló, pero el shell no encuentra el comando | zsh: command not found: claude | Problemas de disponibilidad del comando (PATH) |
| 4. Inicio de sesión | Instalado, pero la página de inicio de sesión se queda cargando o da error | OAuth error: Invalid code | Problemas de inicio de sesión y autenticación |
El texto original del error es la clave. La documentación oficial de solución de problemas indexa las soluciones por el texto original del error, y esta página hace lo mismo: copia literalmente el error que encontraste y hazlo coincidir con los títulos H4 de abajo. Las descripciones traducidas a menudo no coinciden: si a 'claude' is not recognized lo llamas «no reconocido», no encontrarás la solución original.
La verificación tras cada arreglo es siempre una sola: abre un terminal nuevo y ejecuta claude --version; si imprime un número de versión (con la forma 2.1.211 (Claude Code)), la etapa está superada.
Primera revisión: verificación rápida de 60 segundos
Ejecuta los cuatro comandos en orden para verificar, uno a uno, la disponibilidad del comando, los archivos de instalación, la red y la salud de la instalación: donde falle uno, ahí está la etapa del problema.
macOS / Linux (ejecutar en el terminal):
# 1. 命令可用吗?——能打印版本号 = 安装环节全过,卡的是登录,直接跳「登录认证问题」
claude --version
# 2. 安装文件在吗?——有列表输出 = 装上了,是 PATH 问题,跳「命令可用(PATH)问题」
# No such file or directory = 没装上,看第 3 条
ls -la ~/.local/bin/claude
# 3. 网络通吗?——第一行 HTTP/2 200 = 下载服务器可达,重装一次多半就好
# 403 或无输出 = 网络/地区问题,跳「下载与网络问题」
curl -sI https://downloads.claude.ai/claude-code-releases/latest
# 4. 安装健康吗?——第 1 条能出版本号、但 claude 一启动就崩或卡住时,跑官方自检看诊断报告
claude doctorWindows (ejecutar en PowerShell; ten en cuenta que curl debe escribirse curl.exe: el curl de PowerShell es un alias de Invoke-WebRequest y no reconoce -sI):
# 1. 命令可用吗?——能打印版本号 = 安装环节全过,卡的是登录
claude --version
# 2. 安装文件在吗?——True = 装上了,是 PATH 问题;False = 没装上,看第 3 条
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
# 3. 网络通吗?——第一行 HTTP/1.1 200 OK = 下载服务器可达
curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest
# 4. 安装健康吗?——版本号能打印、但 claude 启动就崩或卡住时,跑官方自检
claude doctorCómo interpretar los resultados:
| Resultado de la verificación rápida | En qué etapa se atasca | A qué sección ir |
|---|---|---|
| La orden 1 ya imprime el número de versión | Instalación superada por completo | El inicio de sesión se atasca → «Problemas de inicio de sesión y autenticación» |
| La orden 1 da command not found, la orden 2 tiene archivo / True | PATH | «Problemas de disponibilidad del comando (PATH)» |
| La orden 2 dice que no existe el archivo, la orden 3 200 | La instalación no terminó | Vuelve a Instalación Claude Code y reinstala |
| La orden 3 403 / sin salida / tiempo de espera agotado | Descarga y red | «Problemas de descarga y red» |
| El número de versión se imprime, pero al iniciar se cierra o se queda colgado | Salud de la instalación | La orden 4 claude doctor; si sigue sin funcionar → «¿Todavía no funciona?» |
Diagnóstico de problemas frecuentes
Los títulos H4 de abajo son todos textos originales de errores (o síntomas tal como los lista la documentación oficial); hazlos coincidir literalmente. Cada grupo corresponde a una etapa de la verificación rápida.
Problemas de descarga y red
"syntax error near unexpected token '<'"
Causa: lo que descargó el comando de instalación no es un script, sino una página web: bash ejecutó como comando la primera línea de la página, <!DOCTYPE html>. Suele deberse a problemas de red, enrutamiento regional o fallos temporales del servicio. La manifestación correspondiente en Windows: CMD reporta < was unexpected at this time., y PowerShell muestra una serie de errores de análisis que citan HTML/CSS.
Solución:
Espera unos minutos y reintenta el comando original: este problema suele ser temporal.
Si sigue sin funcionar, cambia de canal de instalación (atención: lo instalado con Homebrew / WinGet no se actualiza automáticamente, hay que actualizar a mano):
macOS:
bashbrew install --cask claude-codeWindows:
powershellwinget install Anthropic.ClaudeCodeAbre un terminal nuevo y verifica:
bashclaude --versionDeberías ver: un número de versión, con la forma
2.1.211 (Claude Code). Si tras instalar sigue diciendo que no encuentra el comando, abre una ventana de terminal nueva e inténtalo de nuevo: la sesión donde lo instalaste todavía tiene el PATH antiguo.
¿El error menciona App unavailable in region? Ve directamente a la entrada de regiones de abajo.
"curl: (22) The requested URL returned error: 403"
Causa: el servidor de descarga bloqueó la petición. Dos orígenes frecuentes: un proxy / filtro de red interceptó downloads.claude.ai, o tu región no está en la lista oficial de regiones admitidas.
Solución:
Primero ejecuta la verificación de conectividad de la orden 3 de la verificación rápida:
bashcurl -sI https://downloads.claude.ai/claude-code-releases/latest403→ proxy/filtro de red, o problema de región (ver la entrada siguiente)5xx→ fallo temporal del servicio, espera unos minutos y reintenta- Sin salida /
Could not resolve host/ tiempo de conexión agotado → la red bloquea la conexión: firewall corporativo, restricciones de red regionales o problema de TLS (ver la entrada de TLS)
Si en una región admitida sigue dando 403 → revisa el proxy. En una red corporativa, pide a IT la dirección del proxy, configúrala antes de instalar y luego ejecuta el comando de instalación:
bashexport HTTP_PROXY=http://proxy.example.com:8080 export HTTPS_PROXY=http://proxy.example.com:8080 curl -fsSL https://claude.ai/install.sh | bashWindows PowerShell:
powershell$env:HTTP_PROXY = 'http://proxy.example.com:8080' $env:HTTPS_PROXY = 'http://proxy.example.com:8080' irm https://claude.ai/install.ps1 | iexNo te apresures a cambiar de canal: los instaladores alternativos se conectan a los mismos servidores; si la red no funciona, cambiar de canal no sirve de nada, arregla primero la red.
"curl: (35) TLS connect error"
Causa: fallo en el handshake TLS: certificados CA del sistema desactualizados, un proxy corporativo que inspecciona TLS, o que Windows PowerShell 5.1 no tiene habilitado TLS 1.2 por defecto. Errores de la misma familia: Could not create SSL/TLS secure channel, unable to get local issuer certificate, SELF_SIGNED_CERT_IN_CHAIN.
Solución:
Actualiza los certificados CA del sistema. Ubuntu / Debian:
bashsudo apt-get update && sudo apt-get install ca-certificatesEl curl del sistema en macOS usa el almacén de confianza del llavero; basta con actualizar macOS.
En Windows PowerShell 5.1, primero habilita TLS 1.2 y luego ejecuta el instalador en la misma ventana:
powershell[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 irm https://claude.ai/install.ps1 | iexUn proxy corporativo que inspecciona TLS provoca este tipo de errores: pide a IT el certificado CA del proxy y añade
--cacertal comando de instalación basado en curl:bashcurl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash
"App unavailable in region"
Causa: tu región no está en la lista oficial de regiones admitidas de Anthropic: la lista no incluye China continental, Hong Kong ni Macao. Es una restricción de política oficial, no un fallo de instalación.
Solución:
- Ve a la página oficial de países admitidos para verificar tu región.
- Cambiar de canal de instalación no lo evita: npm, Homebrew y WinGet se conectan al mismo servicio, y la restricción regional no cambia según el método de instalación.
- Si quieres empezar ahora mismo con vibe coding, cambia a herramientas que no requieren cuenta extranjera: WorkBuddy (de Tencent, inicio de sesión escaneando con WeChat, cero línea de comandos) o OpenCode, que admite modelos nacionales. Para elegir, consulta cómo elegir entre las cuatro herramientas; para instalar WorkBuddy, mira métodos alternativos de instalación.
Problemas con comandos de instalación en Windows
"'irm' is not recognized as an internal or external command"
Causa: irm es un comando de PowerShell y ejecutaste el comando de instalación para PowerShell en CMD; el comando y el shell no coinciden.
Solución (elige una de dos):
Opción 1: abre PowerShell — busca "PowerShell" en el menú Inicio y ejecuta el comando original:
irm https://claude.ai/install.ps1 | iexOpción 2: quédate en CMD y usa el comando de instalación para CMD:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmdAl terminar, abre una terminal nueva y ejecuta claude --version para verificar.
De paso: The token '&&' is not a valid statement separator es el error inverso — ejecutaste un comando de CMD en PowerShell; usa igualmente la versión irm.
"A parameter cannot be found that matches parameter name 'fsSL'"
Causa: ejecutaste el comando curl -fsSL ... | bash de macOS / Linux en Windows PowerShell — en PowerShell, curl es un alias de Invoke-WebRequest y no reconoce parámetros como -fsSL.
Solución: en Windows, usa el comando de instalación para PowerShell:
irm https://claude.ai/install.ps1 | iexAbre una terminal nueva y ejecuta claude --version para verificar.
Problemas de disponibilidad del comando (PATH)
"zsh: command not found: claude"
Causa: sí se instaló, pero el directorio de instalación ~/.local/bin no está en el PATH y el shell no encuentra claude. El instalador de hecho te lo advirtió: Native installation exists but ~/.local/bin is not in your PATH.. El error equivalente en Linux es bash: claude: command not found.
Solución (macOS / Linux, se configura el PATH una vez y queda permanente):
Confirma si el archivo existe:
bashls -la ~/.local/bin/claudeDeberías ver: una línea con el listado del archivo.
No such file or directory= no se instaló en absoluto; vuelve a Instalar Claude Code para reinstalar.Comprueba si este directorio está en el PATH:
bashecho $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"Hay salida = está en el PATH, el problema está en otra parte; mira los puntos de diagnóstico del paso 4; sin salida = no está, añádelo en el siguiente paso.
Escríbelo en la configuración del shell para que surta efecto de inmediato. En macOS el predeterminado es zsh:
bashecho 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrcEn Linux, bash por defecto escribe en
~/.bashrc; en macOS con bash, escribe en~/.bash_profile(la terminal de macOS inicia bash como shell de inicio de sesión y no lee~/.bashrc).Verifica:
bashclaude --versionDeberías ver: el número de versión. ¿Sigue sin encontrarse? Tres causas habituales:
- La terminal antigua conserva el PATH viejo — abre una ventana nueva;
- La terminal integrada del editor hereda el PATH del editor — cierra y reinicia el editor;
- La configuración se escribió en el archivo de otro shell — usa
echo $0para ver cuál es el shell actual y configura ese shell.
"'claude' is not recognized as an internal or external command"
Causa: el mismo problema de PATH en su versión para Windows — %USERPROFILE%\.local\bin no está en el PATH. En PowerShell el error se ve así: claude : The term 'claude' is not recognized as the name of a cmdlet.
Solución (PowerShell):
Confirma si el archivo existe:
powershellTest-Path "$env:USERPROFILE\.local\bin\claude.exe"Deberías ver:
True.False= no está instalado; vuelve a la lección de instalación para reinstalar.Añádelo al PATH del usuario (se configura una sola vez):
powershell$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User') [Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')Reinicia la terminal y ejecuta
claude --versionpara verificar. Si aún no funciona, comprueba si la salida de[Environment]::GetEnvironmentVariable('PATH', 'User')contiene.local\bin; si no, repite el paso 2; la terminal integrada del editor requiere reiniciar el editor.
Usuarios de CMD: dir "%USERPROFILE%\.local\bin\claude.exe" para confirmar el archivo, echo %PATH% | findstr /i "local\bin" para comprobar el PATH; si no está, ve a Configuración del sistema → Variables de entorno, añade %USERPROFILE%\.local\bin al PATH del usuario y reinicia la terminal.
Caso especial: en Windows, si acabas de actualizar y aparece este error → puede que la actualización haya movido claude.exe a una copia de seguridad. El comando de recuperación que da la documentación oficial (renombra la copia de seguridad más reciente con el nombre original):
Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exeSi no hay copia de seguridad claude.exe.old.* o si tras el cambio sigue sin funcionar → reinstala: irm https://claude.ai/install.ps1 | iex.
Problemas de instalación con npm
"running scripts is disabled on this system"
Causa: instalaste Claude Code con npm en Windows y la política de ejecución de PowerShell bloqueó el script de arranque .ps1 generado por npm (el error también menciona PSSecurityException). Al ejecutar claude, el error señala claude.ps1. El instalador oficial de PowerShell no se ve afectado: ejecuta directamente el texto descargado, sin pasar por un archivo de script.
Solución (elige una de tres):
Permite los scripts locales (solo afecta al usuario actual) y reintenta:
powershellSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserCambia al lanzador
.cmd:npm.cmd,claude.cmdhacen el mismo trabajo y la política de ejecución no los alcanza.Usa el instalador oficial de PowerShell — instala un binario, no un
.ps1:powershellirm https://claude.ai/install.ps1 | iex
"Error: claude native binary not installed."
Causa: el claude del paquete npm es solo un script de marcador de posición; el paso postinstall se encarga de sustituirlo por el binario real (el binario se publica por plataforma como dependencia opcional, p. ej. @anthropic-ai/claude-code-darwin-arm64). Si la descarga o el postinstall se omiten, el script de marcador se queda. Los disparadores más habituales: npm 12 omite postinstall por defecto, --omit=optional desactiva las dependencias opcionales, --ignore-scripts desactiva los scripts de instalación.
Solución:
Primero ejecuta
npm --version— si empieza con 12, es un problema de npm 12; sigue una de las dos opciones siguientes.Opción 1 (recomendada, solución definitiva): cambia al instalador nativo oficial y luego desinstala la versión de npm:
bashcurl -fsSL https://claude.ai/install.sh | bash npm uninstall -g @anthropic-ai/claude-codeTras el cambio, las actualizaciones no pasan por npm y este error no volverá.
Opción 2: quédate con npm — añade Claude Code a
allow-scriptsy reinstala:bashnpm config set "allow-scripts=@anthropic-ai/claude-code" --location=user npm install -g @anthropic-ai/claude-codeTen en cuenta dos cosas: primero, actualiza npm 12.0.x con
npm install -g npm@latesta 12.1 o superior; antes de configurar, ejecutanpm config get allow-scriptspara ver la lista existente — el comando de configuración reemplaza por completo la lista, así que si contiene otros paquetes, inclúyelos también entre comillas. Si este paso daEACCES, no añadas sudo; cambia directamente a la opción 1.El mensaje de error también ofrece una solución manual (ajusta tú mismo las rutas de instalación global/local):
bashnode node_modules/@anthropic-ai/claude-code/install.cjs
"EACCES: permission denied"
Causa: el directorio que la instalación necesita escribir no tiene permiso de escritura. El instalador nativo en macOS / Linux escribe en ~/.claude/downloads/, ~/.local/bin/, ~/.local/share/claude/ y otras ubicaciones; si la instalación con npm da EACCES, se trata de un problema de permisos en el directorio global de npm.
Solución:
Comprueba si el directorio es escribible:
bashtest -w ~/.local/bin && echo "writable" || echo "not writable" test -w ~/.claude && echo "writable" || echo "not writable"Si no es escribible, crea el directorio y recupera la propiedad:
bashsudo mkdir -p ~/.local/bin sudo chown -R $(whoami) ~/.localEACCES al instalar con npm → no reintentes con sudo, cambia al instalador nativo oficial:
bashcurl -fsSL https://claude.ai/install.sh | bashCausa: Claude Code no debe ejecutar npm con sudo cuando se actualiza a sí mismo; los paquetes instalados con sudo fallarán de la misma manera en sus actualizaciones automáticas.
"npm error code ENOTEMPTY"
Causa: al reinstalar o actualizar sobre una instalación existente, npm descubre que el directorio del paquete antiguo no está vacío al moverlo y el rename falla — normalmente son directorios residuales dejados por una instalación interrumpida anteriormente.
Solución:
Mira el directorio señalado en la línea
npm error pathdel error — ese es el directorio que npm no puede mover.Elimínalo junto con los directorios temporales residuales
.claude-code-*de al lado (macOS / Linux):bashrm -rf "$(npm root -g)/@anthropic-ai/claude-code" rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*Si Zsh da
no matches found= no hay residuos que eliminar, es normal. Windows PowerShell:powershellRemove-Item -Recurse -Force "$(npm root -g)/@anthropic-ai/claude-code", "$(npm root -g)/@anthropic-ai/.claude-code-*"Nota: si el directorio señalado en el error no está bajo
npm root -g(por ejemplo, si cambiaste la versión de Node con nvm), elimina siguiendo la ruta indicada en el error, no adivines con el comando de arriba.Reinstala y verifica:
bashnpm install -g @anthropic-ai/claude-code claude --version
Problemas de inicio de sesión y autenticación
Cuando el inicio de sesión se queda colgado sin causa aparente, ejecuta primero los «tres pasos» recomendados oficialmente, que resuelven la mayoría de los casos:
- En la sesión, escribe
/logoutpara cerrar sesión por completo - Cierra Claude Code
- Vuelve a ejecutar
claudey completa todo el proceso de autenticación
¿El navegador no se abre automáticamente? Pulsa c para copiar la URL de inicio de sesión y pégala manualmente en el navegador. Este truco también funciona cuando el enlace se parte en varias líneas en un terminal SSH estrecho y no se puede hacer clic.
"OAuth error: Invalid code. Please make sure the full code was copied"
Causa: el código de inicio de sesión caducó o quedó truncado al copiarlo.
Solución:
- Pulsa Enter para reintentar y completa el inicio de sesión lo antes posible tras abrirse el navegador.
- Si el navegador no se abre automáticamente: escribe
cpara copiar la URL completa y abre el navegador manualmente. - SSH / sesión remota: el navegador puede haberse abierto en la máquina remota — copia la URL mostrada en el terminal y ábrela en tu navegador local.
"API Error: 403 Request not allowed"
Causa: el inicio de sesión funcionó, pero la solicitud fue rechazada. Hay tres posibilidades, con el mismo síntoma, identifica la tuya: suscripción inactiva, cuenta de Console sin el rol correcto o un proxy interfiriendo con las solicitudes a la API.
Solución:
- Usuarios de Claude Pro / Max / Ultra: ve a claude.ai/settings y confirma que la suscripción está activa.
- Usuarios de Anthropic Console: pide a un administrador que en platform.claude.com/settings/members añada a tu cuenta el rol "Claude Code" o "Developer".
- El proxy corporativo puede interferir con las solicitudes a la API: revisa la configuración de proxy en la configuración de red.
"Claude Code access has not been granted for this account"
Causa: la organización de Claude Enterprise estableció tu rol como Custom, y ninguno de los roles personalizados asignados incluye el permiso de Claude Code. Por mucho que cambies cosas en Claude Code no servirá; tiene que hacerlo un administrador.
Solución:
- Busca al Owner de la organización: que asigne a tu grupo un rol personalizado con Claude Code, o que cambie tu rol de Custom a un rol estándar como User (los roles se gestionan en los role settings de la organización).
- Tras el cambio, ejecuta
claudepara iniciar sesión de nuevo.
"This organization has been disabled"
Causa: la suscripción está claramente activa pero se informa que la organización está deshabilitada — lo más probable es que una variable de entorno ANTHROPIC_API_KEY residual en el shell esté sobrescribiendo el inicio de sesión con suscripción. Lo más común: una key de una empresa anterior o de un proyecto antiguo sigue en la configuración.
Solución:
Para esta sesión, elimínala antes de iniciar (macOS / Linux):
bashunset ANTHROPIC_API_KEY claudeWindows PowerShell:
powershellRemove-Item Env:ANTHROPIC_API_KEY claudeEliminación permanente: revisa las líneas
export ANTHROPIC_API_KEY=...en~/.zshrc,~/.bashrc,~/.profiley bórralas; en Windows revisa el profile de PowerShell ($PROFILE) y las variables de entorno de usuario.Ejecuta
/statusen la sesión para confirmar que el método de autenticación vigente es la suscripción y no una API key.
¿Sigue sin funcionar?
Recopila evidencia antes de preguntar. Sistema operativo + el comando de instalación que ejecutaste + el texto completo del error valen más que cien descripciones. Si claude --version puede imprimir la versión, incluye también el informe de autodiagnóstico oficial:
# 证据三件套:版本、官方诊断报告、下载服务器连通性
claude --version # 能出版本号,claude doctor 才跑得起来
claude doctor # 官方自动诊断报告
curl -sI https://downloads.claude.ai/claude-code-releases/latest # 网络连通性(Windows 用 curl.exe)Dónde preguntar:
| Canal | Cuándo acudir |
|---|---|
| GitHub Issues | Problemas de instalación: busca primero en los issues conocidos; si no hay, abre uno nuevo adjuntando sistema operativo, comando de instalación y error completo |
claude doctor | La versión se imprime pero el comportamiento es incorrecto: mira primero qué dice el informe de diagnóstico |
/feedback | Puedes entrar en la sesión: informa del problema directamente desde la sesión |
| Soporte de Anthropic | Problemas de cuenta: bucle de inicio de sesión, suscripción no reconocida, organización deshabilitada — inicia sesión en claude.ai, haz clic en el avatar de la esquina inferior izquierda y elige Get help |
Punto de control ✅
- He ejecutado los 4 comandos de verificación rápida y sé en qué punto me quedé atascado
command not found: primero compruebo si el archivo existe, luego el PATH — se configura una vez y queda vigente para siempre- El texto del error coincide con una entrada del H4; tras arreglarlo siguiendo los pasos, verifico con
claude --version - Si el inicio de sesión se atasca, ejecuto primero los tres pasos «cerrar sesión → reabrir → volver a iniciar sesión», y luego identifico el síntoma entre suscripción / rol / API key
- Antes de preguntar preparo el trío: sistema operativo + comando de instalación + texto completo del error
Resumen de la lección
✅ Con Claude Code, ante un fallo de instalación localiza primero la etapa y luego mira el error: descarga (red/región) → instalación (comando/permisos/npm) → comando disponible (PATH) → inicio de sesión (autenticación/suscripción/rol).
✅ Todos los errores frecuentes tienen solución: command not found es una configuración única de PATH; 403, si un script se convierte en página web, primero revisa la red y luego cambia de canal; los tres grandes fallos de npm (EACCES, npm 12 que salta postinstall, ENOTEMPTY) se resuelven de la forma más sencilla cambiando al instalador nativo oficial.
✅ Los problemas de inicio de sesión se clasifican por síntoma: para la suscripción revisa settings, para el rol busca al administrador, si una API key sobrescribe, limpia las variables de entorno; aplica primero los tres pasos básicos (cerrar sesión → reiniciar → volver a iniciar sesión).
✅ La verificación tras reparar es siempre la misma: en un terminal nuevo, claude --version debe mostrar el número de versión.
Consulta rápida de errores clave:
| Error | en qué paso se queda atascado | primer paso |
|---|---|---|
zsh: command not found: claude | comando disponible | ls -la ~/.local/bin/claude para revisar el archivo, luego configurar PATH |
syntax error near unexpected token '<' | descarga | espera unos minutos y reintenta; si no funciona, cambia a Homebrew / WinGet |
curl: (22) The requested URL returned error: 403 | descarga | curl -sI https://downloads.claude.ai/claude-code-releases/latest para comprobar la conectividad |
Error: claude native binary not installed. | npm | cambiar al instalador nativo oficial |
OAuth error: Invalid code. Please make sure the full code was copied | inicio de sesión | pulsa Enter para reintentar; c copia la URL y abre el navegador manualmente |
Vista previa de la próxima lección
Instalado, con sesión iniciada, la depuración inicial termina aquí: tus herramientas ya están listas. El siguiente paso es entrar en uso diario: el uso correcto de cada una de las cuatro herramientas.
Aprenderás:
- Uso correcto de Claude Code en el terminal: cómo empezar y cómo conversar
- Codex, OpenCode, WorkBuddy: la forma correcta de abrir cada uno
- Comparación de precios de las cuatro herramientas: cuánto cuesta, con claridad
Tutoriales relacionados
- Instalación de Claude Code: listo en 10 minutos de preparación
- Formas alternativas de instalación: npm, Homebrew, WinGet y la versión de escritorio de WorkBuddy
- Cómo elegir entre las cuatro herramientas: Claude Code, Codex, OpenCode, WorkBuddy
- Bucle de errores: alimenta el mensaje de error tal cual de vuelta