Codex Desktop Client Configuration Guide

This guide is for users who have Codex Desktop (the GUI client) installed and want to connect it to the OpenAI-compatible gateway at https://claude-code.club/openai/v1. If you are only using the Codex CLI, refer to Installation and Configuration first.

1. Prerequisites

Codex Desktop is installed (if not, refer to Section 1 of Installation and Configuration, or visit the Codex official documentation)
You have a valid API key (refer to Get API Key)
Do not use keys that have been exposed in chats, screenshots, or repositories — compromised keys should be invalidated and regenerated immediately

2. Relationship Between Desktop and CLI Configuration

Codex Desktop and the Codex CLI share the same set of configuration files:

File	Path	Purpose
`config.toml`	`~/.codex/config.toml`	Model and gateway definitions
`auth.json`	`~/.codex/auth.json`	Authentication credentials

Desktop and CLI share configuration, but they differ in restart behavior and environment variable scope: Desktop is a GUI process that must be fully quit and relaunched; on macOS, GUI apps cannot read export statements from ~/.zshrc — you must use launchctl setenv instead. These two points are the focus of this page.

3. Minimum Working Configuration

If you have not previously configured ~/.codex/, complete the steps below in one pass. If you already have a configuration, keep your existing blocks and just ensure the following key-value pairs are present and correct.

3.1 Create / Open the Configuration Directory

mkdir -p ~/.codex
open ~/.codex

3.2 Back Up Existing Files (if they exist)

cp ~/.codex/config.toml ~/.codex/config.toml.bak 2>/dev/null
cp ~/.codex/auth.json   ~/.codex/auth.json.bak   2>/dev/null

3.3 Edit `config.toml`

nano ~/.codex/config.toml

Write or merge the following content:

model_provider = "club"
model = "gpt-5.5"
model_reasoning_effort = "high"
preferred_auth_method = "apikey"
disable_response_storage = true
 
[model_providers.club]
name = "Claude Code Club OpenAI Gateway"
base_url = "https://claude-code.club/openai/v1"
wire_api = "responses"
requires_openai_auth = true
env_key = "OPENAI_API_KEY"

For detailed explanations of fields like wire_api and requires_openai_auth, refer to Section 2 of Installation and Configuration.

3.4 Edit `auth.json`

nano ~/.codex/auth.json

Write the following structure, replacing the placeholder with your actual API key:

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "your-api-key-here"
}

⚠️

auth.json stores your real API key in plain text. Do not screenshot this file, upload it to GitHub, or share it with others. If the key has already been exposed, invalidate it and regenerate immediately.

4. Restart Codex Desktop

After editing the configuration, simply closing the window will not apply the changes — you must fully quit the Codex Desktop process and relaunch it.

Click Codex → Quit Codex in the menu bar, or press Cmd + Q
Open Activity Monitor, search for Codex, and confirm all related processes (including Codex Helper) have exited
Relaunch Codex Desktop
Open any project and send a simple request to verify the configuration is working

⚠️

If you only clicked the window’s close button, the process is often still running in the background and changes to the configuration files will not be picked up. Make sure the process has fully exited.

5. macOS: launchctl Environment Variables (Optional)

If certain OpenAI-compatible SDKs or Codex Desktop extensions need to read the key from an environment variable, and you only want it to apply to GUI processes, you can use launchctl setenv.

If you have already completed the configuration via config.toml + auth.json and can chat normally, this section can be skipped.

launchctl setenv OPENAI_BASE_URL "https://claude-code.club/openai/v1"
launchctl setenv OPENAI_API_KEY  "your-api-key-here"

⚠️

GUI apps (including Codex Desktop) do not read export statements from ~/.zshrc / ~/.bashrc. This is due to the environment isolation between macOS terminal shells and the Aqua GUI layer — which is why launchctl setenv is required. Note that launchctl setenv settings are reset on system restart; to persist them across reboots, use a LaunchAgent.

If you are only using the Codex CLI in the terminal, refer to Section 3 of Installation and Configuration.

6. Connectivity Test (Optional Diagnostic)

If you want to confirm that the gateway and key are working before launching Desktop, you can call the OpenAI Responses-style API directly with curl.

curl -sS "https://claude-code.club/openai/v1/responses" \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","input":"Hello, reply with: test successful"}'

If the returned JSON contains a model response, the gateway and key are working correctly. If Desktop still cannot connect after this, the problem is most likely in the config.toml fields or the process not being fully restarted.

7. Troubleshooting

Symptom	Resolution
`Invalid API key`	The key in `auth.json` or the environment variable is incorrect, expired, or disabled — regenerate and replace it
`stream disconnected before completion: stream closed before response.completed`	`base_url` is missing the trailing `/v1`. Starting with Codex CLI v0.130, the URL is constructed as `{base_url}/responses`. Without `/v1`, the request goes to `/openai/responses` and the gateway returns an empty SSE stream that closes immediately. Change to `https://claude-code.club/openai/v1`
Still connecting to old gateway	Check that `base_url` in `config.toml` is not still the old `https://cc.ai-code.club` — change it to `https://claude-code.club/openai/v1`
Model not available	The `model` value is not supported by the current gateway — switch to a supported model, e.g. `gpt-5.5`
`JSON` format error	`auth.json` must be valid JSON — no trailing commas after the last entry
`TOML` format error	Strings in `config.toml` must use ASCII double quotes; check the spelling of `[model_providers.club]`
Changes not taking effect	Fully quit Codex Desktop (see Section 4); restart the system if necessary

8. Restore Default Configuration

If your configuration becomes broken, you can restore from the backup files:

cp ~/.codex/config.toml.bak ~/.codex/config.toml
cp ~/.codex/auth.json.bak   ~/.codex/auth.json

After restoring, you still need to fully restart Codex Desktop as described in Section 4.

9. Security Best Practices

⚠️

The OPENAI_API_KEY in auth.json is equivalent to a password — do not write it in public documentation, screenshots, or Git repositories
config.toml / auth.json / other exported files may contain plain-text keys — store them only on trusted devices for short periods
When sharing configurations with a team, share only the steps and placeholders, not the actual keys
If a key has ever appeared in a chat, screenshot, log, or public repository, invalidate it and regenerate it immediately

10. References

OpenAI Codex Installation and Configuration — Complete installation guide from the Codex CLI perspective
Get API Key — How to apply for a claude-code.club API key
Configure Base URL and Auth Token — Three methods: environment variables / config files / project-level configuration
Codex Official Repository

CC Switch Bootstrap Error