Claude Code: assinatura ou chave de API?

Qual credencial a sua sessão do Claude Code está a usar?

Um login do Claude Code funciona de uma de duas formas. Pode iniciar sessão com uma conta de subscrição do Claude em claude.ai ou autenticar-se numa organização do Anthropic Console, que contabiliza cada token no saldo da API (interface de programação de aplicações) dessa organização. Execute /status numa sessão em execução para ver qual está ativa: o separador Status mostra uma linha Login method relativa à conta usada no início de sessão, e aparece uma linha API key adicional quando uma chave de API fornece a credencial.

A questão de saber se a ferramenta está incluída no seu plano é separada e é respondida em se o Claude Code está incluído numa subscrição Claude Pro. O funcionamento das chaves na API do Claude é explicado em como funciona a autenticação da API do Claude. O que se segue é a parte que esses dois tópicos não abrangem: qual credencial a sessão escolheu efetivamente e como alterá-la.

O comportamento abaixo baseia-se na documentação de autenticação do Claude Code da Anthropic, consultada em 31 August 2026. O Claude Code lança versões com frequência e vários destes comportamentos exigem uma versão mínima. Por isso, execute claude --version antes de concluir que existe um problema na sua máquina.

Duas contas que podem partilhar o mesmo endereço de email

Uma conta claude.ai e uma conta Claude Console em platform.claude.com são contas diferentes. Podem usar o mesmo endereço de email e continuar a ser inícios de sessão separados, com saldos separados e em organizações separadas. Criar uma não cria a outra. Pagar um plano Max não adiciona crédito a uma organização Console, e adicionar crédito a uma organização Console não acrescenta nada ao seu plano.

Os saldos diferem porque os modelos de faturação são diferentes. Um início de sessão de subscrição usa o limite de utilização do seu plano, que é reposto numa janela móvel de cinco horas e numa janela semanal. Esse limite é partilhado com o Claude na web. Uma credencial Console é faturada por token à organização, e os valores oficiais estão na página de utilização do Console. O impacto dessa diferença no trabalho real é o tema de pagar por token ou pagar uma subscrição.

Um dos tipos de conta não pode usar o método de subscrição. A Anthropic indica que pode iniciar sessão com uma subscrição Pro ou Max, uma licença Claude for Teams ou Enterprise, uma conta Claude Console ou um fornecedor de cloud. Uma conta claude.ai gratuita não aparece nessa lista. Por isso, um utilizador do plano gratuito não tem uma credencial de subscrição para iniciar sessão, e o que o nível gratuito do Claude inclui e não inclui não se estende à ferramenta de linha de comandos. A alternativa restante é uma organização Console com crédito de API, que é uma conta paga de outro tipo.

Caminho 1: iniciar sessão com a sua subscrição Claude

Execute claude num diretório de projeto. Na primeira execução, abre uma janela do navegador para iniciar sessão com a conta claude.ai associada ao seu plano.

claude

Há duas diferenças importantes num servidor. Se o navegador não abrir, prima c para copiar o URL de início de sessão para a área de transferência e cole-o num navegador na sua própria máquina. Se esse navegador mostrar um código de início de sessão em vez de o devolver ao terminal, cole o código na pergunta que o solicita. Este segundo caso é normal através de SSH (secure shell), no WSL2 e dentro de contentores, porque o navegador não consegue aceder ao servidor de callback local que o Claude Code iniciou na máquina remota.

Quando o início de sessão terminar, confirme-o em vez de assumir que foi concluído. Inicie uma sessão e execute /status. O separador Status indica o método de início de sessão, além da organização e do endereço de email guardados. /login executa novamente o fluxo com outra conta, e /logout remove a credencial guardada. Terminar a sessão também repõe o estado da configuração inicial, pelo que o próximo claude apresenta novamente o processo de integração.

É importante saber onde essa credencial é guardada quando reinstala um servidor ou o entrega a outra pessoa:

