V3 Codex 安装与配置指南

本页目录

开始前先看：3 步最简路径兑换流程：先兑换，再获取 API Key 适合谁读不适合谁读 Codex 和 Claude Code 的关键区别配置前确认方法 1（推荐）：使用 CC switch 配置常见错误

这篇只适用于 V3 + Codex。不要拿这篇配置 Claude Code，也不要拿这篇配置二合一。

开始前先看：3 步最简路径

不要一打开客户端就找 API Key，按下面顺序做：

兑换（如果还没有兑换）：V3 的兑换码先在 V3 后台兑换；二合一不要去 V3 兑换，订单里的 cr-... 卡密直接作为 API Key。
新建 API Key，并选择分组：V3 打开 https://v3.codesome.cn/dashboard，进入“API 密钥”并创建 sk-... Key；按要使用的模型选择具体分组——Claude 使用 Kiro 来源时选择 lite 或 pro，使用 Max 来源时选择当天后台可用的具体 Max 分组；Codex/GPT 选 codex，Grok 选 grok，月卡选择对应月卡/订阅分组。二合一直接使用 cr-... Key，不在 V3 创建或选择分组。
安装并配置到客户端：先安装 Codex CLI 或桌面版，再按本文选择 CC Switch 或 WSL/终端方式，填入 sk-... Key、请求地址和 Codex 分组，完成后新建会话验证。

下面展开第 1 步的兑换细节；已经有可用 API Key 的用户可以直接跳到客户端配置部分。

兑换流程：先兑换，再获取 API Key

如果你还没有 API Key，先完成下面的兑换流程。兑换码不是 API Key：V3 兑换码要先兑换，再到“API 密钥”页面创建 sk-... Key；二合一的 cr-... 卡密则直接作为 API Key，不要去 V3 兑换。如果你已经有对应的可用 Key，可直接跳到本文后面的客户端配置步骤。完整兑换说明也可以查看cc兑换码兑换指南。

基本兑换步骤

1、登录 v3.codesome.cn（cc.codesome.ai 是同一个网站，.cn 登录不了就登录.ai）

2、注册后，在兑换区输入兑换码，入口：https://v3.codesome.cn/redeem

3、新人福利 3 美金兑换码可以加微信领取，微信oops0731111（口号：领新人福利）

codesome

付款后卡密在哪里

打开下单站点：

https://meta.codesome.cn

使用下单时注册的新站账号登录（新站账号与老站账号不通用），进入订单详情查看并保存卡密。老站已下单但尚未兑换的订单，联系客服处理。

兑换规则：一次一个、只贴纯卡密

一次只能输入并兑换一个兑换码，不能一次粘贴多个，也不能粘贴多个码之间加空格或换行。
不要使用下单页面带说明文字的一键复制内容，它可能包含“二合一卡密：xxxx”这类中文前缀。输入框里只能是纯卡密，不含中文、空格和换行。
页面显示“兑换成功”即表示卡密已生效。

兑换失败怎么排查

提示卡密无效、已使用或兑换失败时，按顺序检查：

确认输入框里只有一个卡密。
清空输入框，重新手动粘贴纯卡密（去掉中文前缀、空格和换行）后再次提交。
确认你买的是 V3 产品（Claude 月卡、GPT 月卡、V3 按量）而不是二合一——二合一的 cr 开头卡密不在本站兑换。

仍失败时联系客服，并提供打码后的页面截图（保留报错信息）和兑换时间；截图请隐藏完整卡密、API Key、邮箱、订单号等身份信息。

兑换成功后在哪里确认到账

V3 按量：在 V3 后台“余额”处查看。
Claude 月卡 / GPT 月卡：在 V3 后台“订阅”页面查看。
随后进入“API 密钥”页面创建 Key，再按对应客户端教程配置。
二合一（V5）：订单里的 cr 开头卡密直接作为 API Key 使用，不会显示在 V3 余额里，也不要到 V3 兑换。

已显示兑换成功但余额或订阅没更新时，先刷新页面；仍无变化再联系客服。

适合谁读

你要使用 Codex CLI。
你要使用 Codex 桌面版，但还没完成 CLI 配置。
你买的是 V3 / 普通 Codesome API / V3 Codex 月卡或按量。
你已经创建了 V3 API Key，常见形态是 sk-...。

不适合谁读

你的情况	应该看
要配置 V3 Claude Code	V3 Claude Code 安装与配置指南
使用二合一月卡，key 是 `cr-...`	二合一 Codex 安装与配置指南
已经报错	使用问题速查

Codex 和 Claude Code 的关键区别

工具	常见配置
Claude Code	`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`
Codex	`CODESOME_API_KEY`、`~/.codex/config.toml`

如果你正在配置 Codex，不要照 Claude Code 教程写 ANTHROPIC_*。

配置前确认

已经在 V3 后台兑换成功。
已经创建 sk-... API Key。
API Key 分组适合 Codex。
你知道自己是在 Windows、macOS 还是 WSL 里配置。
如果使用桌面版，也要先完成 CLI 配置。

V3 Codex 核心配置：

