Tool IntegrationsSeptember 22, 2026Flatkey Team

Claude Code ANTHROPIC_AUTH_TOKEN Errors: Complete Configuration Fixes

A complete troubleshooting runbook for Claude Code ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, /status, VS Code, GitHub Actions, and gateway 401 errors.

When Claude Code ANTHROPIC_AUTH_TOKEN Errors: Complete Configuration Fixes is the query, the fix usually starts with one question: is Claude Code sending the credential in the header your gateway actually reads?

For Claude Code gateway routing, ANTHROPIC_AUTH_TOKEN sends Authorization: Bearer .... ANTHROPIC_API_KEY sends x-api-key: .... A token in the wrong variable can look like a bad key, a stale login, or a broken gateway even when the value itself is valid.

Use this runbook when Claude Code fails after you set ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, a Claude Code settings file, the VS Code extension, or a CI workflow.

The fast fix

Start with the smallest possible diagnosis before editing every settings file on your machine.

Pick one credential variable.
Export the gateway base URL and that credential in the same shell.
Run a one-token curl request against $ANTHROPIC_BASE_URL/v1/messages.
Start Claude Code from that same shell.
Run /status and confirm both Anthropic base URL and the expected credential source appear.
If the curl succeeds but Claude Code still asks you to log in, move the credential to a place Claude Code reads before first-run setup, such as ~/.claude/settings.json, a shell export, or managed settings.

For a bearer-token gateway:

export ANTHROPIC_BASE_URL="https://llm-gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="REPLACE_WITH_GATEWAY_TOKEN"

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "replace-with-a-gateway-supported-claude-model",
    "max_tokens": 1,
    "messages": [{"role": "user", "content": "."}]
  }'

For an x-api-key gateway:

export ANTHROPIC_BASE_URL="https://llm-gateway.example.com"
export ANTHROPIC_API_KEY="REPLACE_WITH_GATEWAY_KEY"

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "replace-with-a-gateway-supported-claude-model",
    "max_tokens": 1,
    "messages": [{"role": "user", "content": "."}]
  }'

A JSON response with a message id and content means the URL and credential work. A 401 means the gateway rejected the credential or received it in a header it does not read.

Claude Code ANTHROPIC_AUTH_TOKEN Errors: Complete Configuration Fixes checklist

Use this table as the working diagnostic. Do not rotate keys until the active variable, header, and settings precedence are known.

Symptom	Most likely cause	Fix
`401` invalid or unrecognized token	The credential is revoked, mistyped, or sent in the wrong header	If the gateway expects bearer auth, use `ANTHROPIC_AUTH_TOKEN`. If it expects `x-api-key`, use `ANTHROPIC_API_KEY`. Regenerate only after the header is correct.
Startup warning says two credential sources are active	A gateway credential and a saved Claude login or API key are both active	Choose one path. Unset the gateway variable to use the saved login, or run `/logout` and keep only the gateway credential.
`/status` has no `Anthropic base URL` line	`ANTHROPIC_BASE_URL` did not reach the Claude Code process	Start `claude` from the same shell, move the variable to `~/.claude/settings.json`, or configure the surface you are actually using.
Curl works, Claude Code asks you to log in	The CLI has a reachable base URL but no credential available before first-run setup	Put `ANTHROPIC_AUTH_TOKEN` in a shell export, user settings, or managed settings that Claude Code reads before the wizard.
`ANTHROPIC_API_KEY` is set but ignored	Interactive Claude Code needs a one-time approval for a custom API key, or a previous key was declined	Enable it under `/config` with `Use custom API key`.
Empty or malformed response with HTTP 200	The gateway or proxy returned HTML, a login page, or another non-API response	Run the curl request and fix the route that answers with non-Claude API JSON.
DNS, firewall, or connection refused errors	Nothing reachable is answering at `ANTHROPIC_BASE_URL`	Confirm DNS, VPN, proxy, and firewall access to the gateway host.
`400` names `context_management`, `Extra inputs are not permitted`, or tool schema fields	The gateway forwards Anthropic-format Claude Code requests to an upstream that rejects fields Claude Code sends	Forward compatible fields correctly, use the provider-specific route, or temporarily set `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` when appropriate.
`400` names `thinking` or `adaptive`	The upstream model build does not accept adaptive reasoning	Upgrade the upstream or use the documented `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` workaround for supported Claude 4.6 cases.
`/fast` fails while inference works	Fast mode checks can go directly to Anthropic instead of following the gateway URL	Treat this as separate from message routing; allowlist the direct check or use the documented skip variable when applicable.
Certificate errors while curl works	Claude Code's runtime trusts a different CA bundle than curl	Set `NODE_EXTRA_CA_CERTS` to the corporate CA bundle path.