• Linux: ~/.claude/.credentials.json, modo do ficheiro 0600.
• macOS: o Keychain encriptado. Quando o Keychain rejeita a gravação, o que acontece quando está bloqueado numa sessão SSH, o Claude Code usa como fallback o mesmo ficheiro 0600.
• Windows: %USERPROFILE%\.claude\.credentials.json, restringido ao seu utilizador pelos próprios controlos de acesso do diretório do perfil.
• Qualquer plataforma com CLAUDE_CONFIG_DIR definido: o ficheiro é movido para esse diretório, e a entrada do Keychain do macOS fica associada a esse diretório. Assim, uma sessão iniciada com um CLAUDE_CONFIG_DIR diferente lê uma credencial diferente.

O Claude Code gere esse ficheiro através de /login e /logout. Editá-lo manualmente não é uma forma suportada de mudar de conta.

Caminho dois: autenticar numa organização do Console

O acesso ao Console começa com um administrador. O administrador envia-lhe um convite no Console, em Settings, depois Members e Invite. Também atribui uma função: a função Claude Code pode criar apenas chaves de API do Claude Code, enquanto a função Developer pode criar qualquer chave. Em seguida, selecione a conta do Anthropic Console no prompt /login.

A partir do Claude Code v2.1.242, existem dois caminhos no Console, e cada um armazena dados diferentes. Ao iniciar sessão com a conta do Console, o Claude Code mantém o token OAuth (autorização aberta) desse início de sessão no browser e armazena-o como um perfil do Anthropic, sem criar qualquer chave de API. O Claude Code atualiza esse início de sessão automaticamente. Quando a atualização falha, os pedidos falham até iniciar sessão novamente. Ao criar uma chave de API, identificada como legacy no prompt, o Claude Code gera uma chave do Console e armazena-a com as outras credenciais. Uma chave estática nunca é atualizada. Por isso, continua a funcionar até ser revogada. Isto é útil num servidor de build, mas representa um risco num portátil.

Remova a definição de ANTHROPIC_API_KEY antes de iniciar um login sem chave no Console. Com essa variável definida, o Claude Code ignora completamente o prompt de início de sessão e pede-lhe para aprovar a chave encontrada.

Nem sempre pode escolher. O Claude Code cria uma chave sem perguntar quando a sessão utiliza um fornecedor de cloud, quando qualquer ficheiro de definições define forceLoginOrgUUID ou fixa forceLoginMethod como "claudeai" ou "console", ou quando existe uma origem de definições gerida na máquina e o Claude Code não consegue lê-la. Estas são decisões do administrador. Se a opção sem chave nunca aparecer, pergunte a quem administra a frota. /status também imprime uma linha Setting sources com o nome de cada ficheiro de definições carregado pela sessão. Quando aplicável, também identifica a origem gerida.

Na primeira vez que autenticar o Claude Code numa organização do Console, o Console cria um workspace chamado "Claude Code" para essa organização. Esse workspace existe para que os custos do Claude Code sejam acompanhados num único local. Não pode criar chaves de API dentro dele.

Por que ANTHROPIC_API_KEY tem precedência depois do início da sessão

O Claude Code nunca pergunta qual credencial você prefere usar. Ele verifica as fontes numa ordem fixa e usa a primeira que encontrar. Conforme documentado em agosto de 2026, a ordem é:

1. Credenciais do provedor de nuvem, quando CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX ou CLAUDE_CODE_USE_FOUNDRY está definido.
2. ANTHROPIC_AUTH_TOKEN, enviado como cabeçalho Authorization: Bearer, para gateways que autenticam com tokens bearer.
3. ANTHROPIC_API_KEY, enviado como cabeçalho X-Api-Key.
4. A saída de um script apiKeyHelper indicado num arquivo de configurações.
5. CLAUDE_CODE_OAUTH_TOKEN, o token de longa duração de claude setup-token.
6. Credenciais de perfil e federação da Anthropic.
7. A credencial da assinatura gravada por /login.

