Serverless & Agents

Codex CLI

Use this page for a local command-line coding agent that supports an OpenAI-compatible base URL. The same installer also configures Codex Desktop because both read ~/.codex/config.toml.

Keep Codex sign-in and Quotaflow model access separate:

What	Use
Codex app sign-in, remote control, approvals, and device identity	ChatGPT login
Model requests from Codex CLI or Desktop	Quotaflow API key configured as a model provider

Do not run codex login --with-api-key just to install Quotaflow on a Codex Desktop host. The installer below does not edit ~/.codex/auth.json.

If you do not have a ChatGPT account

For Codex CLI or another OpenAI-compatible local agent, you can use Quotaflow directly with a qf_ key as long as the client supports a custom base URL and API key. You do not need your own OpenAI API key for model requests through Quotaflow.

For Codex Desktop, the app may still require ChatGPT sign-in for app identity, device connections, approvals, and remote control. A Quotaflow key is not a replacement for that app sign-in.

Choose your operating system

System	What to do
macOS CLI/Desktop	Use the installer below in Terminal.
Linux CLI	Use the installer below in your shell.
Windows WSL CLI	Run the installer inside WSL. This configures the WSL Codex environment.
Windows native CLI/Desktop	Do not paste the bash installer into PowerShell. Use Git Bash only if your Codex installation reads that same home directory, or use manual provider setup.

Recommended setup

For macOS, Linux, WSL, or a compatible POSIX shell, run the installer from Terminal. Copy the whole block, paste it into Terminal, and press Enter:

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

When prompted, paste your Quotaflow API key. The input is hidden. Do not paste the key into the command itself.

The installer:

Keeps ChatGPT OAuth in ~/.codex/auth.json untouched.
Adds Quotaflow as a user-level model provider.
Stores the key in ~/.codex/quotaflow-codex-api-key with private file permissions.
Runs a small /models and /responses smoke test.
Installs a restore script.

If you use the Codex App from ChatGPT mobile or another device, keep Codex signed in with ChatGPT. Do not overwrite ~/.codex/auth.json, do not delete the ChatGPT OAuth tokens, and do not replace your ChatGPT login with codex login --with-api-key.

The recommended setup is:

ChatGPT OAuth stays in Codex auth storage for app sign-in, phone access, remote control, approvals, and device connections.
Quotaflow is used only as the model provider for coding requests.
The Quotaflow key is loaded from a local private key file, not written into auth.json.

Smoke test

After installation, run a simple Codex prompt and expect connected:

codex exec "Reply with only: connected"

You can also test the API directly:

curl "https://api.quotaflow.ai/openai/v1/models" \
  -H "Authorization: Bearer $(cat ~/.codex/quotaflow-codex-api-key)"

Switch back or uninstall

To restore your previous Codex configuration:

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

If you also want to remove the saved Quotaflow key file:

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

Manual setup for advanced users

Most macOS, Linux, and WSL users should use the installer. If you manage Codex configuration manually, use the user-level ~/.codex/config.toml or the equivalent Codex user config file for your native Windows installation. Do not put provider auth settings in a project-local .codex/config.toml, because Codex ignores project-local provider and auth redirection keys.

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. Avoid putting production keys directly in command history.

For native Windows PowerShell, do not run the bash installer block. Configure the same provider values in the Codex user config location used by your Windows installation, and store the key in a Windows secret store or a private local file.

Other OpenAI-compatible clients

For non-Codex clients that only read OpenAI-style environment variables, see the general Quick Start and Base URL pages. On Codex App remote-control hosts, prefer the installer above so ChatGPT OAuth remains available for device connections.

Agent session guidance

If your client supports custom headers, set a stable x-session-id per workspace or task. If it supports prompt_cache_key, use a stable value per repository or long-running task.

Failure handling

Retry transient 429 with backoff.
Retry 503 and network timeouts.
Do not retry invalid API key errors without rotating the key.

AI agents: start at /llms.txt, fetch /llms-full.txt, and parse /openapi.yaml for exact endpoint schemas.