Voltar aos guias
Instalação·3 de outubro de 2026·13 min de leitura

Instalar o Claude Code: comandos de instalação no Windows e macOS, configurar a chave de API sem o plano Pro/Max e pagar com cartão ou Link

Para instalar o Claude Code, basta um comando oficial. Os problemas costumam surgir depois: versão do Node.js ao instalar com npm, terminal e PATH no Windows, configuração da chave de API sem o plano Pro/Max e como pagar a partir do Vietnã sem MoMo, ZaloPay ou VNPay.

Para usar o Claude Code sem comprar um plano Pro/Max, faça três coisas: instale-o com o comando nativo oficial (uma linha para cada tipo de terminal, logo abaixo), defina ANTHROPIC_BASE_URL=https://api.kunavo.com (sem /v1) junto com ANTHROPIC_AUTH_TOKEN e as quatro variáveis de fixação de modelos e digite /status para confirmar que o Claude Code está usando a chave. O custo dos tokens é descontado do saldo pré-pago, recarregado a partir de 10 USD com cartão Visa/Mastercard ou Link; MoMo, ZaloPay e VNPay não estão disponíveis. Para instalar com npm, a máquina precisa do Node.js 22 ou posterior.

Terminal
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash
PowerShell
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
cmd.exe
:: Windows Command Prompt (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Lệnh cài và tên biến trong bài lấy từ tài liệu chính thức của Claude Code, gồm página de instalação và lista de variáveis de ambiente, đọc lại ngày 3 de outubro de 2026. Anthropic chưa có bản tiếng Việt của các trang này (đường dẫn /docs/vi/setup báo 404 cùng ngày), nên thông báo lỗi trong bài được giữ nguyên tiếng Anh để bạn tìm cho dễ. Giá và cách thanh toán của Kunavo được kiểm tra ngày 3 de outubro de 2026.

Escolha o comando de instalação conforme o terminal aberto

Todos os métodos de instalação resultam no mesmo programa claude; a diferença é quem cuida das atualizações. A documentação oficial coloca o método nativo na aba “Native Install (Recommended)”, e ele também é o único método que se atualiza automaticamente sem exigir nenhuma ação sua.

Você está emUsar o comandoAtualização
macOS, Linux ou terminal WSLinstall.sh (primeira linha acima)Automática, executada em segundo plano
Windows PowerShell, prompt no formato PS C:\Users\TenBan>irm https://claude.ai/install.ps1 | iexAutomática, executada em segundo plano
Windows CMD, prompt no formato C:\Users\TenBan> (sem PS)Linha com install.cmdAutomática, executada em segundo plano
Já está familiarizado com Homebrew ou WinGetbrew install --cask claude-code, winget install Anthropic.ClaudeCodePor padrão, não atualiza automaticamente; atualize pelo próprio gerenciador de pacotes
É necessário usar npmnpm install -g @anthropic-ai/claude-code, requer Node.js 22+Execute novamente com @latest
# Homebrew (macOS, Linux) – mặc định không tự cập nhật
brew install --cask claude-code

# WinGet (Windows) – mặc định không tự cập nhật
winget install Anthropic.ClaudeCode

A máquina precisa atender às seguintes condições (conforme a página de instalação, consultada em 3 de outubro de 2026):

  • Sistema operacional: macOS 13.0 ou posterior; Windows 10 versão 1809 ou posterior ou Windows Server 2019 ou posterior; Ubuntu 20.04+, Debian 10+ ou Alpine Linux 3.19+.
  • Mínimo de 4 GB de RAM, CPU x64 ou ARM64. O Windows de 32 bits não é compatível.
  • O shell deve ser Bash, Zsh, PowerShell ou CMD, e é necessária uma conexão com a Internet.
  • O Node.js só é necessário ao instalar via npm e deve ser da versão 22 ou posterior.

Depois de instalar, não digite claude imediatamente na janela antiga: ela ainda não recebeu o novo PATH. Abra outro terminal e execute:

claude --version   # in ra số phiên bản, kèm chữ (Claude Code)
claude doctor      # chẩn đoán cài đặt và file cấu hình, không mở phiên làm việc

Se claude --version imprimir o número da versão, a instalação foi concluída; todos os erros posteriores são de configuração. claude doctor é útil quando você não sabe onde está o problema, pois verifica tanto a instalação quanto os arquivos de configurações sem abrir uma sessão de trabalho.

Windows: cinco pontos comuns de tropeço

  1. Você colou a linha de comando errada. Se o PowerShell receber uma linha do CMD, exibirá The token '&&' is not a valid statement separator; se o CMD receber uma linha do PowerShell, exibirá 'irm' is not recognized as an internal or external command. Observe o prompt: se houver PS, use a linha irm; caso contrário, use a linha install.cmd.
  2. Você abriu o “Windows PowerShell (x86)” por engano. Essa opção do menu Iniciar é um processo de 32 bits, portanto exibirá Claude Code does not support 32-bit Windows mesmo em uma máquina de 64 bits. Escolha a opção sem (x86).
  3. Executar como Administrador é desnecessário. A documentação não exige isso, e a versão nativa é instalada na pasta do usuário: %USERPROFILE%\.local\bin\claude.exe.
  4. Digitar claude exibe “not recognized”. A pasta acima ainda não foi adicionada ao PATH. Primeiro, tente abrir um terminal novo; se o erro persistir, use o trecho de PowerShell abaixo para verificar e adicionar o caminho. No macOS/Linux, o erro equivalente é command not found: claude, e o programa fica em ~/.local/bin/claude.
  5. O npm informa npm.ps1 cannot be loaded because running scripts is disabled on this system. A política de execução do PowerShell está bloqueando o script .ps1 criado pelo npm. A documentação oferece três saídas: permitir que o usuário atual execute scripts locais com o comando Set-ExecutionPolicy abaixo, chamar npm.cmd e claude.cmd em vez da versão .ps1, ou abandonar o npm e usar o comando nativo.
PowerShell
# 1. Kiểm tra thư mục cài đặt đã có trong PATH chưa
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Không có kết quả nào? Thêm vào PATH của người dùng, rồi đóng và mở lại terminal
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Trong terminal mới
claude --version
PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Nativo ou WSL? Dự án sống trên Windows thì chạy native là đủ. Lúc đó Git for Windows là tùy chọn: có nó, Claude Code chạy lệnh qua Git Bash; không có, nó dùng PowerShell. Nếu Git đã cài mà Claude Code không thấy Git Bash, khai báo CLAUDE_CODE_GIT_BASH_PATH trong khối env của ~/.claude/settings.json, trỏ tới bash.exe (tài liệu lấy ví dụ C:\Program Files\Git\bin\bash.exe). Chọn WSL 2 khi bạn cần công cụ Linux hoặc muốn lệnh chạy trong sandbox, vì sandbox chỉ có trên WSL 2; Windows native và WSL 1 đều không có. WSL 1 chỉ là phương án khi máy không bật được WSL 2. Đã chọn WSL thì cài bằng dòng install.sh và chạy claude hoàn toàn trong terminal WSL.

Instalação via npm: requisitos e três observações

npm hợp lý khi bạn đã quản lý công cụ dòng lệnh bằng Node, hoặc khi mạng công ty chỉ cho tải gói qua registry npm. Điều kiện là Node.js 22 ou posterior; con số Node 18 trong nhiều bài cũ không còn đúng. Đáng chú ý là Node cũ hơn không làm hỏng việc cài: npm chỉ in cảnh báo EBADENGINE, vì thứ thật sự chạy là một chương trình native mà gói npm tải về, không phụ thuộc Node. Máy chưa có Node thì lấy bản 22+ ở nodejs.org.

Terminal
node -v                                    # cần v22 trở lên
npm install -g @anthropic-ai/claude-code   # không dùng sudo

# nâng cấp bằng @latest, không dùng npm update -g
npm install -g @anthropic-ai/claude-code@latest
  • Não use sudo npm install -g: a documentação alerta que esse método causa problemas de permissão e representa um risco de segurança.
  • Atualize com npm install -g @anthropic-ai/claude-code@latest; npm update -g não é o método recomendado.
  • O programa nativo vem de uma dependência opcional (o pacote @anthropic-ai/claude-code-* correspondente à sua plataforma). A opção --omit=optional, a linha optional=false no .npmrc ou --ignore-scripts fará com que ele não seja instalado, e no macOS/Linux você verá claude native binary not installed.

É necessário usar VPN? Erros ao baixar o script de instalação

Không cần. Việt Nam nằm trong lista de países com suporte da Anthropic cho cả Claude.ai lẫn API (kiểm tra ngày 3 de outubro de 2026). Chính VPN mới hay gây chuyện: theo página de solução de problemas da instalação (đọc ngày 3 de outubro de 2026), khi địa chỉ cài đặt trả về App unavailable in region, Claude Code không khả dụng ở nơi mà kết nối của bạn được nhìn thấy. Ở Việt Nam mà gặp dòng này thì tắt VPN hoặc proxy đặt ở nước khác rồi chạy lại.

Os dois erros restantes têm a mesma causa: syntax error near unexpected token '<' ou curl: (22) The requested URL returned error: 403 significa que, em vez do script, você recebeu uma página HTML ou um código de erro. Uma rede corporativa com proxy ou firewall bloqueando o download de arquivos é o primeiro suspeito. Não mude imediatamente para Homebrew, WinGet ou npm: a documentação recomenda verificar a conexão de rede primeiro, pois os métodos alternativos também baixam do mesmo servidor. Tente outra rede ou peça ao departamento de TI para liberar o acesso.

Configuração da chave de API: executar o Claude Code sem plano Pro/Max

O Claude Code se autentica de uma destas duas formas. A tabela abaixo faz uma comparação rápida; o restante do artigo segue a coluna da direita.

Login na conta ClaudeChave de API da Kunavo
RequisitoPlano Pro, Max, Team, Enterprise ou uma conta do Console. O plano gratuito do Claude.ai não inclui o Claude Code.Uma chave sk-kn-… definida em uma variável de ambiente. Sem comprar um plano e sem fazer login.
CustoTheo tháng: Pro 20 USD/tháng (17 USD/tháng nếu trả năm, tức 200 USD một lần), Max từ 100 USD/tháng, chưa gồm thuế (claude.com/pricing, đọc ngày 3 de outubro de 2026).Conforme os tokens realmente usados, descontados do saldo pré-pago a partir de 10 USD. Sem tarifa mensal, o saldo não expira e requests com erro não são cobrados.
Pagamento porMua trên web của Anthropic thì chỉ thẻ tín dụng hoặc ghi nợ (FAQ de pagamentos do Claude, đọc ngày 3 de outubro de 2026).Cartão Visa, Mastercard ou Link; Apple Pay ou Google Pay se disponíveis no dispositivo. MoMo, ZaloPay e VNPay não estão disponíveis.
O que falta—Remote Control e entrada por voz. Não há emissão de nota fiscal VAT.

Direcionar o Claude Code para um serviço diferente da Anthropic não é um truque: a documentação oficial descreve ANTHROPIC_BASE_URL como a variável usada para substituir o endpoint da API ao passar por um proxy ou gateway. A Kunavo usa o protocolo Anthropic Messages API corretamente, portanto você usa o Claude Code original, sem plugin e sem patch. São necessárias exatamente seis variáveis:

VariávelValorFinalidade e possíveis erros
ANTHROPIC_BASE_URLhttps://api.kunavo.comApenas o domínio. O Claude Code adiciona /v1/messages automaticamente; se você incluir /v1, o request se tornará /v1/v1/messages e retornará 404.
ANTHROPIC_AUTH_TOKENChave sk-kn-…Enviada no cabeçalho Authorization: Bearer, com efeito imediato e sem etapa de confirmação.
ANTHROPIC_MODELclaude-sonnet-5Modelo principal (Claude Sonnet 5). O nome precisa corresponder caractere por caractere à lista da Kunavo; nomes antigos com sufixo de data não são convertidos automaticamente.
ANTHROPIC_DEFAULT_OPUS_MODELclaude-opus-5-5Fixe o alias opus (e opusplan quando estiver no modo de planejamento) em Claude Opus 5.5, para que ele não acompanhe a versão mais recente do Opus. É necessário o Claude Code v2.1.280 ou posterior; em versões anteriores, execute claude update.
ANTHROPIC_DEFAULT_SONNET_MODELclaude-sonnet-5Por padrão, o alias sonnet aponta para o Sonnet 5.5, um modelo que a Kunavo não oferece. Sem fixação, /model sonnet, a fase de execução de opusplan e subagentes definidos com model: sonnet retornarão 404.
ANTHROPIC_DEFAULT_HAIKU_MODELclaude-haiku-4-5O alias haiku e as tarefas em segundo plano do Claude Code usam este modelo.

Onde definir as variáveis

A forma mais simples de usar isso por longo prazo é o bloco env no arquivo de configurações do usuário, ~/.claude/settings.json (Windows: %USERPROFILE%\.claude\settings.json). Esse arquivo se aplica a todos os projetos; se já tiver conteúdo, basta adicionar o bloco env:

~/.claude/settings.json
{
  "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"
  }
}

