---
title: "跑非互動任務"
description: "基於官方 non-interactive mode，講清 codex exec 適合什麼自動化任務、許可權怎麼給、輸出怎麼驗收。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

Non-interactive mode 的入口是 `codex exec`：給 Codex 一個明確任務，讓它在預設許可權裡跑完，並把結果交給指令碼、CI 或下游系統。

> [!WARNING]
> 非互動不是“無人值守萬能修復”。輸入、許可權、輸出和驗收都不清楚時，先用互動模式把任務收窄。

<Cards>
  <Card title="Non-interactive mode" href="https://developers.openai.com/codex/noninteractive">
    檢視 `codex exec` 的官方自動化說明。
  </Card>
  <Card title="CLI options" href="/zh-Hant/docs/codex/official/01-products/27-cli-args">
    需要指令碼化執行時，先確認 flags 和 `--config` 覆蓋方式。
  </Card>
  <Card title="Approvals and security" href="/zh-Hant/docs/codex/official/02-config-security/07-approval-security">
    自動化任務必須先確定 sandbox、approval 和 Git 邊界。
  </Card>
</Cards>

## 它適合什麼

```mermaid
flowchart LR
    Input["明確輸入"] --> Exec["codex exec"]
    Exec --> Policy["sandbox / approval"]
    Policy --> Run["一次性執行"]
    Run --> Output["stdout / JSONL / schema"]
    Output --> Downstream["CI / 指令碼 / PR"]
```

適合：

- CI 失敗後總結原因。
- 合併前審查 diff 風險。
- 定時生成 release notes。
- 把日誌、測試輸出、掃描結果轉成報告。
- 在固定許可權下執行一次小修復，並由指令碼消費結果。

不適合：

- 新手學習和長輪次溝通。
- 目標還沒有拆清楚的重構。
- 需要人即時判斷大量檔案改動的任務。
- 沒有 Git、沒有隔離環境、沒有許可權邊界的目錄。

新指令碼的預設起點應是隻讀總結。只有當總結穩定、驗證清楚、寫入範圍可控時，再開放寫許可權。

## 許可權怎麼給

官方文件把 `codex exec` 放在自動化場景裡使用。實際配置時按任務風險分層：

- 只讀審查：保持 read-only sandbox。
- 小範圍修復：使用 workspace-write，並在提示詞裡限制檔案範圍。
- 全自動 runner：只放在隔離 CI、容器或臨時工作區裡。
- 高危目錄：不要用 `danger-full-access` 直接跑主工作目錄。

提示詞要寫清三件事：

- 只允許做什麼。
- 明確不能做什麼。
- 完成後必須跑什麼驗證。

不要靠“請小心”控制風險。自動化依賴的是許可權和驗收，不是語氣。

## 輸出怎麼設計

預設輸出適合人讀：進度通常走 `stderr`，最終 agent message 走 `stdout`。這讓 shell 管道可以只消費最終結論。

需要程式消費全過程時，用 `--json`。官方說明 JSONL 事件會覆蓋 thread、turn、item、error 等執行過程，適合日誌留存、平臺整合和失敗診斷。

只需要最終結構化結果時，用 `--output-schema`。例如固定輸出：

- 專案名。
- 失敗原因。
- 風險等級。
- 受影響檔案。
- 建議動作。

結構化輸出比自然語言更適合 CI。指令碼應在欄位缺失、JSON 解析失敗或風險等級缺失時直接失敗。

## CI 認證邊界

CI 裡優先使用受保護的 secret 環境變數，不把 key、token 或認證檔案寫進儲存庫、日誌、artifact、issue comment。

`auth.json`、API key、access token 都按密碼處理。公開儲存庫和第三方 runner 裡不要複製本機登入態。需要企業級自動化時，先確認 runner、儲存庫許可權、日誌脫敏和 secret rotation，而不是先把本機配置搬過去。

## 穩妥自動修復流程

第一步，主 CI 失敗後觸發 follow-up job，不在主 CI 裡直接改程式碼。

第二步，checkout 失敗 commit，安裝依賴，復現失敗命令。

第三步，用 `codex exec` 跑窄任務，提示詞限制目標檔案、禁止重構、要求復跑同一測試。

第四步，測試不過就失敗並保留 Codex 輸出；測試透過才生成 patch、PR 或人工審查材料。

第五步，記錄輸入、輸出、diff、測試結果和執行許可權，方便追溯。

這個流程的重點不是“全自動”，而是每一步都有可檢查的失敗邊界。

## 常見坑

- 讓 Codex “修好專案”，沒有失敗命令和範圍。
- 一開始就給寫許可權或全許可權。
- CI 只看自然語言輸出，無法程式化判斷成功失敗。
- 自動修復後不復跑測試。
- 把本機認證檔案帶進 CI。
- 忽略 Git 儲存庫檢查或隨手跳過安全檢查。

## 驗收清單

- 只讀任務沒有檔案 diff。
- 寫入任務只改預期範圍。
- 結構化輸出能被下游解析。
- 失敗時 job 明確失敗，不靜默吞錯。
- 日誌裡沒有 key、token、私有路徑或完整認證檔案。
- 成功時留下任務輸入、最終輸出、diff 和測試結果。

## 官方資料

- [Non-interactive mode](https://developers.openai.com/codex/noninteractive)
- [Codex CLI options](https://developers.openai.com/codex/cli/options)
- [Agent approvals and security](https://developers.openai.com/codex/agent-approvals-security)
