Google (Gemini)

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

• 提供商：google
• 认证：GEMINI_API_KEY 或 GOOGLE_API_KEY
• API：Google Gemini API
• 托管云提供商：google-vertex，使用 Google Cloud Application Default Credentials
• 可选运行时：agentRuntime.id: "google-gemini-cli" 通过本地 Gemini CLI 运行显式配置的模型

快速开始¶

对于大多数安装，请使用 Google AI Studio API 密钥。当 Gateway 已经运行在托管的 Google Cloud 环境中时，使用 google-vertex。

**推荐用于：** 标准 Gemini API 访问。

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

openclaw onboard --non-interactive --accept-risk --skip-health \
  --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 CLI 运行规范的 `google/*` 模型，同时保持认证使用受支持的 AI Studio API 密钥路径。

OpenClaw 不提供新的 Gemini CLI OAuth 或 Antigravity OAuth 设置。
[Google 已于 2026 年 6 月 18 日终止消费者 Gemini CLI 的 Login with Google 访问](https://developers.google.com/gemini-code-assist/docs/deprecations/code-assist-individuals)，
并且 [Antigravity 条款](https://antigravity.google/terms) 禁止
第三方工具通过 Antigravity OAuth 访问该服务。请改用
AI Studio API 密钥或 Vertex AI。

# Homebrew
brew install gemini-cli

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

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

- 运行时：`google-gemini-cli`
- 认证：所选 Google AI Studio API 密钥配置
- 模型引用：规范的 `google/*`

`google-gemini-cli` 是内置 Google 插件注册的 CLI 后端。
有关其 argv、JSONL 方言以及会话和压缩行为，以及所有已注册后端共享的设置，请参阅 [CLI 后端](../gateway/cli-backends.md)。

现有有效的 Gemini CLI OAuth 配置出于兼容性原因仍可执行，
但 OpenClaw 无法创建或修复它们。如果某个配置损坏，请将其替换为
Google AI Studio API 密钥配置。

`google-gemini-cli/*` 引用仍为遗留兼容别名。新配置
应使用 `google/*` 模型引用加上上述显式运行时选择。

功能¶

网络搜索¶

内置的 gemini 网络搜索提供商使用 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-3.6-flash",
          },
        },
      },
    },
  },
}

