Setup guide · as of 2026-11-04

Codex CLI Third-Party API Setup Guide

As of November 20, 2026, Codex CLI rust-v0.171.0 (published 2026-11-20) added GPT-6.2 Sol and Astra to model catalogs with Sol as the default catalog selection; to pin a model on a custom provider, write model = "gpt-6.2-sol" explicitly in ~/.codex/config.toml, or use codex --model gpt-6.2-sol for a one-off run. A Codex relay means pointing Codex CLI at an endpoint that serves the OpenAI Responses protocol and paying per token with a key that starts with cr_ – a system separate from a ChatGPT subscription. As of 2026-11-04, QCode's docs set base_url for Codex to https://api.qcode.cc/openai. As of 2026-10-07, you connect Codex CLI to a third-party or custom endpoint by adding your own table under model_providers in ~/.codex/config.toml, with base_url, wire_api and env_key (the name of the environment variable that holds your key), and pointing the top-level model_provider at it; the official config reference says responses is the only supported wire_api value. For QCode, base_url is https://api.qcode.cc/openai; QCode's docs set requires_openai_auth = true in that table and put the key in ~/.codex/auth.json, and to pass the key through an environment variable instead you replace that line with env_key – use one or the other. This page walks through each key, the common errors and which models to pick.

Updated 2026-11-20

Point this tool at the QCode endpoint — one key for Claude, GPT and Chinese models.

#config.toml#model_providers#base_url#gpt-6.1-sol

Four values to get right

responses

The only wire_api value

The official config reference states that responses is the only supported value and also the default when the field is omitted. QCode's docs set wire_api to responses too, which maps to the /openai/v1/responses path.

env_key

env var that holds the key

env_key holds the name of an environment variable, not the key itself; the official wording is the environment variable supplying the provider API key. QCode keys start with cr_. You can pick the variable name yourself; the QCode docs example uses QCODE_API_KEY.

/openai

Where QCode's base_url ends

QCode's docs say Codex's base_url must be https://api.qcode.cc/openai; Codex speaks the Responses protocol, so requests land on /openai/v1/responses.

As of November 20, 2026, the newest entry in OpenAI's official GitHub releases is Codex CLI rust-v0.171.0 (published 2026-11-20). Before it, as of 2026-11-04 the newest was Codex CLI 0.166.0 (2026-10-29); earlier still, 0.160.1 on 2026-10-05 was the newest, and since 0.159.1 (2026-09-29) the bundled model catalog used GPT-6.1 Sol as its default model.

Newest CLI in OpenAI's official releases

As of 2026-11-04, the newest entry in OpenAI's official GitHub releases is Codex CLI 0.166.0 (2026-10-29). Before it, 0.160.1 on 2026-10-05 was the newest; since 0.159.1 (2026-09-29) the bundled model catalog uses GPT-6.1 Sol as its default model.

How Codex picks an endpoint

As of 2026-10-07, Codex CLI decides where requests go from model_provider in config.toml: its value is the id of a table under model_providers, and it defaults to openai when unset. The official docs say a model provider defines how Codex connects to a model, covering the base URL, wire API, authentication and optional HTTP headers, and custom providers can't reuse the reserved built-in ids openai, ollama and lmstudio.

User-level config lives in ~/.codex/config.toml (on Windows under %USERPROFILE%\.codex\); a project's .codex/config.toml loads only once you trust the project, and model_provider and model_providers are ignored at that project level. QCode's docs name the provider qcode and use the OpenAI Responses protocol, and the same key works on api.qcode.cc, us.qcode.cc and asia.qcode.cc.

Recent releases that touch providers

As of November 20, 2026: Codex CLI rust-v0.171.0 shipped on 2026-11-20, adding GPT-6.2 Sol and Astra to model catalogs with Sol as the default catalog selection; on OpenAI's official API the gpt-6.2-sol Standard rate is $2.00 input, $10.00 output and $0.10 cached input, the same as the gpt-6.1-sol Standard rate.

The earlier release changes read: the official changelog shows that from 2026-09-22 GPT-6 Sol and GPT-6 Luna began rolling out to Codex, selectable in the CLI with /model or codex --model gpt-6-sol; on 2026-09-29 Codex CLI 0.159.1 made GPT-6.1 Sol the default model in the bundled catalog; 0.160.0 on 2026-10-01 clarified how env_key identifies the API-key environment variable, stopped explicit provider model catalogs from including unsupported bundled models, and made the terminal UI keep server provider settings; 0.160.1 followed on 2026-10-05, then 0.164.0 on 2026-10-23 and 0.166.0 on 2026-10-29; as of 2026-11-04, 0.166.0 is the newest in the official GitHub releases.

