Instalar Claude Code: Windows, macOS y Linux, clave de API sin suscripción y pago mediante Bancontact

Para instalar Claude Code basta con una línea, pero no es la misma en todos los sistemas: curl -fsSL https://claude.ai/install.sh | bash en la terminal de macOS, Linux o WSL, irm https://claude.ai/install.ps1 | iex en PowerShell y una línea install.cmd en el símbolo del sistema de Windows. La verdadera pregunta llega en el primer inicio: ¿quién paga las solicitudes? Una cuenta Pro, Max, Team, Enterprise o Console permite iniciar sesión (el plan gratuito de Claude.ai no incluye Claude Code). Sin suscripción, basta una clave API: seis variables, entre ellas ANTHROPIC_BASE_URL sin /v1 ni ANTHROPIC_AUTH_TOKEN, y después echar un vistazo a /status. El saldo de Kunavo se puede pagar con tarjeta, Apple Pay, Google Pay, Link o, en Bélgica, Bancontact, desde $10, sin suscripción.

D’où viennent les informations : les commandes et les variables sont reprises de la documentation officielle de Claude Code (instalación, variables de entorno, conexión a una pasarela), relue le 3 de octubre de 2026 ; les prix Kunavo et les moyens de paiement ont été contrôlés le 3 de octubre de 2026. D’après la lista de países admitidos por Anthropic (lue le 3 de octubre de 2026), Claude.ai et l’API sont ouverts en France, en Belgique, en Suisse, au Luxembourg et au Canada, comme au Maroc, en Tunisie, en Algérie, au Sénégal et en Côte d’Ivoire. Le même guide existe en inglés et, pour la Flandre, en neerlandés.

Qué comando escribir: todo depende de la ventana

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

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

