Skip to content
opencodex

Providers

A provider is one upstream LLM endpoint plus how to reach it: an adapter, a base URL, an auth mode, and an optional model list. Providers live under providers in ~/.opencodex/config.json.

The dashboard provider Overview separates connection details, account usage and editable notes. Notes appear once, below the connection and authentication sections. Supported sponsor presets also show a short introduction, a Sponsor label and links to the provider’s site or console. These links preserve the preset’s referral parameters. Sponsor information is shown only when the configured provider name, adapter and endpoint match the preset; it never changes routing, account selection or defaults.

OpenAI account modes

Section titled “OpenAI account modes”
Provider id Use Credential/account rule
openai Codex login Pool(default) selects main plus added accounts; Direct uses the current caller/main login only.
openai-apikey OpenAI API Configured API key/key pool only; never reads Codex accounts.

Use bare gpt-5.6-sol with the Pool/Direct option on the Providers page, or openai-apikey/gpt-5.6-sol for API. The credential routes never fall through into one another. The API route publishes 1,050,000 context / 922,000 max input metadata. Its sol-pro, terra-pro, and luna-pro virtual ids keep their selected public identity while the wire uses the base model plus reasoning.mode: "pro".

If the built-in openai provider is missing or disabled, the dashboard Accounts picker and Codex Auth page can restore it: absent rows are created from the canonical preset, disabled canonical rows are re-enabled without replacing saved mode or model settings, and noncanonical openai rows are not offered that recovery path.

Luna Reserve compatibility is a ChatGPT account capability on the canonical OpenAI forward path, not an OpenAI API-key entitlement. Its manual stored-main selector requires effective local authless Desktop mode and current credential-bound upstream permission; a catalog entry alone does not authorize a request. See Luna Reserve alongside routed models for setup, restart order, authorization requirements, and unsupported helpers.

For adding an account with exhausted quota and finishing its deferred validation, see Codex account warmup.

Providers overview pool capacity

Section titled “Providers overview pool capacity”

For Codex login in Pool mode, the Providers overview shows a configured-weight estimate of the pool’s used capacity rather than presenting one arbitrary account as the provider total. The same row also shows the current effective account’s raw quota percentage, so you can distinguish the pool estimate from the account that a new request would use.

When reset information is available, the overview shows the next reset time and the capacity that reset is expected to recover as +N% pool capacity. Incomplete coverage means one or more pool accounts could not safely contribute to the estimate, for example because their plan or quota is unknown, their reading is stale, or the account is paused or needs reauthentication.

A partial window coverage warning means some included accounts reported one quota window but not another. The overview keeps those windows separate and marks each affected window incomplete instead of treating the missing reading as usage for that window.

This estimate is display-only. It does not change account selection, session affinity, automatic switching, cooldowns, or any other routing decision. Use the Codex Auth account pool for the individual account state and routing controls.

Shipped v1 configs migrate automatically to marker 2 and one option-aware row. The original config is retained once at ~/.opencodex/config.json.pre-openai-tiers-v2.bak; restore it with cp ~/.opencodex/config.json.pre-openai-tiers-v2.bak ~/.opencodex/config.json.

Auth modes

Section titled “Auth modes”

Provider configs accept three authMode values (key is the default). The built-in registry also labels local presets separately; those normally omit both authMode and apiKey.

authMode How it authenticates Used by
key Sends your API key (Authorization: Bearer …, or x-api-key / api-key per adapter). The key may be a literal or an ${ENV_VAR} reference. Most providers.
forward Relays your incoming Codex auth headers verbatim to the provider — no key stored. This is the ChatGPT-login passthrough. OpenAI (openai-responses adapter).
oauth Resolves a stored OAuth access token (auto-refreshed before expiry) and uses it as the bearer key. xAI, Anthropic, Kimi, Kiro, Google Antigravity, Cursor, Command Code, GitHub Copilot, Nous Portal.

The retryOn429 same-key 429 replay applies only to API-key providers (authMode: "key"). OAuth, forward, and local presets are excluded — their credentials must never be replayed on the same token, and local runtimes have no remote key to preserve. It is opt-in: when the option is absent the feature is off; object presence enables it unless enabled: false.

Which account a request spends

Section titled “Which account a request spends”

The question people ask before connecting an account is whether opencodex will draw on the subscription that login already pays for, or bill a separate API account. The answer follows the authMode above rather than the vendor’s marketing tier.

  • forward — the ChatGPT login. The request carries your Codex credential, so it spends the ChatGPT plan behind that login and reports that plan’s Codex quota windows. Which windows exist is plan-dependent: not every plan has a five-hour window. It never reads an API key.
  • oauth — a subscription login. The request carries a stored access token, so it spends whichever account you logged in as, and opencodex reports whichever usage windows that provider exposes.
  • key — the request carries the key you supplied, so usage lands on the account that owns that key, on that key’s own terms. That is metered usage for a pay-as-you-go API account, but a plan allowance when the key is a subscription: Z.AI GLM Coding Plan, Kimi Code, the BigModel coding plan, Command Code and CodeBuddy all sell one that way.

A request uses exactly one of these, and opencodex does not fall back from one to the other. When an OAuth credential cannot be resolved the request fails with an authentication error instead of reaching for a stored key, and the key-pool failover that answers a 429 or a 401 is refused outright for OAuth and forward providers.

Two exceptions are worth knowing because you can hit them:

  • xai and github-copilot accept authMode: "key" on the same provider id, and if that provider already had a key stored, running ocx login for it can leave it in key mode rather than switching it to the subscription. What that changes differs: an xai key retargets the provider to https://api.x.ai/v1, so a different account pays, while a github-copilot key is still a Copilot credential against api.githubcopilot.com, so the Copilot subscription pays either way.
  • orcarouter-oauth is a consent flow that mints a user-owned sk-orca-… API key. Once it has, the request carries a key, so it follows the key rule above.

Providers that accept both a login and a key

Section titled “Providers that accept both a login and a key”
Provider Subscription login API key
OpenAI / ChatGPT openai — Codex login; spends the ChatGPT plan behind it openai-apikey — a separate provider; usage lands on the OpenAI Platform account that owns the key
Anthropic ocx login anthropic — signs in as your Claude account. opencodex reads its five-hour and seven-day usage windows; that endpoint reports no subscription tier anthropic-apikey — direct Anthropic API billing, no Claude subscription
xAI ocx login xai — the Grok CLI subscription gateway. opencodex reads SuperGrok weekly credits, or the monthly pool the same xai provider with authMode: "key", which targets https://api.x.ai/v1, so usage lands on that API account
Kimi ocx login kimi — log in with your Kimi account kimi-code — the API-key form of the same Kimi Code Plan transport
Command Code ocx login command-code — opencodex reads five-hour and weekly windows plus a credit balance commandcode — the same service on /provider/v1 with a key
GitHub Copilot ocx login github-copilot — requires an active Copilot subscription the same github-copilot provider with authMode: "key". The device flow above is the supported path, and either credential is a Copilot one, so the subscription still pays
OrcaRouter ocx login orcarouter-oauth — consent mints a user-owned, long-lived sk-orca-… key, and the request then carries a key orcarouter — the same key pasted by hand
Meta Muse ocx login meta-muse imports the Muse Code CLI key. Meta scopes that credential to its own CLI, so this is an unsupported use: how the calls settle is not observable from the API, and you should treat every call as billable against your account meta-model is the supported path — every call is metered per token, and a Muse Code subscription does not work there

Cursor, Kiro and Nous Portal are login-only and have no API-key equivalent. Google Antigravity is login-only too: ocx login google-antigravity signs in with your Google account over the Cloud Code Assist wire, and the google preset beside it is the AI Studio Gemini API — a different product reached with its own key, not a key mode for the same login.

