使用 Gemini 的 OpenClaw：模型设置、API 密钥与费用检查

OpenClaw 通过其内置的 google 插件访问 Gemini：设置 GEMINI_API_KEY 或 GOOGLE_API_KEY，运行 openclaw onboard --auth-choice gemini-api-key，然后显式设置模型——因为添加身份验证不会更改默认模型。大多数设置文章遗漏的部分是：使用 AI Studio 密钥时，OpenClaw 有 三个独立的 Gemini 表面，每个都有自己的凭据、端点和账单。（Vertex AI 是第四条独立的凭据路径，通过 gcloud Application Default Credentials 使用，本文不涉及。）让聊天正常工作不会启用 Gemini 搜索，而启用 Gemini 搜索可能会向聊天路由从未使用的 Google 项目产生费用。

Gemini 集成不需要单独安装。它作为内置的 google provider 插件包含在 OpenClaw 本身中（官方 provider 插件，2026 年 9 月 21 日），OpenClaw 采用 MIT 许可证，并以 openclaw@2026.9.5 的形式发布在 npm 上，要求 Node >=24.16.0 <25 || >=26.1.0（npm 注册表，2026 年 9 月 21 日）。软件本身不收费；以下内容全部关于密钥的费用。

三个 Gemini 表面，三种凭据

优先级规则才是关键。Gemini 网页搜索首先读取 plugins.entries.google.config.webSearch.apiKey，然后读取 GEMINI_API_KEY，再读取 models.providers.google.apiKey，并且专用的 webSearch.baseUrl 会优先于 models.providers.google.baseUrl。OpenClaw 在此也不会继承模型 provider 的请求头，因为它们“属于模型 provider 端点，而该端点可能不同于网页搜索端点”，并在搜索请求中保留对 Content-Type、x-goog-api-key 和 x-goog-api-client 的控制权（Gemini 搜索文档，2026 年 9 月 21 日）。两条路由，有意保持独立。

在遵循较旧教程之前：OpenClaw 表示其“不提供新的 Gemini CLI OAuth 或 Antigravity OAuth 设置”，并指出面向消费者的 Gemini CLI 使用 Google 登录的访问权限已于 2026 年 6 月 18 日结束（provider 文档）。Google 自己于 2026 年 5 月 19 日发布的文章称，Gemini CLI 和 Code Assist IDE 扩展将停止向 Google AI Pro、Ultra 订阅者及免费用户提供服务（Google 开发者博客）。这两项说明都针对 CLI 和 IDE 使用方式，并非 AI Studio API 密钥——下面介绍的是 API 密钥路径。

设置 Gemini API 密钥

# The bundled google plugin reads either name.
export GEMINI_API_KEY="AIza..."   # or GOOGLE_API_KEY

openclaw onboard --auth-choice gemini-api-key

# Auth alone does not change the default model — set it on purpose.
openclaw models list --provider google
openclaw models set google/<id-from-that-list>

内置插件还会读取 GEMINI_API_KEYS、GEMINI_API_KEY_1 和 GEMINI_API_KEY_2进行轮换，并读取 OPENCLAW_LIVE_GEMINI_KEY作为单个覆盖值（官方 provider 插件，2026 年 9 月 21 日）。这些变量被说明为 google 插件自身的变量；自定义 provider 参考并未将它们列为你自行声明的 provider id 的变量，此类 provider 通过 apiKey 设置其密钥（其中展示了 $${ENV_VAR} 展开方式）。

最后一行比看上去更重要。openclaw configure“会在添加 provider 或重新进行身份验证时保留现有的 agents.defaults.model.primary”，而 openclaw models auth login 除非传入 --set-default，也会执行相同操作（快速规则）。完成 Gemini 身份验证后仍从旧模型获得回答是预期行为，并非错误。

不要从任何教程（包括本教程）复制模型 id。配置密钥后，OpenClaw 会通过 Gemini models.list API 刷新 Google AI Studio 的文本模型目录，因此新的变体无需 OpenClaw 发布新版本即可出现——而 OpenClaw 自己的页面对示例 id 说法不一：一处命名 google/gemini-3.5-flash，另一处命名 google/gemini-3.1-flash 和 google/gemini-3.1-pro-preview，搜索工具则默认使用 gemini-3.6-flash。实时列表是唯一权威来源。OpenClaw 确实会规范化一些旧版引用——google/gemini-3.1-pro 会被“接受并规范化”为 google/gemini-3.1-pro-preview（官方 provider 插件）——而 google/gemini-3-pro-preview“已于 2026-03-09 退役”，并将 google/gemini-3.1-pro-preview列为替代项（provider 文档，2026 年 9 月 21 日）。

Gemini API 密钥实际计费的内容

令牌和搜索 grounding 是两个计费项目，而 Google 的页面乍看像是一个项目。标准层 Gemini Developer API 的每 1M 令牌费率来自Google 的定价页面（最后更新于 2026 年 9 月 16 日，阅读于 2026 年 9 月 21 日）：

