Tutorial de instalação do Claude Code: comandos de instalação para Windows e macOS, configuração com API key sem fazer login e recarga com Alipay e WeChat Pay

Instale o Claude Code usando o comando oficial de instalação nativa da Anthropic; npm é a alternativa oficial e exige Node.js 22 ou superior. Também é possível usar o Claude Code sem fazer login na conta Claude: defina ANTHROPIC_BASE_URL (apenas o domínio, sem /v1), ANTHROPIC_AUTH_TOKEN e as quatro linhas de fixação de modelos para usar uma chave de API cobrada por token. O saldo da API da Kunavo pode ser recarregado com Alipay ou WeChat Pay, com mínimo de $10. Por fim, execute /status no Claude Code para confirmar a conexão.

# 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 outubro de 2026，依据 Documentação oficial de instalação do Claude Code和 Documentação oficial de variáveis de ambiente；价格和付款方式核对于 3 de outubro de 2026。先说明一个事实：Lista de países e regiões compatíveis com a Anthropic（核对于 3 de outubro de 2026）中没有中国大陆、香港和澳门，Claude Code 安装文档的系统要求里也有一行「所在地区：Anthropic 支持的国家」。本页只讲官方文档写明的安装和配置方法，不提供任何绕过地区限制的办法。Kunavo 没有在中国大陆做过网络连通性测试，下面提到的下载地址、npm 源和 api.kunavo.com 能否在你的网络里访问，需要你自己确认。

Confirmação antes da instalação

Método 1: instalação nativa oficial (recomendada)

A documentação oficial de instalação marca a instalação nativa como recomendada. Os comandos são os três blocos no início desta página: macOS, Linux e WSL usam a linha install.sh, o PowerShell do Windows usa irm … | iex e o CMD do Windows usa a linha install.cmd. A instalação nativa é atualizada automaticamente em segundo plano para a versão mais recente; a documentação oficial também informa que as instalações via Homebrew e WinGet não são atualizadas automaticamente por padrão.

Depois da instalação, abra uma nova janela do terminal (as janelas já abertas não detectam o novo PATH) e confirme:

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

claude doctor não inicia uma sessão; apenas exibe o status da instalação e informações de diagnóstico dos arquivos de configuração, permitindo distinguir entre uma instalação quebrada e uma configuração incorreta.

Quando o download falhar

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

Método 2: instalação via npm (requer Node.js 22 ou superior)

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

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

A documentação oficial exige claramente não usar sudo npm install -g, pois isso causa problemas de permissões e riscos de segurança. Para atualizar, use npm install -g @anthropic-ai/claude-code@latest, não npm update -g.

Quando o download da fonte padrão falhar ou estiver lento: npmmirror

如果从 npm 默认源下载失败或很慢，可以改用 npmmirror。Página inicial do npmmirror（核对于 3 de outubro 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

A instalação do Claude Code usando um espelho tem duas condições fáceis de esquecer, ambas provenientes da documentação oficial de solução de problemas:

• O espelho deve fornecer simultaneamente 8 pacotes de plataforma. O próprio pacote npm é apenas um invólucro; o programa real é baixado como dependência opcional na forma dos pacotes de plataforma @anthropic-ai/claude-code-*. Se o espelho não tiver os pacotes, executar claude após a instalação no macOS ou Linux exibirá claude native binary not installed (no Windows, o PowerShell ou o CMD informará que não consegue executar o arquivo). 3 de outubro de 2026, a Kunavo verificou, a partir de uma rede fora da China continental, que o pacote principal e os pacotes Windows x64, macOS ARM64 e Linux x64 do npmmirror correspondem às versões mais recentes do npmjs; os demais pacotes de plataforma (Windows ARM64, Mac Intel, Linux ARM64 e as duas versões musl) não foram conferidos.
• Não ignore as dependências opcionais. Não inclua --omit=optional no comando de instalação e confirme também que optional=false não está definido em .npmrc.

Informações específicas do Windows

O Windows tem dois comandos de instalação diferentes; a diferença depende do terminal aberto. O prompt que contém PS C:\Users\你的用户名> é o PowerShell; aquele sem PS e com apenas C:\Users\你的用户名> é o prompt de comando (CMD). A documentação oficial informa que a instalação não exige execução como administrador.

