Configuração de Coding Agents

Instalação do Claude Code, API Key, Base URL e modelos

Conecte o Claude Code com BetterToken API Key, Base URL e Model ID. Defina o modelo antes de iniciar ou altere com /model durante a sessão.

Conecte o Claude Code com sua BetterToken API Key, a Base URL https://bettertoken.ai e o Model ID escolhido. Copie o Model ID exato da model plaza.

Configurações principais

Campo	Valor
API Key	BetterToken API Key
Base URL	`https://bettertoken.ai`
Model	`YOUR_MODEL_ID`

Pré-requisitos

Instale o Claude Code
Instale Node.js se usar o script de configuração automática BetterToken; a instalação por npm requer Node.js 22 ou posterior
Crie e copie uma BetterToken API Key

Cadastre-se e obtenha uma BetterToken API Key

Já tem uma conta? Entre, recarregue o saldo e crie uma chave no console.

Instalação

A Anthropic recomenda o instalador nativo, que não requer Node.js. Se preferir npm, instale Node.js 22 ou posterior e execute:

npm install -g @anthropic-ai/claude-code

Configuração pela linha de comando

O script de configuração automática do BetterToken grava a configuração do provedor para o Claude Code. Ele exige Node.js e solicita a API Key quando ela não é informada como argumento.

macOS / Linux

curl -fsSL "https://bettertoken.ai/install-claudecode-provider.sh" | bash

Windows

iwr "https://bettertoken.ai/install-claudecode-provider.ps1" -OutFile "$env:TEMP\install-claudecode-provider.ps1"; powershell -ExecutionPolicy Bypass -File "$env:TEMP\install-claudecode-provider.ps1"

Quando o script terminar, verifique ~/.claude/settings.json (ou %USERPROFILE%\.claude\settings.json no Windows) e reinicie completamente o Claude Code. Use a configuração manual abaixo se quiser controlar cada campo.

Configuração manual

Sistema	Arquivo
macOS / Linux	`~/.claude/settings.json`
Windows	`%USERPROFILE%\.claude\settings.json`

Copie o Model ID exato da model plaza.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://bettertoken.ai",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "API_TIMEOUT_MS": "3000000",
    "ANTHROPIC_MODEL": "YOUR_MODEL_ID",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "YOUR_MODEL_ID",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "YOUR_MODEL_ID",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "YOUR_MODEL_ID"
  }
}

Substitua YOUR_MODEL_ID pelo ID copiado. ANTHROPIC_MODEL define o modelo principal e as três variáveis ANTHROPIC_DEFAULT_*_MODEL definem os aliases Haiku, Sonnet e Opus. Use o mesmo modelo ou um diferente para cada função.

Os exemplos incluem a configuração opcional CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1. Ela desativa atualizações automáticas, relatórios de erros, algumas verificações de disponibilidade e recursos de conta; a autenticação não depende dela. Para atualizar manualmente, execute claude update ou use o gerenciador de pacotes que controla a instalação. Consulte as instruções de atualização e os efeitos da configuração.

Extensão do VS Code

A extensão usa o arquivo settings.json do VS Code. Adicione uma configuração claudeCode.environmentVariables separada:

{
  "claudeCode.environmentVariables": [
    {
      "name": "ANTHROPIC_BASE_URL",
      "value": "https://bettertoken.ai"
    },
    {
      "name": "ANTHROPIC_AUTH_TOKEN",
      "value": "YOUR_API_KEY"
    },
    {
      "name": "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC",
      "value": "1"
    },
    {
      "name": "API_TIMEOUT_MS",
      "value": "3000000"
    },
    {
      "name": "ANTHROPIC_MODEL",
      "value": "YOUR_MODEL_ID"
    },
    {
      "name": "ANTHROPIC_DEFAULT_HAIKU_MODEL",
      "value": "YOUR_MODEL_ID"
    },
    {
      "name": "ANTHROPIC_DEFAULT_SONNET_MODEL",
      "value": "YOUR_MODEL_ID"
    },
    {
      "name": "ANTHROPIC_DEFAULT_OPUS_MODEL",
      "value": "YOUR_MODEL_ID"
    }
  ]
}

Verificar a conexão

Inicie o Claude Code no seu projeto:

claude

Envie uma mensagem curta. Uma resposta normal sem erros 401, de conexão ou de modelo confirma a configuração. Na sessão interativa, execute /status e verifique duas linhas:

