提供商

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 访问。

获取 API 密钥

在 Google AI Studio 中创建免费密钥。

运行新手引导

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

配置 API 密钥后，OpenClaw 会从 Gemini models.list API 刷新 Google AI Studio 的文本模型目录。因此，新发布的 Gemini 3 Pro、Flash 和 Flash-Lite 变体会出现在 openclaw models list --provider google 中，无需等待 OpenClaw 发布新版本。如果无法进行设备发现，OpenClaw 会保留内置的后备目录。

Gemini CLI (OAuth)

**最适合：**通过 Gemini CLI OAuth 登录 Google 账户，而不使用单独的 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

新手引导自动检测会列出现有的 Gemini CLI 登录，但绝不会自动测试它，因为 Gemini CLI 没有无工具探测方式。请选择 Gemini CLI OAuth 或 Gemini API 密钥以继续。

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；OpenClaw 会从 Gemini 2.5 Pro 请求中移除该值，而不是发送它。

图像生成

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

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

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

json5

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

视频生成

内置的 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-3.1-flash-tts-preview 使用 Gemini API TTS 路径。

默认语音：Kore
身份验证：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

{  tts: {    auto: "always",    provider: "google",    providers: {      google: {        model: "gemini-3.1-flash-tts-preview",        speakerVoice: "Kore",        audioProfile: "以平静的语气专业地说话。",      },    },  },}

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 支持的实时语音提供商，用于语音通话和 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`

语音通话实时配置示例：

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 端点，发送初始设置载荷和一个 JPEG 帧，并验证文本响应和 describe_view 函数往返调用。

高级配置

直接复用 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 密钥

获取 API 密钥

运行新手引导

设置默认模型

验证模型是否可用

Gemini CLI (OAuth)

安装 Gemini CLI

通过 OAuth 登录

验证模型是否可用

能力

Web 搜索

图像生成

视频生成

音乐生成

文本转语音

实时语音

高级配置

相关内容

On this page

Molty