Model Gateway

model-gateway

Two local processes give Claude Code native access to the user's ChatGPT subscription models: claude-code-proxy (does OpenAI OAuth and translates Anthropic Messages API to the Codex backend) and a shim router this plugin owns. ANTHROPIC_BASE_URL points at the shim: requests for claude-gpt-* models are un-prefixed and go to the proxy, everything else passes through to api.anthropic.com with the user's normal claude.ai login. The shim's /v1/models advertises Codex models with a claude- prefix because Claude Code's model discovery drops ids that don't start with claude/anthropic. That prefix is shared with the real Anthropic ids, so the route is decided by the backend family segment (claude-gpt-*, claude-grok-*), never by the prefix.

All commands: node ~/.claude/model-gateway/model-gateway.js <command>. SessionStart recreates this stable launcher from Claude Code's installed-plugin registry, so it follows upgrades and falls back to an installed downgrade; it reports a missing install directly.

First-time setup

Project-local wiring is the standard setup. env --write-project writes the current project's .claude/settings.local.json, so the gateway stays configured for this project's sessions and executor worktrees without putting a machine-local endpoint in a committed file. setup uses the same project-local target by default.

env --write-user remains an opt-in shared fallback for people who deliberately want one gateway URL in ~/.claude/settings.json across every project. Claude Code gives a current project's settings.local.json higher precedence, so doctor marks the winner [effective], names both files, and says that project-local wiring wins when their gateway modes disagree.

The first-run order matters:

1. Install Model Gateway at the recommended project scope.
2. Reload plugins so the new skill is available.
3. Invoke this skill and run setup.
4. If setup says sign-in is needed, have the user complete login, then run setup again. The second setup finishes the download, wiring, and project confirmation.
5. After the project wiring is confirmed, tell the user to fully restart the Claude Code process for this same project before selecting a model.

A plugin reload alone does not reload settings or the picker cache. Do not tell the user to select a new row until that full restart is complete.

The SessionStart hook injects a one-line nudge while the gateway is in any half-configured state; act on it. The user sees that same line in the transcript, because a state only they can fix used to reach the model alone. Anything routine stays out of it, and the hook always exits 0 so the line survives: run ensure yourself when you need an exit code. SessionStart waits at most 12 seconds for a newly started gateway, then leaves its supervisor to finish in the background so it stays inside Claude Code's hook budget. setup is one-shot and idempotent: it downloads the claude-code-proxy binary (sha256-verified) and starts everything. Re-running it later is also the upgrade path. Worker hot-replacement accepts the current CLI or a non-older version-shaped sibling under the same lexical and resolved parent directory. This checks filesystem layout, not marketplace registration; a development layout with the same structure can also satisfy it.

Setup fails before extraction when the required checksum asset is absent, its download fails, its contents are invalid or name a different archive, or the archive digest does not match. Report the verification failure; never skip the checksum check or run the unverified download.

Use the bundled lifecycle commands for restarts and drains. They authenticate with the per-user ~/.claude/model-gateway/control-token file. Never print or copy this secret into a conversation, request body, or settings file. Browser-origin lifecycle requests are refused, and a replacement worker must be this CLI or a non-older sibling within the same resolved plugin cache. Development checkouts cannot hot-switch to unrelated installations. After updating, restart the calling Claude Code process to load the current control protocol. These controls do not authenticate inference requests to the separate proxy or protect against a process with the same OS-user access.

node ~/.claude/model-gateway/model-gateway.js setup
# only if setup says sign-in is needed:
node ~/.claude/model-gateway/model-gateway.js login    # browser OAuth; --device for headless
node ~/.claude/model-gateway/model-gateway.js setup    # finishes the wiring

login opens the user's browser; they complete it themselves (suggest ! node ... login if it needs a real TTY). env --write-project writes this project's .claude/settings.local.json. Use env --write-user only when the user wants a shared fallback across projects. If both are present, project-local wiring wins: doctor marks it [effective], names the shadowed user file, and fails when their gateway modes differ. All wiring changes apply to new Claude Code sessions, so restart after the write. The Codex rows appear in /model labeled "From gateway".

The winning ANTHROPIC_BASE_URL source follows Claude Code's precedence: process environment, current-project .claude/settings.local.json, project .claude/settings.json, then user ~/.claude/settings.json. A process export always wins, so settings writes cannot replace it.

