使用 CC Switch 配置 Codex

CC Switch 是一款开源的 AI 编程工具供应商配置管理器。本教程面向第一次使用命令行工具的用户，以 macOS、CC Switch 3.20.0、Node.js 24.14.1 和 Codex CLI 0.149.1 为例，完整演示安装、一键导入 X-AIO 配置、选择模型和首次验证。

Windows 用户请下载 CC Switch 的 Windows 安装程序，并按安装向导完成安装；Node.js 可使用官网安装程序。本教程后续以 macOS 为准。Windows、macOS 以及不同 CC Switch 版本中的按钮位置可能略有差异，但总体步骤相同。

1. 下载并安装 CC Switch（macOS）

从 CC Switch 官方下载页 或 GitHub Releases 下载最新版 macOS .dmg 安装包。本教程实测的 CC-Switch-v3.20.0-macOS.dmg 是同时支持 Apple 芯片和 Intel 芯片的 Universal 安装包。

下载完成后，双击 .dmg 文件，再把 CC Switch 图标拖到 Applications 文件夹。

从“应用程序”中打开 CC Switch。如果 macOS 显示“从互联网下载的 App”提示，请核对应用名称后点击 Open。第一次启动时会看到欢迎窗口，阅读说明后点击 我知道了。

2. 将界面切换为简体中文

本教程中的按钮名称均以简体中文界面为准：

1. 点击 CC Switch 左上角的 设置（齿轮图标）。
2. 打开 通用。
3. 在“界面语言”中选择 简体中文。如果已经选中，可以直接返回。

3. 安装 Homebrew 和 Node.js 24

CC Switch 安装 Codex 时会调用官方 npm 包，因此 macOS 需要先准备 Node.js 和 npm。打开“终端”，按顺序完成下面的步骤。

安装 Xcode Command Line Tools

xcode-select --install

macOS 会弹出安装窗口。按系统提示完成安装；部分步骤可能需要管理员密码。

安装 Homebrew

如果还没有安装 Homebrew，请运行 Homebrew 官网提供的安装命令：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装结束后，终端会显示 Next steps。请逐行执行其中用于把 Homebrew 加入 PATH 的命令；不同 Mac 芯片对应的路径可能不同，不要直接照搬别人的路径。然后验证：

brew --version

通过 Homebrew 安装 Node.js 24

brew install node@24

把 Node.js 24 加入当前用户的 PATH，再重新加载终端配置：

echo 'export PATH="$(brew --prefix node@24)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

最后检查版本：

node --version
npm --version

看到 Node.js v24.x.x 和 npm 版本号就说明准备完成。本教程实测为 Node.js v24.14.1、npm 11.11.0；以后看到更高的小版本也属于正常情况。

4. 在 CC Switch 中安装 Codex

1. 在 CC Switch 中打开 设置 → 关于。
2. 找到“本地环境检查”中的 Codex。
3. 如果“当前版本”显示“未安装”，点击卡片右下角的 安装。
4. 等待安装结束，再点击“本地环境检查”右侧的 刷新。

Codex 卡片出现绿色勾、当前版本和最新版本，就说明安装成功。本教程实测版本为 0.149.1。

CC Switch 安装失败时，可以按 OpenAI Codex CLI 官方文档提供的 npm 方式手动安装，然后回到 CC Switch 刷新：

npm install -g @openai/codex
codex --version

不要在 npm 命令前添加 sudo。如果终端提示没有写入权限，应先修复 Node.js/npm 的安装路径，而不是扩大系统权限。

5. 创建专用 X-AIO API Key

打开 X-AIO API 密钥页面，点击 创建新密钥，然后按下面的示例填写：

1. 密钥用途：CC Switch - Codex。
2. 有效期：90 天。临时设备不建议使用永久密钥。
3. 核对无误后点击 创建密钥。

创建后不需要复制或展示密钥。接下来直接使用 X-AIO 提供的一键接入功能，把配置交给本机 CC Switch。

6. 一键导入 CC Switch

在刚创建的密钥卡片中找到 API Key 右侧的操作区。

在展开的菜单中选择 一键接入 CC Switch（Codex）。不要误选用于 Claude Code 的选项。

Chrome 随后会询问是否打开外部应用。点击 Open CC Switch，让浏览器把配置交给已经安装的 CC Switch；无需勾选 Always allow。

CC Switch 打开“确认导入供应商配置”窗口后，逐项核对：

Codex 使用 OpenAI Responses 兼容接口，因此端点末尾需要保留 /v1。确认无误后点击 导入。

7. 确认启用并选择可用模型

