Codex 部署指南

文档目的

本文档整理了 Windows 环境下 Node.js、Git Bash、nvm-windows、CC Switch、Claude Code 与 Codex 的下载、安装、模型供应商配置和常见问题处理步骤。

• 先安装基础环境：Node.js、Git Bash、nvm-windows。
• 再安装并配置 CC Switch，用于统一管理 Claude Code / Codex 的模型供应商。
• 最后分别完成 Claude Code 与 Codex 的配置，并通过测试确认模型可用。
• API Key 属于敏感信息，文档中统一使用 <YOUR_API_KEY> 占位，实际使用时替换为后台创建的 Key。

下载与安装清单

以下四个组件可以一起下载，如果有过Codex和Claude code安装记录的，大部分只需要下载一个ccswitch便于部署

基础环境下载

Node.js

官方下载：https://nodejs.org/zh-cn/download

在下载页面选择 Windows 安装包（.msi）。原截图中标注的是 “Windows 安装程序（.msi）”。

验证安装命令：node --version

npm --version

Git Bash

官方下载：https://git-scm.com/downloads/win

国内加速下载：https://static.itssx.com/f/kjHz/Git-2.53.0-64-bit.exe

国内加速下载（Cloudflare）：https://staticacc.itssx.com/f/kjHz/Git-2.53.0-64-bit.exe

验证安装指令：git --version

nvm-windows

官方下载页：https://github.com/coreybutler/nvm-windows/releases

进入 Releases 页面后，下载 nvm-setup.exe。

加速下载：https://static.itssx.com/f/x7FY/nvm-setup.exe

加速下载（Cloudflare）：https://staticacc.itssx.com/f/x7FY/nvm-setup.exe

验证安装指令：nvm install lts
nvm use lts

CC Switch 下载与配置

CC Switch v3.14.1 下载页：https://github.com/farion1231/cc-switch/releases/tag/v3.14.1

滚动到页面底部的 Assets 区域，选择 Windows x64 的 .msi 安装包。

Codex 安装与配置

安装 Codex CLI

确认 Node.js / npm 已安装后，在终端执行：

npm install -g @openai/codex@latest

这条命令安装的是 Codex CLI。建议先配置并熟悉 Codex CLI，再继续安装或使用 Codex 桌面版。

Codex 供应商配置要点

• Codex 的整体环境配置与 Claude 类似。
• Codex 的 API 请求地址需要使用带 /v1 的地址：https://ccg-cli.online/v1
• 模型名仍需填写后台实际支持的模型名，原文档示例为 gpt-5.5。

Codex config.toml 示例

Codex 最常见的问题是配置文件格式或旧配置残留。可将 config.toml 中供应商相关部分整理为下面结构：

model_provider = "newapi"
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
disable_response_storage = true
[model_providers]
[model_providers.newapi]
name = "GPT-5.5 API"
base_url = "https://ccg-cli.online/v1"
wire_api = "responses"
requires_openai_auth = true

注意：截图中出现的 [projects...]、trust_level、用户目录和项目路径属于本机环境配置，不建议直接复制到其他电脑。

常见问题处理

Codex 无法正常调用模型

• 检查 Codex 的 base_url 是否为 https://ccg-cli.online/v1，不要漏掉 /v1。
• 检查 wire_api 是否为 responses。
• 检查 requires_openai_auth 是否为 true。
• 检查 model_provider 是否与 [model_providers.newapi] 的名称对应。

Codex 项目不显示或旧配置异常

• 如果之前安装过 Codex，旧的项目路径、沙箱或信任配置可能影响显示。
• 处理前先备份 config.toml。
• 保留供应商配置，删除或重新生成与旧项目路径、sandbox、trust_level 相关的本机专属配置。

Codex 自身满载问题

• 出现输入后没有返回，且有以下报错Selected model is at capacity.Please try a different model.这个是Open Ai官方满载问题，不属于中转站本身问题，0重启一下codex就好。

最终检查清单

• Node.js / npm 已安装，npm 命令可用。
• Git Bash 已安装。
• nvm-windows 已安装（如需要多版本 Node 管理）。
• CC Switch 已安装。
• Claude 供应商请求地址为 https://ccg-cli.online。
• Codex 供应商请求地址为 https://ccg-cli.online/v1。
• API Key 已替换为真实 Key，未写入公开文档。
• 模型名与后台可用模型一致。
• Codex config.toml 中没有直接复制他人电脑的项目路径配置。

