文档/接入指南

通过 CC Switch 统一供应商配置 Codex

关于本文档

本文档说明如何使用 CC Switch 的统一供应商（Universal Provider）功能，将 OpenAI Codex 命令行工具接入指定的 API 网关，并使配置生效。

适用版本：CC Switch v3.16.x 及以上。

信息来源：CC Switch 官方仓库的用户手册与源代码。软件迭代较快，若产品界面与本文描述不一致，以应用内实际显示为准。

术语说明

术语 说明
Codex OpenAI 提供的命令行 AI 编程助手。安装后在终端中运行 codex 命令启动。
CC Switch 跨平台桌面配置管理工具，用于管理 Codex、Claude Code、Gemini CLI 等工具的服务端点与凭据。CC Switch 本身不提供 AI 能力，仅负责生成和切换配置文件。
供应商（Provider） 提供模型推理能力的服务方，可以是模型厂商官方服务，也可以是自建或采购的 API 网关。
API Key 用于身份验证的密钥字符串，通常以 sk- 开头。
统一供应商（Universal Provider） CC Switch 的一项功能。一份配置可同时同步至 Claude Code、Codex 和 Gemini CLI 三个工具，适用于同时支持多种 API 协议的网关（例如 NewAPI）。
应用专属供应商 仅作用于单个工具的供应商配置，与统一供应商相对。

开始之前

系统要求

操作系统 最低版本 架构
Windows Windows 10 x64
macOS macOS 12 (Monterey) Intel (x64) / Apple Silicon (arm64)
Linux Ubuntu 22.04 / Debian 11 / Fedora 34 及同等版本 x64 / ARM64

此外还需要 Node.js 18 或更高版本。安装步骤见"任务 1"。

需要预先获取的信息

在开始配置之前，请从 API 服务提供方获取以下四项信息。缺少任何一项都无法完成配置。

项目 说明 示例
API 地址（Base URL） 网关的服务地址 https://seedrouter.net
API Key 身份验证密钥 sk-xxxxxxxxxxxx
模型名称 Codex 侧使用的模型标识 gpt-5.6-sol
协议支持情况 网关是否支持 OpenAI Responses 协议 支持 / 不支持

要点：第四项决定本文档是否适用。统一供应商为 Codex 生成的配置中，通信协议固定为 wire_api = "responses"，不可修改。如果网关不支持 Responses 协议、仅支持 Chat Completions 协议，则不能使用统一供应商，请改用"故障诊断"章节中的方案 F。

打开终端

本文档多处需要在终端中执行命令。打开终端的方法如下：

  • Windows：按 Win + R，输入 powershell，按 Enter 键。
  • macOS：按 Command + 空格，输入 terminal，按 Enter 键。
  • Linux：使用发行版自带的终端应用程序。

任务 1：安装 Node.js

关于此任务

Codex 通过 Node.js 的包管理器 npm 分发。即使采用 CC Switch 的一键安装方式，仍需先具备 Node.js 运行环境。

过程

  1. 访问 Node.js 官方网站。

  2. 下载标注为 LTS（长期支持版）的安装包。请勿下载 Current 版本。

  3. 运行安装程序，按默认选项完成安装，无需修改任何配置项。

    macOS 用户如已安装 Homebrew，也可在终端中执行 brew install node。

  4. 关闭当前所有终端窗口，重新打开一个新的终端窗口。

  5. 依次执行以下命令验证安装：

    node --version
      npm --version

结果

两条命令均输出版本号（例如 v22.14.0 和 10.9.2），且 Node.js 版本不低于 v18，表示安装成功。

注：如果提示"不是内部或外部命令"或"command not found"，通常是因为未重新打开终端窗口。新安装的命令只在新开的终端会话中生效。

任务 2：安装 CC Switch

关于此任务

CC Switch 为免费开源软件，仅通过以下两个渠道分发：

警告：任何要求付费、充值或索取账号登录凭据的"CC Switch"网站或客户端均非官方渠道，请勿下载和使用。

过程

Windows

  1. 打开 GitHub 发布页，在最新版本条目下的 Assets 区域中找到 CC-Switch-v3.16.x-Windows.msi。

  2. 下载并双击运行安装程序，按提示完成安装。

    如果双击后没有任何反应，说明文件被系统安全策略锁定。请右键单击该文件，选择 属性，在 常规 选项卡底部的 安全 区域勾选 解除锁定，单击 确定 后重新运行。

    如不希望安装到系统，也可下载 CC-Switch-v3.16.x-Windows-Portable.zip 免安装版本，解压后直接运行 CC-Switch.exe。

