Google (Gemini)

Google Plugin 透過 Google AI Studio 提供 Gemini 模型存取，並支援 圖片生成、媒體理解（圖片/音訊/影片）、文字轉語音，以及透過 Gemini Grounding 進行網頁搜尋。

• 供應商：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

# 功能

# 網頁搜尋

內建的 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-2.5-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-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 Plugin 也會透過共用的 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 Plugin 也會透過共用的 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: {
      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 Plugin 會註冊由 Gemini Live API 支援的即時語音供應商，用於 Voice Call 和 Google Meet 等後端音訊橋接。

語音通話即時設定範例：

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

# 相關