---
title: "使用命令行版 Codex"
description: "Codex CLI 是 OpenAI 的本地 coding agent，可以在终端里读取代码、修改代码、运行命令，并把结果交给你审查。"
verifiedAt: "2026-05-07"
---

> [!NOTE]
> **这一篇用 10 分钟换什么**：把 Codex CLI 从"一个命令"重新理解成**一套终端 agent 的入口**——交互式 TUI、`exec` 脚本化、`cloud` 委派、`mcp` 接入、`sandbox` 与 approval 双层边界。读完后你会知道哪种场景该用哪种启动姿势。

Codex CLI 是 OpenAI 的 coding agent（编程 Agent），可以从你的终端本地运行。它能在你选定的目录里读取代码、修改代码，并运行代码。

```mermaid
flowchart LR
    CLI["⚡ codex"]
    Local["💻 本地 TUI<br/>codex / codex resume / codex fork"]
    Exec["📜 脚本化<br/>codex exec"]
    Cloud["☁️ 云端<br/>codex cloud / apply"]
    Ext["🔌 扩展<br/>codex mcp / features / sandbox"]
    Sec{"🔐 安全双层"}
    SB["sandbox<br/>read-only / workspace-write / danger"]
    AP["approval<br/>on-request / never"]
    CLI --> Local
    CLI --> Exec
    CLI --> Cloud
    CLI --> Ext
    CLI --> Sec
    Sec --> SB
    Sec --> AP
```

Codex CLI 是开源项目：

https://github.com/openai/codex

它使用 Rust 构建，重点是速度和效率。

ChatGPT Plus、Pro、Business、Edu 和 Enterprise 套餐都包含 Codex。你可以在官方 pricing（价格）页面了解具体包含内容：

https://developers.openai.com/codex/pricing

官方页面还提供了一个 Codex CLI overview（Codex CLI 概览）视频：

```text
title     Codex CLI overview
videoId   iqNzfK4_meQ
```

## CLI 设置

Codex CLI 支持 macOS、Windows 和 Linux。

在 Windows 上，你可以在 PowerShell 中原生运行 Codex，并使用 Windows sandbox（Windows 沙箱）。如果你需要 Linux-native environment（原生 Linux 环境），可以使用 WSL2。

Windows 设置细节见官方 Windows setup guide：

https://developers.openai.com/codex/windows

如果你是 Codex 新手，建议阅读官方 best practices guide：

https://developers.openai.com/codex/learn/best-practices

## 什么时候选 CLI

优先选择 CLI 的场景：

- 你已经在 terminal 中工作，并希望 Codex 直接使用当前 repo。
- 任务需要跑本地测试、lint、build 或脚本。
- 你想用 `~/.codex/config.toml` 控制模型、sandbox、approval 和 MCP。
- 你要把 Codex 接入脚本、CI 或批处理。
- 你需要 `codex exec`、`codex mcp`、`codex resume`、`codex sandbox` 等命令。

不适合优先选 CLI 的场景：

- 你主要想要桌面多线程、worktree、review pane 和 GUI diff。
- 你希望在 GitHub 里直接委托 cloud task。
- 你不熟悉 terminal，也没有本地开发环境。

## 使用 Codex CLI 工作

### 交互式运行 Codex

运行 `codex`，启动一个 interactive terminal UI（交互式终端界面，也就是 TUI）会话。

官方对应页面：

https://developers.openai.com/codex/cli/features#running-in-interactive-mode

### 控制模型和推理

使用 `/model` 可以在 GPT-5.4、GPT-5.3-Codex 以及其他可用模型之间切换，也可以调整 reasoning levels（推理强度）。

官方对应页面：

https://developers.openai.com/codex/cli/features#models-reasoning

### 图片输入

你可以附加截图或设计稿，让 Codex 在阅读提示词的同时参考这些图片。

官方对应页面：

https://developers.openai.com/codex/cli/features#image-inputs

### 图片生成

你可以直接在 CLI 里生成或编辑图片。如果希望 Codex 基于已有素材迭代，也可以附加参考图。

官方对应页面：

https://developers.openai.com/codex/cli/features#image-generation

### 运行本地代码审查

在 commit 或 push 之前，可以让另一个 Codex agent（Codex Agent）审查你的代码。

官方对应页面：

https://developers.openai.com/codex/cli/features#running-local-code-review

### 使用 subagents

使用 subagents（子 Agent）可以并行处理复杂任务。

官方对应页面：

https://developers.openai.com/codex/subagents

### 网页搜索

你可以让 Codex 搜索网页，为当前任务获取最新信息。

官方对应页面：

https://developers.openai.com/codex/cli/features#web-search

### Codex Cloud 任务

你可以从终端发起 Codex Cloud 任务，选择 environments（环境），并在不离开终端的情况下应用任务产生的 diffs（差异改动）。

官方对应页面：

https://developers.openai.com/codex/cli/features#working-with-codex-cloud

### 把 Codex 脚本化

你可以用 `exec` command（`exec` 命令）把 Codex 脚本化，自动执行可重复的工作流。

官方对应页面：

https://developers.openai.com/codex/noninteractive

### Model Context Protocol（MCP）

通过 Model Context Protocol（MCP，模型上下文协议），你可以给 Codex 接入更多第三方工具和上下文。

官方对应页面：

