Instalar Claude Code — un comando y dos puntos donde se atasca después

La instalación de Claude Code es una sola orden; el verdadero bloqueo aparece después. La mayoría de los artículos sobre la instalación terminan en «instalación completada», pero en Corea hay dos barreras más antes de poder ejecutarlo: los permisos de instalación global y el inicio de sesión y el pago. Este artículo explica los tres pasos en orden, incluida la solución para cada bloqueo.

Paso 1: instalación (una sola orden)

El único requisito previo es Node.js 18 o superior. macOS, Windows (WSL) y Linux utilizan el mismo comando.

# Node.js 18 이상이 필요합니다. 먼저 확인하세요.
node --version

# 설치
npm install -g @anthropic-ai/claude-code

# 확인 — 버전이 출력되면 설치 자체는 끝난 것입니다
claude --version

Si claude --version muestra esta versión, la instalación ha terminado. Si te detienes aquí, corresponde a una de las dos secciones siguientes.

Paso 2: errores de permisos y rutas

Estos son los dos errores más frecuentes durante la instalación.

No recomendamos añadir EACCES a sudo. La instalación funcionará de inmediato, pero el mismo problema reaparecerá con cada actualización y el propietario del directorio global pasará a ser root, complicándolo todo. Es más limpio mover la ruta al directorio personal.

# npm 전역 설치에서 EACCES가 나면 sudo를 붙이지 말고
# 전역 경로를 홈 디렉터리로 옮기는 편이 안전합니다.
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global

# 셸 설정에 추가한 뒤 새 터미널을 엽니다
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc

En Windows, instálalo dentro de WSL. Los archivos del proyecto también deben estar en el sistema de archivos de WSL para que la vigilancia de archivos y el tratamiento de rutas funcionen correctamente.

Paso 3: inicio de sesión y pago (donde realmente se bloquea en Corea)

Cuando termina la instalación y ejecutas claude, se te solicita iniciar sesión. Es el punto donde más usuarios se detienen en Corea, y la causa no tiene relación con la instalación.

• Tarjeta con los pagos internacionales bloqueados: falla al pagar la suscripción. En la mayoría de los casos, se soluciona permitiendo los pagos internacionales en la aplicación o el sitio web de la entidad emisora.
• KakaoPay y Toss: no son compatibles con los pagos web de claude.ai (solo están disponibles como métodos de pago de las tiendas para suscripciones en aplicaciones móviles). Esperar un método de pago local sencillo provoca el bloqueo en este paso.
• Si no tienes una tarjeta que permita pagos internacionales, no puedes usar la ruta de suscripción web. La autenticación mediante clave que aparece a continuación recarga y utiliza el saldo de Kunavo; cuando la pantalla muestra wones, ofrece KakaoPay, Naver Pay, PAYCO, Samsung Pay y tarjetas nacionales (incluidas las tarjetas sin pagos internacionales habilitados) como métodos de pago, por lo que puedes recargar sin una tarjeta para pagos internacionales (TOSS no es compatible).

Qué funciona y qué no según el método de pago está resumido en Métodos de pago de Claude.

Si el pago de la suscripción está bloqueado: ejecútalo con una clave tal como está instalado

Además del inicio de sesión mediante suscripción, Claude Code admite autenticación con clave de API. Si configuras las dos variables de entorno siguientes, se ejecutará sin mostrar la pantalla de inicio de sesión; si las eliminas, volverá al comportamiento original. No es necesario reinstalarlo.

# 구독 결제가 막혔을 때 설치한 클로드 코드를 그대로 쓰는 방법.
# 이 두 줄이 있으면 로그인 대신 키로 인증하고, 지우면 원래대로 돌아갑니다.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# 클로드 코드의 기본 모델과 opus·sonnet 별칭은 Anthropic의 최신 모델을 따라가므로,
# Kunavo가 제공하는 모델로 고정해 404를 막습니다. sonnet 별칭은 Kunavo가 제공하지
# 않는 Sonnet 5.5를 요청하므로, 고정하지 않으면 /model sonnet, opusplan의 실행 단계,
# sonnet 서브에이전트가 404로 실패합니다. opus는 Opus 5.5로 고정하며,
# 클로드 코드 v2.1.280 이상이 필요합니다(이전 버전은 claude update).
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

claude

Con este método se cobran únicamente los tokens utilizados en lugar de una tarifa mensual, por lo que no hay coste durante los meses en que no trabajes. El procedimiento para obtener una clave está en Obtener una clave de API de Claude; cuál resulta más barato, la suscripción o el pago por uso, se explica en Precios de Claude Code.

Primera ejecución tras la instalación: comprobación de 3 minutos

Cuando se ejecute, inicia claude en el directorio del proyecto y ejecuta /init una vez. Leerá el repositorio y creará CLAUDE.md, que se leerá automáticamente en todas las sesiones posteriores. La operación a partir de aquí — escribir reglas, configurar permisos y crear comandos personalizados — continúa en Cómo usar Claude Code.

Los errores que aparecen después de la ejecución (401, 429 y 529) tienen causas completamente distintas de las de la fase de instalación. La forma de diferenciarlos está resumida en Errores de Claude Code.

Preguntas frecuentes