凭据优先级依次为专用的 webSearch.apiKey，然后是 GEMINI_API_KEY，再然后是 models.providers.google.apiKey。webSearch.baseUrl 是可选的，用于运营商代理或兼容的 Gemini API 端点；省略时，Gemini 网络搜索会复用 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: {
      mediaModels: {
        image: {
          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: {
      mediaModels: {
        video: {
          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: {
      mediaModels: {
        music: {
          primary: "google/lyria-3-clip-preview",
        },
      },
    },
  },
}

文本转语音¶

内置的 google 语音提供方使用 Gemini API TTS。默认模型 保持为 gemini-3.1-flash-tts-preview。将 model 设置为 gemini-3.8-flash-tts 可选择加入 Gemini 3.8，或设置为 gemini-3.8-flash-lite-tts 使用更快、成本更低的变体。gemini-2.5-flash-preview-tts 和 gemini-2.5-pro-preview-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

OpenClaw 通过 Interactions API （POST /v1beta/interactions）发送 Gemini 3.8 TTS，并设置 store: false。Google 也在 generateContent 中记录了 3.8；Interactions 是 OpenClaw 的路由选择，而不是模型要求。OpenClaw 请求无文件头的 24 kHz PCM（audio/l16），并仍在本地封装该 PCM。audioProfile 和 personaPrompt 作为 speech_metadata.style 发送，speakerName 作为结构化的 speaker 标签发送，它们都不会作为转录文本的一部分被朗读。3.8 的短暂语音标签使用尖括号，例如 <laugh> 或 <short pause>；持续性的表达方式（如耳语）应放在 audioProfile 中。

将 speakers 设置为恰好两个 { speaker, voice, style? } 条目，即可演绎对话。只有以这两个名称之一开头并后跟冒号的行才会开始一个回合（Puck: Hello 和 Puck:Hello 都算），并且名称不会被朗读。其他所有行都会作为当前回合的一部分被朗读，包括普通带冒号前缀的文本（例如 Budget: 10 dollars）以及任何未配置的标签（例如 Alice: Hi）。第一个标签之前的词语由该第一个说话者朗读，而不是被丢弃。没有配置任何标签的转录文本仍走单声音路径。多说话者对话需要 gemini-3.8-flash-tts 或 gemini-3.8-flash-lite-tts。

Puck: Headphones on. <laugh> We opened it.
Kore: It is waiting at the maintainer gate.

Gemini 3.1 和 2.5 预览版 TTS 仍使用 generateContent。这些模型保留旧行为：audioProfile 会被前置到转录文本中，并且表现力标签使用方括号，例如 [whispers]。未知的 gemini-3.8-*-tts id 会失败关闭，而不是被发送到 generateContent。

对于最低延迟的语音对话，请使用由 Gemini Live API 支持的 Google 实时语音提供商，而不是批量 TTS。

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

{
  tts: {
    auto: "always",
    provider: "google",
    providers: {
      google: {
        model: "gemini-3.8-flash-tts",
        speakerVoice: "Kore",
        audioProfile: "Speak professionally with a calm tone.",
        speakers: [
          { speaker: "Puck", voice: "Puck", style: "bright" },
          { speaker: "Kore", voice: "Kore", style: "whispered" },
        ],
      },
    },
  },
}

Gemini API TTS 使用自然语言提示来控制风格。设置 audioProfile 以定义可复用的播报风格。在 Gemini 3.8 中，该风格是 speech_metadata.style，不会被朗读。在 Gemini 3.1 和 2.5 预览模型中，它仍会被前置到朗读文本中。当表演需要指定说话者时，设置 speakerName；3.8 会将其作为结构化 speech_metadata.speaker 标签发送，绝不会作为风格文本，并且所选语音保持为唯一配置的语音。

Gemini 3.1 和 2.5 预览 TTS 接受文本中的表情方括号音频标签，例如 [whispers] 或 [laughs]。Gemini 3.8 则改用尖括号语音标签，例如 <laugh>。为了在将标签发送到 TTS 的同时避免它们出现在可见的聊天回复中，请将它们放在 [[tts:text]]...[[/tts:text]] 块内：

Here is the clean reply text.

[[tts:text]]<laugh> Here is the spoken version. <short pause> Enjoy.[[/tts:text]]

实时语音¶

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

Talk 和 Discord 会在其语音目录中展示 Google 的预置语音。在活跃的 Talk 或 Discord 通话中，使用 talk_voice 选择新语音。OpenClaw 会使用该语音重新连接，同时保留对话和未完成的代理工作；已保存的语音默认值保持不变。参见 Discord 语音更改。

Voice Call 实时配置示例：

{
  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 函数往返。 OpenAI 路径还会执行一次合成的 PCM24 语音到响应音频往返；传入 --openai-audio-cycles 3 可进行简短的重复生命周期浸泡测试。

高级配置¶

{
  models: {
    mode: "merge",
    providers: {
      "google-interactions": {
        baseUrl: "https://generativelanguage.googleapis.com/v1beta",
        apiKey: "***",
        api: "google-interactions",
        models: [
          {
            id: "gemini-3.8-flash",
            name: "Gemini 3.8 Flash (Interactions)",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 1048576,
            maxTokens: 65536,
          },
        ],
      },
    },
  },
  agents: {
    defaults: { model: { primary: "google-interactions/gemini-3.8-flash" } },
  },
}

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

相关¶

模型选择

选择提供商、模型引用和故障转移行为。

图像生成

共享图像工具参数和提供商选择。

视频生成

共享视频工具参数和提供商选择。

音乐生成

共享音乐工具参数和提供商选择。

CLI 后端

Gemini CLI 后端设置和运行时详细信息。

语音通话插件

使用 Gemini Live 实时语音提供商的音频桥接。