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.
Symptoms
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.
Likely causes
- 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.
Diagnostic procedure
- 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\n' "$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
# Run /status in the session. Redact logs before sharing.
Remediation
- 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 '\n'
export ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_API_KEY
claude
# After the session ends: unset ANTHROPIC_AUTH_TOKENVerification
- 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.
Sensitive diagnostic data
- 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.
View documentation scope