文档 · 供应商

Gemini 接入 Claude Code、Codex、Gemini CLI 和 OpenCode

Google 通过两条路提供 Gemini：一是 Gemini Developer API，也就是 AI Studio 的 Key 能用的那个；二是你自己 Google Cloud 项目里的 Vertex AI。任选一个添加到 magpie 一次，Claude Code、Codex、Gemini CLI、OpenCode 以及你接入的其他工具，都能通过 magpie 的本地网关 127.0.0.1:3425 使用 gemini-3.1-pro-preview 等 Gemini 3 模型，每个工具各用各的模型。

添加 Gemini API Key

1. 拿到 Key在 aistudio.google.com/apikey 创建。
2. 添加供应商在 magpie 的 供应商 页点 ＋ 添加供应商，选 Google Gemini，粘贴 Key 并保存。magpie 会向 Google 查询它提供哪些模型。
3. 给工具选上在 Agent 页点工具那一行的模型，选一个 Gemini 模型，比如 gemini-3.1-pro-preview。

magpie provider add google AIza…
magpie provider test google

magpie 里的模型 id 是 供应商/模型，所以 Gemini API 的模型写作 google/gemini-3.1-pro-preview：前面是供应商，后面是 Google 自己的 id。Key 保存在 magpie 的设置里，magpie 不会从 shell 里读取它。

接口地址

预设只会自动填一次 Gemini API 的地址；你清空之后，它就一直空着。不是 Gemini 客户端发来的请求，都走 Chat Completions。

模型列表

• 列表从哪来。magpie 只向 OpenAI 兼容接口拉一次列表，这份列表同样适用于 Gemini API，不用再拉第二次。模型名、推理档位和价格来自 models.dev 上的 google 目录。
• 图像模型。在 Google 这里，Gemini 的图像模型通过 Gemini API 出图。在 设置 → 模型 → 图像 里选用。

在各个工具里用

在 Agent 页点工具那一行选模型，或者在终端里切换。每篇指南都写了 magpie 会改工具配置里的哪些内容，以及怎么切回去。

magpie claude google/gemini-3.1-pro-preview
magpie codex google/gemini-3.1-pro-preview
magpie gemini model google/gemini-3.8-flash
magpie opencode google/gemini-3.1-pro-preview

• Claude Code 说的是 Anthropic Messages。magpie 把每个请求转换成 Gemini 的 Chat Completions，回复再转回 Messages，流式输出和工具调用都保留。Claude Code 接入其他模型。
• Codex 只说 OpenAI Responses。magpie 同样把它转换成 Chat Completions，回复再转回 Responses 交给 Codex。Codex 接入其他模型。
• Gemini CLI 说 Gemini 自己的 API，请求按原样发给 Gemini API，它的 Google 搜索也在那里执行。Gemini CLI 接入其他模型。
• OpenCode 说 Chat Completions，请求原样发给 Google。OpenCode 接入其他模型。

思考

• 显示思考过程。Gemini 的 OpenAI 兼容接口只有在 thinking_config 里明确要求时才返回模型的思考内容。工具要求显示推理时，magpie 会带上 include_thoughts 去要，这样长时间的思考会显示成思考中，而不是迟迟等不到第一个字。
• 档位与预算。Gemini 3 及之后的模型收到的是思考档位；Gemini 2 系列收到的是预算：minimal 和 low 为 1024 个 token，medium 为 8192，high 为 24576。xhigh 和 max 按 high 发送；没有对应档位的强度交给模型自己决定。
• 关闭推理。Gemini 3 没法完全不思考。工具关闭推理时，magpie 改为要求该模型最低的档位。
• 模型没有的档位。不是每个 Gemini 3 都有全部档位，比如 gemini-3.8-flash 就没有 minimal。Google 用 400 拒绝某个档位时，magpie 会换成该模型最接近的档位再问一次，并在 magpie 重启前一直记住。
• thinking_config 被拒。这是另一种 400：挡在 Gemini 前面的服务不认这个字段本身。magpie 会只带 reasoning_effort 再问一次，之后不再向它发送 thinking_config。
• 代理。放在本机或局域网代理后面的 Gemini 模型，比如 localhost 或内网地址上的，也按同样的方式处理。

思维签名与工具

