Codex CLI Setup

Codex is OpenAI's open-source local coding agent that runs in your terminal. This guide shows how to point it at the Claudexia API.

What is Codex?

Codex CLI supports custom model providers via a config.toml file. By configuring Claudexia as a provider, you can route Codex requests through Claudexia's unified API and use both GPT and Claude models from the same agent.

Quick start

Step 1: Install Codex CLI

Install Codex globally via npm:

bash

npm install -g @openai/codex

Step 2: Get your Claudexia API key

Sign up or log in at the Claudexia dashboard.
Open Dashboard > API Keys and create a new key.
Copy the key — you'll use it as the CODEX_KEY environment variable.

Step 3: Configure Codex for Claudexia

Codex reads its config from ~/.codex/config.toml. Create or edit this file with the following configuration:

toml (~/.codex/config.toml)

model_provider = "claudexia"
model_reasoning_effort = "medium"
model = "gpt-5.5"

[model_providers.claudexia]
name = "claudexia"
base_url = "https://api.claudexia.tech/v1"
env_key = "CODEX_KEY"

Step 4: Set your API key

Export the key in your shell profile so Codex can read it:

bash

# Add to ~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish
export CODEX_KEY="YOUR-KEY"

Step 5: Start Codex

Navigate to your project directory and launch Codex in terminal mode:

bash

cd /path/to/your/project
codex

Or launch the desktop app version:

bash

codex app

Configuration reference

Core settings inside ~/.codex/config.toml:

Setting	Description	Example
`model_provider`	Provider name to use for model requests.	`"claudexia"`
`model`	Model ID to send to Claudexia.	`"gpt-5.5"`
`model_reasoning_effort`	Reasoning effort level for Codex models.	`"low"`, `"medium"`, `"high"`
`base_url`	Claudexia API endpoint. Use the OpenAI-compatible /v1 base URL.	`https://api.claudexia.tech/v1`
`env_key`	Name of the environment variable Codex reads the API key from.	`CODEX_KEY`

Important: For Codex the base URL must include /v1 — Codex uses the OpenAI-compatible endpoint.

Windows (PowerShell)

powershell

npm install -g @openai/codex
$env:CODEX_KEY = "YOUR-KEY"
codex

Create the config file in your user profile:

powershell

New-Item -ItemType Directory -Force "$HOME\.codex" | Out-Null
notepad "$HOME\.codex\config.toml"

Troubleshooting

Authentication errors

Make sure CODEX_KEY is exported in the same shell where you run codex. Run echo $CODEX_KEY to verify. The key must be valid and active in Dashboard > API Keys.

Model not found

Verify the model ID against the Models page. Codex passes the value in model directly to Claudexia, so it must match an exposed ID exactly (e.g. gpt-5.5, not gpt5.5).

404 / unexpected response

Codex requires the OpenAI-compatible endpoint — base_url must end with /v1. Double-check that you didn't accidentally drop it from config.toml.

OpenCode

API Key Configuration