Use Flatkey with Codex Desktop

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, 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.

[Environment]::SetEnvironmentVariable(
  "FLATKEY_API_KEY",
  "sk-fk-...",
  "User"
)

launchctl setenv FLATKEY_API_KEY "sk-fk-..."

export FLATKEY_API_KEY="sk-fk-..."

After changing the variable, fully quit Codex Desktop before reopening it.

2. Update `config.toml`

Open the user-level Codex configuration file:

Platform	Configuration path
Windows	`%USERPROFILE%\.codex\config.toml`
macOS and Linux	`~/.codex/config.toml`

Before replacing the top-level model and model_provider settings, record their current values so you can restore them later. Then update both settings. If either key already exists, replace its value instead of appending a duplicate key. Preserve all unrelated settings. Add the provider table below; if [model_providers.flatkey] already exists, update that table instead of creating a duplicate:

model = "gpt-5.4"
model_provider = "flatkey"

[model_providers.flatkey]
name = "Flatkey"
base_url = "https://router.flatkey.ai/v1"
env_key = "FLATKEY_API_KEY"
wire_api = "responses"

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.

Official credentials may be stored in auth.json or your operating system’s credential store. Never edit, replace, overwrite, export, or share either credential store for Flatkey setup. Never paste a Flatkey API key into either one. config.toml controls model and provider routing.

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 configuration manager, not a Flatkey product. You can also download it from the CC Switch GitHub repository. The steps below follow the current CC Switch interface. Manual configuration and CC Switch are alternative setup methods. Use one method for the active provider. Codex Desktop and Codex CLI share ~/.codex/config.toml on macOS and Linux, or %USERPROFILE%\.codex\config.toml on Windows. CC Switch controls the model and provider settings in that shared file. Preserve unrelated settings and providers. Open Codex Desktop and complete an official ChatGPT or Codex sign-in before switching providers. Do this at least once so the desktop app has a valid official session for account access and its model catalog. The official credentials are stored in auth.json or your operating system’s credential store. Treat both as sensitive. In CC Switch, open Settings > General > Codex App Enhancements, then enable Keep official login for direct switches. The setting prevents a direct provider switch from discarding the official login that Codex Desktop still needs.

Enable the current official-login preservation setting for Codex

Never open auth.json for copying, replace or overwrite it, paste a Flatkey API key into it, or share it. Never expose your Flatkey API key in screenshots or CC Switch provider exports. If either credential is exposed, rotate or revoke it immediately.

3. Add Flatkey as a custom provider

Open the Codex panel in CC Switch and add a Custom Provider. Use the following values. This tutorial does not rely on a built-in Flatkey provider.

Open the Codex provider panel and select the add-provider button in CC Switch

Provider field	Value
Provider Name	`flatkey`
API Key	`sk-fk-...`
API Request URL	`https://router.flatkey.ai/v1`
Default Model	`gpt-5.6-sol` in the screenshot — verify a current exact ID in the Flatkey Model Directory
Upstream Format	Responses (native)

Enter the current Flatkey provider fields in CC Switch

4. Configure the model

Set the provider’s Default Model to the exact Flatkey model ID you want to use. The screenshot shows gpt-5.6-sol as an example. Check the Flatkey Model Directory before choosing an ID. Click Fetch Models to load current IDs. Add the model to the provider’s Model Mapping when you want it in the Codex /model menu. You can also set an exact ID as the provider’s Default Model or pass it from Codex CLI with codex --model <id>. For Codex Desktop, treat the active provider and default model as the intended route even if the picker does not list the custom model. Confirm the actual route with Flatkey Usage Logs after sending a request.

Choose Responses native and configure the Codex model mapping

Flatkey natively supports the Responses API. Keep Local Routing off; it is not required for this setup.

5. Save, activate, and restart

Save the custom provider and activate it for Codex. Do not remove unrelated settings or providers from the shared config.toml.

Confirm that the Flatkey Codex provider is in use

Fully quit Codex Desktop. Make sure no old Codex Desktop process remains, then reopen the app so it reads the new provider settings.

6. Verify the actual route

Start a new conversation with a small context and send a minimal prompt. Then open Flatkey Usage Logs and confirm the model, token counts, latency, and cost for that request.

