OpenAI Codex CLI 完整教程 2026:GPT-5.5、子代理、MCP 与 Codex Cloud

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 走代理接入。

目录

1. Codex CLI 在 2026 为什么重要
2. 90 秒装好
3. 模型怎么挑
4. Reasoning Effort
5. 子代理 Subagents
6. MCP Server 集成
7. Hooks 和 Auto-review
8. Codex Cloud
9. 截图和图片输入
10. Computer Use
11. 当 codex 报 "451: unsupported region"
12. Codex CLI vs Claude Code 对比
13. 常见问题 FAQ

Codex CLI 在 2026 为什么重要

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）：

• 每周 400 万开发者在用 Codex（含 CLI / IDE / ChatGPT App / Codex Cloud）
• GPT-5.5 是默认模型，GPT-5.3-Codex 是 agentic coding 调优的 snapshot、GPT-5.4-mini 主打子代理的低延迟低成本、GPT-5.3-Codex-Spark 主打亚秒级延迟
• Codex 内部的 Chat Completions API 已弃用，所有新能力都建在 Responses API 上

至于你应该选 Codex 还是 Claude Code，这是另一个独立的问题（文末有对比）。但 2026 年再说 "Codex 不过是 OpenAI 包了个壳" 已经站不住脚 —— 它现在是个对等的选择。

90 秒装好

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 仓库里。
• CLI 会自动识别你项目的 package manager、lockfile、测试框架 —— 不需要先写一个 .codex 配置才能开始。
• 如果 codex login 卡住（企业代理后面经常这样），直接设环境变量 OPENAI_API_KEY 跳过 OAuth 流程就行。

模型怎么挑

codex 支持中途用 /model 切换模型。2026 的可选阵容：

实操几周后的经验法则：

• 默认就 GPT-5.5。2026-04-23 起的 frontier 编码模型，多数编码任务严格优于 GPT-5.4。
• 子代理用 GPT-5.4-mini。成本低 + 延迟低，是父代理 spawn 子代理的最甜点。
• 把任务交给 agent 后人不在旁边盯着的长任务，切到 GPT-5.3-Codex——它就是为这种持续 agentic 循环调优的 snapshot。
• 想要 codex --watch 那种行内编辑体感的，钉住 Codex-Spark，延迟是 UX 的关键（需要 ChatGPT Pro 账号）。
• GPT-5.2 留给那种需要换个有深度审议能力的模型出第二意见的硬调试任务。

OpenAI 官方放出的数据是：在相同编码任务下，GPT-5.5 输出 token 数大约比 Claude Opus 4.7 少 72%。我们在内部 harness 跑了两周也测出类似结果 —— 输出中位数小 41%、p95 小 68%。这一定程度上抵消了 Opus 在单 token 单价上的优势，也是 Cursor、Cline 等路由层越来越多默认走 GPT-5.5 的原因之一。

Reasoning Effort

跟模型独立的另一个旋钮：每次 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 脚本里很顶用，在交互会话里非常痛苦。别一直开着。

子代理 Subagents

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 分钟，中间还超时了两次。

MCP Server 集成

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 和 Auto-review

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

长任务不想让笔记本一直开着：

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 任务跑在 OpenAI 托管的隔离 VM 里。任务启动时镜像你的仓库，磁盘上其他东西一概不可见。
• 默认环境跟你本地的语言 / runtime 一致（从 lockfile 自动检测）。自定义工具链就放 .codex/cloud-env.yaml。
• Cloud 任务可以串进 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 一起读。我们用这个功能跑过三类工作流：

1. 设计稿到代码：贴个 Figma 导出，拿到第一版 React/Vue/Svelte 实现，class 命名风格对齐仓库。
2. bug 截图：贴出错状态、指出对应文件，让 Codex 给修法。
3. 白板照：解析手画系统图成 Mermaid 语法的能力意外地不错。

效果好但不是魔法。第一稿当起点，预期还会迭代。

Computer Use

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 任务，省得切上下文。

当 codex 报 "451: unsupported region"

部分用户在某些地区或中转网络下调 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 调用。
• SSE 流式响应完全支持 —— 不会 fallback 到轮询。

Codex CLI vs Claude Code 对比

2026 年中长期同时用过两边的对比（更深度的三方对比看 Claude Code vs Gemini CLI，四方 hub 后续会出）：

诚实总结：2026 年 5 月，没有一方严格更好。Codex 赢在简洁、远程云任务、OpenAI 生态绑定。Claude Code 赢在架构推理能力、长多轮 coherence、更成熟的 plugin / MCP 生态。我们接触到同时跑两个的团队，多数是把它们留给不同任务，而不是二选一。

常见问题 FAQ

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 流被企业代理挡掉的情况下最有用。

相关资料

• Claude Code vs Gemini CLI：2026 对比 — agentic 编码 CLI 领域的第三个选项
• Claude Code 5 分钟接入 — Anthropic 这边的入门指南
• 阶梯倍率说明 — 倍率怎么算
• 错误排查 — 451 / 429 / 529 / 超时各种边界情况
• Codex CLI vs Claude Code — 聚焦的两方对比

外部参考

• OpenAI Codex CLI 文档
• GPT-5.5 model card
• Codex 模型参考
• Codex changelog
• Responses API 指南