To check which mode a provider is actually using, open it on the Providers page: the Connection block’s Authentication row reads OAuth, API key, ChatGPT passthrough, Local, or No key needed. It is a provider-level setting, so the account rows below it do not repeat it.

1. ChatGPT login (forward / passthrough)

Section titled “1. ChatGPT login (forward / passthrough)”

The openai provider needs no API key. Direct forwards credentials from your existing codex login; Pool resolves a main or added Codex account before using the same backend:

{
  "openai": {
    "adapter": "openai-responses",
    "baseUrl": "https://chatgpt.com/backend-api/codex",
    "authMode": "forward"
  }
}

Only a curated set of headers is forwarded (FORWARD_HEADERS: authorization, ChatGPT account id, OpenAI beta/originator/session — see Adapters). This path is also what powers the web-search and vision sidecars.

The ChatGPT passthrough catalog also layers in the bare GPT-5.6 Sol/Terra/Luna slugs (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna) for accounts that can use them.

2. Account login (OAuth)

Section titled “2. Account login (OAuth)”

Provider presets can use account login — including GitHub Copilot via an experimental unofficial device-flow bridge. opencodex stores their credentials in ~/.opencodex/auth.json; refreshable tokens are refreshed automatically, while durable keys are reused until the provider revokes them. ocx login codex is accepted as well, but it is not one of these providers: it routes to the Codex account pool — the same flow as ocx account login codex, which keeps its own account ledger and needs a running proxy. chatgpt and openai are aliases of that route.

Terminal window
ocx login xai          # xAI Grok
ocx login anthropic    # Anthropic Claude (Pro/Max)
ocx login kimi         # Moonshot Kimi
ocx login nous         # Nous Portal (device grant; free + paid models)
ocx login kiro         # import kiro-cli credentials (or token fallback)
ocx login google-antigravity
ocx login cursor       # standalone Cursor PKCE login
ocx login command-code # Command Code browser OAuth (or import ~/.commandcode/auth.json)
ocx login orcarouter-oauth # OrcaRouter browser consent + PKCE
ocx login devin       # Cognition/Devin: import Devin CLI credential, else Auth0 browser sign-in
ocx login github-copilot  # GitHub device flow → Copilot token (Copilot Pro/Business)
ocx login codex        # Codex account pool (aliases: chatgpt, openai; needs a running proxy)
ocx logout <provider>
Provider Adapter Base URL Notes
xai openai-chat https://cli-chat-proxy.grok.com/v1 OAuth uses the separate Grok CLI subscription gateway. The API-key override uses https://api.x.ai/v1 and may inject Priority Processing. Live-first Grok catalog; grok-4.5 is the fallback default.
anthropic anthropic https://api.anthropic.com Claude models; live model list fetched from /v1/models.
kimi openai-chat https://api.kimi.com/coding/v1 Kimi K2.7/K2.6/K2.5 coding models.
nous openai-chat https://inference-api.nousresearch.com/v1 Nous Research subscription gateway (same backend Hermes Agent uses). Device-grant login against portal.nousresearch.com; the access token is the per-request inference JWT. Mixed paid + :free model catalog (tencent/hy3:free, stepfun/step-3.7-flash:free, …) discovered live from the signed-in account. Refresh tokens are single-use and rotated on every refresh.
kiro kiro https://runtime.us-east-1.kiro.dev Initial login imports the installed, signed-in kiro-cli session (on Unix, install with curl -fsSL https://cli.kiro.dev/install | bash; on Windows PowerShell, use irm 'https://cli.kiro.dev/install.ps1' | iex; then run kiro-cli login). Add account logs kiro-cli out, starts a fresh browser login that switches the account used by kiro-cli, and stores account-scoped profile metadata. Existing OpenCodex accounts are preserved, and cancellation or failure restores the previous kiro-cli session.
google-antigravity google https://daily-cloudcode-pa.googleapis.com Google OAuth over the Cloud Code Assist wire. Live discovery uses CCA’s authenticated v1internal:fetchAvailableModels endpoint and publishes the agent models available to the signed-in account; the maintained catalog remains the fallback.
cursor cursor https://api2.cursor.sh Experimental PKCE login, live HTTP/2 transport with an opt-in HTTP/1.1 compatibility path, and account-filtered model discovery.
orcarouter-oauth openai-chat https://api.orcarouter.ai/v1 Browser consent and key exchange use https://www.orcarouter.ai with S256 PKCE. The returned user-owned sk-orca-… API key is stored in the existing credential store and reused until revoked.
devin devin https://server.codeium.com Experimental unofficial Cognition/Devin bridge. Login first imports the credential the installed Devin CLI already holds (devin auth login writes a devin-session-token to its own credentials.toml); when none is present it opens Auth0 browser sign-in and exchanges the pasted token via Cognition’s RegisterUser for a long-lived API key. ocx login devin-cli remains as a deprecated alias. Models are discovered per account with GetCascadeModelConfigs. Not shown in the dashboard preset by default. Chat and usage reporting are verified against a live account across three models.
github-copilot openai-chat https://api.githubcopilot.com Experimental. GitHub device flow + copilot_internal exchange (VS Code OAuth client). Requires an active Copilot subscription; not an official third-party API.

Google Antigravity account and provider quota probes use fixed Google accounting endpoints, including the models fallback. They support transparent Fake-IP DNS for those destinations while retaining TLS verification, redirect rejection and private-address checks. A custom provider base URL changes model requests, not quota destinations; NO_PROXY continues to select the direct-route policy.

After a terminal Nous refresh failure, run ocx login nous to reauthenticate.

For the canonical Kimi Coding Plan presets (kimi account login and kimi-code API key), opencodex forwards only a caller-supplied stable prompt_cache_key to the Chat Completions request; it never generates one. Kimi documents a stable session/task key as required to improve Code Plan cache hit rates, while requests without a key remain keyless. If an opted-in upstream rejects the field, opencodex does not strip it and retry or mutate saved configuration. Other providers remain deny-by-default.

A custom openai-chat provider can opt in when its upstream documents support for prompt_cache_key:

{
  "providers": {
    "example-compatible-provider": {
      "adapter": "openai-chat",
      "baseUrl": "https://api.example.com/v1",
      "apiKey": "${EXAMPLE_API_KEY}",
      "promptCacheKey": true
    }
  }
}

The adapter forwards the key it is given and never invents one. It can still receive a key the caller did not send: Claude Messages translation derives one from metadata.user_id, or from a model/system/tools cohort when the client sends no metadata, because the OpenAI backends report cached_tokens: 0 for every keyless turn. So “forwarded, not fabricated” describes this adapter, not the whole request path.

Preserve the rest of the provider configuration when adding the option, then reload or restart opencodex. To validate caching, compare the initial cold request with later requests carrying the same stable key. Leave the option omitted or set it to false for incompatible upstreams, and disable or remove it if a strict gateway returns an HTTP 400 unknown-field error.

You can also start OAuth from the web dashboard.

Logging in from another browser profile, or another machine

Section titled “Logging in from another browser profile, or another machine”

When a login starts, the proxy opens the authorization URL on its own machine, using the OS default browser — and therefore the default profile. That is the right behavior for a local desktop and the wrong one in two common cases: you need a different browser profile (a work identity, a second account), or the dashboard is open against a proxy running somewhere else.

Every login surface shows the authorization URL with a copy button, the device code when the provider issues one, and a field to paste the redirect URL or authorization code back. So you can always finish a login by hand.

To stop the proxy from opening a browser at all, tick Don’t open a browser on the proxy machine beside the login button, or set it permanently:

{ "oauthOpenBrowser": false }