Se preferir mantê-las no shell, adicione-as a ~/.zshrc ou ~/.bashrc. No Windows, o segundo trecho abaixo (as linhas $env:) é adequado para um teste rápido, mas as variáveis desaparecem assim que a janela do PowerShell é fechada.

~/.zshrc
export ANTHROPIC_BASE_URL=https://api.kunavo.com   # chỉ tên miền, không thêm /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
PowerShell
# Chỉ có hiệu lực trong cửa sổ PowerShell này, đóng cửa sổ là mất
$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

Três coisas para saber antes de ter problemas:

  • Não coloque a chave em .claude/settings.json do projeto. Documentação de conexão com o gateway nhắc rằng file này được commit, ai clone repo cũng có.
  • O arquivo de configurações tem precedência sobre o shell. Se uma variável existir nos dois locais, será usado o valor do bloco env do arquivo de configurações. Se você alterá-la no shell e nada mudar, verifique primeiro o arquivo de configurações.
  • A primeira execução precisa da chave no nível do usuário. No modo interativo, o bloco env em .claude/settings.json ou .claude/settings.local.json do projeto só funciona depois do assistente inicial e da pergunta sobre confiar ou não na pasta. Se a chave estiver apenas ali, a tela de login ainda aparecerá na primeira inicialização.

