Codex CLI | JoyToken | Documentation

What is Codex CLI?

Codex CLI is a local coding agent that runs in your terminal. It supports custom model providers, so teams can route Codex model calls through JoyToken for centralized API key control, model routing, policy checks, wallet limits, and usage attribution.

JoyToken exposes an OpenAI-compatible Chat Completions endpoint:

https://api-dev.joytokens.ai/openai/v1

Quick Start

Step 1: Install Codex CLI

Install Codex CLI by following the official Codex installation instructions for your environment.

Step 2: Create a JoyToken API key

Create a dedicated key for Codex, for example dev-codex-cli.

Recommended policy:

Setting	Recommendation
Model	Start with `auto`
Budget	Small daily or weekly cap
IP allowlist	Team workstation, office, or VPN egress
Logs	Keep enabled for debugging

Step 3: Set your API key

~/.zshrc

$ export JOY_TOKEN_API_KEY="jt_xxx"

Reload your shell:

$ source ~/.zshrc

Step 4: Configure Codex for JoyToken

Codex reads ~/.codex/config.toml. Add a JoyToken provider:

~/.codex/config.toml

1 model_provider = "joytoken"
2 model = "auto"
3 
4 [model_providers.joytoken]
5 name = "joytoken"
6 base_url = "https://api-dev.joytokens.ai/openai/v1"
7 env_key = "JOY_TOKEN_API_KEY"

Step 5: Start Codex

$ cd /path/to/your/project
$ codex

Model requests now route through JoyToken.

Configuration Reference

Core settings

Setting	Description	Example
`model_provider`	Provider used by Codex	`"joytoken"`
`model`	JoyToken model key or router mode	`"auto"`
`base_url`	JoyToken OpenAI-compatible base URL	`"https://api-dev.joytokens.ai/openai/v1"`
`env_key`	Environment variable containing the API key	`"JOY_TOKEN_API_KEY"`

Model values

Value	Behavior
`auto`	JoyToken router selects a model within policy
Concrete model key	Pins the request to a JoyToken model while still passing policy and wallet checks
API key fixed model	Key policy restricts or overrides requested models

Why use JoyToken with Codex CLI?

Central API key control

Create dedicated Codex keys, revoke them independently, and keep local development separate from production keys.

Budget and policy controls

Apply model, tier, IP, and budget policies before a coding session can spend credits.

Usage visibility

Track Codex usage in JoyToken Logs, Usage, and Billing by API key. Split keys by developer or workflow when you need cleaner attribution.

Model flexibility

Start with auto while evaluating quality and cost. Pin a model later for repeatable workflows.

Troubleshooting

Symptom	Check
`401 Unauthorized`	`JOY_TOKEN_API_KEY` is set and copied correctly
`403 Forbidden`	Key policy allows the current IP, tier, and model
`402 Payment Required`	Wallet balance, quota, or budget is sufficient
Model not found	Use `auto` or a model key from the JoyToken model catalog
No JoyToken logs	Confirm `model_provider = "joytoken"` and `base_url` includes `/openai/v1`