Codex CLI 深度指南：终端中的编码智能体
Codex CLI 是整个 Codex 产品族的核心引擎——App、IDE 扩展、Cloud 都构建在它之上。掌握 CLI，就掌握了 Codex 最完整、最灵活的能力。本篇将带你深入 CLI 的每一个角落：从交互式 TUI 的快捷键到非交互式脚本化执行，从代码审查到云端任务委派。
本篇核心收获：
- 熟练使用 TUI 的所有交互技巧：
@文件搜索、!Shell 命令、Esc历史回溯、Ctrl+G编辑器 - 掌握
/review的四种代码审查模式 - 了解所有 Slash Commands 及其使用场景
- 熟记关键命令行选项，构建个性化启动命令
- 使用 Feature Flags 管理实验性功能
- 通过
codex cloud exec委派云端任务 - 建立完整的日常开发工作流：审查 → 修 Bug → 重构 → 文档
一、交互模式（TUI）：你的终端编码搭档
启动 Codex CLI 最基本的方式就是直接运行 codex，进入全屏终端 UI（TUI）。TUI 是一个完整的对话式工作环境，Codex 可以在其中读取仓库、编辑代码、运行命令，你则可以实时审查它的每一个动作。
Bash
# 直接启动 TUI（推荐，最简单直接）
codex
# 带初始提示词启动
codex "Explain this codebase to me"
# 指定工作目录和模型
codex --cd ~/projects/my-app --model gpt-5.4 "Fix the failing tests"1.1 TUI 快捷键与交互技巧
掌握以下快捷键，让你在 TUI 中如鱼得水：
| 快捷键 / 操作 | 功能 | 使用场景 |
|---|---|---|
@ • 文件名 | 模糊文件搜索，Tab/Enter 插入路径 | 快速引用项目文件作为上下文 |
! • 命令 | 执行本地 Shell 命令（如 !ls、!git log） | 快速查看文件列表、Git 状态等，输出作为上下文提供给 Codex |
Esc Esc（双击） | 编辑上一条用户消息；继续按 Esc 回溯更早的历史 | 修正提示词后从该点重新 fork 对话 |
Ctrl+G | 打开 $VISUAL（或 $EDITOR）编辑长提示词 | 编写复杂的多行提示词时，在熟悉的编辑器中撰写 |
Ctrl+L | 清屏但保留当前对话 | 终端太乱时清理视觉，对话上下文不丢失 |
Ctrl+C | 中断当前任务 / 退出会话 | 终止正在运行的任务 |
Enter（任务运行中） | 注入新指令到当前轮次 | 任务执行过程中补充方向指引 |
Tab（任务运行中） | 排队一条跟进提示词，等当前轮次结束后发送 | 提前准备下一步指令 |
Up / Down | 在输入框中浏览草稿历史 | 恢复之前输入过但未发送的提示词 |
`@` 文件搜索的妙用
在输入框中输入 @ 后，Codex 会对工作区根目录进行模糊匹配。你可以输入部分文件名、路径片段，然后用
Tab 或 Enter 选中。这比手动粘贴完整路径快得多，尤其适合引用深层目录中的文件。
1.2 语法高亮与主题
TUI 会自动对 Markdown 代码块和文件 diff 进行语法高亮，让代码审查和调试更加直观。
Bash
# 在 TUI 中使用 /theme 命令
/theme/theme 会打开主题选择器，支持：
- 实时预览：在选择器中即时预览不同主题效果
- 持久化保存：选中后自动写入
~/.codex/config.toml的tui.theme字段 - 自定义主题：将
.tmTheme文件放入$CODEX_HOME/themes目录，即可在选择器中出现
1.3 会话恢复（codex resume）
Codex 会在本地存储完整的会话记录（transcript），你可以随时恢复之前的对话，无需重复提供上下文。
Bash
# 打开会话选择器，浏览最近的交互式会话
codex resume
# 显示所有目录的会话（不限于当前工作目录）
codex resume --all
# 直接恢复最近一次会话
codex resume --last
# 恢复指定 Session ID
codex resume 7f9f9a2e-1b3c-4c7a-9b0e-...非交互式会话也能恢复：
Bash
# 恢复上次的 exec 会话，并追加新指令
codex exec resume --last "Fix the race conditions you found"
# 恢复指定会话并继续
codex exec resume 7f9f9a2e-... "Implement the plan"恢复时保留原始 transcript、plan 历史和审批状态，Codex 可以利用之前的上下文继续工作。使用 --cd 或 --add-dir 可以在恢复前调整工作环境。
1.4 编辑器集成（Ctrl+G）
当提示词较长或需要精心编写时，在输入框按 Ctrl+G 会打开你配置的编辑器：
- 优先使用
$VISUAL环境变量指定的编辑器 - 如果
$VISUAL未设置，则使用$EDITOR - 编辑完成保存退出后，内容自动回填到 Codex 输入框
推荐配置
在 ~/.bashrc 或 ~/.zshrc 中设置：export VISUAL="code --wait" 即可在 VS Code 中编辑提示词。Vim
用户可设置 export VISUAL="vim"。
二、代码审查（/review）：四种模式详解
Codex 内置了专业的代码审查功能。在 TUI 中输入 /review 即可启动，Codex 会读取你选择的 diff，生成按优先级排序的、可操作的审查发现——不会修改你的工作树。
2.1 四种审查模式
| 模式 | 审查范围 | 典型使用场景 |
|---|---|---|
| Review against a base branch | 选择一个本地分支，Codex 找到 merge base 后 diff 你的工作 | 开 PR 前的最终审查：确保改动相对于 main/develop 是安全的 |
| Review uncommitted changes | 检查所有 staged、unstaged 和 untracked 文件 | 提交前的快速检查：发现遗漏的调试代码、拼写错误 |
| Review a commit | 列出最近的 commits，选择一个 SHA 审查其精确变更集 | 逐 commit 审查：验证同事或自己的特定提交 |
| Custom review instructions | 接受自定义审查指令（如 "Focus on accessibility regressions"） | 专项审查：安全审计、性能审查、无障碍合规等 |
审查关键特性：
- 审查结果按严重性排序，优先展示 Bug、风险和行为回归
- 每次审查作为独立的 turn 出现在 transcript 中，方便对比多次审查结果
- 默认使用当前会话模型；可在
config.toml中设置review_model单独指定审查模型 - 审查输出包含文件和行号引用，可直接定位问题
Bash
# 在 TUI 中
/review
# 审查后查看具体 diff
/diff三、Slash Commands 完整参考
Slash Commands 提供了键盘优先的快速控制能力。在输入框中输入 / 即可打开命令弹窗，开始输入命令名即可过滤。
3.1 会话控制类
| 命令 | 功能 | 说明 |
|---|---|---|
/clear | 清屏 + 开始新对话 | 重置终端视图和对话上下文。与 Ctrl+L（仅清屏）不同 |
/new | 开始新对话（不清屏） | 在同一 CLI 会话中切换任务，保留终端视图 |
/resume | 恢复已保存的会话 | 打开会话选择器，继续之前的工作 |
/fork | 克隆当前对话为新线程 | 保留原始 transcript，在新分支中探索替代方案 |
/compact | 压缩当前对话以释放 tokens | 长时间对话后使用，保留关键信息同时释放上下文空间 |
/copy | 复制最近一次完成的 Codex 输出 | 快速复制到剪贴板，运行中时复制最近完成的输出 |
/quit / /exit | 退出 CLI | 两者等效。退出前请确保已保存或提交重要工作 |
3.2 模型与配置类
| 命令 | 功能 | 说明 |
|---|---|---|
/model | 切换模型（和推理力度） | 无需重启即可在模型间切换，如 gpt-5.4、gpt-5.4-mini |
/fast | 切换 Fast 模式 | /fast on、/fast off、/fast status。GPT-5.4 专属 |
/personality | 切换沟通风格 | friendly（友善详细）、pragmatic（务实简洁）、none（无人格） |
/permissions | 切换审批/沙箱模式 | 运行时调整权限级别，无需重启 |
/plan | 进入规划模式 | 让 Codex 先提出执行计划再实施，可带内联提示词 |
/experimental | 切换实验性功能 | 如 Apps、Smart Approvals 等功能的开关 |
/status | 显示会话配置和 token 用量 | 确认当前模型、审批策略、可写路径、上下文容量 |
/statusline | 配置 TUI 底部状态栏 | 选择和排列状态栏项目：模型、上下文、Git 分支、token 等 |
/debug-config | 打印配置层级诊断 | 调试为什么实际生效的设置与 config.toml 不一致 |
3.3 工具与代码类
| 命令 | 功能 | 说明 |
|---|---|---|
/review | 代码审查 | 四种审查模式，详见上文第二节 |
/diff | 显示 Git diff | 包含 staged、unstaged 和 untracked 文件 |
/mention | 附加文件到对话 | 指定文件让 Codex 在后续轮次中直接引用 |
/init | 生成 AGENTS.md 脚手架 | 在当前目录生成项目指令文件的模板 |
/mcp | 列出 MCP 工具 | 查看当前会话可用的 MCP 服务器和工具 |
/apps | 浏览 App 连接器 | 选择后以 $app-slug 格式插入输入框 |
/agent | 切换子智能体线程 | 在多个子智能体之间检查和切换 |
/ps | 显示后台终端状态 | 查看长时间运行命令的最近输出（需 unified_exec） |
/sandbox-add-read-dir | 授予沙箱额外读取权限 | 仅 Windows 原生模式可用 |
/feedback | 发送反馈 | 提交日志和诊断信息给 Codex 维护者 |
/logout | 注销 | 清除本地认证凭据 |
四、命令行选项完整参考
4.1 核心全局选项
这些选项适用于 codex 基础命令，并传递给所有子命令：
| 选项 | 类型 | 说明 |
|---|---|---|
PROMPT | string | 可选的初始提示词。省略则启动 TUI 无预填消息 |
--image, -i | path[,path] | 附加一张或多张图片。逗号分隔或重复使用此标志 |
--model, -m | string | 覆盖配置中的模型，如 --model gpt-5.4 |
--profile, -p | string | 加载 config.toml 中定义的配置档案 |
--sandbox, -s | enum | read-only / workspace-write / danger-full-access |
--ask-for-approval, -a | enum | untrusted / on-request / never |
--full-auto | bool | 低风险自动化预设 = workspace-write • on-request |
--yolo | bool | 无沙箱、无审批（危险！仅在隔离环境中使用） |
--cd, -C | path | 设置工作目录，无需先 cd |
--add-dir （常用） | path | 授予额外目录写入权限。可重复使用 |
--search （常用） | bool | 启用实时 Web 搜索（live 模式） |
--oss | bool | 使用本地开源模型提供方（需 Ollama 运行中） |
--config, -c | key=value | 内联覆盖配置项。值按 JSON 解析，否则用字面字符串 |
--enable / --disable | feature | 强制启用/禁用 Feature Flag。可重复 |
--no-alt-screen | bool | 禁用 TUI 的备用屏幕模式 |
4.2 子命令概览
| 子命令 | 成熟度 | 说明 |
|---|---|---|
codex（无子命令） | Stable | 启动交互式 TUI |
codex exec（别名 codex e） | Stable | 非交互式执行，结果输出到 stdout。支持 --json 输出 JSONL 事件流 |
codex resume | Stable | 恢复之前的交互式会话 |
codex fork | Stable | Fork 之前的会话到新线程 |
codex apply（别名 codex a） | Stable | 将 Cloud 任务的最新 diff 应用到本地工作树 |
codex completion | Stable | 生成 Shell 补全脚本（bash/zsh/fish/PowerShell/elvish） |
codex features | Stable | 管理 Feature Flags：list / enable / disable |
codex login / logout | Stable | 认证管理：ChatGPT OAuth、设备授权、API Key |
codex cloud | Experimental | 浏览和执行 Cloud 任务。codex cloud exec 提交任务，codex cloud list 列出任务 |
codex mcp | Experimental | 管理 MCP 服务器：list / add / remove / login |
codex mcp-server | Experimental | 将 Codex 自身作为 MCP 服务器运行 |
codex sandbox | Experimental | 在 Codex 沙箱中运行任意命令（macOS Seatbelt / Linux Landlock） |
codex execpolicy | Experimental | 测试 Rules 文件对特定命令的匹配结果 |
codex app | Stable | 从终端启动 Codex Desktop（仅 macOS） |
codex app-server | Experimental | 启动 App Server 用于本地开发和调试 |
4.3 codex exec 专属选项
非交互式模式用于脚本化和 CI/CD 集成：
| 选项 | 类型 | 说明 |
|---|---|---|
PROMPT | string | 初始指令。使用 - 从 stdin 读取 |
--json | bool | 输出换行分隔的 JSON 事件流，而非格式化文本 |
--output-last-message, -o | path | 将助手最终消息写入文件，方便下游脚本使用 |
--output-schema | path | JSON Schema 文件，Codex 会验证输出是否符合该 schema |
--ephemeral | bool | 不持久化会话文件到磁盘 |
--skip-git-repo-check | bool | 允许在非 Git 仓库中运行 |
--color | enum | always / never / auto |
resume \[SESSION_ID\] | 子命令 | 恢复之前的 exec 会话。支持 --last、--all、追加提示词 |
五、Feature Flags 管理
Codex 内置了一组功能标志，用于控制实验性或可选功能。使用 features 子命令管理：
Bash
# 列出所有 Feature Flags 及其状态
codex features list
# 持久化启用某个功能（写入 config.toml）
codex features enable multi_agent
# 持久化禁用某个功能
codex features disable shell_snapshot
# 配合 --profile 使用，写入指定配置档案
codex --profile work features enable unified_exec也可以在启动时临时开关：
Bash
# 临时启用
codex --enable multi_agent "Spawn two agents to review code"
# 临时禁用
codex --disable shell_snapshot "Run this task"常用 Feature Flags：
| Flag | 成熟度 | 说明 |
|---|---|---|
multi_agent | Stable | 子智能体协作：支持 spawn_agent 等多代理并行工具 |
shell_snapshot | Stable | Shell 环境快照：加速重复命令执行 |
fast_mode | Stable | 简单任务走快速路径，提升响应速度 |
undo | Stable | 基于 git ghost snapshot 的逐轮撤销能力 |
shell_tool | Stable | 保持默认 Shell 命令执行能力 |
personality | Stable | 保持 /personality 命令可用 |
unified_exec | Stable | 统一 PTY exec（Windows 上默认禁用） |
enable_request_compression | Stable | zstd 压缩流式请求体 |
六、Codex Cloud 命令
codex cloud 让你无需离开终端即可委派和管理云端任务。
6.1 浏览云端任务
Bash
# 打开交互式任务选择器
codex cloud
# 列出最近任务（支持 JSON 输出）
codex cloud list --json
# 按环境筛选
codex cloud list --env ENV_ID --limit 10在交互式选择器中按 Ctrl+O 可以切换环境。
6.2 提交云端任务
Bash
# 直接提交任务
codex cloud exec --env ENV_ID "Summarize open bugs"
# Best-of-N 多次尝试（1-4 次）
codex cloud exec --env ENV_ID --attempts 3 "Fix the flaky test"--env是必需参数，指定 Cloud 环境 ID--attempts请求多次独立执行，取最佳结果- 认证使用 CLI 现有凭据
- 命令失败时返回非零退出码，方便脚本集成
6.3 应用云端结果
Bash
# 将 Cloud 任务的 diff 应用到本地仓库
codex apply TASK_ID如果 git apply 因冲突失败，命令返回非零退出码。
七、实战工作流：从审查到文档的完整循环
下面演示一个典型的日常开发工作流，覆盖代码审查 → 修 Bug → 重构 → 生成文档的完整链路。
1
Step 1：代码审查 — 发现问题
Bash
# 启动 Codex，进入 TUI
codex --cd ~/projects/my-api
# 审查当前分支相对于 main 的所有改动
/review
# → 选择 "Review against a base branch" → main
# Codex 输出按严重性排序的发现列表2
Step 2：修 Bug — 根据审查结果修复
Text
# 直接在 TUI 中向 Codex 下达指令
"Fix the SQL injection vulnerability in UserController.java
that the review identified at line 47. Use parameterized queries
and add a test case for the fix."Codex 会自动：读取相关文件 → 编辑代码 → 运行测试 → 报告结果。
3
Step 3：重构 — 改善代码质量
Text
"The review also noted duplicated pagination logic in
UserController and OrderController. Extract a shared
PaginationHelper class and refactor both controllers to use it.
Run all tests afterward."4
Step 4：生成文档 — 完善交付物
Text
"Generate Javadoc for the new PaginationHelper class and
update the API documentation in docs/api.md to reflect
the new pagination parameters."5
Step 5：最终确认
Bash
# 查看所有改动的 diff
/diff
# 再次审查确认没有遗漏
/review
# → 选择 "Review uncommitted changes"
# 确认无误后退出
/quit工作流提示
- 每一步都在同一个 TUI 会话中完成，Codex 保持完整的上下文
- 如果中途需要离开，
Ctrl+C退出后可用codex resume --last恢复 - 复杂任务可以用
/plan先让 Codex 提出方案，确认后再执行 - 使用
/compact在长会话中释放上下文空间 - 提交前务必运行
/diff和/review做最终确认
八、CLI 使用技巧速查
启动前的环境准备
在启动 Codex 前确保环境已就绪：激活 Python 虚拟环境、启动必要的服务、导出需要的环境变量。这样 Codex 不会浪费 token 去探测如何激活环境。
常用启动命令模板：
Bash
# 日常开发：Auto 模式 + 指定项目目录
codex --cd ~/projects/my-app
# 跨项目协调：前端 + 后端 + 共享库
codex --cd apps/frontend --add-dir ../backend --add-dir ../shared
# 快速修复：带初始提示词的非交互模式
codex exec --full-auto "Fix the CI failure in the latest commit"
# CI/CD 集成：只读分析 + JSON 输出
codex exec --sandbox read-only -a never --json "Analyze code quality"
# 图片驱动开发：截图转代码
codex -i design.png "Implement this UI component using React and Tailwind"
# 使用特定配置档案
codex --profile work --cd ~/work/project