OpenAI Codex CLI 完全指南：2026年最值得入手的终端 AI 编程助手（安装配置 + 多智能体工作流实战教程）

{</* resource-info */>}

来源：github.com/openai/codex — 官方 splash 截图

一、为什么 Codex CLI 是 2026 年开发者必须关注的工具 #

2026 年的开发者工具赛道正在经历一场静默革命。从代码补全（GitHub Copilot）到对话式编程（ChatGPT），再到如今的终端原生 AI Agent——开发工具的进化速度远超大多数人的预期。

OpenAI Codex CLI 正是这场革命的核心参与者之一。这个基于 Rust 重写的开源终端智能体，在 GitHub 上已经积累了超过 83,000 颗 Star，并且以每月数千颗的速度持续增长。它的定位非常清晰：不是一个聊天窗口，而是一位常驻终端的 AI 软件工程师——能够读取你的代码库、修改文件、执行命令、运行测试、审查代码，甚至在云端沙盒中独立完成长达数小时的开发任务。

与 Claude Code 并列为当下两大终端 AI 编程旗舰，Codex CLI 的独特优势在于：

零额外成本：已订阅 ChatGPT Plus/Pro 的用户无需另付 API 费用即可直接使用
开源可扩展：Apache-2.0 协议，社区可自由 fork、定制、扩展
多平台覆盖：CLI + VS Code 插件 + JetBrains 插件 + 云端 Agent + macOS/Windows 桌面端
多智能体架构：支持同时运行最多 6 个并发子智能体，分别承担探索、实现、审查等不同角色
MCP 生态集成：通过 Model Context Protocol 连接外部工具链（数据库、API、文档等）

如果你还在复制粘贴 ChatGPT 的代码片段，那么 Codex CLI 将彻底改变你的工作方式。

二、五分钟极速安装：从零到第一个 AI 编程任务 #

Codex CLI 的安装过程被设计得极其简洁。以下是在 macOS、Linux 和 Windows（WSL）上的标准流程。

2.1 前置要求 #

Node.js 18+（npm 安装路径）
或者 macOS 用户可直接使用 Homebrew 安装原生 Rust 二进制版本
一个 ChatGPT Plus/Pro/Business 账户（推荐）或 OpenAI API Key

2.2 三种安装方式 #

方式一：npm 全局安装（跨平台通用） #

npm install -g @openai/codex
codex --version

方式二：Homebrew 安装（macOS 原生二进制，无需 Node.js） #

brew update
brew install --cask codex
codex --version

方式三：一键脚本安装 #

curl -sSL https://releases.openai.com/codex/install.sh | bash

2.3 首次登录与认证 #

codex login

系统会自动唤起浏览器，引导你使用 ChatGPT 账户授权。授权完成后，终端会显示登录成功的确认信息。这种方式无需手动管理 API Key，且不会额外产生 API 费用——所有用量计入你的 ChatGPT 订阅额度。

如果你偏好 API Key 模式（适合企业环境或需要精细计费控制）：

export OPENAI_API_KEY="sk-..."
codex

或在 ~/.codex/config.toml 中配置：

preferred_auth_method = "apikey"

2.4 验证：运行你的第一个任务 #

进入任意项目目录，尝试这个经典测试：

cd ~/projects/your-repo
codex "为 src/utils/date.ts 中的 parseDate 函数添加单元测试"

Codex 会：

扫描项目结构，理解测试框架（Jest/Vitest/Mocha 等）
读取 parseDate 的实现逻辑
在对应测试目录生成覆盖正常输入、边界条件和异常处理的测试用例
运行测试并报告结果
以 diff 形式展示修改，等待你确认

三、核心工作流：从"写代码"进化为"指挥 AI 写代码" #

Codex CLI 的真正威力不在于它能生成一段代码，而在于它能端到端地完成一个开发任务。要发挥这种威力，关键在于转变思维方式：不要把它当成搜索引擎或代码片段库，而是当成一位能理解自然语言指令并自主执行的团队成员。

3.1 提示词的四要素结构 #

优秀的 Codex 指令通常包含四个部分：

要素	说明	示例
目标	你要构建或修改什么	“实现一个基于 JWT 的用户认证中间件”
上下文	涉及哪些文件或模块	“使用 Go + Gin 框架，数据库连接在 db/conn.go”
约束	必须遵守的规则	“不要破坏现有 API 接口，所有新函数必须带单元测试”
完成条件	如何验证任务完成	“运行 `go test ./...` 全部通过，并提供 curl 测试命令”

