---
title: "Headless mode"
description: "Gemini CLI headless mode：用 -p/--prompt、非 TTY、JSON/JSONL 輸出和退出碼把 CLI 接入指令碼。"
verifiedAt: "2026-05-09"
---

Headless mode 是 Gemini CLI 的程式化入口。它不會開啟互動式終端 UI，而是執行一次任務並把結果輸出到標準輸出。

> [!IMPORTANT]
> Headless 指令碼必須處理退出碼、stderr、空輸出和 JSON 解析失敗。不要只把 stdout 當成成功結果。

## 觸發方式

兩種常見觸發方式：

```bash
gemini -p "Explain this error"
gemini --prompt "Write a commit message"
```

或在非 TTY 環境中執行，例如管道、重定向、CI。

如果沒有 `-p` 且沒有 pipe / redirect，Gemini CLI 會進入互動 UI。自動化指令碼應顯式使用 `-p` 或 `--prompt`，避免 CI 因為等待互動輸入卡住。

官方還支援 `--prompt-interactive` 這類混合入口，但生產指令碼不要依賴互動追問。能一次性給出輸入、上下文、輸出格式和失敗策略，指令碼才可復現。

## 輸出格式

預設輸出普通文本。需要給指令碼消費時，使用結構化輸出：

```bash
gemini --output-format json -p "Summarize @package.json"
```

JSON 模式通常包含：

- `response`：最終回答。
- `stats`：token 與延遲統計。
- `error`：失敗時的錯誤資訊。

Streaming JSON 輸出適合長期任務或即時消費事件，事件可能包括初始化、訊息片段、工具呼叫、工具結果、錯誤和最終結果。

指令碼消費 JSON 時，要用真正的 JSON parser，不要用 `grep` 或字串切分。模型輸出和錯誤欄位都可能包含換行、引號和程式碼塊。

## 退出碼

```text
0   成功
1   通用错误或 API 失败
42  输入错误
53  turn limit exceeded
```

指令碼里不要只讀 stdout。必須同時處理退出碼和 stderr；`response` 為空但退出碼為 0、或者模型返回了不可解析結構，都要算失敗分支。

## 什麼時候用

- CI 裡自動總結 diff。
- 批次處理日誌。
- 為內部工具包一層 AI wrapper。
- 生成結構化 JSON 後交給 `jq` 或後續指令碼。

| 自動化場景 | 推薦輸出 | 驗證點 |
| --- | --- | --- |
| PR 摘要 | text 或 json | diff 範圍和空 diff |
| 批次日誌分析 | json | 每條輸入的失敗記錄 |
| 生成檔案 | json + 臨時檔案 | schema 校驗後替換 |
| 統計模型消耗 | json | stats 是否存在 |
| CI gate | json | 退出碼和 policy 行為 |

## 生產指令碼注意

- prompt 要固定，不要依賴互動追問。
- 輸入先限流和過濾，避免把大檔案、金鑰、二進位制檔案塞進上下文。
- 需要 JSON 時使用 `--output-format json`，再用 `jq` 或語言內 JSON parser 校驗。
- 對 429、網路錯誤、turn limit exceeded 做重試或失敗記錄。
- 批次任務寫入檔案時先寫臨時檔案，校驗後再替換正式檔案。

## 驗收方式

用成功樣例、無效輸入、超長輸入、API 失敗四種情況跑指令碼。確認退出碼、JSON 解析、空輸出處理和日誌記錄都符合預期，再接入 CI。

指令碼里建議把失敗分成三類記錄：輸入不合法、模型或網路失敗、輸出不符合 schema。三類失敗的重試策略不同，不要統一寫成“再跑一次”。

CI 中還要設定超時。

失敗日誌要可追溯。
方便複查。

還要記錄輸入摘要和模型資訊。否則同一個 headless 指令碼在配額、fallback 或模型選擇變化後，失敗很難復現。

## 上線前檢查

上線前至少跑三種輸入：正常輸入、空輸入、超長輸入。再模擬一次非零退出和一次 JSON 解析失敗。指令碼能穩定處理這五類情況，才適合放進 CI 或定時任務。

失敗分支要寫入日誌，且保留輸入摘要、任務編號和退出碼。

## 接下來去哪

<Cards>
  <Card title="自動化指令碼" description="繼續看批次任務、臨時檔案、重試和產物校驗。" href="/zh-Hant/docs/gemini-cli/official/07-integrations-automation/73-automation" />
  <Card title="GitHub Action" description="要接 GitHub workflow 時，繼續看 GitHub Action 邊界。" href="/zh-Hant/docs/gemini-cli/official/07-integrations-automation/74-github-action" />
  <Card title="Policy engine" description="非互動式環境裡，ask_user 通常不能成立，要用 policy 預先控制。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/61-policy-engine" />
</Cards>

## 官方來源

- [Gemini CLI headless mode](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/headless.md)
- [Gemini CLI automation tutorial](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/automation.md)
