古法编程

Appearance

本页说明如何在 OpenClaw 中配置 Google Gemini 模型，支持 API Key 和 Gemini CLI OAuth 两种认证方式。用户可调用聊天补全、图像生成、视频生成、音乐生成、TTS、实时语音和网页搜索（Grounding）等能力。关键操作包括运行 openclaw onboard --auth-choice gemini-api-key 设置 API Key，或使用 openclaw models auth login --provider google-gemini-cli --set-default 完成 OAuth 登录。环境变量支持 GEMINI_API_KEY 和 GOOGLE_API_KEY。

OpenClaw 配置 Google Gemini：API Key 与 OAuth 接入指南 ​

Google 插件通过 Google AI Studio 提供 Gemini 模型的访问权限，此外还集成了图像生成、媒体理解（图像/音频/视频）、文本转语音（TTS）和基于 Gemini Grounding 的网页搜索功能。

  • Provider: google
  • 认证方式: GEMINI_API_KEY 或 GOOGLE_API_KEY
  • API: Google Gemini API
  • 运行时选项: 使用 provider/model agentRuntime.id: "google-gemini-cli" 可复用 Gemini CLI 的 OAuth 认证，同时保持模型引用为 google/* 的规范格式。

快速上手：选择认证方式并完成配置 ​

根据你的偏好，选择以下两种认证方式之一进行配置。

方式一：使用 API Key（推荐标准接入） ​

适用场景： 通过 Google AI Studio 进行标准 Gemini API 接入。

  1. 运行交互式引导命令

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

  2. 或者，直接以非交互模式传入 API Key

    bash
    openclaw onboard --non-interactive \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY"

  3. 设置默认模型

    json5
    {
  agents: {
    defaults: {
      model: { primary: "google/gemini-3.1-pro-preview" },
    },
  },
}

  4. 验证模型是否可用

    bash
    openclaw models list --provider google

    提示：环境变量 GEMINI_API_KEY 和 GOOGLE_API_KEY 都被支持。使用你已有配置的任何一个即可。

方式二：使用 Gemini CLI（OAuth 认证） ​

适用场景： 复用已有的 Gemini CLI 登录凭据（基于 PKCE OAuth），无需申请单独的 API Key。

警告：google-gemini-cli provider 是一个非官方集成。部分用户报告以这种方式使用 OAuth 时可能会遇到账户限制。请自行承担风险。

  1. 安装 Gemini CLI 确保本地 gemini 命令已添加到 PATH。

    bash
    # 使用 Homebrew 安装
brew install gemini-cli

# 或使用 npm 全局安装
npm install -g @google/gemini-cli

    OpenClaw 支持 Homebrew 安装和全局 npm 安装，包括常见的 Windows/npm 布局。

  2. 通过 OAuth 登录

    bash
    openclaw models auth login --provider google-gemini-cli --set-default

  3. 验证模型是否可用

    bash
    openclaw models list --provider google

  • 默认模型: google/gemini-3.1-pro-preview

  • 运行时: google-gemini-cli

  • 别名: gemini-cli

    注意：Gemini 3.1 Pro 的 Gemini API 模型 ID 是 gemini-3.1-pro-preview。OpenClaw 接受简写 google/gemini-3.1-pro 作为便捷别名，并在调用 provider 前将其标准化。

  • 环境变量:

    • OPENCLAW_GEMINI_OAUTH_CLIENT_ID
    • OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET （或 GEMINI_CLI_* 的相关变体）

    注意：如果 Gemini CLI OAuth 请求在登录后失败，请在网关主机上设置 GOOGLE_CLOUD_PROJECT 或 GOOGLE_CLOUD_PROJECT_ID 并重试。

    注意：如果在浏览器流程开始前登录失败，请确保本地 gemini 命令已正确安装且位于 PATH 中。

    google-gemini-cli/* 模型引用是用于向后兼容的遗留别名。新配置应使用 google/* 模型引用，并在需要本地 Gemini CLI 执行时指定运行时为 google-gemini-cli。

能力总览 ​

能力支持情况
聊天补全是
图像生成是
音乐生成是
文本转语音 (TTS)是
实时语音是（Google Live API）
图像理解是
音频转写是
视频理解是
网页搜索 (Grounding)是
推理/思考模式是（Gemini 2.5+ / Gemini 3+）
Gemma 4 模型是

内建的 gemini 网页搜索 provider 使用 Gemini Google Search Grounding 功能。你可以在 plugins.entries.google.config.webSearch 下配置专用的搜索密钥，或让它复用由 GEMINI_API_KEY 设置的 models.providers.google.apiKey 值。

json5
{
  plugins: {
    entries: {
      google: {
        config: {
          webSearch: {
            apiKey: "AIza...", // 可选，如果已设置 GEMINI_API_KEY 或 models.providers.google.apiKey 则可不填
            baseUrl: "https://generativelanguage.googleapis.com/v1beta", // 可选，默认为 models.providers.google.baseUrl
            model: "gemini-2.5-flash",
          },
        },
      },
    },
  },
}

凭据优先级：专用 webSearch.apiKey > GEMINI_API_KEY > models.providers.google.apiKey。webSearch.baseUrl 是可选项，用于运营商代理或兼容的 Gemini API 端点；当省略时，Gemini 网页搜索将复用 models.providers.google.baseUrl。有关 provider 特定工具行为，请参见 Gemini 搜索 页面。

提示：Gemini 3 模型使用 thinkingLevel 而非 thinkingBudget。OpenClaw 将 Gemini 3、Gemini 3.1 和 gemini-*-latest 别名模型的推理控制映射到 thinkingLevel，这样在默认/低延迟运行中不会发送禁用的 thinkingBudget 值。 /think adaptive 会保留 Google 的动态推理语义，而不是选择固定的 OpenClaw 级别。Gemini 3 和 Gemini 3.1 省略固定的 thinkingLevel，以便 Google 自行选择级别；Gemini 2.5 则发送 Google 的动态哨兵值 thinkingBudget: -1。 Gemma 4 模型（例如 gemma-4-26b-a4b-it）支持思考模式。OpenClaw 会将 thinkingBudget 重写为 Gemma 4 所支持的 Google thinkingLevel。将思考模式设置为 off 会保留禁用状态，而非映射到 MINIMAL。

图像生成 ​

内建的 google 图像生成 provider 默认使用 google/gemini-3.1-flash-image-preview。

  • 支持的模型：google/gemini-3.1-flash-image-preview、google/gemini-3-pro-image-preview
  • 生成上限：每次请求最多 4 张图像
  • 编辑模式：已启用，最多可包含 5 张输入图像
  • 几何控制：支持 size、aspectRatio 和 resolution 参数

将 Google 设置为默认图像生成 provider：

json5
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "google/gemini-3.1-flash-image-preview",
      },
    },
  },
}

注意：请参阅 图像生成 页面以了解共享工具参数、provider 选择和故障转移行为。

视频生成 ​

内建的 google 插件还通过共享的 video_generate 工具注册了视频生成功能。

  • 默认视频模型: google/veo-3.1-fast-generate-preview
  • 模式: 支持文本转视频、图像转视频和单视频参考流程
  • 输出控制: 支持 aspectRatio（16:9、9:16）和 resolution（720P、1080P）；目前 Veo 不支持音频输出
  • 支持时长: 4、6 或 8 秒（其他值会就近调整到允许的最接近值）

将 Google 设置为默认视频生成 provider：

json5
{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "google/veo-3.1-fast-generate-preview",
      },
    },
  },
}

注意：请参阅 视频生成 页面以了解共享工具参数、provider 选择和故障转移行为。

音乐生成 ​

内建的 google 插件还通过共享的 music_generate 工具注册了音乐生成功能。

  • 默认音乐模型: google/lyria-3-clip-preview
  • 也可用模型: google/lyria-3-pro-preview
  • 提示控制: lyrics（歌词）和 instrumental（纯器乐）
  • 输出格式: 默认 mp3，google/lyria-3-pro-preview 还支持 wav
  • 参考输入: 最多 10 张图像
  • 会话支持: 基于会话的长运行通过共享的 task/status 流程进行分离，包括使用 action: "status" 进行状态查询。

将 Google 设置为默认音乐生成 provider：

json5
{
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "google/lyria-3-clip-preview",
      },
    },
  },
}

注意：请参阅 音乐生成 页面以了解共享工具参数、provider 选择和故障转移行为。

文本转语音 (TTS) ​

内建的 google 语音 provider 使用 Gemini API 的 TTS 路径，默认模型为 gemini-3.1-flash-tts-preview。

  • 默认语音: Kore
  • 认证方式: messages.tts.providers.google.apiKey > models.providers.google.apiKey > GEMINI_API_KEY > GOOGLE_API_KEY
  • 输出格式:
    • 常规 TTS 附件：WAV
    • 语音备忘录：Opus
    • 通话/电话：PCM
  • 语音备忘录处理：Google PCM 被包装为 WAV 格式，随后通过 ffmpeg 转码为 48 kHz 的 Opus 格式。

Google 的批处理 Gemini TTS 路径会在 generateContent 请求完成后返回生成的音频。对于延迟要求最低的语音对话，建议使用由 Gemini Live API 支持的 Google 实时语音 provider，而非批处理 TTS。

将 Google 设置为默认 TTS provider：

json5
{
  messages: {
    tts: {
      auto: "always",
      provider: "google",
      providers: {
        google: {
          model: "gemini-3.1-flash-tts-preview",
          voiceName: "Kore",
          audioProfile: "Speak professionally with a calm tone.",
        },
      },
    },
  },
}

Gemini API TTS 使用自然语言提示来控制语音风格。设置 audioProfile 可以在朗读文本前预置一个可复用的风格提示。当提示文本中引用了一个具名讲话者时，可设置 speakerName。

Gemini API TTS 还支持在文本中使用方括号包裹的语音标签，例如 [whispers] 或 [laughs]。如果希望这些标签不出现在可见的聊天回复中，但又能发送给 TTS，请将它们放在 [[tts:text]]...[[/tts:text]] 块内：

text
Here is the clean reply text.

[[tts:text]][whispers] Here is the spoken version.[[/tts:text]]

注意：一个限制在 Gemini API 的 Google Cloud 控制台 API 密钥对此 provider 有效。这不是单独的 Cloud Text-to-Speech API 路径。

实时语音 ​

内建的 google 插件注册了一个由 Gemini Live API 支持的实时语音 provider，适用于语音通话和 Google Meet 等后端音频桥接场景。

配置项配置路径默认值
模型plugins.entries.voice-call.config.realtime.providers.google.modelgemini-2.5-flash-native-audio-preview-12-2025
语音...google.voiceKore
温度...google.temperature(未设置)
VAD 开始灵敏度...google.startSensitivity(未设置)
VAD 结束灵敏度...google.endSensitivity(未设置)
静默时长...google.silenceDurationMs(未设置)
活动处理...google.activityHandlingGoogle 默认，start-of-activity-interrupts
轮次控制...google.turnCoverageGoogle 默认，only-activity
禁用自动 VAD...google.automaticActivityDetectionDisabledfalse
会话恢复...google.sessionResumptiontrue
上下文压缩...google.contextWindowCompressiontrue
API 密钥...google.apiKey依次回退到 models.providers.google.apiKey、GEMINI_API_KEY 或 GOOGLE_API_KEY

语音通话实时配置示例：

json5
{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          realtime: {
            enabled: true,
            provider: "google",
            providers: {
              google: {
                model: "gemini-2.5-flash-native-audio-preview-12-2025",
                voice: "Kore",
                activityHandling: "start-of-activity-interrupts",
                turnCoverage: "only-activity",
              },
            },
          },
        },
      },
    },
  },
}

注意：Google Live API 通过 WebSocket 使用双向音频和函数调用。OpenClaw 将电话/Meet 桥接音频适配到 Gemini 的 PCM Live API 流，并在共享的实时语音合约上执行工具调用。除非你需要更改采样参数，否则建议不设 temperature；OpenClaw 会忽略非正值，因为 Google Live 在 temperature: 0 的情况下可能返回无音频的转录文本。Gemini API 转写默认启用，无需 languageCodes 配置；当前的 Google 开发工具包（SDK）在此 API 路径下会拒绝语言代码提示。

注意：控制 UI 的 Talk 功能支持使用有限的一次性令牌进行 Google Live 浏览器会话。仅后端的实时语音 provider 也可以通过通用的 Gateway 中继传输，该方式会将 provider 凭据保留在 Gateway 上。

用于维护者的即时验证命令： 运行 OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts。此烟雾测试也覆盖了 OpenAI 后端/WebRTC 路径；Google 部分会生成与控制 UI Talk 相同形状的受限 Live API 令牌，打开浏览器 WebSocket 端点，发送初始设置包，并等待 setupComplete 信号。

高级配置 ​

直接 Gemini 缓存复用 ​

对于直接的 Gemini API 运行（api: "google-generative-ai"），OpenClaw 会将配置好的 cachedContent 句柄传递给 Gemini 请求。

  • 可在单模型或全局参数中配置 cachedContent 或旧版 cached_content
  • 如果两者都存在，cachedContent 优先
  • 示例值：cachedContents/prebuilt-context
  • Gemini 缓存命中用量会从上游的 cachedContentTokenCount 标准化为 OpenClaw 的 cacheRead 指标
json5
{
  agents: {
    defaults: {
      models: {
        "google/gemini-2.5-pro": {
          params: {
            cachedContent: "cachedContents/prebuilt-context",
          },
        },
      },
    },
  },
}

Gemini CLI JSON 使用说明 ​

当使用 google-gemini-cli OAuth provider 时，OpenClaw 会按以下规则标准化 CLI 的 JSON 输出：

  • 回复文本来自 CLI JSON 的 response 字段
  • 当 CLI 的 usage 字段为空时，用量数据会回退到 stats 字段
  • stats.cached 被标准化为 OpenClaw 的 cacheRead 指标
  • 如果缺少 stats.input，OpenClaw 会通过 stats.input_tokens - stats.cached 推导输入令牌数

环境和守护进程设置 ​

如果 Gateway 以守护进程（launchd/systemd）方式运行，请确保 GEMINI_API_KEY 对该进程可用（例如，配置在 ~/.openclaw/.env 文件中，或通过 env.shellEnv 设置）。

相关链接 ​

  • 模型选择 选择 provider、模型引用和故障转移行为。
  • 图像生成 共享图像工具参数和 provider 选择。
  • 视频生成 共享视频工具参数和 provider 选择。
  • 音乐生成 共享音乐工具参数和 provider 选择。

常见问题 ​

GEMINI_API_KEY 和 GOOGLE_API_KEY 有什么区别，用哪个？ ​

两者都被 OpenClaw 接受，指向同一个 Google AI Studio API。GEMINI_API_KEY 是更新、更明确的名称；GOOGLE_API_KEY 是旧版别名。推荐使用 GEMINI_API_KEY，与 Google 官方文档保持一致。

Gemini Grounding 网页搜索的 credential 优先级是什么？ ​

优先级为：专用 webSearch.apiKey > GEMINI_API_KEY > models.providers.google.apiKey。webSearch.baseUrl 是可选的，当省略时，Gemini 网页搜索会复用 models.providers.google.baseUrl。

视频生成时长为什么有 4、6、8 秒的限制？ ​

这是 Veo 当前 API 的限制（仅支持 4、6、8 秒），由 Google 侧决定，OpenClaw 直接透传。如果输入其他时长，系统会就近调整到允许的最接近值。如需更长视频，可借助外部工具将多个片段拼接，或持续关注 Google 后续 API 更新。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策