错误示范： “帮我写一个登录函数。”

正确示范：

“使用 Go 语言和 Gin 框架帮我实现一个用户认证系统：
包含注册和登录两个 REST 接口，使用 JWT 认证
连接 MySQL 数据库，用户信息表结构参考现有 db/schema.sql
帮我运行起来，并提供 curl 测试命令验证注册和登录流程”

Codex 会依次执行：创建项目结构 → 编写代码 → 安装依赖 → 执行 go run → 返回访问地址和测试命令。

3.2 三种核心交互模式 #

Codex CLI 提供三种审批模式，对应不同的信任级别：

模式	文件读取	文件编辑	命令执行	适用场景
Auto（默认）	自动允许	需确认	需确认	日常开发，保留安全边界
Read Only	自动允许	禁止	禁止	代码审查、项目分析、学习代码库
Full Access	自动允许	自动允许	自动允许	可信环境、CI/CD 流水线、Docker 容器

启动时指定模式：

codex --sandbox read-only          # 纯分析模式
codex --sandbox workspace-write    # 可编辑，但运行不可信命令需确认
codex --full-auto                  # 全自动（仍保留沙箱）
codex --yolo                       # 完全关闭沙箱和审批（仅限隔离环境！）

重要安全提示： --yolo（全名 --dangerously-bypass-approvals-and-sandbox）只应在 CI/CD 容器或完全隔离的虚拟机中使用。千万不要在本地开发机或对生产代码库直接使用。

四、AGENTS.md：让 AI 真正理解你的项目 #

这是 Codex CLI 最被低估却最具影响力的功能。在项目根目录创建 AGENTS.md 文件，Codex 会在每次任务前自动读取它——相当于给 AI 工程师一份项目入职手册。

4.1 AGENTS.md 示例模板 #

# AGENTS.md - AI 开发助手项目指南

## 项目结构
- `src/` —— 业务逻辑代码
- `tests/` —— 测试文件，与源码一一对应
- `migrations/` —— 数据库迁移脚本，使用 Alembic

## 技术栈与规范
- 语言：Python 3.11+
- 框架：FastAPI
- 代码风格：Black + isort，行长度 100
- 类型提示：所有函数必须有类型注解

## 测试要求
- 运行 `pytest tests/` 执行全部测试
- 新功能覆盖率不得低于 85%
- 使用 pytest-asyncio 处理异步测试

## Git 规范
- 提交信息格式：`[类型] 简短描述`，类型包括 Feat/Fix/Refactor/Docs
- 不允许直接提交到 main 分支，必须通过 PR

4.2 进阶：分层配置 #

Codex 支持嵌套 AGENTS.md。你可以在子目录（如 src/api/、src/ml/）放置更具体的规范文件，Codex 会自动合并并优先应用最相关的配置。这对于大型单体仓库或多模块项目尤为实用。

五、多智能体并行开发：一人即团队 #

2026 年 4 月之后的 Codex CLI 版本引入了 Subagents 功能——允许同时运行最多 6 个并发子智能体，每个承担不同角色。

5.1 典型角色分工 #

角色	职责	启动方式
explorer	扫描代码库、映射依赖关系、定位相关文件	自动附加于复杂任务
worker	执行具体的代码实现、文件修改	默认主智能体
reviewer	在提交前审查代码质量、检查安全风险	`/review` 命令触发
tester	生成测试用例并验证覆盖率	在指令中明确要求

5.2 实战：并行实现一个完整功能 #

假设你要为电商项目添加"会员折扣"功能，可以拆分为三个独立子任务：

终端 1 - 业务逻辑（CLI）：

codex "在 pricing.py 中添加 loyalty_discount(price, customer_tier) 函数。等级：bronze(0%)/silver(5%)/gold(10%)。未知等级抛出 ValueError。不要修改其他函数。"

云端 2 - 测试生成（Codex Cloud）： 在 chatgpt.com/codex 提交：

“为 loyalty_discount 函数生成完整测试，覆盖各等级、未知等级、负数价格、零价格、小数价格。不要修改 pricing.py。”

VS Code 3 - 文档更新（IDE 插件）：

“在 README.md 中添加 loyalty_discount 的文档：函数签名、等级表格、一个使用示例。”

三个任务并行推进。当实现完成后，测试验证其正确性，文档同步更新——整个流程无需人工等待串联。

六、杀手级特性：MCP 集成与技能系统 #