Choose `ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY`

ANTHROPIC_AUTH_TOKEN is for a bearer token. Claude Code sends it as:

Authorization: Bearer <token>

ANTHROPIC_API_KEY is for an API key. Claude Code sends it as:

x-api-key: <key>

If your gateway team only says "token" or "Authorization header," start with ANTHROPIC_AUTH_TOKEN. If they say "API key" or "x-api-key," use ANTHROPIC_API_KEY. If you guessed and received 401, switch variables before rotating the key.

Do not set both during troubleshooting. That is how Claude Code ANTHROPIC_AUTH_TOKEN Errors: Complete Configuration Fixes turns from an auth problem into an auth-precedence problem.

Put the variables where Claude Code actually reads them

Shell exports are good for the first test because they are easy to unset:

export ANTHROPIC_BASE_URL="https://llm-gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="REPLACE_WITH_GATEWAY_TOKEN"
claude

They apply only to that terminal session and programs launched from it. If you open VS Code, a desktop app, or a background agent from somewhere else, the export may not be visible.

For a persistent user-level CLI setup, use ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "REPLACE_WITH_GATEWAY_TOKEN"
  }
}

For one project, use .claude/settings.local.json and make sure it is gitignored before adding a credential. Do not put a credential in .claude/settings.json, because that file is meant to be shared with the repo.

When a shell export and a settings-file env block set the same variable, Claude Code uses the settings-file value. That is why /status is a better source of truth than echo $ANTHROPIC_AUTH_TOKEN.

Fix the VS Code extension

The Claude Code VS Code extension has its own launch checks. Configure gateway variables in VS Code user settings under claudeCode.environmentVariables:

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://llm-gateway.example.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "REPLACE_WITH_GATEWAY_TOKEN" }
  ]
}

Use the VS Code command Preferences: Open User Settings (JSON). Then restart the extension session and run /status. If the extension still prompts for login, it is not seeing the credential at its own login check.

Fix GitHub Actions

Claude Code GitHub Actions reads ANTHROPIC_BASE_URL from the workflow env block. For an x-api-key gateway, pass the gateway key as the action input:

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

For a bearer-token gateway, the action still needs anthropic_api_key to satisfy its launch check, while ANTHROPIC_AUTH_TOKEN is the value Claude Code sends as Authorization: Bearer:

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com
  ANTHROPIC_AUTH_TOKEN: ${{ secrets.GATEWAY_API_KEY }}

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

Keep those values in GitHub Secrets. Do not paste gateway credentials into workflow logs, issue comments, or committed files.

Use `/status` as the truth check

After any configuration change, run:

/status

For an Anthropic-format gateway, the Status tab should show:

Anthropic base URL: https://llm-gateway.example.com
Auth token: ANTHROPIC_AUTH_TOKEN

or:

Anthropic base URL: https://llm-gateway.example.com
API key: ANTHROPIC_API_KEY

If the base URL row is missing, ANTHROPIC_BASE_URL did not reach the session. If the credential source is a saved login, Claude Code is not using the gateway credential. If both look correct and the message still fails, the problem is now likely in gateway routing, upstream compatibility, proxy behavior, or certificate trust.

Flatkey note for Claude Code gateway routing

Flatkey is useful in two different Claude Code workflows, and the distinction matters.

For OpenAI-compatible model calls from a project or agent skill, Flatkey's base URL is:

https://router.flatkey.ai/v1

For Claude Code's own gateway path, follow the Anthropic Messages-format gateway setup and do not add /v1 to ANTHROPIC_BASE_URL unless the gateway's own Claude Code instructions explicitly tell you to. A typical provider pattern is:

export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_API_KEY="$FLATKEY_API_KEY"

Then run /status, send a short prompt, and check the gateway ledger or logs. Keep the Claude Code SKILL.md setup separate from this path: a skill teaches Claude Code how to call Flatkey-supported models and tools from your repo; gateway routing controls where Claude Code sends its own Claude-family traffic.

If you are standardizing agent traffic across providers, pair this article with the Claude API proxy vs multi-model router and Flatkey API quickstart guides.

Gateway operator checks when the token is not the real problem

