Configurar o Claude Code

A CLI da Anthropic no endpoint da OneProvider. A configuração se resume a duas variáveis de ambiente e uma chamada de teste.

Instalação

curl -fsSL https://claude.ai/install.sh | bash
# or:
brew install --cask claude-code

Opção 1: variáveis de ambiente (sessão atual)

O caminho mais rápido é definir as variáveis só no terminal atual. Elas não persistem entre sessões — veja “Tornar permanente” no fim da página se quiser que sobrevivam a uma reinicialização.

export ANTHROPIC_BASE_URL=https://api.oneprovider.dev
export ANTHROPIC_AUTH_TOKEN=sk-your-key-here

Opção 2: configurações permanentes

O Claude Code lê as configurações do usuário em settings.json. O modelo padrão e os aliases das famílias abaixo vêm dos modelos ativos do catálogo no momento.

Caminho do arquivo: ~/.claude/settings.json

{
"env": {
"ANTHROPIC_BASE_URL": "https://api.oneprovider.dev",
"ANTHROPIC_AUTH_TOKEN": "sk-your-key-here",
"ANTHROPIC_MODEL": "claude-sonnet-5-5",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5"
},
"model": "claude-sonnet-5-5"
}

Verificação

claude -p "say hi in one sentence"

Você deve ver uma resposta de uma frase em um ou dois segundos. Se aparecer 401, a chave está errada; 400 invalid_request_error significa que o nome do modelo não bate com a lista canônica (a resposta lista os IDs compatíveis).

Problemas comuns

# validate the file
jq . ~/.claude/settings.json
# auto-replace smart quotes with ASCII
sed -i.bak $'s/[\u201c\u201d]/"/g' ~/.claude/settings.json

A lista completa de sintomas → causas → correções dos erros 400 / 401 / 403 / 404 / 429 / 503 / 504 está na página Solução de problemas .

Uso de ferramentas

O Claude Code usa o esquema de ferramentas nativo da Anthropic. A API aceita todos os nomes de ferramenta (Read, Write, Edit, Bash, Grep, Glob, TodoWrite etc.) com tool_choice: auto — que é o que a CLI envia por padrão. Não é preciso o header anthropic-beta.

Se o seu orquestrador próprio define tool_choice: {"type": "any"} ou tool_choice: {"type": "tool", "name": "X"}, a API converte isso para auto + uma dica no prompt de sistema. Veja Uso de ferramentas para a tabela completa.

Tornar permanente

Quando tudo estiver funcionando e você quiser que as variáveis sobrevivam entre sessões de terminal, adicione-as ao rc-file do seu shell (macOS / Linux) ou ao registro de variáveis de ambiente do usuário (Windows). Os novos terminais vão carregá-las automaticamente.

# append to ~/.zshrc (default macOS shell)
cat >> ~/.zshrc <<'EOF'
export ANTHROPIC_BASE_URL=https://api.oneprovider.dev
export ANTHROPIC_AUTH_TOKEN=sk-your-key-here
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
EOF
# apply to the current session:
source ~/.zshrc

Qual modelo escolher

O Claude Code fala o protocolo da Anthropic, então funciona melhor com a família Claude. Use claude-sonnet-5-5 como padrão do dia a dia: preço e qualidade equilibrados para edições, testes e explicações. Troque para claude-opus-5-5 em decisões de arquitetura, refatorações grandes e bugs que você não consegue isolar; ele custa mais por token. Use claude-haiku-5-5 para perguntas rápidas, mensagens de commit e tarefas em segundo plano em que a velocidade importa mais que a profundidade. Dentro de uma sessão, execute /model para trocar, ou comece com claude --model claude-opus-5-5. As configurações acima ligam os aliases sonnet, opus e haiku a esses IDs. Os IDs atuais estão na página de modelos e os valores na página de preços . Os preços são por milhão de tokens, então defina um limite de gastos na chave e acompanhe o Consumo no seu Dashboard.

Erros comuns e soluções

claude: command not found depois da instalação

Abra um novo terminal primeiro: o instalador coloca o binário em ~/.local/bin. Se ele continuar sumido, adicione-o com export PATH="$HOME/.local/bin:$PATH" no rc-file do seu shell. Com o Homebrew, confira se o brew install --cask claude-code terminou sem erros.

400 invalid_request_error sobre o modelo

