Instalar Claude Code en Windows, Mac y Linux: clave API sin suscripción y pago con Satispay

Para instalar Claude Code basta un comando, que varía según el terminal: la línea con install.sh en macOS, Linux y WSL, irm … | iex en PowerShell y la línea con install.cmd en el Símbolo del sistema. Es el método que recomienda Anthropic; npm sigue siendo posible, pero requiere Node.js 22 o posterior. El plan gratuito de Claude no incluye Claude Code, por lo que hace falta una suscripción Pro o superior o una clave de API. Aquí seguimos la segunda opción: ANTHROPIC_BASE_URL=https://api.kunavo.com (sin /v1), la clave en ANTHROPIC_AUTH_TOKEN, cuatro variables que fijan los modelos y /status para la verificación final. El crédito se recarga con Satispay en euros desde $10 y solo pagas los tokens que consumes.

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

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

:: Windows – Prompt dei comandi (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Da dove vengono questi comandi: la documentazione di Claude Code esiste anche in italiano e l'abbiamo riletta il 3 de octubre de 2026, in particolare le pagine su instalación e gateway de LLM. Prezzi e metodi di pagamento di Kunavo sono aggiornati al 3 de octubre de 2026. Anthropic serve l'Italia sia su Claude.ai sia con l'API (países compatibles, letto il 3 de octubre de 2026).

Qué se necesita

I requisiti della documentación oficial (letta il 3 de octubre de 2026) sono bassi:

• macOS 13.0 o posterior; Windows 10 1809 o posterior, o Windows Server 2019 o posterior; Ubuntu 20.04+, Debian 10+ o Alpine Linux 3.19+.
• Al menos 4 GB de RAM y un procesador x64 o ARM64. Windows de 32 bits no es compatible.
• Una shell entre Bash, Zsh, PowerShell y CMD.
• Una conexión desde un país compatible con Anthropic: Italia lo es.
• Node.js solo si eliges npm y, en ese caso, desde la versión 22 en adelante.

Qué comando, en qué terminal

No hacen falta permisos de administrador ni WSL: la documentación oficial lo dice explícitamente, aunque más de una guía sugiera lo contrario. Una vez instalado, Claude Code se actualiza automáticamente en segundo plano. Quien prefiera un gestor de paquetes puede usar Homebrew o WinGet, sabiendo que en ese caso tendrá que iniciar las actualizaciones:

# Homebrew – canale stable; non si aggiorna da solo
brew install --cask claude-code

# WinGet (Windows) – non si aggiorna da solo
winget install Anthropic.ClaudeCode

Antes de probarlo, cierra el terminal y abre uno nuevo: solo una ventana nueva vuelve a leer PATH. Después, comprueba. claude doctor también será útil más adelante, porque verifica la instalación y la configuración sin abrir una sesión y te indica de inmediato si el problema está en una u otra.

claude --version   # stampa la versione, ad esempio 2.1.284 (Claude Code)
claude doctor      # diagnostica di installazione e impostazioni, senza aprire una sessione

Descarga bloqueada: 403 o una página HTML en lugar del script

Quando lo script non arriva, il terminale non lo dice in modo chiaro: bash si lamenta con syntax error near unexpected token '<' (sta cercando di eseguire una pagina web), oppure curl si ferma su curl: (22) The requested URL returned error: 403. La página oficial sobre problemas de instalación (in inglese, letta il 3 de octubre de 2026) distingue due casi. Se la pagina scaricata dice App unavailable in region, il server crede che ti colleghi da un paese escluso: dall'Italia capita quasi sempre per una VPN o un proxy che esce all'estero. Un 403 senza testo arriva più spesso da un proxy aziendale o da un firewall. Cambiare metodo di installazione non aiuta, perché Homebrew e WinGet scaricano dagli stessi server: prova da un'altra rete oppure chiedi all'IT di sbloccare quei domini.

Con npm: Node.js 22, no 18

Se Node.js lo usi già tutti i giorni, npm sembra la scelta naturale. Funziona ed è tra i metodi documentati, con una condizione che molte guide in italiano non hanno aggiornato: ci vuole Node.js 22 o successivo. Con un Node più vecchio vedrai l'avviso EBADENGINE, però l'installazione arriva in fondo e claude parte lo stesso (documentación oficial, letta il 3 de octubre de 2026). Le versioni aggiornate di Node sono su nodejs.org.

node -v                                    # serve v22 o successiva
npm install -g @anthropic-ai/claude-code   # senza sudo

# aggiornamento: @latest, non npm update -g
npm install -g @anthropic-ai/claude-code@latest

Tres hábitos que se deben evitar:

• sudo delante de npm install -g. La documentación lo desaconseja, tanto por los permisos que se mezclan como por la seguridad.
• npm update -g para actualizar. En su lugar, repite la instalación con @latest, como en la última línea anterior.
• Omitir las dependencias opcionales. Il binario di Claude Code arriva proprio come dipendenza facoltativa, un pacchetto @anthropic-ai/claude-code-* per ogni piattaforma. Con --omit=optional, o con optional=false nel file .npmrc, non viene scaricato e su macOS o Linux claude risponde claude native binary not installed (problemas de instalación, in inglese, letta il 3 de octubre de 2026).

Claude Code en Windows: dónde se atasca

Su Windows Claude Code gira in modo nativo, e l'installazione in sé è la parte facile. I problemi nascono dall'ambiente. Il primo è il terminale: se incolli in PowerShell la riga per CMD, PowerShell protesta per il &&; se incolli in CMD la riga per PowerShell, CMD non sa cosa sia irm; e la riga curl … | bash del Mac in PowerShell non funziona proprio. Su un Windows in italiano alcuni di questi messaggi possono comparire tradotti. In ogni caso la soluzione è tornare alla tabella qui sopra e prendere la riga del terminale che hai davanti (i messaggi in inglese sono nella tabella degli errori in fondo; fonte: documentación, letta il 3 de octubre de 2026).

Presta atención también al menú Inicio: “Windows PowerShell (x86)” abre un proceso de 32 bits y Claude Code se detiene con Claude Code does not support 32-bit Windows, aunque el PC sea de 64 bits. Elige la entrada sin (x86).

Git for Windows non è obbligatorio. Se è installato, Claude Code esegue i comandi attraverso Git Bash; se manca, usa PowerShell. Quando Git c'è ma Claude Code non trova bash.exe, indicagli il percorso con CLAUDE_CODE_GIT_BASH_PATH nel blocco env di ~/.claude/settings.json, di solito C:\Program Files\Git\bin\bash.exe. E WSL? Serve solo in un caso preciso:

Con WSL todo sucede dentro de Linux: la línea install.sh debe ejecutarse en la shell de WSL y, desde allí, ejecuta claude.

No se encuentra “claude”

Si después de la instalación el terminal responde command not found: claude o 'claude' is not recognized, el programa está instalado, pero su carpeta no está en PATH. El instalador nativo lo copia en ~/.local/bin/claude en macOS y Linux y en %USERPROFILE%\.local\bin\claude.exe en Windows. Primer intento: abre un terminal nuevo. Si en Windows no basta, estos son los comandos de PowerShell de la documentación para comprobar y añadir la carpeta al PATH del usuario:

# 1. Controlla se la cartella di installazione è già nel PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Nessun risultato? Aggiungila al PATH utente, poi chiudi e riapri il terminale
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Nel nuovo terminale
claude --version

npm.ps1 cannot be loaded en PowerShell

Solo afecta a quienes instalan con npm: las directivas de ejecución (execution policy) de PowerShell bloquean el script .ps1 que npm crea, y el mensaje completo contiene running scripts is disabled on this system. La documentación indica tres opciones: permitir que el usuario actual ejecute scripts locales con el comando siguiente, ejecutar npm.cmd y claude.cmd en lugar de los scripts de PowerShell, o prescindir de npm y usar el instalador nativo.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Sin suscripción: cuenta de Claude o clave de API

Installato non vuol dire pronto: al primo avvio Claude Code chiede di autenticarsi, e il piano gratuito di Claude.ai non basta (documentación, letta il 3 de octubre de 2026). Le due strade a confronto:

Esiste anche la chiave della Console di Anthropic, sempre a consumo. Lì però i crediti prepagati scadono dopo un anno e non si rimborsano (asistencia de Anthropic, letto il 3 de octubre de 2026); si paga con carta, mentre il bonifico ACH è riservato agli account API con fatturazione mensile (asistencia de Anthropic). Il credito Kunavo non ha scadenza.

Configurar la clave de API: seis variables

Che Claude Code parli con un endpoint diverso da quello di Anthropic è previsto: la documentazione ufficiale ha una pagina, tradotta anche in italiano, su come conectarlo a una puerta de enlace LLM. Nessun plugin, nessuna versione modificata. Bastano queste variabili:

En macOS y Linux, añádelas al final de ~/.zshrc o ~/.bashrc:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # solo il dominio, senza /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, para una prueba rápida que dura lo mismo que la ventana de PowerShell:

# Vale solo in questa finestra di PowerShell: chiusa la finestra, sparisce
$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 no tener que volver a configurarlas cada vez, el lugar adecuado es el bloque env de ~/.claude/settings.json (en Windows, %USERPROFILE%\.claude\settings.json): se aplica a todos tus proyectos. Si el archivo ya contiene otras configuraciones, añade solo 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"
  }
}

