06 - 非互動模式：codex exec
← 05-AGENTS-md與config-toml | 00-Index | 下一篇 → 07-MCP與擴充
基本用法
codex exec "把 tools/validate.py 的錯誤訊息改成繁體中文"
codex e "同上" # e 是 exec 的別名非互動模式讓你從腳本執行 Codex，不開互動 TUI——CI job、批次處理、被別的 agent 呼叫時用。
這是 Codex 的「headless 模式」，對應 Claude Code 的 claude -p。
核心旗標
| 旗標 | 作用 |
|---|---|
--json | 串流 JSONL 事件到 stdout（每行一個 JSON） |
-o, --output-last-message <FILE> | 把最後一則 agent 訊息以純文字寫進檔案 |
--skip-git-repo-check | 跳過「必須在 git repo 裡」的守衛 |
--full-auto | 不問核准 + 強制 workspace-write sandbox |
--profile <name> | 用 config.toml 裡的某個 profile |
-o 的行為值得知道
-o不管有沒有--json都會把最後一則 agent 訊息以文字捕捉起來。輸出會同時出現在 stdout 和那個檔案。
也就是說 -o 是「額外寫一份」，不是「改寫去哪」。
codex exec -o /tmp/result.txt "分析這個 repo 的測試覆蓋率"
cat /tmp/result.txt💡 這解決了 Herdr 讀不到長輸出 的問題——與其從終端畫面撈，不如讓它寫檔然後讀檔。
JSONL 串流
codex exec --json "審查目前的 diff" > events.jsonl每行一個 JSON 事件，適合：
- CI 裡解析執行過程
- 做進度條 / 監看 UI
- 事後分析它做了什麼
搭配 jq 過濾：
codex exec --json "..." | jq -r 'select(.type == "message") | .content'⚠️ 實際的事件 schema 依版本而異，先跑一次看看實際輸出長什麼樣再寫解析邏輯。
codex exec resume
codex exec 也支援續接之前的 session：
codex exec resume "接著把剩下的檔案也處理掉"用途：把一個大任務拆成好幾個 codex exec 呼叫，但保留脈絡。
CI 整合範例
# .github/workflows/codex-review.yml（示意）
- name: Codex review
run: |
codex exec --json --profile ci \
-o /tmp/review.md \
"審查這次 PR 的 diff，只回報可執行的問題" \
> /tmp/events.jsonl
cat /tmp/review.md >> "$GITHUB_STEP_SUMMARY"CI 的正確設定：
| 設定 | 值 | 理由 |
|---|---|---|
approval_policy | untrusted（或至少 never） | 無人值守，不能停下來等人 |
sandbox_mode | workspace-write | 讓它能改，但寫不出 repo |
network_access | 依需要 | 不需要就關 |
📌 官方對 CI 的建議是
untrusted是無人值守 CI 與正式環境的正確預設——只有可信指令能直接跑，其他的直接失敗並把結果回給模型。
給你的實用腳本
1. 批次格式稽核（vault）
#!/usr/bin/env bash
# audit-vault.sh — 用唯讀 profile 掃描筆記格式問題
set -euo pipefail
for dir in "Nephrology(NEP)" "Cardiology(CV)" "Endocrinology(ENDO)"; do
echo "=== $dir ==="
codex exec --profile audit \
-o "/tmp/audit-${dir}.md" \
"掃描 '$dir' 底下所有 *_overview.md：
1. YAML frontmatter 是否合法
2. 是否有 modified 欄位
3. 是否有用  這種會讓 Quartz 破圖的寫法（應該用 ![[檔名]]）
只回報問題，格式為表格。**你在 read-only sandbox 裡，本來就改不了檔案。**"
done
cat /tmp/audit-*.md設計重點：--profile audit 是 read-only + never——作業系統層級保證它改不到你的筆記，比在 prompt 裡寫「不要改」可靠得多。
2. 詳解量產（刷題網站）
#!/usr/bin/env bash
# draft-explanations.sh <任務檔>
set -euo pipefail
task="${1:?需要任務檔}"
out="tmp_drafts/out/$(basename "$task" .task.md).json"
codex exec --profile worker \
-o "/tmp/$(basename "$task" .task.md).log" \
"$(cat "$task")"
# 驗收：看檔案，不看 agent 說什麼
test -f "$out" || { echo "❌ 沒產出 $out"; exit 1; }
jq empty "$out" || { echo "❌ JSON 不合法"; exit 1; }
echo "✅ $(jq 'length' "$out") 題"驗收看檔案不看狀態，這跟 Herdr 08 的鐵律一致。
codex exec vs claude -p 對照
claude -p | codex exec | |
|---|---|---|
| 別名 | — | codex e |
| JSON 輸出 | --output-format json | --json（JSONL） |
| Schema 保證 | --json-schema | ⚠️ 無等價功能 |
| 存最終回覆 | 自己導向 | -o <file> |
| 續接 | --continue / --resume | codex exec resume |
| 花費上限 | --max-budget-usd | ⚠️ 無等價功能 |
| 輪數上限 | --max-turns | ⚠️ 無等價功能 |
| 極簡啟動 | --bare | — |
| 權限 | --permission-mode | --full-auto / --profile |
🔑 兩個明顯的差異值得記住：
- Claude Code 有
--json-schema保證輸出格式，Codex 沒有 → Codex 的輸出契約要靠 prompt 約定和事後驗證。- Claude Code 有
--max-budget-usd，Codex 沒有 → Codex 跑失控時沒有內建的花費煞車，要靠你自己控制範圍和批次大小。
🔗 相關筆記
- 05-AGENTS-md與config-toml — 上一步：profile 定義在哪
- 07-MCP與擴充 — 下一步
- 08-實戰-被Claude指揮的雙手 — 這些腳本在編排裡的位置
- Claude Code CLI 11 — 對照組
最後更新：2026-08-04