Separately, an official notice of 2026-09-14 gives 2026-10-14 as the date GPT-5.5 retires from ChatGPT, ChatGPT Work and Codex (the retirement does not apply to the OpenAI API), and asks you to update saved model settings, custom agents and scripts that still select gpt-5.5. Check your local version with codex --version.

Timeline

2026-09-22

GPT-6 Sol and GPT-6 Luna start rolling out to Codex; OpenAI recommends Sol for complex coding and agentic workflows, and in the CLI you switch with /model or codex --model gpt-6-sol.

2026-09-29

GPT-6.1 Sol arrives in Codex; the same day Codex CLI 0.159.1 makes it the default model in the bundled catalog. QCode's docs list gpt-6.1-sol as the updated GPT-6 Sol.

2026-10-05

Codex CLI 0.160.1 ships, the newest CLI entry in the official changelog when this page was checked on 2026-10-07; before it, 0.160.0 on 2026-10-01 had clarified the env_key documentation. Afterwards 0.164.0 shipped on 2026-10-23 and 0.166.0 on 2026-10-29; as of 2026-11-04, 0.166.0 is the newest.

Confirmed vs not verified

Confirmed (verbatim in official pages and QCode docs)

Official Codex docs: model_provider defaults to openai; openai, ollama and lmstudio are reserved ids that can't be overridden; responses is the only supported wire_api value and the default when omitted; env_key is the environment variable supplying the API key; requires_openai_auth defaults to false; putting a direct bearer token in experimental_bearer_token is discouraged; model and model_provider must sit before the first TOML table.

Official changelog: GPT-6.1 Sol is the bundled catalog default from 0.159.1, and 0.160.1 shipped on 2026-10-05. QCode docs: base_url is https://api.qcode.cc/openai, wire_api is responses, requires_openai_auth is true, and the key starts with cr_ and goes in OPENAI_API_KEY in ~/.codex/auth.json; for the environment-variable variant, requires_openai_auth = true is replaced with env_key = "QCODE_API_KEY", and only one of the two may be used.

Not verified or not documented

Four points are unverified, so don't build on them: first, the official config reference fetched for this page on 2026-10-07 has no preferred_auth_method entry, and QCode's current example no longer includes that line, so what it does in current versions if an older config still has it is unverified; second, the official reference also offers a command-backed auth table, http_headers, supports_websockets and more, which QCode's docs don't cover, and this page makes no promise they work with QCode; third, whether Codex releases before 0.159.1 recognize the name gpt-6.1-sol was not checked, and the official gateway doc only says that without a custom catalog you should first confirm your Codex version recognizes the model; fourth, OpenAI says GPT-6.1 Sol offers near-Astra performance at a lower cost than Astra, which is the vendor's own claim with no third-party measurement.

Two choices to settle

Custom provider vs openai_base_url

The official docs offer two routes: if you only need to point the built-in openai provider at a proxy or router, set openai_base_url instead of defining a new provider; if you need your own key variable and protocol settings, add a table under model_providers. You can't create a table named openai, because built-in ids can't be overridden. QCode's docs use the second route (provider qcode) and don't document openai_base_url, so this page doesn't recommend it for QCode.

auth.json vs environment variable

QCode's docs say to use one or the other: either set requires_openai_auth = true in the provider table and put OPENAI_API_KEY in ~/.codex/auth.json (the docs' main setup), or replace requires_openai_auth = true with env_key = "QCODE_API_KEY" and export QCODE_API_KEY. The official docs say Codex ignores env_key when requires_openai_auth = true, so with both in the table the environment variable has no effect.

OpenAI advises keeping credentials out of TOML files and repositories, and notes that a variable set in a terminal may not be available to an app launched from the desktop.

Five steps to connect QCode

