Google (Gemini)

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

• 提供者：google
• 驗證：GEMINI_API_KEY 或 GOOGLE_API_KEY
• API：Google Gemini API
• 執行階段選項：agentRuntime.id: "google-gemini-cli" 會重複使用 Gemini 命令列介面的 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 外掛也會透過共用的 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 外掛也會透過共用的 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、通話／電話語音使用 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",          speakerVoice: "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 支援的即時語音提供者，供語音通話和 Google Meet 等後端音訊橋接使用。

Voice Call 即時設定範例：

{  plugins: {    entries: {      "voice-call": {        enabled: true,        config: {          realtime: {            enabled: true,            provider: "google",            providers: {              google: {                model: "gemini-3.1-flash-live-preview",                speakerVoice: "Kore",                activityHandling: "start-of-activity-interrupts",                turnCoverage: "audio-activity-and-all-video",              },            },          },        },      },    },  },}

若要供維護者進行即時驗證，請執行 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",          },        },      },    },  },}

相關內容