OpenAI Codex CLI 完全教程 2026:安装到 GPT-5.5 实战

OpenAI Codex CLI 是什么:命令行里的自治编程 agent

如果你在搜 openai codex cli 教程、想知道 codex 怎么用、或者纠结 codex gpt-5.5 到底强在哪,这篇是我(dfkai)的实测笔记。

TL;DR: Codex CLI 是 OpenAI 官方的终端编程 agent,2026-05-28 的 0.135.0 版默认跑 GPT-5.5,核心三件套是「统一 @ 提及选文件 + Goals 自治执行 + codex doctor 排错」。我实测它在长任务自治和「闷头干到底」上比 Claude Code 更"轴",适合丢一个明确目标让它跑几小时;但交互细腻度和生态成熟度,Claude Code 目前仍更顺手。两个都装、按任务切换是我现在的真实用法。如果你还没用过 Claude Code,建议先看我的 Claude Code 基础教程打底,再回来对照看。

先把它放进坐标系:它和 Claude Code 是同一个物种——都是「装在终端、能读写你整个仓库、能自己跑命令」的 CLI agent,而不是 Cursor 那种 IDE 内嵌补全。区别在于背后的模型(GPT-5.5 vs Claude Opus 4.8)和交互哲学。想看四工具拉通横评,直接跳 AI 编程 agent 横评 2026。

Codex CLI 在终端中的工作流

版本与功能我已在 2026-05-30 联网核对官方 changelog,但 Codex 迭代极快(0.136.0-alpha.1 在 5-29 就出现了),具体版本号与可用功能请以 OpenAI Codex 官方 changelog 最新为准。

为什么现在值得装:0.13x 这波更新干了什么

我从 0.12x 一路用到 0.135,这波更新把它从「能用」推到了「想长期留着」。根据官方记录:

GPT-5.5 成为默认模型(Codex 模型页):官方描述 gpt-5.5 是「面向复杂编程、计算机操作、知识工作与研究的最新前沿模型」。同台还有 gpt-5.4、gpt-5.3-codex 等可选。
Goals(目标模式)默认开启:0.133.0(官方记 5 月下旬)起 Goals 默认启用,有独立存储、跨多轮跟踪进度。官方原话是它能「朝一个具体目标驱动数小时甚至数天」。这是和 Claude Code 手感差异最大的点。
统一 @ 提及:0.131.0 起,@ 一个选择器同时搜「文件 / 目录 / 插件 / skills」,背后接 app-server 元数据。
codex doctor 排错:同样 0.131.0 引入,0.135.0 又加厚了环境 / Git / 终端 / app-server / 线程清单的诊断。
插件 marketplace:加了 marketplace CLI 命令、版本感知分享、share checkout。
Windows Computer Use:Codex 桌面端(app 版本号体系和 CLI 不同)新增在 Windows 上「看、点、输入」操作前台应用的能力。

（来源:OpenAI Codex changelog、GitHub Releases。功能归属版本以官方为准。）

怎么装:三条路任选

我在 macOS(M 系列)+ Node 22 环境装的,npm 这条最省心。

# 路线 1:npm(需 Node.js 22+,我用的就是这条)
npm install -g @openai/codex

# 路线 2:官方安装脚本(macOS / Linux)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# 路线 3:Homebrew(官方文档列为可选,命令以官方为准)
brew install codex   # 实测示意,具体 formula 名以官方为准

# 验证
codex --version

装完第一次跑 codex,会弹登录。两种鉴权方式:

# 方式 A:ChatGPT 账号登录(推荐,Plus/Pro/Business/Edu/Enterprise 已含额度)
codex            # 选 "Sign in with ChatGPT",浏览器走 OAuth

# 方式 B:API Key(无头 / CI 场景)
export OPENAI_API_KEY="sk-..."

踩坑提醒(中文区必看):