:: Invite de commandes Windows (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Las tres primeras líneas configuran la versión nativa, la que recomienda Anthropic: un binario independiente, ubicado en ~/.local/bin (%USERPROFILE%\.local\bin en Windows), que descarga sus actualizaciones en segundo plano y las aplica en el siguiente inicio. Cuando termine la instalación, cierre el terminal y abra uno nuevo: el que utilizó para instalar todavía no conoce el nuevo PATH.

En Windows, equivocarse de ventana es la principal causa de error, y el mensaje lo indica claramente. The token '&&' is not a valid statement separator: ha pegado la línea de CMD en PowerShell. 'irm' is not recognized as an internal or external command: es al revés. En un Windows en francés, este segundo mensaje puede aparecer traducido; la causa no cambia. Los demás mensajes están en la tabla de errores, al final de la guía.

Requisitos

Windows: lo que dicen los tutoriales antiguos y lo que es cierto

Une bonne partie des tutoriels en français datent des premières versions de Claude Code. Voici leurs consignes les plus répandues, confrontées à la documentación de instalación actual et à la página de solución de problemas (lues le 3 de octubre de 2026) :

Si vous installez Git for Windows, Claude Code passe par Git Bash et garde l’outil PowerShell à côté. Il arrive qu’il ne trouve pas bash.exe : indiquez alors son chemin dans la variable CLAUDE_CODE_GIT_BASH_PATH, au sein du bloc env de ~/.claude/settings.json (la documentation donne C:\Program Files\Git\bin\bash.exe en exemple). Dernier piège : le raccourci « Windows PowerShell (x86) » lance une version 32 bits, que Claude Code refuse.

La elección entre nativo y WSL depende de dónde se encuentren sus proyectos:

En WSL, todo ocurre dentro de la distribución de Linux: ahí se pega la línea curl … | bash y ahí se escribe claude después. Si se inicia desde PowerShell o CMD, no verá esta instalación.

Homebrew, WinGet, apt o npm

Los gestores de paquetes funcionan, con una contrapartida: Claude Code no se actualiza automáticamente con ellos. Para Homebrew y WinGet, la variable CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 hace que Claude Code inicie la actualización por sí mismo; sin ella, deberá hacerlo usted:

# Homebrew (macOS)
brew install --cask claude-code
brew upgrade claude-code              # pas de mise à jour automatique

# WinGet (Windows)
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode   # pas de mise à jour automatique

Sur Debian, Ubuntu, Fedora, RHEL et Alpine, Anthropic publie aussi des dépôts apt, dnf et apk signés, mis à jour avec le reste du système ; la procédure figure sur la página de instalación.

Queda npm, práctico si Node.js ya forma parte de sus herramientas. El paquete requiere como mínimo Node.js 22. En una versión anterior, npm se limita a mostrar una advertencia EBADENGINE y continúa hasta el final, porque el paquete instala el mismo binario nativo, que no necesita Node.js para ejecutarse. Dos reglas: no use sudo npm install -g y actualice con @latest, porque npm update -g se mantiene dentro del rango de versiones original y puede dejarle atrás.

node -v                                       # v22 ou plus récent
npm install -g @anthropic-ai/claude-code      # jamais avec sudo

# mise à jour : avec @latest, pas avec npm update -g
npm install -g @anthropic-ai/claude-code@latest

Comprobar la instalación y reparar el PATH

claude --version   # affiche le numéro de version, suivi de (Claude Code)
claude doctor      # diagnostic de l’installation et des réglages, sans ouvrir de session

Si devuelve un número de versión, está instalado. claude doctor va más allá sin iniciar una sesión: muestra el estado de la instalación, los errores en los archivos de configuración y el resultado de la última actualización. Cuando algo falla, es el primer comando que debe ejecutar.

command not found: claude sur macOS ou Linux, claude « non reconnu » sous Windows : le programme est bien installé, mais le shell ne sait pas où le chercher. Une nouvelle fenêtre suffit le plus souvent. Sinon, ajoutez ~/.local/bin au PATH dans ~/.zshrc ou ~/.bashrc. Sous Windows, la página oficial de solución de problemas donne ces trois étapes PowerShell :

# 1. Le dossier d'installation est-il déjà dans le PATH ?
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Aucun résultat ? Ajoutez-le au PATH de l'utilisateur, puis ouvrez une nouvelle fenêtre
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Dans la nouvelle fenêtre : deux chemins = deux installations concurrentes
where.exe claude

¿Lo instaló mediante npm y PowerShell responde npm.ps1 cannot be loaded? Su directiva de ejecución bloquea los scripts de npm. Cambie al instalador nativo o autorice los scripts locales solo para su cuenta:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Quién paga las solicitudes: suscripción de Claude o clave API

La elección no se hace durante la instalación, sino en el primer inicio, y puede revertirse. Una clave definida en el entorno tiene prioridad sobre una conexión de claude.ai guardada, que permanece inactiva; elimine la variable y la conexión volverá a tener prioridad en el siguiente inicio.

Con una suscripción de Claude

No hay nada que configurar: claude en la carpeta del proyecto y, después, inicie sesión en el navegador. Hay una sola excepción: una ANTHROPIC_API_KEY que permanezca en su entorno. Claude Code preguntará una vez si debe usarla; si la rechaza, la decisión se memoriza y la clave se ignora después sin mostrar ningún mensaje, lo que puede hacer creer que la variable no se lee. Para cambiar esta decisión: /config → Use custom API key.

Sin suscripción: la clave API de Kunavo

Faire pointer Claude Code ailleurs que chez Anthropic n’a rien d’un bricolage. La lista oficial de variables de entorno présente ANTHROPIC_BASE_URL comme le moyen d’envoyer les requêtes vers un proxy ou une passerelle. Kunavo répond au format de l’API Messages d’Anthropic : vous gardez le Claude Code officiel, sans extension ni version modifiée.

1. Abra una cuenta: registro en Kunavo.
2. Añada saldo en Billing, $10 como mínimo (consulte más abajo los métodos de pago).
3. Genere una clave en /app/keys. Comienza por sk-kn- y solo se muestra al crearla: cópiela de inmediato.
4. Complete las seis variables siguientes.

Pourquoi épingler quatre modèles ? Les alias de Claude Code suivent les sorties d’Anthropic. D’après la documentación sobre la configuración de modelos (lue le 3 de octubre de 2026), pour un compte API, le réglage par défaut et opus visent aujourd’hui Opus 5.5, et sonnet vise Sonnet 5.5, que Kunavo ne sert pas : sans ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, la phase d’exécution d’opusplan et les sous-agents réglés sur sonnet tombent sur une 404. L’alias opus est épinglé sur Opus 5.5 (claude-opus-5-5), qui exige Claude Code v2.1.280 ou plus récent ; sur une version plus ancienne, lancez claude update. Un modèle tout juste sorti n’est pas non plus toujours disponible chez Kunavo le jour même. Avec des noms complets, chaque requête part vers un modèle servi, au prix que vous connaissez. La documentación sobre el protocolo de las pasarelas (lue le 3 de octubre de 2026) confirme le point sur les tâches de fond : avec Claude Haiku 4.5, elles coûtent peu.

Dónde escribir las variables

La versión recomendada, que debe fusionarse con el contenido existente del archivo si ya lo hay (añada solo 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"
  }
}

