Tutorial de instalación de Claude Code: comandos de instalación para Windows y macOS, configuración con API key sin iniciar sesión y recarga con Alipay y WeChat Pay

La instalación recomendada de Claude Code utiliza el comando nativo oficial de Anthropic; npm es la alternativa oficial y requiere Node.js 22 o superior. Puedes usar Claude Code sin iniciar sesión en una cuenta de Claude: configura ANTHROPIC_BASE_URL (solo el dominio, sin añadir /v1), ANTHROPIC_AUTH_TOKEN y las cuatro líneas de fijación del modelo para usar una clave de API facturada por token. El saldo de API de Kunavo puede recargarse mediante Alipay o WeChat Pay; la recarga mínima es de $10. Por último, ejecuta /status en Claude Code para confirmar la conexión.

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

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

:: Windows 命令提示符（CMD）
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

命令和环境变量核对于 3 de octubre de 2026，依据 Documentación oficial de instalación de Claude Code和 Documentación oficial de variables de entorno；价格和付款方式核对于 3 de octubre de 2026。先说明一个事实：Lista de países y regiones admitidos por Anthropic（核对于 3 de octubre de 2026）中没有中国大陆、香港和澳门，Claude Code 安装文档的系统要求里也有一行「所在地区：Anthropic 支持的国家」。本页只讲官方文档写明的安装和配置方法，不提供任何绕过地区限制的办法。Kunavo 没有在中国大陆做过网络连通性测试，下面提到的下载地址、npm 源和 api.kunavo.com 能否在你的网络里访问，需要你自己确认。

Comprobaciones previas a la instalación

Método 1: instalación nativa oficial (recomendada)

La documentación oficial de instalación marca la instalación nativa como recomendada. Los comandos son las tres secciones del inicio de esta página: para macOS, Linux y WSL usa la línea install.sh; para Windows PowerShell, irm … | iex; y para Windows CMD, la línea install.cmd. La instalación nativa se actualiza automáticamente en segundo plano a la última versión; la documentación oficial también indica que las instalaciones mediante Homebrew y WinGet no se actualizan automáticamente por defecto.

Después de instalarlo, abre una ventana de terminal nueva (las ventanas ya abiertas no detectan el nuevo PATH) y confirma:

claude --version   # 正常会打印版本号，后面跟着 (Claude Code)
claude doctor      # 只读的安装与设置诊断，不会开启会话

claude doctor no inicia una sesión; solo muestra el estado de instalación y la información de diagnóstico de los archivos de configuración, por lo que permite distinguir entre un problema de instalación y uno de configuración.

Cuando la descarga falla

如果终端里出现 syntax error near unexpected token '<' 或 curl: (22) The requested URL returned error: 403，按 Documentación oficial de solución de problemas de instalación（核对于 3 de octubre de 2026）的说法，这表示安装地址返回的是一个网页或错误状态码，而不是安装脚本。如果返回的网页写着 App unavailable in region，官方的解释是：Claude Code 在你所在的国家或地区不可用。不带网页内容的 403 也可能来自公司代理或防火墙拦截下载；官方建议，在支持地区内仍然遇到 403 时，先排查网络连接，再考虑其他安装方式。

Método 2: instalación mediante npm (requiere Node.js 22 o superior)

npm 仍是官方文档列出的安装方式。官方文档写明 npm 包需要 Node.js 22 或更高版本；版本较旧时 npm 会打印 EBADENGINE 警告但不会失败，安装照样完成，因为这个包下载的是一个运行时不依赖 Node.js 的原生程序。没有 Node.js 的话，从 Sitio web oficial de Node.js安装 22 或更高版本。

node -v                                    # 需要 v22 或更高
npm install -g @anthropic-ai/claude-code   # 不要加 sudo

La documentación oficial indica explícitamente que no uses sudo npm install -g, ya que puede causar problemas de permisos y riesgos de seguridad. Para actualizar, usa npm install -g @anthropic-ai/claude-code@latest, no npm update -g.

Cuando la descarga desde el registro predeterminado falla o es muy lenta: npmmirror

如果从 npm 默认源下载失败或很慢，可以改用 npmmirror。Página principal de npmmirror（核对于 3 de octubre de 2026）说明它是「完整 npmjs.com 镜像」，只读，会「尽量与官方服务实时同步」，并给出了 registry 地址和设置命令。首页没有写明具体同步频率。

# 只在这一次安装时使用 npmmirror
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

# 或者把 npmmirror 设为 npm 的默认源（之后所有 npm 安装都会走它）
npm config set registry https://registry.npmmirror.com