macOS

采用以下任一方式：

  • 方式一（已安装 Homebrew 时推荐）：在终端中执行

    brew install --cask cc-switch

  • 方式二：下载 CC-Switch-v3.16.x-macOS.dmg，双击打开后将 CC Switch 图标拖入"应用程序"文件夹。

    注：macOS 版本已通过 Apple 代码签名与公证，可直接安装并打开，不会出现"无法验证开发者"提示，无需执行额外的解除隔离操作。

Linux

根据发行版选择：

  • Debian / Ubuntu：下载 .deb 包后执行

    sudo dpkg -i CC-Switch-v3.16.x-Linux-*.deb
      sudo apt-get install -f

  • Arch Linux：paru -S cc-switch-bin

  • 其他发行版：下载 .AppImage，执行 chmod +x 添加执行权限后直接运行。

结果

启动 CC Switch 后，主窗口正常显示，且系统托盘区（Windows 位于右下角，macOS 位于菜单栏右侧）出现 CC Switch 图标，表示安装成功。

首次启动时如提示导入现有 CLI 工具配置，建议选择导入。该操作会将当前已有配置保存为一个默认供应商，不会造成配置丢失。

任务 3：安装 Codex

关于此任务

可以通过 CC Switch 图形界面安装，也可以使用命令行安装。首次使用者建议采用方式 A。

过程

方式 A：通过 CC Switch 安装（推荐）

  1. 启动 CC Switch。

  2. 依次进入 设置 > 关于。

  3. 在 本地环境检查 区域中查看 Codex 一行的状态。

  4. 如显示未检测到，单击该行右侧的 安装 按钮。

    安装过程在后台静默执行，按钮上显示进度，完成后自动刷新版本号。

注：后续升级同样在此界面完成。检测到新版本时可单独升级，也可单击 全部升级 批量处理。

方式 B：通过命令行安装

  1. 打开终端。

  2. 执行以下命令：

    npm install -g @openai/codex

    如下载速度过慢，可改用镜像源：

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

    如需长期使用镜像源，可先执行一次以下命令进行全局设置：

    npm config set registry https://registry.npmmirror.com

结果

关闭并重新打开终端后，执行以下命令：

codex --version

输出版本号表示安装成功。

注：此时尚未完成供应商配置，直接运行 codex 会因缺少有效凭据而报错，属于预期行为。配置在任务 4 中完成。

任务 4：创建统一供应商

关于此任务

本任务在 CC Switch 中创建一份统一供应商配置，并将其同步至 Codex 的供应商列表。

过程

  1. 启动 CC Switch。

  2. 在顶部应用切换器中切换至 Codex。

    切换至 Claude 或 Gemini 面板同样可以进入统一供应商入口，三者共用同一配置。

  3. 单击右上角的 ＋ 按钮，打开添加供应商面板。

  4. 在面板顶部选择 统一供应商 选项卡。

    限制：OpenCode、OpenClaw、Hermes 和 Claude Desktop 面板不支持统一供应商，在这些面板下不显示该选项卡。如未看到该选项卡，请先切换至 Claude、Codex 或 Gemini 面板。

  5. 单击 添加统一供应商。

  6. 按下表填写表单字段：

    字段 填写说明
    选择预设类型 网关为 NewAPI 时选择 NewAPI；其他情况或不确定时选择 自定义网关。两者字段完全相同，仅默认值不同。
    名称 自定义的标识名称，例如 NewAPI 网关。该名称将显示在 Codex 供应商卡片上。
    API 地址 填入预先获取的 Base URL。填写规则参见下文"API 地址的处理规则"。
    API Key 填入预先获取的密钥。可单击右侧眼睛图标切换明文显示。
    官网地址 可选。填写后可从供应商卡片直接跳转。
    备注 可选。建议记录密钥来源与有效期等信息。
    启用的应用 包含 Claude Code、OpenAI Codex、Gemini 三个开关。必须打开 OpenAI Codex。如该网关同时供其他两个工具使用，可一并打开。
    模型配置 > Codex > 模型 填入预先获取的模型名称，例如 gpt-5.6-sol。
    模型配置 > Codex > Reasoning Effort 推理强度，取值为 low、medium 或 high。无特殊要求时填写 high。

    注：统一供应商表单不提供"获取模型"按钮，模型名称必须手动填写且区分大小写。

  7. 单击 添加。

结果

界面提示"统一供应商已添加并同步"。此时 CC Switch 已在 Codex 的供应商列表中生成一张同名供应商卡片；如勾选了其他应用，也会在对应列表中生成卡片。

