Gemini API CLI 如何接入编码代理？

核心结论

Gemini API CLI（命令名为 gemini-api）把 Gemini API 的文本生成、媒体生成、文件分析和托管 Agent 调用，统一成可从 shell 执行的无状态命令。它不是一个新的交互式编码代理，而是让已有的 Codex、Claude Code、Cursor 或 CI 脚本多一个可以调用的外部工具。开发者真正需要调整的不是“换一个终端助手”，而是把它当作一个有明确输入、输出和退出码的子进程：固定 CLI 版本，把密钥放在运行环境，复杂请求先用 --dry-run 检查，跨步骤时显式保存 interaction ID 或文件 URI。

这个变化有一个容易被忽略的边界：CLI 在 2026 年 10 月 27 日以 beta 形式出现在 Gemini API 文档中，官方文档明确说它随着 Interactions API 演进，次版本之间可能发生破坏性变更。GitHub 的 v0.4.5 release 页面标注发布于 2026 年 10 月 30 日；但在 2026 年 10 月 31 日核对时，releases/latest 仍跳转到 v0.4.4。因此，不能把 v0.4.5 不加说明地称为当前稳定最新版。自动化 Agent 和 CI 应由团队选定并验证 release tag，再把它固定下来，而不是无条件跟随 latest。

它解决的不是 SDK 缺失

如果目标是在 Python、TypeScript、Java、Go 或 C# 服务中长期集成 Gemini，应该继续使用 Google GenAI SDK。CLI 的价值在于减少“为了让编码代理临时调用一个模型能力而增加项目依赖”的成本：代理只需要能够启动 shell 子进程，就可以调用 generate、analyze、image、tts、music、video、transcribe，也可以运行或管理 Gemini 托管 Agent。官方文档把 CLI、SDK 和 Gemini 文档 MCP 分成三种工具：CLI 负责从 shell 调 API，SDK 负责应用内集成，文档 MCP 负责给编码代理提供当前的 SDK 规则。

这一区分会直接影响目录和权限设计。一个构建脚本需要生成占位图、读取 PDF 里的待办事项，或者把录音转成字幕时，CLI 可以作为外部工具；一个 Web 服务需要复用客户端、处理请求生命周期、做鉴权和错误重试时，应该把逻辑留在 SDK 或服务层。不要因为 CLI 能发请求，就把它当作后端 API 客户端的替代品。它的设计重点是无状态和可组合，而不是在进程内维护一个完整的业务会话。

CLI 的“无状态”也不是说服务端永远没有状态。每次命令默认独立运行，不会自动替调用方保存本地上下文。若下一步要继续上一轮交互，调用方需要传 --previous-interaction-id；若要继续使用本地文件，需要把上传后得到的 files/<id> URI 传给后续命令；若启动后台托管 Agent，则要保存返回的 interaction ID，再用 agent status 查询。这个边界让 shell 行为容易预测，也把状态所有权交还给脚本或上层 Agent。

一套可复制的安装和验证流程

macOS 或 Linux 可以用官方安装脚本把二进制放到 PATH：

curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash

Windows PowerShell 的安装方式是：

iwr -useb https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.ps1 | iex

如果这是 CI、Docker 镜像或团队共享的 Agent 环境，不要直接把未固定的安装命令作为唯一供应链策略。官方 CLI 文档支持通过 GEMINI_VERSION 指定 release tag，也支持从 GitHub Releases 下载预构建压缩包。可以把版本固定在环境变量或镜像构建参数中：

export GEMINI_VERSION="${GEMINI_VERSION:?请先设置团队审核过的 release tag}"
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash

认证优先通过环境变量注入：

export GEMINI_API_KEY="${GEMINI_API_KEY:?请从密钥管理系统注入}"
gemini-api whoami
gemini-api generate "用一句话确认 CLI 配置" --dry-run

--dry-run 的重要性不在于它能证明 API Key 有效，而在于它能在不发起网络请求的情况下验证命令参数，并对请求预览中的凭据做脱敏。官方文档还说明，CLI 可以把密钥保存到 macOS Keychain、Linux Secret Service 或 Windows Credential Manager；在 CI 中不要把密钥写入仓库、Dockerfile、日志或构建产物。对一次性的自动化任务，环境变量由外部 secret store 注入通常更容易审计；对本地开发，系统密钥环可以减少 shell 历史记录暴露的机会。

如果要确认脚本实际使用的版本和能力，可以先运行：

