Configuração de API: Login por assinatura ou API key, como escolher e alternar

📚 Navegação da série: Artigo anterior 03 · Como funciona desmontou o loop de agente — como o Claude Code "pensa → age → observa". Este artigo resolve o pré-requisito para fazê-lo rodar: com qual identidade conectar ao modelo. O próximo artigo abordará a integração de modelos de terceiros / nacionais.

Em junho de 2026, a documentação oficial do Claude Code lista 6 formas de autenticação, desde login por assinatura até credenciais de provedores de nuvem, com prioridade em camadas.

Aqui existe uma armadilha muito comum na qual eu mesmo já caí. Para facilitar as coisas na época, eu havia exportado um ANTHROPIC_API_KEY no meu .zshrc há muito tempo, e mais tarde comprei a assinatura Max, fazendo o login com /login perfeitamente bem, até que um dia verifiquei a fatura no Console e descobri que a API estava cobrando continuamente — embora eu achasse que estava usando a cota da assinatura o tempo todo. Demorei muito para entender: desde que haja uma API key no ambiente, sua prioridade supera a da assinatura.

Em outras palavras, "estar logado" não significa "estar usando a identidade correta". Este artigo vai esclarecer essa questão.

Ao terminar de ler este artigo, você obterá:

• Uma tabela de comparação de cenários de uso entre as duas rotas: login por assinatura vs API key, para saber qual escolher
• Três formas práticas de "onde configurar e como alterar" (login por linha de comando / variáveis de ambiente / settings.json), e as diferenças entre Mac / Windows / Linux
• Um conjunto de comandos de auto-verificação: usar /status para confirmar "qual identidade e modelo estou realmente usando agora", e nunca mais ser cobrado acidentalmente

---

01 Duas identidades: Login por assinatura vs API key

A conclusão primeiro: Para uso pessoal, escolha o login por assinatura; apenas quando precisar integrar em scripts / CI / faturamento por uso da equipe, use a API key.

Para conectar o Claude Code ao modelo, a essência é responder a uma pergunta: "Com base em que posso usá-lo?" Isso é a autenticação (authentication) — você tem que provar quem é você e de quem é a cota que está usando. Os métodos oficialmente suportados são vários, mas para iniciantes, basta entender as duas rotas principais.

Analogia: Entrar em uma academia. O login por assinatura é como comprar um passe mensal — reconhecimento facial na entrada, treino livre dentro do mês, sem cobrança por visita; a API key é como um ingresso comprado por entrada — deduz um bilhete a cada entrada, pagando pelo uso. O passe mensal é adequado para quem vai todo dia, o ingresso por entrada é adequado para o cenário de ir ocasionalmente ou ajudar a trazer amigos (scripts, automação).

A diferença entre as duas rotas em uma tabela:

Dimensão	Login por assinatura (Conta Claude.ai)	API key (Console / Variável de ambiente)
Como conectar	Executar claude no terminal, login no navegador	Configurar variável de ambiente ANTHROPIC_API_KEY
Como é cobrado	Assinatura mensal (Pro / Max / Team)	Por uso de token, deduzido do saldo do Console
Cota	Há um limite de uso, deve esperar recarregar quando atingir o teto	Paga o quanto usa, sem limite máximo fixo
Para quem é adequado	Desenvolvimento interativo diário pessoal	Scripts / CI / Faturamento por uso da equipe
De onde vêm as credenciais	Autorização no navegador via /login	Criar chave no Claude Console
Pode ser sem navegador	Por padrão precisa de navegador (CI usa setup-token)	Sim, puramente via variável de ambiente

Vamos subdividir o lado da assinatura, porque usaremos isso na escolha do modelo depois:

• Claude Pro / Max: Assinatura pessoal, login com conta Claude.ai. O Pro é mais leve, o Max tem cota maior e pode usar os modelos mais fortes.
• Claude for Teams / Enterprise: Plano de equipe, o administrador convida você, faturamento unificado. O Enterprise também pode configurar SSO e políticas gerenciadas.

Projetos pessoais devem sempre seguir pelo login de assinatura Max, é tranquilo e você não precisa vigiar o saldo; apenas ao colocar tarefas de automação no GitHub Actions, é que você configura uma API key separadamente (os detalhes específicos para CI serão abordados no artigo 44). Para o desenvolvimento diário, não toque na API key, é pura ansiedade de cobrança.

