CCX + CC-Switch + OpenAI Codex桌面版全平台部署安装文档

> 整体架构：**CCX（API协议中转网关，端口3000）→ CC-Switch（可视化配置管理器桌面端）→ Codex桌面/CLI**，CCX负责不同大模型API协议兼容转换，CC-Switch可视化管理多API密钥一键切换，Codex为OpenAI代码助手桌面客户端。
> 支持系统：Windows10+/macOS12+/Ubuntu22.04+/Debian11+，全流程分三大组件分步安装。

## 目录
1. 前置依赖环境统一安装
2. 组件1：CCX API网关安装（二进制/Docker双方案）
3. 组件2：CC-Switch桌面版全平台安装
4. 组件3：OpenAI Codex桌面版+CLI安装
5. 三组件联动配置（核心对接步骤）
6. 常见故障排查

## 1、前置依赖环境安装
### 1.1 Node.js（Codex/CC-Switch命令行依赖，必需v20+LTS）
#### Windows
1. 官网下载：https://nodejs.org/ 选择20.x LTS安装包
2. 安装勾选`Add to PATH`，安装完成新开终端校验
```powershell
node -v
npm -v
# 配置国内npm镜像加速
npm config set registry https://registry.npmmirror.com
```
> 也可以使用nvm-windows,项目地址：https://github.com/coreybutler/nvm-windows

#### macOS
```bash
# 已有Homebrew
brew install node@20
node -v && npm config set registry https://registry.npmmirror.com
```
#### Linux(Ubuntu/Debian)
```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install nodejs -y
npm config set registry https://registry.npmmirror.com
```

### 1.2 Git（源码编译可选）
```bash
# Windows：安装Git for Windows
# macOS
brew install git
# Linux
sudo apt install git -y
```

## 2、组件1：CCX 中转网关安装（二选一：二进制本地运行 / Docker容器）
> CCX默认端口：`3000`，负责ChatCompletion ↔ Codex Responses协议自动转换，对接各类国产/第三方API Key。
> 项目地址：https://github.com/BenedictKing/ccx

### 方案A：二进制部署（推荐新手，全平台）
1. 下载地址：Github Releases 下载对应系统架构包（win/linux/macos）
2. 解压到**无中文路径目录**
3. 在CCX根目录新建`.env`配置文件（无后缀名），写入配置：
```env
PORT=3000
ENV=production
ENABLE_WEB_UI=true
APP_UI_LANGUAGE=zh-CN
PROXY_ACCESS_KEY=自定义你的网关密钥（自定义字符串）
ADMIN_ACCESS_KEY=自定义后台管理员密钥
```
4. 启动程序
```powershell
# Windows 终端
.\ccx.exe
# macOS/Linux终端
chmod +x ./ccx
./ccx
```
5. 验证：浏览器打开 `http://localhost:3000`，使用`ADMIN_ACCESS_KEY`登录后台，添加上游API服务商与密钥。

### 方案B：Docker一键部署（推荐长期使用）
```bash
# 一键启动CCX容器
docker run -d \
--name ccx \
-p 3000:3000 \
-e PROXY_ACCESS_KEY=自定义网关密钥 \
-e ADMIN_ACCESS_KEY=自定义管理员密钥 \
-e APP_UI_LANGUAGE=zh-CN \
-v $(pwd)/ccx-config:/app/.config \
bene/ccx:latest

# 查看运行状态
docker ps | grep ccx
```
> 同样访问 `http://localhost:3000` 进入CCX后台配置上游模型API。

## 3、组件2：CC-Switch桌面版安装（可视化密钥管理工具）
> CC-Switch：GUI可视化管理Codex/ClaudeCode多API配置，一键切换上游服务商，自动写入Codex环境变量。
> 项目地址：https://github.com/farion1231/cc-switch

### 3.1 Windows安装（两种方式）
#### 方式1：MSI安装版（推荐）
1. Releases下载：`CC-Switch-vxxx-Windows.msi`
2. 双击安装，UAC弹窗点允许，勾选创建桌面快捷方式，自定义安装路径
3. 安装完成桌面双击`CC-Switch`启动

#### 方式2：绿色便携版（免安装）
1. 下载：`CC-Switch-vxxx-Windows-Portable.zip`
2. 解压至`D:\Tools\CCSwitch`（禁止中文目录）
3. 直接运行`CC-Switch.exe`，配置保存在解压目录，可随身U盘携带

### 3.2 macOS安装（两种）
#### 方式1：Homebrew（最简）
```bash
brew tap farion1231/ccswitch
brew install --cask cc-switch
# 更新软件
brew upgrade --cask cc-switch
```
#### 方式2：DMG手动安装
1. 下载`CC-Switch-vxxx-macOS.dmg`
2. 打开DMG，将`CC Switch.app`拖入「应用程序」文件夹
3. 首次启动如提示未知开发者：系统设置→隐私与安全性→仍要打开

### 3.3 Linux安装
```bash
# Debian/Ubuntu deb包
sudo dpkg -i CC-Switch-vxxx-Linux.deb
# ArchLinux
paru -S cc-switch-bin
# 通用AppImage
chmod +x CC-Switch.AppImage && ./CC-Switch.AppImage
```

### 3.4 命令行快速安装（跨平台npm）
```bash
npm install -g cc-switch
# 初始化配置
cc-switch init
```

