快速开始

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/*。

入门指南

选择你偏好的身份验证方式，然后按照设置步骤操作。

API 密钥

**最适合：**通过 Google AI Studio 进行标准 Gemini API 访问。

运行新手引导

bash

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

或直接传入密钥：

bash

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

设置默认模型

json5

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

验证模型是否可用

bash

openclaw models list --provider google

Gemini CLI (OAuth)

**最适合：**通过 PKCE OAuth 复用现有 Gemini CLI 登录，而无需单独的 API 密钥。

安装 Gemini CLI

本地 gemini 命令必须在 PATH 中可用。

bash

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

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

通过 OAuth 登录

bash

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

验证模型是否可用

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，并会在调用提供商前将其规范化。

环境变量：

OPENCLAW_GEMINI_OAUTH_CLIENT_ID / GEMINI_CLI_OAUTH_CLIENT_ID
OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET / GEMINI_CLI_OAUTH_CLIENT_SECRET

google-gemini-cli/* 模型引用是旧版兼容别名。需要本地 Gemini CLI 执行的新配置应使用 google/* 模型引用，并搭配 google-gemini-cli 运行时。

能力

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

Web 搜索

内置的 gemini Web 搜索提供商使用 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 Web 搜索会复用 models.providers.google.baseUrl。有关提供商特定的工具行为，请参阅 Gemini 搜索。

Tip

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。

Gemini 2.5 Pro 只能在思考模式下工作，并会拒绝显式的 thinkingBudget: 0；对于 Gemini 2.5 Pro 请求，OpenClaw 会移除该值，而不是发送它。

图像生成

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

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

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

json5

{  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 用作默认视频提供商：

json5

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

json5

{  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 提供商：

json5

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

text

这是简洁的回复文本。 [[tts:text]][whispers] 这是朗读版本。[[/tts:text]]

实时语音

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

设置	配置路径	默认值
模型	`plugins.entries.voice-call.config.realtime.providers.google.model`	`gemini-3.1-flash-live-preview`
语音	`...google.voice`	`Kore`
温度	`...google.temperature`	（未设置）
VAD 开始灵敏度	`...google.startSensitivity`	（未设置）
VAD 结束灵敏度	`...google.endSensitivity`	（未设置）
静音持续时间	`...google.silenceDurationMs`	（未设置）
活动处理	`...google.activityHandling`	Google 默认值，`start-of-activity-interrupts`
轮次覆盖范围	`...google.turnCoverage`	Google 默认值，`audio-activity-and-all-video`
禁用自动 VAD	`...google.automaticActivityDetectionDisabled`	`false`
会话恢复	`...google.sessionResumption`	`true`
上下文压缩	`...google.contextWindowCompression`	`true`
API 密钥	`...google.apiKey`	回退到 `models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`

Voice Call 实时配置示例：

json5

{  plugins: {    entries: {      "voice-call": {        enabled: true,        config: {          realtime: {            enabled: true,            provider: "google",            providers: {              google: {                model: "gemini-3.1-flash-live-preview",                speakerVoice: "Kore",                activityHandling: "start-of-activity-interrupts",                turnCoverage: "audio-activity-and-all-video",              },            },          },        },      },    },  },}

如需供维护者进行实时验证，请运行 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。

高级配置

直接复用 Gemini 缓存

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

使用 cachedContent 或旧版 cached_content 配置每个模型或全局参数
更具体作用域中的参数（模型级优先于全局级）始终优先。在同一作用域内，如果两个键都已设置，则 cached_content 优先。每个作用域只使用一个键，以免出现意外。
示例值：cachedContents/prebuilt-context
Gemini 缓存命中的用量会从上游 cachedContentTokenCount 规范化为 OpenClaw cacheRead

json5

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

Gemini CLI 使用说明

使用 google-gemini-cli OAuth 提供商时，OpenClaw 默认使用 Gemini CLI 的 stream-json 输出，并根据最终的 stats 载荷规范化用量。旧版 --output-format json 覆盖设置仍使用 JSON 解析器。

流式回复文本来自助手的 message 事件。
对于旧版 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 提供）。

Google（Gemini）

入门指南

API 密钥

运行新手引导

设置默认模型

验证模型是否可用

Gemini CLI (OAuth)

安装 Gemini CLI

通过 OAuth 登录

验证模型是否可用

能力

Web 搜索

图像生成

视频生成

音乐生成

文本转语音

实时语音

高级配置

相关内容

On this page

Molty