¿AUTH_TOKEN o API_KEY?

Kunavo legge la chiave da tutti e due gli header, Authorization: Bearer e x-api-key, quindi in teoria vanno bene entrambe le variabili. La differenza la fa Claude Code. Con ANTHROPIC_API_KEY, inviata come x-api-key, la sessione interattiva ti chiede una volta se approvare la chiave; se rispondi no, la ignora senza dire nulla finché non la riattivi da /config → Usar una clave de API personalizada. ANTHROPIC_AUTH_TOKEN non chiede niente, ed è anche la variabile che la documentación sobre las puertas de enlace (letta il 3 de octubre de 2026) suggerisce quando non sai quale scegliere.

Por qué fijar los modelos

Senza variabili Claude Code ragiona per alias, e gli alias seguono le uscite di Anthropic. Oggi, secondo la documentación sobre la configuración de modelos (letta il 3 de octubre de 2026), per chi usa l'API opus corrisponde a Opus 5.5 e sonnet a Sonnet 5.5. Kunavo, al 3 de octubre de 2026, non offre Sonnet 5.5: senza ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, la fase esecutiva di opusplan e i subagent con model: sonnet chiederebbero un modello che su Kunavo non c'è e tornerebbero 404. Con claude-sonnet-5 in quella variabile l'alias punta a Claude Sonnet 5, lo stesso modello di ANTHROPIC_MODEL. Quest'ultima decide invece il modello della sessione: senza, Claude Code partirebbe dal suo predefinito, oggi Opus 5.5. Opus 5.5 è disponibile, e fissare opus su claude-opus-5-5 serve a un'altra cosa: evitare che modello e tariffa cambino da un giorno all'altro quando l'alias passerà a un Opus successivo. Claude Opus 5.5 richiede Claude Code 2.1.280 o successivo; con una versione più vecchia, lancia prima claude update.