gemini-api --version
gemini-api --help
gemini-api --usage
gemini-api generate --schema > generate-schema.json

--usage 用于查看命令树，--schema 用于查看 --body 请求的 JSON Schema。这种“先询问二进制自身接口，再生成参数”的流程比让编码代理凭记忆猜 flag 更可靠，尤其适合 CLI 仍处于 beta、接口可能变化的阶段。

把输出设计成 Agent 能消费的接口

文本命令默认可以把结果流到标准输出；媒体和转录命令则把文件写到磁盘并输出路径。这个设计解决了一个实际问题：如果把图片、音频或视频的 Base64 直接塞进编码代理上下文，二进制内容会浪费上下文并干扰后续规划。更稳妥的做法是让 CLI 写入项目目录，再把路径交给上层 Agent：

HERO_PATH=$(gemini-api image \
  "为开发者工具生成一张留出左侧标题空间的明亮工作室插画" \
  --aspect-ratio 16:9 \
  --image-size 2K \
  --out ./public/images/hero.jpg)

printf '生成的资源路径：%s\n' "$HERO_PATH"

需要机器读取结果时，使用 JSON 输出或 --jq，不要让脚本解析人类可读的长文本。例如，后台 Agent 应该关闭流式输出后取单个 JSON 对象：

RESEARCH_ID=$(gemini-api agent run \
  "整理 WebRTC SFU 架构的原始资料并列出来源" \
  --agent deep-research-preview-04-2026 \
  --background \
  --stream=false \
  -o json \
  --jq '.id')

gemini-api agent status "$RESEARCH_ID" -o json

官方文档明确指出，generate 和 agent run 在与 -o json 或 --jq 一起使用时，需要 --stream=false 才能返回单个完整 JSON 结果。对于脚本来说，这不是格式偏好，而是数据协议：流式文本和最终对象应当用不同的读取方式。若把流式输出直接交给只接受一份 JSON 的解析器，失败原因可能被误判成模型错误，实际只是调用模式不匹配。

CLI 还提供 --agent-mode，用于把结构化错误写到标准错误，并提供明确的退出码。官方文档列出的语义是：0 表示成功，1 表示运行时或 API 错误，例如网络失败、限流或后台任务失败，2 表示命令语法或参数校验失败，3 表示认证或授权失败。CI 应根据退出码决定是否重试、是否提示修正参数，不能只搜索错误文本里的某个英文片段。

例如，包装一层最小的 shell 门面：

set -o pipefail

if result=$(gemini-api generate \
  "从标准输入提取错误信息" \
  --stdin \
  --stream=false \
  -o json \
  --body '{"store":false}' \
  --agent-mode); then
  printf '%s\n' "$result"
else
  code=$?
  case "$code" in
    2) echo "CLI 参数或请求体校验失败" >&2 ;;
    3) echo "Gemini API 认证失败" >&2 ;;
    *) echo "Gemini API 调用失败，退出码：$code" >&2 ;;
  esac
  exit "$code"
fi

示例中的 store=false 不是所有任务都必须设置的值，但它说明了如何把未提供专用 flag 的 Interactions API 参数交给 --body。使用前应先运行对应命令的 --schema，并避免同一个字段同时由专用 flag 和 --body 设置；官方文档说明，冲突输入会以退出码 2 失败，而不是静默选择其中一个。

文件、后台任务与生命周期边界

文件分析适合采用“上传一次，多次引用”的方式。官方文档说明，小文件可以通过 -i 直接传入；当原始文件超过 14 MB 时，应先用 files upload --wait 上传，再把返回的 files/<id> URI 传给 analyze 或 transcribe。上传后的 Files API 文件会在 48 小时后删除，所以它不是长期对象存储，也不能把这个 URI 当作永久资产地址写入业务数据库。

FILE_URI=$(gemini-api files upload ./recordings/all-hands.mp4 --wait)
gemini-api analyze -i "$FILE_URI" "列出行动项、负责人和时间点。"
gemini-api transcribe -i "$FILE_URI" --format json --out ./recordings/all-hands.json

后台托管 Agent 也需要明确回收策略。--background 让命令快速返回 interaction ID，适合不应长期占用 shell 流的研究或构建任务；上层系统必须保存这个 ID，轮询状态，并在取消、失败或超时时做清理。CLI 文档的示例使用 agent status 获取结果，也提供 agent cancel 停止运行中的任务。不要把“命令已经返回”误认为“后台任务已经完成”。

