PT ▾

InícioGuia

Configuração do Proxy Claude Code com uma API compatível com OpenAI

Esta configuração de proxy claude code leva cinco etapas: obter uma chave, escrever uma configuração LiteLLM, iniciar o proxy, definir duas variáveis de ambiente e executar um teste. Leva cerca de dez minutos.

Cinco pedras luminosas levando de um terminal a um servidor, mostrando uma configuração de proxy passo a passo

Pontos principais

  1. Execute um proxy LiteLLM local que encaminha para https://api.claudecodeproxyapi.com/v1
  2. Aponte o Claude Code para o proxy com ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN
  3. Mapeie o nome do modelo que o Claude Code envia para o modelo upstream uncensored
  4. Teste o proxy com curl antes de iniciar a CLI

O que você precisa

  • Uma chave de API da página de chaves. Faça cadastro com Google ou e-mail e senha, depois reivindique o crédito de teste de $0,50 com um clique.
  • Python 3.9 ou mais recente, para instalar o proxy.
  • Claude Code instalado e funcionando na sua máquina.

Por que usar um proxy? O Claude Code usa o formato Anthropic Messages, e nossa API usa o formato OpenAI Chat Completions com o ID do modelo uncensored. O proxy traduz entre eles. Se quiser entender o contexto primeiro, leia o guia de solução de problemas do proxy. O modelo é um modelo de pesos abertos, não o Claude, então espere comportamento diferente em tarefas complexas de várias etapas.

Etapa 1: instalar o proxy

Use um ambiente virtual para que as dependências do proxy fiquem separadas dos seus projetos:

python3 -m venv ~/litellm-env
source ~/litellm-env/bin/activate
pip install 'litellm[proxy]'

LiteLLM é um software de código aberto de terceiros. Os comandos e chaves de configuração abaixo correspondem à documentação pública dele no momento da escrita, mas verifique a documentação atual se alguma flag tiver mudado.

Etapa 2: escrever a configuração

Crie config.yaml. O model_name é o nome que o cliente envia. O bloco litellm_params indica para onde encaminhá-lo. O prefixo openai/ diz ao LiteLLM para falar com um servidor compatível com OpenAI.

cat > config.yaml <<'EOF'
model_list:
  - model_name: claude-sonnet
    litellm_params:
      model: openai/uncensored
      api_base: https://api.claudecodeproxyapi.com/v1
      api_key: os.environ/UPSTREAM_KEY
EOF

O alias claude-sonnet é um exemplo, não um requisito. O Claude Code pode enviar vários nomes de modelos diferentes, por exemplo um modelo principal e um menor para tarefas de fundo. Adicione uma entrada model_list para cada nome que você vir no log do proxy, todas apontando para o mesmo upstream. Apontar todos os aliases para uncensored é aceitável, porque há apenas um modelo.

A chave é lida de uma variável de ambiente para que nunca fique em um arquivo que você possa fazer commit.

Etapa 3: iniciar o proxy

export UPSTREAM_KEY="YOUR_KEY"
litellm --config config.yaml --port 4000

Deixe este terminal aberto. Você deve ver o servidor escutando na porta 4000. Agora verifique o caminho upstream do lado do proxy com uma solicitação de teste no formato Anthropic, que é o que o Claude Code enviará:

curl http://localhost:4000/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: sk-local-anything" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet",
    "max_tokens": 200,
    "messages": [{"role": "user", "content": "Reply with the word ready."}]
  }'

Uma resposta JSON cujo conteúdo inclui a palavra "ready" significa que a tradução funciona de ponta a ponta: formato Anthropic para dentro, formato OpenAI para https://api.claudecodeproxyapi.com/v1, e de volta. Se você definir uma chave mestra na configuração LiteLLM, use-a no lugar de sk-local-anything.

Etapa 4: apontar o Claude Code para o proxy

O Claude Code lê seu endereço de API e token de variáveis de ambiente. Defina-os no shell onde você inicia a CLI:

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-local-anything"
export ANTHROPIC_MODEL="claude-sonnet"
claude

Use o endereço do proxy sem o sufixo /v1 aqui, porque a CLI adiciona seu próprio caminho. O token só precisa satisfazer o proxy, já que a chave upstream real é a que você exportou como UPSTREAM_KEY. Se você usar o arquivo de configurações da CLI para valores de ambiente em vez do shell, coloque os mesmos três nomes lá. Os nomes das variáveis de ambiente para o Claude Code podem mudar entre versões, então verifique-os contra a documentação atual do Claude Code se algo for ignorado.

Etapa 5: executar uma primeira tarefa e observar o log

Comece pequeno. Peça à CLI para explicar um arquivo ou adicionar um comentário a uma função. No terminal do proxy, você deve ver uma requisição por etapa. Observe cada nome de modelo que aparecer; se um não estiver na sua model_list, o proxy responderá com um erro, então adicione-o e reinicie.

A chamada de funções é importante aqui, pois a CLI lê arquivos e edita código por meio de ferramentas. A API suporta tools, tool_choice e streaming de tool_calls, e o proxy os converte. A adesão mais fraca a um esquema de ferramenta aparece como uma edição falhada ou uma etapa repetida. Quando isso acontecer, encurte a tarefa e tente novamente antes de decidir que a configuração está quebrada.

