OpenAI Codex 使用详解(2026 最新版 · 干货向)

哥们,这篇是真正能落地的 Codex 全栈指南。
一次性讲清楚:这个东西到底是什么、能干啥、怎么装、怎么用、怎么榨干它的能力、怎么避开坑。
截至 2026 年 6 月,CLI 0.132.0 稳定版、GPT-5.3-Codex 引擎、桌面端 2026.5、移动端 5 月已 GA。

---

0. 一句话定位

Codex 不是"补全代码的 Copilot",而是 OpenAI 推出的"自主软件工程 Agent(AI 程序员)"。
它能:读整个仓库 → 拆解任务 → 改文件 → 跑命令 → 跑测试 → 给 PR,链路是端到端的。

对比一下心里有数:

工具	形态	自动化程度	开源	国内可用
Codex	CLI / App / IDE / Web / 移动 / GitHub	高(可无人值守)	✅ CLI 开源	需代理
Claude Code	CLI(终端优先)	中(强协作)	部分开源	需代理
Cursor	IDE(VS Code 衍生)	中(补全+对话)	❌ 闭源	需代理

---

1. Codex 进化史(只挑关键节点,背熟面试加分)

时间	事件	关键点
2021	老 Codex(代码生成模型)	早已下线,别再提了
2025-04-17	Codex CLI 首发,完全开源	基于 o3/o4-mini,本地终端 Agent
2025-05	Codex Web 版上线	云端任务、PR 自动开
2025-09-15	GPT-5-Codex 发布	Agent 编程专用,思考时间自适应,最长 7 小时
2025-09-23	GPT-5-Codex 开放 API	通过 Responses API,定价 = GPT-5
2026-02	GPT-5.3-Codex 发布	速度 +25%,整合推理与领域知识
2026-03	Plugins + Triggers 上线	接入 Sentry/Datadog,响应 GitHub Issue
2026-04-17	桌面控制 + 多智能体 + 内置浏览器	模拟鼠标键盘,可后台并行 Agent
2026-05-07	Codex for Chrome 扩展	抓页面数据、提取图片
2026-05-14	移动端 + Hooks GA	iOS/Android 远程控制开发机
2026-05-15	Mac 强制安全更新(截止 6-12)	TanStack 供应链攻击后预防性补丁
2026-05-20	CLI 0.132.0	SubagentStart Hook、文件系统 deny canonical
2026-05-22	CLI 0.134.0a2(alpha)	体验新功能用
2026-06-18	Codex 全面支持第三方 LLM	DeepSeek / Claude / Gemini 都能接

关键认知:OpenAI 在 2026 年主推的是**“无人值守 Agent”**——你睡了,Codex 在跑 Issue;你醒了,PR 在等你审。

---

2. 安装与环境准备

2.1 系统要求

• macOS 12+(M1/M2/M3 优先)
• Ubuntu 20.04+ / Debian 10+
• Windows 11 仅支持 WSL2(原生命令行不支持,装个 WSL)
• 内存 ≥ 4GB(建议 8GB)

2.2 三种安装方式

方式一:npm 全平台(最常用)

# 稳定版
npm install -g @openai/codex@0.132.0

# alpha 版(尝鲜)
npm install -g @openai/codex@0.134.0a2

# 验证
codex --version
codex --help

方式二:Homebrew(macOS/Linux)

brew install codex
codex --version

方式三:macOS 桌面 App

• 下载 .dmg → 拖入 Applications
• 用 ChatGPT 账号登录(Free/Plus/Pro 都能用)
• 桌面端独有:可视化任务管理、Plugin 配置、移动端 Host

2.3 登录与 API Key

# 方式 A:ChatGPT 账号登录(推荐,自动鉴权)
codex login

# 方式 B:API Key(适合 CI/脚本场景)
export OPENAI_API_KEY="sk-..."
# Windows PowerShell:
$env:OPENAI_API_KEY = "sk-..."

# 国内用户必备:配置代理
export HTTPS_PROXY=http://127.0.0.1:7890
# 或指向中转服务
export OPENAI_BASE_URL=https://your-proxy-endpoint/v1

