How to connect Codex Desktop to Apily

1. Install the official desktop app

1. Install the official app from OpenAI's Codex app page.
2. Open the installed app once.
3. Fully quit the app before editing its configuration; save any open work first.

2. Save the Apily model catalog

1. Open your personal ~/.codex folder, or %USERPROFILE%\.codex on Windows. Create it if absent.
2. Save the catalog in that folder as apily-codex-models.json using the download link: Download the model catalog.
3. Copy the catalog’s full absolute path for model_catalog_json; do not use a relative path or ~.

3. Add your personal configuration

Use your personal ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows), not the project config. If CODEX_HOME is set, use config.toml in that directory.

1. Make a private backup of the existing configuration before editing it. If absent, create the personal directory and file.
2. Merge this example without replacing unrelated settings or duplicating keys. Keep the top-level settings before the first [table].
   Personal config.tomlCopy

   model = "gpt-6.1-terra"
   model_provider = "apily"
   model_reasoning_effort = "low"
   model_catalog_json = "/ABSOLUTE/PATH/apily-codex-models.json"
   web_search = "disabled"
   
   [model_providers.apily]
   name = "Apily"
   base_url = "https://api.apily.pro/v1"
   wire_api = "responses"
   experimental_bearer_token = "apily_your-api-key"
   requires_openai_auth = false
   supports_websockets = false

3. Replace the sample key in the provider table with your own Apily key. How to create a key.
4. Replace model_catalog_json with the copied absolute path. For Windows paths, use a TOML single-quoted literal string so backslashes remain unchanged.
5. Save the configuration file.

4. Open a local chat

Open the Apily model catalog and current prices — Compare current prices before testing: use the lowest-cost compatible model in the supplied catalog. The example ID is not a price or availability guarantee.

1. Reopen the desktop app.
2. Open a local project in the Codex workspace, not a cloud task.
3. Start a new local Codex chat.
4. Select the chosen catalog model in a new local chat; start with Light (low) reasoning if supported.

5. Verify the connection

1. Send this prompt in the client chat.
   Codex Desktop · promptCopy

   Reply with exactly OK. Do not use tools.

2. Confirm that the client’s answer is exactly OK.
3. In Apily, open Usage → Request log and find this paid request by time, model and API key. Inspect its Cost and cost breakdown. Open Usage.

6. Optional: models, catalog and environment key

The downloaded catalog adds these Apily model IDs to the Codex picker. It contains complete Codex model records, so you do not need to build a model list by hand.

• gpt-6.1-terra — default in this guide
• gpt-6-astra · gpt-6-luna · gpt-6.1-sol — choose it in the model picker of a new Codex chat

To change the startup model, edit the top-level model value to a catalog ID. Start a new local chat after changing the model or provider.

When you get an updated catalog, replace the file at the same path and restart Codex. Leave model_catalog_json pointing to that file. Existing chats may keep their previous model, so start a new chat after the change.

In a managed environment, replace only the experimental_bearer_token line inside the existing Apily provider table with:

Remove experimental_bearer_token; do not configure both methods. Pass APILY_API_KEY securely to the process that actually launches Codex. A variable set only in a terminal is not visible to an app opened from the Dock, the Start menu or an already running editor. Fully restart the app after updating its launch environment.

env_key = "APILY_API_KEY"

Codex CLI on the same computer reads the same personal configuration. Open your project directory and run codex. Use /status to check the provider and model, and /model to choose a catalog model. Windows, WSL and remote machines have their own home directories; configure the environment where Codex actually runs.

Troubleshooting

Return to your previous provider

1. Fully quit the app before editing its configuration; save any open work first.
2. Restore only the settings changed for Apily from your private backup. Without a backup, remove only the added Apily table and restore your previous top-level model, provider, catalog, reasoning and web-search values; do not delete the Codex directory or credentials.
3. Reopen the desktop app.

Official sources

Codex desktop app · Connect Codex to a gateway · Configuration reference