Anthropic base URL deve mostrar a Base URL do BetterToken: https://bettertoken.ai. Se a linha não aparecer, a variável não chegou à sessão atual. Verifique o caminho de settings.json e reinicie completamente o Claude Code.
A linha de autenticação deve mostrar ANTHROPIC_AUTH_TOKEN, em vez de um login com uma conta claude.ai.

Para verificar a conexão por um script, envie um prompt curto:

claude -p "Reply with only: OK"

Uma resposta normal com OK confirma que a conexão funciona.

As credenciais nas variáveis de ambiente têm prioridade sobre um login salvo do claude.ai. Se aparecer um aviso sobre duas fontes de credenciais ao iniciar, remova uma delas. Para manter apenas sua BetterToken API Key, execute /logout. Se o seu interpretador de comandos também definir ANTHROPIC_API_KEY, remova essa variável primeiro.

Trocar de modelo

Atualize o Model ID na configuração e reinicie o Claude Code. Para trocar durante a sessão, use /model YOUR_MODEL_ID.

Para outros aliases, como fable com ANTHROPIC_DEFAULT_FABLE_MODEL, siga o mapeamento oficial de aliases e use um Model ID disponível. Se o Claude Code presumir uma janela de contexto incorreta para um ID personalizado, siga as orientações para a janela de modelos personalizados usando o limite confirmado do modelo.

Mostrar modelos do BetterToken em /model (opcional)

Use uma versão recente do Claude Code. Adicione "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1" ao bloco env existente em ~/.claude/settings.json e reinicie completamente o Claude Code. Ao iniciar, o Claude Code consulta /v1/models em https://bettertoken.ai para obter os modelos disponíveis. Consulte o guia oficial de configuração de gateways.

Para confirmar a descoberta de modelos, inicie claude --debug e procure as linhas com [gatewayDiscovery] em ~/.claude/debug/<session-id>.txt. Uma linha indicando que os modelos foram armazenados em cache confirma que a descoberta funcionou.

O Claude Code lista apenas os modelos do gateway cujo Model ID contém claude ou anthropic (sem diferenciar maiúsculas de minúsculas), conforme seu protocolo de gateway. Os demais modelos retornados por /v1/models, incluindo os GPT, não aparecem em /model, mesmo que o BetterToken os ofereça. O Claude Code ainda pode chamar esses modelos se você definir seu Model ID diretamente; nos testes com Claude Code 2.1.309, um modelo GPT especificado dessa forma respondeu a solicitações de texto e de leitura de arquivos por meio de Anthropic Messages.

Erros comuns

Erro	Solução
`401` ou falha de autenticação	Verifique `ANTHROPIC_AUTH_TOKEN` e remova espaços ao redor da API Key.
`ConnectionRefused`	Use exatamente `https://bettertoken.ai`; não acrescente `/v1`.
Model ID	Confira o Model ID exato na model plaza e informe-o nas configurações de modelo do cliente.
A configuração não foi aplicada	Verifique o caminho do arquivo, remova variáveis de ambiente conflitantes e reinicie completamente o Claude Code.
Aviso sobre duas fontes de credenciais conflitantes ao iniciar	Remova uma das fontes ou execute `/logout`.
Erro de certificado / TLS, comum com um proxy corporativo	Defina `NODE_EXTRA_CA_CERTS` com o caminho do arquivo do certificado da CA e reinicie o Claude Code.
`400` mencionando um campo não reconhecido, como `Extra inputs are not permitted`	Adicione `"CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"` a `env` e reinicie completamente o Claude Code. Se o erro persistir, entre em contato com o suporte.
Contexto longo demais durante uma sessão extensa	Execute `/compact` para compactar a sessão.

Recursos indisponíveis com uma API Key

O controle remoto (Remote Control) e a entrada de voz exigem login com uma conta claude.ai. Eles ficam indisponíveis ao usar uma BetterToken API Key e uma Base URL personalizada. Essa é uma limitação do cliente Claude Code e não afeta as conversas normais de programação.

Configuração avançada

Para gerenciar várias configurações em um aplicativo, consulte CC Switch.

Perguntas relacionadas

Detalhes técnicos

Protocolo e endpoint

O Claude Code usa Anthropic Messages. Defina ANTHROPIC_BASE_URL como https://bettertoken.ai; o cliente acrescenta /v1/messages, portanto não adicione /v1 à Base URL.