Skip to content

providers.md

Latest commit

 

History

History
552 lines (458 loc) · 36.7 KB

providers.md

File metadata and controls

552 lines (458 loc) · 36.7 KB
Raw
title Providers
description Every way CodexCommander authenticates and talks to an LLM provider — OAuth, API key, ChatGPT forward, and local.

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 ~/.codexcommander/config.json.

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.

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.

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 and follows its credential owner. CodexCommander-owned credentials refresh before expiry; linked Grok/Kimi CLI credentials are adopted read-only and remain native-CLI-owned. xAI, Anthropic, Kimi, Kiro, Google Antigravity, Cursor, GitHub Copilot.

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.

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)

Seven provider presets use OAuth login — plus GitHub Copilot via an experimental unofficial device-flow bridge. CodexCommander stores their credentials in ~/.codexcommander/auth.json. CodexCommander-owned credentials refresh automatically. When a signed-in Grok or Kimi CLI session is linked, CodexCommander adopts its current access generation read-only and the native CLI remains responsible for renewal. chatgpt is also accepted by the login CLI; it acquires a ChatGPT credential while creating a forward-mode provider entry.

ccx login xai          # xAI Grok
ccx login anthropic    # Anthropic Claude (Pro/Max)
ccx login kimi         # Moonshot Kimi
ccx login kiro         # import kiro-cli credentials (or token fallback)
ccx login google-antigravity
ccx login cursor       # standalone Cursor PKCE login (default). Paste a dashboard key in the GUI or config instead.
ccx login command-code # Command Code browser OAuth (or import ~/.commandcode/auth.json)
ccx login github-copilot  # GitHub device flow → Copilot token (Copilot Pro/Business)
ccx login chatgpt      # standalone ChatGPT OAuth login
ccx 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 K3 (k3, 1M context), fixed-window k3-256k, compatibility alias k3[1m], and 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 (on Unix, 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. Uses the maintained six-model static catalog because CCA does not expose the generic /models endpoint.
cursor cursor https://api2.cursor.sh Experimental unofficial PKCE login or a pasted dashboard user API key. Same unofficial AgentService/Run protocol either way; not a public OpenAI chat-completions API.
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.

If an xAI OAuth request to the Grok subscription proxy reports that the Grok CLI client version is outdated, update CodexCommander to a release with the current xAI compatibility profile. Routed requests advertise CodexCommander's pinned client version; they do not launch the local grok executable, so updating that executable alone does not change the request fingerprint. xAI API-key requests use api.x.ai and do not use the Grok subscription-proxy fingerprint.

For the canonical Kimi Coding Plan presets (kimi account login and kimi-code API key), CodexCommander 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, CodexCommander 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 ~/.codexcommander/auth.json; /api/oauth/accounts returns masked metadata only.

OAuth reliability

CodexCommander 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 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. Healthy Codex tasks keep their account across quota-ranking changes and proxy restarts through a bounded private ownership cache. Missing or invalid cache entries are treated as unbound. 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. CodexCommander does not fabricate official client identity (for example originator, session, or thread headers) when the caller did not send them.

Diagnostics and reauth. Human ccx status prints an OAuth health block (redacted account ids, no tokens). ccx 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 ccx login <provider> (or use Reauthenticate in the dashboard). Codex pool accounts are not an ccx login provider — reauthenticate via the dashboard Codex account pool. See ccx status / ccx doctor in the CLI reference.

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, ccx login kiro falls back to a pasted access token or the KIRO_ACCESS_TOKEN environment variable.

The ccx 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, CodexCommander 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: CodexCommander 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, CodexCommander persists the imported credential to ~/.codexcommander/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 CodexCommander 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

CodexCommander ships 76 built-in presets: 64 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 CodexCommander 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. CodexCommander currently advertises the live-verified low reasoning tier; higher requested tiers clamp to low until the gateway publishes or verifies a wider ladder.

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.

Provider Base URL
OpenAI (API key) https://api.openai.com/v1
Anthropic (API key) https://api.anthropic.com
OpenRouter https://openrouter.ai/api/v1
OpenCode Go https://opencode.ai/zen/go/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
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
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
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
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
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). Volcengine Agent Plan uses its native Responses endpoint through openai-responses.

OpenCode Go is an upstream provider, not the OpenCode client

opencode-go is the OpenCode Go subscription provider at https://opencode.ai/zen/go/v1. It is distinct from the OpenCode Desktop/CLI client described in OpenCode. Create its key in the OpenCode console, then add OpenCode Go from the dashboard's Providers page or configure the opencode-go preset with that key. CodexCommander does not use an OpenCode authentication store or Keychain for this key.

The public model catalog is not evidence that a key works, so a saved key is unverified until the first successful inference using that active key. With a configured Go key, CodexCommander reads OpenCode's Go usage endpoint and shows its account-wide rolling, weekly, and monthly used percentages and reset times in the dashboard and macOS menu. When the endpoint is unavailable, the quota view shows only traffic observed through this proxy in the corresponding time windows. Those local request, token, and estimated-cost totals are not the provider's current balance or per-model allowance. A concrete upstream limit event can also be shown with its reported reset.