# 以后升级用 @latest，不要用 npm update -g
npm install -g @anthropic-ai/claude-code@latest --registry=https://registry.npmmirror.com

La instalación de Claude Code mediante un espejo tiene dos condiciones fáciles de pasar por alto, ambas procedentes de la documentación oficial de solución de problemas:

• El espejo debe proporcionar simultáneamente 8 paquetes de plataforma. El paquete npm en sí es solo una envoltura; el programa real se descarga como dependencia opcional en forma de paquetes de plataforma @anthropic-ai/claude-code-*. Si al espejo le faltan paquetes, después de instalarlo, al ejecutar claude en macOS o Linux aparecerá claude native binary not installed (en Windows, PowerShell o CMD indicará que no se puede ejecutar el archivo). 3 de octubre de 2026, al consultar Kunavo desde una red fuera de China continental, los paquetes principal, Windows x64, macOS ARM64 y Linux x64 de npmmirror coincidían con las versiones más recientes de npmjs; no se comprobaron los demás paquetes de plataforma (Windows ARM64, Mac Intel, Linux ARM64 y las dos versiones musl).
• No omitas las dependencias opcionales. No incluyas --omit=optional en el comando de instalación y confirma también que optional=false no esté configurado en .npmrc.

Sección específica para Windows

Windows tiene dos comandos de instalación distintos; la diferencia depende del terminal que abras. El indicador PS C:\Users\你的用户名> corresponde a PowerShell; el que no contiene PS y solo muestra C:\Users\你的用户名> corresponde al símbolo del sistema (CMD). La documentación oficial indica que no es necesario ejecutar la instalación como administrador.

Un error frecuente en Windows consiste en pegar el comando del terminal equivocado: si ejecutas la línea de CMD en PowerShell, verás The token '&&' is not a valid statement separator; si ejecutas la línea de PowerShell en CMD, verás 'irm' is not recognized as an internal or external command. En ambos casos, cambia a la línea correspondiente. Además, el menú Inicio contiene dos entradas, «Windows PowerShell» y «Windows PowerShell (x86)»; la segunda es un proceso de 32 bits y mostrará Claude Code does not support 32-bit Windows, así que abre la que no incluye (x86).

Git for Windows 是可选的：装了以后 Claude Code 用它附带的 Git Bash 执行命令；没装时改用 PowerShell 工具执行。装了却找不到 Git Bash 时，在 ~/.claude/settings.json 的 env 里设置 CLAUDE_CODE_GIT_BASH_PATH，指向 bash.exe，官方示例路径是 C:\Program Files\Git\bin\bash.exe。

Si eliges WSL, ejecuta la línea de macOS/Linux en el terminal de WSL e inicia también claude en WSL, no en PowerShell o CMD.

Error de la estrategia de ejecución en la ruta npm

Al instalar o ejecutar npm en PowerShell, si aparece npm.ps1 cannot be loaded because running scripts is disabled on this system, significa que la estrategia de ejecución de PowerShell bloqueó el script de inicio .ps1 generado por npm. La documentación oficial ofrece tres soluciones: permitir que el usuario actual ejecute scripts locales (la línea siguiente); usar npm.cmd y claude.cmd; o utilizar el comando de instalación nativa de PowerShell.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Después de instalarlo, aparece un mensaje que indica que no se encuentra claude

Si aparece command not found: claude o 'claude' is not recognized, significa que el directorio de instalación no está en PATH. La instalación nativa coloca el programa en ~/.local/bin/claude en macOS/Linux y en %USERPROFILE%\.local\bin\claude.exe en Windows. Primero abre una nueva terminal y vuelve a intentarlo; si sigue sin funcionar en Windows, sigue la documentación oficial de resolución de problemas para comprobarlo con PowerShell y añadir el directorio al PATH del usuario:

# 1. 检查安装目录是否已在 PATH 里
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. 没有任何输出时，把它加进「用户」PATH，然后关掉终端重新打开
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. 重新打开终端后确认
claude --version

Configurar la clave de API: sin iniciar sesión en una cuenta de Claude

ANTHROPIC_BASE_URL es una variable de entorno incluida en Claude Code. La documentación oficial la describe como una forma de sustituir el endpoint de la API para que las solicitudes pasen por un proxy o una pasarela. Por tanto, apuntar Claude Code a un endpoint que proporcione la API Anthropic Messages es una configuración admitida oficialmente; no requiere un complemento ni modificar el programa. En macOS/Linux, escríbela en el archivo de configuración del shell:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # 只写到域名，不要加 /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