6.1 MCP（Model Context Protocol）连接外部世界 #

MCP 是 2025-2026 年 AI 工具生态最重要的开放标准之一。通过 MCP，Codex CLI 可以连接：

数据库：直接查询 PostgreSQL/MySQL 的表结构作为代码生成上下文
API 文档：读取 Swagger/OpenAPI 规范生成客户端代码
知识库：连接企业内部 Wiki 或 Notion 获取业务规则
监控平台：读取错误日志自动定位 Bug

配置 MCP 工具：

codex /mcp          # 查看已配置的 MCP 工具列表
codex /apps         # 浏览可用的应用连接器

6.2 Skills 技能系统：封装可复用的工作流 #

如果你发现某些提示词模式反复使用且效果良好，可以将其封装为 Skill。

$skill-creator      # 启动内置技能创建向导

Skills 遵循开放的 Agent Skills 标准，可在 Claude Code、GitHub Copilot 等工具间共享。常见技能场景：

自动生成本地化翻译 PR
按检查表审查代码规范
根据错误日志生成修复补丁
将 Python 脚本转换为 TypeScript 实现

七、安全架构：Linux Landlock + macOS Seatbelt 双沙箱 #

Codex CLI 的安全设计是其区别于早期 AI 编程工具的关键。核心安全机制包括：

层级	技术	保护范围
进程级沙箱	Linux Landlock / macOS Seatbelt	限制文件系统访问范围
网络隔离	默认禁止出站网络	防止数据外泄（除非显式授权）
命令审批	三类审批模式	人工确认或自动策略判断
审计日志	SQLite 本地数据库	所有操作可追溯、可 diff、可回滚
敏感变量屏蔽	环境变量白名单	防止 API Key、密码意外泄露

对于企业级部署，Codex 还支持：

Hook 引擎：在 Prompt 提交前拦截审计，在工具执行后自动触发测试
RBAC 工作空间：区分管理员和普通用户的权限范围
Context Compaction：长会话中自动压缩历史上下文，防止敏感信息长期驻留

八、模型选择策略：什么时候用 GPT-5.3-Codex，什么时候用 Spark #

Codex CLI 默认使用 gpt-5.3-codex——OpenAI 专为编程优化的旗舰模型。但 2026 年还新增了一个特殊变体：GPT-5.3-Codex-Spark。

模型	核心优势	最佳场景	注意事项
gpt-5.3-codex	复杂推理、架构设计、代码审查、大规模重构	多文件重构、Bug 排查、长期任务	标准模型，通用首选
gpt-5.3-codex-spark	超高速响应（1000+ tokens/秒）、实时协作	即时编辑、快速迭代、交互式开发	仅 ChatGPT Pro 用户可用；最小化目标修改；测试自动运行需手动触发

Spark 是 OpenAI 与 Cerebras WSE-3 芯片合作的产物，是首个非 NVIDIA 平台运行的 OpenAI 生产模型。对于追求"所想即所得"的流畅编码体验，Spark 是不二之选。

运行时切换模型：

codex -m gpt-5.3-codex          # 启动时指定
codex -m gpt-5.3-codex-spark    # 使用 Spark 极速模式
/model                           # 交互式切换（运行中）

推理等级配置：

# ~/.codex/config.toml
model_reasoning_effort = "high"     # 复杂任务，消耗更多 token
model_reasoning_effort = "medium"   # 日常开发（默认）
model_reasoning_effort = "low"      # 简单任务，省 token

九、Codex CLI vs Claude Code：如何选择你的终端 AI 搭档 #

两者都是 2026 年终端 AI 编程的顶级选择，但气质不同：

维度	Codex CLI	Claude Code
定价模型	ChatGPT 订阅捆绑（Plus $20/月起）	Claude 订阅独立（Pro $20/月起）
开源程度	Apache-2.0，完全开源可定制	闭源，通过 API 调用
上下文窗口	1M tokens（官方标称）	1M+ tokens（实测表现更优）
生态系统	MCP 生态 + OpenAI 全家桶	Skills 系统 + Superpowers 框架
代码库规模	中大型项目表现良好	超大型仓库（10万+文件）优势更明显
企业功能	GitHub 集成、云端并行、Hook 引擎	深度审计、多模态输入（截图/PDF）
入门门槛	更低（ChatGPT 用户零额外成本）	略高（需单独订阅）

我的建议：

