APIClaw

Codex CLI

Connect OpenAI Codex CLI to APIClaw using an OpenAI-compatible provider block.

Codex CLI calls the Responses API (/v1/responses) by default. Create an API key first, then add a custom provider to ~/.codex/config.toml.

Install Codex CLI

macOS and Linux (the installer OpenAI documents first):

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

Homebrew, or npm if you already have Node.js:

bash
brew install --cask codex
npm install -g @openai/codex

On Windows, Codex runs under WSL2. Install and configure it inside your WSL distribution, not in PowerShell.

1. Put your key in an environment variable

Codex reads the key from an environment variable at runtime. env_key in the config below is the name of that variable, never the key itself.

macOS / Linux (add it to ~/.zshrc or ~/.bashrc so it survives a new terminal):

bash
export APICLAW_API_KEY="sk-your-apiclaw-key"

Windows: do this inside WSL2, in the same ~/.bashrc, since that is where Codex runs.

Open a new terminal afterwards and check it with echo $APICLAW_API_KEY before starting Codex.

2. Configure the provider

Add this to ~/.codex/config.toml. It has to be the user-level file: Codex ignores model_provider and model_providers in a project-local .codex/config.toml.

toml
model_provider = "apiclaw"
model = "YOUR_MODEL_ID"
model_reasoning_effort = "high"

[model_providers.apiclaw]
name = "APIClaw"
base_url = "https://apiclaw.biz/v1"
env_key = "APICLAW_API_KEY"
wire_api = "responses"
SettingValue
base_urlhttps://apiclaw.biz/v1
modelFull model ID from the model hub
env_keyName of the variable holding your key, not the key
wire_apiresponses, the only protocol current Codex speaks
model_reasoning_effortminimal, low, medium, high, or xhigh

Provider ids openai, ollama, and lmstudio are reserved, so keep apiclaw (or any other unused id).

3. Verify

bash
cd /path/to/your/project
codex

If Codex opens and answers, the configuration is working. Confirm the request in logs.

Troubleshooting

Missing environment variable: sk-...

The key was pasted into env_key. That field takes the name of an environment variable, so Codex went looking for a variable called sk-.... Set env_key = "APICLAW_API_KEY" and export the key as shown in step 1.

401 Unauthorized

Confirm APICLAW_API_KEY is set in the terminal you launched Codex from, that the name matches env_key, and that the key is active in the API Keys dashboard.

404 Not Found

Confirm base_url ends in /v1 and the model ID exists in your model hub.

stream disconnected before completion or a Reconnecting 1/5 counter

Codex retries a stream up to five times when it ends without a completion event. Upgrade to the current APIClaw gateway (this is fixed as of September 2026) and, if you need a longer leash on a slow reasoning model, raise stream_idle_timeout_ms in the provider block.

wire_api = chat is no longer supported

Current Codex speaks only the Responses API, which APIClaw serves at https://apiclaw.biz/v1/responses. Set wire_api = "responses", or drop the line entirely since it is now the default. Codex validates every provider block at startup, so an old wire_api = "chat" block you no longer use still breaks every command until you remove it.