导入完成后，返回 CC Switch 首页，在顶部选择 Codex。CC Switch 3.20.0 的一键导入会自动启用新供应商；X-AIO Tokens Plan 卡片出现蓝色边框，并显示“使用中”，就说明切换成功。旧版本如果没有自动启用，请在卡片右侧点击 启用。

按下面的步骤选择当前真实可用的模型：

1. 把鼠标移到 X-AIO Tokens Plan 卡片上，点击右侧的 编辑（铅笔图标）。
2. 在“默认模型”右侧点击 获取模型列表。
3. 展开“选择模型”，从刚获取的列表中选择可用模型。本教程以 gpt-5.6-sol 为例。
4. 保持 API 请求地址为 https://llm-api.x-aio.com/v1，上游格式为 Responses（原生）。
5. 点击右下角的 保存。

如果 Codex 已经在运行，请先输入 /exit 退出，再重新启动。供应商或模型切换不会修改已经运行中的旧进程。

8. 在空文件夹中验证配置

Codex 可以读取和修改当前目录中的文件。第一次测试请使用系统新建的空临时文件夹，不要直接在重要项目、桌面或个人资料目录中启动。

打开“终端”，依次运行：

demo_dir="$(mktemp -d /tmp/xaio-codex-demo.XXXXXX)"
cd "$demo_dir"
pwd
ls -A
codex --sandbox read-only

ls -A 没有输出时，说明测试文件夹为空。macOS 可能会把 /tmp 显示为 /private/tmp，两者指向同一个临时目录。

如果 Codex 显示 Do you trust the contents of this directory?，先确认完整路径位于 /tmp 或 /private/tmp 下，且目录名以 xaio-codex-demo. 开头，再选择 1. Yes, continue。不要在陌生目录或包含重要文件的目录中确认信任。

进入对话后发送：

请只回复“配置成功”，不要创建、修改或删除任何文件，也不要运行命令。

收到“配置成功”就说明 Codex 已通过 X-AIO 完成一次真实请求。本教程的实际验证结果如下；输出已省略与配置无关的日志：

OpenAI Codex v0.149.1
workdir: /private/tmp/xaio-codex-demo.XXXXXX
model: gpt-5.6-sol
provider: custom
sandbox: read-only

配置成功

输入 /exit 或按 Ctrl+C 退出 Codex，再检查测试文件夹：

ls -A

如果仍然没有输出，说明文件夹保持为空。本教程已完整验证：gpt-5.6-sol 正常回复“配置成功”，进程退出码为 0，测试目录前后均为空。

常见问题

终端提示 brew: command not found

重新执行 Homebrew 安装完成时显示的 Next steps，再完全退出并重新打开“终端”。不要直接复制其他电脑的 /opt/homebrew 或 /usr/local 路径。

终端提示 node: command not found 或 npm: command not found

确认 brew install node@24 已完成，再运行：

echo 'export PATH="$(brew --prefix node@24)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
node --version
npm --version

终端提示 codex: command not found

回到 CC Switch 的 设置 → 关于 → 本地环境检查，在 Codex 卡片中点击 安装，完成后点击 刷新。如果卡片已显示绿色勾，请完全退出并重新打开“终端”，再运行 codex --version。

请求返回 404 或“模型不存在”

这通常表示默认模型已经下线或不在当前套餐中。打开 X-AIO Tokens Plan 供应商的 编辑 页面，点击 获取模型列表，重新选择列表中存在的模型并保存；然后退出并重新启动 Codex。不要继续使用报错中的旧模型名。

请求地址显示 /responses，是否需要手动删除

不需要。CC Switch 中保存的 Base URL 应为 https://llm-api.x-aio.com/v1，Codex 会自动向它追加 /responses。如果出现 404，先核对 Base URL 和模型，不要把端点改成根域名，也不要重复添加 /responses。

点击一键接入后没有打开 CC Switch

确认 CC Switch 已安装到“应用程序”，并至少手动启动过一次。回到 Chrome 再次点击 一键接入 CC Switch（Codex），出现外部应用提示时点击 Open CC Switch。无需勾选“始终允许”。

启动后仍在使用旧供应商或旧模型

确认 X-AIO Tokens Plan 卡片有蓝色边框，并且模型编辑页已经保存。输入 /exit 完全退出当前 Codex 进程，再在测试目录中重新运行 codex。

请求提示 401、密钥无效或长时间超时

确认 X-AIO API 密钥页面中的 CC Switch - Codex 密钥仍在 90 天有效期内，并检查 Tokens Plan 套餐是否可用。新建密钥可能需要短暂同步，可以等待约 1 分钟后重试。访问 OpenAI 官方页面失败时，还需注意上文的地区限制和网络条件。