As of November 20, 2026 the bundled catalog default is GPT-6.2 Sol, so pin the model in the config if you need it fixed. Following QCode's docs

  1. 1create the config folder ~/.codex (on Windows, %USERPROFILE%\.codex)
  2. 2put the top-level keys at the start of config.toml: model_provider set to qcode, model set explicitly to gpt-6.2-sol (the rust-v0.171.0 catalog default as of 2026-11-20), gpt-6.1-sol or gpt-6-sol, and optionally model_reasoning_effort; for a one-off run use codex --model gpt-6.2-sol; they must come before the first table header, or they are read as part of that table
  3. 3add a model_providers.qcode table with name qcode, base_url https://api.qcode.cc/openai, wire_api responses, requires_openai_auth true (from North America and Europe you can swap the host for us.qcode.cc)
  4. 4supply the key: put your cr_ key as OPENAI_API_KEY in ~/.codex/auth.json; to pass the key through an environment variable instead, replace requires_openai_auth = true in the table with env_key = "QCODE_API_KEY" and export QCODE_API_KEY. Use one or the other: the official docs state that Codex ignores env_key when requires_openai_auth = true
  5. 5start codex and run /status to confirm the active model and provider, or run codex doctor to check the config.

Using Codex on QCode

Copy a key starting with cr_ from the QCode console and follow the five steps above; or use the one-click setup script from QCode's docs, which installs the CLI, writes the ~/.codex config and runs a connectivity check. Codex speaks the OpenAI Responses protocol, so what it runs on QCode is the GPT family: gpt-6.2-sol, gpt-6.2-astra, gpt-6.2-sol, gpt-6.2-astra, gpt-6.2-sol, gpt-6.2-astra, gpt-6.1-sol, gpt-6.1-terra, gpt-6-sol, gpt-6-astra and gpt-5.6-terra (the model table on the Codex page of QCode's docs, 2026-11-04) can all be called, and so can gpt-5.6-sol, which is still listed on /models, and you switch by changing model only (QCode does not currently support gpt-6-luna or gpt-5.6-luna, so please use one of these GPT models instead); Claude and the GLM, Kimi, DeepSeek and Qwen models don't use this protocol.

The same key also works in Claude Code. Billing is per token; per-model prices are on /models. As of 2026-11-04 the top-up page takes Alipay, WeChat Pay, bank cards and cryptocurrency. Alipay, WeChat Pay, cards, Apple Pay and Google Pay usually arrive within a minute; SBP and Russian cards can take a few minutes; crypto is checked by hand and credited within one day.

Not ready for a monthly plan? Pay-as-you-go Packs start at $4 for a one-time quota you use within 7 days; if you already have a Personal Plan, add a booster pack when you need more quota. How to choose a relay is on /how-to-choose-ai-api-relay.

Frequently asked questions

What do I change to use a third-party API in Codex CLI?

Two things in ~/.codex/config.toml: point the top-level model_provider at your own provider id, then add a table for that id under model_providers with base_url, wire_api and env_key. The official config reference says responses is the only supported wire_api value and env_key names the environment variable that supplies the API key; requires_openai_auth marks a provider that uses OpenAI authentication and defaults to false; when it is true, Codex ignores env_key, so use one or the other. QCode's docs set requires_openai_auth = true with the key in ~/.codex/auth.json, and use env_key instead only for the environment-variable variant.

What goes in base_url? Do I add /v1?

For QCode, use https://api.qcode.cc/openai, with no /v1 and no trailing slash. QCode's docs say Codex's base_url must be exactly this, and Codex then uses the /openai/v1/responses path. The endpoints doc's general rule is to leave off the trailing slash, since it produces a double-slash path and a 404; a 404 usually means the path prefix is wrong. The Asia backup is https://asia.qcode.cc/openai, and us.qcode.cc serves North America and Europe.

What if I get 401 or API key not found?