部署目标

本方案用于在 macOS 上完成 Codex CLI 的基础部署，确保终端重启后 nvm、node、npm、codex 均可正常使用，并通过 Codex 配置文件接入第三方 API 服务。

部署完成后应达到以下状态：

git --version 可以输出 Git 版本。
nvm --version 可以输出 nvm 版本。
node -v、npm -v、npx -v 可以输出版本。
codex --version 可以输出 Codex CLI 版本。

• 在项目目录执行 codex 后，可以读取第三方 API 配置并正常发起请求。

前置条件

• 一台可联网的 Mac。
• 已打开系统自带 Terminal 终端。
• 已准备第三方 API 的 base_url、模型名称和 API Key。
• 知道当前 shell 类型；macOS 常见为 /bin/zsh，少数环境为 /bin/bash。

查看当前 shell：

echo $SHELL

安装 Git

macOS 推荐通过 Xcode Command Line Tools 安装 Git。

xcode-select --install

安装完成后验证：

git --version

安装 nvm、Node.js 和 npm

npm 会随 Node.js 一起安装，不需要单独安装。建议通过 nvm 管理 Node.js 版本。

安装 nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

配置终端启动脚本

如果当前 shell 是 zsh，执行：

touch ~/.zshrc
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"' >> ~/.zshrc
echo '[ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"' >> ~/.zshrc
source ~/.zshrc

如果当前 shell 是 bash，执行：

touch ~/.bashrc ~/.bash_profile
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.bashrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"' >> ~/.bashrc
echo '[ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"' >> ~/.bashrc
echo '[[ -f ~/.bashrc ]] && . ~/.bashrc' >> ~/.bash_profile
source ~/.bash_profile

安装并设置默认 Node.js LTS 版本

nvm install --lts
nvm alias default 'lts/*'
nvm use default

验证：

nvm --version
node -v
npm -v
npx -v

安装 Codex CLI

确认 node 和 npm 正常后，通过 npm 全局安装 Codex CLI。

npm i -g @openai/codex@latest

验证安装：

codex --version

配置 Codex 使用第三方 API

创建配置目录

mkdir -p ~/.codex

编辑 Codex 配置

nano ~/.codex/config.toml

填入以下内容；其中 model、provider 名称、base_url 与 env_key 可按第三方服务要求调整：

model = "gpt-5.5"
model_provider = "ccg"
[model_providers.ccg]
name = "ccg-cli"
base_url = "https://ccg-cli.online/v1"
env_key = "CCG_API_KEY"
wire_api = "responses"
nano 保存方式：

1. Control + O
2. 回车确认文件名
3. Control + X

配置 API Key

根据当前 shell 写入环境变量。zsh 用户执行：

echo 'export CCG_API_KEY="sk-你的新key"' >> ~/.zshrc
source ~/.zshrc

bash 用户执行：

echo 'export CCG_API_KEY="sk-你的新key"' >> ~/.bashrc
source ~/.bash_profile

验证环境变量是否生效：

echo $CCG_API_KEY

启动与验证

进入项目目录后启动 Codex：

codex

也可以先用一句简单 prompt 验证链路：

codex "hello"

常见问题处理

常用排查命令：

cat ~/.zshrc
cat ~/.bash_profile
cat ~/.bashrc
ls -l ~/.nvm/nvm.sh
cat ~/.codex/config.toml
echo $CCG_API_KEY
codex --version

安全建议

• API Key 只写入本机 shell 配置或系统密钥管理工具，不提交到 Git 仓库。
• 不要将 ~/.codex/config.toml、shell 配置文件或终端输出中的敏感内容截图公开。
• 使用第三方中转 API 前，确认其隐私政策、日志保留策略、账单规则和用量限制。
• 多人设备上部署时，建议为 API Key 设置最小权限和额度上限。

部署验收清单

git --version 正常输出。
nvm --version 正常输出。
node -v、npm -v、npx -v 正常输出。

• 关闭并重新打开终端后，上述命令仍然可用。

codex --version 正常输出。

• ~/.codex/config.toml 已配置第三方 provider。
• 环境变量中的 API Key 已生效，且与 config.toml 的 env_key 一致。
• 在项目目录执行 codex 后可以正常发起请求。