踩坑提醒:Windows PowerShell 默认 ANSI 编码,设置环境变量时直接 $env:XXX = "..." 即可,别用 set(会丢会话)。

---

3. 三种核心使用形态

3.1 CLI 终端(最强大、可脚本化)

# 交互模式(进入 TUI)
codex

# 非交互单次任务
codex exec "重构 src/utils 目录下的所有函数"

# 指定模型
codex --model gpt-5-codex "用 TypeScript 重写 auth 模块"

# 指定审批模式(后面专门讲)
codex --approval-mode suggest "..."

3.2 IDE 扩展(VS Code / Cursor)

• VS Code 插件市场搜 Codex 安装
• 与 CLI 共享 API 配置与对话历史
• 选中代码 → 右键 → Codex 解释/重构/补测试
• ⚠️ 必须关闭 VS Code 内置的 GitHub Copilot,否则 CLI 在 IDE 终端会因模型上下文冲突静默失败(无日志提示!)

3.3 Web 云端任务(适合长任务)

• 入口:ChatGPT 侧边栏 → Codex → New task
• 适合 1~30 分钟的长时任务,云端沙箱独立运行,不占你本地
• 任务完成可触发 GitHub PR

---

4. 配置文件 ~/.codex/config.toml 详解

这个文件是 Codex 的"灵魂",所有高级玩法都靠它。

4.1 基础结构

# 模型选择
model = "gpt-5-codex"
model_provider = "openai"
model_reasoning_effort = "high"  # low / medium / high

# 沙箱策略
sandbox_mode = "workspace-write"  # read-only / workspace-write / danger-full-access
approval_policy = "on-request"    # untrusted / on-failure / on-request / never

# 多 Provider 配置(2026-06 新增)
[model_providers.openai]
name = "OpenAI"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

4.2 接 Azure OpenAI(企业常用)

model = "gpt-5-codex"
model_provider = "azure"
model_reasoning_effort = "high"

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_RESOURCE.openai.azure.com/openai/v1"
env_key = "AZURE_OPENAI_API_KEY"
wire_api = "responses"

export AZURE_OPENAI_API_KEY="<your-key>"

4.3 接第三方模型(2026-06 解锁)

# 接 DeepSeek
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"
wire_api = "chat"

# 接 Claude
[model_providers.claude]
name = "Claude"
base_url = "https://api.anthropic.com/v1"
env_key = "ANTHROPIC_API_KEY"
wire_api = "chat"

然后命令行切换:

codex --model deepseek-chat "..."
codex --model claude-sonnet-4 "..."

4.4 子目录配置(项目级)

Codex 会自下而上合并配置,优先级:

1. ~/.codex/config.toml(个人全局)
2. <repo>/config.toml(项目共享)
3. <cwd>/.codex/config.toml(当前目录)

---

5. AGENTS.md:让 Codex "懂"你的项目

这是 Codex 最被低估的功能,90% 的人没用对。

5.1 查找顺序(自上而下合并)

1. ~/.codex/AGENTS.md — 个人全局
2. <repo>/AGENTS.md — 项目根
3. <cwd>/AGENTS.md — 子目录/任务级

5.2 实战模板

项目根 AGENTS.md:

# Project: my-saas

## 技术栈
- Next.js 14 (App Router) + TypeScript
- PostgreSQL + Prisma
- Tailwind + shadcn/ui

## 编码规范
- 使用 server components 优先
- 数据库查询必须走 Prisma,不要裸 SQL
- API 路由统一放在 `src/app/api/`,RESTful 风格
- 测试覆盖率 < 80% 不允许合并

## 常用命令
- `pnpm dev` — 启动开发
- `pnpm test` — 跑测试
- `pnpm db:migrate` — 数据库迁移

## 注意事项
- 任何涉及支付的代码改动,先 @我确认
- 不要碰 `src/legacy/` 目录

子目录 src/auth/AGENTS.md(覆盖式):

