文档概述

本方案旨在 Rocky Linux 系统上，通过 CC Switch 工具，将 OpenAI Codex 命令行编程工具的 AI 模型后端切换为 DeepSeek-V4-Pro。文档记录了完整的安装、配置、验证流程及常见问题解决方法。

适用场景： 在终端中使用 AI 辅助编程，偏好 DeepSeek 模型能力，希望绕过对 OpenAI 官方 API 的直接依赖。

---

1. 环境准备

1.1 系统要求

• 操作系统： Rocky Linux 8 或 9 (本指南基于 Rocky Linux 9 测试)

• 网络要求： 服务器需能正常访问互联网，以安装软件包和调用 API。

• 用户权限： 具备 sudo 权限的用户，或可直接使用 root 用户（本指南使用 root，普通用户命令前需加 sudo）。

1.2 安装基础依赖

Codex 和 CC Switch 均依赖 Node.js 环境。

# 安装 Node.js 和 npm（通过官方源安装较新版本）
curl -fsSL https://rpm.nodesource.com/setup_20.x | bash -
dnf install -y nodejs

# 验证安装
node -v  # 应显示 v20.x 或更高
npm -v   # 应显示 10.x 或更高

潜在问题： 若系统提示 bubblewrap 相关警告，这是沙箱安全组件的提示，不影响核心功能。若想消除警告，可执行 dnf install -y bubblewrap。

---

2. 安装并配置 CC Switch（核心桥梁工具）

CC Switch 是一个图形化配置工具，用于统一管理多个 AI 模型供应商的 API 配置，并自动为 Codex 搭建本地代理。

2.1 安装 CC Switch

# 使用 npm 全局安装
npm install -g ccswitch

# 安装完成后，启动 CC Switch 图形界面（会默认打开浏览器）
ccswitch

注意： 确保防火墙允许访问 CC Switch 的 Web 端口（通常为 15721）。若无法自动打开浏览器，可手动访问 http://<服务器IP>:15721。

2.2 在 CC Switch 中添加 DeepSeek 供应商

1. 在 CC Switch 界面顶部，点击 Codex 标签页。

2. 点击右上角的 + 按钮，选择 DeepSeek 预设。

3. 在弹出的配置窗口中：

   • API Key： 粘贴你在 DeepSeek 开放平台申请的 API Key。

   • 其他字段（Base URL、默认模型）保持预设值即可（通常为 deepseek-v4-pro 或 deepseek-v4-flash）。

4. 点击 保存。

2.3 启用本地路由（关键步骤）

1. 点击 CC Switch 右上角的齿轮图标（设置），进入 路由 页面。

2. 开启 本地路由总开关。

3. 在“路由启用”区域，打开 Codex 的开关。

4. 确认本地代理地址（默认为 http://127.0.0.1:15721/v1），后续配置需要用到。

---

3. 安装并配置 Codex

3.1 安装 Codex CLI

# 通过 npm 全局安装 OpenAI Codex
npm install -g @openai/codex

# 验证安装
codex --version  # 应显示版本号，如 v0.140.0

3.2 配置 Codex 配置文件（手动修改以确保生效）

虽然 CC Switch 声称能自动修改，但根据实际测试，手动修改 ~/.codex/config.toml 文件更为可靠。

1. 创建配置目录并编辑配置文件：

   mkdir -p ~/.codex
   vi ~/.codex/config.toml

2. 将以下完整配置写入文件：

   # 指定默认模型和供应商
   model = "deepseek-v4-flash"
   model_provider = "deepseek"
   
   # 定义 deepseek 供应商
   [model_providers.deepseek]
   name = "DeepSeek"
   # 关键：指向 CC Switch 的本地代理地址
   base_url = "http://127.0.0.1:15721/v1"
   env_key = "DEEPSEEK_API_KEY"
   # 关键：使用 Responses API 协议
   wire_api = "responses"

   说明： 若你希望使用 deepseek-v4-pro 模型，可将 model 值替换为 "deepseek-v4-pro"。base_url 的端口号请以 CC Switch 实际显示为准。

3. 保存并退出。

---

4. 验证与启动

4.1 确保相关服务已启动

• CC Switch 必须保持在运行状态（终端窗口中保持 ccswitch 进程活跃）。

• 确保 CC Switch 界面的“路由”页面显示“已激活”状态。

4.2 设置环境变量（可选但推荐）

为避免每次输入 API Key，可在 ~/.bashrc 中设置：

echo 'export DEEPSEEK_API_KEY="你的DeepSeek API密钥"' >> ~/.bashrc
source ~/.bashrc

4.3 启动 Codex 并验证模型

codex

预期正确输出应包含：

model:     deepseek-v4-flash high   /model to change

这表明 Codex 已成功连接到 DeepSeek 模型。此时你可以直接输入问题开始使用。

---

5. 常见问题与解决方案

问题现象	可能原因	解决方法
/model 命令只显示 ChatGPT 选项	正常现象。通过代理添加的第三方模型不会出现在此列表中。应以启动界面显示的 model: 为准。	无需处理。
启动 Codex 显示 Model metadata not found	Codex 无法获取 DeepSeek 模型的完整元数据。	此为警告，不影响对话功能，可直接忽略。
Codex 无法启动或报连接错误	CC Switch 未运行；base_url 端口配置错误；防火墙拦截。	1. 检查 ccswitch 是否在运行； 2. 核对 ~/.codex/config.toml 中的 base_url 端口； 3. 确保防火墙开放 15721 端口。
提示 bubblewrap not found	系统缺少沙箱组件。	dnf install -y bubblewrap 可消除此提示，不影响核心功能。
npm install 时报 EEXIST 错误	文件冲突。	在安装命令后加 --force，如 npm install -g @openai/codex --force。

---

6. 日常使用建议

• 模型切换： 如需临时切换模型，可编辑 ~/.codex/config.toml 中的 model 字段，然后重启 Codex。

• 启动流程： 每次使用前，先确保 CC Switch 已在运行（界面打开或后台服务活跃），再执行 codex。

• 性能提示： deepseek-v4-flash 注重响应速度，deepseek-v4-pro 更擅长复杂推理，可根据任务选择。

---

7. 总结

本方案通过 CC Switch 搭建本地代理，解决了 Codex 原生只支持 OpenAI 官方模型的问题，实现了在 Rocky Linux 下使用 DeepSeek-V4-Pro 模型进行 AI 辅助编程。整个流程的关键在于 CC Switch 的本地路由配置 和 手动修改 Codex 配置文件。

按照文档操作后，你应该能得到一个稳定运行的 DeepSeek + Codex 开发环境。