把最后一列读两遍。OpenClaw 默认的 Gemini 网页搜索模型是 gemini-3.6-flash，这是一个 Gemini 3.x 模型，而其 grounding 在 Google 免费层中“不可用”——因此，开箱即用的 Gemini 搜索设置需要一个已启用计费的项目，尽管同一模型的令牌是免费的。计费单位也不同：OpenClaw 自身指出，“Gemini 3 grounding 按搜索查询计费，而 Gemini 2.5 grounding 按提示计费”；Google 还补充说，一次请求“可能会对 Google Search 产生一个或多个查询。你将为执行的每个单独搜索查询付费”。Grounding 费用叠加在令牌费用之上——“Gemini 的费用始终适用”（两处引文均来自同一定价页面）。举例来说，一个月进行 6,500 次 Gemini 3.x 搜索查询，其中 1,500 次按每 1,000 次 $14 计费，则仅搜索费用就是$21.00，还未包括任何令牌费用。

同一页面还有两项信息：付费层增加上下文缓存，并提供成本降低 50% 的 Batch API；同时数据使用说明也相反——免费层内容“用于改进我们的产品”，付费层内容则不会，这对于持续运行的助手很重要。Gemini 也只是 OpenClaw 的搜索提供商之一；其网页搜索提供商表将 DuckDuckGo（“无（无需密钥）”）、SearXNG（“无（自托管）”）和 Parallel Search（Free）（“无（免费 Search MCP）”）列为无需密钥的选项（网页搜索，2026 年 9 月 21 日），因此“我是否根本需要 Gemini grounding”是一个合理的首要问题。

通过 OpenAI 兼容网关路由 Gemini 聊天

OpenClaw 的自定义 provider 参考表示，只有“当你希望覆盖默认基础 URL、请求头或模型列表”时，才应使用显式的 models.providers.<id> 条目；而网关配置参考列出了十一种 api 值：openai-completions、openai-responses、openai-chatgpt-responses、anthropic-messages、google-generative-ai、google-vertex、github-copilot、bedrock-converse-stream、ollama、pi-messages 和 azure-openai-responses。v2026.9.7 的配置 schema接受第十二种值 google-interactions，该值于 2026 年 9 月 25 日加入。参考文档尚未列出它，但 OpenClaw 的Google provider 页面将其说明为默认 google-generative-ai传输的可选替代方案，使用 Gemini 的 Interactions API，并位于 https://generativelanguage.googleapis.com/v1beta 下。Kunavo 的 Gemini 模型通过其 OpenAI 兼容表面 POST /v1/chat/completions（聊天端点）访问，而 Kunavo 未发布 generativelanguage、v1beta 或 Interactions 端点——因此这些 Google 适配器都无法访问它；可访问的路由是一个单独的 provider id，绝不是被重定向的 google 插件。

{
  "models": {
    "mode": "merge",
    "providers": {
      "kunavo": {
        "baseUrl": "https://api.kunavo.com/v1",
        "apiKey": "${KUNAVO_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "gemini-3-8-flash",
            "name": "Gemini 3.8 Flash",
            "input": [
              "text",
              "image"
            ],
            "contextWindow": 1048576,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "kunavo/gemini-3-8-flash"
      }
    }
  }
}

这里有四个关键细节。slug 使用短横线——Kunavo 的 id 是 gemini-3-8-flash，而 Google 和 OpenClaw 使用点号形式；它们是不同的字符串。之所以声明 contextWindow，是因为没有上下文元数据的自定义模型会退回到 200,000 个令牌的预算，浪费 Kunavo 目录在此记录的窗口大部分容量（1,048,576 个令牌——这是 Kunavo 的元数据，而非 Google 发布的限制）。input用于声明图像，因为 OpenClaw 默认将自定义模型设为仅支持文本。并且省略了 cost，因此 OpenClaw 在此路由上的本地估算默认为零：显示 $0 表示缺少元数据，而不是推理免费。

该路由放弃了哪些能力，文档已有说明，并非猜测。在 api: "openai-completions" 上针对非 OpenAI 自有主机时，OpenClaw 强制使用 compat.supportsDeveloperRole: false，并跳过原生请求构造——没有 service_tier，没有 Responses 或 Completions store，没有提示缓存提示，也没有推理兼容的请求载荷构造（自定义 provider）。Gemini 专属扩展也会被留在后面：params.cachedContent有文档说明可用于直接 Gemini 运行，密钥轮换变量是插件功能，而 OpenClaw 的 thinkingLevel / thinkingBudget 映射则针对 google provider 进行了说明——它是否能在网关路由上继续生效，并非本页面验证过的事项。

Kunavo 不提供 embedding 模型，也不提供文本转语音或语音转文本模型。因此，google插件的 embedding 和语音契约无论聊天如何路由，都仍使用 Google 密钥。