托管 Agent 的安全边界同样不能被 CLI 隐藏。Gemini API 官方文档说明，托管 Agent 在隔离的 Linux 沙箱中运行，但默认具有出站网络访问能力；可以用网络 allowlist 限制域名，外部凭据应通过托管凭据引用，并遵循最小权限。CLI 只是调用入口，不会替你判断某个 Agent 是否应当拥有生产数据库、私有仓库或长期令牌。涉及写入外部系统的任务，仍需要人工复核、幂等设计和可撤销的权限。

适合落地的三种接入方式

第一种是编码代理的按需工具。把 gemini-api --help、--usage、--schema、--dry-run 和退出码规则写入项目的 AGENTS.md、CLAUDE.md 或其他代理说明，让代理知道何时调用 CLI、如何处理文件路径和 interaction ID。这样做的重点不是给代理增加一段产品介绍，而是给它一份可执行的接口契约：不要把二进制内容打印到上下文，复杂调用先预演，后台任务必须保存 ID，失败必须检查退出码。

第二种是构建流水线中的媒体和文档步骤。例如构建前生成一张临时插画、对产品说明 PDF 做结构化提取，或者把测试录音转换成字幕。此时应把输出目录设为明确的临时目录，把 JSON 结果写入后续步骤能读取的文件，并在失败时保留脱敏日志。对于可重复构建，固定 CLI release、固定输入文件、固定模型参数；对于不可重复的生成结果，不要把“重新运行一次即可得到同一文件”当作事实。

第三种是长任务编排。脚本启动后台托管 Agent，记录 interaction ID，把查询状态和取结果拆成单独步骤。这种方式适合研究、批量分析和不需要保持终端连接的任务，但要设计超时、取消、重试和结果归档。若任务需要实时双向音视频流，则不应强行套用 CLI；官方文档明确把双向 WebSocket 场景留给 Live API 和 GenAI SDK，CLI 支持的是普通 HTTP、SSE 流式和异步轮询。

对于 RouterHub 上的开发者，可以先在平台目录查看 API 服务入口；如果要把命令行调用放进仓库自动化，也可参考站内关于生成式工作流如何隔离 PR 锁文件的实践。这里的关键不是把 CLI 当成某个渠道推荐，而是把“命令行调用协议”和“上游 API 能力”分开验证：CLI 版本、模型名称、凭据来源以及中转或代理是否保留必要请求字段，都应在自己的环境里逐项确认。

上线前检查清单

可以把下面的检查作为接入完成的最低标准：

1. 本地开发与 CI 使用的是同一个明确的 CLI release，而不是一个无法回溯的 latest。
2. GEMINI_API_KEY 来自环境或密钥管理系统，仓库、镜像层、shell 历史和日志中没有明文密钥。
3. 新命令先运行 --help 或 --usage，需要自定义请求体时先保存 --schema。
4. 机器到机器调用统一选择 -o json 或 --jq，并在 generate、agent run 场景显式设置 --stream=false。
5. 文件命令只把路径传给后续步骤，大文件走 Files API，并记录 48 小时生命周期限制。
6. 多步交互显式传递 interaction ID、previous interaction ID 或文件 URI，不依赖隐藏的本地状态。
7. CI 按退出码区分参数错误、认证错误和运行时错误，重试策略只覆盖确实可重试的故障。
8. 托管 Agent 使用网络 allowlist、最小权限凭据和人工复核；涉及外部写操作时先做沙箱或测试环境演练。
9. 需要实时双向音视频时改用 Live API 与 SDK，不把 CLI 的 SSE 或轮询能力误当成 WebSocket 客户端。

Gemini API CLI 的实际变化可以用一句话概括：它把一组 API 能力包装成编码代理可以直接编排的 shell 工具，但把版本、状态、权限和结果协议明确留给调用方负责。采用这个边界，CLI 才适合进入 Agent 工作流；忽略这个边界，最容易出现的不是“模型不会回答”，而是脚本无法复现、后台任务丢失、文件 URI 过期或错误处理失真。

参考来源

• Gemini API CLI 官方文档
• Gemini API Release notes
• google-gemini/gemini-api-cli 官方仓库
• gemini-api-cli v0.4.5 Release
• gemini-api-cli GitHub Releases 最新版入口
• Gemini API Interactions 官方文档
• Gemini API 托管 Agent 官方文档