Claude Code with a relay service: full configuration and troubleshooting

What you are actually configuring

Claude Code talks to an Anthropic-compatible endpoint. Pointing it at a relay service means changing which address it talks to and which credential it presents. That is the whole job — there is no plugin, no wrapper, no patched build.

Two values:

ANTHROPIC_BASE_URL=https://the-endpoint-your-service-provides
ANTHROPIC_AUTH_TOKEN=the-key-your-service-provides

The relay service gives you both. If the service does not state a Claude Code-compatible endpoint explicitly, ask before paying — some proxies are chat-only.

Where to put them

On Windows, in PowerShell (persisted for your user account):

[Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL','https://...','User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_AUTH_TOKEN','sk-...','User')

Then open a new terminal. Environment variable changes do not apply to terminals that are already open — this catches almost everyone once.

On macOS or Linux, in your shell profile:

export ANTHROPIC_BASE_URL="https://..."
export ANTHROPIC_AUTH_TOKEN="sk-..."

Off the command line entirely, if you prefer not to persist secrets:

ANTHROPIC_BASE_URL="https://..." ANTHROPIC_AUTH_TOKEN="sk-..." claude

Confirm it worked before you do anything else

Do not start with a real task. Ask for something trivial and see whether it answers. If it does, the endpoint and credential are both good, and any later problem is something else.

A quick way to check the endpoint independently of the client:

curl -s -H "Authorization: Bearer sk-..." https://your-endpoint/v1/models

A list of models means the endpoint and key work. A 401 means the key is wrong. A 404 usually means the path is wrong.

The five failures that cover almost everything

One: it answers but never edits files

Symptom: Claude Code responds in text, describes what it would do, and never calls a tool. Files are never modified.

Cause: the relay proxies the chat endpoint but does not forward tool use. This is the single most common problem with relay services and it is a property of the service, not your configuration.

What to do: verify by asking it to read a specific file. If it cannot, the endpoint does not support tool use. Switch services. There is no client-side workaround.

Two: 401 or authentication errors

Symptom: immediate rejection on every request.

Cause, in order of likelihood: the key was pasted with a trailing space or newline; the variable name is wrong (ANTHROPIC_API_KEY versus ANTHROPIC_AUTH_TOKEN — different clients want different ones); the terminal was not restarted; the key has expired or been rotated.

What to do: check the variable name first. It is the most common cause and the least likely to be suspected.

Three: it works for chat but long tasks fail

Symptom: short interactions are fine, but anything with a large context fails or times out.

Cause: the request is exceeding a context or request-size limit somewhere in the chain. Relay services often impose smaller limits than the vendor does.

What to do: confirm the limit with the service, and check whether a proxy or VPN in your path is truncating requests.

Four: tool calls arrive mangled

Symptom: Claude Code does call tools, but arguments are malformed or the result is not parsed.

Cause: the relay is reshaping the request or response body — usually translating between API versions or normalising the format. Small differences in how tool call arguments are serialised break the client.

What to do: check whether the service documents a specific API version, and try it. If the problem persists, it is the proxy's formatting and switching services is the fix.

Five: intermittent failures under load

Symptom: fine one at a time, errors when running longer sessions or parallel tasks.

Cause: the concurrency cap on your tier, or a shared upstream channel.

What to do: check the documented concurrency limit and stay clearly under it. If a single session fails, look at whether the service's own status page reports anything.

A working checklist

[ ] base_url and key both set, terminal restarted
[ ] trivial request answered
[ ] /v1/models returns a list via curl
[ ] a tool call comes back (the decisive test)
[ ] a multi-file task completes
[ ] failure rate under sustained use is acceptable

Security notes worth two minutes

Treat the key as a credential. Do not commit it, do not paste it into a shared config file, and remember that in a relay setup the operator can see your traffic.

Do not send sensitive content through a relay you have not vetted. If prompts contain customer data or internal identifiers, that is a data boundary question, not a configuration one.

Prefer a service that reports usage faithfully. You will want the token breakdown when the bill arrives, and a service that blends everything into one number makes that impossible.

Related reading

• Three ways to reach Claude from mainland China: official, relay, mirror (guides)
• Give a relay service a health check: a 20-minute verification checklist (guides)
• Account throttled or banned: the common triggers for relay service risk controls (guides)