Codex CLI

This guide connects Codex to APIPool on macOS, Linux, native Windows, or Windows WSL2. The provider settings in step 3 live in the user-level ~/.codex/config.toml, which the Codex CLI, the IDE extension, and the desktop app all read; the install and verification commands below are CLI-specific.

Custom Codex model providers use the Responses API. This guide covers the GPT family currently available through APIPool. Pick a GPT text model from the model list that supports Responses and is available to your API key's group. Guides for other model families will be added when those models are officially available.

Import into CC Switch

If Codex is installed, use the form below to import your real API key, APIPool endpoint, and model. Sign in, choose an existing key, then click “Import into CC Switch”, or paste your full key directly. Choose a Responses model available to the selected key’s group.

The same button works on all three systems. Install and launch CC Switch first:

Check that the endpoint is https://app.apipool.dev/v1 in CC Switch, confirm the import, and enable the provider. CC Switch manages local Codex configuration and credentials, so back up existing settings first. After import and activation, skip to “Start and verify”; do not overwrite the generated settings with the manual example. CC Switch chooses the provider ID, so the output may show custom instead of the manual example’s apipool.

If no dialog appears, check the browser’s external-app prompt and the CC Switch protocol troubleshooting guide. A browser cannot reliably confirm installation or import success. Check the provider entry in CC Switch.

WSL2: Windows CC Switch normally manages the Windows user directory. Codex inside WSL uses a separate Linux home and does not automatically receive this configuration. Follow the Linux instructions below or explicitly verify the target directory managed by CC Switch. SSH hosts also need remote configuration.

If earlier tasks disappear after switching, read Missing conversation history. A normal import does not merge histories created under different provider IDs.

1. Install Codex CLI

These commands come from the official Codex CLI installation guide. Skip this section if codex --version already works.

macOS

brew install --cask codex

Or use the standalone installer:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Linux

curl -fsSL https://chatgpt.com/codex/install.sh | sh

If Node.js is installed, npm also works on macOS, Linux, and Windows:

npm install -g @openai/codex

Native Windows

Run in PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Codex recommends Windows 11. Prefer the elevated native sandbox, and fall back to unelevated only when device policy blocks the administrator-approved setup:

[windows]
sandbox = "elevated" # Change to "unelevated" only as a fallback.

Windows WSL2

Install and enter WSL from an administrator PowerShell:

wsl --install
wsl

Then install Codex from the WSL shell as you would on Linux:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Keep repositories in a Linux path such as ~/code rather than /mnt/c, to avoid filesystem performance, symlink, and permission problems.

Verify the installation:

codex --version

2. Prepare an API key

1. Add credit on the balance page.
2. Create a key on the API key page, choosing a group that contains the target model.
3. Save the complete key while it is shown. Do not put a real key in config.toml, project files, screenshots, or support messages.

macOS, Linux, and WSL2

Set the key in the shell that will start Codex:

export APIPOOL_API_KEY="YOUR_APIPOOL_API_KEY"

Windows PowerShell

Set the key in the same PowerShell session that will start Codex:

$env:APIPOOL_API_KEY = "YOUR_APIPOOL_API_KEY"

These commands affect only the current terminal session. For persistent use, rely on an operating-system secret manager or another protected environment mechanism, and do not commit shell or PowerShell files containing a real key.

3. Configure Codex

Merge the following settings into the user-level configuration file, leaving unrelated settings in place. Do not put provider or authentication settings in a project-level .codex/config.toml — Codex ignores them there.

GPT configuration:

model_provider = "apipool"
model = "gpt-5.6-sol"
review_model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
model_supports_reasoning_summaries = true
disable_response_storage = true
network_access = "enabled"
web_search = "cached"
windows_wsl_setup_acknowledged = true

[model_providers.apipool]
name = "APIPool"
base_url = "https://app.apipool.dev/v1"
wire_api = "responses"
env_key = "APIPOOL_API_KEY"
requires_openai_auth = false

[features]
goals = true

This base_url is a Codex custom-provider client setting, not the platform-wide Base URL. The platform Base URL remains https://app.apipool.dev; Codex appends /responses to the provider base_url, so this setting must retain /v1 to produce the final request URL https://app.apipool.dev/v1/responses. Do not copy Base URL values between tools: Claude Code appends /v1/messages itself and therefore uses the bare domain described in the Claude Code guide.

Keys you must not get wrong:

• Keep the trailing /v1 in this Codex-specific base_url; do not replace it with the platform's bare domain or append /responses yourself.
• env_key together with requires_openai_auth = false makes Codex authenticate with the APIPool key from your environment. An explicit env_key can also work with requires_openai_auth = true, but that flag affects login status and some features; it is not a subscription/API routing switch.
• Discount-group GPT models accept Codex web search declarations without an additional web search charge. web_search = "cached" makes that behavior explicit and is also Codex's current default, so existing users who omitted this setting do not need to change their configuration.

Migrating from the legacy site

The legacy site's Compatibility mode stores OPENAI_API_KEY in auth.json and sets requires_openai_auth = true. Existing configurations can keep using that path temporarily, but it reuses Codex's global OpenAI credential store and may share or conflict with an existing ChatGPT/OpenAI login. New configurations should use the env_key setup above; do not overwrite an existing auth.json just to connect APIPool.

When migrating, the new-site base_url must still be https://app.apipool.dev/v1. The legacy site's API Key Mode is not a supported new-site setup: x-openai-actor-authorization is only a static extra header. It does not supply an API key and cannot replace Authorization: Bearer ....

The remaining keys are preferences you can adjust: model_reasoning_effort sets the reasoning depth, review_model picks the model used by /review, network_access controls sandbox network access, and [features] goals enables the goals feature. For a custom provider, keeping disable_response_storage = true is recommended so Codex does not rely on server-side response storage.

4. Choose a GPT model

The default gpt-5.6-sol is the most capable GPT-5.6 tier. To switch models, change the top-level model (and review_model) value, then restart Codex. Use only a GPT text model that appears in the model list, is available to the API key's group, and supports Responses. A model name alone does not grant access to another group.

5. Start and verify

Start an interactive session in your project:

codex

On macOS, Linux, and WSL2, run this read-only tool-call check:

codex --ask-for-approval never --sandbox read-only exec \
  --skip-git-repo-check \
  "Run pwd with the shell tool, then report the path."

Use the same command in Windows PowerShell, with a backtick for line continuation:

codex --ask-for-approval never --sandbox read-only exec `
  --skip-git-repo-check `
  "Run Get-Location with the shell tool, then report the path."

A successful run prints provider: apipool and the selected model, then returns the model response or tool result. Global options such as --ask-for-approval and --sandbox must appear before exec.

Troubleshooting

For the current custom-provider field definitions, see the Codex configuration reference.