非互動自動化：codex exec

到目前為止，你跟 Codex 都是「面對面」聊天：你打字、它回話、跑到一半要不要動手還會停下來問你。這一章要教你另一種完全不同的用法——不開對話視窗、把任務寫成一張紙條塞給它、它自己跑完吐結果。

這正是把 Codex 變成「自動化工人」的關鍵一招。

10.0 一句話 + 一個比喻

codex exec 是 Codex CLI 的「非互動模式」——你給它一句指令，它不開聊天視窗、不等你按鍵，自己跑完、把結果印到畫面上就退出。

打個比方：

• 平常的 codex（互動模式）像是把同事叫到你旁邊，你一句他一句，過程中他還會回頭問你「這個檔可以改嗎?」。
• codex exec 像是寫一張工作紙條，塞進一台會自己動的機器，按下開始，它就照紙條一路做到底，做完把成果丟出來給你，中間不打擾你。

為什麼需要這種模式?因為很多場景根本沒有「你」坐在電腦前面：

• 半夜兩點，伺服器自動跑你排程的整理任務。
• GitHub 上有人開了 Pull Request（程式碼修改提案），系統自動叫 Codex 幫忙審查。
• 你寫一個腳本，把網路抓來的資料丟給 Codex 整理成表格，再存檔。

這些都沒有人在旁邊按 [Y/n]。這就是 codex exec 的舞台。

本章只談終端裡的 codex exec。GitHub Actions、雲端委派那些「接到生產線」的玩法，屬於第 11 章，我們這章專心把「一台機器自己跑」這件事學透。

10.1 codex exec 概念與退出碼

它到底做了什麼

官方對 exec 的定義是這樣寫的（逐字）：

"Automate workflows or wire Codex into your existing scripts with the exec subcommand. This runs Codex non-interactively, piping the final plan and results back to stdout."

翻成白話：用 exec 子命令把 Codex 接進你現有的腳本，它會非互動地跑，並把最終計畫與結果送回 stdout（標準輸出，也就是終端機畫面）。

把這句話拆成三個你必須記住的特性：

第一次跑跑看

最簡單的形式就是 codex exec 後面接一句你的需求：

🍎 Mac / 🐧 Linux：

codex exec "summarize the repository structure and list top 5 risky areas"

🪟 Windows（PowerShell）：

codex exec "summarize the repository structure and list top 5 risky areas"

它會分析你目前所在的這個專案，把「結構摘要 + 最該注意的 5 個風險區」直接印出來，然後退出。全程不會問你任何問題。

退出碼：腳本怎麼知道它成功還失敗

每個終端指令跑完，都會留下一個叫退出碼（exit code）的數字。0 代表成功，非 0 代表出事了。這是所有 shell 腳本判斷上一步成敗的依據。

codex exec 在這方面有兩條官方明講的行為：

• CLI 功能頁逐字：exec「the command exits non-zero if submission fails so you can wire it into scripts or CI.」——提交失敗就以非零退出，讓你可以接進腳本或 CI。
• 非互動頁逐字：如果某個「必要的」MCP server（外掛工具，詳見第 9 章）啟動失敗，codex exec「exits with an error instead of continuing.」——直接以錯誤退出，不會硬著頭皮繼續跑。

你可以這樣親眼看退出碼：

🍎 Mac / 🐧 Linux：

codex exec "do something"
echo $?

🪟 Windows（PowerShell）：

codex exec "do something"
echo $LASTEXITCODE

$?（Mac/Linux）或 $LASTEXITCODE（PowerShell）會印出剛才那個指令的退出碼。

別只信退出碼：雙重判斷

正因為退出碼不是萬無一失的單一真相，CI 實務上的建議是「退出碼 + 產出檔案」雙重判斷：不只看它有沒有非零退出，還要看「它該產出的東西（例如一份報告、一個修補檔）到底有沒有真的生出來、是不是空的」。

這個「看 artifact（產出物）在不在」的思路，在第 11 章的自動修復範例會再用到——官方那個範例就是用「修補檔是不是非空」來判斷成功，而不是只看退出碼。

10.2 結構化輸出（--json / --output-schema / -o）

預設情況下，codex exec 吐給你的是人看的自由文字。但如果你要用程式去接它的輸出（例如自動把結果存進資料庫、貼到 PR 留言、產生報表），自由文字就很難穩定解析。

這時候你需要「結構化輸出」。Codex 提供三個旗標，目的各不相同，先看一張對照表：

