Claude Code with an Anthropic-Compatible AI Gateway

A provider-neutral runbook for connecting Claude Code CLI and Claude Desktop to an organization’s Anthropic-compatible AI gateway.

This document intentionally contains no production hostnames, credentials, Kubernetes details, private network information, personal filesystem paths, or gateway internals. Replace the placeholders with values supplied by the gateway administrator.

What this configures

• Claude Code CLI through an Anthropic-compatible gateway endpoint.
• Claude Desktop through its separate third-party inference configuration.
• Explicit model-family mappings for opus, fable, sonnet, and haiku.
• A credential helper so tokens do not live in shell profiles or repository files.
• An explicit Desktop model list when gateway model discovery is unavailable.

Prerequisites

You need:

• Claude Code v2.1.219 or newer for the current Opus model family.
• Claude Code v2.1.197 or newer for the current Sonnet model family.
• Claude Desktop with third-party inference configuration support.
• An Anthropic-compatible gateway base URL from the gateway administrator.
• A user-scoped bearer token or API key issued by that gateway.
• The exact gateway model IDs for the models you are allowed to use.
• A credential helper or approved secret store. Do not paste credentials into this repository.

The gateway base URL should be the endpoint whose /v1/messages path is accepted by the gateway. For example:

https://gateway.example.com/anthropic

Do not assume that the gateway root, /v1, and /anthropic are interchangeable. Confirm the required base path with the gateway administrator.

1. Create a credential helper

The helper must:

• be executable by the local user;
• print only the current credential to stdout;
• print diagnostics to stderr, never stdout;
• exit with status 0 when it returns a usable credential;
• read from a secret manager, OS keychain, or another approved credential source;
• never write the credential to Git, shell history, logs, or a shared configuration file.

Example shape:

#!/bin/sh
set -eu

# Replace this with the approved secret-store command.
exec /path/to/secret-provider read claude-gateway-token

Protect the helper and any local credential cache:

chmod 700 /path/to/get-gateway-credential
chmod 600 /path/to/local-credential-file

Do not put a literal token in the script shown in documentation.

2. Configure Claude Code CLI

Claude Code supports gateway configuration through ANTHROPIC_BASE_URL and either ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, or apiKeyHelper.

For a persistent per-user setup, add an apiKeyHelper and gateway environment block to the user Claude Code settings file. Use the exact model IDs returned or documented by the gateway:

{
  "model": "<gateway-opus-model-id>",
  "apiKeyHelper": "/path/to/get-gateway-credential",
  "env": {
    "ANTHROPIC_BASE_URL": "https://gateway.example.com/anthropic",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "<gateway-opus-model-id>",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "<gateway-fable-model-id>",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "<gateway-sonnet-model-id>",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "<gateway-haiku-model-id>",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

The important distinction is that fable has its own mapping:

opus   -> <gateway-opus-model-id>
fable  -> <gateway-fable-model-id>
sonnet -> <gateway-sonnet-model-id>
haiku  -> <gateway-haiku-model-id>

Do not map Fable into the Opus slot. ANTHROPIC_DEFAULT_FABLE_MODEL is the independent Claude Code mapping.

Use the models

Interactive Claude Code:

/model opus
/model fable
/model sonnet
/model haiku

One-shot CLI:

claude --model opus
claude --model fable
claude --model sonnet
claude --model haiku

The exact model ID is also valid and useful for diagnostics:

claude --model <gateway-fable-model-id>

CLI smoke test

Use a harmless one-turn request:

claude -p "Reply with exactly: gateway-connected" \
  --model fable \
  --max-turns 1 \
  --output-format json \
  --no-session-persistence

Verify all of the following:

• the process exits successfully;
• the response is returned by the gateway;
• the reported model usage contains the expected gateway Fable model ID;
• the gateway access log records a successful request;
• no credential appears in command output or logs.

3. Configure Claude Desktop

Claude Desktop does not read Claude Code’s ~/.claude/settings.json or shell environment. Configure it separately using the official third-party inference UI:

1. Open Claude Desktop.
2. Choose Help → Troubleshooting → Enable Developer Mode.
3. Relaunch Claude Desktop if requested.
4. Choose Developer → Configure Third-Party Inference….
5. Select Gateway as the inference provider.
6. Set the gateway base URL supplied by the administrator.
7. Select the correct authentication scheme:
   • bearer for Authorization: Bearer ...;
   • x-api-key for the x-api-key header.
8. Select helper-script and enter the absolute path to the approved credential helper.
9. Configure model discovery or provide an explicit model list.
10. Use Apply locally for a single-user installation, or export a managed profile for an MDM deployment.

The Desktop helper follows the same contract as the CLI helper: stdout must contain only a bare credential or the documented JSON credential object.

Model discovery fallback

If the configured gateway does not expose model discovery at the base URL’s /v1/models path, disable automatic discovery and provide an explicit list:

[
  "<gateway-opus-model-id>",
  "<gateway-fable-model-id>",
  "<gateway-sonnet-model-id>",
  "<gateway-haiku-model-id>"
]

The first entry is normally the Desktop default. Use exact IDs. Do not add unprefixed server aliases merely to make the picker look familiar; local model mappings and explicit model lists are safer.

Desktop smoke test

After applying the profile and relaunching Desktop:

1. Start a new conversation.
2. Select the configured Fable model in the model picker.
3. Send a short prompt such as Reply with exactly: gateway-connected.
4. Confirm the response and the gateway-side successful request.

4. Troubleshooting

401 Unauthorized

Check:

• bearer versus API-key authentication scheme;
• helper exit status;
• helper stdout contains only the credential;
• the credential is current and issued for the gateway;
• the gateway accepts the chosen header.

Do not solve a 401 by committing a token to a settings file.

404 for a model

The gateway is receiving a model ID it does not advertise or route. Compare the requested ID byte-for-byte with the gateway catalog. Common causes:

• missing provider or gateway prefix;
• using a Claude API model ID where a gateway-specific ID is required;
• assuming the gateway rewrites unprefixed names;
• stale model discovery data.

Prefer an exact local mapping or explicit model list over adding a server alias.

Desktop model picker is empty

Disable model discovery and configure inferenceModels explicitly with the exact gateway IDs. Then fully quit and relaunch Desktop; the configuration is read at launch.

The helper works in a shell but not in Desktop

Desktop may run helpers with a restricted environment. Avoid relying on interactive shells, terminal state, $PATH, or a live terminal session. Use absolute executable paths and an OS keychain/secret-store helper. Test the helper with a minimal environment and make sure it emits no diagnostic text on stdout.

Requests reach the wrong endpoint

Inspect the gateway request path. The configured base URL must produce the gateway’s supported Anthropic Messages path. A successful OpenAI-shaped compatibility route does not prove that the native Anthropic path is configured correctly.

Security checklist

Before publishing or sharing a configuration:

• No API keys, bearer tokens, cookies, OAuth data, or private keys.
• No kubeconfig, secret-manager exports, shell history, or raw logs.
• No internal hostnames, IP addresses, namespaces, service names, or cluster topology.
• No personal home-directory paths.
• No account identifiers or organization identifiers.
• Model IDs are placeholders unless they are intentionally public API identifiers.
• Credential helpers are referenced by path only and contain no secret values.
• The repository’s history has been scanned before it is made public.

References

• Claude Code model configuration
• Connect Claude Code to an LLM gateway
• Claude Desktop third-party configuration reference
• Claude Desktop in-app configuration
• Claude Desktop gateway deployment