Using ByteRouter with Codex CLI

Introduction

Codex CLI is an open-source terminal programming agent from OpenAI that can read and write files, run commands, fix bugs, and complete entire coding tasks directly from the command line. By integrating ByteRouter, you can freely use multiple models including GPT and Claude in Codex CLI, while enjoying more flexible and cost-effective billing.

Prerequisites

Before getting started, ensure you have:

Node.js Installed Download and install from Node.js official website (recommended LTS version v20 or higher) for npm-based installation of Codex CLI
ByteRouter API Key Sign in to ByteRouter Console to get your API key

Tip: If you don’t have a ByteRouter account yet, register at ByteRouter first.

Step 1: Install Codex CLI

Choose one of the following installation methods:

npm (Recommended)
Homebrew (macOS)

Install globally via npm, works on all operating systems:

npm install -g @openai/codex

If you encounter permission issues, prepend sudo (macOS / Linux).

macOS users can also install via Homebrew:

brew install codex

Verify Installation

After installation, run the following command to confirm success:

codex --version

If a version number is displayed, the installation is successful.

Step 2: Configure ByteRouter API

Codex CLI manages model providers through configuration files in the ~/.codex/ directory. We simply need to add a custom provider pointing to ByteRouter.

2.1 Find the Configuration Directory

macOS / Linux: ~/.codex/
Windows: C:\Users\<username>\.codex\

If the directory doesn’t exist, run codex once in your terminal and press Ctrl + C to exit. The directory will be created automatically.

2.2 Configure API Key

Create or edit the auth.json file in the configuration directory with your ByteRouter key:

{
  "OPENAI_API_KEY": "your_api_key_here"
}

Field	Description
`OPENAI_API_KEY`	Your ByteRouter API key

2.3 Configure Model Provider

Create or edit the config.toml file in the configuration directory and add the ByteRouter provider:

# Default model to use
model = "gpt-5.5"
# Default provider, corresponds to [model_providers.byterouter] below
model_provider = "byterouter"

# ByteRouter provider configuration
[model_providers.byterouter]
name = "ByteRouter"
base_url = "https://byterouter.ai/v1"
wire_api = "responses"
requires_openai_auth = true

Field	Description
`model`	Default model ID, choose from the list below
`model_provider`	Default provider, must match ID in `[model_providers.xxx]`
`name`	Provider display name, customizable
`base_url`	ByteRouter’s OpenAI-compatible address, fixed as `https://byterouter.ai/v1`
`wire_api`	Communication protocol, new Codex requires `responses` (Responses API)
`requires_openai_auth`	Set to `true` to use the key from `auth.json`

After saving both files, restart Codex CLI for changes to take effect.

Ensure auth.json is valid JSON and config.toml is valid TOML. Don’t use Chinese quotes, or the configuration won’t work.

Step 3: Get Started

Verify Configuration

In any project directory, run the following command to verify your configuration:

codex "Introduce yourself in one sentence"

If you receive an AI response, the configuration is successful. If you see a login screen or 401, 403 errors, refer to the troubleshooting section below.

Interactive Mode

Run codex directly to enter the interactive interface, ideal for handling complete coding tasks:

codex

Once inside, describe your requirements in natural language, for example:

Create an Express.js server with a health check endpoint that returns JSON

Codex will automatically analyze your project, generate code, run commands, and request confirmation before sensitive operations.

Approval Mode

On first run, Codex will let you choose the approval level for operations:

Mode	Description
Read-only	Only allow file reads; modifications and commands need approval
Auto	Can autonomously read/write files and run commands within the directory (recommended)
Full access	Execute any operation without confirmation (use with caution)

We recommend starting with Auto mode. Type /approvals in the interactive interface to adjust anytime.

Switch Models

Type /model command in the interactive interface to quickly switch models, or modify the model field in config.toml and restart.

Supported Models

For Codex CLI, we recommend the following GPT-5 series models:

Model ID	Characteristics	Recommended Use Case
`gpt-5.5`	Latest flagship, strongest code ability	Codex first choice, complex engineering tasks
`gpt-5.4`	Previous generation flagship, powerful capability	Complex coding, architecture design
`gpt-5.4-mini`	Lightweight, fast speed, good price-performance	Daily coding, rapid iteration
`gpt-5.3-codex`	Codex-optimized coding model	Agent-style coding tasks
`gpt-5.2`	Stable and balanced	Regular coding tasks

Model Selection Recommendation: The above GPT-5 series models work best with Codex CLI. For optimal results, we recommend prioritizing gpt-5.5; gpt-5.3-codex is specifically optimized for Codex’s agent-based coding scenarios.