When doctor or SessionStart says that process env shadows a wired settings file, Model Gateway is bypassed. If the user controls the Claude Code CLI launch, they can correct or unset ANTHROPIC_BASE_URL, then restart. If the host replaces that value, use the supported Claude Code CLI on the wired project instead. Model Gateway does not support Desktop routing under forced overrides on Windows or macOS, and settings, parent, or User-scope edits cannot be promised to win.

env --write-user --reconcile is confirmation-gated. Plain env --write-user writes the shared user fallback, then lists recorded projects whose local URL differs without changing their files. The confirmed command removes only Model Gateway-owned keys from those other projects' .claude/settings.local.json files: its base URL, the three Claude alias pins, and static gateway flags whose values equal plugin defaults. It leaves unrelated settings alone, skips projects already agreeing, cannot change process.env, and needs a restart to affect a new session. Discovery needs Claude Code v2.1.129+; models shows exactly what the shim advertises. Claude Code only refetches gateway discovery when it has an API-key credential. OAuth subscriptions do not give it one, so Model Gateway writes Claude Code's discovery cache whenever its advertised list changes, but only from a list the proxy answered. While the proxy is unreachable the shim serves models.json or its built-in list, keeps the previous cache, retries the proxy on its next refresh tick, and status says fallback catalog (proxy unreachable). setup --preserve-wiring (what the Toolshed updater runs) never wires the directory it runs from.

Restart remains necessary to surface new rows in /model: Claude Code reads the picker cache once at session start. /reload-plugins does not reload it. Restoring or refreshing auth on an already-wired install needs no restart of the current Claude Code process: the proxy is a separate process, so once login + setup re-authenticate it, the next request routes through cleanly. Settings, discovery-cache, plugin, or model-row changes do need a full restart of the affected project process. Keep these two recovery paths separate. The shim supervisor also probes the proxy's /v1/models endpoint while it runs, confirming a failed probe through a fresh connection before restarting an unavailable proxy with single-flight bounded backoff. It leaves a healthy proxy alone. Recovery output remains in ~/.claude/model-gateway/logs/guardian.log; bounded lifecycle records in ~/.claude/model-gateway/logs/lifecycle.jsonl identify supervisor, worker, and proxy PIDs, orderly stop/restart requests, observed exits, and recovery outcomes. Use doctor to print the evidence path and the last observed exit. An OS termination or force-killed supervisor may leave no final record, so treat an absent exit record as absence of evidence, not a clean shutdown. Cleanup accepts a PID record whose start time matches even when the live command line is unavailable, and deletes a record only when a readable command line contradicts it; it never stops a reused PID. On Windows, an unavailable command line can mean the process is elevated, so doctor names the condition and stop or setup must run from a session with the same privileges. Proxy recovery stops a listener using the shared proxy binary only when the live process tree proves it descends from the recovering supervisor. A matching shared binary alone never proves ownership. A failed /v1/models check gets one fresh-connection confirmation before recovery can stop an owned listener; a healthy confirmation resets recovery without stopping or starting the proxy. This matters when an agent is mid-orchestration (e.g. dispatching Codex subagents through the gateway): do not tell the user to restart Claude Code just to bring auth back, or you kill the session that was about to use it.

Selecting models

• /model picker: rows like "GPT-6.1-sol (Codex)" and "Grok 4.5".

• Typed: /model claude-gpt-6.1-sol[1m] or /model claude-grok-4.5[1m]. The picker and Sidequest catalog emit those exact ids. The suffix is stripped before routing to Codex or Grok.

• lib/runtime.js's exported MODEL_WINDOW_POLICY is the sole authority for gateway backend windows, picker aliases, advertised windows, and sentry mode. GPT-6.1 Sol, GPT-5.6 Sol, Terra, Luna, and GPT-6 Astra are measured rows. GPT-6.1 Sol is the default Codex model; GPT-6 Astra is reserved for frontier or high-stakes tickets. GPT ids absent from the table are deliberately advertised through its explicitly unmeasured 920k default, rather than silently inheriting a window. Grok 4.5 is a measured 500k row with a [1m] picker alias and the shared synthetic-413 sentry.

