Use TokenPak with Codex CLI¶

This guide is for developers using OpenAI Codex CLI who want to route its traffic through TokenPak for request records, cost tracking, and cache analytics.

Run tokenpak codex with an already authenticated Codex client. The reference path reuses its existing OAuth login and selected or default model.

What you need before starting:

Codex CLI installed and authenticated (codex --version works)
Python 3.10+
No existing OPENAI_BASE_URL override that conflicts

An OpenAI or Anthropic API key is not required for this path. You also do not need to choose a model in TokenPak: the launcher preserves the model Codex selected, or Codex's own default.

Copy-paste setup¶

pip install --upgrade tokenpak
tokenpak setup
tokenpak codex

tokenpak codex launches Codex with the TokenPak route for that process. It does not edit ~/.codex/auth.json, require a provider key, or override the model selected by Codex.

1. Install and start TokenPak¶

pip install tokenpak
tokenpak setup

tokenpak setup detects optional provider API keys, creates ~/.tokenpak/config.yaml, and starts the proxy on port 8766. If no keys are present, setup continues for clients such as Codex that already have their own credentials. You should see:

TokenPak proxy listening on http://localhost:8766

Confirm the proxy is healthy:

curl -s http://localhost:8766/health | python3 -m json.tool

Expected response shape:

{
  "status": "ok",
  "uptime_seconds": 3,
  "version": "1.25.1",
  "requests_total": 0,
  "requests_errors": 0,
  "compression_ratio_avg": 0.0
}

If status is not "ok", run tokenpak status for details before continuing.

2. Launch Codex through TokenPak¶

The recommended path is:

tokenpak codex

TokenPak supplies the route only to the launched process and reuses Codex's existing OAuth state. Normal model selection remains owned by Codex.

Manual shell-scoped route¶

Codex CLI uses the same OPENAI_BASE_URL environment variable as the OpenAI SDK to redirect API traffic.

export OPENAI_BASE_URL=http://localhost:8766/v1
codex exec "summarize the last commit"

Set the variable in the same shell you launch Codex from, or add it to your shell profile so it persists across sessions:

# Add to ~/.bashrc or ~/.zshrc
export OPENAI_BASE_URL=http://localhost:8766/v1

Then reload:

source ~/.bashrc   # or source ~/.zshrc

TokenPak reuses your existing Codex OAuth login; no separate credential is required for this path.

When another Codex session is already running¶

TokenPak first inspects the shared local history for a verified live or stopped holder. In an interactive terminal, verified contention may produce this choice:

Another Codex session is using your shared local history.
Start a temporary session without that prior history? [y/N]

The safe default is No. If you accept, the temporary session receives a new history lineage for that launch; it does not attach or replace the prior shared history, and later normal launches return to the shared lineage. TokenPak does not ask you to select or manage CODEX_HOME.

If inspection is incomplete, permissions or storage fail, state appears corrupt, or the cause is unknown, TokenPak refuses the fallback rather than guessing. Close the active session normally or resolve the reported diagnostic before retrying.

3. Verify the proxy is intercepting traffic¶

Run any Codex command. Then in a second terminal:

tokenpak status

You should see at least one row of recent activity attributed to the openai-codex-responses adapter. If the table is still empty after sending a request, the env var is not in scope — see Troubleshooting below.

4. Check your usage and savings¶

After a few requests:

tokenpak cost --week      # spend by model
tokenpak savings          # recorded token savings; zero is a valid result

The default proxy preserves conversation turns, so a forwarded request can truthfully report zero tokens saved. Explicit context tools can reduce eligible content; measure their effect with tokenpak savings.

Troubleshooting¶

`tokenpak status` shows no activity after a Codex run¶

Confirm the env var is set in the same shell that ran codex:

echo "$OPENAI_BASE_URL"   # should print http://localhost:8766/v1

If it prints nothing, set it before invoking codex:

export OPENAI_BASE_URL=http://localhost:8766/v1
codex exec "your prompt"

Codex picks up the variable on launch. Already-running shells that started before the export will not see it — open a fresh shell or re-source your profile.

Port collision — proxy fails to start on 8766¶

If 8766 is already in use:

lsof -i :8766

Kill the conflicting process, then restart TokenPak. Alternatively, change the port:

TOKENPAK_PORT=8767 tokenpak serve
export OPENAI_BASE_URL=http://localhost:8767/v1

Auth errors — 401 from the proxy¶

TokenPak forwards the OAuth bearer token from each request unchanged. If you see a 401:

Confirm Codex CLI is authenticated: cat ~/.codex/auth.json should show a tokens.access_token field. If the file is missing, run codex login first.
Codex tokens expire on a rolling schedule — Codex CLI refreshes them automatically when you run a command. If 401s persist, run codex login again to force a fresh sign-in.
The token TokenPak sees must be a JWT (starts with eyJ). If your shell exports a stale OPENAI_API_KEY=sk-..., Codex will send that instead and the proxy will route to api.openai.com rather than the ChatGPT backend. Either unset OPENAI_API_KEY or rely on Codex's own credential file.

Codex requests get 403 (Cloudflare block)¶

The Codex adapter routes to chatgpt.com/backend-api, which Cloudflare protects. TokenPak uses curl_cffi to present a browser-shaped TLS fingerprint and bypass the block. If curl_cffi is not installed, the proxy falls back to urllib3 and Cloudflare may return 403.

Install or upgrade curl_cffi:

pip install --upgrade curl_cffi

Restart the proxy after installing.

`CODEX_HOME` set to a non-default location¶

If you set CODEX_HOME to point Codex's config elsewhere, TokenPak's credential discovery honors it as well. No proxy-side change is required — just keep the env var consistent across the shell that runs both codex and tokenpak.

Removing TokenPak¶

To stop routing Codex CLI traffic through TokenPak:

unset OPENAI_BASE_URL

Remove the export from your shell profile if you added it there. Codex will return to the default ChatGPT backend on the next run. Your ~/.codex/auth.json is untouched at every step — TokenPak never writes to it.