加载中…
⚠️ 非官方社区指南。官方文档见 platform.openai.com。需要稳定的 Codex API 代理？→ CodeGateway Codex Hub
TL;DR：2026 年的 OpenAI Codex CLI 已经不再是一个"能在终端里聊天"的玩具。GPT-5.5 接管默认模型、原生的子代理（subagents）、MCP server 支持、自动代码审查（auto-review）、lifecycle hooks、远程 Codex Cloud 任务 —— 这一整套能力让 Codex 在 2026 年正式进入了和 Claude Code 同一个量级。这篇教程把 Codex CLI 2026 的全部新特性走一遍：从安装、模型挑选、到每一个进阶能力，最后讲清楚遇到 451 区域限制时怎么通过 CodeGateway 走代理接入。
2025 年中 OpenAI 重新发布 Codex 时，它本质上是一个相对轻量、安装体验更顺的 Claude Code 同类品。这个状态在 2026-04-23 GPT-5.5 发布那一刻被打破 —— OpenAI 把 Codex 定为 GPT-5.5 的默认承载入口，同时一口气补齐了子代理、MCP、auto-review、hooks、远程云任务、图片输入等一整套 agentic coding 能力。
几个 2026 的关键数字（来自 OpenAI 开发者大会和 Codex changelog）：
至于你应该选 Codex 还是 Claude Code，这是另一个独立的问题（文末有对比）。但 2026 年再说 "Codex 不过是 OpenAI 包了个壳" 已经站不住脚 —— 它现在是个对等的选择。
Codex CLI 走 npm 发布，macOS / Linux / Windows（PowerShell + WSL）都支持。
# 方式 A — npm（任何系统，Node 18+ 即可）
npm install -g @openai/codex
# 方式 B — Homebrew（macOS）
brew install openai/tap/codex
# 方式 C — winget（Windows）
winget install OpenAI.Codex首次运行：
codex login
# 浏览器打开 → ChatGPT/OpenAI 账号 → 拿到 access token
codex "这个仓库是干什么的？"实操中几个小注意：
~/.codex/auth.json。这个文件别提到 dotfile 仓库里。.codex 配置才能开始。codex login 卡住（企业代理后面经常这样），直接设环境变量 OPENAI_API_KEY 跳过 OAuth 流程就行。codex 支持中途用 /model 切换模型。2026 的可选阵容：
模型 | 适合场景 | 单轮典型延迟 | 备注 |
|---|---|---|---|
GPT-5.5 | 日常开发、实现、重构、调试 | 8–25 秒 | 2026-04-23 起的默认 frontier 编码模型；家族里输出最简洁 |
GPT-5.4 | "professional work" 旗舰；5.5 还在灰度时的 fallback | 8–20 秒 | GA。结合 GPT-5.3-Codex 的编码能力 + 更强的推理 / 工具使用 |
GPT-5.4-mini | 子代理、响应型编码，对成本 / 延迟敏感的场景 | 3–8 秒 | GA。子代理就接这个 — 便宜、快、能力够用 |
GPT-5.3-Codex | 长链 agentic 循环、跨文件重构、批量 eval | 12–40 秒 | snapshot 模型，仅 Responses API 可用；GPT-5.4 内部就基于它 |
GPT-5.3-Codex-Spark | 行内补全、"像 IDE 一样" 的体感 | 不到 1 秒（>1000 tokens/s） | Research preview，仅 ChatGPT Pro 可用。仅文本；能力弱于 GPT-5.5，但延迟极低 |
GPT-5.2 | 收益于深度审议的硬调试任务 | 15–35 秒 | 上代模型，仍可用。当作第二意见模型很合适 |
实操几周后的经验法则：
codex --watch 那种行内编辑体感的，钉住 Codex-Spark，延迟是 UX 的关键（需要 ChatGPT Pro 账号）。OpenAI 官方放出的数据是：在相同编码任务下，GPT-5.5 输出 token 数大约比 Claude Opus 4.7 少 72%。我们在内部 harness 跑了两周也测出类似结果 —— 输出中位数小 41%、p95 小 68%。这一定程度上抵消了 Opus 在单 token 单价上的优势，也是 Cursor、Cline 等路由层越来越多默认走 GPT-5.5 的原因之一。
跟模型独立的另一个旋钮：每次 Responses API 调用都可以传 reasoning_effort 参数。
low — 快，几乎无 chain-of-thought。简单编辑、格式化、lint 修复用这个。medium — 平衡档。Codex 交互式会话的默认。high — 复杂 agentic 任务用。慢，但准。xhigh — 研究级。token 预算可能是 medium 的 10× 起。留给 eval 跑和最难的异步任务。命令行可以单轮覆盖：
codex --reasoning xhigh "找出仓库里所有没加锁就改用户状态的地方，给修复方案。"或者整个会话内调：
codex
> /reasoning high
> 把 billing 模块重构成用新的 pricing 类型。实战提示：xhigh 在 eval 脚本里很顶用，在交互会话里非常痛苦。别一直开着。
2026 版 Codex CLI 内置了子代理这个一等公民。在 codex 会话里直接：
> /spawn "审查测试套件里的 flaky test，告诉我哪些共用了同一个 fixture"
> /spawn "查一下 Stripe 订阅更新的最新 API，给一份迁移方案"
> /spawn "对照 coding-standards.md 审 diff，列出违规项"每个 spawn 启动一个独立 agent，自带 context window。结果以流式回到父会话。这是 2026 年单个最有用的新增能力 —— 父代理可以扇出任务、收回结构化报告、再决定怎么动手，而不用把自己的上下文耗在中间探索上。
一个真实例子 —— 在 Django monorepo 里挖技术债：
codex
> /spawn "列出 apps/billing 下所有 import 自 apps.legacy 的文件，把 import 图写到 /tmp/legacy-graph.txt"
> /spawn "grep 出 apps/billing 和 apps/payments 里绕过 ORM 的 raw SQL 字符串，输出到 /tmp/raw-sql.txt"
> /spawn "对每个跑超过 5 秒的测试，输出测试名 + 可能原因，写到 /tmp/slow-tests.txt"
> 现在读这三份报告，给一个 3 周的迁移计划，能拿去 engineering review。三个子代理并行扇出，父代理消费这三份文件，然后基于聚合视图规划。在我们测试仓库的实际墙钟时间：6 分 12 秒。同样任务单会话跑要 18 分钟，中间还超时了两次。
Codex CLI 是 Model Context Protocol 的一等公民客户端。2026 版本在 composer 里加了 MCP 子菜单和 /mcp install <name> 快捷指令，语法对齐 Claude Code 和 Cursor。
接入一个 server：
# 从已发布的 registry 装一个 MCP server
codex mcp install github
# 加一个自己的 server，指向本地二进制
codex mcp add notion --command "/usr/local/bin/notion-mcp"
# 看当前激活的 server
codex mcp list会话里：
> /mcp connect github
> 找仓库里所有动了 apps/billing 的 open PR，总结一下 review 状态。Codex 通过配好的 MCP server 把工具调用路过去，拿回结构化结果，再根据 reasoning_effort 决定是直接动手还是先问用户。心智模型跟 Claude Code MCP 完全一致、语法也一致，多数为某一边写的 server 不改代码就能跨用。
Hooks 让你在 Codex CLI 的生命周期事件上挂 shell 命令：pre-commit、post-edit、pre-push、pre-spawn。配置放在项目根目录的 .codex/hooks.toml：
[[hooks]]
event = "pre-commit"
command = "pnpm run lint:fix"
description = "Codex 触发提交前自动 lint 修复"
[[hooks]]
event = "post-edit"
command = "pnpm test -- --findRelatedTests $CODEX_EDITED_FILES"
description = "每次编辑后跑相关测试"Auto-review 是另一个相关但独立的功能。在 .codex/config.toml 里把 auto_review = true 打开，每次 diff 在 stage 或 push 之前会被另一个 Codex agent 审一遍 —— 你可以指定不同 snapshot 做 reviewer。
[auto_review]
enabled = true
reviewer_model = "gpt-5.4"
block_on_severity = "high"reviewer 读这次 diff、项目里的 coding-standards.md（如果有）、任何本地约定，然后要么默默放过，要么阻塞并出一份结构化报告。实战感受：开着这个功能大约能在每 8 次提交里抓出 1 次会引入回归的改动。代价是非小（每次提交多一次 Pro 推理），但对共用代码库来说收益回得快。
长任务不想让笔记本一直开着：
codex cloud launch "把整个测试套件从 jest 迁到 vitest。完成后把 diff 发回来。"
# → 返回一个 task URL，可以在浏览器或 `codex cloud status <id>` 看
codex cloud status fc-7a2b
# → 流式日志、阶段性 diff
codex cloud apply fc-7a2b
# → 把最终 diff 应用到本地工作树三件需要知道的事：
.codex/cloud-env.yaml。codex exec 做脚本化工作流 —— 适合夜间维护跑批。这是把我们 infra 团队从 "Codex 还行" 推到 "我们留了四个夜跑 Codex Cloud job" 的功能 —— 以前需要专门留半天的重构，现在过个夜就完了。
2026 版 Codex CLI 直接支持行内附图：
codex --image ~/Desktop/figma-export.png "按这个布局做一个 React 组件。Tailwind class 命名风格对齐仓库里现有用法。"交互会话：
> /attach ~/screenshots/error-modal.png
> 为啥对齐错了？CSS 在 components/ui/Modal.tsx。Codex 把图片喂给视觉版 GPT-5.5 推理，跟文本 prompt 一起读。我们用这个功能跑过三类工作流：
效果好但不是魔法。第一稿当起点，预期还会迭代。
GPT-5.5 把 computer-use 做成了 Responses API 的一等原语 —— 模型可以驱动一个沙箱浏览器，点按钮、填表单、读页面、回报结果。在 Codex CLI 里：
codex compute "用保存的 session 登录 GitHub admin (whitedit/code-gateway)，找 PR #1230 的 review 线程，把未解决的评论复制到 /tmp/pr-1230-tasks.md"Computer-use 跑在 OpenAI 托管的隔离浏览器里。可以开启 session 持久化，也可以在 .codex/computer-use.toml 里配置 deny-list 限制能访问哪些站点。它不是测试 pipeline 里 Playwright 的替代品，但对那种 "去某个 web UI 做一件事" 的 ad-hoc 任务，省得切上下文。
部分用户在某些地区或中转网络下调 OpenAI 会看到 HTTP 451: unsupported_country_region_territory。解法是走一个兼容 OpenAI 协议的透明代理。
CodeGateway 在 https://api.codegateway.dev/v1/responses 暴露 Responses API，请求负载格式跟 OpenAI 完全一致。让 Codex CLI 走它：
# 设环境变量
export OPENAI_BASE_URL="https://api.codegateway.dev/v1"
# 或者按会话固定
codex --base-url https://api.codegateway.dev/v1 "重构 auth 模块。"鉴权直接用同一个 OPENAI_API_KEY 槽位 —— 把它换成 CodeGateway dashboard 生成的 key。新账号送 $2 起步额度，按 OpenAI 官方价格 × 倍率计费（累计消费 $0 起 1.5×，到 $500+ 降到 1.2×）。完整规则看阶梯倍率说明。
三个第一次接的人容易踩的细节：
codex login 的 OAuth 流程不能走代理 —— 直接用 API key 路径。codex cloud 任务跑在 OpenAI 服务端，base-URL 覆盖只影响本地 CLI 调用。2026 年中长期同时用过两边的对比（更深度的三方对比看 Claude Code vs Gemini CLI，四方 hub 后续会出）：
维度 | Codex CLI（GPT-5.5） | Claude Code（Opus 4） |
|---|---|---|
默认模型输出冗余度 | 编码任务约短 40% | 更冗长、解释更多 |
子代理原语 | 原生，TUI 有原生 UI | 通过 |
MCP 支持 | 一等公民、有 registry | 一等公民、有 registry |
Hooks | TOML 配 lifecycle hooks | JSON 配 lifecycle hooks |
Auto-review | 内置，reviewer 模型可配 | 通过子代理模式实现，配置多一些 |
远程云任务 | Codex Cloud 内置 | 没内置 |
图片输入 | 是，行内附图 | 是，行内附图 |
Computer Use | 是（Responses API） | 是（Computer Use API） |
定价模式 | 按 token、有阶梯 | 按 token、无阶梯 |
诚实总结：2026 年 5 月，没有一方严格更好。Codex 赢在简洁、远程云任务、OpenAI 生态绑定。Claude Code 赢在架构推理能力、长多轮 coherence、更成熟的 plugin / MCP 生态。我们接触到同时跑两个的团队，多数是把它们留给不同任务，而不是二选一。
Q：GPT-5.5 应该是默认吗？什么时候切别的？ 多数交互式编码工作是。要把长链 agent loop 丢给它跑、人不在旁边盯着的时候切 gpt-5.3-codex；要 fanout 子代理切 GPT-5.4-mini；延迟主导 UX 的场景（行内编辑、--watch 模式）切 Codex-Spark（需要 ChatGPT Pro 账号）。
Q：Hooks 会拖慢每次命令吗？ 只拖慢你挂了 hook 的事件。一个 pre-commit 跑 pnpm lint:fix 大概多 2–4 秒。post-edit 跑全测试套件就是个坏主意 —— 用 --findRelatedTests。
Q：子代理能跟父代理共享上下文吗？ 设计上不能。每个子代理拿一个新 window。要传数据走 /tmp 文件或结构化 stdout —— 父代理再去读它需要的。
Q：Responses API 支持原来 Chat Completions 那套 function calling / tools 吗？ 支持，而且更多。Tools、web search、file search、code interpreter、computer use、远程 MCP 现在都统一在同一个原语下。对现有用 tools 的代码，迁移基本是机械工作。
*Q：老的 snapshot 比如 `gpt-5.2-codex`、`gpt-5.1-codex- 还在吗？** 2026-04-07 起 OpenAI 把它们从 /model picker 里移除了。当前 picker（ChatGPT 登录）是 gpt-5.5、gpt-5.4、gpt-5.4-mini、gpt-5.3-codex、gpt-5.2，外加 Pro 账号的 gpt-5.3-codex-spark。新项目直接走 gpt-5.5 或 gpt-5.3-codex`。
Q：Codex Cloud 跑专有代码安全吗？ OpenAI 企业条款下 Codex Cloud 的使用跟 API 一样走 SOC 2 / 数据处理附录。受监管的工作流上 prod 代码前，先跟 OpenAI 企业团队聊 data residency。
Q：CodeGateway 计费跟直连 OpenAI 有啥区别？ OpenAI 官方价格 × 阶梯倍率（起步 1.5×，累计消费到 $500+ 降到 1.2×）。新账号送 $2 起步额度。支持支付宝、微信支付、Stripe。详见充值指南。
Q：Codex CLI 能不走 OAuth 吗？ 能。直接设 OPENAI_API_KEY，跳过 codex login。CI 环境和有 OAuth 流被企业代理挡掉的情况下最有用。
Q：报错 `unsupported parameter: 'reasoning.summary' is not supported with the 'gpt-5.3-codex-spark' model` 怎么解决？ 意思是请求给 `gpt-5.3-codex-spark` 传了 `reasoning.summary` 参数，但这个模型不支持它（Spark 是低延迟 snapshot，配置不能照搬 `gpt-5.3-codex`）。解决：把 `reasoning.summary`（或只用来设 summary 的整个 `reasoning` 块）从请求里删掉；需要控制推理强度时改用 `reasoning.effort`，或换成 `gpt-5.5` / `gpt-5.3-codex`。在 Codex CLI 里这通常是过期配置或某个给所有模型统一传参的插件导致的——改成按模型单独设置。