Skip to main content
Codex Desktop reads the same user-level Codex configuration as Codex CLI. You can add Flatkey as a custom model provider without replacing your official ChatGPT or Codex login.

​
Prerequisites

  • Codex Desktop installed
  • One completed official ChatGPT or Codex sign-in in the desktop app
  • A Flatkey API key — create one in the Flatkey Console
  • A supported model ID from the Flatkey Model Directory
  • CC Switch v3.16.1 or later, preferably the latest version, if you use the CC Switch setup

​
Manual configuration

​
1. Set the API key

Store the key in a user environment variable instead of writing it into a configuration file.
After changing the variable, fully quit Codex Desktop before reopening it.

​
2. Update config.toml

Open the user-level Codex configuration file: Update the top-level model and model_provider settings. If either key already exists, replace its value instead of appending a duplicate key. Preserve all unrelated settings. Then add the provider table below; if [model_providers.flatkey] already exists, update that table instead of creating a duplicate:
gpt-5.4 is available in the Flatkey Model Directory at the time of writing. Check the directory before switching to a different model ID.
Do not replace or paste a Flatkey API key into auth.json. That file stores the official ChatGPT or Codex login that the desktop app uses for account access and model-picker state.

​
3. Restart and verify

Fully quit Codex Desktop, reopen it, and send a small prompt. Open Flatkey Usage Logs and confirm the model, token counts, latency, and cost.

​
Configure with CC Switch

CC Switch is a third-party desktop configuration manager. You can also download it from the official GitHub repository.
  1. Open Codex Desktop and complete an official ChatGPT or Codex sign-in at least once.
  2. In CC Switch, enable Settings → General → Codex App Enhancements → Keep official login for direct switches. In v3.16.1–v3.16.x, this option is labeled Keep official login when switching third-party providers.
  3. Open the Codex panel and add a Custom Provider named Flatkey.
  4. Set Base URL to https://router.flatkey.ai/v1.
  5. Select the OpenAI Responses protocol.
  6. Enter the Flatkey API key and choose a supported model such as gpt-5.4.
  7. Activate the provider, fully quit Codex Desktop, and reopen it.
  8. Send a small prompt and verify the request in Flatkey Usage Logs.
Flatkey supports the Responses route directly. Do not enable CC Switch Local Routing unless a future provider change explicitly requires protocol conversion.

​
If the model is not visible

The Codex Desktop model picker can depend on the official login state and the app’s current model catalog. A missing custom model in the picker does not prove that the provider configuration failed.
  1. Confirm the official ChatGPT or Codex login is still active.
  2. In CC Switch, confirm Keep official login for direct switches is enabled. In v3.16.1–v3.16.x, confirm the legacy Keep official login when switching third-party providers option instead.
  3. Confirm model_provider = "flatkey" and the intended model ID in config.toml.
  4. Fully quit and reopen Codex Desktop.
  5. Use Flatkey Usage Logs to verify which provider handled the real request.
Keeping the official login does not route model traffic to OpenAI billing. The active provider in config.toml or CC Switch controls request routing.

​
Switch back to the official provider

In CC Switch, activate the official Codex provider and restart Codex Desktop. For a manual setup, restore your previous model_provider and model values in config.toml. Keep auth.json unchanged so the official login remains available.

​
Troubleshooting