Los mismos valores en el shell, en macOS y Linux:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # le domaine seul, sans /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

Para una prueba rápida en una ventana de PowerShell:

# Valable uniquement dans cette fenêtre PowerShell
$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

Y para la extensión de VS Code, en la configuración de usuario del editor (comando Preferences: Open User Settings (JSON)):

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://api.kunavo.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-kn-..." },
    { "name": "ANTHROPIC_MODEL", "value": "claude-sonnet-5" },
    { "name": "ANTHROPIC_DEFAULT_OPUS_MODEL", "value": "claude-opus-5-5" },
    { "name": "ANTHROPIC_DEFAULT_SONNET_MODEL", "value": "claude-sonnet-5" },
    { "name": "ANTHROPIC_DEFAULT_HAIKU_MODEL", "value": "claude-haiku-4-5" }
  ]
}

La aplicación de escritorio de Claude es una excepción: no lee ni ANTHROPIC_BASE_URL ni settings.json. ¿Una variable modificada en el shell sigue sin surtir efecto? Busque primero la misma variable en un settings.json, que tiene prioridad.

Tarifs par million de tokens tirés du catalogue Kunavo, à côté du prix public d’Anthropic relevé sur claude.com/pricing (lu le 3 de octubre de 2026) :

Para cambiar a Opus durante una tarea: /model opus durante la sesión (el alias fijado en claude-opus-5-5) o claude --model claude-opus-5-5 al iniciar. El presupuesto mensual según su uso y el umbral a partir del cual la suscripción resulta más ventajosa se detallan en el precio de Claude Code. La calculadora de coste en tokens de Claude hace el cálculo para sus propios volúmenes, y la página de precios enumera todos los modelos.

Comprobar con /status

La primera señal, incluso antes de /status: con ANTHROPIC_AUTH_TOKEN configurada, Claude Code se inicia sin pantalla de inicio de sesión. Si aparece esta pantalla, no se ha leído ninguna clave, a menudo porque solo se encuentra en la configuración del proyecto (.claude/settings.json o .claude/settings.local.json). En una sesión interactiva, este bloque env solo se aplica después del asistente de primer inicio y de la pregunta de confianza sobre la carpeta. Mueva la clave al shell o a ~/.claude/settings.json.

Une fois dans la session, /status s’ouvre sur l’onglet Status. Voici comment le lire, d’après la documentación sobre las pasarelas (lue le 3 de octubre de 2026) :

¿Ya había iniciado sesión con una suscripción? En ese caso, Claude Code puede indicar al iniciarse que hay dos fuentes de identificación activas, en una advertencia que termina con auth may not work as expected. La clave es la que se utiliza para las solicitudes; /logout elimina la conexión anterior y hace desaparecer la advertencia.

Para saber si un problema procede de Kunavo o de su configuración, haga una prueba sin Claude Code. La documentación propone una solicitud limitada a un solo token de salida, que cuesta una fracción de centavo. Los dos comandos siguientes toman la dirección y la clave del shell: si solo están definidas en settings.json, no se verían aquí.

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": "."}]}'

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": "."}]}'

