Skip to main content

​
One command

The CLI 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 lx1-* slug. See CLI.

​
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.layerx1] header — TOML scopes every key after a table header into that table, so model written below it silently becomes model_providers.layerx1.model.
~/.codex/config.toml
Do not set env_key = "LAYERX1_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 layerx1 setup writes experimental_bearer_token instead. The catalog file is required too. Without it Codex prints Model metadata for lx1-deepseek-v4-flash not found and falls back to generic limits. Setup writes ~/.codex/model-catalogs/layerx1.json (merged with your existing OpenAI cache so the picker is not wiped) 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 lx1-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.layerx1] header below it is invalid TOML. Merge the provider into the inline table (see above) — npx layerx1 setup does this for you from 0.2.2 on.
  • Codex still calls its old model? model is a top-level key and Codex only serves one: if it still says e.g. gpt-5.6-terra, that request goes to Layer X1 under a model id the gateway doesn’t serve. Setup takes the key over and leaves the old value as a # layerx1:was … comment; npx layerx1 unset puts it back.
  • A [profiles.…] in play? A profile’s own model / model_provider beat the top-level ones — set model_provider = "layerx1" inside the profile you launch with.
  • 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: LAYERX1_API_KEY? An older installer set env_key and expected the variable in the process environment. Re-run npx layerx1 setup --tool codex --key lx1_your_key (0.2.4+) — the key goes in the provider table, so Desktop and already-open terminals work.
  • Model metadata for lx1-… not found? Codex only ships OpenAI slugs. Setup writes model_catalog_json pointing at ~/.codex/model-catalogs/layerx1.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.