Codex 桌面客户端 + CC Switch
中国开发者 API 接入完全指南
从下载安装到 API Key 登录、本地路由配置、国内大模型接入，一篇搞定 Codex Desktop 在国内的全链路使用。不需要 ChatGPT 账号，不需要海外手机号。
背景：为什么需要这篇教程
Codex 桌面客户端（Codex Desktop App）是 OpenAI 推出的 AI 编程桌面应用，能直接在桌面上管理多个 AI Agent，自动读代码、写代码、跑测试、修 Bug。但国内开发者上手时面临几个现实问题：
账号门槛
Codex 默认要求用 ChatGPT 账号登录，注册需要海外手机号验证，对国内用户基本是劝退门槛。
网络不通
即使有账号，直连 OpenAI 官方 API 在国内也经常超时或被墙。
价格昂贵
官方 API 按量计费，对话一会儿额度就耗光，成本让很多人望而却步。
协议不兼容
Codex 使用 OpenAI Responses API，而 DeepSeek 等国内模型用 Chat Completions API，直接改地址会 404。
这篇教程带你用 CC Switch 的本地路由功能解决协议转换问题，接入 DeepSeek 等国内大模型，以极低成本跑通 Codex 桌面客户端的完整流程。
Codex 桌面客户端是什么
Codex Desktop App 是 OpenAI 于 2026 年推出的 AI 编程桌面应用。官方定义它为「一个用于管理 AI 编程代理的开发工作中心」。
| 特性 | 说明 |
|---|---|
| 多 Agent 同时工作 | 可以同时运行多个编程代理，每个任务拥有独立 Workspace |
| 代码 Diff 查看 | 清晰看到 AI 修改了哪些代码，可接受或拒绝每一处变更 |
| 自动化任务执行 | AI 可以像开发代理一样自动完成开发流程 |
| Computer Use | AI 可直接操控你的电脑——打开浏览器、读取文档、操作文件系统 |
| API Key 登录 | 支持直接用 API Key 授权登录，无需 ChatGPT 账号 |
| 与 CLI 共享配置 | 桌面客户端和命令行版共用 ~/.codex 配置目录 |
macOS：通过 Mac App Store 下载，需要 macOS 14.0+（Sonoma 或更新版本），需 Apple Silicon 芯片（M1/M2/M3/M4）
Windows：通过 Microsoft Store 下载，需要 Windows 10 19041+ 版本
CC Switch 是什么
CC Switch 是一个免费开源的跨平台桌面应用，用于统一管理 Claude Code、Codex、Gemini CLI 等多种 AI 编程工具的 API 供应商配置。
GitHub：farion1231/cc-switch ｜ 官网：ccswitch.io ｜ 技术栈：Tauri 2.0 + React + Rust ｜ 许可证：MIT
对于 Codex 桌面客户端的用户，CC Switch 的核心价值在于：
- 本地路由（关键功能）：在本地启动代理服务，自动将 Codex 的 Responses API 请求转换为国内模型能听懂的 Chat Completions 格式——这是接入国内大模型的核心
- 一键切换供应商：在 DeepSeek、智谱 GLM、Qwen 等多个国内模型间秒级切换
- 可视化配置：内置 50+ 供应商预设，填写 API Key 即可，无需手动编辑 TOML 配置文件
- 用量查询：直接在应用内查看各供应商剩余额度
- 速度测试：可视化测量各端点延迟
前置准备
| 条件 | 说明 |
|---|---|
| 操作系统 | Windows 10 19041+ 或 macOS 14.0+（需 Apple Silicon 芯片） |
| Node.js 22+ | 虽然桌面客户端本身不依赖 Node.js，但 CC Switch 写入的配置文件与 CLI 共享，建议安装 Node.js 22+ 以备后续使用 CLI。 |
| 至少一个 API Key | 你需要一个国内大模型的 API Key。本文以 DeepSeek 为例，操作流程对智谱 GLM、Qwen、Kimi 等完全一样。 |
| 网络环境 | 使用国内大模型 API 时不需要科学上网。CC Switch 本地路由在本地运行，无网络限制。 |
获取 DeepSeek API Key（以 DeepSeek 为例）
注册 DeepSeek 开放平台
访问 DeepSeek 开放平台，注册并登录账号。
创建 API Key
进入「API Keys」页面，点击「创建 API Key」。给 Key 起个名字（如 codex使用），点击创建。
复制保存 Key
Key 只会在创建时完整显示一次，格式形如 sk-xxxxxxxxxxxxxxxx。务必立即复制保存到安全的地方。
下载安装 Codex 桌面客户端
macOS 安装
通过 Mac App Store 安装
打开 Mac App Store，搜索「Codex」，点击下载安装。或访问官方页面 developers.openai.com/codex/app 获取下载链接。
系统要求确认
需要 macOS 14.0+（Sonoma 或更新版本）和 Apple Silicon 芯片（M1/M2/M3/M4）。Intel Mac 暂不支持。
Windows 安装
通过 Microsoft Store 安装
访问 Microsoft Store 下载页面，点击「获取 / 下载」，按提示完成安装。需要 Windows 10 19041+ 版本。
或从官网下载安装包
访问 OpenAI Codex 官方页面，根据系统选择对应安装包下载。
用 API Key 登录 Codex
安装完成后双击打开 Codex，你会看到登录界面。默认要求使用 ChatGPT 账号登录，但国内用户大多没有海外账号。
选择「使用其他方式登录」
在登录界面点击左下角的 「使用其他方式登录」（或「Enter API Key」），进入 API Key 授权模式。
粘贴 API Key
将你准备好的 API Key（如 DeepSeek 的 sk-xxxxxxxx，或第三方中转站的 Key）粘贴到输入框中，点击「继续」。
完成登录
登录成功后，首次使用会让你选择职业方向（工程、产品等），选择一个即可，后续可在设置中修改。
完全绕开了 ChatGPT 账号注册和海外手机号验证的门槛。配合后续的 CC Switch 配置，即使填的是 DeepSeek 的 Key，登录后也能正常进入 Codex 界面。
安装 CC Switch
macOS
# 添加 tap 源并安装（推荐）
brew tap farion1231/ccswitch
brew install --cask cc-switch
# 后续更新
brew upgrade --cask cc-switch由于作者没有 Apple 开发者账号，首次打开会弹出「未知开发者」警告。请关闭提示，前往 系统设置 → 隐私与安全性，点击「仍要打开」即可正常使用。
Windows
下载安装包
前往 CC Switch Releases 页面，下载最新版的 CC-Switch-v{版本号}-Windows.msi 安装包，或下载 -Portable.zip 绿色免安装版。
运行安装
双击 .msi 文件按提示安装。如果 Windows 弹出「已保护你的电脑」，点击「更多信息」→「仍要运行」。
Linux
# Debian / Ubuntu
sudo dpkg -i CC-Switch-v*_Linux.deb
# 或使用 AppImage
chmod +x CC-Switch-v*_Linux.AppImage
./CC-Switch-v*_Linux.AppImage用 CC Switch 配置国内大模型
安装完 CC Switch 后，打开应用，按以下步骤将国内大模型（以 DeepSeek 为例）接入 Codex。
步骤一：切换到 Codex 分组
打开 CC Switch，在界面顶部的应用分组栏中，点击选择 「Codex」。你会看到当前已有的 Codex 供应商列表（首次使用为空）。
步骤二：添加供应商
点击右上角「+ 添加供应商」
在弹出的配置窗口中，你会看到模板配置和自定义配置两种方式。
选择预设模板（推荐）
CC Switch 内置了 50+ 供应商预设。在预设列表中搜索并选择 「DeepSeek」，CC Switch 会自动填充 Base URL、模型名称等所有配置项。
如果你想用其他模型（如智谱 GLM、Qwen、Kimi），选择对应预设即可，操作完全一样。
如果你的供应商没有预设，选择 「自定义配置」，手动填写：
| 字段 | 说明 | 示例 |
|---|---|---|
名称 | 供应商显示名称 | DeepSeek |
API Key | 模型平台提供的密钥 | sk-xxxxxxxx |
Base URL | API 端点地址 | https://api.deepseek.com/v1 |
模型 | 默认模型 ID | deepseek-v4-pro |
填写 API Key
在「API Key」输入框中粘贴你之前在 DeepSeek 开放平台创建的 API Key。
勾选「本地路由映射」（关键！）
在配置窗口中，务必勾选 「本地路由映射」 选项。这是因为 Codex 使用的是 OpenAI 的 Responses API 协议，而 DeepSeek 等国内模型使用的是 Chat Completions API 协议，两者不兼容。CC Switch 的本地路由会在你电脑上启动一个代理服务，自动做协议转换。
点击「添加」保存
保存后，该供应商会出现在主界面的列表中。
步骤三：启用供应商
回到 CC Switch 主界面，在供应商列表中找到你刚添加的 DeepSeek，点击右侧的 「启用」 按钮。状态变为「使用中」即表示已激活。
启用供应商后，如果在 Codex 中直接发消息，可能会遇到 404 错误。这是因为本地路由还没开启。请继续下一步。
开启本地路由（关键步骤）
这是接入国内大模型最关键的一步。CC Switch 的本地路由会接管 Codex 的 API 请求，做协议转换后转发给国内模型。
请求流转原理
DeepSeek / 国内模型 ← 返回结果 ← CC Switch 本地路由 ← 转换回 Responses 格式 ← Codex 桌面客户端
整个转发对 Codex 完全透明——它以为自己还在访问 OpenAI 官方接口，实际上请求已经被 CC Switch 偷偷转给了 DeepSeek。
开启步骤
进入设置页面
在 CC Switch 中点击左上角的 「设置」 按钮（齿轮图标），进入设置页面。
找到路由设置
在设置菜单中找到 「路由设置」（或「本地路由」）选项卡。
打开路由总开关
将 「路由总开关」 打开，然后选择 启用 Codex 路由。这一步让 CC Switch 的本地代理正式接管 Codex 的请求。
重启 Codex
关闭并重新打开 Codex 桌面客户端，配置即可生效。
重新打开 Codex 桌面客户端后，输入一句话测试（比如「你是什么模型？」），如果能正常回复，说明国内大模型已经成功接入！你会发现 AI 嘴上还说自己是 GPT-5——这是因为 Codex 会给模型注入自己的系统提示词，但实际干活的底层已经换成了 DeepSeek。
Codex 桌面客户端和命令行版（Codex CLI）共用 ~/.codex 这套配置。CC Switch 切换之后，桌面客户端和 CLI 都会生效，无需重复配置。
设置中文界面
Codex 桌面客户端默认界面为英文。如需切换为中文：
打开设置
点击左上角 File → Settings（或点击齿轮图标）。
进入 General 标签页
在设置界面中选择 「General」 标签页。
切换语言
找到 「Language for the app UI」 选项，在下拉菜单中选择 「Chinese (China)」。
下载语言包并重启
选择中文后，软件会提示下载语言包。点击「下载」，完成后重启 Codex 即可生效。
部分版本存在 UI 本地化不完全的 Bug，切换中文后顶部菜单栏和侧边栏可能仍显示英文。OpenAI 正在逐步完善本地化覆盖，预计后续版本会修复。
日常使用 Codex 桌面客户端
核心操作流程
使用 Codex 桌面客户端非常简单——你只需要给它一个任务目标：
- 打开 Codex Desktop
- 输入你要完成的任务描述（支持中文）
- Codex 会自动分析并开始执行
- 你可以查看代码 diff，接受或拒绝每一处修改
常见使用场景
写代码
写函数、脚本、前端页面、后端 API 接口，从零搭建项目框架。
修改项目代码
新增功能、代码重构、性能优化，以 diff 形式展示变更。
查 Bug
把报错信息、日志或代码发给 Codex，它会分析问题并给出修复方案。
写测试
单元测试、集成测试、端到端测试自动生成。
写技术文档
README、接口文档、设计文档、中英文翻译。
自动化任务
AI 可像 Agent 一样工作，自动完成 Bug 整理、日报生成、项目部署。
切换供应商（日常操作）
当你需要切换到另一个国内大模型时：
- 主界面：在 CC Switch 的 Codex 分组中，点击另一个供应商的「启用」按钮
- 系统托盘：右键点击系统托盘中的 CC Switch 图标，在菜单中直接选择目标供应商
切换后重新打开 Codex 桌面客户端即可生效。
国内常用 API 供应商推荐
以下信息仅供参考，不构成推荐。中转服务的稳定性、价格、合规性请自行评估。使用第三方 API 时请注意保护代码隐私和数据安全。
| 供应商 | Base URL | 特点 | CC Switch 预设 |
|---|---|---|---|
| DeepSeek 官方 | https://api.deepseek.com/v1 |
价格极低，中文理解能力强，编程能力出色 | 有 |
| 智谱 GLM | https://open.bigmodel.cn/api/paas/v4 |
国产大模型，支持 GLM-4.6 等最新模型 | 有 |
| 通义千问 Qwen | https://dashscope.aliyuncs.com/compatible-mode/v1 |
阿里达摩院，支持多种开源模型 | 有 |
| Kimi (月之暗面) | https://api.moonshot.cn/v1 |
超长上下文，适合处理大段代码 | 有 |
| MiniMax | https://api.minimax.chat/v1 |
多模态能力强 | 有 |
| 硅基流动 | https://api.siliconflow.cn/v1 |
聚合平台，支持多种开源模型 | 有 |
所有有 CC Switch 预设的供应商，操作流程和 DeepSeek 完全一样：选预设 → 填 API Key → 勾选本地路由 → 启用。想换哪家模型，几分钟就能搞定。
常见问题排查
检查 API Key 是否正确复制（无多余空格或引号）。如果你用的是 DeepSeek 等国内模型的 Key，需要先通过 CC Switch 配置并开启本地路由后才能正常使用。直接在 Codex 登录界面填的 Key 主要用于初始进入，实际模型路由由 CC Switch 管理。
这是因为本地路由没开启。Codex 使用 Responses API，而国内模型用 Chat Completions API，直接请求会 404。解决方法：
1. 打开 CC Switch → 进入「设置」→「路由设置」
2. 打开「路由总开关」
3. 启用 Codex 路由
4. 重启 Codex 桌面客户端
Error: 401 UnauthorizedAPI Key 不正确或已过期。检查：1）CC Switch 中填写的 API Key 是否与模型平台一致；2）API Key 是否已过期或被删除；3）账户余额是否充足。新开终端后重试。
Codex 不会热加载配置。切换供应商后需要完全关闭并重新打开 Codex 桌面客户端。如果当前有 Codex 会话正在运行，需要先退出。
macOS 用户确认系统版本 ≥ 14.0 且为 Apple Silicon 芯片。Windows 用户确认版本 ≥ 10 19041。也可以从 官方页面 直接下载安装包。Microsoft Store 无法下载时，尝试修改系统区域或使用网络工具。
这是已知的本地化 Bug（GitHub Issue #19518、#17309），OpenAI 正在逐步完善。确保语言包已下载完成并重启应用。顶部菜单栏和部分侧边栏可能仍显示英文，不影响核心功能使用。
在 CC Switch 中：1）关闭本地路由总开关；2）在供应商列表中切换到「官方登录」预设并启用；3）重启 Codex 桌面客户端。此时将恢复使用 OpenAI 官方 API（需要你有可用的 OpenAI 账号和网络环境）。
写入模式（默认）：CC Switch 直接将供应商配置写入 Codex 的 ~/.codex/auth.json 和 config.toml。适合使用兼容 Responses API 的供应商（如第三方中转站）。
本地路由模式：CC Switch 在本地启动代理服务，做协议转换后转发请求。适合使用 Chat Completions API 的国内模型（如 DeepSeek、GLM）。接入国内大模型必须用这个模式。
Comments NOTHING