Claude Code com chave de API, sem assinatura

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 cobra o uso de tokens na conta de API (application programming interface) dessa organização, em vez de o cobrar no seu plano. Execute /status numa sessão em execução para ver qual está ativa: o separador Status mostra uma linha Login method correspondente à conta usada no login, e aparece uma linha API key adicional quando uma chave de API fornece a credencial.

Saber se a ferramenta está incluída no seu plano é uma questão separada, respondida em se o Claude Code está incluído numa subscrição Claude Pro, e o funcionamento das chaves para a Claude API é explicado em como funciona a autenticação da Claude API. O que se segue é a parte que esses dois tópicos não abrangem: qual credencial a sessão realmente selecionou e como a alterar.

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

Duas contas que podem partilhar um 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 sessões de início de sessão separadas, com saldos separados e em organizações separadas. Criar uma não cria a outra. Adicionar saldo a uma organização Console não acrescenta nada ao seu plano.

O inverso tem uma exceção, verificada em 31 October 2026. Os planos Max e Ultra incluem agora créditos mensais para a API, de $100 e $200 por mês, e os planos Team recebem um montante partilhado. Esses créditos só chegam a uma organização Console depois de associar uma nas definições de faturação em claude.ai e não cobrem o Claude Code interativo. A documentação da plataforma da Anthropic indica que o Claude Code não está coberto, e o centro de ajuda abre uma exceção apenas para execuções claude -p que utilizem uma chave de API da organização associada. Por isso, uma sessão interativa faturada a uma organização que tenha apenas esses créditos falha com Credit balance too low.

Os saldos diferem porque os modelos de faturação são diferentes. Uma sessão iniciada com uma subscrição utiliza o limite de utilização do seu plano. Esse limite é partilhado com o Claude na Web e tem um limite semanal. Os planos Pro e Max também têm um limite de sessão de cinco horas, enquanto as contas Ultra verificadas não têm limite de cinco horas e as contas Ultra não verificadas têm um limite temporário. Nos planos Max e Ultra, o Fable tem um sublimite de 50% do limite semanal normal e consome esse mesmo limite mais rapidamente do que os outros modelos Claude. Uma credencial Console é faturada por token à organização, e os valores oficiais estão na página de utilização da Console. O custo dessa diferença em trabalho real é o tema de pagar por token em vez de pagar uma subscrição.

Um dos tipos de conta não pode utilizar a opção de subscrição. A Anthropic lista os tipos de conta com os quais pode iniciar sessão: uma subscrição Pro, Max ou Ultra; uma licença Claude for Teams ou Enterprise; uma conta Claude Console; um fornecedor de cloud; e um gateway Cloud, ou seja, um gateway de aplicações Claude autoalojado, executado pela sua organização, no qual inicia sessão com SSO (single sign-on) empresarial através de /login. Uma conta claude.ai gratuita não consta dessa lista. Por isso, um utilizador do plano gratuito não tem uma credencial de subscrição com a qual possa iniciar sessão, e o que o nível gratuito do Claude inclui e não inclui não se aplica à ferramenta de linha de comandos. A opção restante é uma organização Console com créditos de API, que é uma conta paga com um modelo diferente.

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

Execute claude num diretório de projeto. No primeiro arranque, o comando abre uma janela do browser para iniciar sessão com a conta claude.ai associada ao seu plano.

claude

Há dois comportamentos diferentes num servidor. Se o browser 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 browser no seu próprio computador. Se esse browser apresentar um código de início de sessão em vez de o devolver ao terminal, cole o código novamente na prompt que o solicita. Este segundo caso é normal através de SSH (secure shell), no WSL2 e dentro de contentores, porque o browser 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 o assumir. Inicie uma sessão e execute /status. O separador Status indica o método de início de sessão, bem como a organização e o endereço de email guardados. /login executa novamente o processo com outra conta, e /logout remove a credencial guardada. Terminar sessão também repõe o estado da configuração inicial, por isso o próximo claude apresenta novamente o processo de configuração inicial.

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

• Linux: ~/.claude/.credentials.json, com o modo de ficheiro 0600.
• macOS: o Keychain encriptado. Quando o Keychain rejeita a escrita, o que acontece quando está bloqueado numa sessão SSH, o Claude Code usa como alternativa o mesmo ficheiro 0600. Um início de sessão na Console que crie uma chave de API não usa essa alternativa e falha até o Keychain permitir a escrita.
• Windows: %USERPROFILE%\.claude\.credentials.json, restrito 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 no 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 da Console

