Skip to content
Nexus Docs
↑↓Navigate↵SelectescClose

Claude Code → Nexus

Route Claude Code through the Nexus native Anthropic edge

Last updated on:

Route Claude Code through the Nexus native Anthropic edge (/anthropic). Claude Code and the Anthropic SDKs append /v1/messages themselves; set ANTHROPIC_BASE_URL to the gateway’s /anthropic prefix and authenticate with a gateway API key (nxs_…). Upstream Anthropic API keys are never accepted at the edge.

Shared prerequisites (gateway URL, nxs_… key, registry model, BYOK/PTB): README.md.

Certification launch matrix: ../../../test-suite/compat/claude-code/environment-matrix.md.

1. Environment

Section titled “1. Environment”
Variable Value Notes
ANTHROPIC_BASE_URL https://api.example.com/anthropic Must include /anthropic. Local: http://127.0.0.1:14450/anthropic.
ANTHROPIC_AUTH_TOKEN nxs_… Preferred for Claude Code (Authorization: Bearer).
ANTHROPIC_API_KEY nxs_… Alternate (x-api-key). May trigger a one-time in-client approval prompt.
ANTHROPIC_MODEL Registry model id Main model, e.g. claude-sonnet-4-6 or anthropic/claude-sonnet-4-6.
ANTHROPIC_SMALL_FAST_MODEL Registry model id Background/utility model; must also resolve in the registry.

Use the same Nexus key in either credential variable. Do not point Claude Code at an upstream Anthropic key.

2. Avoid Claude subscription OAuth

Section titled “2. Avoid Claude subscription OAuth”

Claude Code prefers a logged-in Claude subscription over ANTHROPIC_AUTH_TOKEN. A subscription credential is rejected by the Nexus edge (authentication_error). Launch with a clean config directory that has no subscription login:

Terminal window
export CLAUDE_CONFIG_DIR=/path/to/clean-claude-home
export ANTHROPIC_BASE_URL=https://api.example.com/anthropic
export ANTHROPIC_AUTH_TOKEN='nxs_…'
# optional:
# export ANTHROPIC_MODEL=claude-sonnet-4-6
# export ANTHROPIC_SMALL_FAST_MODEL=claude-haiku-4-5-20251001


claude

3. Model selection

Section titled “3. Model selection”

Pick ids present in the tenant-visible catalog (GET /v1/models on the OpenAI edge lists the same catalog). Claude Code works on default settings with any chat model in the catalog. When a request enables extended thinking, Anthropic upstreams (and Bedrock Mantle Claude models) are tried first among the providers for that model; any other model serves the request without thinking and names thinking in x-nexus-dropped-params. On a non-Anthropic model, the x-nexus-dropped-params response header lists the Claude Code request fields that model cannot take (for example metadata, output_config, context_management).

4. Smoke test

Section titled “4. Smoke test”
Terminal window
GATEWAY_URL="${GATEWAY_URL:-https://api.example.com}"
NEXUS_API_KEY='nxs_…'


curl -sS "$GATEWAY_URL/anthropic/v1/messages" \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 32,
    "messages": [{"role": "user", "content": "ping"}]
  }' | jq .

Then start Claude Code and run a short session. Manual checklist: ../../../test-suite/compat/claude-code/session-battery.md.

Common failures

Section titled “Common failures”
Symptom Likely cause
authentication_error Claude subscription OAuth winning over ANTHROPIC_AUTH_TOKEN
404 on /v1/messages Base URL missing /anthropic (bare /v1/messages is not the Anthropic edge)
Unknown model Id not in registry, or utility model unset / invalid
401 Upstream Anthropic key or nxd_… used instead of nxs_…
Section titled “Related”