EN ▾

HomeGuide

Claude Code Proxy Setup With an OpenAI-Compatible API

This claude code proxy setup takes five steps: get a key, write a LiteLLM config, start the proxy, set two environment variables and run a test. It takes about ten minutes.

Five glowing stepping stones leading from a terminal to a server, showing a step-by-step proxy setup

Key points

  1. Run a local LiteLLM proxy that forwards to https://api.claudecodeproxyapi.com/v1
  2. Point Claude Code at the proxy with ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN
  3. Map the model name Claude Code sends to the upstream model uncensored
  4. Test the proxy with curl before starting the CLI

What you need

  • An API key from the key page. Sign up with Google or email and password, then claim the $0.50 trial credit with one click.
  • Python 3.9 or newer, to install the proxy.
  • Claude Code installed and working on your machine.

Why a proxy at all? Claude Code speaks Anthropic's Messages format, and our API speaks OpenAI's Chat Completions format with model ID uncensored. The proxy translates between them. If you want the background first, read the proxy troubleshooting guide. The model is an open-weight model, not Claude, so expect different behaviour on hard multi-step tasks.

Step 1: install the proxy

Use a virtual environment so the proxy's dependencies stay apart from your projects:

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

LiteLLM is third-party open-source software. The commands and config keys below match its public docs at the time of writing, but check its current documentation if a flag has changed.

Step 2: write the config

Create config.yaml. The model_name is the name the client sends. The litellm_params block says where to forward it. The openai/ prefix tells LiteLLM to talk to an OpenAI-compatible server.

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

The alias claude-sonnet is an example, not a requirement. Claude Code may send several different model names, for instance a main model and a smaller one for background tasks. Add one model_list entry per name you see in the proxy log, all pointing to the same upstream. Pointing every alias at uncensored is fine, because there is only one model.

The key is read from an environment variable so it never lands in a file you might commit.

Step 3: start the proxy

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

Leave this terminal open. You should see the server listening on port 4000. Now check the upstream path from the proxy's side with a test request in the Anthropic format, which is what Claude Code will send:

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."}]
  }'

A JSON reply whose content includes the word "ready" means the translation works end to end: Anthropic format in, OpenAI format to https://api.claudecodeproxyapi.com/v1, and back. If you set a master key in the LiteLLM config, use it in place of sk-local-anything.

Step 4: point Claude Code at the proxy

Claude Code reads its API address and token from environment variables. Set them in the shell where you start the CLI:

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

Use the proxy's address without a /v1 suffix here, because the CLI adds its own path. The token only has to satisfy the proxy, since the real upstream key is the one you exported as UPSTREAM_KEY. If you use the CLI's settings file for environment values instead of the shell, put the same three names there. Environment variable names for Claude Code can change between releases, so verify them against the current Claude Code docs if something is ignored.

Step 5: run a first task and watch the log

Start small. Ask the CLI to explain one file or to add a comment to a function. In the proxy terminal you should see a request per step. Note each model name that appears; if one is not in your model_list, the proxy answers with an error, so add it and restart.

Tool calling matters here, since the CLI reads files and edits code through tools. The API supports tools, tool_choice and streamed tool_calls, and the proxy converts them. Weaker adherence to a tool schema shows up as a failed edit or a repeated step. When that happens, shorten the task and try again before deciding the setup is broken.

The context window is 100,000 tokens, prompt and completion together. Long sessions that go past it will fail, so start a fresh session for a new task. Costs are tiny at $0.15 per 1M input tokens and $0.50 per 1M output tokens: a request with 20,000 tokens in and 800 out costs $0.003 + $0.0004 = $0.0034. See the pricing page for top-ups, which on this site are paid by crypto (USDT on TRC20, USDC on Base).

Troubleshooting

What you seeCauseFix
Connection refusedProxy is not running or port differsStart it and match the port in ANTHROPIC_BASE_URL
Proxy 404 or "model not found"The model name the CLI sent is not in the configAdd that name to model_list
Upstream 401Wrong or empty UPSTREAM_KEYRe-export the key in the proxy's shell and restart
429 with concurrencyMore than 8 parallel requests (2 on trial)Reduce parallel agents
429 with rate_limitedOver 300 requests per minute (60 on trial)Back off and retry
429 with Retry-After: 5Temporary overloadRetry after five seconds
Stalled streamA streamed request holds its slot until it endsCancel it in the CLI to free the slot

For anything not covered here, include the X-Request-Id response header when you write to support. The docs list every supported parameter.

Make it permanent

Typing exports each time gets old. Put the proxy start-up in a small script and the client variables in an alias, so one command brings everything up:

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'

Because the variables are set only for that one command, your normal claude command keeps working against its default settings. Add the alias to your shell profile. Protect the script with file permissions such as chmod 700, since it holds your key.

Switching back

If you exported the variables in the current shell, run unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_MODEL and start the CLI again. Nothing is changed on the API side, so there is nothing to undo.

Watching your balance and spend

Every response from the API carries X-Balance-USD, the credit left on your key. LiteLLM can pass upstream headers through in some setups, but the surest way to see your balance is to call the upstream directly now and then:

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

Agent sessions grow quietly. Each step resends the working context, so a long session costs more per request than a short one. Starting a fresh session for each task keeps the input small and the bill low. At the published prices ($0.15 per 1M input and $0.50 per 1M output), a request with 50,000 tokens in and 1,000 out costs 50,000 x $0.15 / 1M = $0.0075 plus $0.0005, which is $0.008. Twenty such requests come to $0.16.

Top-ups run from $20 to $500 in whole amounts and are paid by crypto (USDT on TRC20, USDC on Base) on this site. The credit never expires, so a larger top-up with the +5%, +10% or +15% bonus does not put a clock on your balance.

Questions and answers

Which environment variables does Claude Code need for a proxy?

ANTHROPIC_BASE_URL for the proxy address and ANTHROPIC_AUTH_TOKEN for a token the proxy accepts. ANTHROPIC_MODEL can name the alias you defined. Check the current Claude Code docs for changes.

Do I put /v1 on ANTHROPIC_BASE_URL?

No. Use the proxy address such as http://localhost:4000, because the CLI appends its own path. The /v1 belongs only on the upstream api_base in the proxy config.

Can I use a proxy other than LiteLLM?

Yes. Any proxy that converts Anthropic Messages requests to OpenAI Chat Completions works, for example claude-code-router. Point its upstream at https://api.claudecodeproxyapi.com/v1 with model uncensored.

Is my upstream key safe in the config?

Keep it in an environment variable instead of the file, as shown in the config above. Do not commit the key to a repository.

Your key is one form away

Create an account, copy the key, change the base URL. That is the whole setup.