Codex IDE 接入指南

Codex 是面向开发者的 AI 编码助手。本文只介绍 Codex IDE/桌面软件 的安装与中转站配置：先从官网安装 Codex，再通过 CC-Switch 或配置文件把请求切换到 PotatoAI.cc。

与 Codex CLI 的区别

本页适用于 Codex IDE/桌面软件。如果你使用的是终端里的 codex 命令，请查看 Codex CLI。

• 适用场景
• 安装 Codex
• 准备信息
• 推荐方式：使用 CC-Switch 切换中转站
  • 1. 打开 Codex 配置页
  • 2. 填写 PotatoAI.cc 配置
  • 3. 启用配置并重启 Codex
• 备用方式：手动修改配置文件
  • 配置文件位置
  • config.toml 示例
  • auth.json 示例
• 常见问题

适用场景

页面	适合谁	配置方式
Codex IDE	使用图形界面、编辑器集成或桌面软件的用户	官网安装后，用 CC-Switch 或配置文件切换中转站
Codex CLI	在终端中运行 codex 命令的用户	npm 安装 CLI 后，用 CC-Switch 切换中转站

安装 Codex

请前往 OpenAI Codex 官方页面下载或安装适合你系统的版本。

资源	地址
OpenAI Codex 官方文档	developers.openai.com/codex
PotatoAI.cc API Key 创建	创建 API Key
可用模型查询	模型与定价
CC-Switch 说明	CC-Switch

令牌组要求

Codex 建议使用 codex 令牌组的专用 API Key。不要把 Claude Code、Cursor 或其他工具的令牌直接混用到 Codex。

准备信息

配置项	填写内容
Provider	OpenAI Compatible / Custom OpenAI Endpoint
Base URL	https://www.potatoai.cc/v1
API Key	PotatoAI.cc 控制台创建的 codex 令牌组密钥
Model	模型广场或控制台展示的完整模型 ID

推荐方式：使用 CC-Switch 切换中转站

CC-Switch 适合需要在多个 Codex 配置之间快速切换的用户，也能减少手动编辑配置文件时的格式错误。

1. 打开 Codex 配置页

1. 启动 CC-Switch。
2. 切换到 Codex 标签页。
3. 点击右上角 + 添加新配置。

2. 填写 PotatoAI.cc 配置

配置项	建议值
配置名称	自定义名称，例如 PotatoAI Codex。
Base URL	https://www.potatoai.cc/v1。如果控制台给出专用地址，以控制台为准。
API Key	粘贴 codex 令牌组的 API Key。
Model	从模型广场复制完整模型 ID，例如 gpt-5.4。仅在该模型出现在当前分组列表中时使用。
其他参数	按需调整推理强度、网络访问和权限策略。

模型名必须完整复制

不要自行修改模型名称、版本号、大小写或短横线。Codex 报 model not found 时，优先回到模型广场核对当前令牌分组可用模型。

3. 启用配置并重启 Codex

1. 在 CC-Switch 的 Codex 配置列表中选择刚创建的配置。
2. 点击 当前使用 或同等含义的按钮。
3. 完全退出并重新打开 Codex IDE/桌面软件。
4. 发送一条短请求，确认可以正常返回。

托盘快速切换

如果 CC-Switch 已在系统托盘运行，可以右键托盘图标，在 Codex 分类下直接切换配置。切换后建议重启 Codex，让新配置被重新读取。

备用方式：手动修改配置文件

如果你不使用 CC-Switch，也可以手动维护 Codex 配置文件。不同 Codex 版本可能读取的配置位置略有差异；如果官方界面提供了自定义 Base URL 和 API Key 入口，优先使用界面配置。

配置文件位置

系统	常见位置
Windows	%USERPROFILE%\.codex\
macOS / Linux	~/.codex/

config.toml 示例

model_provider = "PotatoAI"
model = "gpt-5.4" # 请替换为控制台展示的完整模型 ID
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 示例

{
  "OPENAI_API_KEY": "此处粘贴你的 Codex 专用令牌"
}

密钥安全

不要把 auth.json、API Key 或截图中的完整密钥提交到代码仓库、公开 Issue 或聊天记录里。

常见问题

Codex IDE 和 Codex CLI 是同一个入口吗？

不是。Codex IDE/桌面软件偏图形界面和编辑器工作流；Codex CLI 是终端里的命令行工具。两者都可以通过 CC-Switch 管理中转配置，但安装方式和使用入口不同。

配置后没有生效怎么办？

先确认 CC-Switch 中目标配置已经标记为当前使用，然后完全退出并重新打开 Codex。部分设置只会在应用启动时读取。

可以和 Claude Code 共用令牌吗？

不建议。Codex 应使用 codex 令牌组，Claude Code 使用自己的令牌组。令牌组不同会影响可用模型和权限。

出现模型不存在或无权限怎么办？

进入模型广场，筛选当前 codex 令牌组，复制列表中展示的完整模型 ID，并确认 API Key 属于正确分组。