xKiroxKiro docs

Coding tools

Codex CLI

Codex speaks the Responses API and nothing else. xKiro serves it, so Codex works — but three details in the config fail silently if you get them wrong, and each one looks like a different problem.

Wire format

OpenAI Responses format

Base URL

https://api.xkiro.com/v1

Configured by

~/.codex/config.toml

Model IDs always carry the vendor prefix

Use openai/gpt-5.6-sol, never a bare gpt-5.6-sol. Full list at GET /v1/models.

Configure the provider#

Codex reads its endpoint from a TOML file. The key itself stays in your environment, named by env_key.

# ~/.codex/config.toml
# ⚠️ Bốn dòng này phải nằm TRÊN CÙNG, trước mọi [bảng] khác.
model = "openai/gpt-5.6-sol"
model_provider = "xkiro"
model_context_window = 1000000

[model_providers.xkiro]
name = "xKiro"
base_url = "https://api.xkiro.com/v1"
env_key = "XKIRO_API_KEY"
wire_api = "responses"
Then set the key and run
export XKIRO_API_KEY="sk-xt-..."

codex

Three traps that fail silently#

Every one of these leaves a valid file and a running Codex. Nothing errors; it simply does not go through xKiro. They are worth reading before you start debugging anything else.

1. Top-level keys must be at the top of the file

model, model_provider and model_context_window are top-level keys. In TOML, once a [table] header appears, every key after it belongs to that table until the next header. Paste them at the bottom of an existing config and they silently become settings of whatever table happens to be last — Codex never sees them and quietly keeps using its own defaults.

2. env_key is the NAME of an environment variable

It is not the key itself. Put your key there and Codex will look for an environment variable literally named sk-xt-…, then report Missing environment variable: sk-xt-… — which reads like the key is wrong when the key is fine.

3. A new environment variable does not reach an open terminal

Windows loads environment variables when a process starts. Setting one and then running codex in that same window will not work, because the window predates the variable. Open a new terminal, or pull it in explicitly:

PowerShell — persist it, then load it into the current session
[Environment]::SetEnvironmentVariable('XKIRO_API_KEY','sk-xt-...','User')

# only needed in windows opened before the line above
$env:XKIRO_API_KEY = [Environment]::GetEnvironmentVariable('XKIRO_API_KEY','User')

Close Codex before editing the config

Codex rewrites config.toml while it is running, so edits made with a session open can be overwritten from its in-memory copy. Quit Codex first, edit, then start it again.

Why wire_api must be "responses"#

Codex used to support wire_api = "chat" for third-party gateways. OpenAI removed it: deprecated in December 2025, a hard startup error since February 2026. responses is now the only accepted value, and the default when the key is omitted.

If you are following an older guide and Codex refuses to start, that error is Codex rejecting wire_api = "chat" — not a problem with your key or your network.

Set model_context_window#

Codex ships built-in specifications for OpenAI's own models only. Give it any other model ID and it warns Model metadata not found. Defaulting to fallback metadata and guesses the context window. Guess low and it compacts your conversation earlier than it needs to; guess high and it sends more than the model accepts.

  • Take the real number from GET /v1/catalog — /v1/models does not carry context sizes — and set model_context_window.
  • It is a global setting, not per-model — change models and you need to change this too.

Codex never asks us for model metadata

It only fetches a model list when signed in to a ChatGPT account, which does not apply to an API-key provider. That is why the warning cannot be fixed from our side, and why model_context_window is the answer.

If it does not work#

Send one request by hand before touching Codex's settings again. A reply proves the URL and key are both fine, which means whatever is left is in the tool's own configuration — and that is a much smaller place to look.

curl https://api.xkiro.com/v1/chat/completions \
  -H "Authorization: Bearer $XKIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-5.6-sol","messages":[{"role":"user","content":"ping"}],"max_tokens":8}'

An error naming an unknown model still counts as a success here: the request was authenticated before the model was rejected. Common failures and what each one means are on the overview page.

Was this page helpful?