Direct answer
Claude Code requires Anthropic Messages behavior, not just a text endpoint. Validate the gateway directly before attributing the failure to the client.
What this guide helps you solve
Fix Claude Code gateway connection, authentication, model mapping, and streaming compatibility failures.
Confirm the symptom and blast radius
Claude Code reports connection, authentication, model, or stream errors after a custom gateway is configured.
A generic curl endpoint may return text while Claude Code still fails on Messages paths, event types, or tool-use behavior.
- Capture the status or exception, response body, request ID, UTC time, client version, and final host before changing configuration.
- Compare one minimal request with the failing workflow to determine whether the issue is global, model-specific, or feature-specific.
- Keep credentials, full prompts, customer data, and private file contents out of screenshots and support bundles.
Common causes and ownership boundaries
Treat the error as evidence from one layer, not as proof that every downstream component failed. These are the highest-value causes to test first.
- The base URL already includes a resource path that Claude Code appends again.
- Environment variables map the credential to the wrong authentication header.
- Claude model aliases do not route to an actual supported upstream model.
- The gateway lacks required Messages streaming or tool-use semantics.
Run a layered minimal diagnosis
Start with a request that has the fewest moving parts. Preserve the same account, API host, and target model while removing optional features.
Change one variable at a time and retain the raw status, headers, response body, and timing. This separates client serialization from gateway and upstream behavior.
- 01Establish the boundaryInspect Claude Code status and the effective sanitized base URL, model, and credential source.
- 02Create a baselineSend one minimal non-streaming Messages request directly to the gateway.
- 03Compare one variableCompare Bearer-token and x-api-key mapping with gateway documentation.
- 04Record decisive evidenceValidate the mapped model, then test streaming and tool use separately.
printf 'ANTHROPIC_BASE_URL=%s
' "$ANTHROPIC_BASE_URL"
test -n "$ANTHROPIC_AUTH_TOKEN" && echo 'Bearer token is set'
test -n "$ANTHROPIC_API_KEY" && echo 'x-api-key credential is set'
claude --version
claude --debug-file /tmp/claude-gateway-debug.log
# 会话内运行 /status；分享日志前必须脱敏。
Apply the fix at the confirmed root cause
Make the smallest change that addresses the proven layer. Avoid hiding deterministic configuration failures behind broad retries or disabled validation.
- 01Correct the failing layerSet the root expected by Claude Code so the Messages resource path is appended once.
- 02Restore required behaviorConfigure the credential variable and gateway header mapping consistently.
- 03Remove temporary workaroundsCreate an explicit supported model mapping and enable only verified protocol capabilities.
export ANTHROPIC_BASE_URL='https://<your-gateway-host>'
read -rsp 'Gateway token: ' ANTHROPIC_AUTH_TOKEN && printf '
'
export ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_API_KEY
claude
# 会话结束后：unset ANTHROPIC_AUTH_TOKENVerify the repair, not just one successful call
Repeat the original path after the minimal check succeeds, then verify stable behavior under normal streaming, concurrency, and timeout conditions.
- The effective base URL contains the Messages path exactly once.
- The emitted authentication header matches gateway expectations.
- Each Claude Code model name resolves to a real supported model ID.
- Non-streaming, streaming, and tool-use paths pass independent checks.
Security boundaries and escalation evidence
Collect enough evidence to reproduce and escalate the failure without exposing credentials or weakening transport, permission, and validation controls.
- Do not print Claude or gateway credentials while inspecting environment variables.
- Keep model aliases explicit; do not silently downgrade to another model.
- Retain permission prompts and tool restrictions through the gateway.
- Escalate with versions, sanitized environment names, model mapping, UTC time, and request IDs.
Official sources and verification scope
This guide is grounded in protocol specifications and official client documentation. Error text, retry headers, and configuration fields may change by service or client version; verify the sources and redact logs and request samples before sharing.
Read the verification methodology