https://developers.openai.com/codex/mcp

### 审批模式

在 Codex 编辑文件或运行命令之前，你可以选择适合自己风险承受程度的 approval mode（审批模式）。

官方对应页面：

https://developers.openai.com/codex/cli/features#approval-modes

## 常用命令地图

| 命令 | 用途 | 适合场景 |
| --- | --- | --- |
| `codex` | 启动 interactive TUI | 日常本地开发和探索 |
| `codex exec` / `codex e` | 非交互运行 Codex | CI、脚本、批处理、结构化输出 |
| `codex resume` | 继续旧会话 | 回到之前的上下文 |
| `codex fork` | fork 旧会话到新 thread | 保留历史，同时尝试另一条路线 |
| `codex apply` | 应用 Codex Cloud task 的 diff | 从云端任务回到本地工作树 |
| `codex cloud` | 在终端管理 cloud tasks | 不打开 Web UI 的 cloud workflow |
| `codex login` / `logout` | 登录或移除凭据 | 初始化和账号切换 |
| `codex mcp` | 管理 MCP servers | 接入外部工具和上下文 |
| `codex features` | 管理 feature flags | 开关稳定或实验能力 |
| `codex sandbox` | 用 Codex sandbox 运行命令 | 调试 sandbox 行为 |
| `codex app` | 从终端启动 Codex Desktop | CLI 和桌面 app 联动 |
| `codex app-server` | 启动 app server | 远程 TUI 或富客户端调试 |

官方 command reference 会标注 Stable、Experimental 等 maturity。新手优先使用 Stable 命令；Experimental 命令要按调试或内部集成看待，不要当成长期 API 承诺。

## 推荐启动参数

低风险本地开发：

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

只读分析：

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

非交互任务：

```bash
codex exec --sandbox workspace-write --ask-for-approval never "Run lint and summarize failures"
```

需要 live web search：

```bash
codex --search
```

不要在普通工作目录里使用：

```bash
codex --dangerously-bypass-approvals-and-sandbox
```

这个模式会绕过 approvals 和 sandbox，只适合外部已经隔离好的 runner、VM 或 disposable container。

## CLI 工作流范式

### 解释项目

```text
Tell me about this project. Focus on architecture, entry points, build commands, and the safest first change.
```

适合新接手代码库。先让 Codex 读结构和脚本，不要直接改代码。

### 小范围修 bug

```text
Reproduce the failing test, identify the smallest responsible code path, fix only that bug, and run the narrowest relevant test.
```

关键是要求 reproduce、localize、minimal fix、prove。

### 本地 code review

```text
Review my unstaged changes for bugs, missing tests, and risky behavior. Do not edit files. Return findings with file paths and evidence.
```

先只读 review，再决定是否让 Codex 修改。

### 脚本化执行

```bash
codex exec --json --output-last-message /tmp/codex-summary.md "Audit this package and report only actionable failures"
```

`--json` 适合下游程序消费事件，`--output-last-message` 适合保留最终摘要。

## 安全边界

CLI 的核心安全配置来自两层：

- `sandbox`：Codex 技术上能访问和修改什么。
- `approval`：Codex 什么时候必须暂停请求许可。

常见组合：

| 组合 | 用途 |
| --- | --- |
| `read-only` + `on-request` | 只读调研、review、方案 |
| `workspace-write` + `on-request` | 日常本地开发 |
| `workspace-write` + `never` | 受控自动化 |
| `danger-full-access` + `never` | 外部隔离环境内的高权限自动化 |

需要额外目录写权限时，优先用 `--add-dir`，不要直接切到 full access。

## 新手完成标准

第一次使用 CLI，建议完成这套闭环：

1. `codex login status` 确认登录。
2. 在 Git repo root 运行 `codex`。
3. 用只读 prompt 让 Codex 解释项目。
4. 用小任务让 Codex 修改一处低风险文件。
5. 让 Codex 跑最小验证命令。
6. 用 `git diff` 审查改动。
7. 只在确认后提交。

## 官方资料

- [Codex CLI](https://developers.openai.com/codex/cli)
- [Command line options](https://developers.openai.com/codex/cli/reference)
- [Config basics](https://developers.openai.com/codex/config-basic)
- [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security)
- [Codex best practices](https://developers.openai.com/codex/learn/best-practices)

## 接下来去哪

<Cards>
  <Card title="CLI 命令参数" href="/docs/codex/official/01-products/27-cli-args" description="逐项理解 codex 全部 flag" />
  <Card title="CLI 功能详解" href="/docs/codex/official/01-products/26-cli-features" description="按功能维度深入" />
  <Card title="CLI Slash 命令" href="/docs/codex/official/01-products/25-cli-slash" description="TUI 内可用的 / 命令" />
  <Card title="非交互模式" href="/docs/codex/official/01-products/28-non-interactive" description="codex exec 脚本化与 CI 用法" />
  <Card title="Cloud 运行时" href="/docs/codex/official/05-cloud-remote/18-cloud-runtime" description="把任务委派给云端环境" />
  <Card title="基础配置" href="/docs/codex/official/02-config-security/06-basic-config" description="config.toml 是 CLI 行为的家" />
  <Card title="批准与安全模式" href="/docs/codex/official/02-config-security/07-approval-security" description="日常应该选哪个组合" />
</Cards>
