𝐙𝐀𝐈

Codex CLI / App (API Key Integration)

codex

Powering Codex CLI / App with ZAI Router

Current Codex custom providers use the responses wire protocol. Once ~/.codex/config.toml and XAI_API_KEY are configured, Codex App can reuse the same connection settings.

Prerequisites

  • Codex CLI installed
  • Your XAI API Key received by email
  • Linux/macOS config path: ~/.codex/config.toml
  • Windows config path: %USERPROFILE%\.codex\config.toml

Note: After signing up and logging in at m.zairouter.com, open Account Recharge to view available monthly plan options and pricing.

# ~/.codex/config.toml
model_provider = "xai"
model = "gpt-5.6-sol"
approval_policy = "never"
sandbox_mode = "danger-full-access"

[features]
api_key_model_discovery = true

[model_providers.xai]
name = "xai"
base_url = "https://api.zairouter.com"
model_catalog_url = "https://api.zairouter.com/models"
wire_api = "responses"
requires_openai_auth = false
env_key = "XAI_API_KEY"
supports_websockets = false
http_headers = { "x-codex-routing-hint" = "model=gpt-5.6-sol" }

Remote model discovery requires a CLI/App version that supports both settings. Restart after updating; see native model discovery.

export XAI_API_KEY="sk-Xvs..."
codex --yolo

Optional: Enable WebSocket

The default supports_websockets = false uses HTTP. To use Responses WebSocket instead, change only:

supports_websockets = true

With WebSocket, Codex sends only the new input within a connection. Interrupted turns are billed differently by transport. Over HTTP, Codex 0.162 and later drop the connection and resend the full history; the interrupted request returns no usage, so the router estimates it from the session's latest real usage and bills the part the session already had cached at the cached price. Over WebSocket, when you type new input mid-turn Codex waits for the upstream's real usage; when you press Esc the router asks the upstream to interrupt the response and bills the usage it reports on models that support interruption, and otherwise estimates from the session's usage as well. For long sessions that you interrupt often, enable WebSocket; if your network or proxy does not support WebSocket, keep HTTP.

x-codex-routing-hint only supplies upstream routing information; it does not select the request model. A static header is needed because Codex does not generate it automatically for a custom API-key provider. Before forwarding, the router synchronizes it with the final mapped model and the current request's service tier, so switching with --model or /model does not require a config edit.

Windows Launch Examples

:: Config file path
:: %USERPROFILE%\.codex\config.toml

set XAI_API_KEY=sk-Xvs...

codex
# Config file path
# $env:USERPROFILE\.codex\config.toml

$env:XAI_API_KEY="sk-Xvs..."

codex

Verify Commands

  • codex: start an interactive session
  • codex exec "Reply with one sentence confirming the connection works": verify a non-interactive request
← Common Scenarios