• Codex GPT-5.6 through the ChatGPT Codex product (the subscription login this gateway routes to, not the pay-per-token API) accepted 920,012 input tokens and refused 935,012 on 2026-09-05 through claude-code-proxy 0.1.35 (upstream 55bf0b58). Every synthetic-413 policy row keeps its backend-window-minus-40000 ceiling. With no saved compactAt, the lowest legacy environment trigger or cap-minus-85000 wins. With compactAt.codex or compactAt.grok saved, the explicit maximum replaces those legacy candidates, is clamped to the cap, and ignores CODEX_GATEWAY_COMPACT_TRIGGER without mutating it. Claude Code 2.1.261 ignores a settings-file CLAUDE_CODE_MAX_CONTEXT_TOKENS value for its own unrecognized-model resolver, so rows above 200k use their policy's recognized [1m] alias. That alias gives Claude Code a 1M client window, the closest available setting to the verified 920k backend window; it does not promise a 1M backend input limit. A lower explicit autoCompactWindow still wins. Use /context to inspect the selected model and effective cap.

• Context window and cost: context-window saves backend windows in ~/.claude/model-gateway/context-window.json (--claude <tokens|full> --codex <tokens|full> --grok <tokens|full>). Defaults stay Claude full, Codex 272000, Grok full; existing installs are never auto-migrated. /v1/models advertises the cap and keeps [1m] ids. With no explicit maximum, the gateway's legacy cap policy subtracts 85000, so Codex still compacts past 187000.

• Direct gateway compaction maximum: context-window --codex-compact-at <tokens|cap> and --grok-compact-at <tokens|cap> save positive whole counts under compactAt; cap removes the explicit field and restores the legacy policy. These flags have no 100000 floor. Window-only updates preserve saved maxima. An explicit maximum has no hidden 85000 subtraction; the cap and actual backend window minus 40000 remain authoritative. status, doctor, and catalog notes report the requested and effective trigger, actual backend window, limiting source, and any ignored CODEX_GATEWAY_COMPACT_TRIGGER unchanged. --codex-compact-at 242000 is an opt-in example that leaves the 272000 cap unchanged. OpenAI bills input above 272k at 2x; the crossing turn and compaction request can still exceed 272k and pay double. Never promise this example keeps every request below the billing boundary.

• Native Claude window: preserve --claude <tokens|full> and existing gateway-owned autoCompactWindow synchronization to project-wired .claude/settings.local.json; numeric windows require project-scoped wiring. Native engine headroom and exact trigger are unverified. --claude-compact-at and compactAt.claude are unsupported and refuse without writing. Same-model main/subagent thresholds are unverified; use one backend policy with no role inference. A lower native session window can bound gateway models too. After deliberately adopting a change, restart the gateway (stop, then ensure) and restart open Claude Code sessions for native-window or picker changes. No automatic 242000 adoption, machine environment mutation, or worker restart during implementation. CODEX_GATEWAY_CONTEXT_WINDOW still applies only when no Codex window is saved.

