本页介绍如何在 OpenClaw 中配置 Google Gemini Provider。通过 GEMINI_API_KEY 或 GOOGLE_API_KEY 认证，可以在龙虾里调用 Gemini 全系能力：文本推理（支持 thinking）、图像生成（Imagen 3）、视频生成（Veo）、音乐生成（Lyria）、图像/音频/视频理解，以及 Grounding 网页搜索。覆盖快速上手步骤、各能力配置示例和 Gemini 缓存复用配置。

Google（Gemini）

Google 插件通过 Google AI Studio 提供 Gemini 模型访问，以及图像生成、媒体理解（图像/音频/视频）和 Gemini Grounding 网页搜索能力。

• Provider：google
• 认证：GEMINI_API_KEY 或 GOOGLE_API_KEY
• API：Google Gemini API

快速上手

1. 设置 API Key

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

能力总览

能力	支持情况
聊天补全	是
图像生成	是
音乐生成	是
图像理解	是
音频转录	是
视频理解	是
网页搜索（Grounding）	是
推理/Thinking	是（Gemini 3.1+）

直接 Gemini 缓存复用

对于直接 Gemini API 请求（api: "google-generative-ai"），可以透传已配置的 cachedContent 句柄：

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

• 参数支持 cachedContent 或旧版 cached_content（两者同时存在时 cachedContent 优先）
• Gemini 缓存命中用量从上游 cachedContentTokenCount 规范化到 OpenClaw cacheRead

图像生成

内置 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；lyria-3-pro-preview 还支持 wav
• 最多 10 张参考图像
• Session 支持的运行通过共享 task/status 流程分离，包括 action: "status"

设置 Google 为默认音乐提供商：

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

环境注意事项

如果 Gateway 作为守护进程（launchd/systemd）运行，确保 GEMINI_API_KEY 对该进程可用（例如在 ~/.openclaw/.env 中或通过 env.shellEnv）。

常见问题

Q: GEMINI_API_KEY 和 GOOGLE_API_KEY 有什么区别，用哪个？

A: 两者都被 OpenClaw 接受，指向同一个 Google AI Studio API。GEMINI_API_KEY 是更新、更明确的名称；GOOGLE_API_KEY 是旧版别名。推荐使用 GEMINI_API_KEY，与 Google 官方文档保持一致。

Q: Gemini Grounding 网页搜索和普通 web_search 工具有什么区别？

A: Gemini Grounding 是 Google 原生的网页搜索能力，直接集成在模型推理过程中，结果会影响模型的回答内容。OpenClaw 的 web_search 工具是插件提供的独立工具，Agent 会显式调用它获取搜索结果再整合到回答中。Grounding 更无缝，web_search 工具更可控。

Q: 视频生成时长上限为什么只有 8 秒？

A: 这是 Veo 当前 API 的限制（4 到 8 秒），由 Google 侧决定，OpenClaw 直接透传。如需更长视频，可以考虑将多个片段拼接，或关注 Google 后续 API 更新。