Verify the Flatkey route with a minimal Codex Desktop response

Keeping the official login does not mean the request uses OpenAI billing. The current provider and model settings in the shared config.toml control the route. Flatkey Usage Logs are the authoritative confirmation that the request reached Flatkey. System prompts, tools, conversation history, attached files, and command output can increase input tokens beyond the text in your visible prompt. Higher input token counts can increase billed cost.

If the model is not visible

Codex Desktop may show the official model catalog and omit a custom model from its picker. A missing custom model in the UI does not prove that routing failed.

Confirm the official ChatGPT or Codex login is still active.
Confirm Settings > General > Codex App Enhancements > Keep official login for direct switches is enabled.
Confirm the Flatkey provider is active and its Default Model contains the exact model ID.
Check the provider’s model mapping. Use Fetch Models when you want the model in the /model menu.
Confirm the shared config.toml contains the intended active provider and model without changing unrelated settings.
Fully quit every Codex Desktop process and reopen the app.
Send a minimal prompt and check Flatkey Usage Logs for the actual route.

Switch back to the official provider

If you used CC Switch, activate the official Codex provider. Fully quit Codex Desktop, make sure no old process remains, and reopen it. You do not need to delete the Flatkey custom provider. If you used manual configuration, restore the previous top-level model and model_provider values in config.toml. Preserve unrelated settings and provider tables. Leave the official credentials in auth.json or the operating system’s credential store untouched. Fully quit Codex Desktop, make sure no old process remains, and reopen it.

Troubleshooting CC Switch

Issue	What to check
Official login is missing or expired	Sign in again through Codex Desktop, then enable Keep official login for direct switches before activating Flatkey
Authentication fails or the Flatkey key is rejected	Confirm the API key is active and was entered in the custom provider’s API key field; rotate or revoke it if it was exposed
Endpoint or Responses errors	Set API Request URL to `https://router.flatkey.ai/v1`, select Responses (native), and keep Local Routing off
`Model not found`, custom model is hidden, or `/model` mapping is missing	Copy an exact ID from the Model Directory, set it as Default Model, and use Fetch Models or model mapping
Usage Logs show the wrong provider or model	Activate the Flatkey custom provider and confirm its default model and the active values in the shared `config.toml`
Changes do not take effect	Fully quit Codex Desktop, end any stale Codex Desktop process, and reopen the app
Flatkey balance is insufficient	Add balance or use a Flatkey key with available credit, then retry a minimal prompt
Local Routing is enabled by mistake	Turn Local Routing off because Flatkey accepts native Responses requests
A request is missing from Usage Logs	Start a new small-context conversation, send a minimal prompt, then recheck the active provider, API endpoint, and Usage Logs
Official login disappeared after switching	Sign in again through Codex Desktop and enable the login-preservation setting; never replace or overwrite `auth.json`

Quick Start

Code

Mainstream AI Tools

Media Generation

Popular models

Dashboard

Reference

Use Flatkey with Codex Desktop

Prerequisites

Manual configuration

1. Set the API key

2. Update `config.toml`

3. Restart and verify

Configure with CC Switch

3. Add Flatkey as a custom provider

4. Configure the model

5. Save, activate, and restart

6. Verify the actual route

If the model is not visible

Switch back to the official provider

Troubleshooting CC Switch

​Prerequisites

​Manual configuration

​1. Set the API key

​2. Update config.toml

​3. Restart and verify

​Configure with CC Switch

​1. Complete one official sign-in

​2. Preserve the official login for direct switches

​3. Add Flatkey as a custom provider

​4. Configure the model

​5. Save, activate, and restart

​6. Verify the actual route

​If the model is not visible

​Switch back to the official provider

​Troubleshooting CC Switch

Prerequisites

Manual configuration

1. Set the API key

2. Update `config.toml`

3. Restart and verify

Configure with CC Switch

1. Complete one official sign-in

2. Preserve the official login for direct switches

3. Add Flatkey as a custom provider

4. Configure the model

5. Save, activate, and restart

6. Verify the actual route

If the model is not visible

Switch back to the official provider

Troubleshooting CC Switch