Google (Gemini)

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

• 供應商：google
• 驗證：GEMINI_API_KEY 或 GOOGLE_API_KEY
• API：Google Gemini API
• 執行階段選項：provider/model 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

# Homebrewbrew install gemini-cli # or npmnpm 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（16:9、9:16）和 resolution（720P、1080P）；Veo 目前不支援音訊輸出
• 支援的時長：4、6 或 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 等後端音訊橋接。

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。 此煙霧測試也涵蓋 OpenAI 後端/WebRTC 路徑；Google 段落會鑄造 Control UI Talk 使用的相同 受限 Live API 權杖形狀、開啟瀏覽器 WebSocket 端點、傳送初始設定承載，並等待 setupComplete。

進階設定

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

相關