• 思维签名。Gemini 3 会给每一步的第一个函数调用签名；签名丢了，下一个请求就会失败，报 400 “Function call is missing a thought_signature in functionCall parts”。工具本身不会保存签名，magpie 把它放进交给工具的调用 id 里（一个指向 magpie 目录中某个文件的简短引用），发往 Gemini 时再放回去。签名保留 90 天。
• Gemini 没签名的调用。对话前面其他模型发出的调用，或者 id 被工具截短的调用，会带上 Google 文档里写明的 skip_thought_signature_validator 发送，所以对话中途换成 Gemini 也没问题。
• 签名只回到原供应商。签名只会发回给出它的那个供应商。在同时有 Vertex AI 和 Gemini API 的路由分组里，另一个供应商收到的是不带签名的历史调用，而不会报 “Corrupted thought signature”。
• 工具的 schema。magpie 会给工具里没写类型的 schema 补上类型（Vertex AI 要求必须有），并去掉布尔型 schema 和 x- 开头的关键字，比如 MCP 的 x-mcp-header。不需要处理的工具原样发送。
• 流的结尾。Gemini 的 OpenAI 兼容接口会把整个函数调用放在一个 chunk 里，finish_reason 放在下一个。如果用量已经收到而这个结束原因丢了，magpie 会补上；连用量都没收到，就把回复报告为被截断，而不是当作完整的交出去。

缓存、费用与搜索

• 提示缓存。Gemini 缓存了提示，却不会在当轮说出来。magpie 把这样的一轮记为缓存写入，让下一轮继续走同一个供应商和 Key；是谁回答的也会记下来，重启后依然有效。
• 缓存与思考 token。无论走 Chat Completions 还是 Gemini API，magpie 都会从每个回复里读取缓存 token 和推理 token，用量 页会统计它们。
• 费用。用量页按 models.dev 上的 google 目录给每次调用计价。
• 联网搜索。Gemini API 只对没有声明函数工具的请求执行 Google 搜索。Claude Code 和 Codex 的请求都带工具，所以它们的联网搜索用的是 magpie 自己的搜索，由 Google 供应商用你的 Key 来回答：这些搜索会消耗你的 Gemini API 额度。

多个 Key 与限流

一个 Google Gemini 供应商可以放多个 Key：在它下面点 添加另一个密钥，也可以一次粘贴好几个。请求先走第一个开着的 Key，它用完或被限流时由下一个接替。也可以把供应商的路由方式改成轮流、按权重或用完一个再换下一个。

• 每分钟限流的 429。Gemini 因每分钟限额返回的 429 “You exceeded your current quota … Please retry in 33s”，magpie 视为限流而不是额度用完；Vertex AI 的 requests_per_minute_per_project 也一样。Key 先暂停一分钟，之后每次翻倍，最长到 rest-cap。
• 控制速度。rpm 给每个 Key 限定每分钟的请求数：超出的请求排队等空位，最多等 2 分钟，再等不到就返回 429。
• 额度用完。quota-rest 设定额度用完后 Key 暂停多久：默认 15 分钟，最长 8 天，也可以暂停到某个时刻。
• 花费上限与备用模型。spend-cap 给 Key 设一个每天、每月或总计的美元上限；fallback 指定 Gemini 额度用完或挂掉时请求去哪。

magpie provider rpm google 10
magpie provider spend-cap google <key> 20 month
magpie provider fallback google google-vertex/gemini-3.1-pro-preview

Vertex AI

Google Vertex AI 预设在你自己的 Google Cloud 项目里调用 Gemini，不需要 API Key。填上项目 id 即可，费用记在请求里的这个项目上。

gcloud auth application-default login
magpie provider add google-vertex project=my-project
magpie claude google-vertex/gemini-3.1-pro-preview

• 凭据。magpie 用 gcloud 的应用默认凭据（Application Default Credentials）签名，或者用 credentials= 以完整路径指定的文件：用户登录、服务账号密钥或模拟的服务账号都行。impersonate= 填服务账号的邮箱，需要你在该账号上有 roles/iam.serviceAccountTokenCreator。元数据服务器、工作负载身份联合以及 Vertex AI 快速模式的 API Key 都不会读取。
• 区域。location= 可以是 global（默认）、us、eu，或 us-central1 这样的具体区域。
• 模型。这个预设有自己的模型列表，包括 gemini-3.8-flash、gemini-3.1-pro-preview、gemini-2.5-pro，zai-org/glm-5.2-maas 这类合作方模型，以及 claude-opus-5-5 这类 Claude 模型。Gemini 走 Vertex AI 的 Gemini API，合作方模型走它的 OpenAI 兼容 Chat Completions，Claude 走 Anthropic 的 Messages API，全都在你的项目里。
• Vertex AI 上的思考。Gemini 3 的档位会对齐到该模型实际有的档位，关闭推理时用最低档。Gemini 2.5 用预算：Pro 为 128 到 32768 个 token（关闭时 128），Flash 最多 24576（关闭时 0），Flash-Lite 为 512 到 24576（关闭时 0）。