Si quieres probarlo primero en Windows, hazlo en una ventana de PowerShell:

# 只对当前 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 usarlo a largo plazo, se recomienda escribirlo en ~/.claude/settings.json, dentro de env (en Windows es %USERPROFILE%\.claude\settings.json). Al escribirlo aquí, todos los terminales y las tareas en segundo plano pueden leerlo; si el archivo ya contiene otras configuraciones, integra env en ellas:

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

Estas seis líneas tienen cada una un aspecto fácil de configurar incorrectamente:

• ANTHROPIC_BASE_URL solo debe contener el dominio. Claude Code añade automáticamente /v1/messages; si escribes también /v1, se convertirá en /v1/v1/messages y devolverá 404.
• Usa ANTHROPIC_AUTH_TOKEN, no ANTHROPIC_API_KEY. La documentación oficial indica que el valor de ANTHROPIC_AUTH_TOKEN se envía como la cabecera Authorization y añade automáticamente el prefijo Bearer; surte efecto de inmediato. En cambio, ANTHROPIC_API_KEY requiere una confirmación inicial en el modo interactivo; si eliges rechazarla, esa clave se ignorará silenciosamente después (debes volver a activarla en /config, dentro de Use custom API key).
• ANTHROPIC_MODEL determina el modelo principal. Aquí se fija en Claude Sonnet 5 (claude-sonnet-5). El nombre del modelo debe coincidir exactamente con la lista de modelos de Kunavo; los nombres antiguos con sufijo de fecha no se asignan automáticamente.
• ANTHROPIC_DEFAULT_OPUS_MODEL determina el alias opus.按 Documentación oficial de configuración de modelos（核对于 3 de octubre de 2026），API 用户的默认模型和 opus 别名指向最新的 Opus（目前是 Opus 5.5），sonnet 别名指向 Sonnet 5.5，而且别名会跟着 Anthropic 的新版本移动。官方文档写明别名「会随时间更新」，要固定版本，就写完整模型名或设置 ANTHROPIC_DEFAULT_OPUS_MODEL 这类变量。Kunavo 目前没有提供 Sonnet 5.5，Anthropic 以后发布新 Opus 时 Kunavo 也不一定已经上架，没上架的模型会返回 404。这就是要把主模型、opus 和 sonnet 别名都固定下来的原因。这里 opus 别名固定为 Claude Opus 5.5（claude-opus-5-5），需要 Claude Code v2.1.280 或更高版本，旧版本先运行 claude update 升级。
• ANTHROPIC_DEFAULT_SONNET_MODEL determina el alias sonnet. La documentación oficial indica que esta variable determina a qué modelo apunta el alias sonnet y qué modelo utiliza opusplan fuera del modo de planificación, durante la fase de ejecución. Por defecto, el alias sonnet solicita Sonnet 5.5, que Kunavo no ofrece actualmente; por eso, si no configuras esta línea, /model sonnet, la fase de ejecución de opusplan y los subagentes que especifican model: sonnet devolverán 404. Aquí también se fija en Claude Sonnet 5 (claude-sonnet-5).
• ANTHROPIC_DEFAULT_HAIKU_MODEL también controla las tareas en segundo plano. La documentación oficial indica que esta variable determina el alias haiku y también se utiliza para funciones en segundo plano. En Kunavo, por millón de tokens, Claude Haiku 4.5 cuesta $0.70 de entrada y $3.50 de salida; el modelo principal Claude Sonnet 5 cuesta $1.40 / $7.00 (precio oficial de Anthropic: $2.00 / $10.00); el modelo Claude Opus 5.5 asociado al alias opus cuesta $2.80 / $14.00.

No escribas la clave en .claude/settings.json dentro del proyecto: la documentación oficial advierte que este archivo se confirmará en el repositorio y se compartirá con todas las personas que lo clonen. Ten presente también una regla de prioridad: si la misma variable se configura en el shell y en el archivo settings, prevalece el valor del archivo settings. Si cambias la variable del shell y no surte efecto, comprueba primero el archivo settings.

Qué ocurre la primera vez que se ejecuta

按官方的 Documentación de conexión de la pasarela（核对于 3 de octubre de 2026），设置了 ANTHROPIC_AUTH_TOKEN 后运行 claude，会直接进入会话，No se muestra la página de inicio de sesión；这个变量立即生效，不像 ANTHROPIC_API_KEY 那样要先确认一次。如果打开后看到的是登录页，说明 Claude Code 没有读到凭据。