要点：同步不等于启用。此时配置尚未写入 Codex 的运行配置文件，必须继续执行任务 5。

API 地址的处理规则

CC Switch 在为 Codex 生成配置时，会对填入的 API 地址进行如下处理：

填入的地址形式 处理结果
纯域名，不含路径，例如 https://seedrouter.net 自动补全为 https://seedrouter.net/v1
已以 /v1 结尾，例如 https://seedrouter.net/v1 原样使用
含其他路径，例如 https://api.example.com/openai 原样使用，不补全 /v1

判定标准为：处理后的地址加上 /responses 后，必须是网关实际可用的接口路径。填写前建议向服务提供方确认完整的接口地址，再依据上表反推应填入的内容。地址不正确将导致请求返回 404。

任务 5：启用供应商并使配置生效

关于此任务

供应商卡片生成后需手动启用，配置才会写入 Codex 的配置文件。Codex 不支持配置热重载，启用后必须重启终端。

过程

  1. 关闭添加供应商面板。

  2. 在顶部应用切换器中切换至 Codex。

  3. 在供应商列表中找到任务 4 中创建的同名卡片。

  4. 单击卡片上的 启用 按钮。

    卡片显示为蓝色边框并带有"当前启用"标签，表示配置已写入。

  5. 完全关闭当前终端窗口，然后重新打开一个新的终端窗口。

    要点：此处指关闭整个终端窗口，而非退出 codex 进程后重新运行 codex 命令。各工具的生效方式差异如下：

    工具 切换供应商后的生效方式
    Claude Code 即时生效，支持热重载
    Gemini CLI 即时生效，每次请求重新读取配置
    Codex 需关闭并重新打开终端
    OpenCode / OpenClaw 需关闭并重新打开终端

  6. 在新终端中执行：

    codex

  7. 启动后输入一句测试内容，例如"你好，请简单介绍一下自己"。

结果

模型正常返回应答，表示配置完成，Codex 已接入指定网关。

参考：生成的配置文件

CC Switch 遵循最小侵入原则。启用供应商后，配置直接写入 Codex 自身的配置文件；即使卸载 CC Switch，Codex 仍可继续正常工作。

涉及的文件如下。路径中的 ~ 表示当前用户目录，Windows 下为 C:\Users\<用户名>\，macOS 与 Linux 下为 /Users/<用户名>/ 或 /home/<用户名>/。

~/.codex/auth.json — 存储凭据：

{
        "OPENAI_API_KEY": "<API Key>"
      }

~/.codex/config.toml — 存储模型与端点配置：

model_provider = "cliproxyapi"
      model = "gpt-5.6-sol"
      model_reasoning_effort = "max"
      sandbox_mode = "workspace-write"
      model_context_window = 372000
      model_auto_compact_token_limit = 334800
      model_auto_compact_token_limit_scope = "total"
      service_tier = "priority"
      
      [model_providers.cliproxyapi]
      name = "SeedRouter"
      base_url = "https://seedrouter.net/v1"
      wire_api = "responses"
      requires_openai_auth = true
      experimental_bearer_token = "sk-xxxxxxxxxx"

CC Switch 自身的数据存储于 ~/.cc-switch/ 目录下，其中数据库文件为 cc-switch.db，自动备份位于 backups/ 子目录，保留最近 10 份。

维护操作

修改配置

修改 API Key、模型名称或服务地址时：

  1. 单击 ＋ 按钮，切换至 统一供应商 选项卡。

  2. 在目标卡片上单击编辑图标。

  3. 修改相应字段。

    编辑模式下表单底部提供 配置 JSON 预览 区域，可在同步前确认将写入各应用的实际内容。

  4. 单击 保存并同步。

  5. 在确认对话框中确认操作。该操作将覆盖 Claude、Codex 和 Gemini 中关联的供应商配置。

  6. 关闭并重新打开终端。

供应商卡片操作说明

操作 说明
同步 手动将当前配置重新推送至各关联应用，用于配置不一致时的修复。
复制 基于当前配置创建一份副本，便于配置备用密钥。
编辑 修改配置内容。
删除 删除统一供应商，同时删除其在 Claude、Codex、Gemini 中生成的关联供应商卡片。

快速切换

右键单击系统托盘中的 CC Switch 图标，在 Codex 子菜单中直接单击目标供应商名称即可切换，无需打开主界面。切换后同样需要重启终端。

故障诊断

A. 返回 401 或 403 认证失败

