AI coding tools · BYOK ·

Claude Code ANTHROPIC_BASE_URL not working? Gateway fixes

You pointed Claude Code at a gateway or compatible server with ANTHROPIC_BASE_URL, and now requests fail with a 400, the gateway rejects an anthropic-beta value, or subagents and claude -p suddenly can't use their tools. Several of these changed in October 2026. This guide covers the checks and switches in Anthropic's own docs and release notes.

If you want the next step, read Claude Code or Codex limit hit? Use an API key instead.

Quick fix

  • Run /status and confirm the Anthropic base URL line shows your gateway. If it isn't there, the variable didn't reach the session.
  • Update Claude Code to v2.1.310 or later (claude update). As of October 2026, that release retries without the effort-2025-11-24 beta value when a gateway rejects it.
  • Gateway rejects anthropic-beta or says Extra inputs are not permitted: set CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.
  • Subagents only have ToolSearch, or claude -p has no Bash: set ENABLE_TOOL_SEARCH=false.

Step 1: check the gateway is actually in use

Anthropic's gateway guide says to run /status and look at two lines. The Anthropic base URL line "only appears when a gateway address is set". An Auth token or API key line naming the variable you set "confirms the gateway credential is active rather than a saved claude.ai login".

If a shell export and a settings-file env block both set the variable, the docs say "the settings-file value applies". To drop a saved login so only the gateway credential remains, run /logout.

Step 2: update past the recent gateway bugs

As of October 2026, two recent releases changed what Claude Code sends to a custom base URL, per the release notes:

  • v2.1.307 (21 Oct 2026) fixed "the prompt-caching-scope beta header being sent behind custom ANTHROPIC_BASE_URL gateways".
  • v2.1.310 (23 Oct 2026) "Fixed requests failing behind some gateways and compatible servers that reject the effort-2025-11-24 beta value or mid-conversation system messages; Claude Code now retries without them".

Check your version with claude --version and update with claude update.

Step 3: strip pre-release betas the gateway rejects

If your gateway or its upstream still returns a 400, the environment variable reference describes CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 for "when a proxy gateway rejects requests with an Unexpected value(s) error for the anthropic-beta header or an Extra inputs are not permitted error". It strips pre-release beta headers, their paired body fields and beta tool-schema fields such as defer_loading.

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
claude

Or put it in the env block of ~/.claude/settings.json. The gateway guide notes that some betas aren't gated by this flag, so if one still gets through, it suggests the matching CLAUDE_CODE_USE_* provider variable. Turning this on also disables MCP tool search, per the docs.

Step 4: subagents or claude -p lose their tools

As of October 2026, Anthropic's MCP docs say that when ANTHROPIC_BASE_URL points to a gateway, "tool search is on by default", and tool search was off behind a gateway before v2.1.304. In issue #104309 (22 Oct 2026), a user behind a third-party gateway reports that since 2.1.304, subagents start with ToolSearch as their only tool and claude -p has no Agent or Bash tool. The reporter found the "only escape is ENABLE_TOOL_SEARCH=false", which the docs describe as loading all tools upfront:

export ENABLE_TOOL_SEARCH=false

The issue is still open, so this may change in a later release.

Other gateway errors

The gateway guide's troubleshooting table also lists:

  • 401 naming an invalid token: the credential is in "a header the gateway doesn't read". The gateway guide says to use ANTHROPIC_AUTH_TOKEN if you weren't told which kind your gateway wants, covered in using an API key instead of a Claude Code or Codex subscription.
  • API returned an empty or malformed response (HTTP 200): the gateway returned "a non-API response, often an HTML error or login page".
  • 403 with an HTML body and nothing in gateway logs: a web application firewall blocked the request body; exempt the /v1/messages path from body inspection.

Get the tested profiles

Disclosure: this is our own paid product. The BYOK Profiles Kit has copy-paste Claude Code and Codex profiles and Cursor steps for Kimi, OpenRouter, Vercel AI Gateway and Azure OpenAI, with keys read from environment variables, plus a table of 29 error strings and symptoms with their cause and fix. It's designed to save the trial and error of base URL paths and auth headers. It doesn't patch Claude Code bugs like the ones above; update Claude Code for those. The Codex and Claude Code snippets were run against a local mock server, not the live provider APIs, and the Cursor steps are checked against docs and Cursor staff replies only. No API keys are included, and providers bill you directly. It costs $9 (plus VAT where applicable).

Sources

As of October 2026 (sources checked 24 Oct 2026):

  • Claude Code docs, LLM gateway connection and troubleshooting: https://code.claude.com/docs/en/llm-gateway-connect
  • Claude Code docs, environment variables: https://code.claude.com/docs/en/env-vars
  • Claude Code docs, MCP tool search through a gateway: https://code.claude.com/docs/en/mcp
  • Claude Code release notes (v2.1.307, v2.1.310): https://github.com/anthropics/claude-code/releases
  • GitHub issue #104309, tool search behind a gateway: https://github.com/anthropics/claude-code/issues/104309

Claude Code and Anthropic, Codex and OpenAI, Cursor and Anysphere, Kimi and Moonshot AI, OpenRouter, Vercel, Azure and Microsoft, AWS and other names belong to their owners. Names are used only to identify products and compatibility. Stack & Ship is not affiliated with or endorsed by any of them.

Related posts