⌘K
Guides

Codex CLI and AI Hub

Connect Codex CLI to AI Hub as a custom provider over the Responses API.

1. Prepare your workspace

Create a dedicated workspace inference key in this AI Hub environment and set a spend cap. A coding agent resends its instructions and tool list on every turn, so a small task can use tens of thousands of input tokens. Choose an exact author/slug ID with tools support from Models or the catalogue:

bash
curl --fail "https://tokenhub-api.belive.sg/api/v1/models"

2. Configure Codex

Make the key available as TOKENHUB_API_KEY through your secret manager or shell environment; keep it out of the TOML file. Add the provider to your user configuration, ~/.codex/config.toml (a project-level file cannot define providers). Top-level keys go before any [table]:

toml
model = "qwen/qwen3.8-max"
model_provider = "tokenhub"
web_search = "disabled"

[model_providers.tokenhub]
name = "AI Hub"
base_url = "https://tokenhub-api.belive.sg/api/v1"
wire_api = "responses"
env_key = "TOKENHUB_API_KEY"

Codex appends /responses to base_url. Keep web_search = "disabled": Codex's hosted web search tool is ignored. Codex may warn that it has no metadata for a model ID it does not know; it then uses its defaults, which worked in the runs below.

3. Run

bash
codex -m qwen/qwen3.8-max
codex exec -m z-ai/glm-5.3 "Run the tests and fix the first failure"

Check Activity for the model, usage and cost of each turn.

What AI Hub supports

  • Stateless Responses: send the full input each time. Codex already does this (store: false). store: true, previous_response_id and background are refused with 400.
  • Function tools, parallel calls and tool outputs, streamed or not. Grouped (namespace) tools are supported.
  • Hosted and freeform tools (web_search, custom such as a freeform apply_patch, tool_search) are ignored. Replayed reasoning items are ignored. Ignored fields are listed in the x-tokenhub-ignored-fields response header.
  • reasoning.effort is passed on; minimal is sent as low and xhigh as high.

An answer that stops at the output limit ends as incomplete, which Codex retries. If a model keeps stopping there, choose a model with a larger output limit.

Troubleshooting

  • 401 invalid API key: the key is not set in the environment Codex runs in, or belongs to another environment. Never print the key to check it.
  • 404 for the model: copy the exact catalogue ID, and check the key's model restrictions.
  • 400 … is not supported: this route is stateless: remove previous_response_id or store: true from a custom client.
  • Use /status in Codex to confirm the active provider and model.

Client support

For Codex Desktop, see the Codex Desktop guide.

← PreviousClaude DesktopNext →Codex Desktop