Google (Gemini)

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

• 提供商：google
• 凭证：GEMINI_API_KEY 或 GOOGLE_API_KEY
• API：Google Gemini API
• 运行时选项：agents.defaults.agentRuntime.id: "google-gemini-cli" 会复用 Gemini CLI OAuth，同时将模型引用保持为规范的 google/*。

# 入门指南

选择你偏好的凭证方式，并按照设置步骤操作。

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

# Homebrew
brew install gemini-cli

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

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

openclaw models list --provider google

# 能力

# 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...", // 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-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-preview。

• 也支持 google/gemini-3-pro-image-preview
• 生成：每次请求最多 4 张图像
• 编辑模式：已启用，最多 5 张输入图像
• 几何控制：size、aspectRatio 和 resolution

要将 Google 用作默认图像提供商：

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "google/gemini-3.1-flash-image-preview",
      },
    },
  },
}

# 视频生成

内置的 google 插件还会通过共享的 video_generate 工具注册视频生成。

• 默认视频模型：google/veo-3.1-fast-generate-preview
• 模式：文本转视频、图像转视频和单视频参考流程
• 支持 aspectRatio、resolution 和 audio
• 当前时长限制：4 到 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 张图像
• 由会话支持的运行会通过共享任务/Status 流程分离，包括 action: "status"

要将 Google 用作默认音乐提供商：

{
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "google/lyria-3-clip-preview",
      },
    },
  },
}

# 文本转语音

内置的 google 语音提供商使用 Gemini API TTS 路径，并搭配 gemini-3.1-flash-tts-preview。

• 默认声音：Kore
• 凭证：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 的批量 Gemini TTS 路径会在已完成的 generateContent 响应中返回生成的音频。对于最低延迟的语音对话，请使用 由 Gemini Live API 支持的 Google 实时语音提供商，而不是批量 TTS。

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

{
  messages: {
    tts: {
      auto: "always",
      provider: "google",
      providers: {
        google: {
          model: "gemini-3.1-flash-tts-preview",
          voiceName: "Kore",
          audioProfile: "Speak professionally with a calm tone.",
        },
      },
    },
  },
}

Gemini API TTS 使用自然语言提示词进行风格控制。设置 audioProfile，可在朗读文本之前添加可复用的风格提示词。当你的提示词文本引用具名说话人时，请设置 speakerName。

Gemini API TTS 也接受文本中的表现性方括号音频标签， 例如 [whispers] 或 [laughs]。要在将标签发送到 TTS 的同时避免它们出现在可见聊天回复中， 请将它们放入 [[tts:text]]...[[/tts:text]] 块中：

Here is the clean reply text.

[[tts:text]][whispers] Here is the spoken version.[[/tts:text]]

# 实时语音

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

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

对于维护者实时验证，请运行 OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts。 Google 分支会铸造与 Control UI Talk 使用的相同受限 Live API 令牌形态， 打开浏览器 WebSocket 端点，发送初始设置载荷， 并等待 setupComplete。

# 高级配置

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

# 相关内容