跳转至

Gemini 搜索

OpenClaw 通过内置的 Google Search grounding 支持 Gemini 模型，该功能会返回由实时 Google Search 结果支持的 AI 合成答案，并附带引用。

获取 API 密钥

1. 创建密钥

前往 Google AI Studio 创建一个 API 密钥。

2. 存储密钥

在 Gateway 环境中设置 GEMINI_API_KEY，复用 models.providers.google.apiKey，或通过以下命令配置专用的 web 搜索密钥：

openclaw configure --section web

配置

{
  plugins: {
    entries: {
      google: {
        config: {
          webSearch: {
            apiKey: "AIza...", // optional if GEMINI_API_KEY or models.providers.google.apiKey is set
            baseUrl: "https://generativelanguage.googleapis.com/v1beta", // optional; falls back to models.providers.google.baseUrl
            headers: {
              "X-Routing-Target": "staging",
              "X-Gateway-Token": {
                source: "env",
                provider: "default",
                id: "GEMINI_GATEWAY_TOKEN",
              },
            },
            model: "gemini-3.6-flash", // default
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        provider: "gemini",
      },
    },
  },
}

凭证优先级： Gemini web 搜索首先使用 plugins.entries.google.config.webSearch.apiKey，然后使用 GEMINI_API_KEY，最后使用 models.providers.google.apiKey。对于 base URL，专用的 plugins.entries.google.config.webSearch.baseUrl 优先于 models.providers.google.baseUrl。

对于 gateway 安装，请将环境变量中的密钥放在 ~/.openclaw/.env 中。

请求头

当操作方网关需要额外的请求元数据时，可设置 plugins.entries.google.config.webSearch.headers。普通字符串值使用常规配置处理；它们不会仅仅因为是 header 就被自动视为机密。当某个 header 包含机密时，请使用如上所示的 SecretRef 值。OpenClaw 会在运行时解析该值，并对其应用现有的机密编辑（redaction）流程。

Gemini 请求保留对 Content-Type、x-goog-api-key 和 x-goog-api-client 的所有权；这些值会覆盖同名的已配置 header。models.providers.google.headers 不会被继承，因为它们属于模型提供方端点，而该端点可能与 web 搜索端点不同。

空的普通字符串值是有效的。无效字段以及传输层所有或分帧名称（如 Content-Length、Host 和 Transfer-Encoding）会在缓存查找或网络 I/O 之前使当前搜索失败。

有效的 header 名称和值通过摘要对内存中的搜索缓存进行分区，因此两个路由目标不会共享结果。对于上述提供方拥有的名称，配置的值会被忽略，并且不会对缓存进行分区。在跨域重定向时，受保护的 fetch 路径仅保留其标准的安全重定向 header。

工作原理

与返回链接和摘要列表的传统搜索提供方不同，Gemini 使用 Google Search grounding 生成带有内联引用的 AI 合成答案。结果同时包含合成答案和来源 URL。

  • Gemini grounding 中的引用 URL 会通过 OpenClaw 的 SSRF 防护 fetch 路径（跟随重定向、校验 http/https）发出的 HEAD 请求，自动从 Google 重定向 URL 解析为直接 URL。
  • 重定向解析使用严格的 SSRF 默认值，因此指向私有/内部目标的重定向会被阻止。

支持的参数

Gemini 搜索支持 query、freshness、date_after 和 date_before。

为兼容共享的 web_search，count 会被接受，但 Gemini grounding 仍然返回一个带有引用的合成答案，而不是 N 条结果的列表。

freshness 接受 day、week、month、year 以及共享的快捷方式 pd、pw、pm 和 py。day/pd 会向 Gemini 查询添加一条时效性指令，而不是强制的 24 小时范围。week、month、year 以及显式的 date_after/date_before 范围会设置 Gemini Google Search grounding 的 timeRangeFilter。不支持 country、language 和 domain_filter。

模型选择

默认模型是稳定的 gemini-3.6-flash。省略 plugins.entries.google.config.webSearch.model 时使用此默认模型；显式指定的模型会保持固定。你可以选择任何支持 grounding 且对你的 API 密钥可用的 Gemini 模型。

Gemini 3 grounding 按每次搜索查询计费，而 Gemini 2.5 grounding 按每个 prompt 计费。请参阅 Google Search grounding 定价。

Base URL 覆盖

当 Gemini web 搜索必须通过操作方代理或自定义的 Gemini 兼容端点路由时，请设置 plugins.entries.google.config.webSearch.baseUrl。如果未设置，Gemini web 搜索会复用 models.providers.google.baseUrl。普通的 https://generativelanguage.googleapis.com 值会被规范化为 https://generativelanguage.googleapis.com/v1beta；自定义代理路径在去除尾部斜杠后按原样保留。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw