Model gateway accounts
A model gateway account is an owned Claude or Codex account bound to one metered model gateway: OpenRouter, Vercel AI Gateway, Cloudflare AI Gateway, Requesty, Portkey or an operator-supplied LiteLLM proxy. Sessions launched with it use the gateway instead of a Claude or ChatGPT subscription.
Configuration
Add a Claude or Codex account to the execution host as usual (no provider
sign-in is needed), then open Accounts, select that owned account and press
P (Model gateway). Choose a preset, enter the API key in the masked field,
list the allowed models and the default model, and optionally set a monthly
budget in USD. Claude accounts can also map the Opus, Sonnet and Haiku tiers.
A Claude account uses the gateway's Anthropic Messages surface. A Codex account
uses its OpenAI Responses surface, because Codex custom providers support only
wire_api = "responses"; presets without a documented Responses endpoint are
not offered for Codex.
| Preset | Base URL | Anthropic Messages (Claude) | OpenAI Responses (Codex) | Chat Completions | Key header |
|---|---|---|---|---|---|
| OpenRouter | https://openrouter.ai/api (fixed) |
/v1/messages |
/v1/responses |
/v1/chat/completions |
Authorization: Bearer |
| Vercel AI Gateway | https://ai-gateway.vercel.sh (fixed) |
/claude-code/v1/messages |
/v1/responses |
/v1/chat/completions |
Authorization: Bearer |
| LiteLLM | operator HTTPS URL | <base>/v1/messages |
<base>/v1/responses |
<base>/v1/chat/completions |
Authorization: Bearer |
| Cloudflare AI Gateway | https://gateway.ai.cloudflare.com/v1/<account_id>/<gateway_id> |
<base>/anthropic/v1/messages |
not documented | <base>/compat/chat/completions |
cf-aig-authorization: Bearer |
| Requesty | https://router.requesty.ai (fixed) |
/v1/messages |
/v1/responses |
/v1/chat/completions |
x-api-key (Messages), Authorization: Bearer (others) |
| Portkey | https://api.portkey.ai (fixed) |
/v1/messages |
/v1/responses |
/v1/chat/completions |
x-portkey-api-key |
Model names follow each gateway's own catalog: provider/model for
OpenRouter, Vercel, Requesty and Cloudflare's unified endpoint (for example
anthropic/claude-sonnet-4-5), native Anthropic names on Cloudflare's
/anthropic endpoint, LiteLLM model aliases, and Portkey Model Catalog IDs
@provider-slug/model. The broker forwards the exact allowed name; it does not
rewrite model IDs.
Preset notes, from the providers' documentation:
- Cloudflare AI Gateway: enter the gateway base URL with your account ID and
gateway ID. The stored key is the gateway's authentication token, sent as
cf-aig-authorization. Provider keys must be stored in the gateway (BYOK) or covered by Unified Billing; the broker never sends a separate provider key. If the gateway requires provider credentials and none is stored, Cloudflare answers with error 2044. Cloudflare documents no Responses endpoint for the gateway, so it is available for Claude accounts only. - Requesty: the global router is used; the EU router
(
router.eu.requesty.ai) is not selectable yet. - Portkey: the stored key is the Portkey API key. Use Model Catalog IDs
(
@provider-slug/model) so no provider header or virtual key is needed. Self-hosted Portkey gateways are not selectable.
An operator base URL (LiteLLM, Cloudflare) must be HTTPS on port 443, with a DNS
hostname and no credentials, query, fragment or trailing /v1. IP literals,
localhost, .local and .internal names are refused, and the Cloudflare URL
must have exactly the documented host and /v1/<account_id>/<gateway_id>
path. The single upstream host is shown as upstreamHost and is the only
destination the controller broker contacts for that account.
The API key is stored as an encrypted controller secret
(model-gateway:<accountId>). It is never returned by the API, never written
to the snapshot or audit log, cannot be granted to a workspace and cannot be
edited through Secrets. An existing owned controller-only env secret can
be referenced instead through credentialSecretRef.
Routes, all owner-scoped:
GET /v1/accounts/:accountId/model-gatewayPUT /v1/accounts/:accountId/model-gateway(expectedRevision, write-onlyapiKey)DELETE /v1/accounts/:accountId/model-gateway(removes the managed key, keeps usage history)GET /v1/accounts/:accountId/model-gateway/usageGET /v1/accounts/:accountId/model-gateway/balance(optionalrefresh=1)
Sessions
At launch the controller issues a capability bound to the exact session, account, provider process generation and configuration revision.
Claude Code receives:
ANTHROPIC_BASE_URLpointing to the controller broker (/v1/model-gateway/anthropic)ANTHROPIC_AUTH_TOKENset to the capability, and an emptyANTHROPIC_API_KEYANTHROPIC_MODELandANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU}_MODELfrom the configurationCLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1; the broker answers/v1/modelswith the allowlist
User-supplied ANTHROPIC_*, Bedrock, Vertex, Foundry and OAuth-token
variables are discarded for these sessions.
Codex receives a custom model provider through -c overrides, which take
precedence over the managed profile and config.toml
(Codex configuration reference):
model_provider = "devctl_gateway"
model = "<default or selected allowed model>"
[model_providers.devctl_gateway]
name = "devctrl model gateway"
base_url = "<controller>/v1/model-gateway/openai/v1"
env_key = "DEVCTRL_MODEL_GATEWAY_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
DEVCTRL_MODEL_GATEWAY_KEY holds only the broker capability. User-supplied
OPENAI_*, AZURE_OPENAI_* and CODEX_API_KEY variables are discarded. The
broker answers GET /v1/model-gateway/openai/v1/models with the allowlist in
the OpenAI list format.
Saving or removing the binding revokes every issued capability.
The broker forwards anthropic-version, anthropic-beta, user-agent and
x-app, injects the upstream key in the preset's documented header, enforces
the model allowlist on /v1/messages, /v1/messages/count_tokens,
/v1/chat/completions and /v1/responses, refuses routing and credential
override fields, and streams responses unchanged. It sends one request with no
fallback or retry; Codex's own client retries arrive as separate requests and
are counted separately.
Schedule interpretation
The controller can also use a gateway account directly, without a session, to
convert schedule wording that its deterministic parser does not recognize into
cron rules (Schedulers). It sends one
non-streaming, tool-free request to the first configured surface of Chat
Completions, Responses or Anthropic Messages whose allowlist contains the chosen
model, with the same upstream URL, key header, allowlist, monthly budget and
administrator account locks as the broker. No capability is issued and no
retry or fallback is made. Usage is recorded under the label
scheduled-task-interpreter. Accounts with a proxy/VPN network route are not
used for these requests.
Usage and limits
The broker records, per account and session, the request count, failures,
input, output and cache tokens, and the cost reported by the upstream
(usage.cost or LiteLLM's x-litellm-response-cost). Prompts and responses
are not stored. A request without a reported cost adds no cost. When the
monthly reported cost reaches the budget, new requests are refused with HTTP 402.
Balance
The gateway editor shows the gateway's own balance where an official endpoint accepts the same key:
| Preset | Endpoint | Shown |
|---|---|---|
| OpenRouter | GET https://openrouter.ai/api/v1/key |
key limit, remaining limit, total and monthly usage, reset period |
| Vercel AI Gateway | GET https://ai-gateway.vercel.sh/v1/credits |
team credit balance and total used |
| LiteLLM | GET <base>/key/info (calling key) |
key spend, max budget, remaining, budget reset time |
| Cloudflare, Requesty, Portkey | none with the inference key | "no official balance endpoint" |
OpenRouter's account-wide GET /api/v1/credits requires a management key and
is not used; a key without a limit shows "no limit". Requesty's organization
balance is on its management API, not the inference router.
Balance reads are bounded: one in-flight request per account, a 10-second timeout, redirects refused, at most 64 KiB read, results cached for 5 minutes (1 minute after a failure) and an explicit refresh honored at most every 30 seconds. Only numeric amounts and the reset time are kept; key labels, user and organization IDs and error bodies are discarded and never logged. A refused key shows as unauthorized, any other failure as unavailable.
Gateway sessions are metered: they have no subscription quota windows and do not block on subscription quota. Claude artifacts and Claude Design need a Claude subscription and are unavailable; ChatGPT sign-in features are unavailable to Codex gateway sessions.
Limitations
Verification notes (2026-11-09): the LiteLLM preset ran through the real
controller service against a disposable LiteLLM proxy (HTTPS on port 443, with
a Postgres-backed virtual key) and a fake Anthropic upstream. GET /key/info
returned limitUsd: 2.5 and remainingUsd: 2.5. One Messages request was
relayed, and a forged capability and an unlisted model were refused. LiteLLM
sent no x-litellm-response-cost header for that route, so cost depends on
response usage. Hosted gateways (OpenRouter, Vercel, Cloudflare, Requesty,
Portkey) were not exercised. See local integration live tests (source access required).
- Delegated (shared) accounts and accounts with a proxy/VPN network route cannot use a gateway.
- Budget enforcement depends on the upstream reporting cost.
- The first launch of a never-signed-in account may show the client's onboarding screen once.
- Codex may warn about unknown model metadata for non-OpenAI model names.
- Only Claude Code and Codex are wired to the broker. Optional native clients keep their own credential handling.
- None of the presets, the Codex provider wiring or the balance endpoints were exercised against live gateway accounts; they follow the providers' documentation and are covered by fixture tests.