---
title: "06 - 非互動模式：codex exec"
type: note
specialty: Programming
tags: [codex-cli從0開始使用教學, 06-exec, automation, ci]
created: 2026-08-04
updated: "2026"
modified: 2026-08-04
---

# 06 - 非互動模式：codex exec

← [[05-AGENTS-md與config-toml]] | [[00-Index]] | 下一篇 → [[07-MCP與擴充]]

---

## 基本用法

```bash
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` 是「額外寫一份」，不是「改寫去哪」。

```bash
codex exec -o /tmp/result.txt "分析這個 repo 的測試覆蓋率"
cat /tmp/result.txt
```

> 💡 **這解決了 [[Programming/Herdr/Herdr從0開始使用教學/06-CLI與自動化基礎|Herdr 讀不到長輸出]] 的問題**——與其從終端畫面撈，不如讓它寫檔然後讀檔。

---

## JSONL 串流

```bash
codex exec --json "審查目前的 diff" > events.jsonl
```

每行一個 JSON 事件，適合：
- CI 裡解析執行過程
- 做進度條 / 監看 UI
- 事後分析它做了什麼

搭配 `jq` 過濾：

```bash
codex exec --json "..." | jq -r 'select(.type == "message") | .content'
```

> ⚠️ 實際的事件 schema 依版本而異，**先跑一次看看實際輸出長什麼樣**再寫解析邏輯。

---

## `codex exec resume`

`codex exec` 也支援續接之前的 session：

```bash
codex exec resume "接著把剩下的檔案也處理掉"
```

**用途**：把一個大任務拆成好幾個 `codex exec` 呼叫，但保留脈絡。

---

## CI 整合範例

```yaml
# .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）

```bash
#!/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. 是否有用 ![](assets/...) 這種會讓 Quartz 破圖的寫法（應該用 ![[檔名]]）
     只回報問題，格式為表格。**你在 read-only sandbox 裡，本來就改不了檔案。**"
done

cat /tmp/audit-*.md
```

**設計重點**：`--profile audit` 是 `read-only` + `never`——**作業系統層級保證它改不到你的筆記**，比在 prompt 裡寫「不要改」可靠得多。

### 2. 詳解量產（刷題網站）

```bash
#!/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") 題"
```

**驗收看檔案不看狀態**，這跟 [[Programming/Herdr/Herdr從0開始使用教學/08-Claude當大腦-Codex當雙手|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` |

> 🔑 **兩個明顯的差異值得記住**：
> 1. **Claude Code 有 `--json-schema` 保證輸出格式**，Codex 沒有 → **Codex 的輸出契約要靠 prompt 約定和事後驗證**。
> 2. **Claude Code 有 `--max-budget-usd`**，Codex 沒有 → **Codex 跑失控時沒有內建的花費煞車**，要靠你自己控制範圍和批次大小。

---

## 🔗 相關筆記

- [[05-AGENTS-md與config-toml]] — 上一步：profile 定義在哪
- [[07-MCP與擴充]] — 下一步
- [[08-實戰-被Claude指揮的雙手]] — 這些腳本在編排裡的位置
- [[Programming/Claude-Code/Claude-Code-CLI從0開始使用教學/11-非互動模式與腳本化|Claude Code CLI 11]] — 對照組

---

*最後更新：2026-08-04*