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

TL;DR: Codex CLI 2026 一条命令即可安装（Windows 用 winget，其它平台用 npm），通过 config.toml 指向任意兼容端点。版本号、安装命令与必配键见下文。

⚠️ 非官方社区指南。官方文档见 platform.openai.com。需要稳定的 Codex API 代理？→ CodeGateway Codex Hub

TL;DR：Codex CLI 2026 默认模型 GPT-5.5，npm i -g @openai/codex 90 秒装完。它早已不是「终端聊天玩具」：子代理、MCP server、hooks 自动审查、Codex Cloud 全部内置。本教程覆盖 config.toml、AGENTS.md 层级与 451 unsupported-region 修复。

目录

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 包了个壳" 已经站不住脚 —— 它现在是个对等的选择。

安装 Codex CLI

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 CLI 安装与配置报错排查覆盖 auth.json、config.toml 与 MCP 故障（含 451 地区错误）；分档定价说明解释装完之后各模型的实际成本。还在选型？看Codex CLI vs Claude Code 对比。

如果你拿不到 OpenAI API key——所在地区没有受支持的支付方式，或账号始终过不了审核——Codex CLI 也不必停摆。CodeGateway 签发的 key 兼容 OpenAI 协议，CLI 指向它和指向 OpenAI 一样：把 OPENAI_BASE_URL 设为 https://api.codegateway.dev/v1，key 填进 OPENAI_API_KEY 槽位即可。prompt、MCP server 和 AGENTS.md 都照常工作。在 CodeGateway 注册后建一个按量计费的 key 填进去即可；按 token 计费，没有月度最低消费。

模型怎么挑

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。这来自上游/合规侧的地区判定，不是你的 key 或额度问题：先用重试确认它是不是瞬态（网关对上游瞬态拒绝返回 503 + Retry-After，SDK 会自动重试），持续失败再换模型或网络出口。网关提供的是可达的 API 端点与统一账单，不改变上游的地区判定。

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。新账号绑定支付方式后可获得起步额度（具体金额以注册/定价页实时展示为准），按 OpenAI 官方价格 × 统一的 1.07× 倍率计费（所有账户一致，不随累计消费变化）。完整规则看统一倍率说明。

三个第一次接的人容易踩的细节：

• 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.07× 倍率（所有账户一致，不随累计消费变化）。新账号绑定支付方式后可获得起步额度（具体金额以注册/定价页实时展示为准）。支持支付宝、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 里这通常是过期配置或某个给所有模型统一传参的插件导致的——改成按模型单独设置。

Q: 如何安装 Codex CLI？ Node 18+ 上执行 npm install -g @openai/codex（macOS / Linux / Windows）；winget install openai.codex 与 Homebrew 亦可。然后 codex login 鉴权；无界面 Linux 用 OPENAI_API_KEY 代替 OAuth。

Q: Codex CLI 的配置文件在哪？ ~/.codex/config.toml（凭据单独存于 ~/.codex/auth.json）。config.toml 里固定模型、设置审批策略并注册 MCP server。

Q: Codex CLI 能指向自定义 API 端点吗？ 可以 —— 在 ~/.codex/config.toml 设置 base URL（例如 https://api.codegateway.dev/v1）。若报 451 unsupported region，按上文修复章节处理。

Q：npm install -g @openai/codex 报 EACCES 或装完提示 command not found 怎么办？

EACCES 表示 npm 全局目录属于 root：用 nvm / fnm 重装 Node，或执行 npm config set prefix ~/.npm-global 后把 ~/.npm-global/bin 加入 PATH。安装成功但当前 shell 仍提示 command not found，是 PATH 没刷新 —— 重开终端后用 which codex 确认。同时检查 node -v 是否 18 以上，Node 版本过低会在安装阶段就失败。

Q：Codex CLI 报 451 Unsupported Region 怎么解决？

451 是 OpenAI 按地区拒绝请求，不是 config.toml 写错，重新 codex login 也不会绕过。把 CLI 指向可访问的 OpenAI 兼容端点：在 ~/.codex/config.toml 里声明 [model_providers.codegateway]（base_url + env_key），导出该 key 后用 codex 启动新会话即可。prompt、MCP server 与 AGENTS.md 都照常工作，具体取值见上文的网关一节。

Q：怎么给 Codex CLI 接入 MCP server？

在 ~/.codex/config.toml 里新增 [mcp_servers.<名称>] 表，填 command 与 args（远程 server 用 url），重启 Codex 后在会话里用 /mcp 确认已加载。项目级覆盖写到仓库内的 .codex/config.toml；没有注册的 server 不会被启动。

相关资料

• 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 指南

相关阅读：CodeGateway 指南

• AGENTS.md 实战手册（Codex CLI 层级配置）

• Claude Code 全自动模式：权限模式与 CI/CD 实战

• 给 Claude Desktop 配置自定义 API 端点

• 查看 Claude、GPT、Gemini 实时 API 价格

• Claude Code 连接超时排查（5 分钟稳定接入）

Codex CLI 在 Windows / macOS 上怎么安装？

一条命令装完：Windows 用 winget，macOS / Linux 用 npm（完整命令见上文安装一节），装完先跑 codex --version 确认版本。重新执行安装命令即可升级。

没有 OpenAI API Key 或信用卡，能用 Codex CLI 吗？

可以。Codex CLI 走 OpenAI Responses 协议，任何兼容该协议的网关都能接：在网关侧创建 Key，把 base URL 与 Key 写进 config.toml 即可，CLI 用法不变；遇到「451: unsupported region」也是同样的解法。一键配置与 Key 创建见Codex 接入页。