Google (Gemini)
Google 插件可通过 Google AI Studio 访问 Gemini 模型,并提供图像生成、媒体理解(图像/音频/视频)、文本转语音,以及通过 Gemini Grounding 进行的网络搜索。
- 提供商:
google - 身份验证:
GEMINI_API_KEY或GOOGLE_API_KEY - API:Google Gemini API
- 托管云提供商:
google-vertex,使用 Google Cloud 应用默认凭据 - 可选运行时:
agentRuntime.id: "google-gemini-cli"通过本地 Gemini CLI 运行显式配置的模型
快速开始¶
对于大多数安装,请使用 Google AI Studio API 密钥。当 Gateway 已在托管的 Google Cloud 环境中运行时,请使用 google-vertex。
**推荐用于:**标准 Gemini API 访问。
1. 获取 API 密钥
在 Google AI Studio 中创建一个免费密钥。
2. 运行入门配置
或直接传入密钥:
openclaw onboard --non-interactive --accept-risk --skip-health \
--mode local \
--auth-choice gemini-api-key \
--gemini-api-key "$GEMINI_API_KEY"
3. 设置默认模型
4. 验证模型可用
Tip
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 发布。刷新失败时会报告失败,并保留最后一次成功的清单,或在首次成功之前保留捆绑的模型。成功的空响应会清除已发现的模型。Vertex 使用其独立的静态目录。
**推荐用于:**运行在 Google Cloud(GCE、GKE、Cloud Run)内的 Gateway 实例,或已通过 gcloud 应用默认凭据完成身份验证的工作站。
1. 使用 gcloud ADC 进行身份验证
在工作站上,运行:
对于已附加服务账号的 Google Cloud 虚拟机,元数据服务器已提供凭据,无需文件。
2. 设置项目和位置
两者在 Gateway 服务环境中均为必需:
GCLOUD_PROJECT 也可用于项目。如果没有项目,运行将失败,错误为 Vertex AI requires a project ID. Set GOOGLE_CLOUD_PROJECT/GCLOUD_PROJECT or pass project in options.
如果没有位置,错误为 Vertex AI requires a location. Set GOOGLE_CLOUD_LOCATION or pass location in options.
3. 凭据:自动发现或手动哨兵值
如果存在可识别的 ADC 文件(由
`gcloud auth application-default login` 创建)**并且**已设置项目和
位置变量,OpenClaw 会自动发现 `google-vertex`
——无需存储任何内容。
仅当凭据仅为元数据(例如已附加服务账号且磁盘上没有 ADC 文件的
GCE 虚拟机)或需要显式选择 ADC 路径时,才需要手动存储。ADC 路径通过
哨兵值选择,而不是真实密钥——请精确存储
`gcp-vertex-credentials`:
```bash
openclaw models auth paste-api-key --provider google-vertex
# paste exactly: gcp-vertex-credentials
```
Warning
其他存储的值会通过 x-goog-api-key 请求头发送,而不是作为
ADC 凭据。请勿粘贴来自
gcloud auth print-access-token 的 OAuth 访问令牌:它不是 API 密钥,并可能导致
401 UNAUTHENTICATED 等身份验证错误。
4. 列出 Vertex 目录
--all 会包含您尚未配置的模型。--refresh 会在
本地目录尚未加载时填充本地目录;它不会查询
实时的 Vertex 模型清单,也不会验证 ADC 能否获取令牌。
Tip
Vertex 使用独立的静态模型目录;新的 Gemini 变体会 随 OpenClaw 发布出现在其中,而不是通过 AI Studio 密钥路径使用的 实时刷新出现。
**仅限高级使用:**通过已安装的
Gemini CLI 运行标准的 `google/*` 模型,同时保持身份验证使用受支持的 AI Studio API 密钥
路径。
OpenClaw 不提供新的 Gemini CLI OAuth 或 Antigravity OAuth 设置。
[Google 已于 2026 年 6 月 18 日终止面向消费者的 Gemini CLI 使用 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。
1. 配置 Google AI Studio
完成第一个选项卡中的 API 密钥设置。在选择 CLI 运行时时,OpenClaw 必须已有可用的
google API 密钥配置。
2. 安装 Gemini CLI
本地 gemini 命令必须在 PATH 中可用。
OpenClaw 同时支持 Homebrew 安装和全局 npm 安装,包括 常见的 Windows/npm 布局。
3. 选择 CLI 运行时
保留规范的 Google 模型引用,并将该模型选择为 CLI 运行时:
```json5
{
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/*` 模型引用,并加上上述显式运行时选择。
Note
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) |
| 图像理解 | 是 |
| 音频转录 | 是 |
| 视频理解 | 是 |
| 网络搜索(Grounding) | 是 |
| 思考/推理 | 是(Gemini 2.5+ / Gemini 3+) |
| Gemma 4 模型 | 是 |
标记为 MAX_TOKENS 或 CONTINUATION 的响应已达到生成限制。
OpenClaw 会保留其部分内容,并报告一个受长度限制的结果。
该部分响应中的函数调用将保持不完整,而不会变成
可执行的工具使用轮次。
网络搜索¶
捆绑的 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 搜索 了解提供商特定的工具行为。
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)支持思考模式。对于 Gemma 4,
OpenClaw 会将 thinkingBudget 重写为受支持的 Google thinkingLevel。
将思考设置为 off 会保持思考禁用,而不是映射到
MINIMAL。
Gemini 2.5 Pro 仅在思考模式下工作,并拒绝显式的
thinkingBudget: 0;对于 Gemini 2.5 Pro 请求,OpenClaw 会移除该值,
而不是发送它。
图像生成¶
捆绑的 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",
},
},
},
},
}
Note
有关共享工具参数、提供商选择和故障转移行为,请参阅 图像生成。
视频生成¶
捆绑的 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",
},
},
},
},
}
Note
有关共享工具参数、提供商选择和故障转移行为,请参阅 视频生成。
音乐生成¶
内置的 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",
},
},
},
},
}
Note
参见 音乐生成 了解共享工具参数、提供商选择和故障转移行为。
文本转语音¶
内置的 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。
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]]
Note
仅限 Gemini API 的 Google Cloud Console API 密钥对此提供商有效。这不是单独的 Cloud Text-to-Speech API 路径。
实时语音¶
内置的 google 插件注册了一个由 Gemini Live API 支持的实时语音提供商,用于 Voice Call 和 Google Meet 等后端音频桥接。
Talk 和 Discord 在其语音目录中展示 Google 的预置语音。在活跃的 Talk 或 Discord 通话期间,使用 talk_voice 选择新语音。OpenClaw 会使用该语音重新连接,同时保留对话和未完成的代理工作;已保存的语音默认值保持不变。参见 Discord 语音更改。
| 设置 | 配置路径 | 默认值 |
|---|---|---|
| 模型 | 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",
},
},
},
},
},
},
},
}
Note
Google Live API 使用基于 WebSocket 的双向音频和函数调用。
OpenClaw 将电话/Meet 桥接音频适配为 Gemini 的 PCM Live API 流,
并将工具调用保持在共享的实时语音契约上。除非需要更改采样,否则保持
temperature 未设置;OpenClaw 会省略非正值,因为对于 temperature: 0,
Google Live 可能返回没有音频的转录文本。
Gemini API 转录在未设置 languageCodes 的情况下启用;当前 Google
SDK 在此 API 路径上拒绝语言代码提示。
Note
Gemini 3.1 Live 通过实时输入接受会话文本,并使用顺序函数调用。OpenClaw 会省略该模型的旧版 NON_BLOCKING、函数响应调度和情感对话字段。优先使用
thinkingLevel;配置的正值 thinkingBudget 会映射到最近的支持级别,而 -1 会保留 Google 的默认设置。参见
Gemini Live 功能比较。
Note
Gemini 3.8 Live(gemini-3.8-live)保留异步函数调用契约,并拒绝任何思考配置,因此 OpenClaw 不会为其发送任何配置。Gemini 3.8 Live Extended
Thinking(gemini-3.8-live-extended-thinking)要求使用 NON_BLOCKING 工具,拒绝函数响应调度,并在临时响应后放弃调用,因此 OpenClaw
每次代理咨询只发送一个最终结果,而不发送“工作中”临时结果。使用
thinkingLevel(low、medium 或 high;minimal 映射到
low)配置其推理深度,或使用映射到最近级别的正值 thinkingBudget。在交互仍在进行时,口头填充词具有自己的语句边界;OpenClaw 会最终确定该
转录文本和音频,但保持响应处于活动状态,直到 Google 报告交互为空闲。在此模型上,显式停止或打断会通过一个简短的客户端内容轮次中断生成,该轮次
告知模型它已被打断(空轮次会使其恢复)。取消当前生成是可靠的,但随后的静音是尽力而为的:模型仍可能恢复或开始另一个响应,因此将停止视为“停止此回复”,而不是保证
静音。其他 Gemini Live 模型仅通过服务器端语音活动检测进行打断。参见
Gemini 3.8 Live 思考指南。
Note
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 函数往返。
OpenAI 路径还会执行合成的 PCM24 语音到响应音频往返;传入 --openai-audio-cycles 3 可进行短时间的重复生命周期浸泡测试。
高级配置¶
Gemini Interactions API(无状态)
Gemini Interactions 是默认
google-generative-ai 传输方式的一种可选替代方案。使用
api: "google-interactions" 注册一个提供商,并通过该提供商 ID 选择模型:
{
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" } },
},
}
该传输方式是无状态的:OpenClaw 会发送 store: false,不会保留服务器端
交互 ID,并在每次请求时重放所需的对话上下文。此路由不支持显式的 Gemini
cachedContent 句柄;如需该功能,请使用 google-generative-ai。
被中断的文本回复会使用常规的瞬时错误重试和故障转移策略。格式错误的已完成 工具调用参数仍会被拒绝。
直接 Gemini 缓存复用
对于直接 Gemini API 运行(api: "google-generative-ai"),OpenClaw
会将已配置的 cachedContent 句柄透传到 Gemini 请求中。
- 使用
cachedContent或旧版cached_content配置按模型或全局参数 - 来自更具体作用域(模型级别优先于全局)的参数始终优先。
在同一作用域内,如果同时设置了两个键,则
cached_content优先。 为避免意外,每个作用域只使用一个键。 - 示例值:
cachedContents/prebuilt-context - Gemini 缓存命中用量会从上游
cachedContentTokenCount规范化为 OpenClaw 的cacheRead
Gemini CLI 使用说明
可选的 google-gemini-cli 运行时默认使用 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推导输入 Token 数。
环境和守护进程设置
如果 Gateway 作为守护进程(launchd/systemd)运行,请确保 GEMINI_API_KEY
对该进程可用(例如,位于 ~/.openclaw/.env 中,或通过
env.shellEnv 提供)。
相关¶
选择提供商、模型引用和故障转移行为。
共享图像工具参数和提供商选择。
共享视频工具参数和提供商选择。
共享音乐工具参数和提供商选择。
Gemini CLI 后端设置和运行时详情。
使用 Gemini Live 实时语音提供商的音频桥接。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw