An API for everyoneUser guide
Website ↗
User guideTool setup

Codex

Connect an installed local Codex client to your API. First distinguish a local client from a cloud task.

Have these three details ready

With your app already installed, open Self-service on this website and sign in. Create or view your own API key, copy the API address shown there, and copy an exact model ID from Models and pricing. A website homepage, account password or marketing name is not a substitute. Check both account balance and key allowance.

API_HOST, YOUR_API_KEY and YOUR_MODEL_ID below are placeholders: replace each before use. Follow this article on whether to keep /v1; do not append /chat/completions or /responses. Examples do not connect automatically or contain your key.

1. Identify your Codex client

These file settings target Codex CLI and clients that read local configuration, not browser cloud tasks. For a mouse-driven setup, use the Codex branch of the CC Switch guide.

2. Open the configuration file

Open ~/.codex/config.toml on macOS/Linux, or %USERPROFILE%\.codex\config.toml on Windows. Start Codex once if the file is missing. Merge the example below. MY_API_KEY is a variable name, not the key itself.

Field diagram · not an app screenshot
Base URL
https://API_HOST/v1
wire_api
responses
model
YOUR_MODEL_ID
env_key
MY_API_KEY
Configuration example

Keep a copy of your current file first. Update matching entries rather than adding duplicates, and preserve unrelated settings. Do not share a configuration or screenshot containing a real key.

model_provider = "my_api"
model = "YOUR_MODEL_ID"

[model_providers.my_api]
name = "My API"
base_url = "https://API_HOST/v1"
wire_api = "responses"
env_key = "MY_API_KEY"
requires_openai_auth = false

3. Set the key and start

Set MY_API_KEY as shown below, enter the test folder in that same terminal, then run codex. You do not need to replace your existing auth.json. A desktop app launched from its icon may not inherit terminal variables; use CC Switch for that client instead.

When the configuration uses MY_API_KEY, set it in the same terminal from which you start the app. Enter your real key only on your computer. This example shows the syntax; the variable lasts for that terminal session.

macOS / Linux terminal
export MY_API_KEY="YOUR_API_KEY"
codex
Windows PowerShell
$env:MY_API_KEY = "YOUR_API_KEY"
codex

4. Select the model and effort

Use /model to confirm the model. Start with the default or Medium when available. Alternatively put model_reasoning_effort = "medium" at the top level of config.toml, before any [table]. Use only levels accepted by the chosen model.

5. Confirm the API format

Use OpenAI Responses with wire_api = "responses" and retain /v1 in Base URL. Do not copy the Harness Chat Completions choice here. The model also needs compatible streaming and tools; a successful chat alone is insufficient.

Check 1: receive a reply

Create an empty test folder, choose it as the workspace and start a new chat. Confirm the new provider and model are selected, then send the prompt below. A normal reply without an error confirms basic connectivity, not every agent feature. Tests incur normal API usage.

Reply only: Connection successful.

Expected: the app displays “Connection successful.” If you see a login page, an error or endless loading, use the checks below before sending again.

Check 2: read a real file

In that test folder, use a text editor to create hello.txt containing “API connection test 27”. Save it, then send the prompt below. If permission is requested, allow reading only this test folder.

Use the file-reading tool to open hello.txt in the current workspace and tell me its contents. Do not change any files.

Expected: a visible tool execution reading hello.txt, followed by an answer containing API connection test 27. A text answer alone is not evidence of a tool call. You may remove the test folder afterwards.

Troubleshoot by symptom

401 / Invalid API key

Check that the address and complete key belong to the same service and that the key is active. Never send support a full key.

404 / model not found

Check /v1, the exact model ID and the API format. A listed model is not a guarantee of support for every format.

429 / quota / balance

Check balance, key allowance and request rate; follow the returned error. More thinking effort cannot fix a quota problem.

Chat works but files cannot be read

Check model tool support, workspace permissions and the tool execution error.

No effort selector

Check capability declarations, the model and client version. Thinking support does not necessarily include adjustable effort.

Official references and scope

Configuration checked on 2026-11-08. Menus may change with updates; use these official references to verify details. Use the current connection information provided by this platform.