Codex IDE Integration

Codex is an AI coding assistant for developers. This page is only for the Codex IDE/desktop app: install Codex from the official website, then switch its relay settings to PotatoAI.cc with CC-Switch or configuration files.

Codex IDE vs Codex CLI

Use this page for the Codex IDE/desktop app. If you run codex in a terminal, use Codex CLI instead.

• When to Use This Page
• Install Codex
• Required Values
• Recommended: Switch Relay with CC-Switch
  • 1. Open the Codex Config Page
  • 2. Fill In the PotatoAI.cc Settings
  • 3. Enable the Config and Restart Codex
• Fallback: Edit Config Files Manually
  • Config Location
  • config.toml Example
  • auth.json Example
• FAQ

When to Use This Page

Page	Best For	Configuration Style
Codex IDE	Users working in a graphical app, editor integration, or desktop workflow	Install from the official website, then switch the relay with CC-Switch or config files
Codex CLI	Users running the codex command in a terminal	Install the CLI with npm, then switch the relay with CC-Switch

Install Codex

Download or install the version for your system from the official OpenAI Codex page.

Resource	Link
Official OpenAI Codex docs	developers.openai.com/codex
PotatoAI.cc API key guide	Create an API Key
Available model lookup	Models and Pricing
CC-Switch guide	CC-Switch

Token Group Requirement

Use a dedicated API key from the codex token group for Codex. Do not reuse Claude Code, Cursor, or other tool tokens directly.

Required Values

Field	Value
Provider	OpenAI Compatible / Custom OpenAI Endpoint
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

Recommended: Switch Relay with CC-Switch

CC-Switch is recommended when you need to switch between multiple Codex configurations, and it helps avoid formatting mistakes in manual config files.

1. Open the Codex Config Page

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

2. Fill In the PotatoAI.cc Settings

Field	Suggested Value
Configuration name	A custom name, such as PotatoAI Codex.
Base URL	https://www.potatoai.cc/v1. If the console shows a dedicated URL, use the console value.
API Key	Paste the API 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, and permission policy as needed.

Copy the Full Model Name

Do not modify the model name, version suffix, capitalization, or hyphens. If Codex reports model not found, check Model Square for the models available to the current token group.

3. Enable the Config and Restart Codex

1. Select the configuration you just created in the CC-Switch Codex list.
2. Click Use Current or the equivalent active-config button.
3. Fully quit and reopen the Codex IDE/desktop app.
4. Send a short request to confirm that the model responds normally.

Tray Switching

If CC-Switch is running in the system tray, right-click the tray icon and switch configurations under the Codex category. Restart Codex after switching so the new configuration is read cleanly.

Fallback: Edit Config Files Manually

If you do not use CC-Switch, you can maintain Codex configuration files manually. Config locations may vary by Codex version; if your Codex app exposes a UI for Base URL and API key, prefer the built-in UI.

Config Location

System	Common Location
Windows	%USERPROFILE%\.codex\
macOS / Linux	~/.codex/

config.toml Example

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

auth.json Example

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

Key Safety

Do not commit auth.json, API keys, or screenshots containing full keys to repositories, public issues, or chat messages.

FAQ

Are Codex IDE and Codex CLI the same entry point?

No. The Codex IDE/desktop app is for graphical and editor-based workflows; Codex CLI is the terminal command-line tool. Both can use CC-Switch for relay configuration, but they are installed and used differently.

Why did the new config not take effect?

Confirm that the target configuration is marked as active in CC-Switch, then fully quit and reopen Codex. Some settings are read only when the app starts.

Can I share one token with Claude Code?

Not recommended. Codex should use the codex token group, while Claude Code uses its own token group. Token groups affect model availability and permissions.

What should I do if the model is missing or unauthorized?

Open Model Square, filter by the current codex token group, copy the full model ID shown in the list, and confirm that your API key belongs to the correct group.