ANTHROPIC_AUTH_TOKEN ou ANTHROPIC_API_KEY e a questão do “erro 403”

Kunavo đọc key ở cả Authorization: Bearer lẫn x-api-key, nên biến nào cũng kết nối được. Khác biệt nằm ở phía Claude Code. Theo documentação das variáveis de ambiente (đọc ngày 3 de outubro de 2026), ANTHROPIC_AUTH_TOKEN đi vào header Authorization với tiền tố Bearer và có hiệu lực ngay. ANTHROPIC_API_KEY đi vào header X-Api-Key, và ở chế độ tương tác Claude Code hỏi bạn một lần có dùng key này thay cho gói đăng ký không. Trả lời “không” thì key bị bỏ qua mà không hỏi lại; muốn bật lại thì vào /config, mục Usar chave de API personalizada. Bài này chọn ANTHROPIC_AUTH_TOKEN chỉ để bỏ được bước hỏi đó.

Vài hướng dẫn tiếng Việt viết rằng ANTHROPIC_API_KEY khiến Claude Code phớt lờ ANTHROPIC_BASE_URL, gọi thẳng api.anthropic.com và nhận 403. Cả tài liệu biến môi trường lẫn documentação de conexão do gateway (đọc ngày 3 de outubro de 2026) đều không nói vậy: hai biến là hai cách đưa key tới cùng một gateway trong ANTHROPIC_BASE_URL. Nếu bạn thật sự gặp 403 sau khi đổi biến, hãy kiểm tra lại base URL và key thay vì đổi qua đổi lại tên biến.