## 4、组件3：OpenAI Codex桌面版 + CLI安装
### 4.1 CLI全局安装（必装，桌面端依赖CLI环境）
管理员/root权限打开终端执行：
```bash
# 全局安装Codex CLI
npm install -g @openai/codex --force
# 校验安装
codex --version
```

### 4.2 Codex桌面版启动
```bash
# 命令行唤起Electron桌面客户端
codex desktop
```
> 首次启动自动下载桌面依赖组件，等待完成后弹出Codex可视化界面，windows则需要去应用商店查找codex安装
> powershell 需要先执行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

### 4.3 手动下载桌面安装包（备选）
官网下载对应系统安装包：
- Windows：Codex-Setup.exe
- macOS：codex.dmg，拖入应用程序
- Linux：deb/AppImage包安装

## 5、三组件联动核心配置（关键对接）
### 步骤1：CCX后台添加上游模型API
1. 访问`http://localhost:3000`登录
2. 【上游渠道】→新增服务商，填入对应平台`API_KEY、BaseURL`，CCX自动做协议转换
3. 记录CCX本地地址：`http://127.0.0.1:3000/v1`

### 步骤2：CC-Switch配置对接CCX
1. 打开CC-Switch桌面软件→左侧【Providers】→`+添加供应商`
2. 自定义名称，BaseURL填写：`http://127.0.0.1:3000/v1`
3. API Key填写CCX的`PROXY_ACCESS_KEY`（.env内自定义密钥），保存配置
4. 选中该配置，点击**设为默认**，软件自动写入系统环境变量

### 步骤3：Codex加载配置验证
1. 关闭已有Codex，重新执行`codex desktop`启动桌面
2. 桌面内打开设置，查看API地址自动变为CCX本地地址
3. 终端测试调用：
```bash
codex "写一段HelloWorld"
```
返回代码即联动全部成功。

## 6、常见问题排查
### 6.1 CCX 3000端口被占用
```bash
# Windows查看占用端口
netstat -ano | findstr :3000
# Linux/macOS
lsof -i:3000
# 修改CCX端口：修改.env PORT=3001，同步CC-Switch的BaseURL端口
```
### 6.2 npm安装Codex报错权限不足
- Windows：右键终端【以管理员运行】
- macOS/Linux：添加`sudo npm install -g @openai/codex`

### 6.3 CC-Switch无法写入环境变量
关闭杀毒/防火墙，软件右键管理员运行；便携版切换至非系统盘目录。

### 6.4 Codex请求报错401
核对三处密钥：CCX的PROXY_ACCESS_KEY、CC-Switch内填写的APIKEY、CCX后台上游服务商KEY。

## 7、软件卸载
### 7.1、全局卸载 Codex CLI（核心）
#### Windows / macOS / Linux 通用命令
```bash
npm uninstall -g @openai/codex
```

#### 强制彻底卸载（解决删不掉）
```bash
npm rm -g @openai/codex --force
```

验证是否卸载成功：
```bash
codex --version
```
出现 **command not found** 就是删干净了。

---

### 7.2、删除桌面端残留（彻底清理）
#### Windows 系统（必执行）
```powershell
# 删除桌面端缓存
rmdir /s /q "%APPDATA%\Codex"
rmdir /s /q "%LOCALAPPDATA%\Programs\Codex"
rmdir /s /q "%USERPROFILE%\.codex"

# 删除快捷方式
del "%USERPROFILE%\Desktop\Codex.lnk"
```

#### macOS 系统
```bash
# 删除桌面端
rm -rf /Applications/Codex.app
rm -rf ~/Applications/Codex.app

# 删除缓存、配置、日志
rm -rf ~/.codex
rm -rf ~/Library/Application\ Support/Codex
rm -rf ~/Library/Caches/Codex
rm -rf ~/Library/Preferences/com.openai.codex.plist
```

#### Linux 系统
```bash
# 删除桌面端与缓存
rm -rf ~/.codex
rm -rf ~/.config/Codex
rm -rf ~/.local/share/Codex
rm -rf /opt/Codex
```

---

### 7.3、清理 npm 残留（防止重装冲突）
```bash
npm cache clean --force
npm cache verify
```

---

### 7.4、一键全量卸载脚本（直接复制整段执行）
#### Windows 一键彻底删除
```powershell
npm rm -g @openai/codex --force
rmdir /s /q "%APPDATA%\Codex"
rmdir /s /q "%LOCALAPPDATA%\Programs\Codex"
rmdir /s /q "%USERPROFILE%\.codex"
npm cache clean --force
echo "Codex 已彻底卸载完成！"
```

#### macOS / Linux 一键彻底删除
```bash
sudo npm rm -g @openai/codex --force
rm -rf ~/.codex
rm -rf ~/Library/Application\ Support/Codex
rm -rf ~/Library/Caches/Codex
npm cache clean --force
echo "Codex 已彻底卸载完成！"
```

---

#### 总结
执行完上面命令后：
- `codex` 命令失效
- 桌面端消失
- 所有配置/缓存/日志全部删除
- 系统无任何残留

CCX + CC-Switch + OpenAI Codex桌面版全平台部署安装文档

添加新评论

关于博主

文章分类

最受欢迎的文章

最近回复

其它

CCX + CC-Switch + OpenAI Codex桌面版 全平台部署安装文档

添加新评论

关于博主

文章分类

最受欢迎的文章

最近回复

其它

CCX + CC-Switch + OpenAI Codex桌面版全平台部署安装文档