base_url=https://cc.codesome.ai/v1
env_key=CODESOME_API_KEY

方法 1（推荐）：使用 CC switch 配置

方法 1 是唯一的配置流程：用 CC switch 管理请求地址、API Key、模型和本地代理配置，下面按系统同时提供 Codex CLI 的安装与验证步骤。CC switch 图形客户端支持 Windows 和 macOS；WSL 仅保留 CLI 安装步骤，CC switch 配置需在 Windows 或 macOS 中完成。

Windows

前往 https://github.com/farion1231/cc-switch/releases 下载最新版本，选择对应的 .msi 安装包。

安装完成后，登录 Codesome V3 后台，打开 https://v3.codesome.cn/keys 获取对应 key。月卡订阅要切换到月卡分组；按量额度要切换到 Codex 分组。

V3 后台创建或复制 key

打开 ccswitch 主界面，点击右上角加号，创建供应商：

供应商名称填 codesome
API Key 填你在 V3 后台获得的 sk-... key
请求地址填 https://cc.codesome.ai/v1
模型名称填 gpt-5.6-terra

ccswitch 创建供应商

ccswitch 填写 V3 Codex 配置

安装并验证 Codex CLI

CC switch 配置完成后，还要安装 codex 命令。已经安装过 Codex 的用户可直接执行 codex --version，无需重复安装。

安装 Node.js：

https://nodejs.org/en/download

安装完成后，在 PowerShell 验证：

node -v
npm -v

安装 Codex：

npm i -g @openai/codex

如果下载慢，可以使用镜像：

npm i -g @openai/codex --registry=https://registry.npmmirror.com

验证：

codex --version

macOS

macOS 用户可以先执行：

brew tap farion1231/ccswitch
brew install --cask cc-switch

如果命令运行失败，前往 https://github.com/farion1231/cc-switch/releases，下载后缀是 .dmg的版本。

macOS 在启动台选择 cc-switch 后，如果因为安全性问题无法打开，需要去：设置 → 隐私与安全 → 安全性，允许信任当前开发者。

macOS 允许打开 cc-switch

安装完成后，登录 Codesome V3 后台，打开 https://v3.codesome.cn/keys 获取对应 key。月卡订阅要切换到月卡分组；按量额度要切换到 Codex 分组。

V3 后台创建或复制 key

打开 ccswitch 主界面，点击右上角加号，创建供应商：

供应商名称填 codesome
API Key 填你在 V3 后台获得的 sk-... key
请求地址填 https://cc.codesome.ai/v1
模型名称填 gpt-5.6-terra

ccswitch 创建供应商

ccswitch 填写 V3 Codex 配置

安装并验证 Codex CLI

CC switch 配置完成后，还要安装 codex 命令。已经安装过 Codex 的用户可直接执行 codex --version，无需重复安装。

安装 Node.js：

https://nodejs.org/en/download

安装完成后，在终端验证：

node -v
npm -v

安装 Codex：

npm i -g @openai/codex

如果下载慢，可以使用镜像：

npm i -g @openai/codex --registry=https://registry.npmmirror.com

验证：

codex --version

WSL

WSL 没有 CC switch 图形客户端。若你需要在 WSL 中安装 Codex CLI，可按下面步骤完成；CC switch 配置需在 Windows 或 macOS 中完成。

安装并验证 Codex CLI

在 Windows PowerShell 输入：

wsl

安装 Node.js：

sudo apt update
sudo apt install -y curl
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm alias default 'lts/*'

验证：

node -v
npm -v

安装 Codex：

npm i -g @openai/codex

Codex 桌面版

Codex 桌面版通常依赖 CLI。先完成本文的 CC switch 配置和 CLI 安装，再安装并打开桌面客户端。

下载地址

打开官方 Codex 桌面客户端下载页：

https://developers.openai.com/codex/app

CC switch 配置和 CLI 安装完成后，打开 Codex 桌面客户端会看到类似界面。

Codex 桌面客户端界面

使用顺序

先按本文完成 CC switch 配置和 Codex CLI 安装。
确认终端里执行 codex 可以正常进入并回复。
打开安装包文档或官方下载地址，安装 Codex 桌面客户端。
安装完成后打开桌面客户端。
如果桌面版没有生效，退出后台进程后重新打开。

注意事项

桌面版不是单独配置一套 Codesome；它通常读取本机 CLI 相关配置。
如果 CLI 没配好，桌面版大概率也不能正常使用。
如果你在 Windows / macOS / WSL 之间切换环境，先确认桌面版实际读取的是哪一套配置。

常见错误

如果严格按本文配置后仍出现 503，请先回到 CC switch 的模型选择处，选择界面中正确显示的模型 ID gpt-5.6-terra，不要选择“自定义”。
用 Claude Code 的 ANTHROPIC_* 配置 Codex。
~/.codex/config.toml 不存在或写错。
V3 base_url 少了 /v1。
桌面版没重启。
用二合一 cr-... key 或 v5 地址配置了这篇 V3 教程。

遇到报错，去看：

使用问题速查：报错、账单与配置排查