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 中创建免费密钥。

运行新手引导

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

配置 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 上可用。

# 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 登录，但绝不会自动测试它，因为 Gemini CLI 没有无工具探测方式。请选择 Gemini CLI OAuth 或 Gemini API 密钥以继续。

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

能力

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

图像生成

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

实时语音

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

语音通话实时配置示例：

{
  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 函数往返调用。

高级配置

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

相关内容

• 模型选择：选择提供商、模型引用和故障转移行为。
• 图像生成：共享图像工具参数和提供商选择。
• 视频生成：共享视频工具参数和提供商选择。
• 音乐生成：共享音乐工具参数和提供商选择。