如果你已经是 ChatGPT Plus/Pro 用户，从 Codex CLI 开始——零额外成本，覆盖 80% 的日常需求
如果你需要处理超大规模单体仓库或需要极致的代码审查深度，补充使用 Claude Code
两者并非二选一。许多开发者早晨用 Codex 快速原型，下午切 Claude 做深度重构——工具是为你服务的，不是你为工具站队

十、实战案例库：十个可直接复制的 Codex 指令模板 #

10.1 新手 onboarding #

codex "解释这个项目的架构，画出主要模块的依赖关系，并告诉我作为新成员应该先看哪三个文件"

10.2 技术债务清理 #

codex "找出 src/ 目录下所有未使用的导入和函数，删除它们并确保测试仍然通过"

10.3 依赖升级 #

codex "将 React 从 18 升级到 19，处理所有 breaking changes，运行测试并修复失败项"

10.4 性能优化 #

codex "分析 api/routes.py 中的 N+1 查询问题，用 joinload 或 selectinload 优化，提供优化前后的 benchmark 对比"

10.5 安全加固 #

codex "扫描所有 API 端点，检查是否缺少身份验证或输入验证。为发现的每个漏洞提供修复方案和测试用例"

10.6 文档生成 #

codex "为所有公共函数生成 Google 风格的 docstring，并更新 README.md 的 API 参考章节"

10.7 跨语言迁移 #

codex "将 scripts/data_processor.py 转换为等效的 TypeScript 实现，保持所有逻辑和错误处理行为一致"

10.8 CI/CD 配置 #

codex "为这个项目创建 GitHub Actions 工作流：在 PR 时运行 lint + test + typecheck，在合并到 main 时自动构建 Docker 镜像并推送到 GHCR"

10.9 错误诊断 #

codex "这个错误日志是什么意思？帮我定位根因并修复：[粘贴报错]"

10.10 代码审查（提交前自检） #

codex /review --uncommitted

十一、从入门到精通：30-60-90 天成长路线图 #

第 1-30 天：建立基础习惯 #

在 3 个不同项目中安装并运行 Codex CLI
为每个项目编写初版 AGENTS.md
熟练使用 Auto 和 Read Only 两种模式
完成 10 次以上的代码生成/修改任务
学会使用 /review 做提交前自检

第 31-60 天：进阶工作流 #

配置 2-3 个 MCP 工具连接（数据库/API/文档）
创建第一个自定义 Skill
尝试一次多智能体并行任务（CLI + Cloud 组合）
在团队代码库中推广 AGENTS.md 规范
对比测试 gpt-5.3-codex 和 spark 在不同任务上的表现

第 61-90 天：团队与自动化 #

设置 CI/CD Hook 实现自动代码审查
建立团队共享的 Skills 仓库
用 Codex Cloud 处理跨时区协作的长时任务
形成团队内部的 Prompt 模板库和最佳实践文档
评估是否引入 Claude Code 作为补充工具

十二、常见问题 FAQ #

Q：Codex CLI 是免费的吗？ A：工具本身开源免费。但 AI 推理需要 OpenAI 模型支持。ChatGPT Plus/Pro/Business 用户可直接使用（计入订阅额度）；API Key 用户按 token 计费（输入 $1.50/1M tokens，输出 $6.00/1M tokens）。

Q：没有 ChatGPT 订阅能用吗？ A：可以，使用 API Key 模式。但 Plus 用户登录后每月会获赠 $5 API 额度（Pro 用户 $50），30 天内有效。

Q：Codex 会泄露我的代码吗？ A：Codex CLI 在本地运行，代码不会上传用于模型训练（可在 Data Controls 中关闭）。云端任务在隔离沙盒中执行，任务结束后环境销毁。

Q：支持哪些编程语言？ A：Python、JavaScript/TypeScript、Go、Rust、Java、C/C++、Ruby、PHP 等主流语言。在 Python 和 JavaScript 上表现最优。

Q：Windows 能用吗？ A：CLI 支持 Windows（推荐 WSL2）。2026 年 4 月起还推出了原生 Windows 桌面端 App。

结语：AI 编程 Agent 时代的入场券 #

2026 年，“Vibe Coding”（氛围编程）已经成为主流开发范式——开发者用自然语言描述意图，AI Agent 负责实现细节。OpenAI Codex CLI 是进入这个时代的最便捷入口之一：它开源、免费部署、与 ChatGPT 生态无缝衔接，且以惊人的速度持续进化。

不要观望。今天安装，明天你的开发效率就可能提升一个数量级。

延伸阅读：