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 密钥
Gemini CLI (OAuth)

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

获取 API 密钥

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

运行新手引导

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

GEMINI_API_KEY 和 GOOGLE_API_KEY 均可使用。使用已配置的任意一个即可。

配置 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 登录 Google 账户，而不使用单独的 API 密钥。

google-gemini-cli 提供商是非官方集成。一些用户报告称，以这种方式使用 OAuth 时遇到了账户限制。使用风险自负。

安装 Gemini CLI

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

# Homebrew
brew install gemini-cli

# 或 npm
npm install -g @google/gemini-cli

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

通过 OAuth 登录

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

验证模型是否可用

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 OAuth 请求失败，请在 Gateway 网关主机上设置 GOOGLE_CLOUD_PROJECT 或 GOOGLE_CLOUD_PROJECT_ID，然后重试。

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

新手引导自动检测会列出现有的 Gemini CLI 登录，但绝不会自动测试它，因为 Gemini CLI 没有无工具探测方式。请选择 Gemini CLI OAuth 或 Gemini API 密钥以继续。google-gemini-cli/* 模型引用是旧版兼容别名。新配置如需在本地执行 Gemini CLI，应使用 google/* 模型引用和 google-gemini-cli 运行时。

google/gemini-3-pro-preview 已于 2026-03-09 停用；请改用 google/gemini-3.1-pro-preview。重新运行 Gemini API 密钥设置（openclaw onboard --auth-choice gemini-api-key 或 openclaw models auth login --provider google）会将过时的已配置默认值重写为当前模型。

能力

能力	支持
聊天补全	是
图像生成	是
音乐生成	是
文本转语音	是
实时语音	是（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：

{
  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 搜索。

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 用作默认图像提供商：

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

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

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

这是简洁的回复文本。

[[tts:text]][whispers] 这是朗读版本。[[/tts:text]]

限制为 Gemini API 的 Google Cloud Console API 密钥对此提供商有效。这不是单独的 Cloud Text-to-Speech API 路径。

实时语音

内置的 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`

语音通话实时配置示例：

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

Google Live API 通过 WebSocket 使用双向音频和函数调用。 OpenClaw 将电话/Meet 桥接音频适配到 Gemini 的 PCM Live API 流，并将工具调用保留在共享的实时语音契约中。除非需要更改采样，否则不要设置 temperature；OpenClaw 会忽略非正值，因为对于 temperature: 0，Google Live 可能返回转录文本但不返回音频。无需 languageCodes 即可启用 Gemini API 转录；当前 Google SDK 会拒绝此 API 路径上的语言代码提示。

Gemini 3.1 Live 通过实时输入接受对话文本，并使用顺序函数调用。对于此模型，OpenClaw 会忽略旧版 NON_BLOCKING、函数响应调度和情感对话字段。优先使用 thinkingLevel；已配置的正 thinkingBudget 值会映射到最接近的受支持级别，而 -1 会保留 Google 的默认设置。请参阅 Gemini Live 能力对比。

Control UI Talk 支持使用受限一次性令牌的 Google Live 浏览器会话。在 Video Talk 中，浏览器以提供商规定的每秒最多一帧速率，将限定大小的 JPEG 帧直接发送到 Google Live。describe_view 函数会报告该摄像头流是否处于活动状态。摄像头帧不会经过 Gateway 网关。仅支持后端的实时语音提供商也可通过通用 Gateway 网关中继传输运行，从而将提供商凭据保留在 Gateway 网关上。

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

{
  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）

入门指南

能力

Web 搜索

图像生成

视频生成

音乐生成

文本转语音

实时语音

高级配置

相关内容

模型选择

图像生成

视频生成

音乐生成

​入门指南

​能力

​Web 搜索

​图像生成

​视频生成

​音乐生成

​文本转语音

​实时语音

​高级配置

​相关内容

模型选择

图像生成

视频生成

音乐生成

入门指南

能力

Web 搜索

图像生成

视频生成

音乐生成

文本转语音

实时语音

高级配置

相关内容