---
title: "掌握 CLI 功能"
description: "按交互、自动化、远程连接、审查和扩展五类能力理解 Codex CLI，而不是背完整命令清单。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

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

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

> [!TIP]
> 不要把 CLI 当成“聊天命令”。它的价值在于把 Codex 放进终端工作流：脚本、CI、SSH、批处理和可重复验证。

<Cards>
  <Card title="CLI Features" href="https://developers.openai.com/codex/cli/features">
    查看交互模式、resume、remote TUI、review、web search 等官方说明。
  </Card>
  <Card title="Command Line Options" href="/docs/codex/official/01-products/27-cli-args">
    学习 sandbox、approval、profile 和一次性配置覆盖。
  </Card>
  <Card title="Non-interactive mode" href="/docs/codex/official/01-products/28-non-interactive">
    用 `codex exec` 把 Codex 接入脚本或 CI。
  </Card>
</Cards>

## CLI 能力地图

```mermaid
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

最基础入口：

```bash
codex
```

带初始任务：

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

适合场景：

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

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

## Resume：复用上下文

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

```bash
codex resume
codex resume --last
```

适合场景：

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

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

## Exec：非交互和自动化

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

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

从 stdin 读取任务：

```bash
cat prompt.md | codex exec -
```

适合场景：

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

不适合场景：

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

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

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

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

典型结构：

```mermaid
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 使用建议

日常本地开发：

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

只读审查：

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

脚本化只读任务：

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

临时配置覆盖：

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

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

## 不要写死的内容

CLI 教程里不建议写死：

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

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