Skip to main content

MindsHub in Codex

Codex is OpenAI's terminal coding agent. It speaks the Responses API, so once MindsHub's Responses upgrade lands, Codex runs against MindsHub as a custom model provider and can drive any model in the catalog, not just OpenAI's. Codex on Claude Sonnet 5 or Kimi K3 is a small config change.

Not usable yet. /v1/responses does not yet return the streaming Responses format Codex requires, so Codex sessions against MindsHub currently fail with a server error. This page documents the setup that will work when the upgrade ships. The Claude Code and VS Code integrations work today.

Prerequisites​

Check your key first​

Before touching Codex, confirm the key and the Responses endpoint work:

curl https://api.mindshub.ai/v1/responses \
  -H "Authorization: Bearer $MINDSHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt", "input": "say OK"}'

A 401 means authentication failed; fix that first. While the upgrade is pending this call returns a Chat Completions-shaped body. When it starts returning a Responses body with "output_text": "OK", Codex support is live.

Configure Codex​

Add MindsHub as a model provider in ~/.codex/config.toml:

model = "gpt"
model_provider = "mindshub"

[model_providers.mindshub]
name = "MindsHub"
base_url = "https://api.mindshub.ai/v1"
env_key = "MINDSHUB_API_KEY"
wire_api = "responses"

Then export the key and run it:

export MINDSHUB_API_KEY="mdb_..."
codex

The four provider fields:

  • base_url must end in /v1. Codex appends /responses itself. (This is the opposite of the Claude Code setup, where the base URL is the bare host; the two agents follow their own vendors' conventions.)
  • env_key names the environment variable Codex reads the key from. It does not hold the key itself, and the key never goes in the config file.
  • wire_api = "responses" is required. Codex removed its Chat Completions mode in early 2026.
  • name is a display label only.

The top-level model is the default for new sessions, and it takes a catalog alias such as gpt, sonnet, kimi, or deepseek, not a provider model ID.

Switch models​

Per run:

codex --model sonnet       # Claude Sonnet 5, in Codex
codex --model kimi         # Kimi K3
codex --model deepseek     # DeepSeek V4 Pro
codex --model gpt-codex    # GPT 5.3 Codex

Or keep a few profiles in config.toml and select one with --profile:

[profiles.claude]
model = "sonnet"
model_provider = "mindshub"

[profiles.cheap]
model = "deepseek"
model_provider = "mindshub"
codex --profile cheap

Any alias from GET /v1/models works. Because every model resolves through the same key, switching costs you nothing but the edit.

Verify it​

Ask Codex something trivial in a session, then confirm MindsHub metered it. The row should show the alias you ran:

curl "https://auth.mindshub.ai/v1/usage/summary/?range=period&group_by=model" \
  -H "Authorization: Bearer $MINDSHUB_API_KEY"

If a row appears for your alias, the integration is working end to end: request, generation, and metering.

Cost and billing​

  • Codex shows token counts, not costs. Its session stats carry no MindsHub prices, so the usage summary is the only real number.
  • Everything lands on one balance. Codex, Claude Code, VS Code, and your application traffic all draw the same prepaid wallet and appear in the same per-model summary.
  • Agents are token-hungry. Long system prompts and large file contexts add up; see the price list and pick accordingly. deepseek and kimi are markedly cheaper than opus for bulk work.
  • Prompt caching helps. Codex resends context each turn; the prompt cache absorbs most of that at about a tenth of the input price on most models.

Scope and limits​

  • No conversation chaining. MindsHub doesn't honor previous_response_id, so Codex's context comes from what it sends each turn, which is how it operates by default. See Statelessness.
  • Sampling parameters are adapted per model. If Codex sends a sampling parameter the target model doesn't take, MindsHub drops it and serves the request rather than failing, and reports it in X-MindsHub-Dropped-Params. See Core concepts.
  • Reasoning content isn't returned. Models reason internally and those tokens bill as output, but the traces aren't exposed.

Troubleshooting​

SymptomCause and fix
404 or Not Foundbase_url must end in /v1.
401The key is wrong or revoked, or MINDSHUB_API_KEY isn't exported in the shell running codex. Remember env_key names the variable, not the value.
model_not_foundmodel isn't a catalog alias. Check GET /v1/models: it's kimi, not kimi-k3.
Requests fail only when streamingConfirm wire_api = "responses". A provider left on a chat wire will not work.
Replies truncate mid-answerThe model's internal reasoning used the output budget. Choose a model with adjustable reasoning effort, or raise the output cap.
429Throughput limit, not funding. Back off; see Rate limits.

See also​