Codex 安装全指南：桌面应用与 CLI（Windows / macOS / Linux + 国内接入）
最近把 Codex 从”装好”到”在国内真正跑通”完整折腾了一遍，这篇把官方桌面应用安装说明、国内网关接入实践、以及社区国产大模型方案合并成一份可直接照抄的完整指南：桌面应用怎么装、CLI 三平台怎么装、国内网络怎么接入、国产模型怎么接、报错怎么排。信息核对时间 2026-08，具体版本号与命令以官方文档 / 服务商页面实时显示为准。
⚠️ 安全提示：只从 OpenAI、Microsoft 等官方渠道下载安装包。不要使用第三方下载站的”完整版""绿色版""破解版”，避免账号、代码仓库和本地文件泄露。
一、先搞清楚：Codex 有哪几种形态
Codex 不是单一产品，而是一组编程入口的统称，目前主要有四种形态：
| 形态 | 说明 |
|---|---|
| 桌面 App | 已集成进 ChatGPT 桌面应用（macOS / Windows），安装后可在应用内选 ChatGPT 或 Codex |
| IDE 插件 | VS Code / Cursor / Windsurf 等编辑器的插件 |
| CLI | @openai/codex npm 包，终端里的命令行工具（本文重点之一） |
| 云端浏览器版 | chatgpt.com/codex，仅在线使用，需要绑定 GitHub 仓库 |
桌面应用和 CLI 是两个不同的使用入口：安装 CLI 不等于安装了图形界面客户端，反之亦然。本指南第三节讲桌面应用，第四节起讲 CLI，第五、六节讲国内接入。
二、国内访问：为什么这么麻烦
不管走哪种形态，首次启动基本都要连 chatgpt.com 或 api.openai.com 完成鉴权，而这两个域名在国内都不太友好：
- chatgpt.com：走 Cloudflare 边缘节点，国内 DNS 解析时延不稳定，登录页经常加载到一半挂掉；
- api.openai.com：在大陆出口被收紧，超时、握手失败、SSL 报错都很常见；
- developers.openai.com：文档站偶尔能打开，但下载安装包时跳到的对象存储域名又是另一回事。
对桌面 App 来说，忍一忍还能用；但 Codex CLI 是常驻进程，每次请求都要握手，网络稳定性直接决定编程会话能不能进行下去。所以国内用户通常有三条路线：
- 官方账号路线：用稳定网络访问官方服务；
- OpenAI 兼容网关路线：CLI 支持自定义
base_url和wire_api，指向支持 Responses API 的兼容网关（见第五节）； - 国产模型路线：通过社区工具把 Codex 接到 DeepSeek、GLM、Qwen、Kimi 等国产模型（见第六节）。
三、桌面应用：Windows / macOS 官方安装
macOS
macOS 有两个版本，先确认芯片：苹果菜单 → 关于本机，Apple M 系列选 Apple Silicon，Intel 处理器选 Intel。两种 DMG 架构不同，不要混用。
- 从 developers.openai.com/codex/app 下载对应 DMG；
- 打开
Codex.dmg，把应用拖入”应用程序（Applications）“文件夹； - 从”应用程序”打开 ChatGPT；
- 登录后选择 Codex，或创建/打开项目目录开始使用。
注意：桌面 App 的下载和登录流程仍走 OpenAI 官方域名，国内网络不稳定，这也是下面重点讲 CLI 的原因之一。
Windows
普通用户推荐网页安装器：从 get.microsoft.com 下载 ChatGPT Installer.exe（约 1.4 MB，引导安装器，不是完整离线包）。也可以直接用命令：
winget install --id 9PLM9XGG6VKS -s msstore其中 9PLM9XGG6VKS 是 ChatGPT 桌面应用的 Microsoft Store 产品 ID。若 msstore 源异常，先重置再装：
winget source list
winget source reset --force
winget install --id 9PLM9XGG6VKS -s msstore企业 / 离线部署：OpenAI 提供 Store 签名 MSIX（x64 / Arm64 两个架构），配合离线许可证 ChatGPT-License.xml，经 Intune、MDM 等平台分发。完成初次安装后，设备只要能访问 persistent.oaistatic.com 即可按组织的更新策略获取后续更新。
四、Codex CLI：macOS / Windows / Linux 三平台安装
安装前准备：Node.js
Codex CLI 当前要求 Node ≥ 22（官方实测最低版本 22.22.0）。Node 20 及以下虽然能全局安装，但启动 codex 时会报 SyntaxError: Unexpected token 之类的解析错误。
node -v # v22.x.x 以上 OK版本不够就装新 LTS：macOS / Linux 用 nvm，Windows 用 nvm-windows。
macOS（三种方式选一种）
方式 A：Homebrew（推荐）——brew 会接管后续更新：
brew install --cask codex
brew upgrade --cask codex # 以后更新用这条方式 B：npm 全局安装——OpenAI 最早支持、版本同步最快：
npm install -g @openai/codex方式 C：桌面 App——见第三节，这一步通常需要稳定网络，不推荐当主路径。
Windows
CLI 用户直接 npm 安装：
npm install -g @openai/codex装完发现 codex 命令找不到？大概率是 npm 全局目录没进 PATH：
npm prefix -g # 通常是 C:\Users\<你>\AppData\Roaming\npm把输出目录加到系统 PATH，重开 PowerShell 即可。
另外建议把项目放在 C:\Users\<你>\Code\ 之类的用户目录下——Codex 沙箱在写 Program Files 或盘根目录时容易触发权限拒绝。
Windows 上还有 Microsoft Store 桌面 App（商店搜 “Codex by OpenAI”），不需要 Node，但登录流程仍走 chatgpt.com，国内不稳定，别选它当主路径。
Linux
主流发行版直接用 npm：
npm install -g @openai/codex服务器不想装 Node 的话，可以从 GitHub Releases 下载对应架构的归档包。注意官方 Linux 产物是 musl 静态链接的 tar.gz，不是裸二进制：
mkdir -p ~/.local/bin
curl -L -o /tmp/codex.tar.gz \
https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz
tar -xzf /tmp/codex.tar.gz -C ~/.local/bin/
chmod +x ~/.local/bin/codex
rm /tmp/codex.tar.gzARM 服务器把文件名换成 codex-aarch64-unknown-linux-musl.tar.gz。解压后如果实际文件名不是 codex（部分版本归档偶尔带后缀），自己 mv 重命名即可。GitHub Releases 下载国内速度看运气，卡住就回头用 npm 更稳。
五、国内接入路线一：CLI 指向 OpenAI 兼容网关
装好的 CLI 默认连 api.openai.com，国内会立刻超时。这条路适合”网关本身支持 Responses API”的场景，配置入口在 ~/.codex/config.toml（Windows 是 %USERPROFILE%\.codex\config.toml），文件不存在就手动创建。
以 ofox.io 这类 OpenAI 兼容网关为例，最小可用配置：
# 默认模型（OpenAI Codex 编程专用）
model = "openai/gpt-5.3-codex"
# 默认 Provider
model_provider = "ofoxai"
# Provider 定义
[model_providers.ofoxai]
name = "OfoxAI"
base_url = "https://api.ofox.io/v1"
env_key = "OFOXAI_API_KEY"
wire_api = "responses"要点：
wire_api = "responses"务必写上：2026-02 起 Codex CLI 已把wire_api = "chat"标记为弃用，新版会直接拒绝发请求；base_url不要写错、结尾不要多写/，如https://api.ofox.io/v1；env_key告诉 CLI 去哪个环境变量读 Key。
然后设置环境变量（macOS / Linux 写入 ~/.zshrc 或 ~/.bashrc）：
export OFOXAI_API_KEY="sk-ofox-xxxxxxxxxxxx"
source ~/.zshrcWindows（PowerShell，永久生效）：
[Environment]::SetEnvironmentVariable("OFOXAI_API_KEY", "sk-ofox-xxxxxxxxxxxx", "User")设完重开 PowerShell。
⚠️ 第三方网关需要自行甄别服务商资质、数据留存策略与价格。模型 ID（如
openai/gpt-5.3-codex，注意小写 + 短横线 + 点）和可用模型列表以服务商控制台实时显示为准。
六、国内接入路线二：国产大模型 + EchoBird / CC-Switch / Codex++
第五节是”把 Codex 接到支持 Responses API 的网关”。但国内更常见的诉求是：把 Codex 接到 DeepSeek、GLM、Qwen、Kimi 这些国产模型上。很多人第一反应是”改个 Base URL、填个国产 Key”，结果一跑全是乱码或超时——问题出在协议层。
6.1 为什么不能只改 Base URL
新版 Codex 在 API Key 模式下默认走 OpenAI 的 Responses API，而绝大多数国产模型只提供 OpenAI-compatible 的 Chat Completions API。两套协议在消息结构、流式响应、reasoning 字段、tool call 表达方式上都有明显差异，硬接是接不上的——必须有一层”翻译”。
6.2 三款社区工具怎么选
社区为此出现了三个有代表性的开源项目：
| 维度 | EchoBird | CC-Switch | Codex++ |
|---|---|---|---|
| 定位 | AI Agent 管理器（All-in-One） | API 切换器（协议路由） | 桌面增强插件（注入层） |
| 实现原理 | 图形化配置 + 一键分配到 Codex | 本地代理做协议翻译 | launcher + CDP 注入增强 |
| 支持平台 | Win / Mac / Linux | Win / Mac / Linux | 主要是 Windows |
| 上手难度 | 极低（图形化） | 中等（YAML/JSON 配置） | 低（一键安装） |
| 国产模型适配 | ✅ 内置 DeepSeek、Qwen、Kimi 等 | ✅ 任意 OpenAI 兼容接口 | ❌ 需配合 CC-Switch 等中转 |
| 免登录 | ✅ 自动跳过 OAuth | ✅ 支持 OAuth 态复用 | ❌ 仍需登录 |
| 价格 | 免费 | 免费 | 免费 |
| 项目地址 | github.com/edison7009/EchoBird | github.com/farion1231/cc-switch | github.com/b-nnett/codex-plusplus |
一句话总结本质差别：CC-Switch 解决”请求往哪路由、协议怎么翻译”（网络层）；Codex++ 解决”桌面端如何增强、第三方 provider 怎么写入”（注入层）；EchoBird 是把常用功能做成图形化一键方案（All-in-One）。
6.3 快速上手
EchoBird（最快）：
- 下载安装包直接运行（支持 Intel / Apple Silicon）；
- 启动后进”模型中心”，添加 DeepSeek / Qwen / Kimi；
- 填入 API Key（或 Endpoint），一键分配到 Codex Agent。
全程 3 分钟，不用碰命令行。
CC-Switch（最灵活，CLI 用户推荐）：
- 安装后首次运行设置转发端口（默认 8080）；
- 在 Providers 里添加自定义 OpenAI Compatible（如 Name=DeepSeek、Base URL=
https://api.deepseek.com/v1、API Key）； - 在 Settings 里把 DeepSeek 排进 fallback chain 顶部；
- 重启 Codex 验证——CC-Switch 路由页能看到请求数从 0 涨起来，说明 Codex 真的走过了本地代理。
Codex++（桌面端增强）：
- 一键安装，自动检测 Codex 安装路径并打补丁；
- 重启 Codex，顶部出现”Codex++“菜单，可启用插件入口、Timeline 会话管理。
它本身不做 API 路由，跑国产模型需配合 CC-Switch。
6.4 能力兼容性：哪些保留、哪些降级、哪些没了
切到国产模型后，Codex 的能力不是全部保留，按社区实测分三档：
- ✅ 基本不受影响：代码编写、调试重构、文件读写、项目管理、多轮对话、任务规划；
- ⚠️ 降级可用：Skills / 插件体系（部分场景能跑，稳定性看版本）；复杂 tool calls 或长任务可能出现格式问题；
- 🚫 难以替代：Image Gen（图像生成）依赖 OpenAI 自家能力；Computer Use（电脑操作）依赖 Responses API 内置的 computer action 类型，协议转换层很难硬补。
6.5 选型建议
- 刚接触、想要图形化界面、主要用国产模型 → EchoBird；
- 追求灵活性、需要 fallback chain / 多 Key 管理、愿意调参 → CC-Switch（绝大多数人的默认路线）；
- Codex 桌面版重度用户、想要 Timeline 等增强 → Codex++（配合 CC-Switch）；
- 团队降本推荐组合：EchoBird 日常 + CC-Switch 备用；轻量任务走 DeepSeek，复杂工程用 GPT 做整体规划、子任务交给国产模型——混搭下来月支出可省约 60%。
⚠️ 以上三个均为社区开源项目，功能与版本持续变化；模型可用性、价格与能力边界以各项目仓库和模型服务商实时信息为准。GPT 订阅额度够用的话，原生体验最稳定。
七、第一次跑通 + 常见报错
新建空目录测试：
mkdir codex-test && cd codex-test
codex进入交互模式后试一句最简单的：
写一个 Python 的 fibonacci(n) 函数，要求带类型注解和单测能拉起一次完整流程（拉上下文 → 写文件 → 跑测试），说明网络和模型都通了。
最常见的三个报错：
| 报错 | 原因与排查 |
|---|---|
401 Unauthorized | 99% 是环境变量没加载：echo $OFOXAI_API_KEY（Windows 是 echo $env:OFOXAI_API_KEY）输出为空就 source 一下配置；也可能是 Key 拼错 |
404 - Endpoint not found / invalid endpoint | base_url 写错或末尾多了 /；或 wire_api 配成了已弃用的 "chat"，改成 "responses" |
model not found / invalid_model | 模型 ID 大小写或格式错误；或该模型不在你账户可用列表里，先换服务商提供的其他 Codex 模型顶一下 |
八、桌面应用 vs CLI，Windows 原生 vs WSL2
桌面应用 vs CLI：要图形界面、可视化操作项目，用桌面应用；要终端里轻量、脚本化、和编辑器/终端工作流配合，用 CLI。两者可以共存，不是二选一。
Windows 原生 vs WSL2：桌面应用默认使用 Windows 原生 agent（PowerShell 执行命令），也可以在设置里切到 WSL（切换后需重启应用生效）。注意 WSL1 从 Codex 0.115 起不再受支持，应使用 WSL2。
安全上，发送任务前可在输入框下方选择 Ask for approval 启用沙箱保护；Full access 会扩大 Codex 可访问范围，只在明确理解风险时使用。
九、常见问题
Q：Windows 安装器为什么只有约 1.4 MB？ 它是网页引导安装器，会在安装过程中获取完整应用。需要企业或离线部署时，改用与设备架构匹配的官方 MSIX。
Q：Windows x64 和 Arm64 应该选哪个？ 绝大多数 Intel / AMD 电脑选 x64；Snapdragon 等 Arm Windows 设备选 Arm64。可在”设置 → 系统 → 系统信息 → 系统类型”确认。
Q：macOS 应该选 Apple Silicon 还是 Intel？ “苹果菜单 → 关于本机”里显示 Apple M 系列芯片选 Apple Silicon，显示 Intel 处理器选 Intel。
Q：能用 API Key 登录吗？ 可以。API Key 适用于本地 Codex 工作，按 API 用量计费，部分依赖 ChatGPT 工作区或云服务的功能会受限；日常个人使用通常优先选 ChatGPT 账号。
Q：国产模型接入后，Codex 的插件和 Computer Use 还能用吗？ 插件体系部分场景可降级使用；Image Gen 与 Computer Use 强依赖 OpenAI 私有能力，切到国产模型后基本无法对等替代，详见第六节能力兼容性。
十、只认这些官方来源
| 域名 | 用途 |
|---|---|
developers.openai.com | OpenAI 官方 Codex 文档 |
learn.chatgpt.com | OpenAI 官方 ChatGPT / Codex 文档当前站点 |
persistent.oaistatic.com | OpenAI 官方安装包静态资源 |
get.microsoft.com | Microsoft 官方网页安装器 |
chatgpt.com | ChatGPT 与 Codex 官方服务 |
github.com/openai/codex | OpenAI Codex 开源仓库 / Releases |
再次强调：Codex 可以访问本地项目并执行命令，篡改过的客户端可能造成登录凭证、源代码和本地文件泄露。从官方渠道安装，别省这一步。
本文整理自 OpenAI / Microsoft 官方安装说明与社区实践（含国内网关与国产大模型接入方案），信息核对时间 2026-08；具体版本、模型 ID 与命令以官方文档 / 服务商页面实时显示为准。