# Auth 模块特殊规则
- 所有密码操作走 argon2,不要用 bcrypt
- JWT 过期时间统一 15 分钟
- Refresh token 存 Redis,key 前缀 `auth:rt:`

效果:Codex 每次进入这个目录,自动加载对应的规则。这就是为什么"好的 AGENTS.md = 半个 senior 工程师"。

---

6. 三种审批模式(安全核心)

# 1. suggest(默认) — 每步都问你,最安全
codex --approval-mode suggest "重构 src/utils"

# 2. auto-edit — 自动读 + 自动编辑,危险操作才问
codex --approval-mode auto-edit "分析并修复 tests/ 下所有失败用例"

# 3. full-auto — 全自动,沙箱内自由发挥
codex --approval-mode full-auto "生成本次 PR 的 CHANGELOG"

安全设计三件套:

• ✅ 默认沙箱目录:只能写当前 workspace
• ✅ 默认关网:除非显式白名单
• ✅ 默认审批:写命令、安装依赖、提交代码都要人确认

实战建议:第一次用必须 suggest 跑一遍,熟悉它会做什么再切 auto-edit。永远不要在 main 分支用 full-auto。

---

7. 高级特性:Triggers / Plugins / Skills / Hooks

7.1 Triggers(自动响应 GitHub 事件)

.codex/triggers.yml:

triggers:
  - name: auto-fix-issue
    on:
      github:
        event: issues
        action: labeled
        label: "codex-fix"
    task: |
      分析这个 Issue 描述的 Bug:
      1. 定位代码根因
      2. 生成修复方案 + 单元测试
      3. 创建 PR 关联此 Issue
    approval_mode: suggest  # 提交前仍需人工审批

自动化流程:

GitHub Issue 打 "codex-fix" 标签
  ↓ Codex Trigger 触发
  ↓ 读取 Issue + 代码库上下文
  ↓ 生成修复 + 测试
  ↓ 自动开 PR,标注"等待审核"
  ↓ 开发者手机端 approve

实战价值:Issue → PR 的平均响应从小时级压缩到分钟级,适合无值班工程师的中小团队。

7.2 Plugins(接入外部工具链)

插件	干啥用
Sentry	读错误报告,自动生成修复 PR
Datadog	读监控/日志,定位性能回归
GitHub	仓库操作、Issue、PR
CodeRabbit	协同代码审查
GitLab Issues	同 GitHub
MCP 协议	自定义接入任意服务

.codex/config.toml:

[plugins.sentry]
dsn = "https://xxx@sentry.io/123"
auto_fix = true

[plugins.github]
token_env = "GITHUB_TOKEN"

7.3 Skills(技能,2026 新概念)

技能 = 可复用的 Prompt + 工具链,放在 .codex/skills/:

# 安装官方技能集
mkdir -p .codex/skills
python3 ~/.codex/skills/.system/install.py \
  --set code-review,test-gen,refactor

自带技能举例:

• code-review:PR 风格 + 安全 + 性能审查
• test-gen:根据代码自动补单元测试
• refactor:跨语言迁移、老项目现代化
• changelog-gen:从 git log 生成 CHANGELOG

7.4 Hooks(钩子,0.132 GA)

在 Agent 生命周期插入自定义脚本:

[hooks]
SubagentStart = "scripts/on-subagent-start.sh"
PreCommand = "scripts/pre-command.sh"  # 拦截危险命令
PostEdit = "scripts/post-edit.sh"      # 编辑后自动跑 lint

scripts/pre-command.sh 实战:

#!/bin/bash
# 拦截 rm -rf、sudo、curl | sh
cmd="$1"
if [[ "$cmd" == *"rm -rf"* ]] || [[ "$cmd" == *"sudo"* ]]; then
  echo "[Hook] 危险命令已拦截: $cmd" >&2
  exit 1
fi

---

8. 实战场景大全(对照抄)

8.1 场景 1:从零生成一个项目

mkdir my-api && cd my-api
codex --approval-mode suggest "用 FastAPI + SQLAlchemy 创建一个博客 API,包含用户、文章、评论三个表,带 JWT 鉴权"