• Claude models (opus/sonnet/fable, with or without [1m]) keep their OWN separate native windows and compaction limits: the shim forwards their requests byte-identically to Anthropic and never applies Codex window advertisement or error rewriting to them. The env block pins the current real 1M aliases (Opus, Sonnet, Fable) to [1m] ids so a gateway session on one gets its full 1M window instead of the 200k gateway default; Haiku stays unpinned (it's 200k). An env --write-* command resolves those aliases through the installed Claude CLI's credential-free headless probe; SessionStart refreshes its cache after the CLI changes or the cache ages out, and rewrites stale pins it wrote, including in a project where the gateway was turned off for Remote Control. A failed probe keeps the last good pin, then a shipped safe default. A detected alias older than the shipped default, or one the plugin retired, loses to the shipped default. Set a persistent per-alias override with pin --opus claude-opus-5-5[1m] (same for --sonnet and --fable), or use pin --opus default to return to auto-detection. Overrides always win. pin with no arguments and doctor show each effective pin, whether it is overridden, and which lagging CLI alias a shipped pin replaced. Overrides live in ~/.claude/model-gateway/pins.json, outside the plugin cache. A pin change, and every SessionStart pin refresh, updates every registered wired project's gateway-owned pins (so a new shipped default reaches them too) and skips any project with a user-owned pin value. Restart every open Claude Code session in an affected project; changing a saved value cannot alter an open session.

• Do NOT set a global CLAUDE_CODE_AUTO_COMPACT_WINDOW: it applies to both providers and can make Codex /compact fail after history already exceeds the Codex limit.

• Caution: loading a huge reference skill (e.g. claude-api, ~800k chars) in a single turn can spike Codex context past the point proactive compaction can recover from. Prefer pulling large references incrementally on Codex models.

• The advertised catalog comes from the proxy's /v1/models; models.json and the built-in list only stand in while the proxy is unreachable. A models.json file cannot add a backend that the claude-code-proxy allowlist does not support; update the proxy through setup instead.

• Claude Desktop cannot use Codex/Grok models in this version: Desktop has its own native Gateway configuration, separate from Claude Code CLI settings, and can point at this shim's endpoint. But installed Desktop 1.49585.0 validates every Gateway model ID client-side and rejects any gpt/codex/non-Anthropic family marker before it reaches the picker or a session, whether the ID came from an explicit config entry or from discovery; a terminal [1m] is stripped first and does not change the outcome. Only a genuinely Anthropic-backed route (a real Claude alias) is usable there. This is a Desktop-side restriction, not a Model Gateway bug, and there is no supported workaround: do not suggest an Anthropic-named alias to disguise a Codex/Grok route, patch the Desktop binary, substitute credentials or auth, intercept TLS, or use a global env or hosts trick. Tell the user Desktop end-to-end Codex/Grok support is not available on this version; the Claude Code CLI is the verified path. VS Code success has been reported by users but is not independently verified here. This is version-specific and can be revisited if a future Desktop release removes the model-family filter.

• RC-compat and missing Codex rows: On inspected Claude Code 2.1.267, RC-compatibility points ANTHROPIC_BASE_URL at api.anthropic.com, which disables gateway model discovery. The rows disappear and cache refresh cannot restore them. Claude Code can accept and persist /model claude-gpt-5.6-terra[1m], but that client-side action does not prove a later request reaches the gateway. The current cleaner preserves canonical [1m] ids; do not present it as a fix for a reported request error. RC-compatibility makes Claude Code treat the gateway as first-party and can enable experimental message threading. The shim refuses Codex/Grok thread continuations locally with HTTP 400 because those backends have no conversation state. Nothing is forwarded or rerouted. A recognizing client drops the threading beta and resends the full message history. This is version- and experiment-limited, so do not promise one refusal per session. Normal gateway mode is the verified inference path. The reported 2.1.259 client and inspected 2.1.267 client have no verified end-to-end RC result: inspected session creation uses HTTPS while compatibility transport is HTTP. A detected hosts entry or bound listener proves local HTTP transport only. Sidequest dispatch is unaffected because it resolves its explicit route marker and never uses picker discovery.

• Claude models keep working normally at the same time (passthrough path). That does not mean a subagent invocation can mix in a gateway id freely: the Agent tool's own model parameter is a fixed host enum (sonnet/opus/haiku/fable), independent of gateway or plugin state, and a gateway id passed there is refused. To route one subagent to a specific gateway model, give it a definition file instead, with a full gateway id in model: frontmatter, and omit model from the invocation so that frontmatter applies:

  ---
  name: luna-reviewer
  description: Reviews code changes using the GPT-5.6 Luna gateway model.
  model: claude-gpt-5.6-luna[1m]
  tools: Read, Grep, Glob
  ---
  
  Review the diff for correctness and report findings.

  Save that as .claude/agents/luna-reviewer.md and start a new session before invoking it — definitions are read at session start, so a running session won't see one just added. Invoke with subagent_type: "luna-reviewer" and no model argument. This needs only Model Gateway, not Sidequest: a concrete gateway id needs no route marker, only Sidequest's own claude-codex-auto id does. Never edit Claude Code's built-in model aliases, the Agent tool schema, or the host binary — none of that is supported or necessary. This frontmatter contract and Model Gateway's routing for a concrete id are confirmed; an end-to-end custom-agent spawn through this path has not been verified here.

• Codex schema compatibility: Codex rejects some Unicode property escapes such as \p{Cc} and \P{Cf}. After deferred hydration, the shim changes only a Codex-bound provider hint, never Claude Code's host schema or an Anthropic request. It admits a missing dialect or Draft 2020-12 and only pattern instances reached through properties, compatible patternProperties values, additionalProperties, items, prefixItems, allOf, anyOf, dependentSchemas, propertyNames, or unevaluatedProperties/unevaluatedItems. Each real property atom must stand alone in a negated character class without ranges, set syntax, captures, backreferences, or a negative regex context. The shim removes only that atom and preserves every other regex byte. not, conditionals, oneOf, contains, references, definitions, content schemas, affected pattern-property keys, unknown containers, and unsafe regexes refuse locally with HTTP 400 naming the tool, JSON Pointer, and reason code. Tell the user it was not forwarded or rerouted. Do not claim arbitrary schemas are preserved or try to bypass that diagnostic.