Codex Desktop

​

Before you start

• Install the Codex app.
• Copy your alias path and create a Hebo API key. See Getting Started.

​

Configure Codex

1. Open or create ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows) and add these settings. Set model to your alias path:
   config.toml

   model_provider = "hebo"
   model = "my-first-agent-x7k/main/default"
   
   [model_providers.hebo]
   name = "Hebo"
   base_url = "https://gateway.hebo.ai/v1"
   env_key = "HEBO_API_KEY"
   wire_api = "responses"
   supports_websockets = false
   
   Put model_provider and model before the first table header, such as [model_providers.hebo]. If the file already sets these keys or has a [model_providers.hebo] section, update them instead of adding duplicates.
2. Set HEBO_API_KEY for desktop apps. Apps launched from the Dock or Start menu do not read your shell profile.
   macOS

   Windows

   launchctl setenv HEBO_API_KEY "your_api_key_here"
   
   On macOS, the launchctl setenv value lasts until you log out. Run the command again after each login.
3. Quit and reopen Codex Desktop.

​

Verify the connection

​

Switch models

• To use a different model with the same alias, change the Type of the alias in the Hebo Console. Your config.toml stays the same. See Models.
• To use a different alias, set model in config.toml to its alias path. Then quit and reopen Codex Desktop.

​

Troubleshooting

• Authentication errors: Check that HEBO_API_KEY holds a valid Hebo API key. Do step 2 again, then quit and reopen Codex Desktop.
• The app ignores your changes: Check that you edited ~/.codex/config.toml in your home directory, not a .codex/config.toml file in a project folder. If the app still uses old settings, log out of your computer, log in, and do step 2 again.
• BYOK_REQUIRED error: The model needs your own provider credentials. See Bring your own key.