Gemini实战：让Claude Code 和 Codex 调用 Gemini处理多模态任务

写编码 Agent 时，经常遇到一个分工问题：主 Agent 负责读代码、改文件、跑测试，但图片生成、PDF 阅读、音频转写、深度研究这些任务，它手头的模型并不擅长。一个自然的想法是让 Claude Code 或 Codex 去调用 Gemini。问题是，装哪个 CLI？

截至 2026 年 10 月 30 日发布的 0.4.5 版，Google 给 Gemini API 提供的命令行客户端叫 gemini-api，仓库是 google-gemini/gemini-api-cli，Apache 2.0 许可，macOS、Linux、Windows 都能跑。它和 Gemini CLI 不是一回事。原文对两者有完整对比：https://apifox.com/apiskills/gemini-api-cli/

先分清两个 CLI

这张表决定了选型：你要的是「给现有 Agent 加能力」，选 gemini-api；你要的是「换一个 Agent 来写代码」，才选 Gemini CLI。装错之后，两个 Agent 互相对话，上下文和权限都更难管。

图 1：两个 CLI 的角色对照

左边会接手任务，右边只补能力。

gemini-api 是无状态单二进制，每个命令 POST 到 https://generativelanguage.googleapis.com/v1beta/interactions。没有会话记忆，也没有隐藏状态，这对 Agent 反而友好：输入明确，输出可解析，失败可重试。

安装、认证与最小验证

macOS / Linux 安装脚本：

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 ​

也可以 go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest，或从 GitHub Releases 下载对应平台的压缩包，用 checksums.txt 校验后放进 PATH。装完确认版本：

gemini-api version # gemini-api 0.4.5 ​

认证有两种方式。临时用环境变量：

export GEMINI_API_KEY="YOUR_API_KEY" ​

在自有工作站上，建议让 CLI 存进系统钥匙串：

gemini-api configure --api-key "YOUR_API_KEY" gemini-api whoami ​

configure 在 macOS 用 Keychain，Linux 用 Secret Service，Windows 用 Credential Manager。加 --no-keyring 则写到 ~/.config/gemini-api/config.yaml。whoami 会显示当前凭据和来源，排查「为什么 Agent 说没权限」时先跑它。

Google 明确提示 beta 期间小版本可能有破坏性变更，CI 里要锁版本。官方安装脚本支持在命令前加 GEMINI_VERSION=。

让 Agent 真正用得上的四个细节

第一，--dry-run。它校验参数并打印请求，凭据会脱敏，不发起网络调用，也不读取钥匙串。没配密钥时也能用。本文的示例就是先 dry-run 再真跑。

第二，--stream=false。流式命令（generate、agent run）如果直接配 -o json 或 --jq，stdout 会输出多条流式事件，Agent 无法当成一个 JSON 解析。加 --stream=false 才会拿到单个可解析结果。这是最容易踩的坑。

第三，退出码。0 正常，1 运行时或 API 失败，2 用法或校验错误，3 认证失败。Agent 不用解析错误文本，按退出码决定重试、修正参数还是来问用户。

第四，输出格式。全局支持 pretty、json、yaml、table、toon，--agent-mode 会把错误以结构化 JSON 写到 stderr，stdout 输出紧凑 TOON。对无头 Agent，再加 --no-interactive 禁用提示和 TUI 表单。

四类典型任务

图 2：八组命令和三种返回

命令不记会话，结果交回主 Agent。

生成或编辑图片：

gemini-api image "A friendly robot mascot, soft studio lighting" --out ./assets/mascot.jpg gemini-api image "Add a winter scarf" -i ./assets/mascot.jpg --out ./assets/mascot-winter.jpg ​

image 支持 --aspect-ratio 和 --image-size，可选 512、1K、2K、4K。默认模型是 gemini-nano-banana-2.1。

分析 PDF、图片和 YouTube URL：

gemini-api analyze -i product-brief.pdf "What should we build first, and why?" > plan.md gemini-api analyze -i before.png -i after.png "Summarize the visual design changes" ​

-i 可重复。内联输入上限约 14 MB。更大的文件先上传一次：

FILE_URI=$(gemini-api files upload interview.mp4 --wait --output-format json --jq '.name') gemini-api analyze -i "$FILE_URI" "List the key action items with timestamps" ​

Files API 的上传文件保留 48 小时，过期要重新上传。

转写音频和视频：

gemini-api transcribe -i interview.mp4 --format srt --out interview.srt ​

--format 支持 md、text、json、srt；--no-speakers 和 --no-timestamps 可以去掉说话人和时间戳。

后台跑 Deep Research：

ID=$(gemini-api agent run "Research battery recycling approaches and cite sources" --agent deep-research-preview-04-2026 --background --jq '.id') gemini-api agent status "$ID" --stream=false --output-format json ​

--background 立即返回 interaction ID，Agent 可以先去做别的事，稍后查状态；agent cancel 可以停止。0.4.5 还列出 deep-research-max-preview-04-2026 和 antigravity-preview-05-2026。

注意边界：它不支持 WebSocket，实时语音和视频仍要回到 GenAI SDK。

和 Apifox CLI 接力，补上接口验证

gemini-api 能生成内容、分析文件，但对你的 API 一无所知。假设你的服务包了一个 /v1/invoices/extract 接口，接收 PDF 并返回 total 字段。gemini-api 可以帮你确认模型能不能从 PDF 里读出金额，但不能证明 staging 上的接口返回 200、字段非空、发布没有破坏功能。

这层交给 Apifox CLI，同一个 Agent 可以同时调两者：

npm install -g apifox-cli@latest apifox login --with-token apifox import --project --format openapi --file ./openapi.yaml apifox cli-schema get test-case-create apifox test-case category --project apifox test-case create --project --file case.json apifox run --test-case --project -e -r cli,json ​

两个容易漏的点：创建用例前先查 categoryId，否则 test-case create 会失败；CI 里把 -r cli,json 换成 -r junit，同一行命令就能产出测试报告。Apifox 免费版不限制成员数量和协作人数，小团队可以直接把这条链路跑起来。

图 3：模型能力与接口验证

一个管模型，一个管接口契约。

收尾

选型结论很明确：让现有编码 Agent 用 Gemini，装 gemini-api；想把 Gemini 当编码 Agent，才装 Gemini CLI。前者负责模型能力，后者负责编码对话，Apifox CLI 负责接口验证。三者边界清楚，Agent 的工作流才稳定。