Tokenmaxer

Codex

Point Codex at a Tokenmaxer access token.

Before you start

  • Codex installed, with codex on your PATH. The setup script configures a harness; it does not install one. Install Codex →
  • Node.js 18 or newer, which the setup script runs on.
  • A Tokenmaxer API key. Create one →

Run the setup script

Run this, pick Codex, and paste your key when it asks. It writes the configuration below for you, backing up anything it touches.

Terminal
curl -fsSL https://tokenmaxer.dev/setup.sh | bash

To skip the menu, pass the harness: curl -fsSL https://tokenmaxer.dev/setup.sh | bash -s -- codex. Run it again after connecting another provider plan to refresh the available models, or curl -fsSL https://tokenmaxer.dev/setup.sh | bash -s -- --undo to put your files back.

Test it

Terminal
codex --profile tokenmaxer

The session starts on a Tokenmaxer model, and `/model` lists Tokenmaxer's models rather than OpenAI's. `codex` on its own still uses your normal OpenAI account and auth.

Configure it manually

This is what the setup script writes, for anyone who would rather edit the files themselves. Replace<YOUR_KEY> with your Tokenmaxer access token.

  • The provider must be defined at user level

    Codex ignores `model_providers` in a project-local `.codex/config.toml`. The definition has to live in `~/.codex/config.toml`.

  • `model_catalog_json` is the only way Codex reads Tokenmaxer's model list

    Codex asks a custom provider for its catalogue only when the provider carries an auth command: `http_headers`, `env_key` and `experimental_bearer_token` all leave it on the list it shipped with. Even with one it *merges* rather than replaces, so OpenAI's bundled slugs appear in the picker and Tokenmaxer rejects them. A profile-level `model_catalog_json` skips both: no catalogue request, no merge, no `models_cache.json`, and the picker holds exactly the file's models.

~/.codex/config.toml

Defines Tokenmaxer as a provider without selecting it, so your normal Codex setup keeps working.

~/.codex/config.toml
[model_providers.tokenmaxer]
name = "Tokenmaxer"
base_url = "https://api.tokenmaxer.dev/v1"
wire_api = "responses"

[model_providers.tokenmaxer.http_headers]
Authorization = "Bearer <YOUR_KEY>"

~/.codex/tokenmaxer-models.json

Tokenmaxer's model list, in the shape Codex reads. Without it Codex never asks a header-authenticated provider for a catalogue, and merges the one it shipped with into the picker: OpenAI slugs the gateway rejects. Re-run setup to refresh it.

~/.codex/tokenmaxer-models.json
curl -fsS "https://api.tokenmaxer.dev/v1/models?client_version=$(codex --version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')" \
  -H "Authorization: Bearer <YOUR_KEY>" -o ~/.codex/tokenmaxer-models.json

~/.codex/tokenmaxer.config.toml

`codex --profile tokenmaxer`: starts on Claude Sonnet 5.5. `/model` switches to any of the other 9, across both serviceIds. Tokenmaxer writes this file whole, so a hand-edit here is replaced on the next setup run.

~/.codex/tokenmaxer.config.toml
model = "anthropic/claude-sonnet-5-5"
model_provider = "tokenmaxer"
model_catalog_json = "~/.codex/tokenmaxer-models.json"