Skip to main content
Codex Desktop uses the same local configuration as Codex CLI. Install Codex Desktop first, then write the dashboard-generated config.toml and auth.json into the Codex config directory. If you already completed the Codex setup, open or restart Codex Desktop. You do not need to create another API Key.

​
Prerequisites

  • You have completed Create an account.
  • You have completed Get an API Key.
  • Codex Desktop is installed.
  • The Use key dialog is open for the API Key you want to use.
The API Key in auth.json is stored as a local plaintext credential. Do not commit ~/.codex/auth.json, screenshots, or terminal output to a repository or chat.

​
Install

Download and install Codex Desktop from the OpenAI Codex app documentation. After installation, open the app and complete the initial setup shown by Codex Desktop. If Codex Desktop is not available for your system yet, use Codex CLI for terminal access.

​
Copy config from the dashboard

1

Open API Keys

Open the dashboard and go to API Keys.
2

Choose Codex CLI

Find the key you want to use for Codex Desktop, click Use key, then choose Codex CLI.
3

Choose your system

Select macOS / Linux or Windows. The dashboard shows the target config file paths.
4

Write local config

Follow the matching system steps on the Codex page to write config.toml and auth.json.
5

Restart Codex Desktop

Save the config, quit Codex Desktop completely, then open it again.

​
Config file paths

Systemconfig.tomlauth.json
macOS / Linux~/.codex/config.toml~/.codex/auth.json
Windows%USERPROFILE%\.codex\config.toml%USERPROFILE%\.codex\auth.json
If you use Codex inside WSL, configure WSL’s ~/.codex/ directory instead of the Windows user directory. Use the model, review_model, base_url, and API Key values shown in the dashboard. See the Codex page for field meanings.

​
Verify

Open Codex Desktop, choose a local project, then send a low-risk task: 
Describe the purpose of the current project in one sentence. Do not modify files.
If Codex Desktop responds without authentication or model errors, the config is active.

​
Common issues

No. Codex Desktop reads the same ~/.codex/ config. Quit Codex Desktop completely, then open it again.
Put the new config at the beginning of config.toml. Save, quit Codex Desktop completely, and open it again.
Check that auth.json is valid JSON. Confirm the API Key has no missing characters, newlines, or extra spaces.
model and review_model must match the dashboard model name exactly. Do not copy names from someone else’s screenshot.