💡 Resumo em uma frase: Assinatura = Passe mensal (diário pessoal), API key = Ingresso (scripts/equipe por uso), decida que tipo de pessoa você é primeiro e depois configure.

---

02 Login por assinatura: O caminho mais tranquilo

Se você é um usuário pessoal e comprou o Pro ou o Max, a configuração é basicamente nenhuma — basta rodar e fazer o login.

O processo tem apenas um passo. Após instalar o Claude Code (para a instalação veja o artigo 02), digite no terminal:

claude

Na primeira inicialização, o Claude Code automaticamente abrirá o navegador para permitir o login na sua conta Claude.ai. Após o login, o navegador retornará ao terminal e estará feito.

Algumas situações reais que você encontrará, já adianto:

• O navegador não abriu automaticamente? Na interface do Claude Code, pressione c, ele copiará o link de login para a área de transferência, e você mesmo cola no navegador para abrir.
• Após o login no navegador, foi fornecido um "código de login" e não voltou? Cole esse código de volta no terminal no prompt Paste code here if prompted. Esta situação é comum no WSL2, sessões SSH remotas, contêineres — porque o navegador não consegue conectar à porta de callback da máquina local.
• Quer mudar de conta / fazer logout? No Claude Code digite /logout, na próxima inicialização faça o login novamente.

Onde as credenciais de login estão armazenadas? Diferentes plataformas fazem diferente, sabendo disso, você não ficará perdido ao investigar problemas:

Plataforma	Local de armazenamento de credenciais
macOS	Keychain do sistema criptografado (Keychain)
Linux	~/.claude/.credentials.json (permissões 0600)
Windows	%USERPROFILE%\.claude\.credentials.json (herda permissões do diretório do usuário)

Tudo isso é gerenciado automaticamente pelo Claude Code através do /login / /logout, você não precisa tocar manualmente. Quando eu mesmo investigava um problema de login no Mac, segui a abordagem do Linux e procurei o arquivo ~/.claude/.credentials.json, mas não o encontrava de jeito nenhum e cheguei a suspeitar que não tinha feito o login com sucesso — o motivo é este: o macOS simplesmente não o salva como arquivo, mas o coloca no Keychain.

💡 Resumo em uma frase: Para usuários de assinatura "rode claude → faça o login no navegador" e pronto, o Claude Code armazena as credenciais automaticamente, não procure manualmente.

---

03 API key: O caminho para scripts e equipes

O escopo de aplicação do caminho da API key na verdade é muito restrito — se você não faz automação e não está faturando por uso em uma equipe, basicamente não a utilizará. Mas já que queremos explicar claramente "como alternar", precisamos primeiro saber como ela se parece.

Primeiro passo, obtenha a chave. Vá para o Claude Console e crie uma API key (este é o console oficial de desenvolvedores da Anthropic, cobrado pelo uso de token, e é uma conta diferente da assinatura do Claude.ai).

Segundo passo, configure como variável de ambiente. Os comandos diferem por plataforma, vamos separar:

macOS / Linux:

export ANTHROPIC_API_KEY=sk-ant-sua-chave

Windows (PowerShell, escreve permanentemente na variável de ambiente do usuário):