Check three things: that the key starts with cr_ and the one in auth.json has no stray spaces or line breaks; with the environment-variable variant, that the variable name is exactly what env_key says in config.toml (QCODE_API_KEY in QCode's docs), that the table no longer has requires_openai_auth = true (with it, Codex ignores env_key), and that the variable is really set in the current shell; and finally the key's status in the QCode console.

I edited config.toml, so why isn't my provider active?

Most often a top-level key is in the wrong place: the official docs say model and model_provider must come before the first TOML table, because keys after a table header belong to that table. Next, a project's .codex/config.toml ignores model_provider and model_providers, so the provider has to live in your user-level ~/.codex/config.toml, and the table can't be named openai. Also, QCode's docs note that since Codex 0.134.0 the old profiles tables in config.toml are retired, and running --profile while they are still there is a hard error. After starting, /status shows the active model and provider.

Can one key serve both Codex and Claude Code?

Yes. The QCode docs re-checked on 2026-11-04 say Claude Code and Codex use the same QCode API key, and switching models needs no extra setup. But sending a Claude model to Codex will not work: QCode's docs say Codex uses the OpenAI Responses protocol, which serves only the GPT family, not Claude or the GLM, Kimi, DeepSeek and Qwen models; Claude models only work over the Anthropic protocol. The docs' example: sending a Claude model to /openai/v1/chat/completions returns model_not_available_on_endpoint, and that check runs before authentication, so it means the wrong protocol, not a bad key. For Claude, use Claude Code with the same key.

How does a Codex relay differ from one for Claude Code?

As of November 20, 2026 the catalog default is GPT-6.2 Sol (rust-v0.171.0), and gpt-6.2-sol carries the same OpenAI official API Standard rate as gpt-6.1-sol. The difference is the protocol and the models it serves: Codex uses the OpenAI Responses protocol and only the GPT family, while Claude Code uses the Anthropic protocol and Claude models. The rest stays as before. As of 2026-10-07, QCode's docs recommend gpt-6-sol by default (1.05M context, general and complex work); gpt-6.1-sol is the GPT-6 Sol update of 2026-09-29, also with 1.05M context and, per the docs, cache reads priced lower, and it has been the bundled catalog default in official Codex since 0.159.1; gpt-5.6-sol belongs to the GPT-5.6 flagship line, gpt-5.6-terra is tuned for code, gpt-6-astra is the top tier at a high price, and gpt-6-luna is what OpenAI positions for focused, high-volume tasks. All of them except gpt-6-luna can be called on QCode; switch by changing model or with codex --model. QCode does not currently support gpt-6-luna or gpt-5.6-luna (not supported on QCode); please use another GPT model, such as gpt-6.1-sol, gpt-6-sol or gpt-5.6-terra. Re-checked on 2026-11-04, the model line on the Codex page of docs recommends gpt-6.1-sol as the default model. As of 2026-11-04, the model table on the Codex page of QCode's docs lists gpt-6.1-sol, gpt-6.1-terra, gpt-6-sol, gpt-6-astra and gpt-5.6-terra; gpt-6.1-terra is the mid tier of GPT-6.1, for everyday coding and batch work. gpt-5.6-sol is not in that table but is still listed on /models.

Sources

Checked on 2026-11-20: the official Codex CLI rust-v0.171.0 release (github.com/openai/codex/releases/tag/rust-v0.171.0, published 2026-11-20), OpenAI's official Codex models page (developers.openai.com/codex/models, with the codex --model gpt-6.2-sol and model = "gpt-6.2-sol" forms) and OpenAI's official API pricing page (Standard tier, where gpt-6.2-sol carries the same rate as gpt-6.1-sol). Codex config keys: OpenAI's official Codex configuration reference and advanced configuration docs (learn.chatgpt.com, checked 2026-10-07), covering the model_provider default, reserved ids, the wire_api value, env_key and requires_openai_auth, openai_base_url and the keys ignored at project level. Top-level key placement, credential handling and the /status check: the official Connect to a gateway doc, checked the same day. Versions and models: the official ChatGPT and Codex changelog, checked the same day (0.159.1, 0.160.0, 0.160.1, the GPT-6 Sol and GPT-6.1 Sol announcements, and the GPT-5.5 retirement notice). QCode's setup, base_url, env_key name, key prefix and model list: the Codex complete guide, Codex quick start and endpoints and API formats pages on docs.qcode.cc, checked 2026-10-07. Re-checked on 2026-11-04 against four pages on docs.qcode.cc: the Codex complete guide, endpoints and API paths, payment methods, and subscriptions versus API keys.

Connect Codex with one key

Set base_url to https://api.qcode.cc/openai and pick gpt-6.1-sol, gpt-6-sol or gpt-5.6-sol, billed per token, ready the moment you sign up.

Not sure where to start?

Try it for a week

Small Pack: $4 for $30 of quota, valid 7 days

Use it every day

Starter: $9.00/month with $5 of quota every day — just $0.060 per $1 of quota, vs about $0.113 for the Medium Pack