可能原因 解决方案
API Key 复制时包含多余的空格或换行符 重新复制并粘贴，注意选取范围
API Key 已过期或额度耗尽 向服务提供方确认密钥状态
API Key 与 API 地址不匹配 核对二者是否来自同一服务

B. 返回 404 或提示接口不存在

多数情况下是 API 地址处理后不正确。请参照"任务 4 > API 地址的处理规则"重新核对，并向服务提供方确认完整的接口地址。

C. 修改配置后无任何变化

未重启终端。请完全关闭终端窗口后重新打开。这是 Codex 使用过程中最常见的问题。

D. 界面顶部显示环境变量冲突警告

系统中存在 OPENAI_API_KEY 等环境变量。环境变量的优先级高于配置文件，会覆盖 CC Switch 写入的配置，导致请求发送至错误的端点或使用错误的密钥。

处理步骤：

  1. 单击警告横幅上的 展开，查看冲突变量的名称、取值与来源。
  2. 勾选需要删除的变量，或单击 全选。
  3. 单击 删除选中 并确认。

CC Switch 在删除前会自动备份至 ~/.cc-switch/env-backups/，如需恢复可从该目录中的 JSON 文件手动还原。

E. 终端提示 codex 命令不存在

可能原因 解决方案
安装后未重新打开终端 关闭全部终端窗口后重新打开
Node.js 未正确安装 返回任务 1，验证 npm --version 是否正常输出
npm 全局目录未加入 PATH 使用 CC Switch 的 设置 > 关于 > 本地环境检查 重新安装

F. 网关仅支持 Chat Completions 协议

统一供应商的通信协议固定为 Responses，此场景下不适用，须改用应用专属供应商。

  1. 在 CC Switch 中切换至 Codex 面板，单击 ＋ 按钮。
  2. 保持在左侧的 Codex 供应商 选项卡，不要切换至统一供应商。
  3. 在预设下拉框中选择对应的服务商。DeepSeek、智谱 GLM、Kimi、MiniMax、StepFun、百炼、ModelScope、硅基流动、豆包 Seed、小米 MiMo、Novita AI 等均属于 Chat Completions 类预设。
  4. 选择此类预设后，CC Switch 会自动开启"需要本地路由映射"开关并配置模型映射表，由本地代理完成协议转换，无需手动设置。
  5. 填写 API Key，单击 添加，随后启用该供应商并重启终端。

G. 需要恢复为官方账号登录

  1. 在 Codex 面板中添加"OpenAI 官方"预设的供应商。
  2. 启用该供应商并重启终端。
  3. 按 Codex 自身的登录流程完成认证。

完成后可在官方登录与第三方供应商之间自由切换。

选型参考：统一供应商与应用专属供应商

使用场景 建议方案
单一网关同时服务 Claude Code、Codex 和 Gemini CLI，且支持 Responses 协议 统一供应商
仅使用 Codex 一个工具 二者皆可，应用专属供应商配置路径更短
网关仅支持 Chat Completions 协议 应用专属供应商，配合内置预设
各工具接入不同的服务方 应用专属供应商，分别配置
需要配置 OpenCode、OpenClaw 或 Hermes 应用专属供应商，这三个工具不支持统一供应商

安全注意事项

  1. API Key 具有与账号凭据同等的敏感性。请勿在即时通讯工具中传递、截图分享，或提交至代码仓库。
  2. 仅从 CC Switch 官网或官方 GitHub 仓库获取 CC Switch 安装包。
  3. 设备变更或怀疑密钥泄露时，应立即更换密钥。
  4. CC Switch 的配置导出功能会将全部供应商信息以明文形式写入 .sql 备份文件。导出的文件应妥善保管，避免存放于共享目录。

快速参考

1. 安装 Node.js               nodejs.org，选择 LTS 版本
      2. 安装 CC Switch             ccswitch.io 或 GitHub Releases
      3. 安装 Codex                 CC Switch > 设置 > 关于 > 本地环境检查 > 安装
      4. 创建统一供应商             切换至 Codex 面板 > ＋ > 统一供应商 > 添加统一供应商
                                    填写名称、API 地址、API Key
                                    打开 OpenAI Codex 开关，填写模型名称
      5. 启用供应商                 Codex 面板 > 目标卡片 > 启用
      6. 重启终端                   完全关闭终端窗口后重新打开
      7. 验证                       执行 codex 命令并发送测试消息

提交问题反馈时，请一并提供完整的错误信息截图，以及在任务 4 中填写的 API 地址（密钥部分需脱敏），以缩短排查周期。

获取 SeedRouter API Key 返回文档首页