Gemini CLI 无头模式（headless mode）通过 -p 标志或非 TTY 环境触发，返回结构化 JSON 或流式 JSONL 输出。JSON 模式包含 response 和 stats 字段，流式模式按事件类型（init/message/tool_use/tool_result/result）输出。退出码 0 成功、1 失败、42 输入错误、53 超过轮次限制。

无头模式技术参考

无头模式（Headless Mode）为 Gemini CLI 提供程序化接口，返回结构化文本或 JSON 输出，无需交互式终端界面。适合脚本调用、CI/CD 集成和自动化管道。

触发条件

无头模式在以下情况自动启用：

• 使用 -p（或 --prompt）标志提供查询
• 在非 TTY 环境中运行（如管道、CI/CD）

输出格式

用 --output-format 标志指定输出格式。

JSON 输出

返回单个 JSON 对象，包含完整响应和统计数据：

gemini -p "请总结一下 TypeScript 的优势" --output-format json

Schema：

字段	类型	说明
response	string	模型的最终回答
stats	object	Token 用量和 API 延迟指标
error	object（可选）	请求失败时的错误详情

流式 JSON 输出（JSONL）

返回按换行符分隔的 JSON 事件流（Newline-Delimited JSON），适合实时处理：

gemini -p "分析这段代码" --output-format stream-json

事件类型：

事件	说明
init	会话元数据（会话 ID、模型名称）
message	用户和助手的消息分块
tool_use	工具调用请求及参数
tool_result	工具执行结果
error	非致命警告和系统错误
result	最终结果（汇总统计、各模型 Token 用量分解）

退出码

退出码	含义
0	成功
1	通用错误或 API 失败
42	输入错误（无效 Prompt 或参数）
53	超过轮次限制

在 Shell 脚本中使用退出码做条件判断：

gemini -p "检查代码质量" --output-format json
if [ $? -eq 0 ]; then
  echo "成功"
elif [ $? -eq 1 ]; then
  echo "API 错误"
elif [ $? -eq 42 ]; then
  echo "输入错误"
fi

实用脚本示例

从文件读取 Prompt：

gemini -p "$(cat prompt.txt)" --output-format json | jq '.response'

CI/CD 代码审查：

git diff HEAD~1 | gemini -p "审查这个 diff，列出潜在问题" --output-format json

批量处理：

for file in src/*.ts; do
  gemini -p "@$file 为这个文件生成单元测试" --output-format json > "tests/$(basename $file).json"
done

进一步阅读

• 实际脚本示例：无头模式与自动化教程
• 所有可用标志：CLI 命令速查

常见问题

Q: 无头模式下 AI 还能执行文件修改等工具操作吗？

A: 可以。工具操作（读文件、写文件、Shell 命令等）在无头模式下同样有效。需要注意的是，工具调用需要用户审批的步骤在无头模式下会被跳过或自动批准，具体取决于配置。建议在自动化场景中配合沙箱使用。

Q: 流式 JSON 和普通 JSON 如何选择？

A: 如果任务执行时间较长（如复杂代码分析），用流式 JSONL 可以实时获取进度；如果只需最终结果，用普通 JSON 更简单。

Q: 退出码 53（轮次限制）如何处理？

A: 这意味着 AI 在达到最大轮次限制前未能完成任务。可以用 --turn-limit 标志增加允许的最大轮次，或将任务拆分为更小的子任务。