O acesso à Console começa com um administrador. O administrador envia-lhe um convite na Console, em Settings, depois Members e, por fim, 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. Depois, selecione a conta da Anthropic no prompt /login.

A partir do Claude Code v2.1.242, existem dois caminhos na Console, e eles armazenam dados diferentes. Iniciar sessão com a sua conta da Console mantém o token OAuth (autorização aberta) dessa autenticação no browser e armazena-o como um perfil da Anthropic, sem criar qualquer chave de API. O Claude Code atualiza essa sessão automaticamente. Se a atualização falhar, os pedidos falham até iniciar sessão novamente. Essa autenticação sem chave também termina qualquer sessão do claude.ai armazenada no computador. Criar uma chave de API, identificada como legacy pelo prompt, gera uma chave da Console e armazena-a com as restantes credenciais. Uma chave estática nunca é atualizada. Continua a funcionar até alguém a revogar. Isto é útil num servidor de build e representa um risco num portátil.

Remova ANTHROPIC_API_KEY antes de iniciar uma autenticação sem chave na Console. Quando essa variável está definida, o Claude Code ignora completamente o prompt de início de sessão e pede-lhe para aprovar a chave encontrada.

Nem sempre é possível escolher. O Claude Code cria uma chave sem perguntar quando a sessão é executada num cloud provider, quando qualquer ficheiro de definições define forceLoginOrgUUID ou fixa forceLoginMethod como "claudeai", ou quando existe uma origem de definições geridas no computador, mas o Claude Code não consegue lê-la e nenhuma outra origem gerida fornece uma política. Com apenas forceLoginMethod definido como "console", uma autenticação falhada apresenta uma opção de nova tentativa que permite escolher a opção sem chave. Estas são decisões do administrador. Se a opção sem chave nunca aparecer, contacte a pessoa responsável pela gestão da frota. /status também apresenta uma linha Setting sources com o nome de cada ficheiro de definições carregado pela sessão. Também identifica a origem gerida quando esta se aplica. As restrições de início de sessão geridas também bloqueiam sessões que utilizem ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN ou apiKeyHelper. Remova essas credenciais e utilize o método de autenticação exigido.

Na primeira vez que autenticar o Claude Code numa organização da Console, a Console cria para essa organização um workspace chamado "Claude Code". Esse workspace existe para que os gastos do Claude Code sejam controlados num único local. Não é possível criar chaves de API dentro dele.

Por que ANTHROPIC_API_KEY tem prioridade depois do início de 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 outubro de 2026, essa ordem é:

1. Credenciais do fornecedor de cloud, quando CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX ou CLAUDE_CODE_USE_FOUNDRY está definido.
2. ANTHROPIC_AUTH_TOKEN, enviado num cabeçalho Authorization: Bearer, para gateways que autenticam com bearer tokens.
3. ANTHROPIC_API_KEY, enviado como cabeçalho X-Api-Key.
4. A saída de um script apiKeyHelper indicado num ficheiro de definições.
5. CLAUDE_CODE_OAUTH_TOKEN, o token de longa duração proveniente de claude setup-token.
6. Credenciais de perfil e federação da Anthropic, usadas pela CLI ant e pelo Workload Identity Federation.
7. A credencial da subscrição escrita por /login.

Há duas exceções relacionadas com essa lista. Um perfil fica na posição 6 quando é indicado em ANTHROPIC_PROFILE, quando as variáveis de federação estão definidas ou quando o perfil ativo é um perfil de Workload Identity Federation. Um perfil ativo no modo user_oauth, criado por ant auth login ou por um início de sessão sem chave no Console, fica abaixo de uma credencial /login funcional. Além disso, uma sessão ativa num gateway do Claude apps fica fora da lista: tem prioridade sobre todas as opções da lista, incluindo as variáveis do fornecedor de cloud. Quando as definições geridas pelo administrador exigem o início de sessão no gateway e nenhum fornecedor de cloud é selecionado por uma variável de ambiente, o Claude Code ignora as outras fontes e pede que você inicie sessão através de /login.

Nenhuma destas exceções protege a sua subscrição contra uma chave exportada. Sem um gateway ou restrições de início de sessão geridas, tudo entre as posições 1 e 5 tem prioridade sobre a conta usada no início de sessão. Portanto, uma ANTHROPIC_API_KEY aprovada e exportada em qualquer ponto do ambiente do processo tem prioridade, e a sessão debita uma organização do Console enquanto você acredita que está a usar o seu plano. Nada está avariado. A ordem está a funcionar conforme documentado. O Claude Code mostra uma notificação depois do início de sessão quando ambas as credenciais estão ativas, alertando para possíveis cobranças inesperadas da API.

