Skip to main content
Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，并通过 Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）、文本转语音和网页搜索。
  • Provider: google
  • Auth: GEMINI_API_KEY or GOOGLE_API_KEY
  • API: Google Gemini API
  • Runtime option: provider/model agentRuntime.id: "google-gemini-cli" 复用 Gemini CLI OAuth，同时保持模型引用规范为 google/*。

​
开始使用

选择你偏好的身份验证方式并按照设置步骤操作。
最佳适用场景： 通过 Google AI Studio 进行标准 Gemini API 访问。
1

运行引导

openclaw onboard --auth-choice gemini-api-key
或直接传入密钥：
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY"
2

设置默认模型

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

验证模型是否可用

openclaw models list --provider google
环境变量 GEMINI_API_KEY 和 GOOGLE_API_KEY 都可以接受。请使用你已经配置好的那个。

​
功能支持

功能支持情况
Chat completions是
Image generation是
Music generation是
Text-to-speech是
Realtime voice是（Google Live API）
Image understanding是
Audio transcription是
Video understanding是
Web search (Grounding)是
Thinking/reasoning是（Gemini 2.5+ / Gemini 3+）
Gemma 4 models是
捆绑的 gemini 网页搜索 provider 使用 Gemini Google Search grounding。 在 plugins.entries.google.config.webSearch 下配置专用搜索密钥， 或者让它在 GEMINI_API_KEY 后复用 models.providers.google.apiKey： 
{
  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。参见 Gemini search 了解 provider 特定的工具行为。
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-pro-image-preview
  • 生成：每次请求最多 4 张图片
  • 编辑模式：已启用，最多 5 张输入图片
  • 形状控制：size、aspectRatio 和 resolution
要将 Google 设为默认图像 provider： 
{
  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： 
{
  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 张图片
  • 基于会话的运行会通过共享的任务/状态流程进行分离，包括 action: "status"
要将 Google 设为默认音乐 provider： 
{
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "google/lyria-3-clip-preview",
      },
    },
  },
}
共享工具参数、provider 选择和故障切换行为请参见 音乐生成。

​
文本转语音

内置的 google 语音 provider 使用 Gemini API 的 TTS 路径， 并采用 gemini-3.1-flash-tts-preview。
  • 默认语音: Kore
  • Auth: messages.tts.providers.google.apiKey、models.providers.google.apiKey、GEMINI_API_KEY 或 GOOGLE_API_KEY
  • 输出：常规 TTS 附件为 WAV，语音便笺目标为 Opus，Talk/电话场景为 PCM
  • 语音便笺输出：Google PCM 会被包装为 WAV，并通过 ffmpeg 转码为 48 kHz Opus
Google 的批量 Gemini TTS 路径会在完成的 generateContent 响应中返回生成的音频。 对于最低延迟的语音对话，请使用由 Gemini Live API 支持的 Google 实时语音 provider， 而不是批量 TTS。 要将 Google 设为默认 TTS provider： 
{
  messages: {
    tts: {
      auto: "always",
      provider: "google",
      providers: {
        google: {
          model: "gemini-3.1-flash-tts-preview",
          speakerVoice: "Kore",
          audioProfile: "Speak professionally with a calm tone.",
        },
      },
    },
  },
}
Gemini API TTS 使用自然语言提示来控制风格。将 audioProfile 设置为在朗读文本之前附加一个可复用的风格提示。当前提示文本中提到特定姓名说话人时，设置 speakerName。 Gemini API TTS 还接受文本中的带方括号的富有表现力音频标签，例如 [whispers] 或 [laughs]。若要在发送给 TTS 的同时让这些标签不出现在可见聊天回复中，请将它们放入 [[tts:text]]...[[/tts:text]] 块中： 
这里是干净的回复文本。

[[tts:text]][whispers] 这里是朗读版本。[[/tts:text]]
受限于 Gemini API 的 Google Cloud Console API key 对此 provider 是有效的。这不是独立的 Cloud Text-to-Speech API 路径。

​
实时语音

内置的 google 插件注册了一个由 Gemini Live API 支持的实时语音 provider，用于后端音频桥接，例如 Voice Call 和 Google Meet。
设置配置路径默认值
Modelplugins.entries.voice-call.config.realtime.providers.google.modelgemini-2.5-flash-native-audio-preview-12-2025
Voice...google.voiceKore
Temperature...google.temperature(unset)
VAD start sensitivity...google.startSensitivity(unset)
VAD end sensitivity...google.endSensitivity(unset)
Silence duration...google.silenceDurationMs(unset)
Activity handling...google.activityHandlingGoogle default, start-of-activity-interrupts
Turn coverage...google.turnCoverageGoogle default, only-activity
Disable auto VAD...google.automaticActivityDetectionDisabledfalse
Session resumption...google.sessionResumptiontrue
Context compression...google.contextWindowCompressiontrue
API key...google.apiKey回退到 models.providers.google.apiKey、GEMINI_API_KEY 或 GOOGLE_API_KEY
Voice Call 实时配置示例： 
{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          realtime: {
            enabled: true,
            provider: "google",
            providers: {
              google: {
                model: "gemini-2.5-flash-native-audio-preview-12-2025",
                speakerVoice: "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 路径上的语言代码提示。
Control UI Talk 支持带受限一次性令牌的 Google Live 浏览器会话。 仅后端的实时语音 provider 也可以通过通用的 Gateway relay transport 运行，这会将 provider 凭据保留在 Gateway 上。
对于维护者的实时验证，请运行 OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts. 该 smoke 也覆盖 OpenAI 后端/WebRTC 路径；Google 这一路会签发与 Control UI Talk 使用的相同 受限 Live API 令牌形状，打开浏览器 WebSocket 端点，发送初始设置负载，并等待 setupComplete。

​
高级配置

对于直接的 Gemini API 运行（api: "google-generative-ai"），OpenClaw 会将已配置的 cachedContent 句柄传递给 Gemini 请求。
  • 可使用 cachedContent 或旧版 cached_content 配置按模型或全局参数
  • 如果两者都存在，则以 cachedContent 为准
  • 示例值：cachedContents/prebuilt-context
  • Gemini 缓存命中用量会从上游 cachedContentTokenCount 归一化为 OpenClaw 的 cacheRead
{
  agents: {
    defaults: {
      models: {
        "google/gemini-2.5-pro": {
          params: {
            cachedContent: "cachedContents/prebuilt-context",
          },
        },
      },
    },
  },
}
使用 google-gemini-cli OAuth 提供方时，OpenClaw 会按如下方式 规范化 CLI JSON 输出：
  • 回复文本来自 CLI JSON 的 response 字段。
  • 当 CLI 将 usage 留空时，使用 stats 作为回退。
  • stats.cached 会被归一化为 OpenClaw 的 cacheRead。
  • 如果 stats.input 缺失，OpenClaw 会从 stats.input_tokens - stats.cached 推导输入 token 数。
如果 Gateway 以守护进程方式运行（launchd/systemd），请确保 GEMINI_API_KEY 对该进程可用（例如，放在 ~/.openclaw/.env 中或通过 env.shellEnv 提供）。

​
相关内容

模型选择

选择提供方、模型引用以及故障切换行为。

图像生成

共享的图像工具参数和提供方选择。

视频生成

共享的视频工具参数和提供方选择。

音乐生成

共享的音乐工具参数和提供方选择。