Instalar Claude Code: comandos para Windows, macOS y Linux, clave de API sin suscripción y pago con MB WAY

Claude Code se instala con un comando oficial por sistema: en macOS, Linux y WSL, curl -fsSL https://claude.ai/install.sh | bash; en Windows, en PowerShell, irm https://claude.ai/install.ps1 | iex (en la línea de comandos, CMD, la línea de install.cmd más abajo). Después hay dos formas de usarlo. Con suscripción, inicia sesión con una cuenta Pro, Max, Team, Enterprise o Console (quien solo tiene el plan gratuito de Claude.ai no tiene acceso a Claude Code). Sin suscripción, usa una clave de API: define ANTHROPIC_BASE_URL (solo el dominio, sin /v1), ANTHROPIC_AUTH_TOKEN y cuatro variables de modelo, y confirma con /status. El saldo de Kunavo se recarga con MB WAY en el checkout en euros, a partir de US$ 10, sin cuota mensual.

Comandos e variáveis verificados a 3 de octubre de 2026 na documentación oficial de instalación de Claude Code e na documentación de las variables de entorno; preços e meios de pagamento verificados a 3 de octubre de 2026. Portugal consta da lista de países compatibles con Anthropic (consultada a 3 de octubre de 2026), tanto para o Claude.ai como para a API. Este guia existe também em inglês: Instalar Claude Code.

Antes de instalar

macOS, Linux y WSL: una sola línea

En el Terminal (en macOS está en Aplicaciones › Utilidades), ejecuta:

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

Es la instalación nativa recomendada: un programa independiente que, según la documentación oficial, se actualiza automáticamente en segundo plano. El comando claude queda en ~/.local/bin. Un terminal que ya estaba abierto aún no conoce el nuevo PATH, así que abre una ventana nueva antes de probarlo. En WSL, la línea es exactamente la misma y se ejecuta dentro del terminal de WSL.

Instalar en Windows

En Windows hay dos líneas, y la elección depende únicamente de la ventana que esté abierta. Si la línea empieza por PS C:\Users\Nome>, estás en PowerShell; si solo aparece C:\Users\Nome>, sin PS, estás en la línea de comandos (CMD). No es necesario usar «Ejecutar como administrador»: la documentación oficial dice expresamente que no es necesario, al contrario de lo que recomiendan algunas guías en portugués.

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