O login da sua assinatura aparece por último. Portanto, um ANTHROPIC_API_KEY exportado em qualquer ponto do ambiente do processo tem precedência sobre a conta com a qual você iniciou a sessão. A sessão cobra de uma organização do Console enquanto você acredita que está usando o seu plano. Não há uma falha. A ordem está funcionando conforme documentado. Por isso, nada avisa você.

Dois detalhes facilitam não perceber isso. Numa sessão interativa, o Claude Code pergunta uma vez se deve usar a chave encontrada e memoriza a resposta. Assim, uma escolha feita há um mês ainda se aplica hoje. No modo não interativo com -p, não há prompt. A chave é sempre usada quando está presente. -p é o modo usado por um cron job ou uma etapa de CI (integração contínua). Por isso, um job não supervisionado é exatamente onde a credencial errada passa mais tempo sem ser detectada.

Há uma verificação visual rápida dentro da sessão. Enquanto ANTHROPIC_API_KEY está definido, /config mostra uma opção "Usar chave de API personalizada". A opção só existe enquanto a variável está definida. Portanto, a ausência dela significa que o ambiente está limpo.

Localizar a chave perdida num servidor

Uma chave exportada permanece em mais lugares além do perfil da shell:

• ~/.bashrc, ~/.bash_profile, ~/.profile ou ~/.zshrc, lidos por cada nova shell de login.
• Uma unidade systemd, através de Environment= ou EnvironmentFile=, para qualquer processo executado como serviço.
• O servidor tmux, que mantém uma cópia do ambiente com que foi iniciado. Um painel aberto hoje pode herdar uma variável que foi removida do perfil na semana passada, porque o servidor está em execução desde antes dessa alteração.
• Uma imagem de contentor ou definição de tarefa de CI, onde a variável é definida fora de qualquer ficheiro que possa ser lido a partir da shell.
• O bloco env de um ficheiro de definições do Claude Code, que é uma chave de definições normal e segue a precedência normal das definições.

Verifique estes locais antes de fazer qualquer outra alteração:

[ -n "$ANTHROPIC_API_KEY" ] && echo "ANTHROPIC_API_KEY is set" || echo "not set"
env | grep -E '^(ANTHROPIC_|CLAUDE_CODE_)' | cut -d= -f1
grep -n 'ANTHROPIC_API_KEY' ~/.bashrc ~/.bash_profile ~/.profile ~/.zshrc 2>/dev/null
tmux show-environment 2>/dev/null | grep ANTHROPIC
grep -n 'ANTHROPIC_API_KEY\|apiKeyHelper' ~/.claude/settings.json .claude/settings.json .claude/settings.local.json 2>/dev/null

O segundo comando usa cut de propósito. Assim, imprime os nomes das variáveis sem mostrar os valores secretos num ecrã que possa estar a ser partilhado ou gravado. O primeiro comando responde à questão principal: se indicar que a variável está definida, o próximo claude iniciado a partir desta shell usará essa chave. Se os cinco comandos não produzirem saída, não existe uma credencial no ambiente. Uma sessão iniciada aqui usará a sua credencial /login.

Adicione systemctl cat your-unit.service | grep -i environment a qualquer serviço que execute Claude Code. Um ficheiro de unidade define o seu próprio ambiente e nunca lê o perfil da shell.

Alternar uma sessão entre uma credencial e outra

Para voltar à sua subscrição:

unset ANTHROPIC_API_KEY
[ -n "$ANTHROPIC_API_KEY" ] && echo "still set" || echo "clear"
claude

Aguarde clear. Em seguida, execute /status na nova sessão e confirme que a linha API key desapareceu. Remover a variável da shell não afeta um processo do Claude Code que já esteja em execução, porque um processo mantém o ambiente com que foi iniciado. Reinicie a sessão.