[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-sua-chave", [EnvironmentVariableTarget]::User)

⚠️ Chave é dinheiro, não a deixe solta. Não coloque a chave no código, não faça commit no Git e não a cole em nenhum arquivo que possa ser compartilhado. Usar export temporariamente no terminal atual é o mais seguro; ela sumirá ao ser fechado. Para persistência, use a variável de ambiente do sistema, não faça hardcode no projeto.

Terceiro passo, verificação na inicialização. Após configurá-la, rode o claude; no modo interativo, o sistema solicitará que você aprove esta chave uma vez (escolha entre aprovar / recusar, a escolha será lembrada). Depois de aprovar, usará ela.

Existe um comportamento crucial explicitamente declarado pela equipe oficial, que é a raiz daquela armadilha mencionada no início:

Se você possui uma assinatura do Claude ativa, mas configurou a variável ANTHROPIC_API_KEY no ambiente ao mesmo tempo, então a API key terá prioridade após a aprovação. Se essa chave pertencer a uma organização desativada ou expirada, isso resultará diretamente em falha de verificação.

Em outras palavras, a API key "sobrescreverá" sua assinatura. É por isso que surge o problema de alternância discutido na próxima seção.

💡 Resumo em uma frase: A API key segue os três passos obter a chave no Console → configurar a variável de ambiente → aprovar na inicialização; lembre-se que, uma vez que exista, ela tem prioridade sobre a assinatura, o que é a raiz de todos os problemas de "alternância" que vêm a seguir.

---

04 Como alternar: A prioridade é a verdade

Conclusão central: Qual identidade você "acha que está usando" não importa; a ordem de prioridade do Claude Code é que manda. Querer alternar é, em essência, ajustar essa prioridade.

Analogia: Ordem de conexão de uma tomada. Na sua parede há várias tomadas (assinatura, API key, credenciais de nuvem...), e de onde o aparelho realmente tira energia não depende de qual você quer usar em mente, mas sim de qual está efetivamente conectada e qual posição está mais à frente. Para trocar a fonte de energia, você deve desligar a que está mais à frente.

A prioridade de autenticação dada pela documentação oficial, de cima para baixo em 6 camadas (as mais altas sobrescrevem as mais baixas):

Prioridade	Fonte de credencial	Cenário típico
1 (Mais alta)	Provedor de nuvem (Bedrock / Vertex / Foundry)	Empresa usando provedor de nuvem
2	Variável de ambiente ANTHROPIC_AUTH_TOKEN	Usando gateway LLM / proxy
3	Variável de ambiente ANTHROPIC_API_KEY	Conectando diretamente à API Anthropic
4	Saída do script apiKeyHelper	Credenciais dinâmicas / rotativas
5	CLAUDE_CODE_OAUTH_TOKEN	Token de longo prazo usado em CI
6 (Mais baixa)	Credencial de assinatura do /login	Assinatura pessoal segue esta camada por padrão

Esta imagem "ergue" a tabela acima: as 6 camadas de credenciais são empilhadas verticalmente de cima para baixo. O Claude Code varre do topo da pilha para baixo, ignora todas as camadas "vazias" e para na primeira camada "com valor" e a utiliza — no cenário de assinatura pessoal, as 5 camadas superiores estão vazias, então atinge a camada inferior do login de assinatura.

Você entendeu? A assinatura está na camada inferior. Portanto, enquanto houver valor em qualquer camada acima, ela sobrescreverá sua assinatura. Isso explica aquele cenário inicial — claramente logado no Max, mas gastando dinheiro da API — porque a ANTHROPIC_API_KEY na camada 3 está reprimindo a assinatura na camada 6.

Então como voltar para a assinatura? O método oficial é bem direto — limpe a camada de prioridade superior:

unset ANTHROPIC_API_KEY

Em seguida, execute /status para confirmar. Se estiver no modo interativo e não quiser usar uma determinada chave temporariamente, você também pode ir em /config e desativá-la através do botão "Usar chave de API personalizada".

Por outro lado, para alternar da assinatura para a API key, basta configurar com export a chave e aprová-la uma vez (veja a seção 03).

Vários detalhes fáceis de escorregar, anote todos:

• ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN só têm efeito para a sessão do terminal CLI. O cliente de desktop Claude Desktop e as sessões remotas só reconhecem o login OAuth e não leem essas variáveis de ambiente.
• Claude Code na Web (versão web) sempre usa sua credencial de assinatura, a variável de ambiente da API key na sandbox não a substitui.
• O ANTHROPIC_AUTH_TOKEN (camada 2) e o ANTHROPIC_API_KEY (camada 3) são duas coisas diferentes: o primeiro é enviado como um cabeçalho Authorization: Bearer, usado ao passar por um gateway / proxy; o segundo é enviado como um cabeçalho X-Api-Key, usado ao conectar-se diretamente à API oficial. Não os misture.

💡 Resumo em uma frase: Alternar = ajustar prioridade. A assinatura está na camada inferior, qualquer camada com valor acima irá sobrescrevê-la; para voltar para a assinatura, aplique o unset na de cima, em seguida verifique usando /status.

---

05 Base de escolha do modelo: opus, sonnet ou default

Depois que a identidade é configurada, há mais uma coisa para decidir: Qual modelo deixar ele usar para trabalhar.

Analogia: Atribuir tarefas a pessoas. O Opus é o engenheiro sênior mais forte do grupo — boa mente, raciocínio profundo, mas lento, caro; o Sonnet é o executor principal — a programação diária é rápida e estável, altamente custo-efetiva; o Haiku é o assistente de recados — tarefas simples com resposta imediata, o mais econômico. Atribua problemas difíceis ao Opus, tarefas diárias ao Sonnet e tarefas menores ao Haiku.

O Claude Code usa aliases de modelo para evitar que você precise memorizar uma longa sequência de números de versão. Os mais comuns são estes:

Alias	Uso
default	Valor especial: limpa a substituição manual, retorna ao modelo recomendado do nível da sua conta
opus	Último Opus, para raciocínio complexo / decisões de arquitetura
sonnet	Último Sonnet, para programação diária
haiku	Rápido e eficiente, lida com tarefas simples
best	Atualmente equivalente a opus, utiliza o modelo mais potente disponível
opusplan	Modo híbrido: Usa o Opus para pensar no Plan Mode, troca pro Sonnet ao executar
opus[1m] / sonnet[1m]	Com janela de contexto de 1 milhão de tokens, para grandes bases de código / sessões longas

Atenção: O alias aponta para a "versão recomendada para o seu nível", e será atualizado ao longo do tempo. A versão específica em que se resolve depende da documentação oficial. Por exemplo, na API da Anthropic, opus resolve atualmente para Opus 4.8 e sonnet resolve para Sonnet 4.6, mas diferentes provedores (Bedrock / Vertex etc.) resolvem para versões diferentes (de acordo com a documentação oficial, sujeitas a mudanças).

O seu nível de assinatura determina qual modelo lhe é atribuído por padrão:

Tipo de conta	default resolve para
Max / Team Premium / Faturamento por uso Enterprise / API Anthropic	Opus 4.8
Pro / Team Standard / Assentos de assinatura Enterprise	Sonnet 4.6

O que significa que usuários Pro por padrão usam Sonnet, usuários Max por padrão podem ir para o Opus — e essa é uma das razões para recomendar que usuários intensivos adquiram o Max. Além disso, ao atingir o limite de uso do Opus, o Claude Code pode retornar automaticamente ao Sonnet, e este é um comportamento normal, não um bug.

Como definir o modelo? Os métodos dados oficialmente por prioridade são quatro:

# 1. Troca temporária durante a sessão (executar /model sem argumentos abre o seletor) — a prioridade mais alta
/model sonnet

# 2. Especificar na inicialização
claude --model opus

# 3. Variável de ambiente (válido para esta sessão)
ANTHROPIC_MODEL=opus

// 4. Escrever em settings.json, tornando-se o padrão permanentemente para novas sessões — prioridade mais baixa
{
  "model": "opus"
}

Os itens acima estão ordenados da prioridade mais alta para a mais baixa: /model na sessão > --model na inicialização > variável de ambiente ANTHROPIC_MODEL > arquivo de configurações. Um hábito prático: no settings.json diário, fixe sonnet e, quando encontrar um problema de arquitetura difícil de mastigar, use /model opus temporariamente na conversa para subir o nível e economizar a cota.

Detalhes sobre o nível de esforço (/effort, que controla a profundidade do pensamento) e opusplan não serão expandidos aqui por enquanto — para iniciantes, acertar a escolha do modelo é o suficiente. Ao necessitar ir mais fundo, consulte a documentação oficial "Configuração de Modelos".

💡 Resumo em uma frase: Problemas difíceis opus, uso diário sonnet, tarefas pequenas haiku; o default acompanha o seu nível de assinatura, Pro é por padrão Sonnet, Max é por padrão Opus.

---

06 Mão na massa: 3 minutos para confirmar "quem estou usando"

Apenas ler e não praticar equivale a não ter lido. Com os comandos abaixo executados uma vez, você poderá entender completamente sua identidade atual e estado do modelo. Todo o processo no terminal e, em seguida, operado na interface do Claude Code, não dependendo de nenhum ambiente complexo.

Primeiro passo: Entrar no Claude Code. Encontre um diretório qualquer e execute:

claude

Segundo passo: Verificar o status atual. Na caixa de entrada do Claude Code, digite:

/status

Ele exibirá suas informações da conta e o método de autenticação / modelo atualmente ativo. O que você deve esperar ver será parecido com isso (os campos específicos variam com a versão, com base na exibição real):

Account: your@email.com (Max)
Auth: Claude subscription (OAuth)
Model: opus (Opus 4.8)

Se o que aparece em Auth for uma API key e você achava que estava usando a assinatura — parabéns, você acabou de pegar a armadilha mencionada no começo.

Terceiro passo: Ver quais modelos pode usar / trocar de modelo. Digite:

/model

Aparecerá o seletor de modelos, listando opções como opus / sonnet / haiku, selecione para cima e para baixo e pressione Enter para confirmar. Para mudar diretamente, digite:

/model sonnet

Quarto passo (Opcional): Verificar a prioridade de "Assinatura vs API key". Este passo permite que você veja a regra ensinada na seção 04 com seus próprios olhos. Primeiro feche o Claude Code e, no terminal:

# Veja se existe uma API key no ambiente "sorrateiramente" sobrescrevendo a sua assinatura
echo $ANTHROPIC_API_KEY

• Se a saída for uma string sk-ant-...: Indica que está oprimindo a sua assinatura. Para voltar para a assinatura, digite unset ANTHROPIC_API_KEY, em seguida entre no claude novamente e rode /status para verificar; o Auth deve ter voltado para a assinatura.
• Se a saída estiver vazia: Você estava efetivamente usando a assinatura (ou outra credencial de prioridade superior) desde o início, sem problemas.

Para verificar variáveis de ambiente no Windows (PowerShell) use:

echo $env:ANTHROPIC_API_KEY

Critério de aceitação: Você conseguir informar de relance pelo /status "se estou usando uma assinatura ou API key agora e qual modelo está rodando", e através do uso de unset + re-verificação, poder alternar de volta para a assinatura com suas próprias mãos. Tendo feito isso, o objetivo principal deste artigo foi alcançado.

---

07 Resumo

Este artigo explicou claramente uma coisa: Qual identidade o Claude Code usa para se conectar ao modelo e como escolher e alternar essa identidade.

Sua situação	Como configurar	Modelo padrão
Pessoal Pro / Max	Rodar claude → no navegador /login	Pro→Sonnet, Max→Opus
Scripts / CI / Equipes faturadas por uso	Obter chave no Console → configurar ANTHROPIC_API_KEY	Veja configuração específica
Deseja voltar para a assinatura	unset ANTHROPIC_API_KEY + re-verificar /status	—

Três pontos mais importantes para se lembrar:

• A assinatura está no último nível de prioridade, qualquer API key / token no ambiente irá sobrescrevê-la — caso haja cobranças inexplicáveis, verifique isso primeiro.
• /status é o seu espelho revelador: não tem certeza de quem está sendo usado, digite ele.
• O modelo é escolhido pela tarefa: problema difícil opus, dia a dia sonnet, default segue o seu nível de assinatura.

Agora você já deve conseguir: efetuar login corretamente após a instalação, compreender qual identidade e modelo está sendo usado, alternar entre a assinatura e a API key e nunca mais ser prejudicado por "estar conectado à assinatura, mas ser cobrado pela API".

Prévia do próximo artigo

Até aqui você esteve conectado aos modelos oficiais da Anthropic. Mas o uso do Claude na China Continental com a API oficial não é tão amigável — É possível fazer com que o Claude Code rode DeepSeek, Tongyi Qianwen (Qwen) e GLM, modelos nacionais?

É possível. O segredo está naquela variável de ambiente que continuou a aparecer neste artigo, mas nunca foi expandida — a ANTHROPIC_BASE_URL: ela não altera "qual modelo usar", apenas "para onde enviar a solicitação". O próximo artigo 05 · Integrando modelos de terceiros / modelos nacionais, a utilizará para conectar o Claude Code a grandes modelos nacionais, o que economiza dinheiro sem precisar pular muros digitais.

Deixo-lhe um pequeno pensamento: Já que a API key pode sobrescrever a assinatura, se eu apontar a ANTHROPIC_BASE_URL para a plataforma nacional e equipar com a chave correspondente, o Claude Code não passaria por uma "troca de cérebro"? A resposta na próxima vez.

---

Depois de ter conectado o "caminho principal" dos modelos oficiais, vamos seguir para a "bifurcação" dos modelos nacionais na próxima edição.

---

Leitura recomendada

• MCP: Conectando o Claude com o mundo exterior
• Controles e Modos: A "mesa de mixagem" ao abrir uma sessão
• Manual de referência de plugins: Como empacotar a sua própria configuração em um pacote compartilhável