8.2 场景 2:大型重构

codex --approval-mode auto-edit "把 src/ 下的 class 组件全部重构成函数组件,保持 props 一致,不要改业务逻辑"

技巧:大型任务给 gpt-5-codex + model_reasoning_effort=high,思考时间自适应,最长跑 7 小时。

8.3 场景 3:补测试

codex --approval-mode auto-edit "为 src/services/payment.ts 补单元测试,覆盖率要 > 90%,边界 case 全覆盖"

8.4 场景 4:GitHub PR 自动审查

仓库装好 Codex App,配置 .codex/review.yml:

review_on:
  - pull_request.opened
  - pull_request.ready_for_review
focus:
  - security
  - dependencies
  - performance

触发方式:

• PR 从 Draft → Ready 自动审查
• 评论区输入 @codex review 手动触发
• 评论数从 1.32 降到 0.93,高质量意见占比 52.4%

8.5 场景 5:多智能体并行(2026-04 新)

# 启动 3 个 Agent 并行处理不同模块
codex agent spawn --task "重构 auth 模块" --model gpt-5-codex &
codex agent spawn --task "补 payment 测试" --model gpt-5-codex &
codex agent spawn --task "更新 OpenAPI 文档" --model gpt-5-codex &
wait

桌面端可后台并行,你在前台写别的代码,Agent 在 Mac 后台跑。

8.6 场景 6:CI/CD 自动化

.github/workflows/codex.yml:

name: Codex Auto-Changelog
on:
  push:
    branches: [main]

jobs:
  update-changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Update changelog via Codex
        run: |
          npm install -g @openai/codex
          export OPENAI_API_KEY="${{ secrets.OPENAI_API_KEY }}"
          codex -p openai exec --full-auto \
            "根据最近 10 个 commit 更新 CHANGELOG.md"
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

8.7 场景 7:前端截图迭代

# Codex CLI 支持多模态
codex "分析这张设计稿(./mockup.png),用 React + Tailwind 还原"
codex "对比 ./before.png 和 ./after.png,告诉我视觉差异"

8.8 场景 8:移动端远程控制(2026-05 GA)

1. Mac 装 Codex App,Settings → Remote Connections → Enable
2. iPhone/Android 打开 ChatGPT App → Codex → Connect to host → 扫码
3. 手机端可:跨 Thread 工作、批准命令、切换模型、发起新任务

适用场景:通勤路上 review 跑了一夜的重构任务输出。

8.9 场景 9:桌面控制 + 内置浏览器(2026-04)

# 让 Codex 帮你操作没 API 的老旧桌面应用
codex --approval-mode auto-edit \
  "打开 Photoshop,把这 200 张商品图批量裁剪成 800x800"

注意:此功能仅 macOS + Apple Silicon 优先。

---

9. 性能 & 选型参考

9.1 GPT-5-Codex 关键数据

指标	数据
SWE-bench Verified	74.5%(GPT-5 是 72.8%)
代码重构任务	33.9% → 51.3%
简单任务 token 节省	-93.7%
复杂任务 token 增加	+102.2%
错误评论率	13.7% → 4.4%
高影响力评论占比	39.4% → 52.4%
连续工作时长	最长 7 小时+

9.2 怎么选模型

场景	推荐	原因
补全、写小函数	gpt-5	速度优先
重构 + 跨文件	gpt-5-codex	思考更深,自适应
长时间 Agent 任务	gpt-5-codex + reasoning_effort=high	7+ 小时续航
成本敏感	gpt-5-codex-mini	质量略降,价格低
国内合规	DeepSeek / Qwen	走第三方 model_provider

---

10. 与 Claude Code / Cursor 的差异化选择

维度	Codex	Claude Code	Cursor
最强项	无人值守 Agent	实时协作 + 长上下文	IDE 体验
适合	后台跑长任务、自动 PR	边写边聊、复杂架构	改老代码、补全
开源	✅ CLI 开源	部分	❌
PR 审查	✅ 内置	需插件	需插件
移动端	✅	❌	❌
Triggers	✅	❌	❌
桌面控制	✅	❌(Cowork 刚出)	❌
价格起点	Free 计划可用	Pro $20/月	Pro $20/月