Em seguida, remova o export do ficheiro que o definiu. Caso contrário, a próxima shell de login irá defini-lo novamente. No tmux, tmux set-environment -u ANTHROPIC_API_KEY limpa a variável para os painéis abertos depois desse momento na sessão. Os painéis já abertos mantêm a sua própria cópia.

Para fazer a troca no sentido contrário, defina ANTHROPIC_API_KEY no ambiente ou execute /login e selecione a conta Console. Para limpar completamente um login armazenado, execute /logout. Depois de um login Console sem chave, /logout remove e revoga a credencial criada por esse login.

Se /status continuar diferente do esperado, execute claude doctor. O comando lista as entradas de configurações rejeitadas pelo Claude Code. Isso permite detetar um ficheiro de configurações que falhou ao ser analisado e, por isso, nunca foi aplicado.

Autenticação quando não existe um browser

claude setup-token abre o mesmo fluxo de autorização no browser que /login e imprime um token OAuth válido por um ano no terminal.

claude setup-token

O token não é guardado em nenhum local, por isso copie-o quando aparecer. Defina-o como CLAUDE_CODE_OAUTH_TOKEN na máquina que precisa dele. O token autentica-se com a sua subscrição, por isso requer um plano Pro, Max, Team ou Enterprise, e só pode fazer pedidos ao modelo. O modo bare não o lê, por isso um script que passe --bare precisa de ANTHROPIC_API_KEY ou de um apiKeyHelper.

A precedência também é importante neste caso. Se CLAUDE_CODE_OAUTH_TOKEN estiver num perfil da shell, executar /login muda a sessão atual para o novo login, e todas as sessões novas voltam a ler a variável até a remover.

Se a sua organização executar inferência através do Amazon Bedrock, Google Cloud ou Microsoft Foundry, essas credenciais ficam no topo da ordem e não ocorre qualquer login no browser. A configuração é uma tarefa separada, descrita em executar Claude Code no Bedrock ou Vertex.

Uma sessão de longa duração num VPS (virtual private server) é onde estes problemas se concentram, porque a shell que a iniciou pode ter sido configurada há meses e nunca mais reiniciada. Executar Claude Code num VPS dentro do tmux aborda a parte da sessão dessa configuração.

Verificando quanto cada credencial realmente consumiu

Num login de subscrição, /usage mostra as barras de utilização do seu plano e uma discriminação do que as consumiu. O valor em dólares no bloco Session é calculado localmente a partir da contagem de tokens ao preço de tabela. Considere-o uma estimativa destinada a utilizadores da API, não uma fatura. Os subscritores devem consultar as barras, não os valores em dólares.

Numa credencial do Console, os valores relevantes estão no Console: a página de utilização mostra os gastos, e o dashboard do Claude Code mostra os valores por membro. Nada do que é apresentado no terminal é uma fonte oficial para essa faturação.

Se as barras do plano nunca avançarem enquanto trabalha, uma credencial de ambiente está a prevalecer na ordem de seleção. Esse sintoma isolado é o sinal mais fiável de que a credencial em vigor está errada, e acompanhar quanto uma sessão do Claude Code consome explica como medir isso com mais detalhe. Se as barras avançarem e depois pararem, atingiu um limite do plano. como funcionam os limites de utilização do Claude e as janelas de reposição explica esse caso.

Modos de falha e o que verificar

Tudo funciona, mas o uso do seu plano nunca muda. Uma credencial de ambiente está em vigor. /status mostra uma linha API key, e a verificação da shell acima mostra a variável.

Os pedidos falham, embora a sua subscrição esteja ativa. Uma chave pertencente a uma organização da Console desativada ou expirada está a ter precedência sobre o seu início de sessão. Execute unset ANTHROPIC_API_KEY, inicie uma nova sessão e verifique /status novamente. Se a falha indicar uma chave de API inválida, corrigir o erro de chave de API inválida do Claude Code explica este caso em detalhe, incluindo o motivo pelo qual executar /login novamente não o resolve.