A janela de contexto é de 100.000 tokens, prompt e conclusão juntos. Sessões longas que passam por ela falharão, então inicie uma nova sessão para uma nova tarefa. Os custos são mínimos em $0,15 por 1M de tokens de entrada e $0,50 por 1M de tokens de saída: uma solicitação com 20.000 tokens de entrada e 800 de saída custa $0,003 + $0,0004 = $0,0034. Veja a página de preços para recargas, que neste site são pagas por cripto (USDT na TRC20, USDC na Base).

Solução de Problemas

O que você vêCausaCorreção
Conexão recusadaProxy não está em execução ou a porta é diferenteInicie-o e use a mesma porta em ANTHROPIC_BASE_URL
Proxy 404 ou "model not found"O nome do modelo enviado pela CLI não está na configuraçãoAdicione esse nome a model_list
Upstream 401UPSTREAM_KEY errada ou vaziaExporte novamente a chave no shell do proxy e reinicie
429 com concurrencyMais de 8 requisições simultâneas (2 na versão de teste)Reduza os agentes paralelos
429 com rate_limitedMais de 300 requisições por minuto (60 no teste)Reduza a taxa e tente novamente
429 com Retry-After: 5Sobrecarga temporáriaTente novamente após cinco segundos
Stream travadoUma requisição streaming segura sua vaga até o fimCancele-a na CLI para liberar a vaga

Para qualquer coisa não coberta aqui, inclua o cabeçalho de resposta X-Request-Id ao entrar em contato com o suporte. A documentação lista todos os parâmetros suportados.

Tornar permanente

Definir variáveis de ambiente toda vez cansa. Coloque o comando de inicialização do proxy em um pequeno script e as variáveis do cliente em um alias, para que um único comando inicie tudo:

cat > ~/start-proxy.sh <<'EOF'
. ~/litellm-env/bin/activate
export UPSTREAM_KEY="YOUR_KEY"
exec litellm --config ~/config.yaml --port 4000
EOF
chmod +x ~/start-proxy.sh

alias claude-uncensored='ANTHROPIC_BASE_URL=http://localhost:4000 ANTHROPIC_AUTH_TOKEN=sk-local-anything ANTHROPIC_MODEL=claude-sonnet claude'

Como as variáveis são definidas apenas para esse comando único, seu comando claude normal continua funcionando com suas configurações padrão. Adicione o alias ao seu perfil de shell. Proteja o script com permissões de arquivo como chmod 700, pois ele contém sua chave.

Voltando atrás

Se você exportou as variáveis no shell atual, execute unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_MODEL e inicie a CLI novamente. Nada muda no lado da API, então não há nada a desfazer.

Acompanhe seu saldo e gastos

Cada resposta da API inclui X-Balance-USD, o crédito restante na sua chave. O LiteLLM pode repassar cabeçalhos upstream em algumas configurações, mas a maneira mais segura de ver seu saldo é chamar o upstream diretamente de vez em quando:

curl -i https://api.claudecodeproxyapi.com/v1/models \
  -H "Authorization: Bearer YOUR_KEY" | grep -i x-balance-usd

Sessões de agente crescem silenciosamente. Cada etapa reenvia o contexto de trabalho, então uma sessão longa custa mais por solicitação do que uma curta. Iniciar uma nova sessão para cada tarefa mantém a entrada pequena e a conta baixa. Nos preços publicados ($0,15 por 1M de entrada e $0,50 por 1M de saída), uma solicitação com 50.000 tokens de entrada e 1.000 de saída custa 50.000 x $0,15 / 1M = $0,0075 mais $0,0005, que é $0,008. Vinte dessas solicitações totalizam $0,16.

Recargas variam de $20 a $500 em valores inteiros e são pagas em USDT na TRC20 ou USDC na Base neste site. O crédito nunca expira, então uma recarga maior com o bônus de +5%, +10% ou +15% não coloca um prazo de validade no seu saldo.

Perguntas e respostas

Quais variáveis de ambiente o Claude Code precisa para um proxy?

ANTHROPIC_BASE_URL para o endereço do proxy e ANTHROPIC_AUTH_TOKEN para um token que o proxy aceita. ANTHROPIC_MODEL pode nomear o alias que você definiu. Verifique a documentação atual do Claude Code para alterações.

Devo colocar /v1 no ANTHROPIC_BASE_URL?

Não. Use o endereço do proxy, como http://localhost:4000, porque a CLI adiciona seu próprio caminho. O /v1 fica apenas no upstream api_base na configuração do proxy.

Posso usar um proxy diferente do LiteLLM?

Sim. Qualquer proxy que converta requisições Anthropic Messages para OpenAI Chat Completions funciona, por exemplo, claude-code-router. Aponte seu upstream para https://api.claudecodeproxyapi.com/v1 com o modelo uncensored.

Minha chave upstream está segura na configuração?

Mantenha-a em uma variável de ambiente em vez do arquivo, conforme mostrado na configuração acima. Não faça commit da chave em um repositório.

Sua chave está a um formulário de distância

Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.