Cómo instalar Claude Code en Windows, macOS y Linux: clave API sin suscripción y pago con BLIK

Claude Code se instala con un único comando oficial (a continuación se incluyen las versiones para macOS y Linux, PowerShell y CMD). Anthropic recomienda el instalador nativo, mientras que npm es una alternativa que requiere Node.js 22 o posterior. Sin una suscripción Pro/Max y sin iniciar sesión, basta con configurar ANTHROPIC_BASE_URL=https://api.kunavo.com (sin /v1), ANTHROPIC_AUTH_TOKEN con la clave de API y cuatro variables que fijan los modelos. De este modo, solo paga los tokens utilizados con el saldo que recargue mediante BLIK en zlotys, desde 10 USD. Por último, escriba /status en Claude Code para comprobar que la clave funciona.

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

:: Windows – wiersz polecenia (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Polecenia i zmienne sprawdziliśmy 3 października 2026 w documentación oficial de instalación de Claude Code i w documentación de las variables de entorno. Polskiej wersji tej dokumentacji nie ma. Ceny i metody płatności sprawdziliśmy 3 października 2026. Polska jest na lista de países compatibles con Anthropic (sprawdzone 3 października 2026), zarówno dla Claude.ai, jak i dla API.

¿Inicio de sesión o clave de API?

Después de la instalación, Claude Code debe autenticarse. Hay dos opciones, y esta guía describe detalladamente la segunda:

Antes de comenzar

Método 1: instalador nativo (recomendado)

En la documentación oficial, este método tiene la pestaña «Native Install (Recommended)». Los comandos se encuentran al principio de la página. En macOS, Linux y WSL se utiliza la línea con install.sh. En Windows PowerShell, utilice irm … | iex; en el símbolo del sistema CMD, la línea con install.cmd. La instalación nativa se actualiza automáticamente en segundo plano. Claude Code también puede instalarse mediante Homebrew o WinGet, pero según la documentación estas instalaciones no se actualizan automáticamente de forma predeterminada, por lo que debe actualizarlas manualmente en el gestor de paquetes:

# Homebrew – kanał stable; domyślnie nie aktualizuje się sam
brew install --cask claude-code

# WinGet (Windows) – domyślnie nie aktualizuje się sam
winget install Anthropic.ClaudeCode

Después de la instalación, abra una ventana de terminal nueva, porque una ventana abierta anteriormente no ve la variable PATH actualizada. Después, compruebe:

claude --version   # wypisuje numer wersji, np. 2.1.280 (Claude Code)
claude doctor      # diagnostyka instalacji i ustawień, bez otwierania sesji

claude doctor no abre una sesión. Solo muestra el estado de la instalación y el diagnóstico de los archivos de configuración. Esto permite distinguir rápidamente un problema de instalación de uno de configuración.

Cuando la descarga falla

Jeśli terminal pokazuje syntax error near unexpected token '<' albo curl: (22) The requested URL returned error: 403, to według página oficial sobre problemas de instalación (sprawdzone 3 października 2026) adres instalatora zwrócił stronę HTML lub kod błędu zamiast skryptu. Strona z napisem App unavailable in region oznacza według dokumentacji, że Claude Code nie jest dostępny w Twoim kraju. Polska jest jednak na liście obsługiwanych krajów, więc jeśli widzisz ten napis w Polsce, sprawdź, czy połączenie nie wychodzi przez VPN albo proxy. Samo 403 bez treści może też pochodzić z firmowego proxy lub zapory, która blokuje pobieranie. Dokumentacja radzi wtedy najpierw sprawdzić połączenie sieciowe, bo inne metody instalacji łączą się z tymi samymi serwerami. Spróbuj z innej sieci albo poproś administratora o odblokowanie tych adresów.

Método 2: npm (Node.js 22 o posterior)

npm nadal jest jedną z metod opisanych w oficjalnej dokumentacji. Pakiet wymaga Node.js 22 lub nowszego. Część polskich poradników wciąż podaje Node.js 18, co jest już nieaktualne. Na starszym Node.js npm wypisze ostrzeżenie EBADENGINE, ale nie przerwie instalacji, a claude będzie działać, bo pakiet pobiera natywny program, który nie korzysta z Node.js w czasie działania. Jeśli nie masz Node.js, zainstaluj wersję 22 lub nowszą ze página nodejs.org.

node -v                                    # potrzebna wersja v22 lub nowsza
npm install -g @anthropic-ai/claude-code   # bez sudo

# aktualizacja: @latest, a nie npm update -g
npm install -g @anthropic-ai/claude-code@latest

• No utilice nunca sudo npm install -g. La documentación advierte que esto provoca problemas de permisos y supone un riesgo para la seguridad.
• Actualice mediante @latest. Para actualizar, utilice npm install -g @anthropic-ai/claude-code@latest, no npm update -g.
• No omita las dependencias opcionales. El programa correcto se instala como una dependencia opcional, es decir, el paquete @anthropic-ai/claude-code-* correspondiente a su plataforma. Con la opción --omit=optional o con optional=false en .npmrc, la instalación en macOS o Linux termina con el mensaje claude native binary not installed.

Claude Code en Windows: PowerShell, CMD, WSL y PATH

Windows tiene dos comandos de instalación diferentes, y la elección depende únicamente del terminal. Si la línea comienza por PS C:\Users\TwojaNazwa>, trabajas en PowerShell. Si ves solo C:\Users\TwojaNazwa>, sin PS, es el símbolo del sistema (CMD). Según la documentación, no es necesario ejecutar el terminal como administrador, aunque algunas guías lo recomiendan.

El error más común es pegar el comando en el terminal equivocado. Una línea para CMD pegada en PowerShell produce The token '&&' is not a valid statement separator. Una línea para PowerShell pegada en CMD produce 'irm' is not recognized as an internal or external command. En Windows en polaco, el mismo mensaje dice: «irm» no se reconoce como un comando interno o externo, programa ejecutable o archivo por lotes. Por otro lado, una línea curl … | bash de macOS pegada en PowerShell termina con el error A parameter cannot be found that matches parameter name 'fsSL' o 'bash' is not recognized as the name of a cmdlet. En todos estos casos, basta con usar la línea destinada a tu terminal.

En el menú Inicio hay dos entradas: «Windows PowerShell» y «Windows PowerShell (x86)». La segunda funciona como un proceso de 32 bits, por lo que incluso en un equipo de 64 bits termina con el error Claude Code does not support 32-bit Windows. Abre la entrada sin el sufijo (x86).

Git for Windows jest opcjonalny, ale zalecany. Gdy jest zainstalowany, Claude Code wykonuje polecenia przez dołączony do niego Git Bash, a bez niego przez PowerShell. Jeśli Git jest zainstalowany, ale Claude Code nie znajduje Git Bash, ustaw w bloku env pliku ~/.claude/settings.json zmienną CLAUDE_CODE_GIT_BASH_PATH ze ścieżką do bash.exe. Przykładowa ścieżka z dokumentacji to C:\Program Files\Git\bin\bash.exe.

Si eliges WSL, ejecuta la línea para macOS y Linux en el terminal de WSL y también inicia allí claude, no en PowerShell ni en CMD.

Error de la política de ejecución de scripts (npm en PowerShell)

El mensaje npm.ps1 cannot be loaded because running scripts is disabled on this system durante la instalación o la ejecución mediante npm significa que la política de ejecución (execution policy) de PowerShell bloquea el script de inicio .ps1 generado por npm. Según la documentación, puedes permitir que el usuario actual ejecute scripts locales (con el comando siguiente), usar npm.cmd y claude.cmd o cambiar al instalador nativo para PowerShell.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

El comando «claude» no se reconoce después de la instalación

command not found: claude o 'claude' is not recognized significa que el directorio de instalación no está en PATH. El instalador nativo coloca el programa en ~/.local/bin/claude en macOS y Linux, y en %USERPROFILE%\.local\bin\claude.exe en Windows. Primero, abre un terminal nuevo. Si en Windows sigue sin funcionar, comprueba y añade la ruta en PowerShell tal como indica la documentación:

# 1. Sprawdź, czy katalog instalacji jest już w PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Brak wyniku? Dopisz go do PATH użytkownika, zamknij i otwórz terminal
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. W nowym terminalu
claude --version

Clave API en lugar de inicio de sesión (sin suscripción)

ANTHROPIC_BASE_URL es una variable integrada de Claude Code. Según la documentación oficial, sobrescribe el endpoint de la API para dirigir las solicitudes a través de un proxy o una puerta de enlace (gateway). Por tanto, conectar Claude Code a un servicio compatible con Anthropic Messages API es una configuración prevista por Anthropic. No necesitas complementos ni un programa modificado. En macOS y Linux, añade las variables al archivo de configuración del shell (~/.zshrc o ~/.bashrc):

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # sama domena, bez /v1
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
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

En Windows, primero puedes comprobar la configuración en una ventana de PowerShell:

# Działa tylko w tym oknie PowerShella – po zamknięciu znika
$env:ANTHROPIC_BASE_URL = "https://api.kunavo.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-kn-..."
$env:ANTHROPIC_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "claude-opus-5-5"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-4-5"
claude

Para dejarlo permanente, lo mejor es escribir las variables en el bloque env del archivo de configuración del usuario ~/.claude/settings.json (en Windows, %USERPROFILE%\.claude\settings.json). Según la documentación, este archivo se aplica a todos tus proyectos. Si el archivo ya contiene otros ajustes, añade únicamente el bloque env:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Es fácil equivocarse en cualquiera de estas seis líneas:

• ANTHROPIC_BASE_URL es solo el dominio. Claude Code añade automáticamente /v1/messages. Con /v1 al final, la solicitud llegará a /v1/v1/messages y devolverá un 404.
• ANTHROPIC_AUTH_TOKEN, no ANTHROPIC_API_KEY. El valor de ANTHROPIC_AUTH_TOKEN se envía en el encabezado Authorization con el prefijo Bearer y funciona de inmediato. ANTHROPIC_API_KEY se envía en el encabezado x-api-key y, en modo interactivo, hay que aprobarlo una vez. Si lo rechazas entonces, la clave se ignorará silenciosamente. Puedes volver a activarla en /config → Use custom API key.
• ANTHROPIC_MODEL selecciona el modelo principal. Aquí es Claude Sonnet 5 (claude-sonnet-5). El nombre debe coincidir exactamente con el de la lista de modelos de Kunavo. Kunavo no reconoce los nombres antiguos con una fecha al final.
• ANTHROPIC_DEFAULT_OPUS_MODEL y ANTHROPIC_DEFAULT_SONNET_MODEL fijan los alias opus y sonnet. Według documentación oficial de configuración de modelos (sprawdzone 3 października 2026) dla użytkowników API model domyślny i alias opus wskazują Opus 5.5, a alias sonnet wskazuje Sonnet 5.5. Aliasy z czasem się zmieniają, a wersję przypina się pełną nazwą modelu albo zmiennymi takimi jak te dwie. Zapytanie o model, którego nie ma w Kunavo, zwraca 404. Alias opus przypinamy do Claude Opus 5.5 (claude-opus-5-5), bo kolejny Opus wydany przez Anthropic nie musi być od razu dostępny w Kunavo. Opus 5.5 wymaga Claude Code w wersji 2.1.280 lub nowszej, starszą wersję zaktualizujesz poleceniem claude update. Sonnet 5.5 nie jest obecnie (stan na 3 października 2026) dostępny w Kunavo, więc bez przypięcia aliasu sonnet do claude-sonnet-5 błąd 404 zwracają /model sonnet, faza wykonania w trybie opusplan i subagenci ustawieni na model: sonnet.
• ANTHROPIC_DEFAULT_HAIKU_MODEL también gestiona tareas en segundo plano. Según la documentación, esta variable selecciona el modelo para el alias haiku y para las funciones que se ejecutan en segundo plano. En Kunavo, Claude Haiku 4.5 cuesta 0,70 USD por millón de tokens de entrada y 3,50 USD por millón de tokens de salida. El modelo principal Claude Sonnet 5 cuesta 1,40 USD / 7,00 USD (lista de precios de Anthropic: 2,00 USD / 10,00 USD), mientras que Claude Opus 5.5 cuesta 2,80 USD / 14,00 USD (entrada / salida, por millón de tokens).

Klucza no wpisuj do projektowego .claude/settings.json. Według documentación sobre la conexión de una puerta de enlace ten plik trafia do repozytorium, a więc do każdego, kto je sklonuje. Pamiętaj też o kolejności pierwszeństwa. Gdy ta sama zmienna jest ustawiona i w powłoce, i w bloku env pliku ustawień, w większości sesji obowiązuje wartość z pliku ustawień. Osobna zasada dotyczy klucza model w pliku ustawień: zmienna ANTHROPIC_MODEL ma przed nim pierwszeństwo, a model działa tylko wtedy, gdy zmiennej nie ma. Jeśli zmiana w powłoce nie działa, najpierw sprawdź plik ustawień. W rozszerzeniu Claude Code dla VS Code zmienne ustawia się w claudeCode.environmentVariables, w ustawieniach użytkownika samego VS Code.

Primer inicio y /status

Según la documentación sobre la conexión de una puerta de enlace (comprobado 3 października 2026), con ANTHROPIC_AUTH_TOKEN configurado, el comando claude abre inmediatamente una sesión sin pantalla de inicio de sesión. La variable funciona de inmediato y no hay que aprobarla, a diferencia de ANTHROPIC_API_KEY. Si en su lugar ves la pantalla de inicio de sesión, Claude Code no ha leído la clave.

La clave debe estar donde Claude Code la lee antes de la primera configuración: establecida mediante export en el shell o en el bloque env del archivo de usuario ~/.claude/settings.json. En modo interactivo, el bloque env de .claude/settings.json o .claude/settings.local.json del proyecto empieza a funcionar solo después del asistente de primer inicio y de la pregunta sobre la confianza en la carpeta. Si la clave está únicamente en la configuración del proyecto, en el primer inicio seguirás viendo la pantalla de inicio de sesión.

En la sesión, escribe /status y comprueba estas dos líneas:

• Anthropic base URL aparece únicamente cuando se ha establecido la dirección de la puerta de enlace. Debería mostrar https://api.kunavo.com. Si no aparece esta línea, ANTHROPIC_BASE_URL no ha llegado a la sesión.
• Auth token con el nombre ANTHROPIC_AUTH_TOKEN significa que funciona una clave API, no el inicio de sesión guardado de claude.ai. Si ves Login method con una cuenta de claude.ai, la variable no ha funcionado.

También puedes comprobar la dirección y la clave antes de iniciar Claude Code, mediante el método de la documentación oficial. Consiste en enviar una solicitud de 1 token de salida, que descontará del saldo una cantidad simbólica. El comando lee las variables del shell actual, así que, aunque la clave esté en el archivo de configuración, primero establece las variables con export en este terminal. Una respuesta JSON que comience por {"id":"msg_ significa que la dirección y la clave funcionan. El código 401 significa que la clave fue rechazada.

curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

En PowerShell, la misma comprobación se ve así. Si todo funciona, en la respuesta verás el campo id que comienza por msg_:

Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Qué funciona de forma diferente con una clave API

• Remote Control y el dictado por voz no están disponibles. Según la documentación, requieren una identidad de claude.ai y no funcionan cuando ANTHROPIC_AUTH_TOKEN está activo. Desde la versión 2.1.196, Remote Control también se desactiva cuando ANTHROPIC_BASE_URL apunta a un host distinto de api.anthropic.com.
• /fast aparece como desactivado. Según la documentación, cuando solo hay un token bearer, Claude Code trata el modo rápido como desactivado y no envía una solicitud para comprobar su disponibilidad.
• La búsqueda de herramientas MCP está desactivada de forma predeterminada. Esto ocurre cuando ANTHROPIC_BASE_URL apunta a un host distinto de Anthropic.
• Los números de /context son estimaciones. Kunavo nie udostępnia endpointu /v1/messages/count_tokens. Według documentación de compatibilidad de puertas de enlace (sprawdzone 3 października 2026) Claude Code liczy wtedy tokeny lokalnie na podstawie liczby znaków.

Encontrarás una descripción completa de la integración en la documentación de integración de Claude Code (en inglés), y la versión en inglés de esta guía en el artículo Install Claude Code.

Pago mediante BLIK: recargar el saldo y obtener una clave API

Subskrypcje Claude kupowane przez stronę Anthropic można opłacić wyłącznie kartą kredytową lub debetową (Preguntas frecuentes sobre la facturación de Claude, sprawdzone 3 października 2026). BLIK-iem nie zapłacisz za Pro ani za Max. W Kunavo BLIK doładowuje przedpłacone saldo API, z którego Claude Code płaci za tokeny po ustawieniu klucza tak jak wyżej. Wszystkie kroki płatności opisuje poradnik cómo pagar Claude con BLIK, a w skrócie wygląda to tak:

1. Crea una cuenta de Kunavo mediante correo electrónico o una cuenta de Google. No tienes que proporcionar una tarjeta al registrarte.
2. En la pestaña Facturación (Billing), elige el importe de la recarga. El mínimo es 10 USD y no hay cuota mensual. Con importes mayores recibes un bono: 100 USD → 110 USD na saldzie, 1000 USD → 1200 USD na saldzie, 5000 USD → 6250 USD na saldzie.
3. Na stronie płatności Stripe kwota jest pokazana w złotych. Wybierz BLIK, wygeneruj w aplikacji bankowej sześciocyfrowy kod, wpisz go i potwierdź płatność w aplikacji. Według documentación de Stripe (sprawdzone 3 października 2026) kod BLIK jest ważny 2 minuty, a po rozpoczęciu płatności masz 60 sekund na jej zatwierdzenie.
4. En la pestaña Claves API, crea una clave que comience por sk-kn-. La clave solo se muestra una vez, así que guárdala inmediatamente e introdúcela en ANTHROPIC_AUTH_TOKEN.

Na stronie płatności w złotych oprócz BLIK-a są też karty (Visa, Mastercard), Apple Pay i Google Pay na obsługiwanych urządzeniach oraz Link. Nie ma natomiast Przelewy24, PayU, PayPal ani zwykłego przelewu bankowego. Ceny są ustalone w dolarach, a Stripe przelicza je na złote. Według documentación de Stripe sobre Adaptive Pricing (sprawdzone 3 października 2026) kurs zawiera opłatę za przewalutowanie w wysokości 2–4%, którą ponosi kupujący. Płacąc kartą w dolarach, unikniesz tej opłaty, choć wtedy obowiązują kurs i opłaty Twojego banku, a BLIK działa tylko w złotych. Dokładną kwotę w złotych zobaczysz na stronie płatności przed potwierdzeniem.

BLIK solo funciona para recargas manuales. La recarga automática requiere una tarjeta guardada o Link. El saldo no caduca y no pagas por las solicitudes fallidas. Kunavo no emite facturas con IVA; encontrarás el historial de recargas en la pestaña Facturación (Billing). Recuerda que esto es una recarga del saldo de la API de Kunavo, no el pago de Claude Pro o Max.

Cuánto cuesta (cálculo de ejemplo)

En Claude Code pagas por tokens. En cada solicitud, Claude Code vuelve a enviar todo el contexto de la conversación, pero el inicio repetido del contexto puede facturarse con la tarifa de lectura de caché. A continuación se muestra un cálculo de ejemplo basado en tokens. No es una medición ni un límite máximo de costes. Se indican todas las suposiciones:

• cada solicitud tiene 40 000 tokens de entrada, de los cuales 36 000 (90%) se facturan como lectura de caché, y los 4000 restantes como escritura en caché;
• cada solicitud devuelve 1000 tokens de salida;
• en una sesión de trabajo hay 50 solicitudes de este tipo, sin llamadas de Claude Haiku 4.5 en segundo plano;
• en Kunavo, la lectura de caché cuesta 10% de la tarifa de entrada, y la escritura en caché cuesta 1,25× la tarifa de entrada. Estas proporciones corresponden a Claude Sonnet 5, y cada modelo de la tabla se calcula según sus propias proporciones.

El coste real depende de la longitud del contexto, del número de aciertos de caché, de la longitud de la respuesta y de si borras la conversación entre tareas con el comando /clear. Encontrarás las tarifas de todos los modelos en la lista de precios. Puedes estimar tu propio consumo con la calculadora de costes de tokens de Claude (en inglés). La guía cuánto cuesta Claude Code explica cuándo resulta más rentable una suscripción y cuándo la API.

Errores más comunes

Limitaciones

• Kunavo no emite facturas con IVA.
• BLIK solo funciona para recargas manuales. La recarga automática requiere una tarjeta guardada o Link.
• Esta es una API facturada por tokens, no una suscripción de Claude Pro o Max. Con una clave API no funcionan Remote Control ni el dictado por voz, el modo /fast está desactivado y la búsqueda de herramientas MCP está desactivada de forma predeterminada.
• Actualmente, Kunavo (estado a 3 października 2026) no ofrece Sonnet 5.5, por lo que la configuración anterior fija el alias sonnet en claude-sonnet-5. Sin modelos fijados, los alias predeterminados pueden devolver un 404. Claude Opus 5.5, fijado al alias opus, requiere Claude Code versión 2.1.280 o posterior.
• La documentación oficial de Claude Code y la documentación de integración de Kunavo solo están disponibles en inglés.

Preguntas frecuentes