下面一個一個拆。

--json：看它每一步在做什麼

--json 會讓 stdout 變成逐行的 JSON 事件（這種「一行一個 JSON」的格式叫 JSONL，JSON Lines）。每完成一個動作，就吐一行事件出來。

官方列出的事件型別（逐字）有：

• Thread / Turn 事件：thread.started、turn.started、turn.completed、turn.failed
• Item 事件：item.*（泛指，含 item.started、item.completed）
• 錯誤事件：error

item.* 涵蓋的內容包括：agent 訊息、推理、指令執行、檔案修改、MCP 工具呼叫、網路搜尋、計畫更新等。

官方給的一個事件範例長這樣（逐字）：

{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122,"reasoning_output_tokens":0}}

你可以看到它連 token 用量都報給你了。配上 jq（一個處理 JSON 的小工具）就能漂亮地解析：

🍎 Mac / 🐧 Linux：

codex exec --json "summarize repo structure" | jq

🪟 Windows（PowerShell）：

codex exec --json "summarize repo structure" | jq

--output-schema：強迫最終結果照你的格式來

--output-schema <檔案路徑> 指向一個 JSON Schema 檔（描述「我要的結果該有哪些欄位、各是什麼型別」）。Codex 會讓最終訊息乖乖符合這個格式。

這在「我要穩定欄位的報表」場景超好用——例如每次都要產出 {專案名稱, 用到的語言} 這種固定結構，比解析一坨自由文字可靠太多。

官方的 schema 範例（逐字）：