Absent and true both open, so nothing changes for an existing install; only an explicit false declines. POST /api/oauth/login and POST /api/codex-auth/login also accept a per-request openBrowser boolean that overrides the stored setting for that login.

Two cases behave differently, and it is worth knowing which you are in:

  • A different browser profile on the same machine works with the copied link alone. The loopback callback on 127.0.0.1 still completes the flow.
  • A browser on a different machine also needs the paste fallback, because the redirect URI is still http://127.0.0.1:<port>/callback on the proxy’s host. Finish the login there, then paste the redirect URL (or just the code) back into the dashboard or ocx account code.

Device-code providers never open a browser from the proxy in either case: they show a code and a verification URL to open wherever you are signed in.

Multiple OAuth accounts

Section titled “Multiple OAuth accounts”

OAuth providers whose credentials include a stable account id or email can keep more than one login. The Providers page shows those accounts in a dropdown, lets you add another, and switches the active account without logging the others out. A normal login with an identity-less Kimi credential replaces the active slot, while an explicit Add account preserves that slot and activates a new, distinct one. Kiro accounts are keyed by profile ARN. chatgpt is always single-slot because Codex pool accounts have a separate ledger. Tokens stay in ~/.opencodex/auth.json; /api/oauth/accounts returns masked metadata only.

Cockpit Tools Antigravity import

Section titled “Cockpit Tools Antigravity import”

For v1, OpenCodex imports only a Cockpit Tools Antigravity JSON export for the google-antigravity provider. In the Providers dashboard, choose the local JSON file from that provider’s Accounts tab. The dashboard does not show the file contents or credential values; it reports only imported, updated, failed, and unsupported counts. Other Cockpit providers are rejected in v1.

The CLI accepts the export from a file or standard input only — never paste it into a command argument:

Terminal window
ocx account import google-antigravity --format cockpit-tools --file <path> [--json]
cat accounts.json | ocx account import google-antigravity --format cockpit-tools --stdin [--json]

Inline JSON and extra positional arguments are rejected. Keep exported files private and delete or store them securely after import.

OAuth reliability

Section titled “OAuth reliability”

opencodex coordinates token refresh and Codex pool routing so concurrent requests do not race the credential store. This is reliability and diagnostics work — it does not guarantee protection from provider enforcement, rate limits, or account actions.

Refresh coordination. Before a routed call, an expired access token is refreshed once per (provider, account):

  1. In-process single-flight — concurrent callers share one refresh promise.
  2. Per-account file lock — cross-process writers serialize on the same account.
  3. Generation CAS — persist only when the stored credential generation still matches; a newer writer wins, and an older refresh result cannot overwrite it.

Terminal refresh failures mark the account as needing reauthentication instead of retrying forever.

Cooldowns (Codex pool). Upstream 429 / quota responses set a hard cooldown from Retry-After, quota reset headers (capped), or a short default backoff. Accounts on an explicit Retry-After cooldown are not probed early; reset-derived cooldowns may receive a paced probe lease so recovery can be detected without flooding the provider. Reset-derived native-model cooldowns keep shared native quota (including GPT-5.6 Terra/Luna) separate from gpt-reserve. Models in the shared group still protect one another; an ordinary success cannot clear a Reserve cooldown. Explicit Retry-After and default cooldowns always remain account-wide.

Session affinity. Codex thread→account affinity is process-local (in-memory only; not persisted across proxy restarts). On credential failures (401 / 403) the account is quarantined for reauth and affinities for that account are cleared. On 429, the account enters cooldown, affinities are cleared, and pool selection may rotate — threads are not pinned through a rate-limit response.

Codex client metadata. The ChatGPT forward path passes through the curated FORWARD_HEADERS allowlist (authorization, chatgpt-account-id, originator, session/thread ids, and related Codex headers — see Adapters). Pool mode overwrites only auth and chatgpt-account-id to match the selected credential. opencodex does not fabricate official client identity (for example originator, session, or thread headers) when the caller did not send them.

For account-switch compatibility diagnosis, enabling provider debug (ocx debug provider on) adds one [ocx:codex:affinity] line per canonical ChatGPT forward response. The line contains header presence, coarse size buckets, process-local HMAC equality tags, safe summaries of known top-level turn fields, and a count of unknown turn fields. It never includes raw credentials, account ids, attestation values, thread/session ids, turn metadata, or request bodies; the tags intentionally change after every proxy restart. Use ocx debug provider logs -f while reproducing the two requests, then run ocx debug provider off. This capture is observation-only and does not strip metadata, retry a request, switch accounts, reset a thread, or otherwise affect routing.

Diagnostics and reauth. Human ocx status prints an OAuth health block (redacted account ids, no tokens). ocx doctor adds an OAuth reliability section with writable-store / single-flight checks and WARN rows that include a recovery Action. When an OAuth provider account needs reauthentication, run ocx login <provider> (or use Reauthenticate in the dashboard). Codex pool accounts are not one of those providers, but ocx login codex --reauth routes to their account-pool reauthentication, which the dashboard Codex account pool also performs. See ocx status / ocx doctor in the CLI reference.

Kiro credential import

Section titled “Kiro credential import”

Kiro login expects the Kiro CLI: on Unix, install it with curl -fsSL https://cli.kiro.dev/install | bash; on Windows PowerShell, use irm 'https://cli.kiro.dev/install.ps1' | iex; then sign in with kiro-cli login. Without a kiro-cli session, ocx login kiro falls back to a pasted access token or the KIRO_ACCESS_TOKEN environment variable.

The ocx login kiro import path searches the platform Kiro CLI stores and opens SQLite databases read-only. Two environment variables make the source and token row selection explicit:

  • KIROCLI_DB_PATH selects a nonstandard Kiro CLI SQLite database. The path must already exist; during this import path, opencodex does not create or modify the database, WAL, or SHM files.
  • KIROCLI_TOKEN_KEY selects the exact auth_kv token key when a database contains multiple otherwise ambiguous token rows. A missing selection fails login instead of guessing.

On Windows, import looks for %LOCALAPPDATA%\Kiro-Cli\data.sqlite3. Forced/add-account login also needs the local CLI binary: opencodex first uses PATH, then falls back to %LOCALAPPDATA%\Kiro-Cli\kiro-cli.exe and C:\Program Files\Kiro-Cli\kiro-cli.exe.

After a successful import, opencodex persists the imported credential to ~/.opencodex/auth.json. Keep these variables and the selected database private. Do not attach database files or raw login diagnostics to bug reports.

Add account is a separate write workflow: it snapshots the current session, logs kiro-cli out, and imports the fresh browser login. If the login is cancelled or fails, including while OpenCodex persists the credential, rollback replaces the Kiro CLI database and removes its current WAL, SHM, and journal sidecars before publishing the previous session snapshot.

Because that rollback is only possible from a snapshot, Add account refuses to sign kiro-cli out when a session store is present but cannot be captured (unreadable file, mismatched schema, or an ambiguous token selection), when KIROCLI_DB_PATH / KIRO_CLI_DB_FILE redirect import reads away from the live CLI store, or when an existing primary CLI database has no recognized token row. Repair or remove the unreadable database under the normal kiro-cli data path, unset those import selectors, then retry. Signing in from a machine with no existing kiro-cli session is unaffected.

3. API-key catalog

Section titled “3. API-key catalog”

opencodex ships 79 built-in presets: 67 key-based, eight OAuth, three local, and one default ChatGPT-forward preset. The dashboard’s Add provider picker opens a key provider’s dashboard, validates the key, and stores it; validation is provider-specific. Notable entries:

