Claude Code

Claude Code can read endpoint and authentication settings from environment variables or settings files. Use those settings when Claude Code should call AISIX as an Anthropic-compatible gateway instead of calling Anthropic directly.

In this guide, you will point Claude Code at the AISIX proxy listener and authenticate with an AISIX caller API key. You will also select an AISIX model alias that is available on the Anthropic Messages route.

Prerequisites

Before starting, prepare the following:

• Claude Code installed.
• A running AISIX gateway with the proxy listener available.
• An AISIX caller API key.
• An AISIX model alias that works with Anthropic Messages. An Anthropic-backed alias is the safest choice for Claude Code because it preserves Anthropic-specific request and response behavior most directly.

Configure Claude Code

Set the endpoint, caller key, and model alias before launching Claude Code:

# Replace with your values
export ANTHROPIC_BASE_URL="http://127.0.0.1:3000"
export ANTHROPIC_AUTH_TOKEN="YOUR_CALLER_API_KEY"
export ANTHROPIC_MODEL="claude-demo"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-demo"

claude

ANTHROPIC_BASE_URL points Claude Code at the AISIX proxy listener. Claude Code sends ANTHROPIC_AUTH_TOKEN as a bearer token, so AISIX receives the value as the caller API key. ANTHROPIC_MODEL and ANTHROPIC_DEFAULT_HAIKU_MODEL should be AISIX model aliases, not upstream provider model IDs. You can point both variables to the same alias, or use a separate fast alias for Claude Code background behavior.

To apply the same settings every time Claude Code starts, put them in the env block of a Claude Code settings file:

~/.claude/settings.json

{
  "model": "claude-demo",
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:3000",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_CALLER_API_KEY",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-demo"
  }
}

Verify the Route

Start Claude Code and send a short prompt.

When the request succeeds, verify the following results:

• Claude Code prints a model response.
• AISIX records a successful POST /v1/messages request for the selected model alias.

AISIX authenticates the caller API key, checks model access, resolves the model alias, applies configured policies, and dispatches to the upstream provider behind the alias.

If you use AISIX Cloud or an on-premises managed control plane, verify the request in the managed gateway logs. For self-hosted gateways, use your configured logs, metrics, or upstream provider request logs.

Handle Compatibility Issues

Claude Code may send Anthropic-specific fields and beta behavior as it evolves. Use an Anthropic-backed AISIX model alias for the most direct compatibility, and validate the exact Claude Code workflow your team plans to use before rolling it out broadly.

If Claude Code reports an endpoint, authentication, or model error, check these items:

Symptom	Check
Authentication fails	Confirm ANTHROPIC_AUTH_TOKEN is the AISIX caller API key and that the key can access the selected model alias.
Model is not found	Confirm ANTHROPIC_MODEL and ANTHROPIC_DEFAULT_HAIKU_MODEL are AISIX model aliases available to the caller API key.
Requests reach AISIX but fail upstream	Confirm the alias points to a compatible upstream model and provider key.
Tool or beta behavior fails	Validate whether the Anthropic-specific feature is supported by the selected AISIX route and upstream provider.

For endpoint behavior, see Anthropic Messages.

Next Steps

• Anthropic Messages: review route behavior and compatibility boundaries.
• Metrics and Logs: confirm gateway-side request metrics and logs.
• Guardrails: add request or response policy checks.