Run Claude Code through Gatewayz

Claude Code talks to the Anthropic Messages API. Gatewayz serves that API natively at https://api.gatewayz.ai/v1/messages, including tool use and prompt caching, so Claude Code can run through Gatewayz without a translation shim. This guide covers the setup, model selection, verification, and the mistakes that come up most often.

What you need

• Claude Code installed and working on your machine.
• A Gatewayz API key.
• curl, for the verification steps.

1. Set two environment variables

export ANTHROPIC_BASE_URL=https://api.gatewayz.ai
export ANTHROPIC_AUTH_TOKEN=<your Gatewayz key>

Two details matter here.

No /v1 on the base URL. Claude Code appends /v1/messages to whatever base URL you give it. If you set https://api.gatewayz.ai/v1, requests go to /v1/v1/messages and fail. The same rule applies to the Anthropic SDKs: give them the host, not the versioned path.

Use ANTHROPIC_AUTH_TOKEN. Claude Code sends this value as a bearer token in the Authorization header. If you also have ANTHROPIC_API_KEY set in your shell from earlier Anthropic use, unset it for this session so there is no ambiguity about which credential is being sent:

unset ANTHROPIC_API_KEY

To make the setup persistent, put the exports in your shell profile, or in the env block of Claude Code's settings file. The Claude Code settings documentation lists where that file lives and which variables it accepts.

2. Choose models from the live catalog

Gatewayz model ids are namespaced by provider, for example anthropic/claude-sonnet-4-6. The catalog is published at https://api.gatewayz.ai/v1/models and is the only list to trust; ids change as providers release and retire models.

List the Anthropic models currently offered:

curl -s https://api.gatewayz.ai/v1/models \
  | python3 -c 'import sys, json; [print(m["id"]) for m in json.load(sys.stdin)["data"] if m["id"].startswith("anthropic/")]'

Then tell Claude Code which model to use:

export ANTHROPIC_MODEL=anthropic/claude-sonnet-4-6

You can also switch models inside a session with the /model command. Claude Code uses a smaller model for some background tasks; the settings documentation describes the variables that control those defaults, and the same rule applies: use an id that appears in the catalog.

Prefer dated snapshot ids, such as anthropic/claude-haiku-4-5-20251001, for anything you want to behave the same next week. An undated alias resolves to its dated snapshot, and an id that matches nothing returns 400 model_not_found rather than running a different model. Resolution, not substitution explains the rules.

3. Verify before a long session

Three checks take under a minute and rule out most setup problems.

The service is up, and which version is serving:

curl -s https://api.gatewayz.ai/health/quick

The response includes the commit currently serving requests.

Your model id exists:

curl -s https://api.gatewayz.ai/v1/models | grep -c '"anthropic/claude-sonnet-4-6"'

A result of 0 means the id is wrong or no longer offered.

Your key works against the Messages endpoint:

curl -s https://api.gatewayz.ai/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-6",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "Reply with the word ready."}]
  }'

A normal Messages response means Claude Code will work with the same variables. Then start Claude Code in a project directory and run a small task.

4. Read errors by status

Claude Code surfaces API errors in the session. The status tells you whether waiting will help:

If a response stops partway through a stream because the upstream failed, Gatewayz ends the stream with an explicit error event, so the session reports an error rather than presenting a cut-off answer as complete.

Prompt caching

Claude Code marks large, stable parts of its context for prompt caching. Gatewayz passes cache_control through to Anthropic on the Messages endpoint, so cache writes and cache reads happen as they would against Anthropic directly, and appear in the usage fields of each response. See Prompt caching through a gateway for how to verify caching is actually happening rather than assuming it.

Cost and data

Usage is billed per token at the provider's list price plus a routing fee.

Plain API calls through Gatewayz do not store prompt or completion content; billing metadata is kept. Content is processed by the provider serving the model under that provider's terms.

Common problems

• Requests go to /v1/v1/messages. Remove /v1 from ANTHROPIC_BASE_URL.
• "Model not found" on start. The configured model id is not in the catalog, often because it is missing the anthropic/ prefix or names a retired snapshot.
• Claude Code still uses your Anthropic account. Another credential is set. Check env | grep ANTHROPIC and your Claude Code settings file for an apiKeyHelper or a stored key.
• Everything worked yesterday and fails today with 402. Check the code. A per-key cap and an empty balance need different people to fix them.