Google 登录

另有两种 Google 登录不用 Key 也能用 Gemini 模型。它们属于订阅，设置方法见 订阅用于任意 Agent。

• Gemini（Code Assist）。这是 Gemini CLI 的 Google 登录，模型为 gemini/…：magpie accounts add gemini。Google 只对有自己 Google Cloud 项目的 Code Assist Standard 或 Enterprise 账号提供服务；用 magpie accounts project gemini <邮箱> <项目> 指定项目。
• Antigravity。模型为 antigravity/…：magpie accounts add antigravity。登录后可以用 Antigravity 的 Claude 和 Gemini 模型。

常见报错

• “Thinking level MINIMAL is not supported for this model”。这个模型没有 minimal 档位。magpie 会换成它最接近的档位再问一次，工具照样拿到回复，并在 magpie 重启前记住这个档位。只有在没有档位可换时，报错才会原样交给工具。
• “Function call is missing a thought_signature in functionCall parts”。某个 Gemini 3 调用丢了签名。经过 magpie 时，签名放在调用 id 里并会被放回去，没有签名的调用会带上 skip_thought_signature_validator。
• “Corrupted thought signature”。签名不完整，或者来自另一个供应商。magpie 只把签名发回给出它的供应商。
• 429，提示 “Please retry in 33s”。这是每分钟的限额，不是额度用完。Key 会短暂暂停；用 rpm 可以让之后的请求保持在限额以内。
• Vertex AI 报 schema “didn’t specify the schema type field”。magpie 发给 Gemini 的每个工具 schema 都会补上类型，这个报错不应再传到工具那里。
• Vertex AI 保存不了。提示 “Google Vertex AI needs the id of your Google Cloud project” 时，加上 project=。凭据文件必须写完整路径。
• 检查 Key。magpie provider test google 会向每个接口发一个很小的请求，或者发给你指定的每个模型。加上 --as codex 或 --as claude-code，就按那个工具的方式发送。

常见问题

Claude Code 怎么用 Gemini？

在 magpie 里添加 Gemini API Key（供应商页，添加供应商，选 Google Gemini），然后在 Claude Code 那一行选一个模型，比如 gemini-3.1-pro-preview，或者运行 magpie claude google/gemini-3.1-pro-preview。magpie 会写好 Claude Code 的 settings.json，把每个 Messages 请求转换成 Gemini 的 Chat Completions，工具调用和流式输出都保留。

Codex 能用 Gemini 模型吗？

能。Codex 只说 Responses API，magpie 会把每个 Codex 请求转换成 Gemini 的 Chat Completions，回复再转回 Responses。运行 magpie codex google/gemini-3.1-pro-preview，或者在 Codex 那一行选模型。

Gemini 3 Pro 在 Claude Code 里连续调用工具会出错吗？

不会。Gemini 3 会给函数调用签名，下一个请求缺了签名就会被拒。magpie 把每个签名放进交给工具的调用 id 里，发往 Gemini 时再放回去，所以工具循环能一直进行；其他模型发出的调用会按无签名发送。

Gemini CLI 和 OpenCode 能通过 magpie 用我的 Gemini Key 吗？

能。Gemini CLI 的请求按原样发给 Gemini API，Google 搜索也一样。OpenCode 说 Chat Completions，请求原样发给 Gemini 的 OpenAI 兼容接口。

Gemini 为什么返回 429 并提示 “Please retry in 33s”？

这是每分钟的限额，不是额度用完。magpie 把它当作限流，让 Key 短暂暂停。运行 magpie provider rpm google 10（换成你自己的限额），magpie 就会把请求压在这个速度以内。

不用 API Key，能通过 Vertex AI 用 Gemini 吗？

能。用项目 id 添加 Google Vertex AI 预设，比如 magpie provider add google-vertex project=my-project。magpie 用 gcloud 的应用默认凭据或凭据文件签名，费用记在你的项目上。

能用 Gemini Code Assist 或 Antigravity 的登录吗？

能。两者都是订阅：运行 magpie accounts add gemini 或 magpie accounts add antigravity，然后选 gemini/… 或 antigravity/… 模型。Code Assist 需要有自己 Google Cloud 项目的 Standard 或 Enterprise 账号。

按供应商：DeepSeek · Kimi 与 Kimi Code · GLM 编程套餐 · 通义千问 · MiniMax · Grok · Mistral · OpenRouter · GitHub Copilot · Ollama

各个工具的指南：Claude Code 接入其他模型、Codex 接入其他模型、Gemini CLI 接入其他模型、OpenCode 接入其他模型。遇到问题可以在 Discord 提问。