Claude Code

Claude Code is Anthropic’s agentic coding tool for the terminal, IDEs, and desktop. It speaks the Anthropic Messages API, so pointing its base URL at the AI Gateway sends every model request through ngrok.ai, where it shows up in observability and follows your access key configuration.

What you’ll need

Claude Code installed.
An access key from app.ngrok.ai.

Point the CLI at the gateway

Set two environment variables in your shell:

export ANTHROPIC_BASE_URL="https://gateway.ngrok.ai"
export ANTHROPIC_AUTH_TOKEN="ng-xxxxx-g1-xxxxx"

ANTHROPIC_BASE_URL is the gateway URL without /v1, since Claude Code appends /v1/messages itself
ANTHROPIC_AUTH_TOKEN is your access key, which Claude Code sends as an Authorization: Bearer header

ANTHROPIC_AUTH_TOKEN takes precedence over a saved claude.ai login, so Claude Code uses your access key as soon as you start it. If ANTHROPIC_API_KEY is also set in your environment, unset it to avoid an auth conflict warning. To keep the configuration across terminals and for background agents, move the same values into the env block of ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://gateway.ngrok.ai",
    "ANTHROPIC_AUTH_TOKEN": "ng-xxxxx-g1-xxxxx"
  }
}

Don’t put your access key in a project’s .claude/settings.json. That file is committed and shared with everyone who clones the repository.

Test the connection

Before you start Claude Code, send a short request straight to the gateway from the same shell:

curl https://gateway.ngrok.ai/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-5-5", "max_tokens": 16, "messages": [{"role": "user", "content": "Say hello."}]}'

A JSON response that starts with {"id":"msg_ means the URL and access key work. A 401 means the gateway rejected the access key. Then start claude, run /status, and check two lines:

Anthropic base URL shows https://gateway.ngrok.ai
Auth token names ANTHROPIC_AUTH_TOKEN

Send any prompt, then confirm the request in AI Gateway observability in app.ngrok.ai.

Choose a model

Claude Code’s built-in model aliases, such as opus, sonnet, and haiku, resolve to Anthropic model IDs like claude-sonnet-5-5. The gateway finds those IDs in the model catalog, so /model and --model work without extra setup. To pin the model behind each alias, set these variables alongside the base URL:

export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-5-5"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-5-5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-5-5"

Use the catalog’s model IDs rather than dated snapshot IDs like claude-haiku-4-5-20251001, which the gateway doesn’t match. To add the gateway’s Claude models to the /model picker, turn on Claude Code’s gateway model discovery:

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

At startup, Claude Code reads the gateway’s model list, which only includes models your access key is allowed to call, and adds the Claude models in it, such as anthropic/claude-sonnet-5-5. The gateway doesn’t serve Anthropic’s token counting endpoint, so /context shows estimated token counts.

Claude Code only works with Claude models through the gateway. /v1/messages only reaches providers that support the Anthropic Messages API, and Anthropic doesn’t support routing Claude Code to other models.

Use other surfaces

The CLI reads the shell variables and ~/.claude/settings.json. Other surfaces need the same two values in a different place:

VS Code extension: set them in claudeCode.environmentVariables in your VS Code user settings
Claude Agent SDK: pass them in the SDK’s env option, which sets the environment of the Claude Code process it spawns
Claude desktop app: turn on Developer Mode, then enter the gateway details under Developer > Configure Third-Party Inference

See Claude Code’s guide to connecting to an LLM gateway for each surface.

Troubleshooting

Symptom	Fix
`401` errors	Check that `ANTHROPIC_AUTH_TOKEN` holds a current access key from app.ngrok.ai
Claude Code asks you to log in	Set the variables in your shell or in `~/.claude/settings.json`, not in a project settings file, which Claude Code reads only after its first-run setup
`/status` doesn’t show the gateway URL	Start `claude` from the shell where you exported the variables, or move them to `~/.claude/settings.json`
A request fails with a model error	Check that the model ID matches the model catalog exactly, without a date suffix, and that your access key configuration allows it
Long responses stop partway through	Set `totalTimeout` to `15m` in account settings. A saved total timeout caps the whole stream, and saving any account setting stores the `2m` default

For gateway-side errors, see Debug failed requests.

Next steps

Restrict providers and models: Scope what an access key can call
Configure fallback models: Try another model when the first one fails
Observability: See which model served each request

Concepts

Getting Started With

SDKs

Agents

Guides

Observability

Examples

Reference

API Reference

What you’ll need

Point the CLI at the gateway

Test the connection

Choose a model

Use other surfaces

Troubleshooting

Next steps

​What you’ll need

​Point the CLI at the gateway

​Test the connection

​Choose a model

​Use other surfaces

​Troubleshooting

​Next steps

What you’ll need

Point the CLI at the gateway

Test the connection

Choose a model

Use other surfaces

Troubleshooting

Next steps