> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layerx1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex CLI on Layer X1.

> Codex talks the OpenAI Responses protocol. One provider block in config.toml points it at the gateway; the key lives in that block so Desktop and new terminals work without an env var.

## One command

```sh theme={null}
npx layerx1 setup --tool codex --key lx1_your_key
```

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](/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`.

```toml title="~/.codex/config.toml" theme={null}
model = "lx1-deepseek-v4-flash"
model_provider = "layerx1"
model_context_window = 1000000
model_auto_compact_token_limit = 800000
model_catalog_json = "/home/you/.codex/model-catalogs/layerx1.json"

[model_providers.layerx1]
name = "Layer X1"
base_url = "https://api.layerx1.com/v1"
experimental_bearer_token = "lx1_your_key"
requires_openai_auth = false
wire_api = "responses"
```

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:

```toml title="~/.codex/config.toml" theme={null}
model_providers = { layerx1 = { name = "Layer X1", base_url = "https://api.layerx1.com/v1", experimental_bearer_token = "lx1_your_key", requires_openai_auth = false, wire_api = "responses" } }
```

`model` accepts any [catalog id](/models) — 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](/api/responses) dialect on `/v1/responses` for exactly this client.

<Note>
  Switching models mid-project is a one-line change to `model` — the provider block stays
  put.
</Note>