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ê | Causa | Correção |
|---|---|---|
| Conexão recusada | Proxy não está em execução ou a porta é diferente | Inicie-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ção | Adicione esse nome a model_list |
| Upstream 401 | UPSTREAM_KEY errada ou vazia | Exporte novamente a chave no shell do proxy e reinicie |
429 com concurrency | Mais de 8 requisições simultâneas (2 na versão de teste) | Reduza os agentes paralelos |
429 com rate_limited | Mais de 300 requisições por minuto (60 no teste) | Reduza a taxa e tente novamente |
429 com Retry-After: 5 | Sobrecarga temporária | Tente novamente após cinco segundos |
| Stream travado | Uma requisição streaming segura sua vaga até o fim | Cancele-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.