Las tarifas de Kunavo de los tres modelos de la configuración, por millón de tokens (entrada / salida): Claude Sonnet 5 $1,40 / $7,00 (precio de lista de Anthropic: $2,00 / $10,00); Claude Opus 5.5 $2,80 / $14,00; Claude Haiku 4.5 $0,70 / $3,50, que también trabaja entre bastidores.

Dónde no ponerla y qué configuración prevalece

Il .claude/settings.json dentro il progetto viene committato: una chiave scritta lì finisce nel repository e arriva a chiunque lo cloni (documentación sobre las puertas de enlace). Se una variabile compare sia nella shell sia nel blocco env di un file di impostazioni, prevale il file: quando una modifica a ~/.zshrc sembra ignorata, il motivo è quasi sempre lì. Il campo model del file di impostazioni, invece, cede il passo ad ANTHROPIC_MODEL. Nell'estensione di Claude Code per VS Code le stesse variabili vanno in claudeCode.environmentVariables, nelle impostazioni utente di VS Code. L'app desktop di Claude resta fuori da tutto questo: non legge né ANTHROPIC_BASE_URL né settings.json (documentación sobre las puertas de enlace, letta il 3 de octubre de 2026).

Primer inicio y comprobación con /status

Se la chiave è al suo posto, claude parte sin pantalla de inicio de sesión: restano solo la configurazione iniziale e la domanda se ti fidi della cartella. Se invece compare il login, Claude Code non ha trovato la chiave. Il caso tipico è la chiave scritta solo nel .claude/settings.json o nel .claude/settings.local.json del progetto: in modalità interattiva quel blocco env entra in gioco solo dopo la configurazione iniziale e la conferma di fiducia (documentación sobre las puertas de enlace, letta il 3 de octubre de 2026), quindi al primo avvio non c'è ancora. Spostala nella shell o nel file utente. Un vecchio login Pro o Max non dà fastidio, perché la variabile ha la precedenza sull'accesso salvato; se vuoi cancellarlo, c'è /logout.

