Skip to main content

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，并通过 Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）、文本转语音和网页搜索。
  • Provider: google
  • Auth: GEMINI_API_KEY or GOOGLE_API_KEY
  • API: Google Gemini API
  • Runtime option: agents.defaults.agentRuntime.id: "google-gemini-cli" 复用 Gemini CLI OAuth，同时保持模型引用为规范化的 google/*。

​
开始使用

选择你偏好的身份验证方式并按照设置步骤操作。
最佳适用场景： 通过 Google AI Studio 进行标准 Gemini API 访问。
1

运行引导

openclaw onboard --auth-choice gemini-api-key
或直接传入密钥：
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY"
2

设置默认模型

{
  agents: {
    defaults: {
      model: { primary: "google/gemini-3.1-pro-preview" },
    },
  },
}
3

验证模型是否可用

openclaw models list --provider google
环境变量 GEMINI_API_KEY 和 GOOGLE_API_KEY 都可以接受。请使用你已经配置好的那个。

​
功能支持

功能支持情况
Chat completionsYes
Image generationYes
Music generationYes
Text-to-speechYes
Realtime voiceYes (Google Live API)
Image understandingYes
Audio transcriptionYes
Video understandingYes
Web search (Grounding)Yes
Thinking/reasoningYes (Gemini 2.5+ / Gemini 3+)
Gemma 4 modelsYes
捆绑的 gemini 网页搜索 provider 使用 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 网页搜索会复用 models.providers.google.baseUrl。参见 Gemini search 了解 provider 特定的工具行为。
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。

​
图像生成

内置的 google 图像生成 provider 默认使用 google/gemini-3.1-flash-image-preview。
  • 也支持 google/gemini-3-pro-image-preview
  • 生成：每次请求最多 4 张图片
  • 编辑模式：已启用，最多 5 张输入图片
  • 形状控制：size、aspectRatio 和 resolution
要将 Google 设为默认图像 provider： 
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "google/gemini-3.1-flash-image-preview",
      },
    },
  },
}
共享工具参数、provider 选择和故障切换行为请参见 图像生成。

​
视频生成

内置的 google 插件还通过共享的 video_generate 工具注册视频生成。
  • 默认视频模型: google/veo-3.1-fast-generate-preview
  • 模式：文本转视频、图像转视频，以及单视频参考流程
  • 支持 aspectRatio、resolution 和 audio
  • 当前时长限制：4 到 8 秒
要将 Google 设为默认视频 provider： 
{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "google/veo-3.1-fast-generate-preview",
      },
    },
  },
}
共享工具参数、provider 选择和故障切换行为请参见 视频生成。

​
音乐生成

内置的 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 设为默认音乐 provider： 
{
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "google/lyria-3-clip-preview",
      },
    },
  },
}
共享工具参数、provider 选择和故障切换行为请参见 音乐生成。

​
文本转语音

内置的 google 语音 provider 使用 Gemini API 的 TTS 路径， 并采用 gemini-3.1-flash-tts-preview。
  • 默认语音: Kore
  • Auth: messages.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 设为默认 TTS provider： 
{
  messages: {
    tts: {
      auto: "always",
      provider: "google",
      providers: {
        google: {
          model: "gemini-3.1-flash-tts-preview",
          voiceName: "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 key 对此 provider 是有效的。这不是独立的 Cloud Text-to-Speech API 路径。

​
实时语音

内置的 google 插件注册了一个由 Gemini Live API 支持的实时语音 provider，用于后端音频桥接，例如 Voice Call 和 Google Meet。
设置配置路径默认值
模型plugins.entries.voice-call.config.realtime.providers.google.modelgemini-2.5-flash-native-audio-preview-12-2025
语音...google.voiceKore
温度...google.temperature(unset)
VAD 开始敏感度...google.startSensitivity(unset)
VAD 结束敏感度...google.endSensitivity(unset)
静音时长...google.silenceDurationMs(unset)
活动处理...google.activityHandlingGoogle default, start-of-activity-interrupts
回合覆盖...google.turnCoverageGoogle default, only-activity
禁用自动 VAD...google.automaticActivityDetectionDisabledfalse
API key...google.apiKey回退到 models.providers.google.apiKey、GEMINI_API_KEY 或 GOOGLE_API_KEY
Voice Call 实时配置示例： 
{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          realtime: {
            enabled: true,
            provider: "google",
            providers: {
              google: {
                model: "gemini-2.5-flash-native-audio-preview-12-2025",
                voice: "Kore",
                activityHandling: "start-of-activity-interrupts",
                turnCoverage: "only-activity",
              },
            },
          },
        },
      },
    },
  },
}
Google Live API 使用双向音频和函数调用，并通过 WebSocket 进行通信。 OpenClaw 会将电话/Meet 桥接音频适配为 Gemini 的 PCM Live API 流，并 保持工具调用遵循共享的实时语音契约。除非你需要采样变化，否则保留 temperature 未设置；OpenClaw 会省略非正值，因为 Google Live 在 temperature: 0 时可能返回无音频的转录。 Gemini API 转录在没有 languageCodes 的情况下启用；当前 Google SDK 会拒绝此 API 路径上的语言代码提示。
Control UI Talk 支持带受限一次性令牌的 Google Live 浏览器会话。 仅后端的实时语音 provider 也可以通过通用的 Gateway relay transport 运行，这会将 provider 凭据保留在 Gateway 上。
对于维护者的实时验证，请运行 OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts。 Google 这一路会生成与 Control UI Talk 使用的相同受限 Live API 令牌格式，打开浏览器 WebSocket 端点，发送初始设置负载， 并等待 setupComplete。

​
高级配置

对于直接的 Gemini API 运行（api: "google-generative-ai"），OpenClaw 会将已配置的 cachedContent 句柄传递给 Gemini 请求。
  • 可使用 cachedContent 或旧版 cached_content 配置按模型或全局参数
  • 如果两者都存在，则以 cachedContent 为准
  • 示例值：cachedContents/prebuilt-context
  • Gemini 缓存命中用量会从上游 cachedContentTokenCount 归一化为 OpenClaw 的 cacheRead
{
  agents: {
    defaults: {
      models: {
        "google/gemini-2.5-pro": {
          params: {
            cachedContent: "cachedContents/prebuilt-context",
          },
        },
      },
    },
  },
}
使用 google-gemini-cli OAuth 提供方时，OpenClaw 会按如下方式 规范化 CLI 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 提供）。

​
相关内容

模型选择

选择提供方、模型引用以及故障切换行为。

图像生成

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

视频生成

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

音乐生成

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