关于能力，要谨慎判断你相信的是谁的说法。Google 当前的模型页面不再显示每个模型的令牌限制，因此其他地方引用的上下文数值可能只是某个旧来源的复制。Kunavo 的目录在其 Gemini 条目上标记了视觉、函数调用、流式传输和长上下文能力，并在 gemini-2-5-flash 之外的所有模型上标记了思考能力。每项声明都仅适用于发布它的一方——请先在自己的任务上验证工具调用。

为你实际选择的模型计价

按模型比较 Google 标准层，因为如今按整个模型家族进行比较是不成立的：

Kunavo 费率来自实时目录，Google 费率来自 2026 年 9 月 21 日阅读的定价页面；初期优惠期于 2026 年 12 月 31 日结束，之后 Flash 对比将再次反转。

这是一个演算示例，即令牌算术，而不是经过测量的 OpenClaw 任务或账单上限。假设一周的助手工作发送4,000,000 个未缓存输入令牌并接收150,000 个输出令牌，不使用缓存和搜索。按 Kunavo 的费率使用 Gemini 3.8 Flash，费用为 $2.49；按 Google 的 Flash 介绍期费率进行相同计算为 $3.56，按 2027 年费率则升至 $7.13。在 Kunavo 上对 Gemini 3.6 Flash 使用相同数量的令牌，费用为 $4.99——高于 Google 介绍期的数值，这正是决定因素应是模型 id 而非 provider 名称的原因。

Kunavo 目录中的金额是计费下限，而不是上限：当上游报告其费用时，账单取目录成本与上游成本乘以适用加价之间的较大值。缓存费用、搜索 grounding 和托管费用不包含在本示例中，最低充值额为预付额度$10——这是资金最低限额，而非任务费用或订阅费用。请参阅计费详情以及 OpenClaw 定价，了解完整的运行账单。

先用一项请求验证，再读取两本账

openclaw config validate
openclaw gateway restart
openclaw models list --provider kunavo
openclaw infer model run --model kunavo/gemini-3-8-flash --prompt "hi" --json

openclaw models list读取已发布的库存，openclaw models status显示解析后的默认设置和身份验证状态；二者都不能证明付费任务可正常运行，而在已知 provider 上使用 openclaw models set 会保存未编入目录的模型且仅发出警告。openclaw doctor --json --severity-min info还会显示本地目录无法确认的活动模型（CLI 参考）。上面的单项请求才是第一条会产生费用的证据。

按状态码进行分类排查。OpenClaw 记录了本地 OpenAI 兼容服务器的 model_not_found 特征，其中列出的三个字段与自定义提供商条目设置的三个字段相同：确认 baseUrl 包含 /v1；对于 /v1/chat/completions 后端，api 为 "openai-completions"；并确认 models[].id 是不带提供商前缀的、该提供商内部的模型 ID，提供商前缀仅在选择时使用（故障排查）。针对 Kunavo，能说明基础 URL 正确的检查方式是向真实 API 路径发送未经身份验证的请求：GET https://api.kunavo.com/v1/models 返回 401，响应体为 authentication_error，这意味着 URL 正确，而密钥有问题。裸主机名和裸 /v1 路径都不是 API 路径，会返回 HTML，因此指向任一地址的客户端都会在到达模型之前失败（于 2026 年 9 月 21 日核查）。403 是需要停下来仔细查看的状态码：OpenClaw 警告它“可能来自上游安全层，例如 CDN、WAF、机器人管理规则或反向代理”，并且一次成功的最小 curl 请求并不能保证真实的 SDK 风格请求能通过同一层。请参阅找不到模型和Gemini API 密钥无法使用，了解更详细的说明。

对于原生路由，请从 Kunavo 的 Gemini API 密钥说明和 Google AI Studio 开始；对于网关路由，请在 API 密钥中创建密钥并注册 Kunavo 账户，然后按照OpenClaw 的最佳 API中的自定义提供商教程操作。测试期间请保持当前使用的路由可用。

哪种路由胜出时

如果你仍在选择提供商，而不是配置提供商，那么Gemini API 定价和兼容 OpenAI 的 API涵盖了这一决策的两个方面。

常见问题

为本页面于 2026 年 9 月 21 日获取的资料：OpenClaw 的 Google 提供商、官方提供商插件、Gemini 搜索、网页搜索、自定义提供商（包括概念和网关参考）、快速规则、CLI 模型和故障排除文档；Google 的 Gemini API 定价页面（最后更新于 2026 年 9 月 16 日）、模型页面、Google Search grounding 页面及其 2026 年 5 月 19 日的开发者博客文章；openclaw 的 npm 注册表条目；以及 Kunavo 自身的目录。2026 年 10 月 1 日，针对自定义提供商的 api 值，依据网关参考、Google 提供商页面以及 OpenClaw v2026.9.7 源码中的配置架构和 Interactions 传输进行了重新核对。本页面唯一发出的实时请求，是向 Kunavo 的 /v1/models 发出未经身份验证的 GET 请求，以记录上文所述的 401。本文没有任何内容经过 OpenClaw 安装、Kunavo 端点或 Google 端点的运行时测试；所有美元数值都是基于已发布费率的示例性算术。