Codex CLI

Codex keeps its configuration in one file:

• macOS / Linux: ~/.codex/config.toml
• Windows: %userprofile%\.codex\config.toml

Codex CLI and Codex Desktop share this file, so one setup covers both.

The easy way

On a Windows or macOS computer, Rabah Desktop one-click setup writes it for you.

1. Copy the configuration

1. Open API Keys in the Hub and click Use Key next to the key you want.
2. Pick the Codex CLI tab, then your system: macOS / Linux or Windows.
3. Adjust the options below if needed, then copy the generated config.toml.

Authentication mode

Mode	What it does
API Key Mode (default, recommended)	The key goes straight into config.toml; Codex’s built-in local image generation works too.
Compatibility mode	The older layout: the key lives in a separate auth.json. Use it if you already set Codex up this way and want to keep it.

In compatibility mode the Hub also gives you an auth.json, which goes in the same folder as config.toml.

Use WebSocket

When ticked, a multi-turn conversation shares one long-lived connection and responds faster. If streams drop or it fails to connect, untick it and copy the configuration again.

Model catalog

Codex needs to know which models it can offer:

• Remote catalog (default, needs Codex 0.156.0 or later): Codex fetches the model list from Rabah with your key, and new models show up on their own.
• Local file (older Codex): click Fetch catalog → Download catalog and save codex-models.json in ~/.codex/.

If the catalog is larger than the remote catalog’s size limit, the Hub switches to the local file for you.

2. Write the file

If the .codex folder doesn’t exist yet, create it:

• macOS / Linux: run mkdir -p ~/.codex in a terminal
• Windows: press Win+R, type %userprofile%, and create a .codex folder in the window that opens

Then paste what you copied into config.toml:

• No file yet: create it and paste.
• The file already has content: put what you copied at the very top. In TOML, settings without a [...] heading must come before every [...] section; further down they would belong to the section above them.

The generated configuration looks roughly like this; use the Hub’s version, which is complete:

model_provider = "OpenAI"
model = "gpt-5.6-sol"

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://api.rabah.ai/v1"
wire_api = "responses"
requires_openai_auth = false
experimental_bearer_token = "YOUR_KEY"

3. Restart Codex

After saving, quit Codex Desktop or the CLI completely, open it again and start a new task. A new conversation alone isn’t enough: Codex reads the configuration when it starts.

Models and lines

• Switch models inside Codex, or edit the model = line in config.toml.
• To use a specific line, write the model as model:line-code. See Models and lines.

Troubleshooting

Authentication fails (401) Check that the key in experimental_bearer_token or auth.json is complete, and that the key isn’t disabled, expired or out of quota in the Hub.

Changes don’t take effect Make sure you quit Codex completely before reopening it. Settings at the top of config.toml also stop working if they end up below a [...] section.

The model list is empty or incomplete Make sure Codex is 0.156.0 or later, or switch to the local file. Also check whether the key’s “Lines & Models” allows only some models.