Common Commands

Here are frequently used commands and shortcuts in Codex CLI:

Command	Description
`codex`	Enter interactive mode
`codex "task description"`	Start with initial instruction
`codex exec "task description"`	Non-interactive mode, execute and exit
`codex --model gpt-5.4`	Start with specified model
`codex --version`	Check version number
`/model`	Switch model in interactive mode
`/approvals`	Adjust approval mode in interactive interface
`Ctrl + C`	Exit interactive mode

Troubleshooting

If a login prompt appears on startup, the configuration hasn’t taken effect. Troubleshooting steps:

Confirm both config.toml and auth.json are in the ~/.codex/ directory
Check that model_provider in config.toml is set to byterouter
Verify auth.json has valid JSON format and the key is fully entered

Q2: 401 / 403 errors?

Error Code	Meaning	Solution
`401 Unauthorized`	Invalid or missing API key	Check your key in `auth.json` is correct
`403 Forbidden`	Insufficient permissions or expired key	Verify key status at ByteRouter Console

Ensure base_url is set to https://byterouter.ai/v1.

Q3: Connection failure?

Check your network connection
Verify base_url in config.toml is correct
If using a proxy, ensure it allows access to byterouter.ai

Q4: `wire_api = "chat"` no longer supported?

New Codex CLI (0.84.0 and later) has removed the chat protocol. Change wire_api in config.toml to responses:

wire_api = "responses"

ByteRouter supports Responses API. After making this change, restart Codex.

Q5: Tool call or execution errors?

Confirm wire_api in config.toml is set to responses. If you encounter compatibility issues, try switching to recommended models (like gpt-4.1 or claude-opus-4.5), which work more reliably with Codex CLI.

Q6: Want to use environment variables instead of auth.json?

You can also configure the key via environment variables. Modify the provider configuration in config.toml:

[model_providers.byterouter]
name = "ByteRouter"
base_url = "https://byterouter.ai/v1"
wire_api = "responses"
env_key = "BYTEROUTER_API_KEY"

Then set the environment variable BYTEROUTER_API_KEY to your ByteRouter key. You won’t need auth.json in this case.

Q7: How to switch models?

Two ways:

In interactive mode: Type /model command to switch
Modify configuration: Change the model field in config.toml and restart Codex CLI

Support & Help

If you encounter any issues:

📧 Technical Support: [email protected]

Getting started

Client Tools

Using ByteRouter with Codex CLI

Introduction

Prerequisites

Step 1: Install Codex CLI

Verify Installation

Step 2: Configure ByteRouter API

2.1 Find the Configuration Directory

2.2 Configure API Key

2.3 Configure Model Provider

Step 3: Get Started

Verify Configuration

Interactive Mode

Approval Mode

Switch Models

Supported Models

Common Commands

Troubleshooting

Q2: 401 / 403 errors?

Q3: Connection failure?

Q4: `wire_api = "chat"` no longer supported?

Q5: Tool call or execution errors?

Q6: Want to use environment variables instead of auth.json?

Q7: How to switch models?

Support & Help

Get Started with ByteRouter

​Introduction

​Prerequisites

​Step 1: Install Codex CLI

​Verify Installation

​Step 2: Configure ByteRouter API

​2.1 Find the Configuration Directory

​2.2 Configure API Key

​2.3 Configure Model Provider

​Step 3: Get Started

​Verify Configuration

​Interactive Mode

​Approval Mode

​Switch Models

​Supported Models

​Common Commands

​Troubleshooting

​Q1: Login screen appears after startup?

​Q2: 401 / 403 errors?

​Q3: Connection failure?

​Q4: wire_api = "chat" no longer supported?

​Q5: Tool call or execution errors?

​Q6: Want to use environment variables instead of auth.json?

​Q7: How to switch models?

​Support & Help

Get Started with ByteRouter

Introduction

Prerequisites

Step 1: Install Codex CLI

Verify Installation

Step 2: Configure ByteRouter API

2.1 Find the Configuration Directory

2.2 Configure API Key

2.3 Configure Model Provider

Step 3: Get Started

Verify Configuration

Interactive Mode

Approval Mode

Switch Models

Supported Models

Common Commands

Troubleshooting

Q1: Login screen appears after startup?

Q2: 401 / 403 errors?

Q3: Connection failure?

Q4: `wire_api = "chat"` no longer supported?

Q5: Tool call or execution errors?

Q6: Want to use environment variables instead of auth.json?

Q7: How to switch models?

Support & Help