Por que fixar modelos e quanto custa cada modelo

Alias của Claude Code không đứng yên. Theo documentação de configuração do modelo (đọc ngày 3 de outubro de 2026), với người dùng API, mô hình mặc định và alias opus đang trỏ tới Opus 5.5, alias sonnet trỏ tới Sonnet 5.5; tài liệu cũng nói alias “được cập nhật theo thời gian” và khuyên dùng tên đầy đủ hoặc các biến ANTHROPIC_DEFAULT_*_MODEL khi cần cố định. Tính đến ngày 3 de outubro de 2026, Kunavo có Opus 5.5 nhưng không có Sonnet 5.5. Hệ quả nếu bỏ qua bước ghim: phiên mặc định chạy Opus 5.5, đắt hơn Claude Sonnet 5; /model sonnet, giai đoạn thực thi của opusplan và subagent đặt model: sonnet trả về 404; và lần tới alias opus nhảy sang bản Opus mới, bản đó chưa chắc đã có trên Kunavo. Vì vậy đoạn cấu hình ở trên ghim alias sonnet vào claude-sonnet-5 bằng ANTHROPIC_DEFAULT_SONNET_MODEL, và ghim alias opus vào Opus 5.5 (claude-opus-5-5). Opus 5.5 cần Claude Code v2.1.280 trở lên; bản cũ hơn thì chạy claude update.

Preços na Kunavo, por milhão de tokens (entrada / saída): Claude Sonnet 5 1,40 USD / 7,00 USD (preços da Anthropic: 2,00 USD / 10,00 USD); Claude Opus 5.5 2,80 USD / 14,00 USD; Claude Haiku 4.5 0,70 USD / 3,50 USD.

