六三门我最近把日常的代码审查和批量重构工作流彻底切到了 OpenAI Codex 上。这个由 OpenAI 开源的终端编程助手，配合 gpt-5.3-codex、gpt-5.4 这类最新模型，可以直接在 Windows、macOS、Linux 三个平台跑起来，等于在你的终端里多了一个能读懂整个工程上下文的结对程序员。这篇文章不打算讲 PPT 式的功能介绍，我会把从安装、认证、模型配置到日常使用的完整过程过一遍，特别是国内网络环境下怎么减少“装一半卡住”的尴尬，以及三平台各自需要注意的细节。不管你是第一次接触 Codex，还是已经在用但想切到新模型，这份指南都能直接照做。
1. 项目概览：Codex 到底是什么，解决什么问题
1.1 Codex CLI 的核心定位
Codex 是 OpenAI 开源的终端 AI 编程工具，官方仓库在 github.com/openai/codex。和 ChatGPT 网页端里那种“你贴一段代码、它给一段回答”的用法完全不同，Codex 是直接跑在你本地项目目录里的。它会自己读取项目结构、查看相关文件、分析报错日志，然后给出修改方案，并且在你的确认下直接动手改文件、执行命令。
这个定位非常像“驻场程序员”而不是“问答机器人”。比如你面对一个几万行的老项目，想快速定位某个接口被谁调用了、把某个 deprecated API 的调用点全部替换掉，又或者需要修复 CI 上某个莫名其妙的编译错误，这类需要“理解上下文+多文件操作”的任务正好是 Codex 的强项。
安装方式上，Codex 提供了多种渠道支持三平台。核心代码用 Rust 写的，天然有跨平台优势，所以 Windows、macOS、Linux 下都能拿到同样的体验，而不是像某些开发工具只在 macOS 上表现完美。这一点对需要同时维护多台开发机的人来说特别关键，我自己的主力机是 macOS，但公司办公机是 Windows，家里还有台 Linux 服务器，三套环境都用 Codex，配置文件直接同步过去基本无缝切换。
1.2 为什么会需要 gpt-5.3-codex 和 gpt-5.4 这类新模型
Codex CLI 本身是一个框架，真正决定它聪明不聪明的是背后跑的模型。OpenAI 针对 Codex 场景专门做了模型版本体系，这就是标题里提到的 gpt-5.3-codex 和 gpt-5.4。
这两个模型和普通 ChatGPT 模型的最大区别在于，它们针对“工具调用”和“长上下文工程理解”做了专门优化。什么叫工具调用？就是模型不只是生成代码文本，而是会主动请求执行 shell 命令、修改多个文件、读取目录结构，然后根据执行结果继续调整策略。如果模型缺少这个能力，CLI 工具做得再好也只是个“高级代码补全”，谈不上真正的自主编程。
gpt-5.3-codex 和 gpt-5.4 相比上一代，最直观的提升是上下文窗口更大、多文件追踪能力更强。实测下来，让它处理一个中型项目（几百个文件的仓库）时，它能更准确地记住哪些文件已经改过、哪些还没动，不会像老版本那样改着改着就突然忘了前面的操作。如果你在用 Codex 时觉得模型“太蠢”，先看看配置里用的是不是旧模型，很多时候不是工具不好，是模型版本没跟上。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 安装前的前置准备与环境确认
2.1 认证方式准备：ChatGPT 账号与 API Key
安装 Codex 之前，先把认证方式想清楚，因为这决定了你后续用哪种登录流程。Codex 支持两种认证：
第一种是 ChatGPT 账号登录。适用于 ChatGPT Plus、Pro 或 Team 订阅用户。在终端执行 codex login 后会弹出浏览器窗口，授权你的 ChatGPT 账号即可。这种方式的好处是订阅费里已经包含了 Codex 使用额度，不需要额外按量付费，对于重度使用者来说性价比更高。
第二种是 OpenAI API Key。开发者需要在 OpenAI 平台后台创建 API Key，然后通过环境变量 OPENAI_API_KEY 暴露给 Codex。这种方式的计费是按 token 走的，适合有明确预算控制、或者需要通过 API 做自动化流水线集成的场景。
国内用户要特别留意一个前置条件：OpenAI 的服务本身对你的网络环境有访问要求。如果你发现安装完成后执行 codex 一直报网络错误、登录页面打不开、或者请求超时，先确认你的网络环境是否能够正常访问 OpenAI 相关服务，这一步属于外部前置条件，任何安装技巧都绕不开它。先确保网络可达，再谈后续配置。
2.2 开发机依赖检查：Node.js 与 Git
Codex 的安装入口主要走 npm，所以 Node.js 是必须的。建议安装 Node.js 18 或更高版本，我自己用的 Node.js 20 LTS，目前运行稳定。Windows 用户直接去 nodejs.org 下载安装包即可，macOS 用户建议用 Homebrew 安装 node，Linux 用户可以用 NodeSource 源或者系统包管理器。
检查是否安装成功，在终端执行：
bash复制node -v
npm -v
能正常输出版本号就说明基础环境没问题。另外建议把 Git 装上，虽然 Codex 不强制要求项目是 Git 仓库，但有 Git 做版本管理，Codex 改坏代码时你能轻松回滚，这个习惯在让 AI 修改代码时特别重要，等于给自己留了后路。
Rust 工具链并不是安装 Codex 的必需项，只有当你选择源码编译安装时才需要。如果你想省事，直接用 npm 安装就行，下面的章节我会把每种情况都讲清楚。
3. Windows 平台安装配置完整流程
3.1 原生 Windows 安装：npm 全局安装方式
Windows 原生安装其实不复杂，核心就是通过 npm 全局安装。首先以管理员身份打开 PowerShell（注意是 PowerShell，不是 CMD，后面配置环境变量更方便），然后执行：
powershell复制npm install -g @openai/codex
安装完成后，验证是否成功：
powershell复制codex --version
如果出现版本号（比如 0.x.x），说明装好了。这里有个国内用户容易踩的坑：npm 默认源下载速度可能很慢，执行安装命令时半天没反应。你可以先检查 npm 源配置，如果速度太慢，可以临时切换到国内镜像源，装完 Codex 后再换回来。具体命令是：
powershell复制npm config get registry
如果显示的不是官方源，说明之前可能已经改过镜像。改回官方源用：
powershell复制npm config set registry https://registry.npmjs.org/
装完 Codex 后，第一次运行建议直接在 PowerShell 里执行 codex，看到交互式界面就说明原生 Windows 安装成功。
3.2 推荐路线：WSL 方式安装与路径注意事项
虽然原生 Windows 能跑，但我在实际使用下来的感受是：WSL（Windows Subsystem for Linux）下的体验会更好。原因有几个：Codex 在执行 shell 命令时，很多操作假设的是 Linux 风格的路径和命令，在原生 Windows 下偶尔会有路径转义问题；WSL 里直接就是完整的 Linux 环境，沙箱执行命令也更加顺手。
在 WSL 里安装同样走 npm 路线，但先要装好 Node.js。以 Ubuntu 为例：
bash复制sudo apt update
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
然后：
bash复制sudo npm install -g @openai/codex
这里有个细节要注意：WSL 访问 Windows 盘符下的文件路径是 /mnt/c/...，但 Codex 在分析项目时，如果项目位于 Windows 文件系统（/mnt/c 下），文件监听和权限处理可能会变慢。我的建议是，把需要 Codex 操作的项目放在 WSL 自己的文件系统里（也就是 ~/ 目录下），然后在 Windows 里通过 \\wsl$\ 路径访问，这样两边都能操作，Codex 跑起来也更舒服。
3.3 Windows 桌面版情况说明
热词里提到“codex 桌面版 windows”，这里单独说一下。OpenAI 官方的 Codex 桌面应用目前处于逐步开放阶段，功能上主要是把 CLI 能力封装成图形界面，方便不习惯终端操作的人使用。但我的观点很明确：如果你看这篇文章是为了认真用 Codex，优先把 CLI 学好。原因很简单，桌面版的本质还是调用同一个底层引擎，而 CLI 能让你精确控制每次请求的模型、上下文和审批流程，这些在桌面版里要么被隐藏、要么被简化。等 CLI 玩熟了，桌面版对你来说就只是一个锦上添花的入口。
4. macOS 平台安装配置完整流程
4.1 Homebrew 方式安装
macOS 上安装 Codex，最顺手的途径是 Homebrew。先确保 Homebrew 已经装好，然后执行：
bash复制brew install codex
不过这里有一个细节需要留意：Homebrew 的 core 仓库里可能存在其他同名 formula 的冲突风险。如果你执行后提示冲突，可以使用官方的 tap 方式：
bash复制brew tap openai/codex
brew install openai/codex/codex
安装完成后，验证：
bash复制codex --version
Homebrew 方式的好处是安装包放在统一位置，后续升级方便，执行 brew upgrade codex 就能更新到最新版。如果你同时安装了 Node.js 环境，用 npm 安装也完全可行，两条路选一条就行。
4.2 npm 全局安装与目录权限问题
如果你更习惯 npm 生态，macOS 上也可以走：
bash复制npm install -g @openai/codex
但这里有个 macOS 特有的坑：全局 npm 包默认安装在 /usr/local/lib/node_modules 或 /opt/homebrew/lib/node_modules，这些目录通常需要管理员权限。如果安装时报 EACCES 权限错误，很多人第一反应是加 sudo，但我不推荐直接把 npm 全局权限交给 sudo，因为后续用 npm 管理全局包时每次都提心吊胆。
更好的做法是配置用户级 npm 目录。在终端执行：
bash复制mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
然后把 ~/.npm-global/bin 加到 PATH 里。以 zsh 为例，编辑 ~/.zshrc：
bash复制export PATH=~/.npm-global/bin:$PATH
重新加载配置后，再执行 npm install 就不需要 sudo 了。这是我个人推荐的方式，干净、可控、不污染系统目录。
4.3 macOS 首次认证与系统安全设置
macOS 上安装完 Codex 后，首次执行 codex login 会启动浏览器进行授权。这里有一个很多新手会卡住的地方：浏览器弹窗显示“若要打开此 app，你需要从‘macOS 恢复’启动 Mac，并将‘安全策略’更改为‘完整安全’”，或者提示无法验证开发者。
这种情况通常不是 Codex 本身的问题，而是 macOS Gatekeeper 对下载的二进制程序的默认拦截。处理办法是在“系统设置 - 隐私与安全性”里，找到对应的拦截记录，点击“仍然允许”。如果是在浏览器里跳转授权链接时被拦住，确认默认浏览器是否是受支持的 Chrome、Safari 或 Edge，某些轻量级浏览器可能无法正确唤起本地回调，导致 codex login 一直卡在“等待授权”。
另外 macOS 用户普遍会遇到“系统数据占用过大”的问题，如果你在安装 Node.js、Homebrew 和 Codex 后发现磁盘空间告急，多半是 Homebrew 缓存和旧版本 node_modules 累积导致的。执行：
bash复制brew cleanup
能清理掉 Homebrew 留下的旧版本安装包，释放不少空间。这个操作无关 Codex 本身，但三平台里 macOS 用户最容易因为这类空间问题焦头烂额，顺手提一下。
5. Linux 平台安装配置完整流程
5.1 基于 npm 的通用安装方式
Linux 是最接近 Codex 理想运行环境的平台，安装也最简单。只要 Node.js 装好了，一条命令搞定：
bash复制sudo npm install -g @openai/codex
CentOS、Ubuntu、Debian 这些主流发行版都适用。国内 Linux 用户有一点要特别注意：如果你的系统是 CentOS 系的，自带的 Node.js 版本往往比较老（可能还是 10.x 甚至更低），Codex 对 Node 版本有要求，装完才发现跑不起来就很尴尬。建议先从 NodeSource 装一个新版 Node.js 再执行安装，不要用系统自带的远古版本。
bash复制# Ubuntu/Debian 示例
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
5.2 二进制包离线安装方式
有些公司的 Linux 开发机不能直接访问外网下载 npm 包，或者你希望跳过 Node.js 依赖直接拿到可执行文件，这时候可以用 GitHub Releases 里的二进制包。
在官方仓库的 Releases 页面下载对应架构的 .tar.gz 包。以 x86_64 Linux 为例：
bash复制wget https://github.com/openai/codex/releases/download/你的版本/codex-你的版本-x86_64-unknown-linux-gnu.tar.gz
tar -xzf codex-你的版本-x86_64-unknown-linux-gnu.tar.gz
sudo mv codex /usr/local/bin/
把可执行文件放到 /usr/local/bin 后，执行 codex --version 验证。这种方式的优势是干净，完全不依赖 Node.js 运行时，适合对系统环境有洁癖的人。需要注意，Linux 下如果执行时提示权限不足，记得给文件加执行权限：chmod +x /usr/local/bin/codex。
5.3 源码编译安装：什么情况下才需要
源码编译属于最后手段，一般只有这三种情况才值得考虑：官方没有提供你要的架构二进制包（比如 arm64 的某些特殊发行版）；你需要修改 Codex 源码并调试；你单纯想验证最新 commit 的功能。
源码安装依赖 Rust 工具链，先安装 rustup：
bash复制curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
然后克隆仓库并编译：
bash复制git clone https://github.com/openai/codex.git
cd codex
cargo build --release
编译产物在 target/release/codex，你可以把它复制到 /usr/local/bin。整个过程会下载大量 Rust 依赖包，国内网络条件不好的话耗时可能很长，而且 Cargo 默认源访问不稳定，建议提前配置国内镜像源再编译。但说实话，对绝大多数使用者来说，npm 或二进制包已经足够，源码编译更多是折腾的意义。
6. 核心配置详解：模型选择与认证参数
6.1 config.toml 配置文件详解
Codex 的配置信息统一存放在 ~/.codex/config.toml。这个文件在第一次运行时自动生成，如果不存在，手动创建即可。完整的基础配置长这样：
toml复制model = "gpt-5.4-codex"
model_provider = "openai"
[model_providers.openai]
name = "OpenAI"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
这个配置表的核心是 model 和 model_provider。前者指定默认模型，后者指定模型服务商，默认是 OpenAI 官方，但 Codex 的设计允许你接入兼容 OpenAI API 格式的其他服务商，只需要在 [model_providers.xxx] 里填写对应的 base_url 和 env_key。如果你只是想用官方模型，保持默认即可，不用动 providers 部分。
另外还有一个 approval_policy 参数值得关注。它控制 Codex 在执行命令时是否需要你二次确认，可选的三个值分别是：
| 参数值 | 行为说明 | 适用场景 |
|---|---|---|
untrusted |
修改文件前需要逐一确认 | 默认值，适合日常开发 |
on-request |
只在用户主动要求时才执行命令 | 严格受控场景 |
on-failure |
命令失败后才进入人工确认 | 自动化批处理 |
我建议保持 untrusted，尤其是刚开始用的时候。等你对 Codex 的行为模式足够熟悉、工程又有完善的版本控制，再考虑放宽策略。
6.2 认证方式的配置与切换
Codex 的认证状态存储在 ~/.codex/auth.json，通过 codex login 命令写入。如果你用的是 ChatGPT 账号登录，认证完成后 auth.json 里会包含会话凭据；如果你用 API Key，通常不依赖这个文件，而是靠环境变量。
环境变量的配置方式三平台略有区别。Linux/macOS 在 ~/.bashrc 或 ~/.zshrc 里写：
bash复制export OPENAI_API_KEY="sk-你的key"
Windows 在 PowerShell 里执行：
powershell复制$env:OPENAI_API_KEY="sk-你的key"
或者通过“系统属性 - 环境变量”长期设置。两种认证方式可以共存，Codex 会优先读取环境变量中的 API Key，没有才回退到登录凭据。我个人的建议是：日常交互用 ChatGPT 登录，因为它不耗 API 额度；自动化脚本和 CI 里用 API Key，因为它是非交互式认证，便于在服务器上无人工干预地运行。
6.3 模型版本说明：gpt-5.3-codex 与 gpt-5.4 怎么选
这是很多人真正关心的问题。现在 Codex 支持的模型里，标题里提到的两个版本是最新一批，但选哪个取决于你的使用场景。
gpt-5.3-codex 的特点是稳定。它在代码理解、重构、Bug 修复这些常规任务上表现非常均衡，响应速度也快，适合作为日常默认模型。我用它处理了几个中型项目的依赖升级，整个过程中上下文连贯性保持得很好，没有出现中途“失忆”的情况。
gpt-5.4 则是在复杂任务上更进一步。如果你要处理的是跨多个模块的大型重构、从零生成一个完整项目骨架、或者需要同时追踪十几个文件的改动，gpt-5.4 的理解深度和多文件协同能力更强。代价是响应延迟稍高，token 消耗也更大。如果你用 ChatGPT 订阅登录，用量限制要留意；如果走 API Key 计费，成本也要提前评估。
我的选择策略很简单：日常增删改查用 gpt-5.3-codex，涉及架构级调整或大范围重构时临时切到 gpt-5.4。切换方式不需要改配置文件，在交互式会话里直接输入：
bash复制/model gpt-5.4-codex
就能动态切换，非常方便。
7. 日常使用实战与效率技巧
7.1 交互式会话模式
在项目目录下直接执行 codex，就进入了交互式 REPL 模式。这个模式跟对话类似，但 Codex 能看到你当前目录的文件结构。你可以在输入框里写：
code复制这个项目里所有调用 getOldData() 的位置都改成 getNewData()，并同步更新对应的返回类型
Codex 会列出它计划修改的文件列表和原因，然后等你确认。确认之后逐个文件应用修改，每改完一个文件，你都可以通过 diff 检查改动内容。这个模式适合需要反复沟通、逐步修正的任务，也是新手入门最友好的方式。
我在实际使用中有一个习惯：进入交互模式前，先让 Codex 读一遍 README 和项目结构，用一句话告诉它“先了解一下这个项目的架构，再回答我的问题”。这样后续请求的上下文质量会高很多，特别是面对陌生仓库时。
7.2 非交互命令行模式
如果你已经把任务描述得很清楚，不需要来回沟通，可以直接用非交互模式。执行：
bash复制codex exec "在 src/utils 下新增一个 debounce 函数，并补上单元测试"
exec 会直接运行，不会进入交互界面。还有一个更实用的组合是 codex apply，它会直接应用文件的修改而不逐步询问（前提是文件改动在审批策略允许范围内）。这个模式特别适合批量处理重复性任务，比如批量格式化代码、批量替换废弃 API 调用：
bash复制codex exec --skip-git-repo-check "扫描整个项目，找出所有 TODO 注释，按优先级生成一个 issues.md"
非交互模式配合 --json 输出，还能把 Codex 的响应解析到自己的脚本里，做成自动化工具链的一环。
7.3 沙箱模式与文件系统安全
Codex 默认带沙箱机制，它限制模型执行的命令只能落在特定范围内，减少“AI 乱删文件”的风险。在 config.toml 里可以通过 sandbox_mode 控制沙箱级别：
| 模式 | 说明 | 风险等级 |
|---|---|---|
read-only |
只允许读文件，禁止修改 | 低 |
workspace-write |
允许修改当前工作目录 | 中 |
dangerously-bypass-approvals-and-sandbox |
跳过所有确认和沙箱限制 | 高 |
我的建议是日常保持 workspace-write，让 Codex 能正常工作，但在它准备修改文件时仍然会让你确认。只有在非常明确任务动作、且有完整版本管理兜底的情况下，才考虑完全绕过沙箱。毕竟 Codex 最终是概率模型，再聪明也可能有理解偏差，自己的代码得有最后一层防线。
7.4 项目管理中的最佳实践
用了一段时间 Codex 后，我发现它有自己偏好的工作节奏。以下这些经验是从多次实际项目中总结出来的：
第一，任务分解要细。别指望它一口气完成“重构整个项目”这种大指令，而是拆成“先梳理模块边界”“再列出重构方案”“最后逐个模块迁移”这样的小步骤。每一步确认后再进入下一步，出错的概率会小很多。
第二，善用 git 分支隔离。每次让 Codex 做大规模修改前，新建一个分支：git checkout -b codex-refactor。这样无论改动是否合理，都不会影响主分支。
第三，把项目文档喂给它。Codex 能读文件，不代表它理解你的业务约定。如果项目里有架构说明文档或代码规范，先在会话里提醒它“先读 docs/architecture.md，再回答问题”，效果会明显更好。
8. 常见问题与排查技巧实录
8.1 安装阶段的典型问题
安装阶段碰到最多的问题集中在三个方面：npm 安装超时、Node 版本过低、Windows 下路径权限异常。
npm 安装超时的解决办法上面提过，优先检查镜像源和网络。Node 版本过低会导致安装报 engine 错误，直接升级 Node 版本即可。Windows 下如果执行 codex 提示“无法加载文件，因为在此系统上禁止运行脚本”，原因是 PowerShell 的执行策略限制，在管理员 PowerShell 里执行：
powershell复制Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
就能解决。
8.2 登录认证相关问题
codex login 最常见的失败原因是浏览器没有成功跳转回本地服务。Codex 的登录流程是：终端启动本地临时 HTTP 服务，浏览器完成授权后重定向到 localhost 回调。如果你的浏览器设置了严格隐私拦截、或者系统防火墙阻止了对本地端口的访问，就会一直卡在“等待回调”。
排查思路是：先看终端有没有输出一个 http://localhost:xxxx/ 的链接，手动打开看能否访问；再检查命令行里是否有报错 callback address already in use，如果有，换个端口重试即可。另外，如果你在 config.toml 里配置了自定义 base_url，注意是否与官方认证服务器不匹配，这种情况下登录会被重定向到错误地址。
8.3 运行中的模型与性能问题
Codex 运行中偶尔会遇到响应变慢、上下文丢失、输出截断等问题。我的排查经验是按顺序排查三层：
第一层是模型选择。确认当前用的是不是最新模型，如果配置还停在 gpt-5.3-codex 之前的旧版本，能力差异会非常明显。第二层是网络延迟。Codex 的每次请求都是实时的，如果你网络到 OpenAI 服务的延迟很高，交互体验会非常卡顿，这种情况下提高本地网络质量比什么都管用。第三层是任务复杂度。如果项目文件太多、上下文太大，模型的处理速度必然下降，这时尝试把任务拆小，或者用 /compact 压缩当前会话的上下文。
8.4 我踩过几次坑之后留下的最终建议
如果你问我，用 Codex 最值得记住的一条经验是什么，我的回答是：永远把 Codex 当成一个能力很强但需要监督的同事，而不是全自动的代码机器。它会用各种方式帮你把活干完，但你需要确认它走的路径正确、改的范围合理、没有破坏已有行为。这听起来像老生常谈，但只有当你在生产仓库里被它“带偏”过一次，才会真正理解版本管理、审批机制和任务拆分的意义。
另一个小技巧：把 Codex 接入到你的日常命令流里，而不是只在“写代码”时想它。我经常用它做仓库分析、依赖检查、命令生成这些边角料工作，比如忘记一条 find 命令怎么组合时直接问它，反而让整个开发效率提升非常明显。工具就是这样，用得越顺手，价值越能被挖掘出来。