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 # 或 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...", // 若已設定 GEMINI_API_KEY 或 models.providers.google.apiKey，則為選用            baseUrl: "https://generativelanguage.googleapis.com/v1beta", // 備援為 models.providers.google.baseUrl            model: "gemini-2.5-flash",          },        },      },    },  },}

認證資訊的優先順序為專用的 webSearch.apiKey，接著是 GEMINI_API_KEY， 最後是 models.providers.google.apiKey。webSearch.baseUrl 為選用， 用於操作人員的 Proxy 或相容的 Gemini API 端點；若省略， Gemini 網路搜尋會重複使用 models.providers.google.baseUrl。關於提供者專屬的工具行為，請參閱 Gemini 搜尋。

影像生成

內建的 google 影像生成提供者預設使用 google/gemini-3.1-flash-image。

• 也支援 google/gemini-3-pro-image
• 生成：每次要求最多 4 張影像
• 編輯模式：已啟用，最多 5 張輸入影像
• 幾何控制：size、aspectRatio 和 resolution

若要將 Google 設為預設影像提供者：

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

影片生成

內建的 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
• 驗證：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 提供者：

{  tts: {    auto: "always",    provider: "google",    providers: {      google: {        model: "gemini-3.1-flash-tts-preview",        speakerVoice: "Kore",        audioProfile: "以冷靜的語氣專業地說話。",      },    },  },}

Gemini API TTS 使用自然語言提示詞控制風格。設定 audioProfile，即可在語音文字前加上可重複使用的風格提示詞。當你的提示詞文字提到具名說話者時，請設定 speakerName。

Gemini API TTS 也接受文字中的表現力方括號音訊標籤， 例如 [whispers] 或 [laughs]。若要讓標籤不出現在可見的聊天回覆中， 但仍將其傳送至 TTS，請將它們放在 [[tts:text]]...[[/tts:text]] 區塊內：

這是乾淨的回覆文字。 [[tts:text]][whispers] 這是語音版本。[[/tts:text]]

即時語音

內建的 google 外掛會註冊由 Gemini Live API 支援的即時語音提供者，用於 Voice Call 和 Google Meet 等後端音訊橋接器。

語音通話即時設定範例：

{  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 部分會鑄造與控制介面「Talk」所用相同形式的 受限 Live API 權杖、開啟瀏覽器 WebSocket 端點、傳送初始設定承載資料及一個 JPEG 影格，並 驗證文字回應與 describe_view 函式往返。

進階設定

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

相關內容