Verificação com /status

Quando ANTHROPIC_AUTH_TOKEN tiver sido lida, o comando claude entra diretamente na sessão de trabalho, sem tela de login (conforme a documentação de conexão com o gateway, consultada em 3 de outubro de 2026); na primeira vez ainda há algumas etapas de configuração, como a pergunta sobre confiar na pasta. Se a tela de login aparecer, a chave não chegou ao destino. Na sessão, digite /status e procure:

  • Anthropic base URL: https://api.kunavo.com. Essa linha só aparece quando há um endereço de gateway; sua ausência significa que ANTHROPIC_BASE_URL não entrou na sessão.
  • Auth token: ANTHROPIC_AUTH_TOKEN. Se nesse local aparecer Login method junto com uma conta do claude.ai, a sessão ainda está usando o login salvo.

Para confirmar a chave e o endereço antes de abrir o Claude Code, envie um request de teste solicitando exatamente 1 token de saída (isso consome uma quantia muito pequena do saldo). O comando lê a variável do shell atual; portanto, se a chave estiver apenas no arquivo de configurações, execute export primeiro neste terminal. Um resultado que começa com {"id":"msg_ indica sucesso; 401 significa que a chave foi rejeitada.

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

A versão do PowerShell para o mesmo teste; em caso de sucesso, o campo id do resultado começa com msg_:

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

O que se perde ao usar uma chave de API

  • Remote Control e entrada por voz exigem uma identidade do claude.ai, portanto não funcionam quando ANTHROPIC_AUTH_TOKEN está ativo. O Remote Control também é desativado quando ANTHROPIC_BASE_URL aponta para um servidor diferente de api.anthropic.com.
  • /fast informa Fast mode has been disabled by your organization: conforme a documentação de conexão com o gateway, a verificação do modo rápido exige login no claude.ai ou uma chave de API da Anthropic; portanto, com um bearer token, o Claude Code considera o recurso desativado e não consulta o servidor.
  • MCP tool search fica desativado por padrão quando a URL base não pertence à Anthropic.
  • Métricas em /context là ước tính: Kunavo không có endpoint /v1/messages/count_tokens, và theo documentação do protocolo do gateway (đọc ngày 3 de outubro de 2026), khi thiếu endpoint này Claude Code đếm token dựa trên số ký tự.

Os detalhes da integração estão na documentação de integração do Claude Code (em inglês); o artigo correspondente em inglês é Install Claude Code.

Adicionar saldo do Vietnã: cartão ou Link, sem carteiras digitais locais

Para deixar claro: A Kunavo não aceita MoMo, ZaloPay, VNPay nem transferência bancária. Cartões ATM locais que funcionam apenas na rede Napas também não podem ser usados, pois não são cartões Visa ou Mastercard. A página de pagamento Stripe da Kunavo oferece as seguintes opções para compradores no Vietnã:

  • Cartões Visa ou Mastercard, tanto de crédito quanto de débito internacional.
  • Link, ví của Stripe, lưu phương thức thanh toán để lần sau trả nhanh hơn (documentação do Link, đọc ngày 3 de outubro de 2026).
  • Apple Pay ou Google Pay, chỉ xuất hiện trên thiết bị và trình duyệt đã thiết lập ví, vì chúng trả bằng thẻ có trong ví. Apple Pay có mặt ở Việt Nam từ 08/08/2023 và dùng được khi mua hàng trực tuyến (Apple Newsroom Vietnã, đọc ngày 3 de outubro de 2026).

Phía Anthropic cũng vậy: gói Claude mua trên web chỉ nhận thẻ tín dụng hoặc ghi nợ (FAQ de pagamentos do Claude, đọc ngày 3 de outubro de 2026), nên ví điện tử Việt Nam không trả trực tiếp được ở đó; gói mua trong ứng dụng iOS hay Android thì đi theo phương thức của App Store hoặc Google Play. Khác ở chỗ, tiền nạp vào Kunavo thành số dư API, và Claude Code trừ dần theo token sau khi bạn cấu hình key như trên.

Pagar em VND ou USD

Kunavo niêm yết giá bằng USD. Vì Việt Nam nằm trong các thị trường của Stripe Adaptive Pricing (đọc ngày 3 de outubro de 2026), trang thanh toán có thể hiện số tiền đã quy đổi sang VND, và con số chính xác luôn hiện ra trước khi bạn bấm xác nhận. Tỷ giá Stripe đưa ra đã cộng phí chuyển đổi 2–4%, người mua chịu. Chọn trả bằng USD thì không có khoản đó, nhưng ngân hàng phát hành thẻ có thể áp tỷ giá và phí của họ.

Trả bằng VND cũng chưa chắc rẻ hơn: một số ngân hàng thu phí khi thẻ thanh toán bằng VND cho đơn vị bán hàng đăng ký ở nước ngoài. Chẳng hạn Techcombank thu “phí giao dịch nội tệ ở nước ngoài” 1,1% số tiền giao dịch (đã gồm VAT) với thẻ ghi nợ Visa, áp dụng từ 13/08/2023 (FAQ do Techcombank, đọc ngày 3 de outubro de 2026). Đây chỉ là ví dụ của một ngân hàng, và Kunavo chưa xác minh được ngân hàng có xếp giao dịch của mình vào loại này hay không; xem biểu phí thẻ của bạn rồi hãy chọn VND hay USD.

Cartões geralmente são recusados porque o pagamento online ou internacional ainda não foi ativado no aplicativo do banco. Ative-o e tente novamente, ou mude para Link ou Apple Pay/Google Pay usando um cartão compatível com essa carteira.

Do cadastro à chave

  1. Cadastre-se na Kunavo com e-mail ou uma conta Google; essa etapa não solicita um cartão.
  2. Abra Billing e escolha o valor da recarga (mínimo de 10 USD). Valores maiores recebem um adicional: nạp 100 USD được 110 USD vào số dư; nạp 1.000 USD được 1.200 USD vào số dư; nạp 5.000 USD được 6.250 USD vào số dư.
  3. Na página da Stripe, escolha um cartão, Link ou uma carteira disponível no dispositivo, revise o valor e confirme.
  4. Acesse API Keys e crie uma chave sk-kn-…. A chave é exibida apenas uma vez, portanto copie-a imediatamente para ANTHROPIC_AUTH_TOKEN.

Para recarregar automaticamente quando o saldo estiver baixo, é necessário usar um cartão salvo ou Link. O saldo não expira e requests com erro não são cobrados. A Kunavo não emite nota fiscal VAT, nem mesmo nota eletrônica conforme as regras do Vietnã; consulte o histórico de recargas em Billing. Esse saldo só pode ser usado para a API da Kunavo; não pode pagar Claude Pro, Claude Max nem ChatGPT Plus.

Quanto custa aproximadamente uma sessão de programação?

A cada execução, o Claude Code envia novamente todo o contexto da conversa, portanto o custo depende muito do cache: o contexto repetido é cobrado pelo preço de leitura do cache, muito mais barato. A tabela a seguir é um cálculo teórico com as premissas explícitas; não representa uma medição real nem um limite máximo:

  • por solicitação, 40.000 tokens de entrada: 36.000 tokens (90%) lidos do cache, 4.000 tokens gravados no cache;
  • cada request com 1.000 tokens de saída;
  • uma sessão com 50 requests, sem contar as execuções em segundo plano de Claude Haiku 4.5;
  • com Claude Sonnet 5 na Kunavo, a leitura do cache custa 10% do preço de entrada e a gravação do cache custa 1,25 vezes o preço de entrada; cada modelo da tabela usa sua própria proporção.
ModeloUm request50 requests50 requests, sem atingir o cache nenhuma vez
Claude Sonnet 50,019 USD0,95 USD3,15 USD
Claude Opus 5.50,033 USD1,65 USD6,30 USD

A última coluna mostra a importância do cache. Contexto longo, respostas longas ou esquecer de usar /clear entre tarefas diferentes aumentam o valor. Compare assinatura e API e faça uma estimativa mensal no artigo Quanto custa o Claude Code; consulte os preços de cada modelo na tabela de preços da API do Claude ou na página de preços; para inserir seus próprios dados, use a calculadora de custos de tokens do Claude (em inglês).

Solucionar problemas pela mensagem

QuandoO que apareceSolução
InstalaçãoThe token '&&' is not a valid statement separatorVocê está no PowerShell e colou a linha do CMD. Use irm … | iex.
Instalação'irm' is not recognized as an internal or external commandVocê está no CMD e colou a linha do PowerShell. Use a linha install.cmd.
Instalaçãosyntax error near unexpected token '<', 403, App unavailable in regionVocê recebeu uma página HTML em vez do script. Desative a VPN/proxy em outro país e tente outra rede antes de mudar o método de instalação (os outros métodos baixam do mesmo servidor).
InstalaçãoClaude Code does not support 32-bit WindowsO PowerShell (x86) está aberto. Abra o “Windows PowerShell” comum.
Instalação (npm)Aviso EBADENGINENode.js abaixo da versão 22. A instalação termina, mas é recomendável atualizar o Node.
Instalação (npm)claude native binary not installedDependência opcional ausente devido a --omit=optional, optional=false ou --ignore-scripts. Remova essa configuração e instale novamente.
Instalação (npm)npm.ps1 cannot be loadedA política de execução bloqueia o script. Execute Set-ExecutionPolicy acima, use npm.cmd ou mude para o comando nativo.
Após a instalaçãocommand not found: claude, 'claude' is not recognizedA pasta de instalação ainda não está em PATH. Abra um terminal novo; no Windows, execute também o trecho do PowerShell PATH.
ConfiguraçãoA tela de login continua aparecendoA chave não foi lida. Defina-a no shell ou em ~/.claude/settings.json do usuário, não apenas na configuração do projeto; abra um terminal novo.
Configuração401A chave foi recusada: cópia incompleta, espaços extras, foi excluída em /app/keys ou está na variável errada.
Configuração404O Base URL contém /v1 a mais ou o modelo não está disponível no Kunavo (geralmente o alias sonnet ainda não fixado, apontando para o Sonnet 5.5).
Adicionar saldoCartão recusadoAtive os pagamentos online e internacionais no aplicativo do banco; cartões somente com Napas não funcionam. Como alternativa, tente Link, Apple Pay ou Google Pay.

Antes de adicionar saldo

  • Aceitamos apenas cartões Visa/Mastercard, Link e carteiras vinculadas ao cartão; MoMo, ZaloPay, VNPay e transferências bancárias não são aceitos.
  • A recarga automática funciona apenas com cartões salvos ou Link. O Kunavo não emite nota fiscal.
  • Esta é uma API cobrada por token, não um plano Claude Pro/Max: não há Remote Control nem entrada por voz, /fast indica que está desativado e a busca de ferramentas MCP fica desativada por padrão.
  • Em 3 de outubro de 2026, o Kunavo não oferece o Sonnet 5.5; por isso, o alias sonnet não fixado retorna 404.
  • A documentação do Claude Code e a documentação de integração do Kunavo estão disponíveis somente em inglês no momento.

Perguntas frequentes

O Claude Code é gratuito? O que significa “Claude Code sem necessidade de plano”?

Baixar e instalar o Claude Code não custa nada, mas para que ele responda é necessário uma destas opções: fazer login com um plano pago do Claude (Pro, Max, Team, Enterprise) ou uma conta do Console, ou usar uma chave de API. O plano gratuito do Claude.ai não inclui o Claude Code. “Sem necessidade de plano” é a segunda opção: definir ANTHROPIC_BASE_URL=https://api.kunavo.com e ANTHROPIC_AUTH_TOKEN; o Claude Code ignora o login e desconta do saldo pré-pago da Kunavo conforme os tokens realmente usados, com mínimo de 10 USD e sem mensalidade.

Qual é o comando para instalar o Claude Code no Windows? É necessário instalar o WSL ou executar como Administrador?

Abra o PowerShell (o prompt começa com PS) e execute irm https://claude.ai/install.ps1 | iex; se estiver no CMD, use curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd. Não são necessários privilégios de Administrador, WSL nem Git. Se o Git for Windows estiver instalado, o Claude Code executará comandos pelo Git Bash; caso contrário, pelo PowerShell. O WSL 2 só vale a pena quando você precisa de ferramentas Linux ou quer executar comandos em um sandbox. Lembre-se de abrir o “Windows PowerShell”, não a opção com (x86), pois o Claude Code não funciona no Windows de 32 bits.

Qual versão do Node.js é necessária para instalar o Claude Code com npm?

Node.js 22 ou posterior, conforme a documentação oficial de instalação consultada em 3 de outubro de 2026. Muitos artigos antigos ainda informam Node 18, mas esse número está desatualizado. Uma versão antiga do Node apenas faz o npm exibir o aviso EBADENGINE; a instalação ainda é concluída, porque o pacote npm na prática baixa um programa nativo que não precisa do Node. O comando de instalação é npm install -g @anthropic-ai/claude-code (sem sudo); para atualizar, execute-o novamente com @latest, em vez de usar npm update -g. Se não houver um motivo específico para usar npm, o comando nativo é mais simples.

Onde inserir a chave de API do Claude Code? O ANTHROPIC_BASE_URL deve incluir /v1?

O local mais persistente é o bloco env no arquivo ~/.claude/settings.json do usuário (Windows: %USERPROFILE%\.claude\settings.json), aplicado a todos os projetos; também é possível fazer export em ~/.zshrc, ~/.bashrc ou $PROFILE do PowerShell. A URL base é apenas https://api.kunavo.com, sem /v1, porque o Claude Code adiciona /v1/messages automaticamente; o /v1 extra se tornaria /v1/v1/messages e resultaria em 404. Não coloque a chave em .claude/settings.json do projeto: esse arquivo fica no repositório e acompanha cada clone.

Há artigos dizendo que usar ANTHROPIC_API_KEY resulta em 403. Isso é verdade?

Não, de acordo com a documentação oficial. Tanto ANTHROPIC_API_KEY quanto ANTHROPIC_AUTH_TOKEN são enviados ao endereço definido em ANTHROPIC_BASE_URL; a diferença está no cabeçalho (X-Api-Key versus Authorization: Bearer) e no fato de que ANTHROPIC_API_KEY precisa ser aceita por você uma vez no modo interativo. A Kunavo lê a chave em ambos os cabeçalhos. Este artigo recomenda ANTHROPIC_AUTH_TOKEN apenas porque ele funciona imediatamente. Se você clicar em recusar nessa pergunta, a chave será ignorada sem nova pergunta; acesse /config, a opção Use custom API key, para ativá-la novamente.

Qual modelo o Claude Code executa quando ANTHROPIC_MODEL não é definido?

Ele usa um alias, e os aliases mudam gradualmente com o tempo. A documentação de configuração de modelos (consultada em 3 de outubro de 2026) informa que, para usuários da API, o padrão e o alias opus são atualmente o Opus 5.5, enquanto o alias sonnet é o Sonnet 5.5. A Kunavo oferece o Opus 5.5, mas não o Sonnet 5.5; portanto, uma sessão não fixada executará o Opus 5.5 com preço mais alto Claude Sonnet 5, enquanto /model sonnet, a fase de execução do opusplan e subagentes com model: sonnet retornarão 404. Fixe ANTHROPIC_MODEL=claude-sonnet-5, ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5, ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5 e ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5 para saber com certeza qual modelo está sendo cobrado a cada execução. Fixar o alias opus no Opus 5.5 requer o Claude Code v2.1.280 ou posterior; em versões anteriores, execute claude update.

O que indica o /status para confirmar que estou usando uma chave de API?

Duas linhas: “Anthropic base URL” é https://api.kunavo.com, e “Auth token” informa ANTHROPIC_AUTH_TOKEN. Se, em vez disso, aparecer “Login method” com uma conta do claude.ai, a sessão ainda está usando o login antigo; saia, abra um terminal novo e verifique onde a variável foi definida. Você pode testar a chave antes mesmo de abrir o Claude Code com um comando curl enviado a /v1/messages com max_tokens igual a 1: uma resposta JSON que começa com {"id":"msg_ indica sucesso; 401 significa que a chave foi rejeitada.

No Vietnã, é necessário usar VPN para instalar ou usar o Claude Code?

Não. O Vietnã está na lista de países da Anthropic com suporte tanto ao Claude.ai quanto à API (verificado em 3 de outubro de 2026). Por outro lado, se a VPN direcionar a conexão para um país sem suporte, o endereço de instalação poderá retornar a página “App unavailable in region” em vez do script. Se isso ocorrer enquanto você estiver no Vietnã, desative a VPN ou o proxy e execute novamente o comando de instalação.

É possível adicionar saldo com MoMo, ZaloPay ou VNPay? Há emissão de nota fiscal VAT?

Nenhuma das duas opções está disponível. A página de pagamento Stripe da Kunavo permite que compradores no Vietnã escolham Visa, Mastercard ou Link, e Apple Pay ou Google Pay se já estiverem configurados no dispositivo; MoMo, ZaloPay, VNPay e transferência bancária não estão disponíveis. O valor pode aparecer em VND; nesse caso, a taxa de câmbio da Stripe já inclui a tarifa de conversão de 2–4% paga pelo comprador. Ao escolher pagar em USD, essa tarifa não existe, mas seu banco poderá cobrar sua própria taxa de câmbio e tarifa. O depósito mínimo é 10 USD, o saldo não expira e a recarga automática funciona apenas com cartão salvo ou Link. A Kunavo não emite notas fiscais VAT, nem mesmo notas eletrônicas.