# 装了 Gemini CLI 还用得着 gemini-api 吗？名字挺像，分工差得远 **URL:** \ **Category:** 人工智能\ **Tags:** Google, AICoding, API, Gemini\ **Created:** [2026 年10 月 29 日 09:47 UTC](https://www.shiqidu.com/t/topic/1845 "2026-10-29T09:47:22Z")\ **Posts on this page:** 1\ **Page:** 1
作者： ![shiqidu\_editor](https://www.shiqidu.com/user_avatar/www.shiqidu.com/shiqidu_editor/32/528_2.png) [@shiqidu\_editor](https://www.shiqidu.com/u/shiqidu_editor)\ 发布日期： [2026 年10 月 29 日 09:47 UTC](https://www.shiqidu.com/t/topic/1845/1 "2026-10-29T09:47:22Z")
`gemini-api` 的安装脚本默认往 `/usr/local/bin` 放一个单文件 Go 二进制，不依赖 Node 或 Python 运行时。它是 Google 10 月 27 日放出的 beta 版 API 命令行，跟很多人 PATH 里早就有的 Gemini CLI（`gemini`）是两回事，定位几乎没有交集。 ## gemini-api 是干嘛的 [官方发布说明 10 月 27 日那条](https://ai.google.dev/gemini-api/docs/changelog)的描述是：无状态、零依赖的命令行客户端，给 AI 编码助手、脚本和 CI 流水线用，底层走 Interactions API，能生成文本和媒体、分析文件、启动托管 Agent。 [官方文档页](https://ai.google.dev/gemini-api/docs/cli)里专门加了一条提示：`gemini-api` 是无状态的 API 客户端，不是 `@google/gemini-cli` 那种陪你写代码的交互式助手，任何编码 Agent 里都能调用它。 说白了，这东西是给 Codex、Claude Code 这类已经在干活的 Agent 多配一把工具，自己并不陪人聊天改代码。要张占位图、一段配音、读份 PDF，或者把 Deep Research 任务丢到后台，在 shell 里敲条命令就行。媒体文件直接写到磁盘，stdout 只吐路径，不会把 base64 塞满上下文。 「无状态」指本地不存会话。要接着上一轮聊，得显式传 `--previous-interaction-id`，或者复用上传后拿到的 `files/` URI、后台任务的 interaction ID。 ## Gemini CLI 现在的处境 另一边，[gemini-cli 仓库 README](https://github.com/google-gemini/gemini-cli) 开头那段说明可以看一眼。按 10 月的版本，Gemini CLI 现在主要服务买了 Code Assist Standard / Enterprise 授权（含 GitHub 版）的组织。免费个人用户和 Google AI Pro / Ultra 订阅者已在 6 月 18 日迁到 Antigravity CLI（`agy`）。README 还写明它没针对 Gemini 4 系列调优。 所以站里那篇 [Gemini CLI 卡在 Waiting for auth](https://www.shiqidu.com/t/topic/1779) 讲的是交互式工具的登录问题，跟这里的 `gemini-api` 不是一个东西，排查思路不通用。 自己整理的对照： | | Gemini CLI（`gemini`） | `gemini-api` | | --- | --- | --- | | 形态 | 交互式终端编码 Agent | 一次一条命令的 API 客户端 | | 本地状态 | 有会话 | 不存，靠 ID 串联 | | 安装 | npm 包 `@google/gemini-cli` | 单个 Go 二进制 | | 认证 | Code Assist 授权，兼容旧的付费 API / Vertex 密钥 | API Key（`GEMINI_API_KEY`） | | 典型用户 | 坐在终端前的人 | 其他 Agent、脚本、CI | | 阶段 | 面向企业持续维护 | beta | 如果只是坐在终端前让 AI 帮忙改代码，`gemini-api` 派不上用场。反过来，想让流水线每次构建时顺手生成一段发布说明配音，或者批量转写会议录像，交互式 CLI 又显得太重。两者放在同一台机器上并不冲突。 ## 装和配 官方文档列的安装方式就这几种： ```bash # macOS / Linux curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash # 用 Go 装 go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest ``` Windows 用 PowerShell 跑仓库里的 `install.ps1`，也可以去 [GitHub Releases](https://github.com/google-gemini/gemini-api-cli/releases) 下预编译包。别想当然去 npm 上搜 gemini-api：那上面的同名包不是 Google 发的。官方列的渠道里同样没有 pip。 认证就是 API Key： ```bash export GEMINI_API_KEY="YOUR_API_KEY" gemini-api whoami gemini-api generate "Confirm CLI setup in one sentence." --dry-run ``` 自己电脑上可以用 `gemini-api configure --api-key "YOUR_API_KEY"` 存进系统钥匙串，加 `--no-keyring` 则落到 `~/.config/gemini-api/config.yaml`。在 CI 里，文档建议从 secret 存储注入，别提交进仓库。 ## 放进脚本和 CI 要留意的 - `--dry-run` 会校验参数、打印将要发出的 HTTP 请求，凭据打码，不联网。第一次用某个命令前先跑一遍挺省事。 - 想拿结构化结果用 `--output-format json`（简写 `-o`），也能配 `--jq` 直接取字段。`generate` 和 `agent run` 默认流式输出，要单个 JSON 得加 `--stream=false`。 - `--usage` 会把整棵命令树、参数和默认值按 KDL 格式打出来，`gemini-api --schema` 给出 `--body` 能接受的 JSON Schema，Agent 不必翻外部文档就能查到用法。再加上 `--agent-mode`，报错会变成结构化 JSON 写进 stderr。 - 退出码分得很清楚：0 成功，1 运行时或 API 错误，2 参数校验错，3 认证失败。脚本里按退出码分支比解析报错文字靠谱。 - 文档明说 beta 阶段哪怕小版本升级也可能带破坏性变更，CI 里最好锁死 release。安装脚本认 `GEMINI_VERSION` 环境变量，Docker 镜像里则建议直接用 Releases 的归档包。 - 它只走普通 HTTP、SSE 和轮询，不支持双向 WebSocket，实时语音视频还是得用 SDK 接 Live API。 锁版本的写法，`` 换成 Releases 页上的具体 tag： ```bash curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | GEMINI_VERSION= bash ``` 你们会把 `gemini-api` 写进 AGENTS.md 让 Agent 自己挑命令，还是只在 CI 里跑几条固定的？