Claude Code API Gateways on Windows: Verify Base URL and Authentication Before Debugging Models

he hongsheng — Sat, 17 Oct 2026 10:13:35 +0000

Many Claude Code gateway failures are diagnosed too late. People often change the model name first, even though the request is still going to the wrong host or using the wrong authentication header.

This guide uses a narrow workflow for Windows: verify the gateway protocol, select the matching credential variable, test the connection in one PowerShell session, and only then make the configuration persistent. It does not assume that an OpenAI-compatible endpoint can serve Claude Code.

The three values that must agree

A working setup has three independent pieces:

Base URL: the URL supplied by the service for Claude Code or an Anthropic-compatible gateway. Do not derive it from a dashboard login URL.
Credential type: a Bearer token normally maps to ANTHROPIC_AUTH_TOKEN; an x-api-key flow maps to ANTHROPIC_API_KEY. The service documentation decides which one is correct.
Protocol and path: Claude Code needs the gateway to support the Anthropic Messages format, commonly exposed under /v1/messages. A service that only documents OpenAI Responses or Chat Completions is a different integration.

If any one of these values is guessed, a later model error is not useful evidence.

Test from one PowerShell session

Start with temporary variables so that a failed experiment is easy to remove:

$env:ANTHROPIC_BASE_URL = "https://gateway.example.com"
$env:ANTHROPIC_AUTH_TOKEN = Read-Host "Enter the gateway token" -MaskInput
claude

Replace the example host and token flow with the values from the current service documentation. If the service specifies an API key header instead, use ANTHROPIC_API_KEY and do not set both variables at the same time.

Launching claude from the same PowerShell window matters. Setting a variable in one shell and starting the CLI from another can make a correct value appear to be missing.

Verify the route before changing models

Inside the Claude Code session:

Send a small, non-sensitive test message.
Run /status.
Check that the displayed base URL and credential source match the values you intended to use.
Only after that, investigate model availability or request limits.

A visible environment variable is not proof that the gateway accepted the request. The test message and status output provide two separate checks: process inheritance and an actual request path.

Read the error as a branch, not a verdict

`401 Unauthorized`

Check the credential type first. A Bearer token sent through the x-api-key variable, or an API key sent through the Authorization flow, can fail even when the string itself is valid. Also check that the token belongs to the current gateway.

Claude Code still asks for login

The CLI may not have inherited the variables, or a higher-priority settings file may be taking precedence. Confirm the launch directory and inspect the active settings source before changing credentials.

The address is reachable but the response format is invalid

Network reachability only proves that something answered. Re-check whether the endpoint implements the Anthropic Messages format and whether the path is the one documented for Claude Code. Do not copy a Codex or OpenAI configuration into this workflow.

Persist only after the temporary test works

When the temporary session works, a user-level settings file can hold the environment block. Keep real credentials out of project files, screenshots, public issues, and repositories. A shared .claude/settings.json is especially easy to commit by accident.

For a longer Windows walkthrough with the exact variable choices, /status checks, and cleanup steps, see the Claude Code API configuration guide. It also explains when a service should be rejected because it documents only an incompatible protocol.

Official references

The workflow above is intentionally conservative: a successful configuration means that the selected client, protocol, address, and credential source agree. It does not claim that every gateway supports Claude Code, nor that a single successful request proves production reliability.

DEV Community: he hongsheng