Some Claude Code ANTHROPIC_AUTH_TOKEN Errors: Complete Configuration Fixes searches start as a local setup problem and end at the gateway. If the one-token curl authenticates and /status looks right, inspect these gateway-side conditions:

Gateway check	Why it matters
Serve the Anthropic Messages format at `/v1/messages`	`ANTHROPIC_BASE_URL` makes Claude Code treat the gateway as an Anthropic-format endpoint.
Forward `anthropic-version` and `anthropic-beta` unchanged	Claude Code capabilities change over releases; static allowlists can break later requests.
Preserve streaming and keep-alive behavior	Buffering or stripping stream bytes can make Claude Code stall.
Forward error bodies unmodified	Claude Code uses upstream error wording for some recovery paths.
Avoid returning HTML with HTTP 200	Claude Code expects Claude API JSON or event-stream responses, not a browser login page.
Exempt `/v1/messages` from request-body WAF rules	Claude Code prompts can contain XML-style tags and source code that trigger generic body filters.
Return useful retry headers	`retry-after` and `x-should-retry` influence retry behavior.

If your gateway fronts a provider that does not accept the full Anthropic Messages request shape, use the provider-specific variables instead of ANTHROPIC_BASE_URL, or bridge the schema inside the gateway. Do not strip fields blindly; that trades one visible error for a later capability failure.

Copyable debug record

Use this record when handing the problem to a teammate or gateway operator:

claude_code_auth_debug:
  date_checked: 2026-09-22
  surface: cli # cli | vscode | github_actions | agent_sdk | desktop
  claude_code_version: ""
  expected_gateway_base_url: "https://llm-gateway.example.com"
  variable_used: "ANTHROPIC_AUTH_TOKEN"
  expected_header: "Authorization: Bearer"
  status_tab_base_url_seen: false
  status_tab_credential_source: ""
  curl_status_code: ""
  curl_response_shape: "json_message | 401 | html_200 | dns_error | tls_error | other"
  settings_files_checked:
    - "~/.claude/settings.json"
    - ".claude/settings.local.json"
    - ".claude/settings.json"
  shell_started_claude: false
  saved_login_present: unknown
  gateway_logs_received_request: unknown
  suspected_fix: ""

That record forces the investigation to separate three things: where Claude Code read configuration, which header it sent, and what the gateway returned.

Frequently asked questions

Should I use `ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY`?

Use ANTHROPIC_AUTH_TOKEN when the gateway expects a bearer token or Authorization header. Use ANTHROPIC_API_KEY when the gateway expects x-api-key. If you do not know, start with ANTHROPIC_AUTH_TOKEN, verify with the curl request, and switch if you receive 401.

Why does `/status` not show my base URL?

ANTHROPIC_BASE_URL did not reach the Claude Code process. Start claude from the same shell, move the value into the correct settings file, or configure the surface you are using, such as VS Code settings or GitHub Actions env.

Why does curl work but Claude Code still asks me to log in?

The base URL is reachable, but Claude Code does not have a credential available at the point it needs one. Put ANTHROPIC_AUTH_TOKEN or the correct credential variable in a shell export, user settings, or managed settings that Claude Code reads before first-run setup.

Can I put the token in `.claude/settings.json`?

Do not put secrets in .claude/settings.json because it is a shared project file. Use ~/.claude/settings.json, .claude/settings.local.json, managed settings, a secret manager, or CI secrets.

Does `ANTHROPIC_AUTH_TOKEN` route Claude Code to non-Claude models?

No. It only changes how Claude Code authenticates to the configured Anthropic-format gateway. The gateway may route or bridge requests according to its own implementation, but Claude Code still expects the Claude API shape on the ANTHROPIC_BASE_URL path.

What is the safest final verification?

Run the one-token curl request, start Claude Code from the configured surface, run /status, send a short prompt, and confirm the gateway ledger or logs show the request. That four-step check is the durable fix behind Claude Code ANTHROPIC_AUTH_TOKEN Errors: Complete Configuration Fixes.

Sources checked

Anthropic Claude Code docs: Connect Claude Code to an LLM gateway, accessed 2026-09-22.
Anthropic Claude Code docs: Settings files and precedence, accessed 2026-09-22.
Anthropic Claude Code docs: Claude Code gateway compatibility guide, accessed 2026-09-22.
Claude Help Center: Manage API key environment variables in Claude Code, accessed 2026-09-22.
Flatkey public SKILL.md, accessed 2026-09-22.
Flatkey knowledge base: Product Overview, Marketing Strategy, Brand Voice.