Codex Desktop App (PC)

Codex Desktop is OpenAI's official standalone desktop application (not the CLI). It wraps the Codex agent in a GUI with parallel threads, Git integration, Plan mode, and built-in automations.

⚠️ Know which product you're using

• Codex CLI: the terminal tool (@openai/codex npm package) — cross-platform
• Codex Desktop App (this page): OpenAI's official GUI app. macOS requires Apple Silicon (M1/M2/M3/M4); Windows is supported since March 2026

Both products share the same ~/.codex/ config directory, so once you set up Tokensmart in the CLI, the Desktop app inherits automatically.

System requirements

Step 1: Download and install

1. Grab the installer from OpenAI: developers.openai.com/codex/app or openai.com/index/introducing-the-codex-app
2. Pick your platform:
   • macOS: .dmg installer, or brew install --cask codex
   • Windows: .exe / .msi installer, or search "Codex" in the Microsoft Store
3. Run the installer
4. On first launch it asks how to sign in: ChatGPT account or API Key

To use Tokensmart, you must choose API Key. Signing in with a ChatGPT account routes everything through your ChatGPT subscription and completely bypasses Tokensmart.

Step 2: Connect to Tokensmart

The Desktop app and the CLI both read ~/.codex/config.toml + ~/.codex/auth.json. Two ways to configure:

Option A: Import via CC-Switch (recommended)

Easiest path — no hand-editing TOML or JSON:

1. Install CC-Switch if you haven't already
2. Sign in to Tokensmart, go to API Keys
3. Pick your key, open the menu next to it → Config Guide
4. Select CC-Switch in the left pane of the modal
5. Click Import to Codex
6. Browser prompts "Open CC-Switch?" — confirm
7. The Tokensmart provider lands in CC-Switch pre-filled — click Enable
8. CC-Switch writes ~/.codex/config.toml and ~/.codex/auth.json for you

Restart Codex Desktop and it picks up the new config. To swap providers later (official vs Tokensmart vs anything else) just click in CC-Switch.

💡 Why CC-Switch: the Desktop app has no "Override API Base URL" GUI setting (only a sign-in screen). Every custom endpoint change has to happen via the ~/.codex/ files on disk. CC-Switch is purpose-built for that and is less error-prone than editing TOML by hand — plus it gives you one-click switching between Tokensmart and the official OpenAI API.

Option B: Edit the config files manually

If you cannot or do not want to install CC-Switch:

~/.codex/config.toml (Windows: %USERPROFILE%\.codex\config.toml)

model_provider = "OpenAI"
model = "gpt-5.4-mini"

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://api.tokensmart.ai/v1"
wire_api = "responses"
requires_openai_auth = true

~/.codex/auth.json (Windows: %USERPROFILE%\.codex\auth.json)

{
  "OPENAI_API_KEY": "pk_live_xxxxxxxxxxxxxxxx"
}

Missing directory? mkdir -p ~/.codex (or create it in Explorer on Windows).

Step 3: First launch

1. Open the Codex Desktop app
2. At the sign-in screen choose Use API Key (not "Sign in with ChatGPT")
3. If Option A or Option B already wrote auth.json, the app picks it up automatically and skips the key prompt
4. Skip the onboarding questions ("What do you want to build today?" etc.)
5. Check the Model Selector at the top — it should show gpt-5.4-mini (or whatever you set as default in config.toml)

UI walkthrough

Tokensmart tips

• Must sign in with API Key, not ChatGPT: the default flow steers you to "Sign in with ChatGPT", which eats your ChatGPT subscription quota and has nothing to do with Tokensmart. Only the API Key path reads auth.json and routes through Tokensmart.
• Use CC-Switch for multi-provider: the Desktop app has no in-UI provider switcher. To A/B between Tokensmart and the official OpenAI API, CC-Switch is basically mandatory.
• Desktop and CLI share config: any ~/.codex/ change you make from the CLI is picked up by the Desktop app on restart, and vice versa. Treat the Desktop as a GUI panel and the CLI as the scripting surface on top of the same config.
• Lean on Plan mode for big jobs: /plan makes Codex decompose a task into steps before executing. Each step is cheaper to run and easier to correct than dumping one giant prompt.
• Dedicated key + daily limit: same rule as the CLI — create a Tokensmart key named e.g. codex-desktop with a daily limit. Plan mode plus automations can fire dozens of calls in a row; a daily cap is your safety net.

Troubleshooting

• "Codex cannot be opened because it is from an unidentified developer" (macOS): right-click the installer → Open → confirm. (Gatekeeper's first-run block.) Intel Macs are unsupported — don't try to run it under Rosetta.
• "API Key invalid" after signing in: check that auth.json uses the key name OPENAI_API_KEY (all caps), not api_key. The value must start with pk_live_ and have no whitespace.
• Switched to Tokensmart but the UI still shows the official plan: the app caches sign-in state. Fully quit (not just close the window — quit via the system tray/menu), then relaunch.
• Plan-mode steps stuck at "thinking": make sure the CLI codex command is installed. The Desktop app sometimes forks into the CLI for Plan execution. Install with npm install -g @openai/codex.
• Want to go back to the ChatGPT subscription plan: sign out from the Desktop app settings; next launch pick "Sign in with ChatGPT". Keep in mind this stops routing through Tokensmart.

Next steps

• Pair with CC-Switch for one-click provider switching
• Terminal fans might prefer the Codex CLI tutorial
• Every call shows up in API Logs — group by time to see per-step cost in Plan mode