Codex Manual

Use XAI Router

XAI Router is useful when you want centralized API, account, quota, and model governance for Codex.

~/.codex/config.toml:

model_provider = "xai"
model = "gpt-5.6-sol"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[features]
api_key_model_discovery = true

[model_providers.xai]
name = "xai"
base_url = "https://api.xairouter.com"
model_catalog_url = "https://api.xairouter.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" }

Start:

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

PowerShell:

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

Native model discovery

Use a Codex CLI or Codex App version that supports remote model discovery. Follow the example above to configure both api_key_model_discovery = true and model_catalog_url. Remove any existing static model_catalog_json setting when using the remote catalog.

After setting XAI_API_KEY, restart the client. Run /model in the CLI or open the model picker in the App to select an available model and a supported reasoning level.

Native protocol, workspaces, and files

With the remote model catalog enabled, the client chooses Responses Lite from the upstream account’s model capabilities. HTTP and WebSocket preserve that choice. Available models come from the account’s catalog.

For Codex → Router → codex-cloud, set the upstream key’s provider_type to codex. When using the official ChatGPT backend, codex-cloud discovers the account’s workspace route and sends Responses, Compact, and Responses WebSocket requests to that backend. Clients keep using the Router address configured above.

Clients and integrations that support the native file protocol can upload attachments as follows:

Send JSON to the Router’s POST /files (also /v1/files) with file_name, file_size in bytes (up to 512 MiB), and use_case: "codex". Set codex_model to the model that will use the file, and keep the same session identity across uploads.
PUT the file bytes directly to the returned upload_url with x-ms-blob-type: BlockBlob. Use the API key only for Router requests; the signed upload URL already contains upload credentials.
Use the complete returned file_id in POST /files/{file_id}/uploaded with {}. If registration returned pdf_c2pa_reservation: true, send {"pdf_c2pa_create_request": ORIGINAL_REGISTRATION_REQUEST}. Repeat confirmation on status: "retry" until status: "success".
Use that complete ID in the file_id field of subsequent Responses or image-editing requests. URI fields use sediment://{file_id}. The Router keeps the upload account bound across HTTP, WebSocket, and WebSocket steering input.

Upload files used together within the same session and model route, using the same user’s API key. Keep the file ID returned by the Router. Upload again after changing the upstream account or provider configuration. Attachment availability also depends on the client’s features and authentication mode; use the attachment entry points supported by your client in API-key mode.

HTTP, WebSocket, and the routing hint

Current Codex custom providers use wire_api = "responses". The configuration above explicitly uses HTTP. To enable Responses WebSocket, change only:

supports_websockets = true

x-codex-routing-hint is an upstream routing hint; it does not replace the request body's model. Codex does not generate this header automatically for a custom provider authenticated with an XAI Router API key, so the configuration supplies a static seed. Before forwarding, the router synchronizes an existing hint with the final mapped model and the current request's service tier. You do not need to edit the seed when switching with codex --model ... or /model.

Continue with the GPT Image 2.5 Images API guide or see Codex CLI / App API key integration.

Previous Config and Login Next GPT Image 2.5 Images API