ClinePass uses a Cline API key with the official subscription catalog and Chat Completions endpoint, operated by Cline Bot Inc. under Cline’s terms. A routed id such as cline-pass/cline-pass/kimi-k3 is intentional: the first segment selects the opencodex provider, while cline-pass/kimi-k3 is the full model slug sent upstream. ClinePass quota is shared by the account across rolling 5-hour, weekly, and monthly limits. A 2026-08-13 live probe verified that every static ClinePass model accepts low, medium, high, xhigh, and max at the gateway input boundary. opencodex preserves those requested tiers; any backend-specific normalization remains ClinePass’s responsibility.

Cline is the same API key and endpoint on pay-as-you-go usage billing across 100+ models (OpenRouter-style ids like anthropic/claude-sonnet-4-6). Cline’s promotional free models are only available in the Cline IDE/CLI, not through the API; minimax/minimax-m2.5 is the documented API free-experimentation model.

OrcaRouter (sponsor) is an OpenAI-compatible gateway at https://api.orcarouter.ai/v1 with vendor-namespaced model ids (openai/gpt-5.5, anthropic/claude-opus-4.8, deepseek/deepseek-v4-flash, …) and an adaptive router, orcarouter/auto, that grades each prompt and picks the model. Create a key in the OrcaRouter console; the preset pins the row near the top of the Add provider picker and marks it as a sponsor, and nothing else about routing or defaults changes.

PackyCode (sponsor) is an API relay for Claude Code, Codex, Gemini and more. The preset targets their OpenAI-compatible Chat Completions endpoint, https://cf.api.fan/v1, with live model discovery narrowed to what your token group allows (gpt-5.5 and gpt-5.1-codex are seeded). Register at packyapi.com and create a Codex-group token; the preset pins the row near the top of the Add provider picker and marks it as a sponsor, and nothing else about routing or defaults changes.

Provider Base URL
OpenAI (API key) https://api.openai.com/v1
Anthropic (API key) https://api.anthropic.com
OpenRouter https://openrouter.ai/api/v1
Cline https://api.cline.bot/api/v1
ClinePass https://api.cline.bot/api/v1
Ollama Cloud https://ollama.com/v1
Google Gemini · Google Vertex AI https://generativelanguage.googleapis.com · https://aiplatform.googleapis.com
Azure OpenAI https://{resource}.openai.azure.com/openai
Umans AI · Neuralwatt https://api.code.umans.ai · https://api.neuralwatt.com/v1
Mistral https://api.mistral.ai/v1
MiniMax · MiniMax (CN) https://api.minimax.io/v1 · https://api.minimaxi.com/v1
DeepSeek https://api.deepseek.com
Cerebras https://api.cerebras.ai/v1
Chutes https://llm.chutes.ai/v1
DeepInfra https://api.deepinfra.com/v1/openai
Hyperbolic https://api.hyperbolic.xyz/v1
Nscale Serverless Inference https://inference.api.nscale.com/v1
Vultr Serverless Inference https://api.vultrinference.com/v1
Baseten Model APIs https://inference.baseten.co/v1
Command Code https://api.commandcode.ai/provider/v1
OrcaRouter https://api.orcarouter.ai/v1
PackyCode https://cf.api.fan/v1
Meta Model API https://api.meta.ai/v1
Meta Muse Code (CLI credential) https://api.meta.ai/v1
SambaNova Cloud https://api.sambanova.ai/v1
Nebius Token Factory https://api.tokenfactory.nebius.com/v1
DigitalOcean Serverless Inference https://inference.do-ai.run/v1
Scaleway Generative APIs https://api.scaleway.ai/v1
Featherless AI https://api.featherless.ai/v1
Novita AI https://api.novita.ai/openai/v1
Together https://api.together.xyz/v1
Fireworks https://api.fireworks.ai/inference/v1
Moonshot (Kimi API) · Kimi (coding) https://api.moonshot.ai/v1 · https://api.kimi.com/coding/v1
Hugging Face https://router.huggingface.co/v1
NVIDIA NIM https://integrate.api.nvidia.com/v1
Z.AI (GLM Coding) https://api.z.ai — Responses at /api/v1/responses by default; Chat Completions at /api/coding/paas/v4/chat/completions per model through modelAdapters
Zhipu AI (BigModel) https://open.bigmodel.cn/api/paas/v4
BigModel Coding Plan (Responses, static roster) https://open.bigmodel.cn/api/v1
Qwen Cloud Token plan (default): https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1 · Pay as you go: https://dashscope.aliyuncs.com/compatible-mode/v1 · or Custom
Tencent Cloud Coding Plan https://api.lkeap.cloud.tencent.com/coding/v3
SiliconFlow https://api.siliconflow.cn/v1
Volcengine Ark · Coding Plan · Agent Plan https://ark.cn-beijing.volces.com/api/v3 · https://ark.cn-beijing.volces.com/api/coding/v3 · https://ark.cn-beijing.volces.com/api/plan/v3
Xiaomi MiMo https://api.xiaomimimo.com/anthropic
Xiaomi MiMo (OpenAI Chat) https://api.xiaomimimo.com/v1
Kilo https://api.kilo.ai/api/gateway
GitLab Duo https://cloud.gitlab.com/ai/v1/proxy/openai/v1
Cloudflare AI Gateway https://gateway.ai.cloudflare.com/v1/{account-id}/{gateway}/anthropic
…and more opencode zen, Vercel AI Gateway, Venice, NanoGPT, Synthetic, Qianfan, Alibaba, Parallel, ZenMux, LiteLLM

OpenCode Go requires a stable session identifier for routing. OpenCodex derives its Go session header from Codex thread/session headers, or from a client’s x-opencode-session header when Codex headers are absent. This applies to direct Chat Completions requests and requests bridged to Responses. Even an ocx_-prefixed inbound value is treated as client input and hashed into Go affinity; the internal bridge carries the original value, so native Chat, bridged Chat, and Responses derive the same result. Explicit provider-config session headers are operator overrides and are sent unchanged. Clients must keep the identifier stable within a conversation and distinct across conversations. A request without any session identifier is not given an inferred cross-request identity; it is instead sent under a session allocated for that request alone, isolated from every other request (see the provider reference for how that value is carried). For Claude Messages, configured OpenCode Go session headers remain authoritative. Otherwise, valid explicit session or thread headers take precedence, and valid conversation identity in metadata.user_id supplies the fallback. This fallback is applied to the final Go destination, including random combo selections and fallback attempts, rather than the preliminary route. Shared system-prompt cache keys do not identify conversations, and Go-specific identity is not sent to non-Go targets. Generated Pi provider configurations enable compat.sendSessionAffinityHeaders so Pi sends its per-session identity to the proxy. Existing manually managed Pi configurations can set this option on their opencodex provider as well. Pi can omit session affinity when cacheRetention is none; enable cache retention when a stable upstream session is required.

OpenCode Zen (opencode-zen) and the keyless OpenCode Free preset share https://opencode.ai/zen/v1. Free models on that gateway often hit a short-window burst limit around 15–20 requests/minute (community-measured; OpenCode does not publish RPM). Zen may return generic rate-limit 429 responses without Retry-After / X-RateLimit-* headers. That is separate from the keyless desktop quota OpenCode advertises (~200 Big Pickle/free-model requests per 5 hours on opencode-free). When Zen omits Retry-After on such a 429, opencodex adds provider guidance to the client error and a synthetic Retry-After; an upstream Retry-After still takes precedence. Same-key wait-and-retry remains opt-in via retryOn429.

