掌握 CLI 功能

Codex CLI 是終端裡的 coding agent 入口。它不僅能開啟互動式 TUI，也能恢復會話、執行非互動任務、連線遠端 app-server、處理圖片輸入、呼叫 web search、做本地 review，並和 Cloud、MCP、subagents 配合。

CLI 功能更新較快，完整命令以官方 CLI features、codex --help 和子命令 --help 為準。本頁按使用場景講怎麼選。

CLI 能力地圖

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

最基礎入口：

codex

帶初始任務：

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

適合場景：

• 你希望即時看 Codex 的計劃和 diff。
• 任務需要多輪反饋。
• 需要邊讀檔案、邊調整方向。
• 你正在本地 repo 中開發。

互動式 TUI 的關鍵不是命令複雜，而是你能在每一輪審查它的計劃、工具呼叫和輸出。

Resume：複用上下文

Codex 會儲存本地會話記錄。中斷後可以恢復：

codex resume
codex resume --last

適合場景：

• 上一個任務還沒完成。
• 你希望保留之前的計劃、反饋和驗證結果。
• 需要在同一個 repo 狀態下繼續討論。

恢復會話前仍要檢查工作樹。舊上下文可能已經過期，尤其當其他人或其他 agent 也在改同一個儲存庫時。

Exec：非互動和自動化

codex exec 適合一次性、邊界明確、可驗證的任務：

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

從 stdin 讀取任務：

cat prompt.md | codex exec -

適合場景：

• CI 風格檢查。
• 批次文件審計。
• 生成結構化報告。
• 在指令碼里呼叫 Codex。

不適合場景：

• 需求還不清楚。
• 需要大量人工選擇。
• 任務可能觸碰高風險資源。

非互動任務更要明確 sandbox、approval、工作目錄和輸出要求。

Remote TUI：遠端執行，本地操作

Remote TUI 適合程式碼、依賴或憑據在遠端機器上，但你想用本地終端操作 Codex 的場景。

典型結構：

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 使用建議

日常本地開發：

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

只讀審查：

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

指令碼化只讀任務：

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

臨時配置覆蓋：

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

如果某個命令每次都要寫，應該沉澱進 profile、config.toml、skill 或指令碼，而不是長期複製貼上。

不要寫死的內容

CLI 教程裡不建議寫死：

• 完整快捷鍵列表。
• 完整 slash command 列表。
• 實驗 feature flag 名稱。
• 當前推薦模型名。
• 圖片生成用量倍率。
• 遠端協議內部細節。

這些以官方文件和當前 CLI help 為準。教程應該教會你如何選擇入口、控制許可權、組織任務和驗證結果。