Dois detalhes tornam isto fácil de não detetar. Numa sessão interativa, o Claude Code pergunta uma vez se deve usar a chave encontrada e memoriza a resposta. Por isso, uma escolha feita há um mês ainda se aplica hoje. No modo não interativo com -p, não há qualquer aviso e a chave é sempre usada quando está presente. -p é o modo usado por uma tarefa cron ou por uma etapa de CI (integração contínua), por isso é precisamente num processo não supervisionado que a credencial errada pode passar despercebida durante mais tempo.

Há uma verificação visual rápida dentro da sessão. Enquanto ANTHROPIC_API_KEY estiver definido, /config mostra um seletor "Usar chave de API personalizada". O seletor só existe enquanto a variável estiver definida. Portanto, a sua ausência significa que essa variável não está definida na sessão.

Como localizar a chave perdida num servidor

Uma chave exportada permanece em mais locais do que num 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 que abrir hoje pode herdar uma variável que removeu do seu perfil na semana passada, porque o servidor já estava em execução antes da alteração.
• Uma imagem de contentor ou uma definição de tarefa de CI, onde a variável é definida fora de qualquer ficheiro que possa ler 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 encaminha a saída através de 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 verifica esta shell: se indicar que a variável está definida, o próximo claude irá herdá-la, embora as definições possam substituí-la e uma sessão interativa mantenha o registo de que ela foi aprovada. Um resultado not set, sem correspondências nos restantes comandos, não exclui credenciais provenientes de outros ficheiros de definições ou de fontes com prioridade superior na ordem; /status confirma o que a sessão selecionou.

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

Trocar uma sessão de uma credencial para 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 sua subscrição é a credencial em uso. Quando estiverem configurados um login e uma API key, /status identifica a credencial que não está em uso. 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, elimine o export do ficheiro que o definiu. Caso contrário, a próxima shell de login irá restaurá-lo. Dentro do 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 iniciar sessão no Console sem uma key, /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 settings que o Claude Code rejeitou. Isso permite identificar um ficheiro de settings que falhou ao ser analisado e, por isso, nunca foi aplicado.

Autenticar quando não há um browser

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

claude setup-token

O token não é guardado em nenhum local. Copie-o quando aparecer. Defina-o como CLAUDE_CODE_OAUTH_TOKEN na máquina que precisa dele. O token autentica-se na sua subscrição, por isso requer um plano Pro, Max, Ultra, Team ou Enterprise e só pode fazer pedidos a modelos. 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 aqui. Se CLAUDE_CODE_OAUTH_TOKEN estiver num perfil da shell, executar /login muda a sessão atual para o novo login. Todas as sessões novas continuam 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 de precedência e não ocorre qualquer login no browser. Essa 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 reiniciada desde então. Executar Claude Code num VPS dentro do tmux descreve o funcionamento da sessão nessa configuração.

Verificar o que cada credencial consumiu efetivamente

Numa sessão iniciada com uma 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 das contagens de tokens e dos preços de tabela, ou das tarifas contratadas pela sua organização quando um administrador configurou uma tabela modelPricing nas definições geridas; nesse caso, a linha Total cost indica-o. Em qualquer dos casos, trate-o como uma estimativa destinada a utilizadores da API, não como 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 para os custos e o dashboard do Claude Code para 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, é provável que uma credencial de ambiente esteja a ganhar prioridade, e /status esclarece a situação. A exceção ocorre quando as barras já estão cheias: uma sessão de subscrição pode continuar depois de atingir o limite incluído, utilizando créditos de utilização que a Anthropic fatura às tarifas padrão da API, e as barras permanecem inalteradas enquanto isso acontece. Uma nota Showing last-known usage é outra explicação: /usage está a mostrar um instantâneo dos últimos 60 minutos porque não conseguiu obter limites atualizados; prima r para tentar novamente. Fora desses casos, barras inalteradas são o sinal mais claro de que a credencial errada está ativa, e acompanhar o consumo de uma sessão do Claude Code explica como medi-lo com mais detalhe. Quando as barras avançam e depois param, atingiu antes um limite do plano; como funcionam os limites de utilização do Claude e as janelas de reposição explica essa situação.

Modos de falha e o que verificar

