Configure Claude Code

Claude Code is the client: run claude. The proxy translates its Anthropic Messages requests to the backend selected by the model ID. The Codex backend uses a ChatGPT subscription; the separate codex CLI is not required.

Install Claude Code, check claude --version, authenticate the chosen provider with the proxy, and keep claude-code-proxy serve running. Restart Claude Code after changing its endpoint or authentication configuration. Restart the proxy itself after updating its executable; see the upgrade check.

Claude Code with a Codex backend

Authenticate with claude-code-proxy codex auth login. Then launch:

ANTHROPIC_BASE_URL=http://127.0.0.1:18765 \
ANTHROPIC_AUTH_TOKEN=unused \
ANTHROPIC_MODEL='gpt-6-sol' \
ANTHROPIC_DEFAULT_OPUS_MODEL='gpt-6-sol' \
ANTHROPIC_DEFAULT_SONNET_MODEL='gpt-5.6-terra' \
ANTHROPIC_DEFAULT_HAIKU_MODEL='gpt-6-luna' \
CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000 \
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 \
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 \
  claude

This starts Claude Code on gpt-6-sol. Its opus, sonnet, and haiku choices use the three pinned backend IDs. Provider access depends on your account; check claude-code-proxy models for registered IDs.

Claude Code with Claude models through Cursor

Authenticate with claude-code-proxy cursor auth login, then inspect claude-code-proxy models --full. For example:

ANTHROPIC_BASE_URL=http://127.0.0.1:18765 \
ANTHROPIC_AUTH_TOKEN=unused \
ANTHROPIC_MODEL='cursor:claude-sonnet-5-thinking-high' \
ANTHROPIC_DEFAULT_SONNET_MODEL='cursor:claude-sonnet-5-thinking-high' \
ANTHROPIC_DEFAULT_OPUS_MODEL='cursor:claude-opus-5-5-high' \
ANTHROPIC_DEFAULT_HAIKU_MODEL='cursor:claude-haiku-5-5-high' \
CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000 \
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 \
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 \
  claude

These IDs were advertised by the observed Cursor account. Use IDs available to your account, or copy an exact gateway ID from /v1/models. The cursor: prefix keeps these requests on Cursor, including the background Haiku model. See Cursor Agent for parameter variants and tool support.

Gemini default with Opus and Grok through Cursor

Authenticate with claude-code-proxy cursor auth login, inspect claude-code-proxy models --full, and keep the proxy running. Then launch:

ANTHROPIC_BASE_URL=http://127.0.0.1:18765 \
ANTHROPIC_AUTH_TOKEN=unused \
ANTHROPIC_MODEL='cursor:gemini-4-argon[reasoning_effort=high]' \
ANTHROPIC_DEFAULT_SONNET_MODEL='cursor:gemini-4-argon[reasoning_effort=high]' \
ANTHROPIC_DEFAULT_OPUS_MODEL='cursor:claude-opus-5-5[context=1m,effort=high,fast=false]' \
ANTHROPIC_DEFAULT_HAIKU_MODEL='cursor:grok-4.7-high-fast' \
CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000 \
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 \
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 \
  claude

This starts the main conversation and Sonnet role on Gemini, assigns the Opus role to Claude Opus, and sends Haiku background work to Grok. All four selections route through Cursor. The role names describe Claude Code’s choices; they do not require matching model families.

These selections were present in the observed account catalog. Check claude-code-proxy models --full for your account before copying them. Availability can change: Gemini requests returned upstream HTTP 429 during the latest walkthrough, so that recording uses Cursor GLM 5.2 and Grok 4.7 instead. An advertised catalog entry alone does not establish inference access. The 200K compaction boundary is conservative, including when the selected Opus variant has a larger window.

Quote model values in shell commands, especially IDs containing brackets, commas, or other shell syntax. Preserve the exact advertised parameter names and values. Shell quotes protect the value; they are not part of the model ID. In JSON settings, use ordinary JSON strings without adding shell quotes.

Save a reusable settings file

Save this Codex backend example as claude-proxy.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:18765",
    "ANTHROPIC_AUTH_TOKEN": "unused",
    "ANTHROPIC_MODEL": "gpt-6-sol",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "gpt-6-sol",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "gpt-5.6-terra",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gpt-6-luna",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "200000",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK": "1"
  }
}

claude --settings ./claude-proxy.json

For either Cursor recipe, replace the four model values with the chosen cursor: IDs above. Use JSON strings for environment values, without shell quotes inside the strings. Merge the env entries into an existing file rather than replacing hooks, permissions, plugins, or other preferences.