:: Linha de Comandos do Windows (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

En Windows, el tropiezo más frecuente es usar la ventana equivocada. Si PowerShell responde The token '&&' is not a valid statement separator, has recibido la línea de CMD; si CMD responde 'irm' is not recognized as an internal or external command, has recibido la de PowerShell. En un Windows en portugués, este segundo mensaje puede aparecer traducido, con la misma causa. Y pegar la línea de macOS, con | bash, en PowerShell produce un error que indica que bash no se reconoce. En los tres casos, la solución es usar la línea que corresponde a la ventana.

O Git for Windows é opcional. Com ele, a ferramenta Bash do Claude Code passa a correr no Git Bash, e o PowerShell continua disponível ao lado; sem ele, todos os comandos correm pelo PowerShell. Quando o Git está instalado numa pasta fora do habitual e o Claude Code não dá com o bash.exe, indica-se o caminho em CLAUDE_CODE_GIT_BASH_PATH, dentro do bloco env de ~/.claude/settings.json; o exemplo da documentação é C:\Program Files\Git\bin\bash.exe.

Por tanto, WSL es una opción, no un requisito, al contrario de lo que se lee en algunas guías. Quien elija WSL ejecuta la línea de macOS/Linux en el terminal de WSL e inicia claude también allí, no desde PowerShell ni CMD.

Mediante Homebrew, WinGet o npm

También funciona, con una diferencia importante: según la documentación oficial, las instalaciones mediante Homebrew y WinGet no se actualizan automáticamente. La actualización se hace manualmente. También existen repositorios apt, dnf y apk firmados para Linux.

# Homebrew
brew install --cask claude-code
brew upgrade claude-code              # não se atualiza sozinho

# WinGet (Windows)
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode   # não se atualiza sozinho

El paquete npm requiere Node.js 22 o posterior, no Node.js 18, que todavía indican algunas guías. Con una versión anterior de Node.js, npm solo muestra una advertencia EBADENGINE durante la instalación, en lugar de fallar. No uses nunca sudo npm install -g: la documentación oficial lo desaconseja expresamente. Para actualizar, usa @latest, no npm update -g.

node -v                                           # tem de ser v22 ou posterior
npm install -g @anthropic-ai/claude-code          # nunca com sudo

# para atualizar mais tarde: com @latest, não com npm update -g
npm install -g @anthropic-ai/claude-code@latest

Confirmar la instalación

claude --version   # mostra o número da versão, seguido de (Claude Code)
claude doctor      # diagnóstico só de leitura da instalação e das definições, sem abrir sessão

claude doctor no inicia ninguna sesión: muestra el estado de la instalación y de los archivos de configuración. Es la forma más rápida de saber si un problema está en la instalación o en la configuración.

Um command not found: claude (ou, no Windows, a indicação de que claude não é um comando conhecido) quer dizer que o terminal não sabe onde o programa ficou. Muitas vezes basta fechar a janela e abrir outra. Se continuar, falta a pasta no PATH: no macOS e no Linux é ~/.local/bin, a acrescentar no ficheiro de arranque da shell (~/.zshrc ou ~/.bashrc); no Windows é %USERPROFILE%\.local\bin; segundo a resolución de problemas oficial, confirma-se e acrescenta-se assim no PowerShell:

# 1. A pasta de instalação já está no PATH?
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Sem resultado? Acrescente-a ao PATH do utilizador e abra uma janela nova
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Na janela nova: dois caminhos significam duas instalações lado a lado
where.exe claude

Si instalaste mediante npm y PowerShell responde npm.ps1 cannot be loaded because running scripts is disabled on this system, es la política de ejecución de PowerShell la que bloquea los scripts de npm. Usa el instalador nativo o permite scripts locales para tu usuario:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Y si aparece Claude Code does not support 32-bit Windows, se ha abierto «Windows PowerShell (x86)». Windows tiene dos entradas de PowerShell y la versión x86 se ejecuta como un proceso de 32 bits; abre la entrada «Windows PowerShell», sin (x86).

Primer uso: suscripción o clave de API

En el primer arranque se decide cómo se paga Claude Code. No es necesario reinstalarlo para cambiar de opción: lo que decide es que haya o no una clave definida.

Opción A — iniciar sesión con la suscripción

En la carpeta del proyecto, ejecuta claude e inicia sesión en el navegador. Atención si ya tienes ANTHROPIC_API_KEY en el entorno: en lugar de abrir el navegador, Claude Code solicita una única aprobación para esa clave. Si rechazas esa aprobación, la clave se ignora a partir de entonces y la pregunta no se repite, por lo que parece que la variable no se está leyendo. Para reactivarla: /config → Use custom API key.

Opción B — sin suscripción, con clave de API

ANTHROPIC_BASE_URL es una variable del propio Claude Code, diseñada para enrutar las solicitudes mediante un proxy o gateway. Apuntarla a un endpoint compatible con la Messages API de Anthropic es, por tanto, una configuración compatible, sin complementos ni versiones modificadas. Pasos:

1. Crear una cuenta en Kunavo.
2. Recarga el saldo en Facturación, a partir de US$ 10 (el pago con MB WAY se explica más abajo).
3. En /app/keys, crea una clave que empiece por sk-kn-. Solo se muestra una vez, así que conviene guardarla de inmediato.
4. Define las variables. En macOS y Linux, en ~/.zshrc o ~/.bashrc:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # só o domínio, sem /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 probar primero en una ventana de PowerShell:

# Vale só para esta janela do 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

Para uso permanente, el mejor lugar es el bloque env de la configuración del usuario: ~/.claude/settings.json (en Windows, %USERPROFILE%\.claude\settings.json). Allí, los valores se aplican a todos los proyectos, incluidos los agentes en segundo plano; la extensión de VS Code es la excepción (consulta más abajo). Una variable exportada en el shell solo llega a los programas iniciados desde ese shell: un editor abierto desde el Dock o el menú Inicio no la ve. Si el archivo ya tiene 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"
  }
}

