Codex CLI Integration

OpenAI Codex CLI is an AI coding agent that runs in your terminal. Token101 fully supports Codex CLI via the OpenAI Responses API (/api/v1/responses), the same wire protocol Codex uses by default.

Prerequisites

• Node.js 18 or later (nodejs.org)
• A Token101 API key — subscription users can create one directly; free users need to complete API activation first at token.ppthub.shop/settings/apikeys
• Codex CLI installed (see Step 1 below)

Step 1 — Install Codex CLI

npm install -g @openai/codex

If npm downloads are slow, you can use a China mirror:

npm install -g @openai/codex --registry=https://registry.npmmirror.com

Verify the installation:

codex --version

Step 2 — Set Environment Variables

Codex CLI reads two environment variables to locate the API server:

macOS / Linux — Set for current session

export OPENAI_BASE_URL="https://token.ppthub.shop/api/v1"
export OPENAI_API_KEY="your-token101-api-key"

macOS — Set permanently (zsh)

echo 'export OPENAI_BASE_URL="https://token.ppthub.shop/api/v1"' >> ~/.zshrc
echo 'export OPENAI_API_KEY="your-token101-api-key"' >> ~/.zshrc
source ~/.zshrc

macOS — Set permanently (bash)

echo 'export OPENAI_BASE_URL="https://token.ppthub.shop/api/v1"' >> ~/.bash_profile
echo 'export OPENAI_API_KEY="your-token101-api-key"' >> ~/.bash_profile
source ~/.bash_profile

Windows — Set for current session (PowerShell)

$env:OPENAI_BASE_URL = "https://token.ppthub.shop/api/v1"
$env:OPENAI_API_KEY = "your-token101-api-key"

Windows — Set permanently (PowerShell)

[System.Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", "https://token.ppthub.shop/api/v1", "User")
[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "your-token101-api-key", "User")

Step 3 — Verify the Connection

Run a quick test to confirm Codex can reach Token101:

codex "Reply with exactly: TOKEN101_OK"

If everything is configured correctly, Codex will respond with TOKEN101_OK.

Step 4 — Use Codex in Your Project

Navigate to any code project and start using Codex:

cd ~/my-project

# Ask Codex to explain code
codex "Explain what this project does"

# Ask Codex to write a function
codex "Write a function to validate email addresses"

# Ask Codex to fix a bug
codex "Fix the bug in src/utils.ts line 42"

# Interactive mode
codex

Specify a model

Token101 supports multiple models. Use the --model flag to select one:

codex --model gpt-5.2 "Write unit tests for src/auth.ts"

See Supported Models for the full list of available models.

How It Works

Codex CLI uses the OpenAI Responses API (wire_api = "responses") by default. When you set OPENAI_BASE_URL to Token101:

1. Codex sends requests to https://token.ppthub.shop/api/v1/responses
2. Token101 authenticates your API key, applies rate limits and billing
3. Token101's routing layer forwards the request to the underlying model provider
4. The response streams back through the same pipeline

This means you get all of Token101's features — usage tracking, billing controls, model routing — with zero changes to how you use Codex.

Available Models

The following models work with Codex CLI. Use the --model flag to select one:

See Supported Models for the full list including non-OpenAI models.

Known Limitations

• Server-side tool execution: Token101's Responses API is a passthrough adapter — it forwards requests to the upstream model provider as-is. Server-side tools (e.g., web search) are executed natively by the upstream model provider.
• Reasoning token billing: Reasoning/thinking tokens receive the same automatic discounts as other endpoints (Codex series 50% off, non-Codex GPT 25% off the output rate). See Billing for details.
• Model names: Codex sends the model name as-is to Token101. You must use the exact model IDs listed above. Legacy OpenAI model names (e.g., o3-mini, gpt-4.1) are not mapped.

Troubleshooting

Error: 401 Unauthorized

Your API key is invalid or missing.

1. Check that OPENAI_API_KEY is set: echo $OPENAI_API_KEY
2. Verify the key is active at token.ppthub.shop/settings/apikeys
3. Ensure the key starts with sk-

Error: 404 Not Found on /api/v1/responses

The Responses API endpoint is unreachable.

1. Confirm OPENAI_BASE_URL ends with /api/v1 (not /api/v1/responses):

   echo $OPENAI_BASE_URL
   # Should print: https://token.ppthub.shop/api/v1

2. Test the health endpoint: curl https://token.ppthub.shop/api/health

Error: 502 Bad Gateway

The upstream model provider is temporarily unavailable.

1. Check the status page for any ongoing incidents
2. Try a different model with --model gpt-5.2
3. Wait a few seconds and retry — this is usually transient

Error: 429 Too Many Requests

You've hit the rate limit. See Rate Limits for details and how to request higher limits.

Codex hangs or times out

1. Check your network connection
2. Test connectivity: curl -s https://token.ppthub.shop/api/health
3. Try a simpler prompt first to isolate the issue

Next Steps

• Supported Models — full list of available models
• Rate Limits — understand your request quotas
• Billing — track and manage your usage
• Claude Code Integration — if you also use Claude Code