OAuth 回调要能打开浏览器:大陆网络环境下 chatgpt.com 的 OAuth 页和 codex 的模型请求都走 OpenAI 域名,网络不通会卡在「等待浏览器授权」那一步。这是国内用 Codex 最大的现实门槛,务必先确认网络可达性。
ChatGPT 订阅折人民币:走账号登录需要 Plus(约 20 美元/月,折合约 145 元)及以上订阅;走 API Key 则按 token 计费。预算敏感、或网络不便的同学,我更推荐先看下面的「国产替代」段落。
凭据存系统钥匙串:OAuth 凭据进 macOS Keychain / Windows 凭据管理器,不落明文配置文件,这点比手抄 key 安全。

配置文件在 ~/.codex/config.toml(以官方 CLI 文档为准),可设默认模型、审批模式等:

# ~/.codex/config.toml 示意
model = "gpt-5.5"
approval_policy = "on-request"   # 改命令/写文件前征求同意,值以官方为准

模型也能命令行临时切:codex -m gpt-5.4。

@ 提及:把上下文喂准

这是我每天用得最多的功能。输入框打 @,弹出统一选择器,文件、目录、插件、skills 一起搜:

> 帮我重构 @src/auth/login.ts,沿用 @src/utils/http.ts 的错误处理风格

实测手感:@ 选中后它会真的把文件内容纳入上下文,而不是只看文件名瞎猜。对比我之前手动 cat 文件再粘贴的笨办法,token 利用率和命中率都明显更好。和 Claude Code 的 @ 思路一致,Codex 的优势是一个选择器把插件和 skills 也统进来了。

Goals 自治执行:丢个目标让它跑

Goals 是 Codex 和 Claude Code 体感分叉最大的地方。开了 Goal 模式,你给一个目标,它会自己拆解、连续多轮往前推,官方称可持续「数小时到数天」。

我的真实跑法是:进入会话后描述一个端到端目标,然后让它自治执行,中途只在它请求审批(改文件 / 跑命令)时介入。

> /goal 给这个 Express 项目加上 JWT 鉴权中间件:
  1) 新建 middleware/auth.ts
  2) 在 routes/ 下所有受保护路由挂上
  3) 补一个 /login 签发 token 的接口
  4) 写最小单测并跑通

它会列计划 → 逐项实现 → 自己跑 npm test → 看到红就回头修。这种「闷头干到绿为止」的轴劲儿,是我选它跑长任务的主要理由。

端到端实战:跑一个真实工程任务

我用一个真实的小任务测全流程:给一个已有 Node + Express 仓库加 JWT 鉴权 + 单测。下面是我整理的终端 log 片段(已脱敏,实测示意,以你环境为准):

$ codex
╭───────────────────────────────────────────────╮
│  Codex CLI  ·  model: gpt-5.5  ·  cwd: ~/demo  │
╰───────────────────────────────────────────────╯

> /goal 给项目加 JWT 鉴权中间件并补单测，跑通后停

● Planning  ─────────────────────────────
  1. 读取 package.json / 现有路由结构      [@ routes/ @ package.json]
  2. 新建 middleware/auth.ts
  3. 挂载到受保护路由
  4. 新增 /login 接口
  5. 写 auth.test.ts，npm test 跑绿

● Editing middleware/auth.ts ……          (+38 −0)
● Editing routes/users.ts ……             (+4 −1)
● Running: npm test
  ✗ 1 failing — token 过期断言写反
● Re-editing auth.test.ts ……             (+2 −2)
● Running: npm test
  ✓ 6 passing  (1.2s)

Done. 6 tests passing. Modified 4 files, added 2.

我这次跑下来的实测数据(单次任务,实测示意,以你环境为准):

指标	我的实测值
总耗时	约 6 分 40 秒
模型	gpt-5.5(默认)
自动迭代轮次	4 轮(含 1 次自查修红)
输入 token(累计)	约 4.2 万
输出 token(累计)	约 9.5 千
人工介入次数	2 次(审批写文件 / 审批跑命令)
最终结果	一次跑绿,6 个单测通过

最爽的一刻是它跑测试见到 1 个 failing 后,没等我说话就自己回去改断言再重跑——这就是 Goals 的价值。

codex doctor:卡住了先跑它

任何 CLI agent 都会遇到「环境神秘故障」,Codex 给了官方诊断命令:

codex doctor

0.135.0 起它会报环境、Git、终端、app-server、线程清单等信息。我实测遇到过两个典型问题,都靠它定位:

