Codex CLI Integration

Codex CLI is the terminal command-line version of Codex. It is designed for local project workflows where you run codex in a terminal to understand, edit, explain, and execute coding tasks. This page is only for Codex CLI installation and relay switching.

Codex CLI vs Codex IDE

Use this page for the terminal codex command. If you use the Codex IDE/desktop app, see Codex IDE.

• Required Values
• Install Codex CLI
• Recommended: Switch Relay with CC-Switch
  • 1. Open the Codex Tab
  • 2. Fill In the CLI Configuration
  • 3. Enable and Restart the CLI
• Fallback: Manual CLI Configuration
  • Config Directory
  • config.toml
  • auth.json
• Start Codex CLI
• FAQ

Required Values

Field	Value
Node.js / npm	Used to install the @openai/codex command-line tool
Base URL	https://www.potatoai.cc/v1
API Key	A codex token group key created in the PotatoAI.cc console
Model	The full model ID shown in Model Square or the console
Switching tool	CC-Switch is recommended

Command-Line Scope

Codex CLI is launched with the codex terminal command. It is not Cursor, Trae, or the Codex IDE/desktop app.

Install Codex CLI

Install Node.js first, then install Codex CLI through npm.

Windows PowerShell

npm install -g @openai/codex@latest
codex --version

macOS

npm install -g @openai/codex@latest
codex --version

Linux

npm install -g @openai/codex@latest
codex --version

Linux Permission Note

If global npm installation fails on Linux because of permissions, adjust your npm global directory based on your Node.js setup, or temporarily use sudo npm install -g @openai/codex@latest.

Recommended: Switch Relay with CC-Switch

Codex CLI relay switching is also best handled in CC-Switch. This makes it easy to switch between the official configuration, PotatoAI.cc, and other providers.

1. Open the Codex Tab

1. Start CC-Switch.
2. Switch to the Codex tab.
3. Click + to add a new configuration.

2. Fill In the CLI Configuration

Field	Suggested Value
Configuration name	For example, PotatoAI Codex CLI.
Base URL	https://www.potatoai.cc/v1.
API Key	Use a dedicated key from the codex token group.
Model	Copy the full model ID from Model Square, for example gpt-5.4. Use it only if it appears in the current group list.
Other settings	Adjust reasoning effort, network access, sandbox mode, and approval policy as needed.

3. Enable and Restart the CLI

1. Mark this configuration as active in CC-Switch.
2. Close all running Codex CLI sessions.
3. Return to your project directory and run codex again.

Tray Switching

You can also switch Codex CLI configurations from the CC-Switch tray menu. After switching, restart the current codex session in your terminal.

Fallback: Manual CLI Configuration

If you do not use CC-Switch, create the Codex CLI configuration files manually.

Config Directory

Windows PowerShell

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"
Set-Location "$env:USERPROFILE\.codex"

macOS / Linux

mkdir -p ~/.codex
cd ~/.codex

config.toml

model_provider = "PotatoAI"
model = "gpt-5.4" # Replace with the full model ID shown in the console.
model_reasoning_effort = "high"
disable_response_storage = true
approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_supports_reasoning_summaries = true

[model_providers.PotatoAI]
name = "PotatoAI"
base_url = "https://www.potatoai.cc/v1"
wire_api = "responses"
requires_openai_auth = true

Sandbox Recommendation

workspace-write is a better default for daily project work. Only loosen sandbox settings in trusted projects when you clearly need broader permissions.

auth.json

{
  "OPENAI_API_KEY": "Paste your dedicated Codex CLI token here"
}

Do Not Expose Keys

Do not commit auth.json or API keys to Git, and do not send full keys to others when troubleshooting.

Start Codex CLI

Run this inside your project directory:

codex

For the first test, send a simple task such as:

Summarize this project structure and identify the main entry files.

If Codex responds normally, the CLI is connected through the PotatoAI.cc relay.

FAQ

Which page should I use: Codex CLI or Codex IDE?

Use this page for the terminal codex command. Use Codex IDE for the graphical app, desktop app, or IDE integration.

Why is Codex still using the old relay after switching?

Close the current codex session, reopen your terminal, and run codex again. The CLI usually reads configuration at startup.

Can Codex CLI use a Claude Code token?

Not recommended. Codex CLI should use a dedicated key from the codex token group, while Claude Code uses its own token group.

What should I do if the model does not exist?

Open Model Square, filter by the current codex token group, copy the full model ID from the available model list, and make sure capitalization, version suffixes, and symbols match exactly.