Google (Gemini)

Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，并支持图像生成、媒体理解（图像/音频/视频）、文本转语音，以及通过 Gemini Grounding 进行 Web 搜索。

• 提供商：google
• 凭证：GEMINI_API_KEY 或 GOOGLE_API_KEY
• API：Google Gemini API
• 运行时选项：agentRuntime.id: "google-gemini-cli" 会复用 Gemini CLI OAuth，同时保持模型引用规范为 google/*。

入门指南

选择你偏好的凭证方式并按设置步骤操作。

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

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

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

openclaw models list --provider google

# Homebrewbrew install gemini-cli # or npmnpm install -g @google/gemini-cli

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

openclaw models list --provider google

能力

Web 搜索

内置的 gemini Web 搜索提供商使用 Gemini Google Search grounding。请在 plugins.entries.google.config.webSearch 下配置专用搜索密钥，或让它在 GEMINI_API_KEY 之后复用 models.providers.google.apiKey：

{  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", // falls back to models.providers.google.baseUrl            model: "gemini-2.5-flash",          },        },      },    },  },}

凭证优先级依次为专用 webSearch.apiKey、GEMINI_API_KEY，然后是 models.providers.google.apiKey。webSearch.baseUrl 是可选项，供操作员代理或兼容的 Gemini API 端点使用；省略时，Gemini Web 搜索会复用 models.providers.google.baseUrl。有关提供商特定的工具行为，请参阅 Gemini 搜索。

图像生成

内置的 google 图像生成提供商默认使用 google/gemini-3.1-flash-image-preview。

• 还支持 google/gemini-3-pro-image-preview
• 生成：每次请求最多 4 张图像
• 编辑模式：已启用，最多 5 张输入图像
• 几何控制：size、aspectRatio 和 resolution

要将 Google 用作默认图像提供商：

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

视频生成

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

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

要将 Google 用作默认视频提供商：

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

音乐生成

内置的 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 用作默认音乐提供商：

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

文本转语音

内置的 google 语音提供商使用 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，Talk/电话场景使用 PCM
• 语音便签输出：Google PCM 会被包装为 WAV，并通过 ffmpeg 转码为 48 kHz Opus

Google 的批量 Gemini TTS 路径会在完成的 generateContent 响应中返回生成的音频。对于最低延迟的语音对话，请使用由 Gemini Live API 支持的 Google 实时语音提供商，而不是批量 TTS。

要将 Google 用作默认 TTS 提供商：

{  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]] 块中：

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

实时语音

内置的 google 插件注册了一个由 Gemini Live API 支持的实时语音提供商，用于 Voice Call 和 Google Meet 等后端音频桥接。

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",              },            },          },        },      },    },  },}

对于维护者实时验证，请运行 OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts。 该冒烟测试也覆盖 OpenAI 后端/WebRTC 路径；Google 分支会签发与 Control UI Talk 使用的相同受约束 Live API 令牌形态，打开浏览器 WebSocket 端点，发送初始设置载荷，并等待 setupComplete。

高级配置

{  agents: {    defaults: {      models: {        "google/gemini-2.5-pro": {          params: {            cachedContent: "cachedContents/prebuilt-context",          },        },      },    },  },}

相关内容