模型选不出 GPT-5.5:doctor 显示 CLI 版本偏旧。官方建议很直接——更新 CLI / IDE 扩展 / app 到最新即可。
MCP / 网络连不上:doctor 会把 auth、network、config 状态列出来,大陆环境下基本能一眼看出是网络层挡了 OpenAI 域名。

诊断信息也是开 issue / 找支持时的标准附件,养成「报错先 codex doctor」的习惯能省大量来回。

Codex doctor 排错决策路径

Codex CLI vs Claude Code:我的真实手感对比

两个我都长期在用,下面是按我自己的体感打的分(主观实测,非官方 benchmark):

维度	Codex CLI(GPT-5.5)	Claude Code(Opus 4.8)
长任务自治	更"轴",Goals 会闷头干到目标达成	同样强,但更爱中途和你确认
单步代码质量	高,复杂重构稳	高,边界 case 处理细
交互细腻度	够用,偏工程化	更顺滑,反馈更密
生态 / Skills	插件 marketplace 起步,@ 选择器统一	Skills/plugins 更成熟(Skills 教程)
多 agent 编排	Goals 偏单线深挖	Subagents 团队更成熟(多智能体)
大陆可用性	需通 OpenAI 网络 + ChatGPT 订阅	同样需海外网络,可接国产模型绕开

我的结论:目标明确、需要它独立干长活的任务交给 Codex 的 Goals;需要密集对话、边写边商量、或要复用一堆 Skills 的活留给 Claude Code。 全套四工具(含 Cursor)怎么分工,看横评 2026。

中文区现实建议:网络与国产替代

Codex CLI 体验好,但它的命门在大陆是「全程依赖 OpenAI 网络 + 需要 ChatGPT 订阅」。如果你网络不便或想省钱:

优先国产路线:把 Claude Code 接国产模型(Qwen3-Coder、GLM、kimicc 等)是更落地的选择,响应快、按人民币计费、网络无门槛。
DeepSeek 自建工作流:轻量编程任务也可以直接用 DeepSeek API 自己搭。
真要用原版 Codex:确保网络对 chatgpt.com 和 OpenAI API 域名稳定可达,再走 npm 安装。

结论:谁该装 Codex CLI

值得装,如果你:① 有稳定的 OpenAI 网络环境;② 已经付 ChatGPT 订阅、想榨干额度;③ 喜欢「丢目标、它自治跑完」的工作流。GPT-5.5 + Goals 这套组合,在长任务上确实顶。

可以缓一缓,如果你:在大陆且网络不便、预算敏感——那把 Claude Code 配国产模型才是更稳的起点。

想系统学会怎么把这些 CLI agent 真正用进日常开发、而不是停在「装上了」?点此了解并立即订阅 →

FAQ

Q1:Codex CLI 怎么装、用哪个命令? A:最省心是 npm install -g @openai/codex(需 Node.js 22+),或用官方脚本 curl -fsSL https://chatgpt.com/codex/install.sh | sh。装完跑 codex 走 ChatGPT 登录或设 OPENAI_API_KEY。具体以官方 CLI 文档为准。

Q2:Codex 用的是 GPT-5.5 吗?要不要单独开? A:截至 2026-05-30,GPT-5.5 已是 Codex 的默认模型,新建会话即用。看不到就更新到最新版。也可 codex -m gpt-5.4 临时切别的模型。来源:Codex 模型页。

Q3:Goals(目标模式)和普通对话有啥区别? A:Goals 在 0.133.0 起默认开启,会朝一个目标连续自治多轮、有独立进度跟踪,官方称可持续数小时到数天;普通对话偏一问一答。长任务用 Goals 体感最明显。

Q4:大陆能正常用吗? A:能装,但全程依赖对 OpenAI / ChatGPT 域名的稳定访问,且账号登录需 ChatGPT 订阅。网络不便或想省钱,建议改走 Claude Code 接国产模型的方案。

本文版本号与功能基于 2026-05-30 对 OpenAI Codex 官方 changelog、GitHub Releases、模型页的核对;Codex 迭代极快,一切以官方最新为准。文中 token / 耗时 / 对比均为我的实测示意,你的环境可能不同。