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.

Which credential do I need?

For a fresh local install, usually only the first row applies:

Credential	Scope	When it is required
ChatGPT/Codex login	Upstream OpenAI ChatGPT/Codex account	Default `openai` forward route. Sign in with `codex login` or the Codex app; no API key is stored.
Upstream provider credential	One optional provider	That provider’s API key, OAuth login, or local runtime. Add one only when you want that route.
OpenCodex admission key	Your own opencodex proxy	Required for data-plane clients on a non-loopback/LAN bind. `ocx host enable --new-key --yes` generates it; local loopback traffic does not need it.

The admission key never authenticates to OpenAI, Anthropic, or another upstream and does not pay for model usage. Conversely, a provider API key does not satisfy the proxy’s non-loopback admission gate. If a client says opencodex API key required, see Remote access and admission keys.

OpenAI account modes

Provider id	Use	Credential/account rule
`openai`	Codex login	The fresh-install default. Pool (default) selects main plus added accounts; Direct uses the current caller/main login only. No provider API key.
`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.

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

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, GitHub Copilot.

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"
  }
}

That provider is configuration-ready on a fresh install even though it has no apiKey field. Live requests still need a valid ChatGPT/Codex login and access to the requested model; configuration readiness is not a promise that the upstream account is healthy.

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.

Six provider presets use OAuth login — plus GitHub Copilot via an experimental unofficial device-flow bridge. opencodex stores their credentials in ~/.opencodex/auth.json and refreshes them automatically. chatgpt is also accepted by the login CLI; it acquires a ChatGPT credential while creating a forward-mode provider entry.

ocx login xai          # xAI Grok
ocx login anthropic    # Anthropic Claude (Pro/Max)
ocx login kimi         # Moonshot Kimi
ocx login kiro         # import kiro-cli credentials (or token fallback)
ocx login google-antigravity
ocx login cursor       # standalone Cursor PKCE login
ocx login github-copilot  # GitHub device flow → Copilot token (Copilot Pro/Business)
ocx login chatgpt      # standalone ChatGPT OAuth login
ocx logout <provider>

Provider	Adapter	Base URL	Notes
`xai`	`openai-chat`	`https://api.x.ai/v1`	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.
`kiro`	`kiro`	`https://runtime.us-east-1.kiro.dev`	Initial login imports the installed, signed-in `kiro-cli` session (install with `curl -fsSL https://cli.kiro.dev/install
`google-antigravity`	`google`	`https://daily-cloudcode-pa.googleapis.com`	Google OAuth over the Cloud Code Assist wire.
`cursor`	`cursor`	`https://api2.cursor.sh`	Experimental PKCE login, live HTTP/2 transport, and account-filtered model discovery.
`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.

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.

You can also start OAuth from the web dashboard.

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. Only identity-less Kimi credentials replace the active slot; 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. Provider login is independent of optional quota enrichment: a rate-limited or unavailable usage probe does not roll back an authenticated account.

Codex pool OAuth follows the same identity-first rule when fresh authenticated WHAM data confirms the account’s relevant quota is already 100% used. That authenticated usage response has already proved the token and account binding work, and a spent account cannot generate, so the warmup generation call is skipped rather than sent to be refused. The exhausted account is saved and remains visible, but routing excludes it until Refresh quotas successfully reports usage below 100%. Identity, duplicate, and namespace checks remain mandatory; every account whose quota is not confirmed exhausted — including one whose usage probe failed — still must pass warmup, and unverified manual import always does.

By default every request uses the active account only. An experimental, opt-in account pool can route across them instead — sticky session affinity, 429 cooldown and failover, and quota/round-robin/fill-first selection for new sessions. It is off for every provider until you turn it on, and it is ToS-sensitive: see providers[<name>].accountPool (Anthropic configures the same engine through anthropicAccountPool).

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):

In-process single-flight — concurrent callers share one refresh promise.
Per-account file lock — cross-process writers serialize on the same account.
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 also preserve known independent quota groups: gpt-5.3-codex-spark does not prevent the same account from trying the shared GPT-5.6 Terra/Luna quota, while models in that shared group still protect one another. 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.

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 an ocx login provider — reauthenticate via the dashboard Codex account pool. See ocx status / ocx doctor in the CLI reference.

Kiro credential import

Kiro login expects the Kiro CLI: install it (curl -fsSL https://cli.kiro.dev/install | bash) and sign in with kiro-cli login first. 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.

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

opencodex ships 53 built-in presets: 42 key-based, seven OAuth, three local, and the default ChatGPT-forward preset. The dashboard’s Add provider picker opens a key provider’s dashboard, validates the key, and stores it. Notable entries:

Provider	Base URL
OpenAI (API key)	`https://api.openai.com/v1`
Anthropic (API key)	`https://api.anthropic.com`
OpenRouter	`https://openrouter.ai/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`
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/api/coding/paas/v4`
Zhipu AI (BigModel)	`https://open.bigmodel.cn/api/paas/v4`
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`
Xiaomi MiMo	`https://api.xiaomimimo.com/anthropic`
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

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).

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.

Two GLM 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.

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

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.

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-*`	372,000
OpenAI (API key)	`openai-apikey/gpt-5.6-` plus `-pro`	1,050,000 (922,000 max input)
OpenRouter	`openrouter/openai/gpt-5.6-sol`, `openrouter/openai/gpt-5.6-terra`, `openrouter/openai/gpt-5.6-luna`	1,050,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.

A provider is included when opencodex has a matching wire adapter, not based on whether it is an “agent” product. The current adapter ids are openai-chat, openai-responses, anthropic, google (AI Studio, Vertex, and Antigravity/Cloud Code Assist modes), azure / azure-openai, kiro, and cursor. A proprietary API without one of these implementations, such as native Amazon Bedrock, is not supported directly. GitHub Copilot is an OAuth provider (ocx login github-copilot) that exchanges a GitHub device-flow login for a short-lived Copilot API token — not a pasted API key. GitLab Duo remains a key/subscription-token gateway on its OpenAI-compatible endpoint. Cloudflare AI Gateway needs your account + gateway ids filled into the URL.

Cursor is tracked separately as an experimental adapter. adapter: "cursor" appears in ocx init and the dashboard Add Provider picker as an experimental local config entry with Cursor’s static fallback model catalog metadata. When a Cursor access token is configured, opencodex uses Cursor’s live HTTP/2 transport. Its v2.7.1 fallback seed includes gpt-5.6-sol / terra / luna (1M context) plus grok-4.5 / grok-4.5-fast (500K); live discovery decides which remain visible for the account. Cursor server-driven native read/write/delete/ls/grep/shell/fetch execution is disabled by default because it bypasses Codex’s approval and sandbox path; set unsafeAllowNativeLocalExec: true on the providers.cursor object in ~/.opencodex/config.json only for trusted local experiments (or via Providers → Cursor → Edit JSON in the dashboard). See the Configuration reference for a full example. MCP, screen recording, and computer-use are available as executor hooks; without a configured local executor, opencodex returns typed no-executor results instead of policy-blocking the request. Cursor OAuth and live model discovery are enabled for this experimental adapter; Cursor is still not shown in key-login lists.

Ollama Cloud

Ollama Cloud is a hosted (not local) Ollama, OpenAI-compatible at https://ollama.com/v1 with a key from ollama.com/settings/keys. 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-pro, 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.

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

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, …).