Integrating with OpenAI Codex CLI

OpenAI Codex CLI is OpenAI's official terminal coding agent. It reads ~/.codex/config.toml and supports custom model_providers, so you can point it at xmAI with a few lines of TOML and one environment variable.

Prerequisites

• Registered at XmAI Console with credits available (free tier included)
• Created an API Key on the API Keys page (format sk-xxx...)
• Installed OpenAI Codex CLI:

  npm install -g @openai/codex
  # or: brew install codex

Wire protocol caveat

Codex CLI defaults to the OpenAI Responses API (wire_api = "responses"). xmAI currently only exposes Chat Completions (/v1/chat/completions) and the Anthropic Messages API — Responses is not yet implemented. You must set wire_api = "chat" in your provider block.

If your Codex CLI version hard-requires Responses API support (wire_api = "chat" is no longer supported), you will need to wait for xmAI's Responses API milestone (tracked in a future story), or pin Codex CLI to an older version. We'll update this page when the Responses API ships.

Configuration

Step 1 — Add a provider entry in ~/.codex/config.toml

Create the file if it doesn't exist and add:

model_provider = "xmai"
model = "gpt-4o"

[model_providers.xmai]
name = "xmAI"
base_url = "https://api.xmai.sg/v1"
wire_api = "chat"
env_key = "XMAI_API_KEY"

TOML scoping

Root-level model_provider and model must appear before the [model_providers.xmai] header. Placing them after the header makes them properties of that table (model_providers.xmai.model = ...), so Codex would ignore them and keep using its built-in default OpenAI provider.

Key field explanations:

Field	Value	Purpose
base_url	https://api.xmai.sg/v1	xmAI's OpenAI-compatible endpoint (includes /v1 — Codex does not append it)
wire_api	"chat"	Use Chat Completions protocol (not Responses API)
env_key	XMAI_API_KEY	Name of the environment variable that holds the key
model_provider	"xmai"	Tells Codex to use the custom block above by default
model	"gpt-4o"	Default model at startup (any ID on xmAI works — see below)

Step 2 — Export the API key

macOS / Linux / Git Bash

export XMAI_API_KEY="sk-your-xmai-key"

Windows PowerShell

$env:XMAI_API_KEY = "sk-your-xmai-key"

Windows CMD

set XMAI_API_KEY=sk-your-xmai-key
:: Current session only. For persistence: setx XMAI_API_KEY "sk-your-xmai-key"

Persist it in your shell profile (~/.zshrc, ~/.bashrc) or — on Windows — via setx XMAI_API_KEY "..." or the System Properties → Environment Variables panel so Codex picks it up on every launch.

Step 3 — Run Codex

codex

The status line should show xmai / gpt-4o. Use /model <id> inside Codex to switch models on the fly.

Optional — Use a named profile instead of the default

If you want to keep the default OpenAI provider and toggle xmAI only on demand, wrap the two top-level fields in a profile:

[model_providers.xmai]
name = "xmAI"
base_url = "https://api.xmai.sg/v1"
wire_api = "chat"
env_key = "XMAI_API_KEY"

[profiles.xmai]
model_provider = "xmai"
model = "gpt-4o"

Then launch with:

codex --profile xmai

Model Routing

xmAI exposes one catalog across providers. Any model ID returned by /v1/models works as the model value.

Recommended default	Notes
gpt-4o	OpenAI's flagship multimodal model
gpt-4o-mini	Fast / low-cost fallback
claude-sonnet-4-6	Access Claude via Chat Completions (xmAI auto-maps tools/system blocks)
gemini-2.5-pro	Long-context Gemini Pro

Cross-vendor note

Unlike vanilla OpenAI Codex CLI, pointing at xmAI lets you use non-OpenAI model IDs (e.g. claude-sonnet-4-6) via Chat Completions. xmAI's gateway translates the request to the upstream Anthropic / Google protocol internally. Tool-use, streaming, and temperature controls all work — cross-check Error Codes for any 400s.

See Models for the authoritative list and pricing.

Verifying the connection

Send any message in Codex. Then:

1. Log into the Console → Request Logs to confirm the request landed
2. Or watch the Today's Usage card on the Dashboard for credit consumption

A new row in the log = you're connected.

Troubleshooting

404 or model not found

• Verify the model ID against /v1/models (or the Models page). Codex passes model through verbatim.
• Confirm wire_api = "chat" — if it reads "responses", xmAI returns 404 Not Found for /v1/responses (endpoint not implemented).
• Confirm base_url is exactly https://api.xmai.sg/v1 (with /v1, no trailing slash).

401 / auth failures

• Check key status / expiry on the API Keys page
• Confirm XMAI_API_KEY is exported in the Codex shell (echo $XMAI_API_KEY should print sk-...)
• Make sure env_key = "XMAI_API_KEY" exactly matches your exported variable name (case-sensitive)

402 insufficient balance

xmAI deducts per-token in real time. When your balance runs out, requests return 402 or insufficient_balance. Top up on the wallet page, or enable auto-topup.

429 rate limit

Either xmAI user-level rate limits or upstream provider 429. Implement backoff; see Error Codes for the retry-after header contract.

Connection / TLS errors

System proxy interference: If http_proxy / https_proxy are set, they may intercept xmAI traffic:

export NO_PROXY="api.xmai.sg"

Self-signed certificates: In corporate networks with custom CA chains:

export NODE_EXTRA_CA_CERTS=/path/to/your-ca-chain.pem

Switching back to OpenAI

Either comment out model_provider = "xmai" in config.toml (Codex falls back to its default OpenAI auth) or use a profile and omit --profile xmai at launch.

Related

• Chat Completions API — the underlying API Codex speaks
• Models — available models and pricing
• Error Codes — error handling guide
• OpenCode — an alternative open-source agent
• OpenAI-Compatible Tools — generic guide for other OpenAI-compatible CLIs / SDKs