{
  "type": "object",
  "properties": {
    "project_name": { "type": "string" },
    "programming_languages": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["project_name", "programming_languages"]
}

{
  "type": "object",
  "properties": {
    "project_name": { "type": "string" },
    "programming_languages": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["project_name", "programming_languages"],
  "additionalProperties": false
}

-o：把結果順手存成一個檔

-o（全名 --output-last-message）把 assistant 的最終訊息寫到指定檔案——而且它同時還是會印到 stdout，不是二選一。

三招最常一起用：讓結果符合 schema、又存成檔給後續步驟讀。

🍎 Mac / 🐧 Linux：

codex exec "Extract metadata" --output-schema ./schema.json -o ./output.json

🪟 Windows（PowerShell）：

codex exec "Extract metadata" --output-schema .\schema.json -o .\output.json

10.3 stdin、pipe、codex exec resume 串接

這一節教你把 codex exec 接進「資料流水線」，以及怎麼讓兩次執行接續同一段記憶。

stdin 只讀一份完整 prompt：先把資料組好

codex exec 沒有「引號放指示、管道再自動附上資料」的雙輸入模式。先記住兩條互斥規則：

1. 如果引號裡已有位置引數（prompt），stdin 內容會被忽略；這時不要把日誌或其他資料接在管道前面。
2. 如果要讓外部文字成為 prompt 的一部分，就用單獨的 -，並先把「指示 + 已處理資料」組成同一份輸入。

含日誌範例：先遮罩，再把指示和資料一起送

日誌常藏著 token、密碼、cookie、Email、內網網址或使用者資料。先複製成 app.redacted.log，把這些值以固定文字取代後再重新打開檢查；不確定能不能提供時，改用測試日誌。不要把原始日誌、密鑰或個資直接送進 prompt，也不要把遮罩後的檔案提交到公開儲存庫。

🍎 Mac / 🐧 Linux：

# app.redacted.log 必須已先遮罩；這次只做唯讀分析
{
  printf '%s\n\n' '以下是已遮罩的應用程式日誌。只分析可能原因與下一步；不要執行指令、修改檔案或連線。'
  tail -n 200 app.redacted.log
} | codex exec --sandbox read-only - > log-triage.md

🪟 Windows（PowerShell）：

# app.redacted.log 必須已先遮罩；這次只做唯讀分析
$prompt = @'
以下是已遮罩的應用程式日誌。只分析可能原因與下一步；不要執行指令、修改檔案或連線。
'@
$prompt += "`n`n" + ((Get-Content .\app.redacted.log -Tail 200) -join "`n")
$prompt | codex exec --sandbox read-only - > log-triage.md

--sandbox read-only 限制的是 Codex 的可寫範圍；最後的 > log-triage.md 是終端機把回覆存成報告。請先確認該檔名不存在，避免覆寫你原本的分析結果。

# context.txt 會被忽略：不要用這種寫法傳資料
cat context.txt | codex exec "do X"

從檔案讀取一份完整 prompt

當 prompt 很長、想存在一個檔案裡（例如 prompt.txt），用 - 告訴 Codex：「整句指令請從 stdin 讀」。官方逐字：「Use codex exec - when you want to force that behavior explicitly.」檔案一樣只能放可安全提供的內容。

🍎 Mac / 🐧 Linux：

codex exec - < prompt.txt
cat prompt.txt | codex exec -
generate_prompt.sh | codex exec --json - > result.jsonl

🪟 Windows（PowerShell）：

Get-Content prompt.txt | codex exec -

codex exec "do the task" < /dev/null

夾帶圖片：-i 跟 prompt 的先後順序，跟你在互動模式學的相反

第 4 章教過互動模式怎麼用 -i / --image 附圖，codex exec 一樣吃這個旗標——但有一個容易讓人跌一跤的地方：旗標跟 prompt 的先後順序，跟你剛練熟的互動模式手感是反的。

互動模式你已經習慣寫成「旗標在前、prompt 在後」：

# 互動模式：-i 在前；圖片必須已做資料分級與遮罩
codex -i sanitized-bug.png "這張截圖哪裡有問題？只提出排查建議。"

但 codex exec 的位置引數解析邏輯，吃的是「prompt 先、-i 後」：

# exec 模式：prompt 先、-i 後；圖片必須已做資料分級與遮罩
codex exec "這張截圖哪裡有問題？只提出排查建議。" -i sanitized-bug.png

多張圖片一樣支援逗號分隔或重複旗標（跟互動模式語法相同）。哪些終端機貼不了原始影像、貼圖失敗時該怎麼排除，複習第 4 章即可，這裡不重複。

--ephemeral：不持久化 session rollout

平常 codex exec 跑完會把這段對話存成 session rollout 檔（歷程紀錄，放在 ~/.codex/sessions/，詳見第 7 章）。如果這次是「一次性、不需要後續 resume」的 CI 任務，加 --ephemeral 讓它不持久化 session rollout：

codex exec --ephemeral "triage this repository and suggest next steps"

codex exec resume：讓第二次接著第一次

codex exec resume 讓你沿用前一輪的 transcript（對話歷程）、計畫、核准設定繼續跑下一句指令。最經典的用法是「兩段式自動化」：第一段先讓它分析，第二段再叫它動手實作，而且它記得第一段的脈絡。

官方確認的兩種形式（逐字）：

codex exec resume --last "now implement the fix you proposed"
codex exec resume <SESSION_ID> "continue with the next step"

• --last：接續最近一次的對話。
• <SESSION_ID>：指定某一個 session 的 ID 來接續。

10.4 環境變數認證與 non-TTY 防呆

最後一節處理兩個自動化必踩的雷：怎麼在沒有人登入的環境給它鑰匙，以及怎麼讓它別卡在「等你按 Y」。

CODEX_API_KEY：exec 專屬的鑰匙

在 CI 或排程環境裡，沒有人能坐下來跑 codex login 點按鈕。這時由 CI 的 secret 機制把 CODEX_API_KEY 注入單一、受信任的步驟；命令列本身不寫 API key，也不顯示它的值。注入完成後，該步驟只需要執行一般指令：

# CODEX_API_KEY 由 CI secret 在這一個步驟注入；不要在命令列填入值
codex exec --json "triage open bug reports"

在自己的電腦第一次使用時，請先走第 2 章的登入流程；不要為了省一步，把 API key 貼到終端機、腳本或聊天訊息裡。

這裡有一個非常重要、容易記錯的限制——官方逐字：

"CODEX_API_KEY is only supported in codex exec"

也就是說：CODEX_API_KEY 這個環境變數只有 codex exec 認得，你在互動模式 codex 裡設它是沒用的。

non-TTY 防呆：別讓它卡在 [Y/n]

這是自動化最常見的地雷，務必看懂。

互動模式下，Codex 動手前可能會跳出「要不要執行這個指令?[Y/n]」讓你確認。但在 CI / 排程 / agent 這類「non-TTY」環境（non-TTY = 沒有真正的互動終端，沒有人能回應 [Y/n]）裡，這個 prompt 沒有人會去按——結果就是任務卡死，或者更糟，某些工具會在 stdin 結束時直接採預設值（等於沒確認就硬跑）。

防呆不是只有一條路。你要先選擇：這個 job 是越界就失敗（fail-closed），還是允許 Auto-review 審查符合資格的越界。兩者都不依賴人工 [Y/n]，但安全語意完全不同。

codex -a never exec --sandbox workspace-write "run the cleanup task"

• -a never（--ask-for-approval never）：從頭到尾不產生 approval request；沙箱內照跑，仍需核准的越界直接失敗，也不會啟動 Auto-review。適合封閉、可預測的 fail-closed CI。
• --sandbox：同時界定它「能動到哪」（三值 read-only / workspace-write / danger-full-access，雙軸權限心法詳見第 6 章）。

若 job 確實需要讓獨立 reviewer 判斷 eligible escalation，則保留 on-request，再設定 approvals_reviewer="auto_review"。本站把這條路封裝成安全 launcher；完整 interactive／exec 配方與權限邊界見第 7 章 7.6。

兩個旗標的可選值速查：

看到這裡，你可能會想：「乾脆用 --yolo 把核准跟沙箱都關掉，不是更省事？」——先踩煞車。--dangerously-bypass-approvals-and-sandbox（別名 --yolo）拆的不只是核准暫停，連檔案圍欄和網路圍欄一起拆，官方原話是只在外部已加固的環境內使用。codex exec 自動化真正要解決的是「不要卡在等你按鍵」，不是「乾脆什麼都別擋」——上面 -a never + --sandbox workspace-write 的組合已經解決了卡住的問題，同時還留著沙箱圍欄保護你。--yolo 這條紅線的完整風險，第 6 章已經講透，這裡只提醒一句：能用 -a never + --sandbox 解決的自動化，就不要跳去 --yolo。

非 git 目錄要加 --skip-git-repo-check

codex exec 預設會檢查你是不是在一個 Git 儲存庫裡（這是安全機制，提醒你「改檔前最好有版本控制當安全網」）。如果你故意要在一個非 git 的資料夾跑（例如純粹整理一批檔案），這個檢查會擋你，這時加上：

codex exec --skip-git-repo-check "organize these notes into folders"

10.5 🎓 高手進階

前面四節你已經會把 codex exec 接進腳本。這一節是寫給要把它放進正式 CI、跨夜排程、團隊流水線的人——新手可以先跳過，等你真的要「無人值守、出事還能查」時再回來。

進階入口一：幾個你之前沒見過、但 CI 很需要的旗標

把前面零散提到的補齊成一張速查，全是官方逐字佐證的：

進階入口二：--json 事件流的 schema 與 jq 解析鐵律

10.2 節教過 --json 會吐逐行 JSON 事件（JSONL）。要在 CI 裡穩穩解析，先分清楚兩層：

頂層事件型別（官方逐字列舉，可信）：thread.started、turn.started、turn.completed、turn.failed、item.*、error。

每個 item.* 裡面包一個 item 物件，有三個相位：item.started →（item.updated）→ item.completed，每個 item 都帶 item.id 和 item.type。官方逐字列出的 item.type 種類有：agent 訊息、推理、指令執行、檔案修改、MCP 工具呼叫、網路搜尋、計畫更新等。

⚠️ 關鍵分界：型別名是官方的（可信），但 item 物件「裡面有哪些欄位」官方只公開了型別名加兩個範例，完整欄位細節目前最齊的來源是第三方 cheatsheet。 下表的欄位名請當「參考、待實機驗」，別寫死：

幾個立刻能用的 jq 配方（jq 是處理 JSON 的小工具，第 9 章提過）：

🍎 Mac / 🐧 Linux：

# 1) 不靠 -o，直接從事件流撈「最終訊息」
codex exec --json "summarize repo risks" \
  | jq -r 'select(.type=="item.completed" and .item.type=="agent_message") | .item.text'

# 2) 撈 token 用量(成本監控)
codex exec --json "do task" \
  | jq -c 'select(.type=="turn.completed") | .usage'

# 3) 撈它實際跑過的每一條命令(稽核)
codex exec --json "..." \
  | jq -c 'select(.type=="item.completed" and .item.type=="command_execution")
           | {cmd:.item.command, exit:.item.exit_code, status:.item.status}'

🪟 Windows（PowerShell）：

codex exec --json "summarize repo risks" | jq -r 'select(.type==\"item.completed\" and .item.type==\"agent_message\") | .item.text'

進階入口三：CI 別只信退出碼——三重判斷

10.1 節說過「退出碼是粗閘，別只信它」。高手在 CI 裡用三重判斷才算數，任一條不過就當失敗：

1. 退出碼：$? 非零 → 失敗（官方確認：提交失敗會非零、必要 MCP 啟動失敗會以錯誤退出、git apply 衝突也會非零）。
2. 失敗事件：--json 串流裡出現 turn.failed 或 error 事件 → 失敗（比退出碼更細，有時退出碼是 0 但中途其實出過事）。
3. 產出物非空：它「該生出來的東西」（修補檔 / schema 輸出檔）真的存在、而且非空，才算成功。

第二條的 jq 寫法：

🍎 Mac / 🐧 Linux：

out=$(codex exec --json "...")
echo "$out" | jq -e 'select(.type=="turn.failed" or .type=="error")' >/dev/null \
  && { echo "Codex reported a failure event"; exit 1; }

進階入口四：--output-schema + MCP 同開的「靜默降級」陷阱 ⚠️

這是高手級 CI 才會踩到、但一踩就很難 debug 的雷，務必記住。

• 觸發條件：你同時 --json 搭 --output-schema（要求最終訊息照固定 schema），而且這次跑有掛 MCP server / tools。
• 症狀：--output-schema 那層嚴格格式被靜默丟棄，最終訊息退回成沒結構的自由文字——可能缺最外層 {}、屬性間漏逗號、key 沒加引號，甚至整段被 markdown code block 包起來。你的下游解析會莫名其妙爆掉，卻找不到錯在哪。

三條規避鐵律：

1. 拆兩段：需要嚴格 schema 輸出的步驟，盡量別同時掛 MCP / tools。把「需要 MCP 的分析」和「結構化輸出」拆開——前段用 MCP 分析、後段 resume 接續但只跑「無工具的彙整」來產 schema 輸出。
2. jq empty 驗合法性：拿到 -o 或 schema 輸出檔後，一定機械驗一次：

   🍎 Mac / 🐧 Linux：

   複製

   jq empty ./output.json && echo "OK: valid JSON" || { echo "FAIL: not valid JSON"; exit 1; }

   jq empty 會把檔讀一遍但不輸出，只要 JSON 不合法就非零退出。FAIL 就 retry 或報錯，別盲信。
3. 鎖版本：Codex 數天一版、事件 schema 沒凍結。CI 裡把 Codex 版本釘死（例如本機 cron 用 npm i -g @openai/codex@<版本> 釘版），避免哪天 schema 漂移就把你的 parser 整個打爛。

本章小結

這一章你學會了把 Codex 從「對話夥伴」變成「自動化工人」：

• codex exec 非互動跑、結果走 stdout、用退出碼判斷成敗（但別只信退出碼，搭配「產出物在不在」雙重判斷）。
• 結構化輸出三招：--json（看過程的事件流）、--output-schema（固定最終欄位）、-o（順手存檔）。
• 串接：先把指示與已遮罩資料組成一份完整 prompt，再用管道和 - 從 stdin 讀入；也能用 codex exec resume 接續記憶（但 --ephemeral 不能 resume）。
• 自動化防呆：CODEX_API_KEY 僅由 CI secret 在受信任的單一步驟注入（僅 exec 認得，命令列不寫值）；封閉 CI 用 --ask-for-approval never 讓越界 fail-closed，需要自動審查 eligible escalation 則用 on-request + auto_review；非 git 目錄才考慮 --skip-git-repo-check。
• 高手進階：CI 別只信退出碼，疊上「失敗事件 + 產出物非空」三重判斷；--json 事件「型別名信官方、欄位先採樣、未知略過、鎖版本」；--output-schema + MCP 同開有靜默降級陷阱，拿到輸出一定 jq empty 驗。

下一章我們會繼續把 exec 接到更大的場景；而 GitHub Actions 自動審 PR、cron / launchd 跨夜排程那一整套生產線流程，留到第 14 章專章講透。

動手試試

1. 跑 codex exec "summarize the repository structure"，看它印什麼；再跑一次 echo $?（PowerShell 用 echo $LASTEXITCODE）看退出碼。
2. 跑 codex exec --json "list the top 3 files in this repo" | jq，觀察 JSONL 事件流，找找看有沒有 turn.completed 那一行的 token 用量。
3. 把一句不含密鑰、個資或原始日誌的長指令存進 prompt.txt，用 codex exec - < prompt.txt 餵進去，體會「整段 prompt 從檔案來」的感覺。
4. （進階）跑 codex exec --json "list files" | jq -c 'select(.type=="turn.failed" or .type=="error")'，正常情況應該沒有任何輸出——這就是 CI 用「失敗事件」當第二道閘門的偵測寫法。