Claude Code com chave de API, sem assinatura

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

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 fatura a utilização de tokens na conta da API (application programming interface) dessa organização, em vez de a contabilizar no seu plano. Execute /status dentro de uma sessão em execução para ver qual está ativa: o separador Status mostra uma linha Login method correspondente à conta utilizada no início de sessão, 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 na API do Claude é explicado em como funciona a autenticação da API do Claude. O que se segue trata do que esses dois tópicos não explicam: qual credencial a sessão selecionou efetivamente e como alterá-la.

O comportamento abaixo baseia-se na documentação de autenticação do Claude Code da Anthropic, consultada em 10 October 2026. O Claude Code lança versõ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 a sua máquina está avariada.

Duas contas podem partilhar o mesmo endereço de e-mail

Uma conta claude.ai e uma conta Claude Console em platform.claude.com são contas diferentes. Podem usar o mesmo endereço de e-mail e continuar a ser sessões de início de sessão separadas, com saldos separados e em organizações separadas. Criar uma delas não cria a outra. Adicionar saldo a uma organização do Console não acrescenta nada ao seu plano.

O inverso tem uma exceção, verificada em 10 October 2026. Os planos Max 5x e Max 20x incluem agora créditos mensais de API, de $100 e $200 por mês, respetivamente, e os planos Team recebem um montante partilhado. Esses créditos só chegam a uma organização do Console depois de associar uma organização nas definições de faturação em claude.ai, e não cobrem Claude Code. A documentação da plataforma da Anthropic indica que o Claude Code não está incluído, e o centro de ajuda abre uma exceção apenas para execuções de claude -p que utilizem uma API key da organização associada. Por isso, uma sessão interativa faturada a uma organização que contenha 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 de subscrição utiliza a franquia de utilização do seu plano, que é reposta numa janela móvel de cinco horas e numa janela semanal. Essa franquia é partilhada com o Claude na web. Uma credencial do Console é faturada por token à organização, e os valores oficiais estão na página de utilização do Console. O custo dessa diferença num trabalho real é o tema de pagar por token em vez de pagar uma subscrição.

Um tipo de conta não pode utilizar o caminho da subscrição. A Anthropic lista os tipos de conta com que pode iniciar sessão: uma subscrição Pro ou Max, um lugar Claude for Teams ou Enterprise, uma conta Claude Console, um fornecedor cloud e um Cloud gateway, ou seja, um gateway de aplicações Claude autoalojado que a sua organização executa e no qual inicia sessão com SSO empresarial (single sign-on) através de /login. Uma conta gratuita do claude.ai não está nessa lista. Por isso, um utilizador do plano gratuito não tem uma credencial de subscrição com que 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 alternativa restante é uma organização do Console com crédito 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 do Console

O acesso ao Console começa com um administrador. O administrador envia-lhe um convite pelo Console, em Settings, depois Members e, por fim, Invite. Também atribui uma função: a função Claude Code só pode criar chaves de API do Claude Code, enquanto a função Developer pode criar qualquer chave. Depois, 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 sua conta do Console, o Claude Code mantém o token OAuth (autorização aberta) desse início de sessão no navegador e armazena-o como um perfil 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. Esse início de sessão sem chave também termina qualquer sessão do claude.ai armazenada no computador. Ao criar uma chave de API, identificada pelo prompt como legacy, o Console gera uma chave 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, mas representa um risco num portátil.

Remova a definição de ANTHROPIC_API_KEY antes de iniciar um início de sessão sem chave no 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 é apresentada essa escolha. O Claude Code cria uma chave sem perguntar quando a sessão é executada através de um fornecedor de cloud, quando algum ficheiro de definições define forceLoginOrgUUID ou fixa forceLoginMethod como "claudeai" ou "console", ou quando existe uma origem de definições geridas no computador 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 à pessoa responsável pela gestão dos computadores. /status também apresenta uma linha Setting sources que identifica todos os ficheiros de definições carregados pela sessão. Também identifica a origem gerida quando esta se aplica a si.

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 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 precedência depois de iniciar sessão

O Claude Code nunca pergunta qual credencial prefere utilizar. Consulta as fontes por uma ordem fixa e utiliza a primeira que encontrar. Conforme documentado em outubro de 2026, a 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 tokens bearer.
3. ANTHROPIC_API_KEY, enviado como cabeçalho X-Api-Key.
4. O resultado de um script apiKeyHelper indicado num ficheiro de definiçõ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, utilizadas pela CLI ant e pela Workload Identity Federation.
7. A credencial da subscrição gravada por /login.

Há duas exceções associadas a 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 na Console, fica abaixo de uma credencial /login funcional. Além disso, uma sessão ativa num gateway de aplicações Claude autenticado fica fora da lista: tem precedência sobre todas as fontes 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, o Claude Code ignora as outras fontes e pede-lhe para iniciar sessão através de /login.

