Codex 实战指南:从安装到使用教程

它是 OpenAI 官方出的命令行编程 Agent，和 ChatGPT 账号直通（Plus / Pro / Business / Edu / Enterprise 都能用），背后跑的是 GPT-5-Codex 这条专门给编程优化的模型线。

跟 Claude Code 比，Codex 有几个明显特点：

• 登录即用：不用单独申请 API Key，直接用 ChatGPT 账号登

• 沙箱默认安全：除非显式开 --yolo，否则改动都在沙箱里

• 专门优化的代码模型：在 SWE-bench 之类的编程评测上跑得很猛

• 支持并行：配合 git worktree 可以同时跑多个 Codex 修不同的 Bug

下面把我自己摸索的完整流程整理出来，从安装到高级用法。

一、安装：macOS / Linux / Windows 全平台都支持

macOS / Linux

最快的是官方一键脚本，npm 全局安装也很常见，Mac 用户还可以走 Homebrew。

Windows

Windows 用户有两种方式：直接在 PowerShell 里跑官方脚本，或者用 npm。

Windows 用户强烈建议在 WSL2 里跑 Codex，原因有三：

1. 沙箱机制更完善——--full-auto 在原生 Windows 上偶尔会有兼容性问题，WSL 里和 Mac 体验一致

2. 路径处理省心——避免 Windows 反斜杠 \ 在 prompt 里被吞掉的尴尬

3. 终端渲染更好——Codex 的 TUI 界面在 PowerShell 7+ / Windows Terminal 下能看，但 CMD 里基本是乱码

如果你做 Web / Python / Node 项目，建议直接 wsl --install -d Ubuntu 切到 WSL2。如果是 .NET / C# / Unity 这种必须在原生 Windows 的项目，用 PowerShell 7+ 跑也能正常工作，只是个别交互会粗糙一点。

通用验证

装完不管哪个平台，都执行 codex --version 验证一下，能打印版本号就 OK。

一个所有平台共同的限制：Codex 必须在 git 仓库里运行，它会拒绝在非 git 目录启动。这是安全设计——所有改动都能被 git 追踪和回滚。Windows 用户需要先装 Git for Windows（或在 WSL 里自带）。

二、首次启动：登录 ChatGPT

第一次跑 codex 会让你选登录方式。

强烈推荐选 Sign in with ChatGPT——不用管 API Key，浏览器跳出来登录一下，回到终端就能用。你的 ChatGPT 订阅额度直接覆盖 Codex 的调用。

如果你是企业内网或者用代理，也可以选 API Key 方式，需要在 ~/.codex/auth.json 里配置。

三、最常用的两种模式

模式一：交互模式（默认）

直接 codex 进去，像跟 ChatGPT 聊天一样描述需求，它会分析项目、规划改动、列出要改的文件，让你确认后再动手。

适合场景：新功能开发、复杂重构——你想看清每一步的人值得用这个模式。

模式二：exec 一次性任务

用 codex exec "你的需求" 跑完即退，适合脚本化、CI 集成、批处理。

三个关键标志要记住：

• 不加标志：每次改动都问你 (y/n)

• --full-auto：沙箱内的修改自动同意，跑得快还安全（日常推荐）

• --yolo：完全无沙箱无确认，最快但最危险（只在 worktree 隔离环境里用）

需要在非 git 目录里玩一下？一行命令搭临时仓库：cd $(mktemp -d) && git init && codex exec "你的任务"。

四、Code Review：让 Codex 当你的代码审查员

这是 Codex 一个被低估的能力。

切到 PR 分支后跑 codex review --base origin/main，它会用主分支做基线，把当前分支的 diff 全部扫一遍，按风险等级给出意见。

我的实测体验：它对安全问题（SQL 注入、XSS、未处理的 Promise reject）特别敏感，比人工 review 还要细。建议在团队里设成 PR 流程的第一道关，过了 Codex 再走人肉 review。

五、进阶玩法：并行批量修 Bug

这是 Codex 真正能拉开效率的地方。

假设你 backlog 里堆了 5 个独立的 Bug 要修，传统做法是一个个改，每个都要切分支、写代码、跑测试。用 Codex + git worktree 可以同时开 5 个进程并行干。

核心思路：

1. 用 git worktree add 给每个 Issue 开一个独立工作目录（不是 branch，是物理隔离的目录）

2. 在每个目录里启一个 Codex 进程（不同终端窗口 / tmux 面板）

3. 它们互不干扰，并行修改、并行 commit

4. 全部跑完后统一 push + 提 PR

我用这套流程一晚上清掉过 6 个长期没人接的小 Bug。前提是 Issue 之间没有依赖关系——如果有依赖，串行更稳。

六、配置文件：让 Codex 跑得更顺手

Codex 的配置在 ~/.codex/config.toml。

几个高频参数：

• model：默认 gpt-5-codex，也可以切到 gpt-5 或其他 OpenAI 模型

• approval_mode：suggest（每步问）/ auto-edit（沙箱内自动）/ full-auto（完全自动）

• sandbox：沙箱级别，workspace-write 是默认值，限制 Codex 只能改当前项目目录

命令行临时覆盖：codex --model gpt-5 --cwd ~/another-project。

七、Codex vs Claude Code：怎么选？

实际用下来我的判断：

• 如果你已经付了 ChatGPT Plus 订阅：Codex 几乎是"免费送"的，先用它。模型质量在 OpenAI 这边持续迭代，GPT-5-Codex 专门为代码优化过。

• 如果你重度依赖 Anthropic 的长上下文：Claude Code 在超长代码库（几十万行）的理解上仍有优势，复杂跨文件重构更稳。

• 两个都装也行：它们配置文件互不冲突，可以根据任务切换。我自己的习惯是——日常小改用 Codex（开 --full-auto），大型重构用 Claude Code。

八、几个踩坑提醒

1. 必须在 git 仓库里运行——临时实验用 mktemp -d && git init 绕过

2. --yolo 慎用——它会绕过所有沙箱保护，建议只在 worktree 隔离环境用

3. 大型项目首次启动会慢——Codex 要建索引，等几十秒是正常的

4. 并行跑多进程时注意 ChatGPT 限流——Plus 账号有调用频率上限，跑超过 4 个进程容易触发

结语

Codex 不是来取代你写代码的，它是来处理那些"我知道怎么改但懒得写"的部分。

最大化它的价值，靠的不是问出多花哨的需求，而是把任务切得足够小、足够具体——一个 Issue 一个目标，一次任务一个改动。

切得越细，Agent 跑得越准。这条经验对 Codex、Claude Code、所有 Coding Agent 都适用。