---
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="/docs/gemini-cli/official/07-integrations-automation/73-automation" />
  <Card title="GitHub Action" description="要接 GitHub workflow 时，继续看 GitHub Action 边界。" href="/docs/gemini-cli/official/07-integrations-automation/74-github-action" />
  <Card title="Policy engine" description="非交互式环境里，ask_user 通常不能成立，要用 policy 预先控制。" href="/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)