Nunca ponha a chave no .claude/settings.json de um projeto: segundo a documentación oficial de gateways (consultada a 3 de octubre de 2026), esse ficheiro entra nos commits e é partilhado com quem clonar o repositório. E atenção à precedência: quando a shell e um ficheiro de definições definem a mesma variável, prevalece o ficheiro de definições. Se uma alteração na shell não surtir efeito, veja primeiro o settings.json.

Quien use la extensión de VS Code define las variables en claudeCode.environmentVariables, en la configuración de usuario del propio VS Code (comando Preferences: Open User Settings (JSON)). Según la documentación de gateways, la extensión comprueba las credenciales en esta configuración antes de arrancar; los valores de ~/.claude/settings.json llegan al proceso de Claude Code, pero no a esa comprobación:

{
  "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" }
  ]
}

Las cuatro variables de modelo y otras trampas

Cada línea del bloque tiene su propia trampa:

• En ANTHROPIC_BASE_URL no se incluye la ruta. La ruta /v1/messages la añade el propio Claude Code; una dirección que ya termine en /v1 acaba en /v1/v1/messages, que responde 404.
• ANTHROPIC_AUTH_TOKEN o ANTHROPIC_API_KEY: Kunavo acepta ambas. Según la documentación de gateways, ANTHROPIC_AUTH_TOKEN se envía en el encabezado Authorization: Bearer y se aplica de inmediato; ANTHROPIC_API_KEY se envía en el encabezado x-api-key y, en el modo interactivo, debe aprobarse una vez antes de entrar en vigor (consulta la opción A). Por eso esta guía usa ANTHROPIC_AUTH_TOKEN.
• El nombre en ANTHROPIC_MODEL debe ser exacto. Cópialo tal como aparece aquí: claude-sonnet-5.
• Sin ANTHROPIC_DEFAULT_SONNET_MODEL y ANTHROPIC_DEFAULT_OPUS_MODEL, los alias cambian por sí solos. Segundo a documentación de configuración de modelos (consultada a 3 de octubre de 2026), para quem usa a API da Anthropic o alias opus aponta para o Opus 5.5 e o alias sonnet para o Sonnet 5.5, e estes aliases mudam com as novas versões. Fixa-se com o nome completo do modelo ou com variáveis como ANTHROPIC_DEFAULT_OPUS_MODEL. O Kunavo não serve o Sonnet 5.5, e um modelo que não existe devolve 404: sem ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5, falham o /model sonnet, os subagentes com model: sonnet e o passo de execução do opusplan. Já o opus aponta para claude-opus-5-5, que o Kunavo serve, mas só a partir do Claude Code v2.1.280; quem tiver uma versão anterior corre claude update.
• ANTHROPIC_DEFAULT_HAIKU_MODEL también cuenta para las tareas en segundo plano. Según la documentación, define el alias haiku y el modelo de las funciones en segundo plano de Claude Code. Con Claude Haiku 4.5, esas llamadas usan el modelo más barato de la tabla siguiente.

Preços por milhão de tokens, do catálogo do Kunavo; a coluna da Anthropic vem de claude.com/pricing (consultado a 3 de octubre de 2026):

Dentro de una sesión, puedes cambiar de modelo con /model claude-opus-5-5 o iniciar directamente con claude --model claude-opus-5-5. El cálculo en euros, con ejemplos de uso mensual y el punto a partir del cual compensa más una suscripción, está en Precio de Claude Code en euros; el consumo de cada uno se calcula con la calculadora de costes de tokens. Todos los modelos y precios están en la página de precios.

Confirmar con /status

