Codex Desktop

Use this page to connect Codex Desktop to Quotaflow while keeping your normal ChatGPT sign-in for the app.

What this setup does

• Keeps Codex Desktop signed in with ChatGPT for device connections, remote control, approvals, and app identity.
• Adds Quotaflow as the model provider for coding requests.
• Stores your Quotaflow API key in a local file with private file permissions.
• Does not overwrite ~/.codex/auth.json.
• Creates a one-command restore script so you can switch back quickly.

Login versus model provider

Codex has two separate pieces of configuration:

Do not run codex login --with-api-key just to install Quotaflow. Keep ChatGPT sign-in, and add Quotaflow only as the model provider.

If you do not have a ChatGPT account

A Quotaflow key can power model requests, but it is not a Codex Desktop login. If Codex Desktop asks you to sign in, use a ChatGPT account for the app sign-in first, then install Quotaflow as the model provider.

If you do not have or do not want a ChatGPT account, use Codex CLI or another OpenAI-compatible local agent that supports a custom base URL and API key. Those clients can call Quotaflow directly with your qf_ key.

Choose your operating system

Before you start

1. Install and open Codex Desktop or Codex CLI.
2. Keep Codex Desktop signed in with ChatGPT if you use ChatGPT mobile, remote control, or app approvals.
3. Have your Quotaflow API key ready. It starts with qf_.
4. Open the right terminal for your system:

- macOS: Applications → Utilities → Terminal.

- Linux: your normal terminal.

- Windows WSL: your WSL Ubuntu terminal.

- Windows native PowerShell: do not use the bash installer block directly; use manual setup or ask Quotaflow support for a Windows-native installer.

Step 1: run the installer

For macOS, Linux, WSL, or a compatible POSIX shell, copy the whole block below, paste it into Terminal, and press Enter. You do not need to type the commands one by one:

curl -fsSL https://docs.quotaflow.ai/install/codex-desktop.sh -o /tmp/quotaflow-codex-desktop.sh
chmod +x /tmp/quotaflow-codex-desktop.sh
/tmp/quotaflow-codex-desktop.sh

The installer will ask for your Quotaflow key. Paste the key when prompted. The key input is hidden, so Terminal may look blank while you paste or type it.

Do not paste your key into screenshots, issue trackers, shared recordings, or the command itself.

Step 2: restart Codex Desktop

Quit and reopen Codex Desktop so it reloads ~/.codex/config.toml.

Step 3: test Codex Desktop

In Codex Desktop, start a new session and send:

Reply with only: connected

A successful setup should return:

connected

Switch back or uninstall

If you need to restore the previous Codex configuration, run:

bash ~/.codex/bin/quotaflow-codex-desktop-restore.sh

Then quit and reopen Codex Desktop.

The restore command puts your original ~/.codex/config.toml back. It does not delete your ChatGPT login. If you also want to remove the saved Quotaflow key file, run:

rm ~/.codex/quotaflow-codex-api-key

What the installer writes

The installer writes these local files:

Configuration values

Manual setup for advanced users

Most macOS, Linux, and WSL users should use the installer above. If you manage Codex configuration manually, preserve ChatGPT OAuth and do not edit ~/.codex/auth.json.

Add a user-level provider in ~/.codex/config.toml on macOS/Linux/WSL, or the equivalent Codex user config file for your native Windows installation:

model = "gpt-5.5"
model_provider = "quotaflow-codex"

[model_providers.quotaflow-codex]
name = "Quotaflow"
base_url = "https://api.quotaflow.ai/openai/v1"
env_key = "QUOTAFLOW_API_KEY"
wire_api = "responses"

Then provide QUOTAFLOW_API_KEY through your shell profile or secret manager. The installer is safer for most users because it avoids putting the key directly in a command that could be saved to shell history.

For native Windows setups, do not paste the macOS/Linux bash installer into PowerShell. Configure the same provider values in the Codex user config location used by your Windows Codex installation, and keep the key in a Windows secret store or a private local file.

Other desktop or IDE agents

For other desktop agents, IDE extensions, or local GUI coding tools that support OpenAI-compatible endpoints:

1. Open the agent settings.
2. Choose OpenAI-compatible API settings if available.
3. Paste your Quotaflow API key.
4. Set the base URL to https://api.quotaflow.ai/openai/v1.
5. Save and run the same connected test prompt.

Image generation in Codex Desktop

For Codex Desktop image prompts such as 生图：..., use the Quotaflow GPT Image 2 skill setup in the GPT Image 2 reference. This installs a local Codex skill that calls https://api.quotaflow.ai/openai/v1/responses with the Responses image_generation tool and displays the returned PNG in Codex Desktop.

Codex Desktop's built-in image generation may use its own first-party path. If you need image generation to bill through your Quotaflow key, tell the agent to use the local quotaflow-imagegen skill instead of the built-in image generator.

Troubleshooting

• If Codex Desktop still uses the old provider, quit and reopen the app.
• If the installer says the key failed the smoke test, confirm the key is active and starts with qf_. The installer tests the key before changing Codex config, so a failed smoke test leaves your existing Codex config in place.
• If the Quotaflow API is temporarily unreachable and you still want to write the local config, rerun the downloaded installer with --no-smoke, then restart Codex Desktop and test manually.
• If you need to undo the setup, run the restore command above.
• If you use a managed workstation, ask your administrator before changing local agent settings.