Un JSON que comienza por {"id":"msg_, o en PowerShell un objeto cuyo id comienza por msg_: la dirección y la clave funcionan. Un 401: la clave se rechaza.

Qué cambia con una clave API

• Remote Control y el dictado por voz desaparecen. Ambos dependen de una cuenta de claude.ai y siguen sin estar disponibles mientras ANTHROPIC_AUTH_TOKEN esté definida. Remote Control también se desactiva cuando ANTHROPIC_BASE_URL designa un host distinto de Anthropic.
• El modo rápido (/fast) aparece desactivado, porque su verificación requiere una conexión de claude.ai o una clave de Anthropic, no un simple token bearer.
• La búsqueda de herramientas MCP está desactivada de forma predeterminada cuando ANTHROPIC_BASE_URL apunta fuera de Anthropic.
• /context muestra estimaciones. Kunavo ne propose pas /v1/messages/count_tokens, et dans ce cas Claude Code compte à partir du nombre de caractères (documentación sobre el protocolo de las pasarelas).

Para el resto (lectura y escritura de código, herramientas, subagentes, servidores MCP, hooks y caché de prompts), nada cambia. Los detalles técnicos, en inglés, están en la documentación de integración de Claude Code.

Pagar desde Francia o Bélgica

Deux circuits à ne pas confondre. L’abonnement Claude acheté sur le web se règle uniquement par carte de crédit ou de débit (Preguntas frecuentes sobre facturación de Anthropic, lue le 3 de octubre de 2026) ; souscrit dans l’app mobile, il passe par l’App Store ou Google Play. Les montants de claude.com/pricing sont hors taxes.

Le solde Kunavo, lui, se recharge sur une page de paiement Stripe. Le tarif est fixé en dollars américains, mais depuis la France ou la Belgique Stripe vous montre le montant en euros, à un taux garanti 24 heures qui intègre 2 à 4 % de frais de conversion à votre charge (documentación de Stripe sobre Adaptive Pricing, lue le 3 de octubre de 2026). Vous pouvez payer en dollars pour éviter ces frais, mais votre banque applique alors son propre change, et Bancontact n’est proposé qu’en euros. Les moyens de paiement disponibles :

• ¿Tarjeta CB francesa? Selon la documentación de Stripe sobre Cartes Bancaires (lue le 3 de octubre de 2026), plus de 95 % des cartes CB sont co-badgées Visa ou Mastercard. Elles passent donc au checkout en tant que Visa ou Mastercard, et une simple carte de débit fait l’affaire.
• Bancontact est proposé aux acheteurs situés en Belgique. Stripe vous envoie sur le site ou l’app Bancontact pour valider, et le résultat est connu immédiatement (documentación de Stripe sobre Bancontact, lue le 3 de octubre de 2026).
• Pay by Bank, le paiement depuis votre banque en ligne, n’est pas proposé depuis la France ni la Belgique : le checkout ne l’affiche qu’aux acheteurs situés au Royaume-Uni, en Irlande et en Finlande. La documentación de Stripe sobre Pay by Bank (lue le 3 de octubre de 2026) le classe en préversion privée pour la France et ne mentionne pas la Belgique.
• Desde Suiza o Canadá, el importe se muestra en francos suizos o dólares canadienses, con tarjeta y Link, además de Apple Pay y Google Pay, que utilizan una tarjeta.

No disponible: PayPal, domiciliación SEPA y Klarna, que está reservado a compradores ubicados en Estados Unidos (pagar en dólares no basta).

1. Regístrese en Kunavo; en esta etapa no se solicita ninguna tarjeta.
2. En Billing, elija el importe: $10 como mínimo. Los importes más altos dan derecho a un bono ($100 payés, $110 crédités ; $1 000 payés, $1 200 crédités ; $5 000 payés, $6 250 crédités).
3. En la página de Stripe, seleccione el método de pago; el importe en euros se muestra antes de confirmar. Con Bancontact, confirme en la aplicación o con la tarjeta.
4. Cree la clave en /app/keys y colóquela en ANTHROPIC_AUTH_TOKEN.

El saldo es prepagado: no hay cuotas mensuales, no tiene fecha de caducidad y una solicitud que falla no se factura. La recarga automática requiere una tarjeta guardada o Link. Bancontact no admite pagos recurrentes en Stripe, por lo que cada recarga con Bancontact debe iniciarse manualmente. Kunavo no emite facturas con IVA, ni francesas, ni belgas ni de ningún otro país; el historial de recargas se consulta en Billing. Por último, estos métodos de pago sirven únicamente para el saldo de la API de Kunavo y no pagan una suscripción Claude Pro o Max. Todas las demás opciones, incluidas App Store y Google Play, se revisan en pagar Claude sin tarjeta bancaria.

Errores comunes

Primeros pasos en un proyecto

En un repositorio que Claude Code está descubriendo, empiece por /init: explora el código y redacta un CLAUDE.md que registra los comandos de prueba y las convenciones detectadas. Revise este archivo y recórtelo, ya que se vuelve a cargar en cada sesión. Para cambiar de tema, /clear comienza una conversación nueva; para continuar una tarea larga, /compact resume el historial.

Los límites de la clave API

• Paga por consumo, no por un plan Claude Pro o Max. Para varias horas de Claude Code al día, todos los días, la suscripción suele resultar más conveniente; para un uso irregular, el pago por token es más flexible y los meses de poca actividad no cuestan nada. Consulte las cifras en el precio de Claude Code.
• No hay Remote Control ni dictado por voz mientras la clave esté activa.
• La capacidad de Kunavo se comparte, sin cuota reservada ni compromiso contractual; si lo necesita, contrate directamente con Anthropic.
• Bancontact solo permite recargas manuales; las automáticas se realizan mediante una tarjeta guardada o Link.
• Los importes en euros incluyen las comisiones de conversión de Stripe, y Kunavo no emite facturas con IVA.

Preguntas frecuentes