CLI 引數怎麼用

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

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

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

CLI Features

檢視 Codex CLI 的 TUI、slash commands、remote app server、MCP、exec 等官方能力說明。

Configuration Reference

檢視引數背後的配置 key、型別、預設值和可用範圍。

Agent Security

理解 approval、sandbox、network access 和 agent 執行邊界。

CLI 引數的三類用途

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：

codex

帶一個初始任務進入 TUI：

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

在指定目錄啟動：

codex --cd /path/to/repo

非互動執行一次任務：

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

把 stdin 作為任務輸入：

cat prompt.md | codex exec -

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

許可權引數優先看 sandbox 和 approval

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

常見組合：

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 已經隔離。
不要把危險組合寫成團隊預設值。

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

臨時配置用 `-c`

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

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。

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

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

啟動：

codex --profile review
codex --profile implementation

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

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

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

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 等命令。學習順序建議：

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

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

日常命令模板

只讀審計：

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

普通本地實現：

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

單次高推理任務：

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

指令碼化檢查：

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 時看到的是一致邊界，而不是從聊天記錄裡複製一串臨時引數。

CLI 引數怎麼用

CLI Features

Configuration Reference

Agent Security

本頁目錄