Ejecuta claude. Con ANTHROPIC_AUTH_TOKEN definida, no aparece la pantalla de inicio de sesión: la variable se aplica de inmediato. Si aparece la pantalla de inicio de sesión, Claude Code no ha leído ninguna clave. En ese caso, defínela en un lugar que Claude Code lea antes del asistente del primer arranque: un export en el shell o el bloque env de ~/.claude/settings.json. Un bloque env en .claude/settings.json o en .claude/settings.local.json de un proyecto solo se aplica, en una sesión interactiva, después del asistente del primer arranque y de la pregunta sobre si se confía en la carpeta.

Dentro da sessão, escreva /status e procure duas linhas no separador Status (fonte: a documentación oficial de gateways, consultada a 3 de octubre de 2026):

• Anthropic base URL debe mostrar https://api.kunavo.com. Esta línea solo aparece cuando hay una dirección de gateway definida; si falta, ANTHROPIC_BASE_URL no ha llegado a la sesión.
• La línea Auth token debe indicar ANTHROPIC_AUTH_TOKEN. Si, en su lugar, aparece Login method con una cuenta de claude.ai, la variable no se ha leído y la sesión está usando la suscripción.

Quien ya hubiera iniciado sesión con una suscripción puede ver, al arrancar, un aviso de que hay dos credenciales activas (el mensaje termina en auth may not work as expected). Las solicitudes siguen usando la clave; /logout elimina el inicio de sesión antiguo.

Para probar la dirección y la clave antes de abrir Claude Code, la documentación sugiere una solicitud de un único token de salida, que consume una fracción ínfima del saldo. Los comandos leen las variables del shell, por lo que debes definirlas allí también, aunque ya estén en settings.json.

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

