Codex CLI

Let my agent set this upCopy Anchor Link

Copy this task to an agent already running on your computer:

Read this guide and help me connect Codex CLI to TokenLab:
https://tokenlab.sh/docs/en/integrations/codex-cli
Check my installed version and active configuration first.
Preserve existing accounts, providers, permissions and other settings.
Back up local files and show proposed changes.
Have me enter any API key locally; never ask for, print or paste it in chat.
Check configuration loading first.
Explain any paid request test separately before running it.

OverviewCopy Anchor Link

Codex CLI can connect to TokenLab through /v1/responses. The selected model must list openai_responses in tokenlab.accepted_request_formats; features can vary by model.

Remote compaction uses POST /v1/responses/compact. Codex sends the current session model in body.model, so that model must also support Responses. Do not configure /v1/compact.

System RequirementsCopy Anchor Link

Use the official CLI installation guide for macOS, Linux or Windows. Native Windows and WSL are separate environments; follow the Windows guide. The npm command below is one installation option, not a requirement for native binaries.

InstallationCopy Anchor Link

npm install -g @openai/codex@0.149.0

Verify installation:

codex --version

ConfigurationCopy Anchor Link

Step 1: Set API KeyCopy Anchor Link

Use the Quickstart terminal instructions for macOS, Linux, WSL, or Windows PowerShell to set TOKENLAB_API_KEY without putting the key in command history. Launch Codex from that terminal. For persistent use, use your local secret manager; do not append a plaintext key to your shell profile.

Step 2: Configure tokenlab.config.tomlCopy Anchor Link

Use a separate tokenlab.config.toml in your active CODEX_HOME (normally ~/.codex) with Codex 0.149.0. Create it only if the name is unused, or back it up before editing an existing TokenLab profile. The profile below is loaded explicitly with codex --profile tokenlab; it leaves the default config.toml, auth.json, accounts and permission policies unchanged. Do not use a legacy [profiles.tokenlab] table. Start without the profile to return to your ordinary setup. See the official profile configuration.

model_provider = "tokenlab"
model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"

[model_providers.tokenlab]
env_key = "TOKENLAB_API_KEY"
name = "TokenLab"
base_url = "https://api.tokenlab.sh/v1"
wire_api = "responses"
supports_websockets = true
websocket_connect_timeout_ms = 15000

This WebSocket mode is a Responses-over-WebSocket bridge for Codex clients. It accepts only official response.create events; stream is implicit, and background and response.cancel are not available on this transport. It is not the OpenAI Realtime API and does not accept session.update, conversation.item.*, input_audio_buffer.*, binary audio, or nested Realtime response.create.response envelopes.

Current Codex uses wire_api = "responses". Do not configure chat/completions. Keep requires_openai_auth unset or false for this custom provider so env_key is used.

Basic UsageCopy Anchor Link

Start interactive mode:

codex --profile tokenlab

Direct command:

codex --profile tokenlab "Fix the bug in main.py line 42"

Specify model:

codex --profile tokenlab -m gpt-5.6-sol "Build a REST API server"

Choose a modelCopy Anchor Link

Use a model that currently lists openai_responses in tokenlab.accepted_request_formats. Compare candidates on your own coding tasks and check current prices on the Models page.

Interactive CommandsCopy Anchor Link

Verify ConfigurationCopy Anchor Link

Check whether the environment variable is set without printing its value. This check does not validate the key:

if [ -n "${TOKENLAB_API_KEY:-}" ]; then
  printf '%s\n' 'TOKENLAB_API_KEY is set'
else
  printf '%s\n' 'TOKENLAB_API_KEY is not set'
fi

Start Codex and run /status to check the active model and permissions. If you use a profile, start that same profile. See the official status command.

When you are ready to make a real request, run the command below. It uses your TokenLab balance. Check the reply and the matching record in Requests; an environment check or successful startup alone does not prove a request succeeded.

codex --profile tokenlab "Reply only with OK. Do not use tools or modify files."

Common Use CasesCopy Anchor Link

Code review:

git diff | codex --profile tokenlab "Review these code changes"

Generate commit messages:

git diff --staged | codex --profile tokenlab "Generate a commit message for these changes"

Fix errors:

codex --profile tokenlab "Fix the TypeScript errors in src/components/"

Explain code:

cat main.py | codex --profile tokenlab "Explain what this code does"

TroubleshootingCopy Anchor Link