从零配置 Codex

准备（Preparation） ​

预留约 10 分钟。需要 CC Switch v3.20.0、已安装的 Codex 客户端，以及一把只给本机 Codex 使用的可撤销 Key。本教程会区分 Codex 原生 OpenAI Responses 路径，以及必须由 CC Switch 本地路由转换的 Chat Completions 或 Anthropic 上游。

修改 Provider 前备份 ~/.codex/auth.json 和 ~/.codex/config.toml。auth.json 保存 API 或登录材料；config.toml 保存 model_provider、顶层 model 和当前 Provider 的 base_url。不要覆盖现有 ChatGPT OAuth 登录或无关的审批、沙箱与工具设置。

下载（Download） ​

从 OpenAI Codex 官方仓库安装 Codex。官方 npm 命令是：

npm install -g @openai/codex

CC Switch 只从官方 v3.20.0 Release下载，并选择与操作系统和处理器架构匹配的资源。不要使用镜像、重打包安装器或其他架构的包。

安装后运行 codex --version。在 CC Switch 打开 关于（About），确认显示 v3.20.0。任一版本检查失败或与下载 Release 不一致时不要继续。

首次启动（First launch） ​

先运行一次 codex，完成 Codex 自己的引导或登录，直到交互提示可用。随后退出 Codex Desktop 和全部 Codex CLI 会话。首次启动会建立原生配置目录；关闭客户端可避免它读取到只写了一半的 Provider 配置。

配置 Provider 前，再次在 CC Switch 关于（About） 确认 v3.20.0；若不一致，停止并安装匹配的官方 Release。

API Key 与分组（API Key and group） ​

在梭子蟹控制台创建一把专用 <API_KEY>，并分配到允许目标端点与模型的分组。ChatGPT 订阅或 OAuth 登录不是 API Key。只记录 Key 标签、分组和创建时间，不记录完整 Key。每台设备使用不同 Key，才能单独撤销某个安装实例。

模型目录：GET /v1/models（Model catalog） ​

修改 CC Switch 前，用同一把 Key 请求 GET https://suoxie.codes/v1/models，从 data[].id 原样复制一个值作为 <MODEL_FROM_V1_MODELS>。这一步只检查 Key、分组和模型可见性，不证明选定的请求协议可用。

Windows PowerShell：

$secureKey = Read-Host 'API key' -AsSecureString
$credential = [System.Net.NetworkCredential]::new('', $secureKey)
$env:SUOXIE_API_KEY = $credential.Password
curl.exe --fail-with-body https://suoxie.codes/v1/models `
  -H "Authorization: Bearer $env:SUOXIE_API_KEY"

macOS / Linux：

read -rsp 'API key: ' SUOXIE_API_KEY && printf '\n'
curl --fail-with-body https://suoxie.codes/v1/models \
  -H "Authorization: Bearer $SUOXIE_API_KEY"

在 CC Switch 配置 Provider ​

在 CC Switch 选择 Codex，点击 +，创建如 suoxie-responses 的 Provider。Base URL 填 https://suoxie.codes/v1，输入专用 Key，并加入 <MODEL_FROM_V1_MODELS>。必须明确选择上游协议：原生 Responses 端点选 OpenAI Responses；Chat Completions 或 Anthropic 则选择对应的路由转换格式。

保存后，CC Switch 把 API 材料写入 ~/.codex/auth.json，把 Provider 选择写入 ~/.codex/config.toml。原生结构应保持以下关系：

model_provider = "suoxie-responses"
model = "<MODEL_FROM_V1_MODELS>"

[model_providers.suoxie-responses]
name = "Suoxie Responses"
base_url = "https://suoxie.codes/v1"
wire_api = "responses"
requires_openai_auth = true

不要给 base_url 追加 /responses，不要建立重复 Provider 表，也不要在 CC Switch 管理切换时手改凭据缓存。

模型映射与协议（Model mapping and protocol） ​

顶层 model_provider 必须与 Provider 表 ID 一致；model 必须与同一把 Key 的 /v1/models 返回完全一致。Responses 原生上游可直连。若上游仅实现 /v1/chat/completions，必须启用 CC Switch 的 Codex 本地路由接管，把 Codex Responses 请求转换为 Chat，再把结果转回。Anthropic 上游同样需要转换路由；Base URL 本身不会改变 Codex 的 wire protocol。

保存、启用与重启（Save, enable, and restart） ​

保存 Provider，在 CC Switch 中设为当前 Codex Provider，并等待写入完成。完全退出 Codex Desktop 和所有 Codex 终端后再启动。Codex 会在进程启动时读取 config.toml 和生成的模型目录；在旧进程中新建聊天不算重启。

原生 Responses 上游继续使用上面的直连 https://suoxie.codes/v1 路径。若上游是 Chat Completions 或 Anthropic，打开 Settings -> Advanced -> Routing Service -> App Routing，先启动 Routing Service，再打开 Codex 应用开关。服务显示运行且 Codex 开关已启用即为成功信号；有效本地转换路由是 http://127.0.0.1:15721/v1。本地路由只用于转换路径，不替代原生 Responses 的直连 Provider。

首个请求（First request） ​

打开一个可丢弃的空目录，运行 codex，确认选中 <MODEL_FROM_V1_MODELS>，只发送 Reply with OK。成功标准是 Codex 经该 Provider 返回简短文本，仅看到 CC Switch Provider 卡片不算成功。

验证后清理临时 shell 变量：

Remove-Item Env:SUOXIE_API_KEY -ErrorAction SilentlyContinue
Remove-Variable secureKey, credential -ErrorAction SilentlyContinue

unset SUOXIE_API_KEY

Key 用量（Key usage） ​

打开 Key 用量，按请求时间、专用 Key、分组、端点和模型筛选，核对请求数、输入/输出 Token 和费用。使用路由 Provider 时，还要确认记录中的上游端点与模型符合路由。重复请求前先刷新并扩大时间范围。

错误处理（Errors） ​

回滚与安全（Rollback and security） ​

停止 Codex，在 CC Switch 重新启用此前验证可用的 Provider，或成对恢复私有的修改前 auth.json 与 config.toml。先恢复旧 Provider 并验证短请求，再关闭 Routing Service 或 Codex 应用开关。CC Switch 状态保存在 ~/.cc-switch/cc-switch.db，备份目录是 ~/.cc-switch/backups/；恢复前保留两者。不要删除唯一凭据备份，也不要从无关快照只恢复其中一个文件。

CC Switch 可能把完整 Key 存入本地客户端配置。配置与备份不得进入公开仓库、共享工单、截图、录屏或云同步目录。确认旧 Provider 的短请求成功后，再撤销本轮临时测试 Key。怀疑泄露时立即撤销该 Key，在正确分组创建替代 Key，更新 CC Switch，重启 Codex，并在 Key 用量中核对一次新请求。