---
title: "CLI 引數怎麼用"
description: "把 Codex CLI 引數按任務入口、許可權控制和自動化場景拆開，避免把會隨版本變化的命令清單寫死。"
verifiedAt: "2026-05-06"
---

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

Codex CLI 的引數不要按“完整列表”學習。更實用的方式是先判斷你要啟動哪類任務，再決定使用哪些引數覆蓋預設配置。

官方 CLI 會繼續演進，完整命令和 flag 以 `codex --help`、子命令 `--help` 和官方 CLI Features 為準。本頁只保留穩定用法和風險邊界。

> [!TIP]
> 記住一個原則：長期預設值寫進 `config.toml`，專案規則寫進 `.codex/`，本次臨時變化才用 CLI 引數。

<Cards>
  <Card title="CLI Features" href="https://developers.openai.com/codex/cli/features">
    檢視 Codex CLI 的 TUI、slash commands、remote app server、MCP、exec 等官方能力說明。
  </Card>
  <Card title="Configuration Reference" href="https://developers.openai.com/codex/config-reference">
    檢視引數背後的配置 key、型別、預設值和可用範圍。
  </Card>
  <Card title="Agent Security" href="https://developers.openai.com/codex/agent-approvals-security">
    理解 approval、sandbox、network access 和 agent 執行邊界。
  </Card>
</Cards>

## CLI 引數的三類用途

```mermaid
flowchart TB
    Start["codex 命令"] --> Entry["選擇任務入口"]
    Start --> Boundary["設定執行邊界"]
    Start --> Override["覆蓋本次配置"]

    Entry --> TUI["interactive TUI"]
    Entry --> Exec["codex exec"]
    Entry --> Cloud["cloud / apply / resume"]

    Boundary --> Sandbox["sandbox"]
    Boundary --> Approval["approval"]
    Boundary --> Workspace["working directory / extra dirs"]

    Override --> Model["model / profile"]
    Override --> Feature["feature flags"]
    Override --> Config["-c key=value"]
```

讀引數時先問：

- 我是在開啟互動式 TUI，還是跑一次自動化任務。
- 這次是否允許改檔案、聯網、執行命令。
- 這次變化應該臨時生效，還是應該寫進配置檔案。

如果這三個問題沒想清楚，引數越多越容易誤用。

## 最常用入口

開啟互動式 TUI：

```bash
codex
```

帶一個初始任務進入 TUI：

```bash
codex "检查这个 PR 的风险点"
```

在指定目錄啟動：

```bash
codex --cd /path/to/repo
```

非互動執行一次任務：

```bash
codex exec "运行测试并总结失败原因"
```

把 stdin 作為任務輸入：

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

這些入口的差別不是“命令長短”，而是互動模型不同：TUI 適合邊看邊改，`exec` 適合指令碼化、CI、批處理。

## 許可權引數優先看 sandbox 和 approval

Codex 會讀檔案、改檔案、呼叫工具。啟動前最重要的是許可權邊界。

常見組合：

```bash
codex --sandbox read-only --ask-for-approval on-request
codex --sandbox workspace-write --ask-for-approval on-request
codex exec --sandbox workspace-write --ask-for-approval never "运行只读审计"
```

使用建議：

- 只想讓它分析專案，用 `read-only`。
- 允許它改當前 workspace，用 `workspace-write`。
- 需要訪問 workspace 外目錄時，明確傳入額外目錄，而不是放開全部許可權。
- 自動化執行如果使用 `never`，必須確保外層 runner 已經隔離。
- 不要把危險組合寫成團隊預設值。

> [!WARNING]
> `--dangerously-bypass-approvals-and-sandbox` / `--yolo` 只適合外部已經隔離、可回復、低價值環境。它不是“更省事”的日常模式。

## 臨時配置用 `-c`

`-c` / `--config` 用於覆蓋本次 invocation 的配置。它適合臨時實驗，不適合替代正式配置。

```bash
codex -c model_reasoning_effort='"high"'
codex -c sandbox_mode='"read-only"'
codex -c 'features.codex_hooks=true'
```

注意：