The keyless opencode-free tier is currently closed to third-party clients. Zen refuses any request that arrives without an x-opencode-session header, answering with error type MissingSessionID and the message “OpenCode’s free tier can only be used in OpenCode”. Presence of the header is the entire gate, so a proxy could pass it by inventing a value — opencodex does not. Minting a session identifier and a versioned opencode/<version> User-Agent is a claim to be the OpenCode client, and OpenCode publishes no third-party integration contract for this keyless tier; an HTTP 200 obtained that way is a bypassed admission check rather than permission. opencodex therefore reports the restriction instead of working around it: a request to opencode-free returns an error explaining the upstream gate and pointing here.

The supported route to the same models is the keyed opencode-zen provider with an OpenCode Zen API key from opencode.ai/auth. If OpenCode later publishes a supported third-party path for the keyless tier, opencodex can follow it; until then the preset stays as documentation of the restriction. Upstream terms: opencode.ai/docs/zen.

Most use the openai-chat adapter with a bearer key; a few that expose only an Anthropic-compatible endpoint (e.g. Xiaomi MiMo) use the anthropic adapter (x-api-key). Volcengine Agent Plan uses its native Responses endpoint through openai-responses. The built-in DeepSeek preset also routes deepseek-v4-flash over its native Responses endpoint and keeps upstream SSE streaming enabled. If that model finishes every output item but omits the final Responses event, opencodex applies a five-second model-scoped grace repair; malformed or partial streams close as incomplete rather than being reported as successful. The first-party deepseek-flash model advertises native text and image input, so image requests are sent directly to DeepSeek by default instead of through the vision sidecar. Explicit noVisionModels or text-only declarations remain authoritative. First-party deepseek-chat, deepseek-reasoner, and deepseek-v4-flash remain sidecar-backed by default. Zen routes are unchanged and were not probed in this update.

Three Volcengine billing routes: volcengine is the pay-as-you-go Ark API, volcengine-coding-plan consumes Coding Plan quota, and volcengine-agent-plan consumes Agent Plan quota. Use the key and endpoint issued for the same product; the ordinary /api/v3 endpoint can incur pay-as-you-go charges even when a Plan subscription exists. The presets use curated static model catalogs because Ark’s /models response also includes embedding, image, video, and 3D resources, the Coding gateway returns that same broad catalog, and the Agent Plan gateway has no /models resource. Pay-as-you-go defaults to doubao-seed-2-1-pro-260628; its curated catalog also includes current DeepSeek and GLM text models. Coding Plan defaults to ark-code-latest, while Agent Plan defaults to deepseek-v4-flash.

Volcengine Plan usage restriction: Volcengine documents Coding Plan and Agent Plan quota as valid only inside supported AI coding tools, and warns that using a plan key for general API calls may suspend the subscription or ban the account. Routing Codex or Claude Code through opencodex is the documented use; pointing other automation at a plan key is not. The pay-as-you-go volcengine route carries no such restriction.

Chutes discovery. The chutes preset uses Chutes’ fixed shared OpenAI-compatible LLM gateway. It reads the public /v1/models catalog, keeps only rows whose supported_features advertise tools, preserves slash-containing model ids and safe live metadata, and caps discovery at 256 KiB and 128 raw rows. Because that catalog is public, it cannot prove a supplied key is valid; chat requests still use the configured Bearer key. User-deployed custom Chute hosts and Chutes’ non-LLM APIs remain custom-provider territory. Create a key from the Chutes dashboard.

DeepInfra discovery. The key-based deepinfra OpenAI Chat Completions provider uses the openai-chat adapter with a Bearer API key. Its registry-owned model-list URL keeps only rows tagged chat, preserves slash-containing native model ids, and caps live discovery at 512 KiB and 512 raw rows. Create keys in DeepInfra’s dashboard.

Hyperbolic discovery. The preset reads /v1/models with the configured bearer key, preserves slash-containing native model ids, and caps live discovery at 256 KiB and 256 raw rows. It covers serverless text and vision-language chat only; Hyperbolic’s separate image, audio, and GPU endpoints are out of scope. Create keys at Hyperbolic.

Nscale and Vultr discovery. Both presets read the provider’s authenticated /v1/models catalog, preserve native ids, and cap discovery at 256 KiB and 256 raw rows. Nscale’s catalog mixes chat, image, and embedding models without a modality field, so the preset admits only meta-llama/Llama-3.1-8B-Instruct, the model used by Nscale’s official tool-calling API example. Vultr currently documents tool calling only for kimi-k2-instruct, so its preset exposes only that model. Other rows remain hidden until the provider publishes equivalent agent-tool evidence. Create an Nscale service token in the Nscale Console; copy Vultr’s inference key from the subscription overview in the Vultr Console.

Command Code discovery. The preset reads Command Code’s /provider/v1/models list from the fixed Provider API host, preserves provider-native ids, and caps discovery at 256 KiB and 256 raw rows. ocx login command-code supports OAuth via browser sign-in (with optional local CLI credential import from ~/.commandcode/auth.json for existing Command Code CLI users); the model catalog is account-scoped and comes from the authenticated discovery endpoint after login. The Provider-API preset (commandcode) uses the active configured Bearer key for chat requests; the OAuth preset (command-code) uses the stored account bearer for authenticated discovery and chat. Create Provider-API keys at Command Code Studio.

OrcaRouter authentication and discovery. Choose either ocx login orcarouter-oauth for one-click browser authorization or ocx login orcarouter to paste an existing API key. The PKCE flow starts a loopback listener first, sends a fresh S256 challenge and state to https://www.orcarouter.ai/auth, exchanges the single-use code at https://www.orcarouter.ai/api/v1/auth/keys, and stores the returned user-owned key in ~/.opencodex/auth.json. The manual-key preset continues to use the normal provider key store. Both modes route to https://api.orcarouter.ai/v1 and discover the public live catalog with capability=chat; non-chat media/rerank rows are excluded, and reported input modalities control whether Codex offers image attachments. Because the catalog itself is public, manual key setup reports validation as unknown instead of accepting that response as proof that the key works.

For a one-origin self-hosted deployment, set the shared origin before the first PKCE login; the saved inference URL is derived from the same origin:

Terminal window
ORCAROUTER_BASE_URL=https://router.example ocx login orcarouter-oauth

For a split self-hosted deployment, set ORCAROUTER_API_BASE_URL and ORCAROUTER_AUTH_BASE_URL separately.

The value must be an HTTPS origin (or HTTP loopback for local development) with no credentials, query, or fragment. Before the first login to a loopback/private self-hosted endpoint, explicitly allow that destination in your ~/.opencodex/config.json provider row. For example, merge this entry into the existing providers object for a local development server:

{
  "orcarouter-oauth": {
    "adapter": "openai-chat",
    "baseUrl": "http://127.0.0.1:9999/v1",
    "authMode": "oauth",
    "allowPrivateNetwork": true
  }
}

Then run ORCAROUTER_BASE_URL=http://127.0.0.1:9999 ocx login orcarouter-oauth. Login preserves this explicit consent; setting the URL alone never enables private-network access. Without the opt-in, destination validation rejects inference and model discovery for that endpoint. This requirement concerns the provider endpoint; the browser callback listener needs no such opt-in. Re-run the login after a relay 401; OrcaRouter keys are durable and do not have a refresh-token grant.

Meta Model API (meta-model). Muse Spark on Meta’s own OpenAI-compatible endpoint, served over /v1/responses. Create a key in the Meta developer console — Meta calls this variable MODEL_API_KEY, but opencodex derives the env var from the provider id, so export it as META_MODEL_API_KEY (or paste it during ocx init). The account needs a payment method before it will serve requests, and every call is metered per token. Two models are seeded — meta-model/muse-spark-1.3 and meta-model/muse-spark-1.3-contributor — with the vendor’s minimal/low/medium/high/xhigh ladder and a 1M context window. Discovery stays off until an authenticated roster is verified, because Meta serves image and voice models on the same host.

