Connect Codex Desktop to Tokatlas
1. Install and Prepare
Install the desktop client for your operating system through the official OpenAI desktop guide. Prepare a Tokatlas API key and an enabled model compatible with Codex and the Responses API.
The model ID below is a placeholder. Replace it with the exact Tokatlas model ID; a model listed in the client does not establish account access. For a custom alias, obtain a matching Codex model catalog from your gateway administrator.
2. Configure the Provider
Fully quit the app, back up the existing file, then merge the following settings into the user configuration:
| System | Default path |
|---|---|
| macOS | ~/.codex/config.toml |
| Windows | %USERPROFILE%\.codex\config.toml |
model = "YOUR_TOKATLAS_MODEL_ID"
model_provider = "tokatlas"
web_search = "disabled"
[model_providers.tokatlas]
name = "Tokatlas"
base_url = "https://api.tokatlas.ai/v1"
wire_api = "responses"
env_key = "TOKATLAS_API_KEY"Place model, model_provider, and web_search before any TOML table header. Update existing keys instead of duplicating them. Use the user configuration, not a project-local file. If CODEX_HOME is customized, use that configuration directory.
The Base URL ends in /v1; do not append /responses. Start with web search disabled and enable optional features only after confirming gateway support.
3. Make the Key Available to the App
Use TOKATLAS_API_KEY consistently with env_key. Keep the actual key out of config.toml and project files.
macOS
In Terminal, start Bash, enter the following commands, and paste your key at the prompt. Input is hidden.
bashread -r -s -p "Tokatlas API key: " TOKATLAS_API_KEY
printf "\n"
launchctl setenv TOKATLAS_API_KEY "$TOKATLAS_API_KEY"
unset TOKATLAS_API_KEY
exitReopen the desktop app after setting the variable. launchctl setenv applies to your current login session; repeat after logging out or restarting. A variable exported only in .zshrc may not reach an app launched from Finder.
Windows
Open Edit environment variables for your account in Windows settings. Create a user variable named TOKATLAS_API_KEY with your Tokatlas key as its value. Sign out of Windows and sign in again, then launch the app so it receives the new environment.
4. Verify the Connection
Open a project and create a new conversation. Send a small request, such as “Describe this project without changing files.” Check the active model/provider and confirm a successful request in Tokatlas usage records. Then try a small coding task to check streaming and tool behavior.
Switch Models or Restore Settings
To switch models, update the top-level model, restart the app, and create a new conversation. Keep any model catalog consistent with the chosen ID. To return to the prior setup, restore the backed-up configuration and restart; do not delete the entire configuration directory or conversation history.
If the Tokatlas key is no longer needed, remove the Windows user variable or clear it on macOS with:
launchctl unsetenv TOKATLAS_API_KEYTroubleshooting
| Symptom | Check |
|---|---|
| Key missing | Confirm the app process receives TOKATLAS_API_KEY, then fully restart it. |
401 | Verify the complete key and remove surrounding whitespace. |
403 | Check Tokatlas account and model access. |
404 | Check /v1, wire_api = "responses", and the model ID. |
| TOML parse error | Remove duplicate keys/tables and check quotes. |
| Provider unchanged | Inspect the user configuration, selected profile, and managed overrides. |
| Text works but agent fails | Check Responses streaming and tool compatibility for the selected model. |
| Unknown model | Use an enabled ID recognized by the client, or obtain a matching model catalog. |