O ID do modelo não está no catálogo, em geral um alias antigo como claude-3-5-sonnet. Defina ANTHROPIC_MODEL e as três variáveis ANTHROPIC_DEFAULT_*_MODEL como no settings.json acima, ou liste os IDs válidos com curl -s https://api.oneprovider.dev/v1/models -H "x-api-key: $KEY".

404 ou “The requested API endpoint does not exist”

ANTHROPIC_BASE_URL deve ser exatamente https://api.oneprovider.dev: sem /v1 e sem /v1/messages no final. O Claude Code acrescenta o caminho sozinho.

429 “Insufficient balance on this API key”

O saldo do painel ou o limite de gastos da chave acabou. Tentar de novo não resolve: recarregue o saldo ou aumente o limite no painel e envie a requisição outra vez.

A resposta para no meio ou a conexão é reiniciada

Desligue qualquer VPN ou proxy VLESS: eles seguram o streaming em buffer e quebram o HTTP/2. A OneProvider não bloqueia por região e não segura streams em buffer. Uma requisição precisa começar a responder em até 6 minutos e tem o teto de 10 minutos no total, veja os códigos de erro .

Mudei o settings.json, mas nada mudou

O Claude Code lê o bloco env ao iniciar, então feche e abra o claude de novo. Deixe as variáveis em ~/.claude/settings.json ou no seu shell: o .claude/settings.json de um projeto é lido depois da configuração da primeira execução e pode ser tarde demais.

Perguntas frequentes

Preciso de uma conta ou assinatura do Claude?

Não. A chave da OneProvider basta. O Claude Code nunca precisa fazer login no claude.ai; se ele mostrar uma tela de login, siga os passos de Auth conflict acima.

Dá para usar o GPT ou outros modelos no Claude Code?

O Claude Code envia requisições Messages da Anthropic, então use IDs Claude nele. Para modelos GPT use o Codex , o Cursor ou o Cline .

Como volto para o meu login da Anthropic?

Apague do bloco env do settings.json e do rc-file do seu shell as variáveis ANTHROPIC_* que você definiu acima, abra um novo terminal e execute /login.

Onde vejo quanto uma sessão custou?

Na página Consumo do Dashboard da chave: cada requisição com o modelo e a contagem de tokens. Um limite de gastos por chave segura um agente descontrolado.

Funciona no Windows?

Sim. Escolha Windows no seletor de sistema operacional no topo: as mesmas duas variáveis são definidas pelo PowerShell, e o settings.json fica no seu perfil de usuário, na pasta .claude.

A extensão Claude Code do VS Code é a mesma coisa?

Ela usa o mesmo arquivo de configurações. Veja o Claude Code no VS Code .

Respostas rápidas

Qual base URL devo usar?

O Claude Code e os SDKs da Anthropic usam https://api.oneprovider.dev. Os SDKs da OpenAI e os clientes compatíveis com a OpenAI usam https://api.oneprovider.dev/v1. Uma única chave funciona nos dois; a lista de modelos está na página de modelos e os preços, na página de preços .

Como me autentico?

Envie a chave sk-… pura em x-api-key ou em Authorization: Bearer: um dos dois, nunca ambos. Guarde a chave em uma variável de ambiente, não em um arquivo que vai para o commit. Mais sobre autenticação .

Onde consigo uma chave?

Abra o seu painel no bot do Telegram @oneprovider_robot ou em app.oneprovider.dev, recarregue o saldo e toque em “Emitir chave”. Cada chave pode ter o seu próprio limite de gastos. Painel e chaves de API .

O que significam 401, 404 e 429?

401: a chave está ausente, foi digitada errado ou enviada no cabeçalho errado; cole a chave inteira, sem aspas nem espaços. 404: em geral, uma base URL errada, por exemplo um /v1 ausente ou duplicado. 429 com “Insufficient balance”: o saldo do painel ou o limite de gastos da chave acabou, então recarregue em vez de tentar de novo; qualquer outro 429 é um limite de requisições, então aguarde o tempo de Retry-After. Detalhes: códigos de erro e solução de problemas .

Por que os streams são cortados ou reiniciados?

VPNs e proxies VLESS costumam armazenar SSE em buffer ou quebrar a negociação do HTTP/2. A OneProvider não tem restrições regionais e não armazena streams em buffer; desative o proxy e tente de novo.

Onde pergunto se isso não bastar?

Escreva para @Oneproviderhelpbot no Telegram ou abra “Suporte” no painel web, informando o código de status HTTP e a mensagem de erro exata. Como funciona o suporte .