Skip to main content

​
One command

The setup helper writes the provider block below into ~/.codex/config.toml (with a backup), puts the key in experimental_bearer_token, and writes a model catalog so Codex knows the Sideren model ids. See setup helper.

​
By hand

Add a provider to ~/.codex/config.toml. Three details matter: the base URL includes /v1, the wire protocol is responses, and the top-level keys go above the [model_providers.sideren] header — TOML scopes every key after a table header into that table, so model written below it silently becomes model_providers.sideren.model.
~/.codex/config.toml
Do not set env_key = "SIDEREN_API_KEY". Codex checks that variable first and errors when it is missing — including in Codex Desktop, which does not inherit User environment variables. npx sideren setup writes experimental_bearer_token instead. The catalog file is required too. Without it Codex prints Model metadata for auto not found and falls back to generic limits. Setup writes ~/.codex/model-catalogs/sideren.json, with one entry per Sideren model (its own context window, compaction limit and reasoning levels), and points model_catalog_json at it. If your config already declares model_providers as an inline table, add the provider inside it instead — TOML cannot extend an inline table with a dotted key:
~/.codex/config.toml
model accepts any catalog id — a coding flagship like @sdn/glm-5 is a strong daily driver for heavy sessions.

​
Troubleshooting

  • cannot extend value of type inline table with a dotted key? Your config already has model_providers = { … } on one line, and a [model_providers.sideren] header below it is invalid TOML. Merge the provider into the inline table (see above) — npx sideren setup does this for you.
  • Codex still calls its old model? model is a top-level key and Codex only serves one: if it still names an OpenAI-only slug that isn’t in the catalog, that request goes to Sideren under a model id the gateway doesn’t serve. Setup takes the key over and leaves the old value as a # sideren:was … comment; npx sideren unset puts it back.
  • A profile in play? A profile file (~/.codex/<name>.config.toml, used with codex --profile <name>) is layered over config.toml, so its own model / model_provider beat the top-level ones. Set model_provider = "sideren" inside the profile you launch with. Codex 0.134 and later no longer read [profiles.…] tables or a top-level profile = … key.
  • Empty responses? Reasoning models spend hidden reasoning tokens from max_output_tokens — a very low budget can be consumed before any text is emitted. Raise it (4,000+ is a safe floor) or pick a non-reasoning model.
  • Missing environment variable: SIDEREN_API_KEY? An older version of the setup helper set env_key and expected the variable in the process environment. Re-run npx sideren setup --tool codex --key sdn_your_key — the key goes in the provider table, so Desktop and already-open terminals work.
  • Model metadata for … not found? Codex only ships OpenAI slugs. Setup writes model_catalog_json pointing at ~/.codex/model-catalogs/sideren.json. Re-run setup if that file is missing.
  • 401 unauthorized? The provider table’s experimental_bearer_token is empty or stale — re-run setup with --key.
  • 404s? Unlike Claude Code, the Codex base URL must end in /v1.
  • Protocol errors? Keep wire_api = "responses" — the gateway serves the Responses dialect on /v1/responses for exactly this client.
Switching models mid-project is a one-line change to model — the provider block stays put.