Gemini CLI（仓库 google-gemini/gemini-cli，TypeScript，Apache-2.0）提供 headless 非交互模式，适合接到 CI 和脚本里。npm 发布走 preview、latest、nightly 三条通道：nightly 每天更新，latest 每周二 UTC 20:00 更新。
无头模式与输出格式
headless 的核心是 -p 参数：一次性传入 prompt，执行完退出。默认的纯文本输出是给人读的；CI 里做结构化处理要加 --output-format json，拿到结果后用 jq 继续加工。任务耗时长、要看过程状态时用 --output-format stream-json，这是按行输出的 JSON 事件流。
认证与权限
认证先分清三种来源：
- Google OAuth 个人账号：60 次/分，1000 次/天，1M 上下文，走 Gemini 3。
- Gemini API Key：1000 次/天，flash/pro 混合。
- Vertex AI：企业配额。
无头模式不要走交互式 OAuth 授权；设 GEMINI_API_KEY 环境变量即可。走组织 Code Assist 授权时还要设 GOOGLE_CLOUD_PROJECT，否则会被限流。
权限是无头接入最容易踩的坑。shell 工具默认有确认门槛，交互模式靠人点确认；无头模式下没有这个环节，要么放行 trusted 目录，要么约束 agent 只在仓库内活动。--include-directories 默认只喂当前目录，要跨目录分析必须显式加这个参数，否则目录外的文件 agent 看不到。
GEMINI.md
仓库根目录的 GEMINI.md 每次启动都会自动读进上下文，适合承载一套无头审查规则：团队约定、检查点、禁止事项。GEMINI.md 分两层：全局 ~/.gemini/GEMINI.md 和项目级文件。CI 流水线应该读项目级规则，不要让个人全局配置影响审查结果。
MCP 联动
MCP server 配置在 ~/.gemini/settings.json，prompt 里用 @服务名 引用。接上之后，agent 不再只是读代码，能操作外部系统——典型场景是查完 bug 直接开 PR。
边界
- 无头模式烧 token。一个多步任务会循环几十轮，JSON 输出叠上长上下文，账单涨得明显。CI 频繁触发前先算配额，别拿 1000 次/天的额度去填 commit 钩子。
- 别让 agent 在不信任的目录里跑代码。默认安全模型假设目录内可信；runner 挂了敏感路径就加沙箱，或把 workdir 限定到仓库内。
- nightly 有回归风险，生产环境锁
latest或固定版本。 - 默认绑定 Gemini 模型，不能切换 Claude/GPT。项目必须模型无关时，这套接入方式不适用。