实战选型建议:

• 个人开发者:Codex CLI + Cursor(双开)
• 小团队:Codex + GitHub Actions(自动化流水线)
• 大企业:Codex + Azure OpenAI(合规)

---

11. 常见坑 & 排雷指南

11.1 “为什么 codex 命令没反应?”

• 99% 是 PATH 问题:Mac/Linux echo $PATH 看有没有 ~/.local/bin
• 重新加载 shell:source ~/.zshrc

11.2 “国内怎么用?”

• 必须代理:export HTTPS_PROXY=http://127.0.0.1:7890
• 或中转:export OPENAI_BASE_URL=https://your-proxy.com/v1
• 不要把 API Key 直接写进 config.toml 的字符串里,必须用 env_key 引用环境变量

11.3 “Triggers 自动合并有风险吗?”

• 默认配置下不会,PR 开完等人工审批
• 如果配 full-auto + 仓库开了 auto-merge,务必给 Codex Bot 账号只写不合并的权限

11.4 “VS Code 里跑 CLI 静默失败?”

• 关掉内置的 GitHub Copilot 插件(已说过,血泪教训)
• 检查 WSL2 / 原生终端差异,Windows 一定要走 WSL2

11.5 “CLI 卡在 thinking 阶段不动?”

• 检查 model_reasoning_effort 设置,high 模式复杂任务会跑很久
• 用 codex exec 而不是 codex 交互模式,超时可控

11.6 “移动端连不上 Mac?”

• Mac 端 Codex App 必须保持前台或后台运行
• 同网络优先,跨网络要配 SSH Host

11.7 “Mac 用户没更新到最新版?”

• 2026-06-12 截止,TanStack 供应链攻击后强制安全更新
• 检查方式:菜单栏 → Codex → About Codex

---

12. 最佳实践清单(看完这一段就够)

1. 每个项目写好 AGENTS.md,比什么都重要
2. 第一次用 suggest 模式,熟悉它会做什么
3. 生产环境严禁 full-auto + main 分支
4. Hook 拦截危险命令(rm -rf、sudo、curl | sh)
5. CI 场景用 codex exec,可控、可重试
6. 大型任务指定 gpt-5-codex + reasoning_effort=high
7. Triggers 配 approval_mode: suggest,留人工把关
8. Bot 账号权限最小化:只写不合并
9. 用 ~/.codex/skills/ 复用 Prompt,团队共享
10. 定期 review codex --help,新版本加新参数很快

---

13. 资源汇总(收藏这一段就够)

官方

• Codex 产品页:https://openai.com/codex/
• 开发者文档:https://developers.openai.com/codex/
• Changelog:https://developers.openai.com/codex/changelog
• GitHub:https://github.com/openai/codex

配置参考

• Azure OpenAI 接入:微软 Azure AI Foundry 文档
• MCP 协议接入:anthropic.com/mcp

社区

• CSDN / 掘金 / 博客园搜"Codex CLI"
• Reddit r/Codex

国内

• 七牛云 AI 推理服务(兼容 OpenAI SDK,可中转)
• 各种 API 中转(自建风险自担,注意数据合规)

---

14. 一句话总结

Codex = 你团队里那个不会累、会写、会测、会审 PR、还能 7 小时连轴转的"数字员工"。
用好 AGENTS.md + Hooks + Triggers 三件套,基本就超过了 90% 的使用者。

下一步建议:

1. 装 CLI 0.132.0 → 跑通 hello world
2. 写项目级 AGENTS.md → 试一次中型重构
3. 配置一个 GitHub Trigger → 体验"无人值守"
4. 接入第三方模型 → 对比效果

搞起,哥们!有任何具体卡点直接问我,我陪你 debug 到底。

---

最后更新:2026-06-26 · 基于公开资料 + 实战整理 · Codex 仍高频迭代,建议关注官方 Changelog