A instalação do Claude Code em si é um único comando, mas os bloqueios reais vêm depois. A maioria dos textos sobre instalação termina em 「Instalação concluída」, mas, na Coreia, ainda há dois obstáculos até a execução — permissões de instalação global e login e pagamento. Este texto organiza as três etapas na ordem, incluindo a solução para cada bloqueio.
Etapa 1 — instalação (um único comando)
O único pré-requisito é Node.js 18 ou superior. macOS, Windows (WSL) e Linux usam o mesmo comando.
# Node.js 18 이상이 필요합니다. 먼저 확인하세요.
node --version
# 설치
npm install -g @anthropic-ai/claude-code
# 확인 — 버전이 출력되면 설치 자체는 끝난 것입니다
claude --versionclaude --versionSe essa versão for exibida, a instalação terminou. Se parar aqui, você se enquadra em uma das duas seções abaixo.
Etapa 2 — erros de permissão e caminho
São os dois erros mais comuns durante a instalação.
| Sintoma | Causa e solução |
|---|---|
EACCES Erro de permissão | Sem permissão de gravação no diretório global do npm — mova o caminho global para o diretório pessoal |
command not found: claude | O bin global do npm não está no PATH — adicione-o ao PATH e abra um novo terminal |
Não recomendamos adicionar EACCES a sudo. A instalação funciona no momento, mas o mesmo problema se repete a cada atualização, e o proprietário do diretório global se torna root, complicando ainda mais tudo. É mais simples mover o caminho para o diretório pessoal.
# npm 전역 설치에서 EACCES가 나면 sudo를 붙이지 말고
# 전역 경로를 홈 디렉터리로 옮기는 편이 안전합니다.
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
# 셸 설정에 추가한 뒤 새 터미널을 엽니다
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrcNo Windows, instale dentro do WSL. Os arquivos do projeto também devem ficar no sistema de arquivos do WSL para que a observação de arquivos e o tratamento de caminhos funcionem corretamente.
Etapa 3 — login e pagamento (onde o bloqueio realmente ocorre na Coreia)
Depois que a instalação terminar e você executar claude, será solicitado o login. É aqui que a maioria das pessoas na Coreia fica bloqueada, e a causa não tem relação com a instalação.
- Cartão com pagamentos internacionais bloqueados — falha no pagamento da assinatura. Permitir pagamentos internacionais no aplicativo ou site da administradora geralmente resolve.
- KakaoPay e Toss — não são aceitos nos pagamentos web de claude.ai (estão disponíveis apenas como métodos de pagamento da loja para assinaturas móveis). Tentar usar um método de pagamento local simples bloqueia você nesta etapa.
- Quando você não tem um cartão habilitado para pagamentos internacionais — não é possível usar o fluxo de assinatura na web. A autenticação por chave abaixo adiciona saldo ao Kunavo; quando o checkout exibe won sul-coreano, KakaoPay, Naver Pay, PAYCO, Samsung Pay e cartões nacionais (sem pagamentos internacionais habilitados) são oferecidos como métodos de pagamento, permitindo adicionar saldo sem um cartão para pagamentos internacionais (Toss não é compatível).
Organizamos os métodos de pagamento aceitos e não aceitos em Como pagar pelo Claude.
Quando o pagamento da assinatura é bloqueado — execute com uma chave sem reinstalar
Além do login por assinatura, o Claude Code aceita autenticação por chave de API. Com as duas variáveis de ambiente abaixo definidas, ele é executado sem passar pela tela de login; removê-las restaura o comportamento original. Não é necessário reinstalar.
# 구독 결제가 막혔을 때 설치한 클로드 코드를 그대로 쓰는 방법.
# 이 두 줄이 있으면 로그인 대신 키로 인증하고, 지우면 원래대로 돌아갑니다.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
# 클로드 코드의 기본 모델과 opus·sonnet 별칭은 Anthropic의 최신 모델을 따라가므로,
# Kunavo가 제공하는 모델로 고정해 404를 막습니다. sonnet 별칭은 Kunavo가 제공하지
# 않는 Sonnet 5.5를 요청하므로, 고정하지 않으면 /model sonnet, opusplan의 실행 단계,
# sonnet 서브에이전트가 404로 실패합니다. opus는 Opus 5.5로 고정하며,
# 클로드 코드 v2.1.280 이상이 필요합니다(이전 버전은 claude update).
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
claudeNesse caminho, você paga apenas pelos tokens realmente usados em vez de uma mensalidade, portanto não há cobrança nos meses sem trabalho. O procedimento para obter uma chave está em Como obter uma chave de API do Claude; para saber qual opção é mais barata, assinatura ou cobrança por uso, consulte Preços do Claude Code.
Primeira execução após a instalação — 3 minutos para verificar
Depois de executar, abra claude no diretório do projeto e execute /init uma vez. Ele lê o repositório e cria CLAUDE.md, que será lido automaticamente em todas as sessões seguintes. A operação a partir daqui — escrever regras, definir permissões e criar comandos personalizados — continua em Como usar o Claude Code.
Os erros que aparecem após a execução (401, 429 e 529) têm causas completamente diferentes das da etapa de instalação. A distinção está detalhada em Guia de erros do Claude Code.
Perguntas frequentes
Como instalar o Claude Code?
É uma única linha para instalação global pelo npm. Execute npm install -g @anthropic-ai/claude-code e confirme com claude --version. O único pré-requisito é Node.js 18 ou superior, e o mesmo comando funciona no macOS, Windows e Linux. No Windows, é menos problemático instalar dentro do WSL.
A instalação foi concluída, mas não consigo executar. O que devo verificar?
Primeiro, verifique se claude --version exibe uma saída. Se exibir, a instalação terminou e o problema restante é a autenticação. Se o erro disser que o comando não foi encontrado, o caminho global do npm não está no PATH; adicione ao PATH o diretório bin do caminho retornado por npm config get prefix e abra um novo terminal.
Recebo um erro de permissão EACCES durante a instalação.
Isso significa que você não tem permissão para gravar no diretório global do npm. Instalar com sudo funciona no momento, mas não é recomendado porque os problemas de permissão voltarão. Uma opção segura é mover o caminho global para o diretório pessoal com npm config set prefix ~/.npm-global e adicioná-lo ao PATH.
O pagamento falha durante o login após a instalação.
Este é o ponto que bloqueia com mais frequência na Coreia. Cartões com pagamentos internacionais bloqueados falham nas cobranças de assinatura; permitir pagamentos internacionais no aplicativo ou no site da administradora do cartão resolve o problema na maioria dos casos. KakaoPay e Toss não são compatíveis com pagamentos na web do claude.ai; eles aparecem apenas na lista de métodos de pagamento da Coreia da App Store e do Google Play para assinaturas em aplicativos móveis. Se for necessário contornar o pagamento, há a opção de autenticar com uma chave de API em vez de assinar. Nesse fluxo, a recarga do saldo Kunavo oferece KakaoPay, Naver Pay, PAYCO, Samsung Pay e cartões nacionais como métodos de pagamento quando o checkout exibe won sul-coreano (Toss não é compatível).
Posso usar o Claude Code sem assinatura?
Sim. Além do login por assinatura, o Claude Code aceita autenticação por chave de API; defina as duas variáveis de ambiente ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN para executá-lo sem login. Nesse caso, você paga apenas pelos tokens usados em vez de uma mensalidade e não há cobrança nos meses em que não usar.
Como instalar no Windows?
Recomendamos instalar dentro do WSL (Windows Subsystem for Linux). Instale o Node.js 18 ou superior no terminal do WSL e execute o mesmo comando npm. O projeto em que você trabalha também deve ficar no sistema de arquivos do WSL para que a observação de arquivos e o tratamento de caminhos funcionem corretamente.