Claude Code throws ERR_BAD_REQUEST against api.anthropic.com from China. Here is the actual fix.

What ERR_BAD_REQUEST actually means here

Claude Code is a TypeScript program. Its HTTP client is axios. ERR_BAD_REQUEST is not an HTTP status code; it is an axios-internal error code that fires when the request fails on the client side before a clean response can be parsed. There are two common ways to land in this bucket from China:

• The target host does not resolve or refuses the TLS handshake. api.anthropic.com from inside the GFW is unreachable at the network layer; the SDK tries to dial and the connection never opens cleanly, so axios surfaces it as a bad-request-shaped failure rather than a real HTTP error.
• The destination URL fails to parse. If ANTHROPIC_BASE_URL is set but malformed (missing the scheme, stray characters, a port without a host), Node's URL constructor throws and the SDK surfaces it as a request error. This is the silent killer covered in the third section.

The message text varies between SDK versions. What it usually looks like:

The five-line fix, with the schemes written in

The cleanest place to land the variables is ~/.claude/settings.json under the env key. That file is read every time claude starts and applied on top of the inherited shell environment, so you do not have to remember which terminal you exported the value in. Pick one of the three gateways below and paste the URL exactly as written:

// ~/.claude/settings.json
{
  "hasCompletedOnboarding": true,
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_GATEWAY_TOKEN"
  }
}

Or the equivalent shell export, if you would rather keep your config out of a file:

# zsh or bash, before launching claude
export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic"
export ANTHROPIC_AUTH_TOKEN="YOUR_GATEWAY_TOKEN"
claude

The three URLs people actually use from inside China, with the path segments that matter:

None of these are Anthropic. They are gateways that accept POST requests in the Anthropic Messages API shape and translate to the provider's own models on the server side. The model name Claude Code sends gets remapped on the gateway side; the agent loop, the tool surface, and the streaming semantics are unchanged because they are part of the protocol, not the model.

Trap 1: the missing scheme that silently bricks every query

If you paste a gateway URL without the https:// prefix, the Anthropic SDK cannot parse it as an absolute URL and every chat throws API Error: Invalid URL. There is no log line that says you typed the URL wrong. In an interactive shell it can look like the agent has frozen; in a wrapped chat the retry-with-resume path can swallow the error into an empty turn so you see nothing at all.

// Custom API endpoint (allows proxying through Copilot, corporate gateways, etc.)
// Only forward it when it's an absolute http(s) URL with a host. A malformed value
// (missing scheme, "localhost:8766", stray text) otherwise lands in ANTHROPIC_BASE_URL
// and makes the Anthropic SDK throw "API Error: Invalid URL" on every query, silently
// bricking built-in chat (the retry-with-resume path can even swallow it into an empty
// turn so the user sees no error at all). Falling back to the default keeps chat working.
if let customEndpoint = defaults.string(forKey: "customApiEndpoint")?
  .trimmingCharacters(in: .whitespacesAndNewlines), !customEndpoint.isEmpty {
  if let url = URL(string: customEndpoint),
    let scheme = url.scheme?.lowercased(), scheme == "http" || scheme == "https",
    let host = url.host, !host.isEmpty {
    env["ANTHROPIC_BASE_URL"] = customEndpoint
  } else {
    log("ACPBridge: ignoring malformed customApiEndpoint ...")
  }
}

Trap 2: the onboarding ping that bypasses the variable on first launch

This one is the genuinely surprising bug. Claude Code's interactive mode does one direct HTTPS call to api.anthropic.com on startup if hasCompletedOnboarding is not already true in your local settings. The call happens before ANTHROPIC_BASE_URL is consulted. From inside the GFW that initial check times out, the process exits, and you see ERR_BAD_REQUEST or a sibling axios code with no clear pointer to the onboarding step. The two issue threads that track this are anthropics/claude-code#36998 and #26935.

The workaround is to write the onboarding flag in by hand before the first launch:

// ~/.claude/settings.json - write this BEFORE the first `claude` run
{
  "hasCompletedOnboarding": true,
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_GATEWAY_TOKEN"
  }
}

With the flag set the process skips the initial probe, lands on the gateway you configured, and the first query succeeds. Until the upstream issues close, this is the standard procedure for any blocked network: VPN-free China, restrictive corporate egress, air-gapped regional environments, anywhere the public Anthropic endpoint is unreachable at the network layer.

Trap 3: the variable is read once, and only once

Environment variables are copied into a process at the moment it is spawned. From there the process holds its own private snapshot. Editing your shell profile, exporting a new value in another terminal, or rewriting settings.json does not reach into a running process. Claude Code reads ANTHROPIC_BASE_URL at startup and keeps that value until it exits. A change only takes effect on the next launch.

For the bare CLI this is mild: quit and relaunch. For long-lived wrappers it is the whole design problem; the host has to tear down and respawn the child. Here is the sequence, including the step where an edit silently does nothing:

The red message is the one that costs people an afternoon. There is no error, no warning, no log line. The edit lands in a file or a shell, the running process keeps its old snapshot, and the only signal you get is that traffic is still hitting the host you thought you changed.

Verify the fix before you trust the chat

The three checks below are the ones I run before I close the laptop. The order matters because each one rules out a different failure mode: env not present, env present but parsed wrong, env present and parsed but ignored by a stale onboarding probe.

When a wrapper is doing the variable for you

If you are running the Claude Code agent loop through a desktop wrapper, the same three traps still apply, they are just hidden behind a settings pane. The wrapper needs to do four things or it has the same failure modes as the CLI:

• Validate the URL at the moment you save the setting so a paste without a scheme is rejected, not silently forwarded.
• Inject the value into the child process at spawn, not into the wrapper's own environment, since the wrapper is not the thing that speaks to Anthropic.
• Restart the child subprocess any time you change the setting so the new value actually reaches it. Editing a UserDefaults key while the subprocess is alive has the same staleness problem as editing a shell.
• Surface upstream errors in a way that distinguishes your gateway's problem from Anthropic's. If the gateway returns no models loaded, or connection refused, the user needs to know it came from their endpoint, not from Claude Code.

Fazm's implementation of the last point lives at acp-bridge/src/api-failure.ts: a classifier that buckets thrown SDK errors into overloaded, credit, and other, so a 529 from Anthropic does not get hijacked into a billing message and a 400 from a mis-configured custom endpoint surfaces verbatim. The Swift side at ACPBridge.swift lines 2614 to 2627 layers on top: if the user has a custom endpoint set and the upstream returns connection refused or no models loaded, the UI message tells you which endpoint failed and how to toggle it off.

The point of the wrapper is not that it does anything the CLI cannot do. It is that you stop having to remember which of the three traps ate your last hour.

One last thing: tool search and the non-first-party host rule

The official environment-variable reference states that when ANTHROPIC_BASE_URL points at a non-first-party host, MCP tool search is disabled by default. The reason is that tool search depends on the upstream forwarding tool_reference blocks intact, and a proxy may strip them. If the gateway you chose does forward those blocks (DeepSeek, Moonshot, and z.ai all claim to in some form, but their compatibility shims around tool_reference vary), you can re-enable search by also setting ENABLE_TOOL_SEARCH=true. If your first tool-call query after the fix behaves differently from what you remember from the public API, that is the reason, not your gateway breaking.