前言

Github：https://github.com/HealerJean

博客：http://blog.healerjean.com

一、开始使用

1、简介

Codex CLI 是 OpenAI 开源的终端优先编码代理（Apache 2.0），主要用 Rust 编写。

1）四个使用界面

这四个界面共享同一份 ~/.codex/ 配置和认证。

2）核心能力

• 读、写、运行代码，支持多文件修改
• 子代理并行执行任务
• MCP 服务器集成（与 Claude Code / Cursor 兼容）
• 图片输入（截图/设计稿）与图片生成
• 代码审查（/review）
• Web 搜索
• Codex Cloud 远程任务
• 审批模式三级控制

2、模型选择与推理强度

Codex CLI 支持多个模型，默认会根据订阅和任务自动选择。

1）可用模型（2026）

2）切换模型

# 启动时指定
codex --model gpt-5.5

# 会话内切换
/model gpt-5.4-mini

3）推理强度（reasoning_effort）

可在 config.toml 中设置 plan_mode_reasoning_effort = "high" 调整规划时的推理强度。

4）多 Provider 支持

Codex CLI 支持其他兼容 OpenAI API 的提供商：

codex --provider openrouter
codex --provider ollama
codex --provider deepseek
# 等

设置对应环境变量 PROVIDER_API_KEY 和 PROVIDER_BASE_URL。

二、日常使用

1、交互模式

# 进入交互模式
cd /path/to/project
codex

# 启动时直接带提示
codex "解释这个代码库的结构"

进入 TUI 后：

• 输入提示后按 Enter 提交
• @ 触发模糊文件搜索
• ! 开头输入本地 Shell 命令（如 !ls）
• Tab 在 Codex 执行时排队后续输入
• Ctrl+G 打开编辑器写长提示（使用 VISUAL 或 EDITOR 环境变量定义的编辑器）

Codex 会：

1. 读取工作目录的文件
2. 对每个修改/命令展示 diff 等待审批
3. 支持多轮对话持续迭代

2、常用 Slash 命令

3、 审批模式

Codex CLI 提供三级审批控制，用 /permissions 在会话中切换：

命令行指定：

codex --approval-mode auto
codex --approval-mode read-only
codex --yolo  # Full Access 别名

Full Access / --yolo 请仅在信任的 Git 仓库中使用。

3、恢复会话

Codex 本地存储所有会话记录，支持恢复：

# 交互选择器
codex resume

# 上次会话
codex resume --last

# 跨目录会话
codex resume --all

# 指定会话 ID
codex resume <SESSION_ID>

恢复后的会话保留原始转录、历史规划和审批记录。

非交互模式也可恢复：

codex exec resume --last "修复你发现的竞态条件"

4、 快捷键与技巧

三、进阶能力

1、子代理（Subagents）

Codex 2026 版内置子代理原语，父代理可以派生子代理并行执行任务：

/spawn "分析 src/api/ 下所有路由的性能瓶颈"
/spawn --model gpt-5.4-mini "为这些函数写单测"

每个子代理拥有独立的上下文窗口，结果流式返回父会话。适合：

• 大型重构：父代理 fan-out 给多个子代理探索后汇总
• 并行代码生成：如同时生成多个组件及对应测试
• 验收：子代理审查代码质量，父代理决定是否合并

子代理的角色可在 config.toml 的 [agents] 段预配置。

2、MCP 扩展配置

Codex CLI 是一等 MCP 客户端，与 Claude Code / Cursor 的 MCP 服务器语法兼容。

1）配置方式

在 ~/.codex/config.toml 或项目级 .codex/config.toml 中添加：

[mcpServers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]