Una respuesta JSON que empieza por {"id":"msg_ significa que la dirección y la clave funcionan; en PowerShell aparece un id que empieza por msg_. Un 401 significa que no se ha reconocido la clave.

Qué cambia con una clave de API

• Sin Remote Control ni dictado por voz. Según la documentación de gateways, no están disponibles mientras ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN o un apiKeyHelper estén activos; Remote Control también queda desactivado mientras ANTHROPIC_BASE_URL apunte a una dirección fuera de Anthropic.
• /fast muestra el modo rápido como desactivado. Solo con un bearer token, Claude Code trata el modo rápido como desactivado.
• La búsqueda de herramientas MCP (MCP tool search) está desactivada de forma predeterminada quando ANTHROPIC_BASE_URL aponta para um endereço fora da Anthropic (documentación de las variables de entorno, consultada a 3 de octubre de 2026).
• Los números de /context son estimaciones. O Kunavo não serve /v1/messages/count_tokens e, segundo a documentación de compatibilidad para gateways (consultada a 3 de octubre de 2026), sem esse endpoint o Claude Code recorre a uma estimativa baseada em caracteres.

El resto —código, herramientas, subagentes, servidores MCP, hooks y prompt caching— funciona como siempre. Más detalles en la documentación de integración de Claude Code (en inglés) y en Claude Code without a subscription (en inglés).

Pagar el saldo con MB WAY

Primeiro, a subscrição: uma subscrição Claude comprada no site paga-se só com cartão de crédito ou de débito (artículo de ayuda de Anthropic sobre los planes de pago, consultado a 3 de octubre de 2026); numa subscrição feita na aplicação Claude para iOS ou Android, os meios de pagamento são os da App Store ou do Google Play. Os meios de pagamento do Kunavo, MB WAY incluído, não pagam o Claude Pro nem o Max: carregam o saldo da API do Kunavo, que é o que a Rota B usa.

O saldo carrega-se no checkout da Stripe. Os preços estão em dólares americanos; para quem compra em Portugal, a Stripe mostra o valor em euros. Segundo a documentación de Stripe sobre Adaptive Pricing (consultada a 3 de octubre de 2026), essa conversão inclui uma comissão de 2–4% paga pelo comprador; quem escolhe pagar em dólares (com cartão, Apple Pay, Google Pay ou Link) não paga essa comissão, embora o banco possa aplicar a sua própria taxa de câmbio e comissões. O MB WAY só funciona em euros. No checkout em euros aparecem:

• MB WAY. Escolhe-se MB WAY, introduz-se o número de telemóvel e confirma-se a compra na aplicação MB WAY, através da notificação ou na área de atividade (Stripe sobre MB WAY e MB WAY sobre compras en línea, consultados a 3 de octubre de 2026). Segundo a Stripe, são aceites números internacionais, mas a maioria dos clientes usa um número português, começado por +351.
• Tarjetas (Visa, Mastercard), Apple Pay, Google Pay y Link.

Não aparecem: referências Multibanco (pagamento por entidade e referência), PayPal, débito direto SEPA e Klarna, que só aparece a compradores nos Estados Unidos. A conversão para euros vem do Adaptive Pricing da Stripe, e a lista de meios de pagamento que ele disponibiliza inclui o MB WAY mas não o Multibanco. O MB WAY também permite gerar cartões virtuais MB NET para compras online (MB WAY sobre MB NET, consultado a 3 de octubre de 2026); não está confirmado que o campo do cartão do checkout os aceite, por isso o caminho seguro é escolher MB WAY diretamente.

Lo que documenta Stripe sobre MB WAY (consultado a 3 de octubre de 2026):

• Por pago: entre 0,50 € y 5000 €.
• Por día: 1000 € de forma predeterminada, ajustable hasta 10 000 € en la aplicación MB WAY. Las recargas mayores pueden superar el límite diario predeterminado; en ese caso, auméntalo en la aplicación antes de pagar. Compara el importe en euros que muestra el checkout con estos límites.
• Pagos recurrentes: no compatibles.
• En el extracto aparece el nombre de Stripe (Stripe Inc), con el importe de la operación.

1. Crear una cuenta en Kunavo.
2. En Facturación, elige un importe, a partir de US$ 10. Las recargas mayores incluyen saldo adicional: quem carrega US$ 100 recebe US$ 110; quem carrega US$ 1000 recebe US$ 1200; quem carrega US$ 5000 recebe US$ 6250.
3. En el checkout de Stripe, con el importe en euros, selecciona MB WAY, introduce el número de teléfono y confirma la compra en la aplicación MB WAY. El importe en euros aparece antes de la confirmación.
4. En /app/keys, crea la clave y colócala en ANTHROPIC_AUTH_TOKEN.

El saldo es prepagado: no hay cuota mensual, el saldo no caduca y no se cobran las solicitudes que fallan. La recarga automática solo funciona con una tarjeta guardada o con Link; con MB WAY, siempre se recarga manualmente porque, según Stripe, MB WAY no admite pagos recurrentes ni se guarda para pagos futuros. Kunavo no emite facturas, ni con NIF ni con IVA; el historial de recargas queda en Billing. Estos métodos de pago solo recargan el saldo de la API de Kunavo. Más información sobre el tema en Pagar Claude con MB WAY.

Errores comunes

Después de instalar

En el primer arranque de un proyecto, escribe /init: Claude Code recorre el repositorio y escribe un CLAUDE.md con lo que ha deducido: cómo ejecutar el proyecto, cómo probar los cambios y qué reglas de estilo sigue. Revisa este archivo y mantenlo breve, porque se carga en todas las sesiones. Entre tareas independientes, /clear inicia una conversación nueva; en una tarea larga, /compact resume el historial para continuar.

Lo que conviene saber

• Es una API de pago por token, no una suscripción Claude Pro o Max. Quienes usan Claude Code varias horas todos los días suelen pagar menos con una suscripción; pagar por token compensa con un uso irregular, y un mes sin actividad no cuesta nada. La comparación en euros está en Precio de Claude Code en euros.
• Quien usa una clave de API no tiene Remote Control ni dictado por voz.
• A través de Kunavo se utiliza capacidad compartida, sin cuota reservada ni garantías contractuales; quienes las necesiten deben contratar directamente con Anthropic.
• MB WAY solo sirve para recargas manuales; la recarga automática requiere una tarjeta o Link.
• Los importes en euros que se muestran en el checkout ya incluyen la comisión de conversión de Stripe.

Preguntas frecuentes