掌握 CLI 功能

Codex CLI 是终端里的 coding agent 入口。它不仅能打开交互式 TUI，也能恢复会话、运行非交互任务、连接远程 app-server、处理图片输入、调用 web search、做本地 review，并和 Cloud、MCP、subagents 配合。

CLI 功能更新较快，完整命令以官方 CLI features、codex --help 和子命令 --help 为准。本页按使用场景讲怎么选。

CLI 能力地图

flowchart TB
    CLI["Codex CLI"]
    Interactive["交互式 TUI<br/>边看边改"]
    Automation["非交互执行<br/>脚本和 CI"]
    Remote["远程连接<br/>app-server / TUI"]
    Review["本地审查<br/>diff / commit / branch"]
    Extensions["扩展能力<br/>MCP / subagents / images / search"]

    CLI --> Interactive
    CLI --> Automation
    CLI --> Remote
    CLI --> Review
    CLI --> Extensions

先判断你要哪类能力：

• 想边看计划边迭代，用交互式 TUI。
• 想跑一次明确任务，用 codex exec。
• 想继续旧上下文，用 resume。
• 想远程控制一台有代码和凭据的机器，用 remote TUI。
• 想提交前审查 diff，用本地 review。
• 想接外部系统，用 MCP 或 Cloud 集成。

交互式 TUI

最基础入口：

codex

带初始任务：

codex "检查这个仓库的测试入口"

适合场景：

• 你希望实时看 Codex 的计划和 diff。
• 任务需要多轮反馈。
• 需要边读文件、边调整方向。
• 你正在本地 repo 中开发。

交互式 TUI 的关键不是命令复杂，而是你能在每一轮审查它的计划、工具调用和输出。

Resume：复用上下文

Codex 会保存本地会话记录。中断后可以恢复：

codex resume
codex resume --last

适合场景：

• 上一个任务还没完成。
• 你希望保留之前的计划、反馈和验证结果。
• 需要在同一个 repo 状态下继续讨论。

恢复会话前仍要检查工作树。旧上下文可能已经过期，尤其当其他人或其他 agent 也在改同一个仓库时。

Exec：非交互和自动化

codex exec 适合一次性、边界明确、可验证的任务：

codex exec "检查 docs 中的 MDX 格式问题"

从 stdin 读取任务：

cat prompt.md | codex exec -

适合场景：

• CI 风格检查。
• 批量文档审计。
• 生成结构化报告。
• 在脚本里调用 Codex。

不适合场景：

• 需求还不清楚。
• 需要大量人工选择。
• 任务可能触碰高风险资源。

非交互任务更要明确 sandbox、approval、工作目录和输出要求。

Remote TUI：远程运行，本地操作

Remote TUI 适合代码、依赖或凭据在远端机器上，但你想用本地终端操作 Codex 的场景。

典型结构：

flowchart LR
    Local["本地终端<br/>Codex TUI"] --> Remote["远端 app-server<br/>拥有 workspace"]
    Remote --> Repo["代码、命令、工具链"]

使用前要先处理安全：

• 优先用 localhost 或 SSH tunnel。
• 非本地连接必须配置认证。
• 跨网络连接应放在 TLS 后面。
• token 文件按凭据处理，泄露后立即轮换。

Remote TUI 不只是“换个端口连接”。它把执行权放在另一台机器上，安全边界必须更清楚。

本地 review

CLI 支持在本地对 diff 做 review。适合 commit 或 PR 前先跑一轮高信号检查。

常见用法：

• review 当前未提交改动。
• review 某个 commit。
• 对比 base branch。
• 用自定义说明聚焦安全、性能、可访问性或回归风险。

review 的目标不是替代人类 reviewer，而是提前发现明显风险，让人工审查更聚焦。

Web search、图片、MCP 和 subagents

这些能力都属于“增强上下文和工具”的扩展层。

Web search：

• 适合查最新官方文档、版本、外部事实。
• 搜索结果仍是不可信外部内容，不能直接当指令执行。

Image input：

• 适合截图报错、UI 设计稿、架构图。
• 需要同时给文字说明，避免只靠视觉猜测。

MCP：

• 适合连接 repo 外的系统，例如 issue、日志、文档、数据库只读查询。
• 不要一开始接入所有工具，只接能减少真实手动循环的工具。

Subagents：

• 适合用户明确要求并行或角色拆分的任务。
• 会增加用量和协调成本，不适合默认开启。

CLI 使用建议

日常本地开发：

codex --sandbox workspace-write --ask-for-approval on-request

只读审查：

codex --sandbox read-only --ask-for-approval on-request

脚本化只读任务：

codex exec --sandbox read-only --ask-for-approval never "列出文档风险"

临时配置覆盖：

codex -c model_reasoning_effort='"high"' "审查这次改动"

如果某个命令每次都要写，应该沉淀进 profile、config.toml、skill 或脚本，而不是长期复制粘贴。

不要写死的内容

CLI 教程里不建议写死：

• 完整快捷键列表。
• 完整 slash command 列表。
• 实验 feature flag 名称。
• 当前推荐模型名。
• 图片生成用量倍率。
• 远程协议内部细节。

这些以官方文档和当前 CLI help 为准。教程应该教会你如何选择入口、控制权限、组织任务和验证结果。