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; anx-api-keyflow maps toANTHROPIC_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.
Top comments (0)