Um erro comum no Windows é colar o comando no terminal errado: ao executar a linha do CMD no PowerShell, aparecerá The token '&&' is not a valid statement separator; ao executar a linha do PowerShell no CMD, aparecerá 'irm' is not recognized as an internal or external command. Basta trocar pela linha correspondente. Além disso, o menu Iniciar contém as entradas “Windows PowerShell” e “Windows PowerShell (x86)”; a segunda é um processo de 32 bits e exibirá Claude Code does not support 32-bit Windows, portanto abra a que não contém (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。

Se escolher o WSL, execute a linha para macOS/Linux no terminal do WSL e também inicie claude no WSL, não no PowerShell ou CMD.

Erro na política de execução da rota npm

Ao instalar ou executar o npm no PowerShell, se aparecer npm.ps1 cannot be loaded because running scripts is disabled on this system, a política de execução do PowerShell bloqueou o script de inicialização .ps1 gerado pelo npm. A documentação oficial oferece três soluções: permitir que o usuário atual execute scripts locais (a linha abaixo); usar npm.cmd e claude.cmd; ou usar o comando de instalação nativa do PowerShell.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Após a instalação, aparece um aviso de que claude não foi encontrado

Se aparecer command not found: claude ou 'claude' is not recognized, isso indica que o diretório de instalação não está no PATH. A instalação nativa coloca o programa em ~/.local/bin/claude no macOS/Linux e em %USERPROFILE%\.local\bin\claude.exe no Windows. Primeiro, abra um novo terminal e tente novamente; se ainda não funcionar no Windows, siga a documentação oficial de solução de problemas para verificar e adicionar o diretório ao PATH do usuário usando o PowerShell:

# 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 a chave de API: sem fazer login na conta Claude

ANTHROPIC_BASE_URL é uma variável de ambiente integrada ao Claude Code. A documentação oficial a descreve como uma forma de substituir o endpoint da API, fazendo as solicitações passarem por um proxy ou gateway. Portanto, apontar o Claude Code para um endpoint que forneça a Anthropic Messages API é uma configuração oficialmente compatível; não são necessários plugins nem um programa modificado. No macOS/Linux, escreva-a no arquivo de configuração do 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

Para testar primeiro em uma janela do PowerShell no Windows:

# 只对当前 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 contínuo, recomenda-se escrever em env dentro do arquivo de configurações do usuário ~/.claude/settings.json (no Windows, %USERPROFILE%\.claude\settings.json). Assim, cada terminal e tarefa em segundo plano poderá ler a configuração; se o arquivo já tiver outras configurações, mescle env nelas:

{
  "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 linhas têm, cada uma, um ponto fácil de configurar incorretamente:

• ANTHROPIC_BASE_URL deve conter apenas o domínio. O Claude Code acrescenta /v1/messages automaticamente; se você adicionar /v1, o resultado será /v1/v1/messages e retornará 404.
• Use ANTHROPIC_AUTH_TOKEN, não ANTHROPIC_API_KEY. A documentação oficial informa que o valor de ANTHROPIC_AUTH_TOKEN é enviado como o cabeçalho Authorization e recebe automaticamente o prefixo Bearer; ele entra em vigor imediatamente. Já ANTHROPIC_API_KEY exige uma confirmação inicial no modo interativo; se você escolher recusar, essa chave será ignorada silenciosamente depois (reative-a em /config, em Use custom API key).
• ANTHROPIC_MODEL determina o modelo principal. Aqui, fixe-o como Claude Sonnet 5 (claude-sonnet-5). O nome do modelo deve corresponder exatamente à lista de modelos da Kunavo; nomes antigos com sufixo de data não serão associados automaticamente.
• ANTHROPIC_DEFAULT_OPUS_MODEL determina o alias opus.按 Documentação oficial de configuração de modelos（核对于 3 de outubro 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 o alias sonnet. A documentação oficial informa que essa variável determina para qual modelo o alias sonnet aponta e qual modelo opusplan usa fora do modo de planejamento, na fase de execução. O alias sonnet solicita o Sonnet 5.5 por padrão, que a Kunavo atualmente não oferece; portanto, sem esta linha, a fase de execução de /model sonnet, opusplan e os subagentes que especificam model: sonnet retornarão 404. Aqui, fixe-o igualmente como Claude Sonnet 5 (claude-sonnet-5).
• ANTHROPIC_DEFAULT_HAIKU_MODEL também controla as tarefas em segundo plano. A documentação oficial informa que essa variável determina o alias haiku e também é usada pelos recursos em segundo plano. Na Kunavo, Claude Haiku 4.5 custa por milhão de tokens: entrada $0.70, saída $3.50; o modelo principal Claude Sonnet 5 custa $1.40 / $7.00(preço oficial da Anthropic: $2.00 / $10.00); para o alias opus, Claude Opus 5.5 custa $2.80 / $14.00.

Não escreva a chave no .claude/settings.json do projeto: a documentação oficial alerta que esse arquivo será enviado e compartilhado com todas as pessoas que clonarem o repositório. Observe também a prioridade: quando a mesma variável estiver definida no shell e no arquivo settings, prevalecerá o valor no arquivo settings. Se alterar a variável do shell e ela não tiver efeito, verifique primeiro o arquivo settings.

O que acontece na primeira execução

按官方的 Documentação de conexão com o gateway（核对于 3 de outubro de 2026），设置了 ANTHROPIC_AUTH_TOKEN 后运行 claude，会直接进入会话，A página de login não é exibida；这个变量立即生效，不像 ANTHROPIC_API_KEY 那样要先确认一次。如果打开后看到的是登录页，说明 Claude Code 没有读到凭据。

As credenciais devem estar em um local que o Claude Code leia antes da configuração inicial: export no shell ou env dentro do ~/.claude/settings.json do usuário. A documentação oficial informa que, no modo interativo, o env em .claude/settings.json ou .claude/settings.local.json no projeto só terá efeito após o assistente de configuração inicial e a solicitação de confiança na pasta; portanto, quando a chave está nas configurações do projeto, a primeira inicialização ainda exibirá a página de login.

Depois de entrar na sessão, execute /status e veja estas duas linhas na página Status:

• Anthropic base URL: só aparece quando o endereço do gateway está definido e deve mostrar https://api.kunavo.com. Se esta linha não aparecer, significa que ANTHROPIC_BASE_URL não foi transmitida para esta sessão.
• Auth token: se mostrar ANTHROPIC_AUTH_TOKEN, significa que uma chave de API está sendo usada, não um login claude.ai salvo. Se aparecer Login method com uma conta claude.ai, a variável não teve efeito.

Para testar o endereço e a chave separadamente antes de abrir o Claude Code, use o método da documentação oficial para enviar uma solicitação com apenas 1 token de saída (o saldo cobrado será mínimo). Esse comando lê as variáveis do shell; portanto, mesmo que você tenha escrito a chave no arquivo settings, primeiro execute export no terminal atual. Um JSON que comece com {"id":"msg_ indica que o endereço e a chave estão corretos; 401 indica que a chave não foi reconhecida.

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

O que muda ao usar uma chave de API

• Remote Control e entrada de voz não ficam disponíveis. A documentação oficial informa que esses recursos dependem de uma identidade claude.ai e não ficam disponíveis quando ANTHROPIC_AUTH_TOKEN está definido; quando ANTHROPIC_BASE_URL aponta para um endereço que não é da Anthropic, o Remote Control também é desativado.
• /fast mostrará que o modo fast está desativado. A documentação oficial informa que, com apenas um bearer token, o Claude Code trata diretamente o modo fast como desativado e não envia a verificação de disponibilidade.
• A busca de ferramentas MCP fica desativada por padrão. A documentação oficial informa que, quando ANTHROPIC_BASE_URL aponta para um endereço que não é da Anthropic, a busca de ferramentas MCP fica desativada por padrão.
• Os números em /context são estimativas locais.Kunavo 目前不提供 /v1/messages/count_tokens。按 Documentação oficial de compatibilidade com gateways（核对于 3 de outubro de 2026），网关没有这个端点时，Claude Code 改用按字符估算，/context 显示的是近似值。

As instruções completas de integração estão na documentação de integração do Claude Code (em inglês).

O que CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC desativa exatamente

按 Documentação oficial de variáveis de ambiente（核对于 3 de outubro de 2026），它的作用是关闭 Claude Code 的非必要网络流量，官方列出的内容是：

• Atualizações automáticas, telemetria e relatórios de erros;
• O comando /feedback e o feedback redigido pelo Claude;
• Notas de versão e verificações de badges de status de PR/MR;
• Verificações de disponibilidade, como o modo fast;
• Busca de feature flags; portanto, o Remote Control e outros recursos que dependem de feature flags ficarão indisponíveis;
• Reexecução em segundo plano da origem do plugin command (este é um comando local, não tráfego de rede, pois pode acionar a instalação de dependências).

Há também alguns detalhes informados oficialmente: definir como 0 ou false também conta como ativação; ao contrário da maioria das variáveis de alternância, somente remover a variável a desativa. A instalação automática do marketplace oficial de plugins não está incluída; ela não afeta a descoberta de modelos do gateway. A documentação oficial do gateway acrescenta que ela não afeta a verificação de segurança de domínio da ferramenta WebFetch, que continua acessando api.anthropic.com; para desativá-la, adicione skipWebFetchPreflight: true separadamente nas configurações. A documentação oficial não descreve essa variável como uma configuração relacionada ao controle de risco da conta.

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

O custo de ativá-la é deixar de receber atualizações automáticas; a documentação oficial recomenda providenciar outra forma de atualização. Em uma instalação npm, atualize manualmente usando @latest (veja a última linha da seção sobre npmmirror acima).

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

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

Recarregar com Alipay ou WeChat Pay e obter uma chave

Anthropic 官方的网页订阅只收信用卡或借记卡（FAQ sobre cobrança dos planos pagos do Claude，核对于 3 de outubro de 2026）。在 Kunavo 充值可以用支付宝或微信支付，步骤概要如下，完整步骤见 Guia para recarregar a API do Claude com Alipay ou WeChat Pay：

1. Crie uma conta Kunavo; pode ser com e-mail ou conta Google, e não é necessário adicionar um cartão para se registrar.
2. Em Billing, escolha o valor da recarga; o mínimo é $10 e não há mensalidade. Recargas maiores recebem bônus: 充 $100 到账 $110、充 $1000 到账 $1200、充 $5000 到账 $6250.
3. Na página de checkout da Stripe, escolha Alipay ou WeChat Pay e pague escaneando o código. Ao abrir na China continental, o valor será exibido em yuans; considere o número mostrado na página de checkout.
4. Acesse /app/keys para criar uma chave que começa com sk-kn- (ela será exibida apenas uma vez; salve-a imediatamente) e insira-a no ANTHROPIC_AUTH_TOKEN acima.

Alipay e WeChat Pay só podem ser usados para recargas manuais; a recarga automática exige um cartão bancário ou Link. A Kunavo não emite faturas de IVA chinesas; o histórico de recargas pode ser consultado na página Billing.

Quanto custa aproximadamente (cálculo ilustrativo)

O Claude Code cobra por token. A cada solicitação, o contexto da conversa é enviado novamente, e o prefixo igual ao da solicitação anterior pode ser tarifado como leitura do cache. Abaixo há apenas uma aritmética ilustrativa de tokens, não uma fatura real nem um limite de custo. Todas as premissas são listadas:

• Cada solicitação usa 40,000 tokens de entrada, dos quais 36,000 (90%) são tarifados como leitura do cache; os 4,000 restantes são tarifados como gravação no cache;
• Cada solicitação gera 1,000 tokens de saída;
• Durante um período de trabalho, são enviadas 50 solicitações desse tipo; as chamadas em segundo plano de Claude Haiku 4.5 não são contabilizadas;
• Preços da Kunavo: a leitura do cache custa 10% do preço de entrada, e a gravação no cache custa 1.25 vezes o preço de entrada (a proporção de Claude Sonnet 5; na tabela, cada modelo é calculado com sua própria proporção).

O custo real depende do tamanho do contexto, da quantidade de acertos do cache, do tamanho da saída e de você usar /clear para limpar a conversa entre tarefas. Para saber como escolher entre a assinatura e a API do Claude Code e quanto custa aproximadamente por mês, consulte Preços do Claude Code; os preços completos de cada modelo estão em Preços da API do Claude e na página de preços; para estimar com base no seu próprio uso, use a calculadora de custo de tokens do Claude (em inglês).

Tabela de erros comuns

Limitações que você precisa conhecer

• A Kunavo não emite faturas de IVA chinesas.
• Alipay e WeChat Pay só podem ser usados para recargas manuais; a recarga automática exige um cartão bancário ou Link.
• Esta é uma API cobrada por token, não uma assinatura Claude Pro/Max; ao usar uma chave de API, Remote Control e entrada de voz não ficam disponíveis. Veja como escolher entre as opções em Preços do Claude Code.
• A Kunavo não realizou testes de conectividade de rede na China continental. Você precisa verificar se os endereços de instalação do claude.ai, as fontes npm, o npmmirror e api.kunavo.com podem ser acessados na sua rede e qual é a velocidade.
• A lista de países e regiões atendidos pela Anthropic (verificada em 3 de outubro de 2026) não inclui a China continental, Hong Kong nem Macau; a documentação oficial de instalação do Claude Code lista a região como um dos requisitos do sistema.

Perguntas frequentes