Codex CLI
Codex CLI
Codex CLI speaks the OpenAI Responses API, which Hisoka serves at /api/v1/responses.
The chat endpoint is a different wire: pointing Codex at it produces confusing parse
errors rather than a clean refusal.
Configure
Codex reads a config file at ~/.codex/config.toml:
model = "glm-5.3-flash"
model_provider = "hisoka"
[model_providers.hisoka]
name = "Hisoka"
base_url = "https://hisoka.ai/api/v1"
env_key = "HISOKA_API_KEY"
Then export the key:
export HISOKA_API_KEY="sk-your-key-here"
Verify
codex "list the files in this directory"
A successful turn writes a usage row you can read back:
curl -s "https://hisoka.ai/api/v1/transactions?limit=1" \
-H "Authorization: Bearer $HISOKA_API_KEY" | jq '.data[0] | {model, amount_micro_usd}'
Reasoning models in Codex
A model with capabilities.reasoning true may spend its whole completion budget thinking
and return empty content. That is a finished turn, not a failure. The gateway keeps
content empty, records meta.reasoning_only, and only retries when
finish_reason is length.
Treating a thinking-only turn as an empty body is what makes an agent report “the model
did not answer in time” while every upstream attempt was a healthy 200. If you are
debugging something like that, check finish_reason before the provider.
Common problems
| Symptom | Cause |
|---|---|
| Parse error on the first turn | pointed at /chat/completions instead of /responses |
401 invalid_api_key |
env_key names a variable that is not exported |
| Turn ends with no text | reasoning-only turn, or finish_reason: length |
| Requests 404 under a subpath | base_url already includes more than /api/v1 |