- 值按 TOML 解析；字串通常要加引號。
- Nested key 可以用點號。
- 同一個引數可以重複傳入。
- 如果某個覆蓋值每次都要寫，應回到 `config.toml` 或 profile。

這也是排查配置問題的好方法：先用 `-c` 驗證單次行為，再決定是否固化。

## Profile 適合常用工作模式

如果你經常切換模式，不要每次手寫一長串引數。用 profile。

```toml
[profiles.review]
sandbox_mode = "read-only"
approval_policy = "on-request"

[profiles.implementation]
sandbox_mode = "workspace-write"
approval_policy = "on-request"
```

啟動：

```bash
codex --profile review
codex --profile implementation
```

Profile 最適合表達“我現在要進入哪種工作狀態”。它比臨時 flag 更穩定，也比複製命令更少出錯。

## `exec` 用於自動化，不等於放棄審查

`codex exec` 常用於批處理、指令碼和 CI 風格任務。

```bash
codex exec "检查 docs 中有没有失效链接"
```

適合場景：

- 對一批檔案做一致性檢查。
- 在 CI 或指令碼里生成結構化結果。
- 從 stdin 讀取長 prompt。
- 讓 Codex 完成一次明確、可驗證的任務。

不適合場景：

- 需求還在討論。
- 需要頻繁人工決策。
- 需要對生產環境做不可逆操作。
- 任務邊界不清楚但許可權很大。

自動化入口更要明確 sandbox、approval、工作目錄和輸出格式。

## Remote 和 app-server 要先處理認證邊界

Codex CLI 支援把 TUI 連線到 remote app-server。這類能力適合本地開發、遠端工作區和特殊整合，但預設不應暴露給不受信任網路。

使用時重點檢查：

- endpoint 是否只在可信網路可達。
- token 是否透過安全渠道傳遞。
- `ws://` 是否僅用於 localhost 或受控環境。
- app-server 是否有清晰的啟動和關閉方式。

如果不確定認證和網路邊界，不要為了方便直接暴露 remote endpoint。

## MCP 和外掛類命令先看用途

Codex CLI 也包含 MCP、features、completion、cloud、apply、resume 等命令。學習順序建議：

1. 先掌握 `codex` 和 `codex exec`。
2. 再掌握 sandbox、approval、profile、`-c`。
3. 然後配置 MCP servers。
4. 最後處理 cloud、remote、app-server、plugin marketplace 這類擴充套件能力。

這樣學不會被命令數量帶偏。CLI 的核心價值始終是：在正確邊界內把 Codex 接入真實工程任務。

## 日常命令模板

只讀審計：

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

普通本地實現：

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

單次高推理任務：

```bash
codex -c model_reasoning_effort='"high"' "审查这次重构的风险"
```

指令碼化檢查：

```bash
codex exec --sandbox read-only --ask-for-approval never "列出 docs 中需要人工复核的页面"
```

這些模板不要原樣當成永久標準。最終應該根據你的專案風險、團隊規範和執行環境沉澱成 profiles。

## 不建議寫死的內容

教程和團隊文件裡不建議長期寫死這些清單：

- 完整 CLI flag 表。
- 完整子命令表。
- 模型列表和價格。
- 實驗 feature flag 列表。
- remote / app-server 的內部協議細節。

它們更新頻率高，寫死後很快變成誤導。更穩的寫法是說明“怎麼查、怎麼選、怎麼控制風險”。

## 團隊文件怎麼寫

團隊內部寫 Codex CLI 教程時，不要把頁面變成命令速查表。命令速查表會隨版本變化，很快失效；更穩定的寫法是把“入口選擇、許可權邊界、驗證動作、回復方式”寫清楚。新人真正需要知道的是：什麼時候進入 TUI，什麼時候用 `exec`，什麼時候必須只讀，什麼時候要停下來讓負責人確認。

商業專案裡還要把 CLI 引數和團隊預設 profile 對齊。文件可以給出推薦模式，但最終應落到 `config.toml`、專案規則和 CI 檢查裡。這樣每個人啟動 Codex 時看到的是一致邊界，而不是從聊天記錄裡複製一串臨時引數。