É apresentado um aviso no arranque de que o seu início de sessão está a expirar. As versões recentes avisam quando uma credencial /login expira dentro de três dias. /status mostra então a linha de início de sessão num estado expirado, com a organização e o email que guardou. Execute /login para renovar. O aviso nunca bloqueia um pedido. Por isso, é fácil ignorá-lo até uma sessão não supervisionada deixar de avançar.

Um apiKeyHelper está lento ou falha. Por predefinição, o Claude Code executa novamente o auxiliar a cada cinco minutos. Pode ajustar esse intervalo com CLAUDE_CODE_API_KEY_HELPER_TTL_MS. É apresentada uma notificação na barra de comandos quando uma execução demora mais de dez segundos. Um auxiliar que não devolve uma chave, quer tenha ocorrido um erro quer tenha expirado o tempo limite, causa falhas nos pedidos no máximo após três tentativas.

A credencial certa, mas a organização errada. Um endereço de email pode pertencer a duas organizações. /status indica a organização na qual a autenticação foi efetuada. Leia essa linha em vez de presumir em qual organização iniciou sessão.

FAQ

Como posso saber que conta o Claude Code está a utilizar neste momento?

Execute /status na sessão. O separador Status mostra uma linha Login method para a conta com que iniciou sessão e adiciona uma linha API key quando uma chave de API fornece a credencial. Uma linha Profile substitui a linha de início de sessão quando é selecionado um perfil Anthropic ou uma credencial de federação. Fora da sessão, verificar se ANTHROPIC_API_KEY está definida na shell permite saber se existe uma credencial de ambiente que teria precedência sobre o início de sessão.

Porque é que a minha subscrição Claude Pro ou Max está a ser ignorada?

Porque existe uma credencial de ambiente com precedência. O Claude Code utiliza a primeira credencial que encontra numa ordem fixa, e a credencial da subscrição /login aparece em último lugar, abaixo das variáveis do fornecedor cloud, de ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper e CLAUDE_CODE_OAUTH_TOKEN. Execute unset ANTHROPIC_API_KEY, inicie uma nova sessão e confirme com /status. Depois remova a exportação do perfil da shell, da unidade systemd, do ambiente tmux ou da definição do contentor que a configurou. Caso contrário, ela volta a ser definida na próxima shell de início de sessão.

Posso utilizar o Claude Code com uma conta Claude gratuita?

Não. Os tipos de conta que a Anthropic indica para início de sessão são uma subscrição Pro ou Max, um lugar Claude for Teams ou Enterprise, uma conta Claude Console e um fornecedor cloud. Uma conta claude.ai gratuita não é uma dessas opções, por isso não existe uma credencial de subscrição para armazenar. A alternativa paga a uma subscrição é uma organização Claude Console com crédito de API, faturado por token. Trata-se de uma conta separada, mesmo quando utiliza o mesmo endereço de email.

A minha conta claude.ai e a minha conta Console partilham o mesmo saldo?

Não. São contas separadas, com faturação separada, mesmo quando utilizam o mesmo endereço de email. A utilização da subscrição consome o limite do seu plano, que é partilhado com o Claude na Web e é reposto numa janela móvel de cinco horas e numa janela semanal. A utilização da Console é faturada por token à organização e aparece na página de utilização da Console. Adicionar crédito a uma conta não altera a outra.

Como autentico o Claude Code num servidor sem interface gráfica?

Existem duas opções. Execute claude através de SSH e conclua o início de sessão no browser do seu próprio computador: prima c para copiar o URL, inicie sessão nesse endereço e cole o código de volta no terminal se o browser apresentar um código em vez de redirecionar. Ou execute claude setup-token numa máquina com browser, copie o token válido por um ano que o comando apresentar e defina-o como CLAUDE_CODE_OAUTH_TOKEN no servidor. Esse token requer um plano Pro, Max, Team ou Enterprise e só pode efetuar pedidos a modelos. Por isso, um script que utilize --bare precisa de uma chave de API ou de um apiKeyHelper.