OpenCode Go's Overview in the dashboard also shows completed requests and tokens for each model over the last 30 days; the Usage tab retains the full model breakdown. Expanding OpenCode Go in the macOS menu shows the same per-model completed usage beside the provider quota. While a request is active, the menu identifies its model as In flight; its final token count appears only after the request completes and the proxy records it. Unmeasured token totals are shown as unknown rather than zero, and estimated cost appears only when pricing is available for that model.

The Muse Spark 1.2 and 1.3 Contributor models may use submitted prompts and completions to train future Meta models. See Meta's Contributor tier terms before sending data through either model.

The provider keeps a reviewed fallback catalog of OpenCode Go models, including deepseek-v4.1-flash, gpt-6-luna, and grok-4.7. With a Go key, live /v1/models discovery determines which of those models the account can use. That endpoint returns model ids without transport metadata, so a new id appears in Commander after its protocol is verified and added to the trusted catalog; unverified ids are held back. The OpenCode Go endpoint table identifies models using Anthropic Messages, OpenAI Responses, or Chat Completions. These transport facts attach only to the canonical https://opencode.ai/zen/go/v1 destination; a same-named custom provider keeps its own behavior.

OpenCode Go requires a session identifier for each conversation. CodexCommander derives an opaque x-opencode-session from the Codex task or session header and keeps it stable through that conversation, including subagent turns. Claude Code turns use their per-session metadata when available. An explicit x-opencode-session from a Responses, Chat Completions, or Messages client is used when no Codex identity is available. Requests without either identifier receive a distinct temporary session, and a configured provider header takes precedence. This behavior applies only to the canonical OpenCode Go destination. The proxy identifies itself with a CodexCommander user agent unless the provider configuration sets one explicitly.

The built-in preset is key-based, so Add Provider groups it under Paid, not account-login providers, and CodexCommander does not offer an OpenCode Go OAuth flow. It is also separate from both the OpenCode client under Client Apps and the no-key OpenCode Free provider. Add Provider search spans Accounts, Free, and Paid, so searching opencode from any tab shows all matching presets with their tier labels.

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

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 CodexCommander is the documented use; pointing other automation at a plan key is not. The pay-as-you-go volcengine route carries no such restriction.

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. ccx 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. Chat requests use the configured Bearer key. Create keys at Command Code Studio.

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.

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.

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

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 ccx account list, ccx account current, and ccx 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 ccx 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-* Installed native catalog value; pinned metadata when unavailable
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 installed upstream reasoning ladders; pinned metadata is the fallback. 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.

:::note[Gateways & subscription proxies] A provider is included when CodexCommander 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-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 (ccx 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.

Copilot fronts a mixed-wire catalog: its GPT-5 family (gpt-5.3-codex, gpt-5.4, gpt-5.4-mini, gpt-5.5, gpt-5.6-luna, gpt-5.6-sol, gpt-5.6-terra) rejects /chat/completions for agent traffic, so CodexCommander routes those models over the Responses API by built-in default while every other Copilot model stays on chat completions. The precedence is: hard wire pin → your explicit modelAdapters entry → registry default → provider-wide adapter. To opt a model without a built-in default (for example gpt-5.4-nano) into Responses, set "modelAdapters": { "gpt-5.4-nano": "openai-responses" }.

Cursor is tracked separately as an experimental unofficial adapter. adapter: "cursor" appears in ccx init and the dashboard Add Provider picker as an experimental local config entry with Cursor's static fallback model catalog metadata. Default auth is PKCE (ccx login cursor). A pasted dashboard user API key is dual-mode on the same canonical cursor provider: set authMode: "key" (Add Provider → Use an API key instead, or the Settings API-key pool). OAuth accounts are only for providers.cursor; a custom id with adapter: "cursor" can still use a key, but the dashboard will not show Cursor OAuth controls that the backend cannot honor. That key uses the same unofficial api2.cursor.sh AgentService/Run protocol as OAuth — it is not a documented OpenAI /v1/chat/completions credential, and Cursor Cloud Agents keys from api.cursor.com are a different product and will not work here. Dashboard crsr_ user API keys are exchanged via POST /auth/exchange_user_api_key when they are not already a valid Run Bearer. When a Cursor access token is configured, CodexCommander uses Cursor's live HTTP/2 transport. Its bundled fallback seed includes gpt-5.6-sol / terra / luna (1M context), grok-4.5 / grok-4.5-fast (500K), and kimi-k3 (262K); live discovery decides which remain visible for the account. Cursor serves Kimi K3 only as effort-suffixed wire ids, so cursor/kimi-k3 exposes a low / high / max ladder and defaults to max, matching the model's documented API default. 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 nativeLocalExec: "on" on the providers.cursor object in ~/.codexcommander/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, CodexCommander returns typed no-executor results instead of policy-blocking the request. Cursor OAuth, API-key dual-mode, and live model discovery are enabled for this experimental adapter. The dashboard still shows the elevated ToS warning for Cursor OAuth. :::

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. CodexCommander 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 CodexCommander 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 ccx init and enter the base URL. See the Configuration reference for every provider field (headers, noReasoningModels, noVisionModels, models, …).