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

本文档介绍了CCX API网关、CC-Switch可视化配置管理器和OpenAI Codex桌面版的全平台部署安装步骤。整体架构为CCX→CC-Switch→Codex，支持Windows10+/macOS12+/Ubuntu22.04+/Debian11+。包含前置依赖安装、三大组件安装（二进制/Docker/桌面版/CLI）、联动配置及常见故障排查。

人工智能
作者：zhuge···预计阅读 20 分钟·37 阅读·0 评论
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，安装完成新开终端校验
node -v
npm -v
# 配置国内npm镜像加速
npm config set registry https://registry.npmmirror.com

也可以使用nvm-windows,项目地址：https://github.com/coreybutler/nvm-windows

macOS

# 已有Homebrew
brew install node@20
node -v && npm config set registry https://registry.npmmirror.com

Linux(Ubuntu/Debian)

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（源码编译可选）

# 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配置文件（无后缀名），写入配置：
PORT=3000
ENV=production
ENABLE_WEB_UI=true
APP_UI_LANGUAGE=zh-CN
PROXY_ACCESS_KEY=自定义你的网关密钥（自定义字符串）
ADMIN_ACCESS_KEY=自定义后台管理员密钥
  1. 启动程序
# Windows 终端
.\ccx.exe
# macOS/Linux终端
chmod +x ./ccx
./ccx
  1. 验证：浏览器打开 http://localhost:3000，使用ADMIN_ACCESS_KEY登录后台，添加上游API服务商与密钥。

方案B：Docker一键部署（推荐长期使用）

# 一键启动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（最简）

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安装

# 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）

npm install -g cc-switch
# 初始化配置
cc-switch init

4、组件3：OpenAI Codex桌面版 + CLI安装

4.1 CLI全局安装（必装，桌面端依赖CLI环境）

管理员/root权限打开终端执行：

# 全局安装Codex CLI
npm install -g @openai/codex --force
# 校验安装
codex --version

4.2 Codex桌面版启动

# 命令行唤起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. 终端测试调用：
codex "写一段HelloWorld"

返回代码即联动全部成功。

6、常见问题排查

6.1 CCX 3000端口被占用

# 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 通用命令

npm uninstall -g @openai/codex

强制彻底卸载（解决删不掉）

npm rm -g @openai/codex --force

验证是否卸载成功：

codex --version

出现 command not found 就是删干净了。

7.2、删除桌面端残留（彻底清理）

Windows 系统（必执行）

# 删除桌面端缓存
rmdir /s /q "%APPDATA%\Codex"
rmdir /s /q "%LOCALAPPDATA%\Programs\Codex"
rmdir /s /q "%USERPROFILE%\.codex"

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

macOS 系统

# 删除桌面端
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 系统

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

7.3、清理 npm 残留（防止重装冲突）

npm cache clean --force
npm cache verify

7.4、一键全量卸载脚本（直接复制整段执行）

Windows 一键彻底删除

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 一键彻底删除

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 命令失效
  • 桌面端消失
  • 所有配置/缓存/日志全部删除
  • 系统无任何残留

相关文章

人工智能

为OpenClaw添加扩展/Skill

309 阅读
人工智能

为OpenClaw添加新的自定义模型

358 阅读
人工智能

安装OpenClaw然后配置Nginx反向代理

330 阅读

评论

加载中...