Scope	Location or launch
One launch	claude --settings ./claude-proxy.json
Your sessions in one project	.claude/settings.local.json; add it to .gitignore if you create it by hand
Every local session	~/.claude/settings.json

The explicit --settings launch lets you keep your normal direct Anthropic configuration separate. Managed settings can still constrain model selection. See the official settings and precedence guide.

Connection and model settings

Claude Code variable	Purpose
ANTHROPIC_BASE_URL	The local proxy origin, such as http://127.0.0.1:18765, without /v1.
ANTHROPIC_AUTH_TOKEN	Claude Code sends this as a bearer token. unused satisfies the local client contract; inference routes do not validate this value or use it for upstream auth. The local setup UI requires its separate management key.
ANTHROPIC_MODEL	The initial model ID, which the proxy routes to its backend.
ANTHROPIC_DEFAULT_OPUS_MODEL	The backend ID for Claude Code’s opus choice.
ANTHROPIC_DEFAULT_SONNET_MODEL	The backend ID for its sonnet choice.
ANTHROPIC_DEFAULT_HAIKU_MODEL	The backend ID for its haiku choice and Haiku background work. This replaces deprecated ANTHROPIC_SMALL_FAST_MODEL.

Only the endpoint, a client credential, and a routable model are needed for a basic launch. Pinning role models makes alias and background requests explicit. An existing ANTHROPIC_API_KEY, credential helper, or provider-selection setting can affect client authentication; keep the launch consistent with your intended backend. Provider login tokens belong to the proxy, independently of the local placeholder.

Optional client settings

Variable	When to use it
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1	Populate /model from the proxy’s /v1/models catalog.
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1	Avoid a non-streaming fallback after a broken stream, which can duplicate tool execution through a proxy.
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1	Opt out of updates, telemetry, and other nonessential traffic. It also disables feature-flag fetching and account skill/plugin sync; omit it if you need those features. Local hooks, skills, and plugins remain configured normally.
CLAUDE_CODE_SUBAGENT_MODEL	Choose a routable default for subagents. Explicit agent or invocation model choices can take precedence.
ANTHROPIC_DEFAULT_FABLE_MODEL	Pin the fable role if you use it; choose an ID available through the intended backend. The examples above pin the three classic roles only.
API_TIMEOUT_MS	Adjust the client’s response-header timeout when a backend needs longer to start responding.

The proxy can still accumulate a non-streaming response when explicitly requested. Disabling the client’s fallback does not remove that API support. Claude Code Remote Control is unavailable with a custom ANTHROPIC_BASE_URL, independently of the traffic opt-out flag.

Context and compaction

The recipes omit [1m] and maximum-context overrides, and set a conservative 200K compaction boundary. Do not infer an upstream context limit from the word Codex, a Claude role, or a display label. A trailing [1m] is a Claude Code context hint; it does not expand the backend’s window.

For an unrecognized custom ID without [1m], Claude Code normally assumes a 200K window. It may recognize Claude names inside a gateway ID and assume that Claude model’s native window instead. Check the actual upstream selection before changing the client policy.

For example, the verified Cursor Sonnet recipe resolved to a 300K upstream selection while Claude Code reported a 1M window. The earlier 200K compaction boundary keeps that client assumption from delaying compaction beyond the selected upstream limit. Raise the boundary only after checking the actual selection, including the model used for background work.

CLAUDE_CODE_AUTO_COMPACT_WINDOW sets an earlier compaction boundary; for example, 200000 caps it at 200K tokens. CLAUDE_CODE_MAX_CONTEXT_TOKENS can declare a custom model’s window, but its applicability depends on how Claude Code recognizes the ID. Follow the official gateway context guidance. Keep automatic compaction enabled unless you deliberately accept reaching the upstream limit.

Direct Claude through Anthropic

For a direct Anthropic session, start Claude Code with your normal Anthropic authentication and without proxy endpoint, placeholder credential, or backend model overrides in either the shell or settings:

claude --model sonnet

This bypasses the proxy. This application has no direct Anthropic upstream provider. Unqualified recognized claude-*, sonnet, opus, and haiku IDs sent to the proxy are compatibility aliases, routed through aliasProvider (Codex by default). Pin the aliases you use to explicit backend IDs; an unpinned alias can otherwise select that configured provider. See Switching models and backends.

Verify the launch

In Claude Code, run /status to inspect the session and loaded setting sources, then /model to inspect available choices. Send a short prompt and check the proxy monitor for the requested model and backend. A listed model or successful login alone does not establish inference access.

The official model configuration and environment variable reference describe Claude Code’s client behavior. CCP_*, PORT, and the proxy’s config.json configure the server process, independently. See Configuration for those settings.