---
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="/zh-Hant/docs/codex/official/01-products/27-cli-args">
    學習 sandbox、approval、profile 和一次性配置覆蓋。
  </Card>
  <Card title="Non-interactive mode" href="/zh-Hant/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 為準。教程應該教會你如何選擇入口、控制許可權、組織任務和驗證結果。