Two things worth knowing before you pick it. A Muse Code subscription does not apply here: Meta scopes that credential to the Muse Code CLI and bills any other key pay-as-you-go. And the Contributor tier is cheap because Meta trains on your prompts — roughly 92% off input, 95% off output, and 99% off cached input — so keep confidential material off it. Muse Spark is also reachable through resellers, with a narrower roster: command-code carries both tiers, while opencode-go serves only muse-spark-1.3-contributor.

Meta Muse Code (meta-muse). On macOS, if you already use the Muse Code CLI, this imports the API key it stored after muse login instead of asking you to provision a second one. OpenCodex never launches the CLI: if no credential is present it tells you to run muse login yourself.

Elsewhere it asks you to paste the key. Meta ships no native Windows CLI, and on Linux the CLI exists but where it stores its credential has not been verified, so OpenCodex refuses to guess at a credential store and points you at dev.meta.ai instead, where the same key is visible. A pasted key faces the same format check and the same live validation against the Model API as an imported one. See Platform support for the full per-platform picture.

Read this before enabling it. Meta scopes that credential to the Muse Code CLI, so using it here is an unsupported path. Meta does not authorize subscription coverage outside its own client, how these calls settle is not observable from the API, and you should treat every call as billable against your account. The key, imported or pasted, is copied into OpenCodex’s auth store (~/.opencodex/auth.json, mode 0600) like every other OAuth credential. The dashboard shows a Terms-of-Service warning before the first login and before any reauthentication — the same treatment Anthropic and Google Antigravity get.

Meta reports subscription window usage inside streaming responses, and OpenCodex reads it from there. The account row shows the last observed 5-hour and weekly windows with how old that reading is — Meta publishes no endpoint to query them on demand, so a value is only refreshed by another streaming turn through this provider, and a turn that goes through request translation rather than passthrough reports none. An account that has not yet served a streaming turn simply shows no quota, which is not an error. Rate limits apply per team, not per key.

For a supported setup, use meta-model above with your own key.

Command Code quota. The dashboard and ocx account refresh probe Command Code’s /alpha/billing/credits windows (5-hour and weekly) on the canonical https://api.commandcode.ai host. The OAuth preset (command-code) uses the stored account bearer; the Provider-API key preset (commandcode) uses the active configured key. A user-edited lookalike base URL is never probed. Remaining monthly, purchased, and free credits are shown as a USD window when Command Code also reports period spend.

SambaNova Cloud discovery. The preset reads SambaNova Cloud’s public /v1/models list from the fixed API host, preserves provider-native ids, and caps discovery at 128 KiB and 128 raw rows. Because the catalog is unauthenticated, the CLI login flow reports the key as unverifiable instead of treating the public response as proof. Chat requests still use the configured Bearer key and disable parallel function calls, which SambaNova does not yet support. Private SambaStudio deployment endpoints are out of scope. Create keys in SambaNova Cloud.

Nebius Token Factory discovery. The preset requests the authenticated verbose model catalog and keeps only rows whose architecture produces text, excluding embedding and image-generation models. It preserves slash-containing native ids plus reported context and input-modality metadata, and caps discovery at 512 KiB and 512 raw rows. Dedicated deployment hosts are out of scope. Create keys in Nebius Token Factory. DigitalOcean discovery. The preset uses a model access key against the fixed shared Serverless Inference host and intersects the authenticated /v1/models response with DigitalOcean’s docs-backed Chat Completions allowlist. Unknown, Responses-only, embedding, and media-generation ids fail closed. Discovery is capped at 256 KiB and 256 raw rows; agent-specific and dedicated hosts are out of scope. Create a key in the DigitalOcean Control Panel.

Scaleway discovery. The preset intersects the authenticated model list with Scaleway’s documented Serverless Chat Completions allowlist. Unknown, Responses-only, embedding, transcription, and other media-model ids fail closed; discovery is capped at 128 KiB and 128 raw rows. It uses the default Project’s shared endpoint; project-qualified URLs and dedicated deployments require a custom provider. Create an API key in the Scaleway console.

Featherless discovery. The preset authenticates against the fixed OpenAI-compatible host and requests only the first 100 popular models filtered upstream to chat and the current plan. Registry rules then fail closed unless each row independently reports plan availability, no Hugging Face gate, and features.tool_use: true. Discovery is capped at 128 KiB and 100 raw rows, so the service’s tens-of-thousands-model catalog is never downloaded or cached in full. Because /v1/models is documented as callable with or without authentication, it cannot prove a supplied key is valid; chat requests still use the configured Bearer key. Featherless terms reserve individual plans for interactive/prototyping use; arbitrary applications require a Scale plan. Create a key in the Featherless dashboard.

Novita discovery. The key-based preset uses the openai-chat adapter and sends its Bearer key only to Novita’s fixed OpenAI-compatible host. Its public model list is filtered to rows that report both model_type: chat and the chat/completions endpoint, with discovery capped at 512 KiB and 256 raw rows. Model ids must be preserved exactly as Novita returns them, including slash-delimited ids, and must not be normalized or rewritten before routing. Because the catalog is public, login reports the key as unverifiable instead of treating a successful list response as proof. Model capabilities vary, so the preset does not advertise provider-wide parallel tool calls or OpenAI reasoning_effort. Create a key in Novita’s key manager.

Baseten scope: The preset covers Baseten’s shared Model APIs only. Use a personal API key for local use, or a team key with Call Model APIs access for shared/production use. Dedicated Truss predict endpoints use different hosts and schemas and are not routed by this preset. Live discovery for this preset is capped at a 1 MiB response and 256 raw model rows.

Official CodeBuddy Code CLI (Global & CN)

Section titled “Official CodeBuddy Code CLI (Global & CN)”

OpenCodex provides official adapter support for Tencent Cloud’s CodeBuddy Code CLI via the codebuddy (Global) and codebuddy-cn (China) presets.