[mcpServers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_..." }

[mcpServers.custom-server]
command = "uvx"
args = ["my-mcp-server"]
supports_parallel_tool_calls = true

2）CLI 管理 MCP

codex mcp install <name>       # 安装 MCP 服务器
codex mcp list                 # 列出已安装
codex mcp remove <name>        # 移除

supports_parallel_tool_calls = true 可启用并行 MCP 调用，多工具流水线下显著加速。

3、Codex Cloud

Codex Cloud = Codex 的云端离线任务执行平台，和本地 codex/ 本地 AI 工具（OpenCode、Claude Code 本地模式）是两套完全独立运行模式：

• 本地模式：AI 在你电脑本地运行，占用 CPU / 内存，关终端 / 笔记本任务直接中断；

• Codex Cloud：任务在 OpenAI 云端独立隔离微 VM（沙箱虚拟机） 执行，不占用你本机任何资源，断开电脑也能后台跑完任务。

# 交互式浏览
codex cloud

# 直接启动任务
codex cloud exec --env ENV_ID "分析所有未关闭的 Issue"

# 多次运行取最佳（1-4次）
codex cloud exec --env ENV_ID --attempts 3 "重构用户模块"

适用场景：

• 长时间大型重构本地电脑长时间跑重度重构会发烫、卡顿、占用大量内存；云端 VM 无限时后台执行，不影响你本机正常写代码。

• 夜间自动化维护：下班前提交任务，关闭电脑回家，夜间云端自动完成：代码巡检、全量单元测试、文档同步、lint 修复、生成周报，第二天上班直接拿结果 diff。

• 关机 / 断网后任务持续运行：本地工具只要关闭终端、休眠笔记本就中断任务；Codex Cloud 完全依托 OpenAI 服务器，断电、断网、关机都不会终止任务，随时打开面板查看进度。

4、图片输入与生成

1）图片输入

# 单张
codex -i screenshot.png "实现这个设计"

# 多张
codex --image img1.png,img2.jpg "对比这两张图并生成代码"

支持 PNG、JPEG 等常见格式。

2）图片生成

直接通过自然语言请求：

帮我生成一个 SVG 图标，表示"数据导出"

或在提示中显式引用 $imagegen。底层使用 gpt-image-2 模型。

5、代码审查（/review）

输入 /review 进入审查功能：

启动独立审查 Agent，生成优先级排序的可操作反馈，不影响工作树。

6、非交互模式（codex exec）

适合 CI/CD 和自动化脚本：

codex exec "修复 CI 失败"
codex exec "为 src/utils.ts 添加类型注释"

输出可直接管道处理。可组合成工作流：

codex exec "生成 CHANGELOG 条目" && git add CHANGELOG.md && git commit

7、Web 搜索

Codex CLI 内置 Web 搜索工具，默认使用缓存结果（降低注入风险）：

# 使用实时结果
codex --search "实现这个 Prompt"

# 配置中控制
web_search = "live"    # 实时
web_search = "cached"  # 缓存（默认）
web_search = "disabled" # 禁用

四、配置与定制

1、配置文件

Codex CLI 使用 TOML 格式的配置文件。

1）全局配置 ~/.codex/config.toml

[default]
model = "gpt-5.5"
approval_mode = "auto"
plan_mode_reasoning_effort = "high"
web_search = "cached"

[agents.code-reviewer]
model = "gpt-5.4-mini"
reasoning_effort = "medium"

[mcpServers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path"]

2）项目级配置 .codex/config.toml

在项目根目录创建 .codex/config.toml 覆盖全局配置。

3）环境变量

2、AGENTS.md / CODEX.md

在项目根目录创建 CODEX.md（或 AGENTS.md，Codex 按优先顺序读取），提供项目级自定义指令：

CODEX.md > AGENTS.md > CLAUDE.md，命中第一个即停止。与 Claude Code 混用时建议用 CODEX.md 互不干扰。

# Project context
- Stack: Next.js 16 + TypeScript + Tailwind v3
- Backend: PocketBase
- Deploy: Cloudflare Pages, static export

# Don't
- Do not introduce new dependencies without asking
- Do not use next/image (breaks static export)
- Use the cn() helper for className merges

这是提升输出质量最有效的单一手段。

3、自定义指令与 Hooks

1）Slash 命令

自定义可复用的 Prompt 快捷方式，保存在 ~/.codex/slash-commands/。

2）Hooks

.codex/hooks.toml 中定义生命周期钩子：

[hooks]
# 编辑后自动运行类型检查
post-edit = "npm run typecheck"

# 提交前检查
pre-commit = "npm run lint"

# 子代理生成前
pre-spawn = "echo 'Spawning subagent...'"

3）Auto-review

# .codex/config.toml
auto_review = true

启用后每次暂存或推送前自动派生子代理审查 diff。

4、Shell 补全

codex completion zsh >> ~/.zshrc
source ~/.zshrc

支持 bash、zsh、fish。

五、进阶参考

1、与 Claude Code / OpenCode 对比

1）用 Codex CLI 当：

• 你已经是 OpenAI 生态用户（ChatGPT Plus / API Key）
• 需要多界面覆盖（CLI + IDE + Desktop + Web）
• 需要 Computer Use 和图片输入
• 需要 Codex Cloud 长时间后台任务
• 想要 Rust 构建的低延迟体验

2）用 Claude Code 当：

• 你使用 Anthropic 模型
• 需要 Deep Research 功能
• 需要 Web 版 Claude Code

3）用 OpenCode 当：

• 想要最大化的模型选择和灵活性
• 需要本地模型和 LSP 支持
• 需要 CI 集成和远程协作
• 看重完全开源和可定制性