Dentro de la sesión, escribe /status. Las líneas importantes son dos:

• Anthropic base URL, que aparece solo cuando hay una puerta de enlace configurada: debe indicar https://api.kunavo.com. Si no aparece, ANTHROPIC_BASE_URL no llegó a la sesión.
• Auth token con el nombre ANTHROPIC_AUTH_TOKEN: estás usando la clave. Si en su lugar aparece Login method con una cuenta de claude.ai, la variable se ha ignorado.

¿Quieres comprobarlo antes incluso de abrir Claude Code? La documentación propone una solicitud mínima, con 1 token de salida, que descuenta del crédito un importe insignificante. El comando lee las variables del shell actual: si la clave solo está en settings.json, expórtala primero en este terminal. Si devuelve un JSON que comienza por {"id":"msg_, todo está bien; 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 prueba es esta, y la respuesta correcta contiene un 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é pierdes con la clave de API

• Remote Control y dictado por voz. Requieren una identidad de claude.ai y no funcionan con ANTHROPIC_AUTH_TOKEN ni ANTHROPIC_API_KEY; desde la versión 2.1.196, Remote Control también se desactiva cuando ANTHROPIC_BASE_URL apunta a un host que no pertenece a Anthropic.
• El modo /fast. Con solo el token bearer, Claude Code lo considera desactivado y ni siquiera intenta solicitarlo.
• La búsqueda de herramientas MCP al inicio. Con un ANTHROPIC_BASE_URL personalizzato parte spenta (documentación de MCP, in inglese, letta il 3 de octubre de 2026). Si riaccende con ENABLE_TOOL_SEARCH=true se il gateway inoltra i blocchi tool_reference; con Kunavo non l'abbiamo provato.
• La precisión de /context. Kunavo non espone /v1/messages/count_tokens, un endpoint facoltativo secondo la especificación de las puertas de enlace (letta il 3 de octubre de 2026); senza, Claude Code stima i token a partire dai caratteri.

Para profundizar, en inglés: la documentación de la integración con Claude Code, la página sobre los casos límite de ANTHROPIC_BASE_URL y la guía Install Claude Code.

Pagar con Satispay sin tarjeta de crédito

Prima una precisazione, perché è la domanda più frequente: Satispay non paga l'abbonamento Claude. Per Pro e Max comprati sul web Anthropic accetta solo carte di credito o di debito (asistencia de Anthropic) e non accetta PayPal (asistencia de Anthropic), entrambi letti il 3 de octubre de 2026. Su Kunavo Satispay ricarica invece il credito API che Claude Code consuma con la chiave configurata sopra. Tutti i dettagli, compresi i costi per caricare la Disponibilità, sono nella guida pagar Claude con Satispay. Per Claude Code la sequenza è questa:

1. Regístrate en Kunavo con tu correo electrónico o con una cuenta de Google: no se requiere tarjeta.
2. Abre Facturación y elige cuánto recargar: mínimo $10, sin cuota fija. Por encima de ciertos umbrales hay un bono: $100 diventano $110, $1.000 diventano $1.200, $5.000 diventano $6.250 de crédito.
3. Nel checkout di Stripe, che mostra l'importo in euro, scegli Satispay. Si passa alla pagina di Satispay (documentación de Stripe): numero di cellulare o QR code dall'app, poi conferma con Enviar (asistencia de Satispay, letto il 3 de octubre de 2026). Meglio avere già abbastanza Disponibilità prima di cominciare.
4. El crédito aparece en Facturación en cuanto Stripe confirma el pago. Si no lo ves de inmediato, actualiza la página en lugar de volver a pagar: un segundo pago se suma al crédito, no sustituye al primero.
5. En Claves de API, genera la clave sk-kn-… y cópiala de inmediato en ANTHROPIC_AUTH_TOKEN: se muestra una sola vez.

Kunavo fissa i prezzi in dollari e Stripe li converte in euro con una comisión de conversión del 2–4% a carico di chi paga (Stripe, Adaptive Pricing, letto il 3 de octubre de 2026): sulla ricarica minima da $10 sono tra $0,20 e $0,40. In dollari la commissione sparisce, ma sparisce anche Satispay, che esiste solo nel checkout in euro; se il checkout ti appare in dollari, spesso c'entra una VPN. L'importo esatto in euro è quello che leggi nel checkout prima di confermare.

Con Satispay le ricariche si fanno a mano: la ricarica automatica di Kunavo addebita solo una carta salvata o Link. Chi ha la carta Satispay, una Mastercard di debito per i piani Plus, Metal e Velvet (asistencia de Satispay, letto il 3 de octubre de 2026), può salvarla e usarla come qualsiasi carta. Il credito non scade e le richieste fallite non vengono addebitate. Kunavo non emette fatture, né con IVA né elettroniche via SDI; lo storico delle ricariche resta in Facturación.

Una nota honesta: Satispay está en el checkout de Kunavo desde el 3 de octubre de 2026 y Stripe lo ofrece para pagos en euros, pero todavía no se ha procesado ninguna recarga por ese medio. Si no lo encuentras, la tarjeta, Apple Pay, Google Pay y Link hacen el mismo trabajo.

Cuánto cuesta una sesión de trabajo

Con la clave de API, el coste está en los tokens, y Claude Code envía bastantes: en cada paso reenvía todo el contexto. Sin embargo, la parte que no cambia puede leerse desde la caché a una tarifa mucho más baja. Este es un ejemplo preparado expresamente, con las hipótesis claras: no es una medición ni un límite de gasto.

• 40.000 tokens de entrada por solicitud, de los cuales 36.000 (90%) se leen desde la caché y 4.000 se escriben en la caché;
• 1.000 tokens de salida por solicitud;
• 50 solicitudes en una sesión, sin contar las llamadas a Claude Haiku 4.5 en segundo plano;
• lectura desde la caché al 10% de la tarifa de entrada y escritura a 1,25× la tarifa de entrada: son las proporciones de Kunavo para Claude Sonnet 5, y cada fila de la tabla usa las de su propio modelo.

Los contextos largos, pocas lecturas desde la caché y las respuestas extensas hacen subir la factura; un /clear entre una tarea y otra la reduce. Si te conviene más la suscripción o la API, puedes verlo en cuánto cuesta Claude Code; las tarifas de todos los modelos de Claude están en precios de la API de Claude y en la página de precios. Para recalcularlo con tus cifras, está disponible la calculadora de costes de tokens de Claude (en inglés).

Errores: mensaje, causa, solución

Qué no hace esta configuración

• No activa una suscripción Claude Pro o Max: el crédito de Kunavo paga la API y Claude Code con clave, no claude.ai ni la aplicación de Claude.
• No genera facturas: ni con IVA ni electrónicas mediante SDI.
• No recarga automáticamente con Satispay: la recarga automática requiere una tarjeta guardada o Link.
• No funciona sin las variables de los modelos mientras Kunavo no ofrezca Sonnet 5.5 (situación al 3 de octubre de 2026): el alias sonnet devolvería 404, y con él /model sonnet, la fase de ejecución de opusplan y los subagentes con model: sonnet.
• No hay documentación de Kunavo en italiano: la guía de integración y la página sobre saldo y pagos están en inglés, mientras que la de Anthropic sobre Claude Code está traducida.

Para una visión general de quienes desarrollan con Claude desde Italia, consulta la guía de la API de Claude en Italia. Para empezar: crea la cuenta, recarga $10 con Satispay, configura las seis variables y comprueba con /status.

Preguntas frecuentes