{
  "providers": {
    "codebuddy": {
      "adapter": "codebuddy",
      "baseUrl": "https://www.codebuddy.ai",
      "apiKey": "${CODEBUDDY_API_KEY}"
    },
    "codebuddy-cn": {
      "adapter": "codebuddy",
      "baseUrl": "https://www.codebuddy.cn",
      "apiKey": "${CODEBUDDY_CN_API_KEY}"
    }
  }
}
  • Prerequisites: Install the official CodeBuddy CLI globally:
    Terminal window
    npm install -g @tencent-ai/codebuddy-code
  • Authentication: Obtain your official API key from the vendor console:
  • Region Isolation: codebuddy and codebuddy-cn use separate canonical endpoints (https://www.codebuddy.ai and https://www.codebuddy.cn) and isolated child environments (CODEBUDDY_INTERNET_ENVIRONMENT=public vs internal). Credentials are strictly region-scoped and never exchanged across environments. Overriding the canonical base URL fails closed.
  • Tool Ownership: In v1, the CLI is spawned with --tools "" and --strict-mcp-config, ensuring Codex maintains exclusive tool ownership. The provider operates in text and reasoning mode; client tool execution is not delegated to the vendor CLI.
  • Entitlements and Billing: The provider uses the same vendor-documented CodeBuddy account/CLI authentication surface. Availability and billing of free, promotional, trial, or subscription credits remain determined by the user’s CodeBuddy account entitlement.

Official Qoder CLI (Global & CN)

Section titled “Official Qoder CLI (Global & CN)”

OpenCodex provides official adapter support for Qoder through the qoder (Global) and qoder-cn (China) presets. Both use a user-supplied Personal Access Token and the vendor’s headless CLI; OpenCodex never reads Qoder Desktop sessions, browser cookies, refresh tokens, or private console APIs.

{
  "providers": {
    "qoder": {
      "adapter": "qoder",
      "baseUrl": "https://qoder.com",
      "apiKey": "${QODER_PERSONAL_ACCESS_TOKEN}"
    },
    "qoder-cn": {
      "adapter": "qoder",
      "baseUrl": "https://qoder.cn",
      "apiKey": "${QODERCN_PERSONAL_ACCESS_TOKEN}"
    }
  }
}
  • Prerequisites: Install the official CLI for the region you use:
    Terminal window
    npm install -g @qoder-ai/qodercli        # Global: qoder / qodercli
    npm install -g @qodercn-ai/qoderclicn    # CN: qodercn / qoderclicn
  • Authentication: Create a PAT in the account integrations page (Global, CN) and paste it as the provider’s API key. The stored key reaches the CLI only as QODER_PERSONAL_ACCESS_TOKEN (Global) or QODERCN_PERSONAL_ACCESS_TOKEN (CN) in a scoped child environment.
  • Region Isolation: Each preset accepts only its canonical destination (https://qoder.com or https://qoder.cn) and resolves its own executable. Credentials, model cache, usage, and health are independent; neither region falls back to the other. An older custom provider named qoder with a different destination keeps its existing adapter and URL.
  • Model Discovery: qoder --list-models is the authoritative entitlement roster for the current PAT. The cache is bound to an irreversible fingerprint of the token, so switching accounts never reuses another account’s roster. If discovery fails, the provider degrades to a stale cache and then the documented static seed.
  • Tool Ownership: The CLI runs single-turn stream-json with --tools "", --strict-mcp-config, setting sources disabled, and session persistence disabled, so Codex keeps exclusive tool ownership. v1 is text and reasoning only; image input fails explicitly.
  • Quota: No public quota API is used, so totals and reset times are unavailable. Insufficient-credit errors (vendor code 118) surface as HTTP 429 insufficient_quota.
  • Operators: Qoder Global is operated by BRIGHT ZENITH PRIVATE LIMITED under the product service terms; Qoder CN by 通义云启（杭州）信息技术有限公司 with Alibaba Cloud. Verify ocx provider test qoder (or qoder-cn) after configuring.

A6API credit quota

Section titled “A6API credit quota”

A custom openai-chat provider using authMode: "key" and the canonical https://api.a6api.com or https://api.a6api.com/v1 base URL receives an A6API credit meter in the dashboard and from ocx account refresh <provider>. The provider name is arbitrary; detection uses the canonical HTTPS endpoint. The meter converts A6API token units into USD using the account’s hard credit limit and displays the percentage consumed plus remaining credit. Token expiration is not shown as a quota reset because expiration does not imply that credit replenishes.

{
  "providers": {
    "my-a6": {
      "adapter": "openai-chat",
      "authMode": "key",
      "baseUrl": "https://api.a6api.com/v1",
      "apiKey": "${A6API_API_KEY}"
    }
  }
}

Quota probes send only the active key to the canonical A6API host and reject redirects. Malformed, negative, or internally inconsistent billing totals produce no report rather than a misleading bar.

Tencent Cloud Coding Plan usage restriction: Tencent documents this subscription for interactive coding tools only. General API automation, custom application backends, and non-interactive batch use are prohibited and may cause the plan key to be suspended.

GLM billing routes: zai is the Z.AI international coding-plan subscription; zhipu-bigmodel is Zhipu’s domestic BigModel pay-as-you-go endpoint. Different hosts, different keys, different billing — a key issued for one will not authenticate against the other.

BigModel Coding Plan over Responses

Section titled “BigModel Coding Plan over Responses”

Select Zhipu AI — BigModel Coding Plan (Responses) (zhipu-bigmodel-responses) for the openai-responses endpoint https://open.bigmodel.cn/api/v1. This is separate from zhipu-bigmodel-coding, which uses Chat Completions at /api/coding/paas/v4.

The preset uses a static roster (liveModels: false) taken from the published GLM Coding Plan documentation:

Model Context tokens Upstream selectable effort Default effort Reasoning summaries
glm-5.3 1,048,576 low, high, max max Supported
glm-5.3-flash 1,048,576 low, high, max max Supported
glm-5-turbo 204,800 None (empty list) max Supported

glm-5.3 and glm-5-turbo declare upstream text-only input. The Codex catalog advertises text and image for them because opencodex’s existing vision sidecar can describe images for text-only models; that path requires an available, enabled vision sidecar and does not claim native BigModel image support.

glm-5.3-flash is the exception: it declares native text and image input, because upstream documents it as a natively multimodal model. It therefore reads pictures directly instead of being routed through the describe-it-first sidecar detour.

The default model is glm-5.3; Responses reasoning content is preserved on replay. The existing Codex export adds its compatibility ultra tier to GLM-5.3 and omits Turbo’s default-effort field because Turbo has no selectable ladder; the provider metadata still records max for both models. For Turbo, outgoing Responses requests omit reasoning.effort, including a caller’s max or ultra, while preserving requested reasoning summaries. This leaves effort selection to the upstream default; opencodex does not inject a selectable or wire max.

The example’s models.json is a local catalog file, not a documented HTTP model-list response, and not the set of models the endpoint serves — the Coding Plan pages state that every plan tier reaches GLM-5.3 and GLM-5.3-Flash, and that GLM-5-Turbo calls are auto-switched to Flash, so this endpoint was already serving Flash under the Turbo id. This preset still does not perform live model discovery. An existing custom provider with the same name keeps its configured destination and metadata. CLI key login also skips the undocumented /models probe and reports validation as unknown; successful key authentication is established by a subsequent inference request.

Multiple API keys

Section titled “Multiple API keys”

Key-based providers can also keep multiple keys. Adding a key through the Providers page stores it under provider.apiKeyPool, makes it active, and mirrors it to provider.apiKey so routing and adapters continue to read the same field as before. The same dropdown can switch or remove keys; the management API is /api/providers/keys and returns masked keys only.

Switching accounts from the terminal

Section titled “Switching accounts from the terminal”

Use ocx account list, ocx account current, and ocx account use to inspect or switch the same Codex, OAuth, and API-key pools without opening the dashboard. See the CLI reference for commands, JSON output, and new-session behavior.

Subscription tier in account listings

Section titled “Subscription tier in account listings”

ocx account list <provider> --json and GET /api/oauth/accounts report a plan field on every OAuth account, using the same name and placement as the OpenAI/Codex provider so a consumer can read one shape across providers.

The field is always present. It is null when the tier is unknown, which is deliberate: an absent key means the proxy predates this field, while null means this version looked and the provider did not report a tier. Collapsing the two would let a consumer quietly assume a tier.

For Anthropic the value is null today. Its usage endpoint returns quota buckets only — the five-hour and seven-day windows, the model-scoped weekly windows, and a limits array — and no subscription or tier field; the OAuth token response carries only the account id and email. There is nothing to map, so nothing is mapped. The tier is also not derivable from the quota it does return, because percentages are normalized per account: a Max ×5 seat at 50% is indistinguishable from a Max ×20 seat at 50%. If you need weighted pool capacity across mixed Anthropic tiers, keep that mapping outside OpenCodex until upstream reports the tier itself.

GPT-5.6 preview paths

Section titled “GPT-5.6 preview paths”

GPT-5.6 Sol/Terra/Luna are seeded in provider fallback lists so ocx sync can keep the models visible even while live catalogs lag:

Codex route Seeded model ids Codex-visible context
Codex login (Pool or Direct) gpt-5.6-* 922,000
OpenAI (API key) openai-apikey/gpt-5.6-* plus *-pro 922,000 (922,000 max input)
OpenRouter openrouter/openai/gpt-5.6-sol, openrouter/openai/gpt-5.6-terra, openrouter/openai/gpt-5.6-luna 922,000
Cursor cursor/gpt-5.6-sol, cursor/gpt-5.6-terra, cursor/gpt-5.6-luna 1,000,000

The native GPT-5.6 entries preserve the pinned upstream reasoning ladders (for example, Luna has max but no ultra). Routed entries use their provider metadata and reasoning mappings. All four paths remain upstream-gated; Cursor’s live discovery additionally filters its static seed to models the logged-in account can use.

Ollama Cloud

Section titled “Ollama Cloud”

Ollama Cloud is a hosted (not local) Ollama. Configure it at https://ollama.com/v1 with a key from ollama.com/settings/keys. opencodex reaches it over Ollama’s own REST API (POST /api/chat) rather than the OpenAI-compatible surface, and discovers the live model roster from the provider, so new Ollama Cloud models appear without a config change. opencodex classifies its cloud lineup by vision capability so the vision sidecar only kicks in for text-only models. Text-only models (e.g. glm-5.2, deepseek-v4-flash, gpt-oss, qwen3-coder, minimax-m2.x, nemotron-3-*) are listed in noVisionModels; vision-native models (e.g. kimi-k2.6, minimax-m3, gemma4, qwen3.5, gemini-3-flash-preview) are not. Matching is tolerant of Ollama’s :size tags, so gpt-oss covers gpt-oss:120b and gpt-oss:20b.

Ollama currently documents structured outputs as unsupported on Ollama Cloud. For canonical ollama-cloud, opencodex therefore refuses structured-output requests (text.format) with a clear error instead of silently returning unconstrained prose; local and custom ollama-native endpoints keep Ollama’s native format behavior.

4. Local providers

Section titled “4. Local providers”

Point opencodex at a local OpenAI-compatible server — usually with a blank key:

Provider Base URL
Ollama (local) http://localhost:11434/v1
vLLM http://localhost:8000/v1
LM Studio http://localhost:1234/v1

Any OpenAI-compatible endpoint

Section titled “Any OpenAI-compatible endpoint”

If a provider speaks Chat Completions, the openai-chat adapter handles it — choose Custom in the dashboard or custom in ocx init and enter the base URL. See the Configuration reference for every provider field (headers, noReasoningModels, noVisionModels, models, …).

Approval reviewer per provider

Section titled “Approval reviewer per provider”

Codex asks a second model to review approval requests, and takes that reviewer from auto_review_model_override on the catalog row of the current turn’s model. The root auto_review_model in $CODEX_HOME/config.toml applies one reviewer to every row. To give a routed provider its own — usually cheaper — reviewer, set the selector on that provider row in ~/.opencodex/config.json:

{
  "providers": {
    "blsc": {
      "autoReviewModel": "opencode-go/deepseek-v4-flash",
      "autoReviewModelOverrides": { "kimi-k3": "gpt-5.6-terra" }
    }
  }
}

autoReviewModel covers every routed row of the provider. autoReviewModelOverrides targets a single upstream model id and wins over it. A value is either a bare model id of that same provider or a public catalog slug such as opencode-go/deepseek-v4-flash, and a provider stamp wins over the root selector on its own rows while the root selector stays the fallback elsewhere.

A bare value resolves against the provider’s own rows first and then against a bare catalog row, which is how a native model such as gpt-5.6-terra is named; a value that matches neither is left unresolved, and a bare value that lands outside the provider prints a note naming the row that supplies the reviewer. Giving the full slug avoids the question entirely when the reviewer is another provider’s routed model.

Selectors are resolved against the final catalog on the next sync, each one on its own, and each fails closed by itself: an unresolved autoReviewModel prints a diagnostic and stamps no provider-wide rows, an unresolved autoReviewModelOverrides entry prints a diagnostic and stamps no per-model override, leaving a valid provider-wide target as fallback. Whatever resolves is still applied. Rows without a provider stamp keep the root selector, or upstream behavior when that is unset. Removing the root selector leaves provider stamps alone, and removing a provider selector clears only that provider’s stamps.

These fields are available through configuration, PATCH /api/providers?name=<provider>, and the dashboard raw JSON provider editor; dedicated form controls are not present. The canonical openai provider rejects them. Field-by-field rules live in the provider configuration reference.

Rate limits in the providers overview

Section titled “Rate limits in the providers overview”

The Rate limits section of the Providers overview shows live utilization bars refreshed from each provider’s own usage/billing endpoint when one exists. The bars show how much of a window (5-hour, weekly, monthly, or provider-specific) is already consumed.

Providers with a live probe: OpenAI/Codex, Anthropic, xAI, Cursor, Kimi, Google Antigravity, OpenCode Go, OpenRouter, DeepSeek, ClinePass, Z.AI, MiniMax, Moonshot, Venice, Synthetic, DeepInfra, Neuralwatt, Command Code, and any a6api-backed custom provider.

OpenCode Go quota. The canonical opencode-go preset reads GET https://opencode.ai/zen/go/v1/usage with the configured key as a Bearer token and does not follow redirects. The response’s rolling, weekly, and monthly percent values are already-consumed utilization: rolling maps to the 5-hour bar, while weekly and monthly keep their matching bars. OpenCodex does not reconstruct dollar caps from local usage logs, and a provider using a non-canonical baseUrl is never sent the key for this probe.

Z.AI GLM Coding Plan quota. The zai, glm, glm-cn, and zhipu-bigmodel-coding presets read GET /api/monitor/usage/quota/limit and do not follow redirects. The probe runs against the region the provider points at: api.z.ai (bare or /api/coding/paas/v4) or open.bigmodel.cn (bare, /api/coding/paas/v4, or the OpenAI Responses endpoint /api/v1).

Authentication differs by region: api.z.ai takes the key as a Bearer token, while open.bigmodel.cn expects the key directly in Authorization with no scheme prefix and rejects a Bearer header. The response’s limits rows fill the utilization bars: TOKENS_LIMIT / CREDIT_LIMIT rows with unit 3 / number 5 fill the 5-hour bar and unit 6 / number 1 the weekly bar.

TIME_LIMIT rows are not model quota and are ignored. They are the shared monthly MCP call allowance for Web Search, Web Reader, and Zread, so treating them as a model window would let a spent web-search budget read as exhausted model capacity in quota-aware account ranking. A plan that reports only TIME_LIMIT rows therefore shows no quota bars rather than a fabricated one, and windows the plan does not report stay absent instead of rendering as 0%.

A provider using a non-canonical baseUrl is never sent the key for this probe.

Diagnosing an Antigravity quota refresh

Section titled “Diagnosing an Antigravity quota refresh”

The account quota view and ocx account list google-antigravity --quota --refresh distinguish access denial, rate limiting, blocked destinations or redirects, DNS/connection/timeouts, and unusable quota data. Last-known bars remain visible with their observation time when a refresh fails. Reauthentication retires diagnoses from the previous credential; a successful refresh clears the failure.

An access-denied result does not by itself prove an expired login or an ineligible plan. A blocked destination is a network-policy decision, not proof of a Fake-IP defect. Canonical Google quota destinations retain TLS verification and redirect/private-address restrictions. Authenticated TUN behavior must be checked in the affected environment; injected transport fixtures alone do not establish that field result.

Large inline images on Chat providers

Section titled “Large inline images on Chat providers”

Translated OpenAI-compatible Chat requests shrink inline images when their combined base64 data exceeds 3.5 MiB. Older images lose detail first. This is a best-effort image budget, so large text, schemas, or images that cannot be processed may still exceed an upstream request limit. Remote image URLs are not downloaded, and images that cannot be shrunk remain attached. Native Chat passthrough keeps its original image bytes.