Nenhuma das exceções protege a sua subscrição contra uma chave exportada. Sem um gateway, tudo entre as posições 1 e 5 tem precedência sobre a conta com que iniciou sessão. Assim, uma variável ANTHROPIC_API_KEY exportada em qualquer ponto do ambiente do processo tem precedência, e a sessão fatura uma organização da Console enquanto acredita estar a utilizar o seu plano. Nada está avariado. A ordem está a funcionar conforme documentado, e por isso não é apresentada qualquer advertência.

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

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

Encontrar a chave perdida num servidor

Uma chave exportada pode permanecer em mais locais do que num perfil de shell:

• ~/.bashrc, ~/.bash_profile, ~/.profile ou ~/.zshrc, lidos por cada novo 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 abra hoje pode herdar uma variável que removeu do seu perfil na semana passada, porque o servidor está em execução desde antes dessa alteração.
• Uma imagem de contentor ou a definição de um job de CI, onde a variável é definida fora de qualquer ficheiro que possa ler a partir do 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, para apresentar os nomes das variáveis sem mostrar os valores secretos num ecrã que possa estar a partilhar ou a gravar. O primeiro comando responde à pergunta principal: se indicar que a variável está definida, o próximo claude iniciado a partir deste shell utilizará essa chave. Se os cinco comandos não produzirem saída, não existe nenhuma credencial no ambiente e uma sessão iniciada aqui usará a credencial /login.

Adicione systemctl cat your-unit.service | grep -i environment a qualquer serviço que execute o Claude Code, porque um ficheiro de unidade define o seu próprio ambiente e nunca lê o perfil do 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.

Depois, elimine o export do ficheiro que o definiu. Caso contrário, a próxima shell de login irá repô-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 alteração no sentido inverso, defina ANTHROPIC_API_KEY no ambiente ou execute /login e selecione a conta Console. Para limpar completamente um login guardado, execute /logout. Depois de um início de sessão Console sem chave, /logout remove e revoga a credencial criada por esse início de sessão.

Se /status ainda não corresponder ao que espera, execute claude doctor. O comando lista as entradas de definições que o Claude Code rejeitou. Isto permite detetar um ficheiro de definiçõ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 apresenta um token OAuth com validade de 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 aos 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 é relevante aqui. 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. Essa configuração é uma tarefa separada, explicada em executar o Claude Code com 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 o Claude Code num VPS dentro do tmux aborda a parte da sessão dessa configuração.

Verificar quanto cada credencial consumiu efetivamente

Num login de subscrição, /usage apresenta 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 ao preço de tabela ou, quando um administrador definiu uma tabela modelPricing nas definições geridas, às tarifas contratadas pela sua organização. Nesse caso, a linha Total cost indica-o. Em qualquer dos casos, trate este valor 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 números 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, é provável que uma credencial do ambiente esteja a prevalecer; /status resolve essa questão. A exceção ocorre quando as barras já estão completas: uma sessão de subscrição pode continuar depois de atingir o limite incluído, usando créditos de utilização que a Anthropic fatura às tarifas padrão da API, e as barras permanecem inalteradas. Fora desse caso, barras paradas são o sinal mais claro de que a credencial errada está ativa. acompanhar quanto uma sessão do Claude Code gasta explica como medir isso com mais detalhe. Se as barras avançarem e depois pararem, atingiu antes 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. 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 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 seleciona um perfil Anthropic ou uma credencial de federação. Fora da sessão, verificar se ANTHROPIC_API_KEY está definida na shell indica se existe uma credencial de ambiente que teria prioridade 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 prioridade superior. 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 fornecedor de cloud, de ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper, CLAUDE_CODE_OAUTH_TOKEN e de qualquer perfil Anthropic ou credencial de federação que selecione com ANTHROPIC_PROFILE ou com as variáveis de federação. Apenas um perfil ativo no modo user_oauth fica abaixo dela, e uma sessão iniciada num gateway de aplicações Claude tem prioridade sobre toda a lista. Execute unset ANTHROPIC_API_KEY, inicie uma sessão nova 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 voltará 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 iniciar sessão são uma subscrição Pro ou Max, um lugar Claude for Teams ou Enterprise, uma conta Claude Console, um fornecedor de cloud e um gateway Cloud. Este último é um gateway de aplicações Claude autoalojado, com sessão iniciada através de SSO empresarial por meio de /login. Uma conta gratuita claude.ai não está incluída nessa lista, pelo que não existe uma credencial de subscrição para armazenar. A alternativa paga à subscrição é uma organização Claude Console com crédito de API, faturada por token. Trata-se de uma conta separada, mesmo que utilize 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 contínua 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. Existe apenas uma ligação opcional do plano para a Console: um plano Max ou Team pode enviar os respetivos créditos mensais de API para uma organização Console associada a partir de claude.ai. Esses créditos não cobrem o Claude Code.

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 da sua própria máquina: prima c para copiar o URL, inicie sessão nesse endereço e cole o código novamente no terminal se o browser mostrar um código em vez de redirecionar. Em alternativa, execute claude setup-token numa máquina com browser, 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, Team ou Enterprise e só pode fazer pedidos de modelos. Por isso, um script que utilize --bare precisa de uma chave de API ou de um apiKeyHelper.