Las credenciales deben estar en un lugar que Claude Code lea antes de la configuración inicial: export en el shell o env dentro de ~/.claude/settings.json a nivel de usuario. La documentación oficial indica que, en el modo interactivo, env de .claude/settings.json o .claude/settings.local.json dentro del proyecto no surte efecto hasta después del asistente de configuración inicial y del aviso de confianza de la carpeta; por eso, si la clave está en la configuración del proyecto, la primera vez que se inicia aún aparecerá la página de inicio de sesión.

Después de entrar en la sesión, ejecuta /status y consulta estas dos líneas en la página Status:

• Anthropic base URL: solo aparece cuando se ha configurado la dirección de la pasarela y debería mostrar https://api.kunavo.com. Si no aparece esta línea, significa que ANTHROPIC_BASE_URL no se ha transmitido a esta sesión.
• Auth token: si muestra ANTHROPIC_AUTH_TOKEN, significa que se está usando una clave de API y no un inicio de sesión de claude.ai guardado. Si muestra Login method junto con una cuenta de claude.ai, la variable no ha surtido efecto.

Si quieres probar la dirección y la clave por separado antes de abrir Claude Code, puedes enviar, siguiendo el método de la documentación oficial, una solicitud con solo 1 token de salida (se descontará una cantidad mínima del saldo según los tokens). Este comando lee las variables del shell, así que aunque hayas escrito la clave en el archivo settings, primero debes ejecutar export en el terminal actual. Si el JSON devuelto comienza por {"id":"msg_, la dirección y la clave son correctas; si devuelve 401, la clave no se ha reconocido.

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

Qué cambia al usar una clave de API

• Remote Control y la entrada de voz no están disponibles. La documentación oficial indica que ambas funciones dependen de una identidad de claude.ai y no están disponibles al configurar ANTHROPIC_AUTH_TOKEN; si ANTHROPIC_BASE_URL apunta a una dirección que no es de Anthropic, Remote Control también se desactiva.
• /fast mostrará que el modo fast está desactivado. La documentación oficial indica que, cuando solo hay un bearer token, Claude Code trata directamente el modo fast como desactivado y no envía comprobaciones de disponibilidad.
• La búsqueda de herramientas MCP está desactivada de forma predeterminada. La documentación oficial indica que, cuando ANTHROPIC_BASE_URL apunta a una dirección que no es de Anthropic, la búsqueda de herramientas MCP se desactiva de forma predeterminada.
• Los números de /context son estimaciones locales.Kunavo 目前不提供 /v1/messages/count_tokens。按 Documentación oficial de compatibilidad con pasarelas（核对于 3 de octubre de 2026），网关没有这个端点时，Claude Code 改用按字符估算，/context 显示的是近似值。

Consulta las instrucciones completas de integración en la documentación de integración de Claude Code (en inglés).

Qué desactiva exactamente CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC

按 Documentación oficial de variables de entorno（核对于 3 de octubre de 2026），它的作用是关闭 Claude Code 的非必要网络流量，官方列出的内容是：

• Actualizaciones automáticas, telemetría e informes de errores;
• El comando /feedback y los comentarios redactados por Claude;
• Notas de la versión y comprobaciones de insignias de estado de PR/MR;
• Comprobaciones de disponibilidad, como el modo fast;
• La descarga de indicadores de funciones (feature flags), por lo que Remote Control y otras funciones que dependen de ellos dejan de estar disponibles;
• La reejecución en segundo plano del origen del complemento command (es un comando local, no tráfico de red, porque puede activar la instalación de dependencias).

La documentación oficial también especifica estos detalles: establecerlo en 0 o false cuenta como activado; a diferencia de la mayoría de las variables de conmutación, solo se restaura al eliminar la variable; la instalación automática del mercado oficial de complementos no está incluida; y no afecta al descubrimiento de modelos de la pasarela. La documentación oficial de pasarelas añade que no afecta a la comprobación de seguridad de dominios de WebFetch, que sigue accediendo a api.anthropic.com; para desactivarla hay que añadir skipWebFetchPreflight: true en la configuración. La documentación oficial no describe esta variable como una configuración relacionada con el control de riesgos de la cuenta.

Kunavo 不要求设置它，它也不影响发往 Kunavo 的模型请求。什么时候值得开启，官方 Documentación de conexión de la pasarela（核对于 3 de octubre de 2026）给了一个场景：即使 ANTHROPIC_BASE_URL 指向网关，Claude Code 仍会向 Anthropic 和 GitHub 等第三方发送版本检查、遥测、发布说明之类的后台请求；如果你的网络只允许访问网关地址，这些请求会失败，并可能在出站监控里显示为被拦截的连接，官方的做法就是和网关变量一起设置这个变量。

El coste de activarlo es que deja de actualizarse automáticamente; la documentación oficial recomienda organizar otra vía de actualización. Con una instalación npm, actualiza manualmente mediante @latest (consulta la última línea de la sección anterior sobre npmmirror).

# 可选：关闭 Claude Code 的非必要网络流量（会同时关闭自动更新）
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

# 想恢复时删掉这个变量；设成 0 或 false 仍然算开启
unset CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC

Recargar mediante Alipay o WeChat Pay y obtener una clave

Anthropic 官方的网页订阅只收信用卡或借记卡（Preguntas frecuentes sobre la facturación de los planes de pago de Claude，核对于 3 de octubre de 2026）。在 Kunavo 充值可以用支付宝或微信支付，步骤概要如下，完整步骤见 Guía para recargar la API de Claude mediante Alipay y WeChat Pay：

1. Registra una cuenta de Kunavo con tu correo electrónico o una cuenta de Google; no necesitas vincular una tarjeta para registrarte.
2. En Facturación, elige el importe de la recarga; la mínima es de $10 y no hay cuota mensual. Las recargas mayores incluyen un bono: 充 $100 到账 $110、充 $1000 到账 $1200、充 $5000 到账 $6250.
3. En la página de pago de Stripe, elige Alipay o WeChat Pay y paga escaneando el código QR. Al abrirla desde China continental, el importe se muestra en yuanes; toma como referencia la cifra de la página de pago.
4. Ve a /app/keys para crear una clave que empiece por sk-kn- (solo se mostrará una vez; guárdala inmediatamente) e introdúcela en ANTHROPIC_AUTH_TOKEN arriba.

Alipay y WeChat Pay solo permiten recargas manuales; la recarga automática solo puede configurarse con una tarjeta bancaria o Link. Kunavo no emite facturas chinas de IVA; puedes consultar el historial de recargas en la página Billing.

Cuánto se gasta aproximadamente (algoritmo ilustrativo)

Claude Code cobra por token; cada solicitud vuelve a enviar todo el contexto de la conversación, y el prefijo que coincide con el de la solicitud anterior puede facturarse mediante lectura de caché. Lo siguiente es solo una aritmética ilustrativa de tokens, no una factura real ni un límite de costes. Se enumeran todas las condiciones supuestas:

• Cada solicitud contiene 40,000 tokens de entrada; 36,000 (90 %) se factura como lectura de caché y los 4,000 restantes como escritura de caché;
• Cada solicitud genera 1,000 tokens de salida;
• Durante un periodo de trabajo se envían 50 solicitudes de este tipo; no se incluyen las llamadas en segundo plano de Claude Haiku 4.5;
• Precios de Kunavo: la lectura de caché cuesta 10% del precio de entrada y la escritura de caché cuesta 1.25 veces el precio de entrada (la proporción de Claude Sonnet 5; en la tabla, cada modelo se calcula con su propia proporción).

El coste real depende de la longitud del contexto, de cuántas veces se acierte la caché, de la longitud de la salida y de si utilizas /clear para borrar la conversación entre tareas. Para saber cómo elegir entre la suscripción de Claude Code y la API y cuánto se gasta aproximadamente al mes, consulta Precios de Claude Code; los precios completos de cada modelo están en Precios de la API de Claude y en la página de precios. Para estimarlo según tu propio uso, puedes utilizar la calculadora de costes de tokens de Claude (en inglés).

Tabla de errores frecuentes

Limitaciones que debes conocer

• Kunavo no emite facturas chinas de IVA.
• Alipay y WeChat Pay solo permiten recargas manuales; la recarga automática solo puede configurarse con una tarjeta bancaria o Link.
• Esta es una API facturada por token, no una suscripción Claude Pro/Max; al usar una clave de API, Remote Control y la entrada de voz no están disponibles. Consulta Precios de Claude Code para saber cuál elegir.
• Kunavo no ha realizado pruebas de conectividad de red desde China continental. Debes comprobar por tu cuenta si las direcciones de instalación de claude.ai, los registros npm, npmmirror y api.kunavo.com son accesibles desde tu red y qué velocidad ofrecen.
• La lista de países y regiones admitidos por Anthropic (comprobada el 3 de octubre de 2026) no incluye China continental, Hong Kong ni Macao; la documentación oficial de instalación de Claude Code incluye la región donde te encuentras entre los requisitos del sistema.

Preguntas frecuentes