从 5 分钟上手到满血全自动编程
这不是又一篇"AI 编程工具测评"。这是你读完就能开始干活的操作手册。
一、为什么是 Codex，而不是别的
2025 年 4 月，OpenAI 干了一件大事：把 Codex CLI 以 Apache 2.0 协议开源了。
这意味着什么？意味着你拿到的不是一个"黑盒云服务"，而是一个可审计、可定制、可本地运行的编程 Agent。它直接在你的终端里读文件、改代码、跑命令------像坐在你旁边的同事，而不是电话那头的顾问。
和同类工具的核心区别：
| 维度 | Codex CLI | Claude Code | Cursor | GitHub Copilot |
|---|---|---|---|---|
| 开源 | ✅ Apache 2.0（Rust 实现） | ❌ | ❌ | ❌ |
| 运行形态 | 终端 CLI + 桌面 App | 终端 CLI | IDE | IDE 插件 |
| 审批模式 | 3 档精细控制 | 3 档 | 可视化确认 | 补全为主 |
| MCP 支持 | ✅ STDIO + HTTP | ✅ | 部分 | 有限 |
| 多 Agent | ✅ 实验性（Git worktree 并行） | Task 工具 | ❌ | ❌ |
| 免费额度 | ChatGPT Plus 含 5 API / Pro 含 50 | Pro $17/月 | $20/月 | $10/月 |
一句话选型建议：习惯终端 + OpenAI 生态 → Codex CLI；习惯终端 + Anthropic 生态 → Claude Code；不碰终端 → Cursor。想要开源可审计 → Codex CLI 是唯一选项。
GitHub 已获 83.9k Stars，这不是闹着玩的。
二、5 分钟快速上手
第 1 步：安装（选一种就行）
bash
# 方式 A：npm 全局安装（推荐，需 Node.js 22+）
npm install -g @openai/codex
# 方式 B：Homebrew（macOS）
brew install --cask codex
# 方式 C：一键脚本（macOS/Linux，无需 Node）
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# 方式 D：直接下二进制（适合服务器/CI）
# 去 GitHub Releases 下载对应平台的 tar.gz验证安装：
bash
codex --version
# 输出版本号说明 OK第 2 步：认证（二选一）
方式一：ChatGPT 账号（推荐新手）
bash
codex
# 首次启动会提示 Sign in with ChatGPT
# 浏览器打开授权页面，点一下就行支持的计划：Plus（20/月，含 5 API 额度）、Pro（200/月，含 50 额度）、Team/Business/Enterprise。
方式二：API Key（开发者/CI 推荐）
bash
# macOS / Linux
export OPENAI_API_KEY="sk-你的Key"
# 永久写入
echo 'export OPENAI_API_KEY="sk-你的Key"' >> ~/.zshrc
source ~/.zshrc
# Windows PowerShell
$env:OPENAI_API_KEY="sk-你的Key"第 3 步：跑通第一个任务
bash
# 进入你的项目目录
cd ~/projects/my-app
# 启动交互模式
codex
# 输入任务
> 帮我看看这个项目是做什么的Codex 会扫描目录结构、读源码、给你一份项目概览。这一步成功，说明链路完全打通了。
三、三大审批模式：Codex 的"安全旋钮"
这是 Codex 最核心的设计，必须搞懂。
模式对比
| 模式 | 命令 | 自动改文件 | 自动执行命令 | 适合场景 |
|---|---|---|---|---|
| suggest（默认） | codex |
❌ 只建议 | ❌ 只建议 | 新手入门、陌生代码库、不放心时 |
| auto-edit | codex -a auto-edit |
✅ | ❌ 需确认 | 熟悉项目、批量重构、低风险编辑 |
| full-auto | codex -a full-auto |
✅ | ✅ | 隔离环境测试、throwaway branch、CI |
新手铁律
suggest 入门 → 熟悉后切 auto-edit → 在 git 隔离分支中尝试 full-auto不要一上来就 full-auto。 先用 suggest 模式跑几个任务，观察 Codex 的行为模式，建立信任后再逐步放开权限。
full-auto 安全实践
bash
# 1. 先 commit 干净状态
git add -A && git commit -m "checkpoint before codex"
# 2. 创建隔离分支
git checkout -b codex/experiment
# 3. 全自动模式开干
codex -a full-auto "给所有函数添加类型注解"
# 4. 不满意？一键回滚
git checkout .
# 或 git checkout main && git branch -D codex/experimentfull-auto 的最终安全网就是 git。 只要你 commit 了干净状态，任何 AI 操作都可以回滚。
四、AGENTS.md：给 AI 一份"上岗说明书"
这是 Codex 区别于普通代码补全工具的关键能力。
作用机制
Codex 启动时会自动读取以下文件，构建指令链：
~/.codex/AGENTS.override.md ← 临时全局覆盖（最高优先级）
~/.codex/AGENTS.md ← 个人全局偏好
项目根目录/AGENTS.md ← 团队共享规则
子目录/AGENTS.md ← 模块级局部规则（覆盖父级）
当前目录/AGENTS.md ← 最终生效文件从根目录向下拼接，越靠近当前目录的越优先。每个文件最大 32 KiB。
实战模板
在项目根目录创建 AGENTS.md：
markdown
# 项目简介
基于 Next.js 14 + TypeScript 的电商后台管理系统。
# 目录约定
- `src/app/api/` --- 接口路由
- `src/components/` --- UI 组件（PascalCase 命名）
- `src/lib/db/` --- Drizzle 数据访问层
- `tests/` --- 测试文件（Vitest）
# 构建 / 测试 / Lint
- 启动：`pnpm dev`
- 测试：`pnpm test`（改完代码后必须跑）
- 类型检查：`pnpm typecheck`
- Lint：`pnpm lint --fix`
# 工程约束
- TypeScript strict mode
- DB 操作只走 Drizzle，禁止裸 SQL
- 提交前自动 lint，不要绕过 husky
# 不要做的事
- 不要修改 `src/legacy/` 目录
- 不要新增运行时依赖前不询问
- 不要跳过测试直接提交效果对比
| 指标 | 无 AGENTS.md | 有 AGENTS.md |
|---|---|---|
| 代码风格一致性 | 60% | 95% |
| 首次生成正确率 | 40% | 75% |
| 需要返工次数 | 3-5 次 | 0-1 次 |
| 新成员上手时间 | 2-3 天 | 半天 |
Override 文件：临时覆盖不改共享配置
markdown
<!-- ~/.codex/AGENTS.override.md -->
<!-- 临时：支付模块调试期间，每次改动后都跑支付测试 -->
临时覆盖：支付调试期间
- 修改 services/payments/ 下任何文件后，运行 make test-payments
- 专注 checkout 流程，忽略无关失败用完删掉就行，不影响团队的 AGENTS.md。
五、日常用法速查
交互模式（最常用）
bash
codex
# 进入全屏 TUI，像聊天一样输入任务
> 找出所有 TODO 注释，统计数量并生成报告
> 给 src/utils.py 添加日志装饰器
> 运行测试并修复失败的用例单次命令模式
bash
# 给任务描述，执行完退出
codex "在 README.md 中添加安装说明"
codex "找到所有 TODO 注释并生成报告"管道模式（强大但被低估）
bash
# 把错误日志喂给 Codex 分析
cat error.log | codex "分析这个错误日志，找出根本原因"
# 让 Codex 总结最近的提交
git diff HEAD~3 | codex "总结最近 3 次提交的改动"
# 分析项目结构
find . -name "*.py" | head -20 | codex "分析这个项目的文件结构"
# 修复已有代码
codex "给这段代码添加错误处理" < weather.py交互模式快捷键
| 快捷键 | 功能 |
|---|---|
Enter |
发送消息 |
Ctrl+C |
中断当前任务 |
Ctrl+D |
退出 Codex |
\ + Enter |
换行（多行输入） |
Ctrl+T |
查看 Codex 思考过程 |
交互命令
| 命令 | 功能 |
|---|---|
/model |
切换模型或调整推理级别 |
/diff |
查看当前变更 |
/undo |
撤销最近一次修改 |
/clear |
清空对话历史 |
/approvals |
动态调整权限级别 |
/review |
代码审查（对比 base 分支） |
/help |
帮助 |
六、提示词技巧：四元素模板
Codex 官方推荐的提示词结构：
Goal: 要做什么？要改什么？
Context: 涉及哪些文件、文档、错误信息？
Constraints: 约束有哪些？规范、架构、安全要求？
Done when: 完成判定条件是什么？实战示例
差的提示词：
给代码加个测试
好的提示词：
Goal: 给 src/auth/login.ts 的 loginUser 函数写单元测试
Context: 测试框架用 Vitest，测试文件放 tests/auth/login.test.ts
Constraints: 覆盖正常登录、密码错误、账号不存在、token 过期 4 个场景
Done when: 所有测试通过，覆盖率 ≥ 90%
差的提示词：
优化性能
好的提示词：
Goal: 优化 src/api/products.ts 的 getProductList 接口响应速度
Context: 当前平均响应 800ms，目标 < 200ms。数据库是 PostgreSQL，ORM 用 Drizzle
Constraints: 不改变 API 返回格式，不新增依赖
Done when: pnpm test 通过 + 本地基准测试响应 < 200ms
七、高级配置：config.toml 精细控制
全局配置在 ~/.codex/config.toml：
toml
# 默认模型
model = "gpt-5.3-codex"
# 默认审批策略
# untrusted（默认）：不信任的命令前提示
# never：完全信任，自动执行
# on-failure：沙箱失败后请求非沙箱重试
approval_policy = "untrusted"
# 沙箱模式
# read-only | workspace-write | danger-full-access
sandbox_mode = "workspace-write"
# Profile：为不同场景创建独立配置
[profiles.safe_mode]
model = "o4-mini"
approval_policy = "untrusted"
sandbox_mode = "read-only"
[profiles.full_power]
model = "gpt-5.3-codex"
approval_policy = "never"
sandbox_mode = "danger-full-access"
# MCP 服务器配置
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
[mcp_servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]使用 Profile：
bash
codex --profile safe_mode "审查这个 PR"
codex --profile full_power "重构整个 utils 目录"八、MCP 集成：让 Codex 连接一切
MCP（Model Context Protocol）让 Codex 超越纯代码编辑，连接外部工具和数据源。
常用 MCP 服务器
toml
# ~/.codex/config.toml
# GitHub：管理 PR、Issue
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
# PostgreSQL：直接查数据库
[mcp_servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]
# 文件系统：扩展文件操作
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
# Context7：实时文档查询
[mcp_servers.Context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp@latest"]MCP 实战场景
配置好 GitHub MCP 后，你可以直接对 Codex 说：
> 看看 #142 这个 PR 有什么问题，帮我写个 review 评论
> 把 issue #88 的描述提取出来，创建一个分支开始修复
> 列出所有待合并的 PR，按更新时间排序Codex 会自动调用 MCP 工具完成操作，不需要你手动切到浏览器。
九、Agent Skills：给 Codex 装技能包
Codex 支持 Skills 系统------打包好的指令+脚本，让 Codex 可靠地执行特定工作流。
Skill 是什么
my-skill/
├── SKILL.md # 必须：指令 + 元数据
├── scripts/ # 可选：可执行代码
├── references/ # 可选：参考文档
└── assets/ # 可选：模板、资源SKILL.md 格式：
markdown
---
name: deploy-staging
description: 部署到 staging 环境的完整流程。当用户说"部署到 staging"或"发预发"时触发。
---
# 部署到 Staging
1. 运行 `pnpm build` 构建生产包
2. 运行 `pnpm test` 确保测试通过
3. 执行 `./scripts/deploy-staging.sh`
4. 验证：curl https://staging.example.com/health
5. 如果失败，回滚到上一个版本Skill 存放位置
| 作用域 | 位置 | 用途 |
|---|---|---|
| 仓库级 | $CWD/.agents/skills |
当前项目专用 |
| 仓库根 | $REPO_ROOT/.agents/skills |
整个仓库共享 |
| 用户级 | $HOME/.agents/skills |
个人跨项目 |
| 系统级 | /etc/codex/skills |
机器/容器共享 |
| 内置 | 随 Codex 安装 | 所有用户可用 |
安装社区 Skills
$skill-installer linearCodex 会自动发现新安装的 Skills。
十、Codex Cloud：云端后台运行
除了本地 CLI，还有 Codex Web（chatgpt.com/codex），核心区别：
| 特性 | Codex CLI | Codex Web |
|---|---|---|
| 运行位置 | 本地终端 | OpenAI 云端 |
| 需要本地环境 | 是 | 否 |
| 任务执行 | 实时交互 | 后台异步，可关页面 |
| 适合任务 | 实时开发协作 | 长耗时任务（全量测试、大重构） |
| 文件访问 | 读写本地文件 | 连接 GitHub 仓库 |
Cloud Tasks（从 CLI 启动）
bash
# 在 CLI 中启动云端任务
codex cloud run "给整个项目添加类型注解并运行全量测试"
# 选择运行环境（Docker 沙箱）
# 任务在云端异步执行，完成后返回 diff
# 你可以关闭终端，任务继续跑适合耗时超过 30 分钟的大任务------本地终端不用一直开着。
十一、多 Agent 编排：高级玩法
Git Worktree 并行执行
Codex 支持在独立的 Git worktree 中并行运行多个 Agent，适合大规模重构：
bash
# 创建 3 个 worktree 并行处理不同模块
codex --worktree "重构 auth 模块" &
codex --worktree "重构 payment 模块" &
codex --worktree "重构 notification 模块" &
# 各自独立工作，互不干扰
# 完成后合并分支Codex 作为 MCP Server
Codex CLI 本身可以作为 MCP Server 运行，被其他 Agent 框架调用：
python
from agents import Agent, Runner
from agents.mcp import MCPServerStdio
async with MCPServerStdio(
name="Codex CLI",
params={
"command": "npx",
"args": ["-y", "codex", "mcp-server"],
},
) as codex_mcp_server:
developer = Agent(
name="Developer",
instructions="你是前端开发专家，用 Codex 工具实现需求",
mcp_servers=[codex_mcp_server],
)
result = await Runner.run(developer, "实现一个登录页面")这意味着你可以用 OpenAI Agents SDK 编排一个多角色团队：PM 拆任务 → Designer 出设计 → Frontend Dev 写前端 → Backend Dev 写接口 → Tester 验证。
十二、CI/CD 集成：Headless 模式
bash
# 非交互式执行，适合 CI/CD
codex exec "运行所有测试，如果失败就修复" --approval-mode full-auto
# GitHub Actions 示例
- name: Codex Review
run: |
codex exec "审查本次 PR 的改动，指出潜在问题" \
--approval-mode suggest \
--output-format json > review.jsonCodex Autofix
在 CI 中自动修复 lint/类型错误：
yaml
# .github/workflows/autofix.yml
- name: Run Codex Autofix
run: codex exec "修复所有 lint 和类型错误" -a full-auto
- name: Commit fixes
run: |
git config user.name "Codex Bot"
git add -A
git diff --staged --quiet || git commit -m "fix: auto-fix lint/type errors"十三、Codex vs 同类工具：真实场景对比
场景 1：给遗留项目补类型注解
| 工具 | 表现 |
|---|---|
| Codex CLI | codex -a auto-edit "给所有 .ts 文件添加类型注解" --- 全自动扫描+修改，5 分钟搞定 50 个文件 |
| Claude Code | 同样能做，但需要更多交互确认 |
| Cursor | 需要逐文件操作，效率低 |
| Copilot | 只能补全当前光标位置，无法批量操作 |
场景 2：从报错驱动修 Bug
bash
# 把报错信息喂给 Codex
cat error.log | codex "分析错误，找到根因，修复代码" -a auto-editCodex 会读报错 → 定位文件 → 分析原因 → 修改代码 → 跑测试验证。一个命令完成完整闭环。
场景 3：大规模重构
bash
# full-auto 模式 + git 隔离
git checkout -b refactor/cleanup
codex -a full-auto "消除所有重复代码，提取公共函数，更新所有引用"
git diff # 检查改动
git checkout main && git merge refactor/cleanup # 满意就合并十四、最佳实践 & 避坑清单
✅ 推荐做法
- 每次任务前先 git commit --- 这是 full-auto 模式的安全网
- 写好 AGENTS.md --- 投入 30 分钟，节省数十小时返工
- 用四元素提示词 --- Goal + Context + Constraints + Done when
- 善用管道模式 ---
cat error.log | codex "分析"比复制粘贴高效 10 倍 - 配置 Profile --- safe_mode 审查、full_power 重构，一键切换
- Ctrl+T 看思考过程 --- 验证 Codex 是否正确理解了你的意图
- 定期更新 ---
npm install -g @openai/codex@latest，迭代很快 - 用 .codexignore 排除噪声 --- 和 .gitignore 类似，排除生成文件、node_modules 等
❌ 常见坑
- 一上来就 full-auto --- 没建立信任就全放开，改错了都不知道
- 不写 AGENTS.md --- Codex 不知道你的项目规范，生成的代码风格不一致
- 提示词太模糊 --- "优化性能"不如"把 getProductList 响应从 800ms 降到 200ms"
- 让 Codex 处理安全敏感代码 --- 鉴权、加密、权限判断必须人审
- 在非 git 目录跑 full-auto --- 没有回滚保障，改坏了哭都来不及
- 不跑测试就提交 --- Codex 给的是"很可能合理的变更"，不是"已证明等价"
- API Key 提交到 Git --- 用环境变量，不要写死在代码里
十五、模型选择指南
| 模型 | 特点 | 适合场景 |
|---|---|---|
gpt-5.3-codex |
默认，代码专项优化 | 日常开发（推荐） |
gpt-5.3-codex-spark |
更快，Pro 专属 | 简单任务、快速迭代 |
o4-mini |
性价比之王 | 批量操作、CI |
o3 |
最强推理 | 复杂架构设计、算法实现 |
gpt-4.1 |
强力综合 | 需要非代码推理时 |
切换模型：
bash
# 命令行指定
codex -m o3 "设计一个分布式锁的实现方案"
# 交互模式切换
/model o3
# 配置文件默认
# ~/.codex/config.toml
model = "gpt-5.3-codex"十六、满血配置：一键启动最强 Codex
在 ~/.zshrc 或 ~/.bashrc 中添加别名：
bash
alias codex-power='codex -m gpt-5.3-codex \
-c model_reasoning_effort="high" \
-c model_reasoning_summary_format=experimental \
--search \
--dangerously-bypass-approvals-and-sandbox'⚠️
--dangerously-bypass-approvals-and-sandbox会跳过所有安全检查，仅在可信环境 + git 隔离分支中使用。
保存后 source ~/.zshrc，以后输入 codex-power 就是满血启动。
十七、速查卡（打印贴桌上）
┌─────────────────────────────────────────────────────┐
│ CODEX CLI 速查卡 │
├─────────────────────────────────────────────────────┤
│ │
│ 安装: npm i -g @openai/codex │
│ Key: export OPENAI_API_KEY="sk-..." │
│ │
│ 基本用法: │
│ codex # 交互模式 │
│ codex "任务描述" # 单次任务 │
│ cat file | codex "分析" # 管道输入 │
│ │
│ 审批模式 (-a): │
│ suggest → 只建议，不动手 │
│ auto-edit → 自动改文件，命令要确认 │
│ full-auto → 全自动（⚠️ 沙箱内 + git 隔离） │
│ │
│ 模型 (-m): │
│ gpt-5.3-codex → 默认，代码优化 │
│ o4-mini → 性价比 │
│ o3 → 最强推理 │
│ │
│ 配置文件: │
│ ~/.codex/config.toml # 全局配置 │
│ ~/.codex/AGENTS.md # 全局指令 │
│ 项目/AGENTS.md # 项目指令（自动读取） │
│ 项目/.codexignore # 忽略文件 │
│ │
│ 交互命令: │
│ /model /diff /undo /clear /review /approvals │
│ │
│ 提示词四元素: │
│ Goal → Context → Constraints → Done when │
│ │
│ 安全铁律: │
│ full-auto 前先 git commit │
│ 敏感代码必须人审 │
│ 不在非 git 目录跑 full-auto │
│ │
└─────────────────────────────────────────────────────┘结语
Codex CLI 的本质是把 AI 从"建议者"变成了"执行者"。
它不只是告诉你该怎么改，而是直接帮你改好、测好、提交好。三档审批模式让你自己决定 AI 自主的边界，AGENTS.md 让你用文件定义权限，git 给你兜底。
最合理的上手路径：suggest 模式入门 → 熟悉后切 auto-edit → 在 git 隔离分支中尝试 full-auto。三步走完，你就理解了 Agent 编程的完整心智模型。
工具在迭代，但底层方法论不变：可控的自主 > 完全的自动。
数据截止 2026 年 8 月。Codex CLI 更新频率较高，建议定期运行 npm install -g @openai/codex@latest 保持最新版本。