Tudo funciona, mas o uso do seu plano nunca muda. Normalmente, uma credencial de ambiente está ativa: /status mostra uma linha API key, e a verificação da shell acima mostra a variável. Se nenhuma das duas mostrar isso e as barras estiverem no limite, a sessão passou a usar créditos de uso, cobrados pelas tarifas padrão da API. Esse gasto aparece em Settings e, depois, Usage no claude.ai.

Os pedidos falham embora a sua subscrição esteja ativa. Uma chave pertencente a uma organização do Console desativada ou expirada está a ter precedência sobre o seu login. Execute unset ANTHROPIC_API_KEY, inicie uma sessão nova 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 esse caso em detalhe, incluindo por que executar /login novamente não o resolve.

É apresentado no arranque um aviso de que o seu login está a expirar. As versões recentes avisam quando uma credencial /login expira dentro de três dias. Depois de expirar, /status mostra a linha do login como expirada, 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. Esse intervalo pode ser alterado com CLAUDE_CODE_API_KEY_HELPER_TTL_MS. O Claude Code mostra uma notificação na barra do prompt quando uma execução demora mais de dez segundos. Se um auxiliar não devolver uma chave, devido a um erro ou a um timeout, os pedidos falham no máximo após três tentativas.

A credencial correta, 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 saber qual 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 API key fornece a credencial. Uma linha Profile substitui a linha de login quando seleciona um perfil Anthropic ou uma credencial de federation. Fora da sessão, verificar se ANTHROPIC_API_KEY está definida na shell indica se existe uma credencial de ambiente que teria precedência sobre o login depois de aprovada, exceto quando uma gateway ou uma restrição de managed login tem precedência.

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

Porque uma credencial de ambiente tem precedência sobre ela. O Claude Code utiliza a primeira credencial que encontra numa ordem fixa, e a credencial da subscrição /login fica abaixo das variáveis do cloud provider, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper, CLAUDE_CODE_OAUTH_TOKEN e de qualquer perfil Anthropic ou credencial de federation selecionado com ANTHROPIC_PROFILE ou com as variáveis de federation. Apenas um perfil ativo no modo user_oauth fica abaixo dela, e uma sessão autenticada numa Claude apps gateway tem precedência sobre toda a lista. Execute unset ANTHROPIC_API_KEY, inicie uma sessão nova e confirme com /status. Depois remova o export do perfil da shell, da unidade systemd, do ambiente tmux ou da definição do contentor que o configurou. Caso contrário, ele volta a ser definido na próxima shell de login.

Posso utilizar o Claude Code com uma conta Claude gratuita?

Não. Os tipos de conta que a Anthropic lista para o login são uma subscrição Pro, Max ou Ultra, uma licença Claude for Teams ou Enterprise, uma conta Claude Console, um cloud provider e uma Cloud gateway. Esta última é uma Claude apps gateway self-hosted, autenticada com SSO empresarial através de /login. Uma conta gratuita do claude.ai não está incluída nessa lista, pelo que 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, faturada 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. O uso da subscrição é descontado do limite do plano, partilhado com o Claude na Web, e tem um limite semanal. As contas Ultra verificadas não têm um limite de cinco horas, enquanto as contas Pro e Max têm um limite de sessão de cinco horas e as contas Ultra não verificadas têm um limite temporário. Nos planos Max e Ultra, o Fable tem um sublimite de 50% do limite semanal normal e consome esse limite mais depressa do que os outros modelos Claude. O uso do Console é faturado por token à organização e aparece na página de uso do Console. Adicionar crédito a uma conta não altera a outra. A única ligação opcional vai do plano para o Console: um plano Max, Ultra ou Team pode enviar os seus créditos de API mensais para uma organização Console associada a partir do claude.ai. Esses créditos não cobrem o Claude Code interativo, mas cobrem execuções claude -p iniciadas por si com uma API key da organização associada.

Como autentico o Claude Code num servidor headless?

Existem duas opções. Execute claude através de SSH e conclua o login no navegador na sua própria máquina: prima c para copiar o URL, inicie sessão nesse endereço e cole o código de volta no terminal se o navegador mostrar um código em vez de redirecionar. Em alternativa, execute claude setup-token numa máquina com navegador, copie o token válido por um ano que o comando apresenta e defina-o como CLAUDE_CODE_OAUTH_TOKEN no servidor. Esse token requer um plano Pro, Max, Ultra, Team ou Enterprise e só pode fazer pedidos a modelos. Por isso, um script que utilize --bare precisa de uma API key ou de um apiKeyHelper.