Codex CLI 接入指南

Codex CLI 是终端命令行形态的 AI 编程工具，适合在本地项目目录中通过 codex 命令完成代码理解、修改、解释和任务执行。本文只介绍 Codex CLI 的安装与中转站切换。

与 Codex IDE 的区别

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

• 准备信息
• 安装 Codex CLI
• 推荐方式：用 CC-Switch 切换中转站
  • 1. 打开 Codex 标签页
  • 2. 填写 CLI 配置
  • 3. 启用并重启 CLI
• 备用方式：手动配置 CLI
  • 配置目录
  • config.toml
  • auth.json
• 启动 Codex CLI
• 常见问题

准备信息

配置项	填写内容
Node.js / npm	用于安装 @openai/codex 命令行工具
Base URL	https://www.potatoai.cc/v1
API Key	PotatoAI.cc 控制台创建的 codex 令牌组密钥
Model	模型广场或控制台展示的完整模型 ID
切换工具	推荐使用 CC-Switch

命令行专用定位

Codex CLI 的入口是终端命令 codex。它不是 Cursor、Trae，也不是 Codex IDE/桌面软件。

安装 Codex CLI

先安装 Node.js，然后通过 npm 安装 Codex CLI。

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 权限提示

如果 Linux 环境提示 npm 全局安装权限不足，可以根据你的 Node.js 安装方式调整 npm 全局目录，或临时使用 sudo npm install -g @openai/codex@latest。

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

Codex CLI 的中转站切换也推荐在 CC-Switch 中完成。这样可以在官方配置、PotatoAI.cc 配置和其他提供商之间快速切换。

1. 打开 Codex 标签页

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

2. 填写 CLI 配置

配置项	建议值
配置名称	例如 PotatoAI Codex CLI。
Base URL	https://www.potatoai.cc/v1。
API Key	使用 codex 令牌组的专用密钥。
Model	从模型广场复制完整模型 ID，例如 gpt-5.4。仅在该模型出现在当前分组列表中时使用。
其他参数	按需调整推理强度、网络访问、沙箱模式和审批策略。

3. 启用并重启 CLI

1. 在 CC-Switch 中将该配置标记为 当前使用。
2. 关闭所有正在运行的 Codex CLI 会话。
3. 重新进入项目目录并运行 codex。

托盘切换

CC-Switch 托盘菜单也可以切换 Codex CLI 配置。切换后请重新启动当前终端中的 codex 会话。

备用方式：手动配置 CLI

如果不使用 CC-Switch，可以手动创建 Codex CLI 配置文件。

配置目录

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" # 请替换为控制台展示的完整模型 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

沙箱模式建议

workspace-write 更适合日常项目使用。只有在可信项目中，并且明确需要更高权限时，才考虑放宽沙箱模式。

auth.json

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

不要泄露密钥

不要把 auth.json 或 API Key 提交到 Git 仓库，也不要把完整 Key 发给他人排查问题。

启动 Codex CLI

在你的项目目录中运行：

codex

首次测试可以发送一个简单任务，例如：

请总结这个项目的目录结构，并指出主要入口文件。

如果 Codex 能正常返回，说明 CLI 已经通过 PotatoAI.cc 中转站连接成功。

常见问题

Codex CLI 和 Codex IDE 应该看哪一页？

终端命令 codex 看本页；图形界面、桌面软件或 IDE 集成看 Codex IDE。

为什么切换配置后还是旧中转站？

关闭当前 codex 会话，重新打开终端并再次运行 codex。CLI 通常在启动时读取配置。

Codex CLI 可以使用 Claude Code 令牌吗？

不建议。Codex CLI 应使用 codex 令牌组的专用 Key，Claude Code 使用独立令牌组。

提示模型不存在怎么办？

到模型广场筛选当前 codex 令牌组，复制可用模型列表中的完整模型 ID，确保大小写、版本号和符号完全一致。