跳轉到主要內容
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/* 作為標準形式。

​
開始使用

選擇偏好的驗證方式並依照設定步驟操作。
**最適合：**透過 Google AI Studio 進行標準 Gemini API 存取。
1

執行入門設定

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

確認模型可用

openclaw models list --provider google
GEMINI_API_KEY 和 GOOGLE_API_KEY 皆可接受。請使用你已設定好的那一個。
google/gemini-3-pro-preview 已於 2026-03-09 退役；請改用 google/gemini-3.1-pro-preview。重新執行 Gemini API 金鑰設定（openclaw onboard --auth-choice gemini-api-key 或 openclaw models auth login --provider google）會將過時的已設定預設值重寫為目前模型。

​
功能

功能支援
聊天補全是
影像生成是
音樂生成是
文字轉語音是
即時語音是（Google Live API）
影像理解是
音訊轉錄是
影片理解是
網頁搜尋（Grounding）是
思考/推理是（Gemini 2.5+ / Gemini 3+）
Gemma 4 模型是

​
網頁搜尋

內建的 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 搜尋 了解提供者專屬工具行為。
Gemini 3 模型使用 thinkingLevel 而非 thinkingBudget。OpenClaw 會將 Gemini 3、Gemini 3.1 和 gemini-*-latest 別名推理控制項對應至 thinkingLevel，因此預設/低延遲執行不會傳送停用的 thinkingBudget 值。/think adaptive 會保留 Google 的動態思考語意，而不是選擇 固定的 OpenClaw 層級。Gemini 3 和 Gemini 3.1 會省略固定的 thinkingLevel，讓 Google 可以選擇層級；Gemini 2.5 會傳送 Google 的動態哨兵值 thinkingBudget: -1。Gemma 4 模型（例如 gemma-4-26b-a4b-it）支援思考模式。OpenClaw 會將 thinkingBudget 重寫為 Gemma 4 支援的 Google thinkingLevel。 將思考設定為 off 會保留思考停用，而不是對應到 MINIMAL。Gemini 2.5 Pro 只能在思考模式下運作，且會拒絕明確的 thinkingBudget: 0；OpenClaw 會為 Gemini 2.5 Pro 請求移除該值， 而不是傳送它。

​
影像生成

內建的 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，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",
          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]]
限制為 Gemini API 的 Google Cloud Console API 金鑰對此 提供者有效。這不是獨立的 Cloud Text-to-Speech API 路徑。

​
即時語音

內建的 google 外掛會註冊由 Gemini Live API 支援的即時語音提供者，用於 Voice Call 和 Google Meet 等後端音訊橋接。
設定設定路徑預設值
模型plugins.entries.voice-call.config.realtime.providers.google.modelgemini-2.5-flash-native-audio-preview-12-2025
語音...google.voiceKore
溫度...google.temperature（未設定）
VAD 開始靈敏度...google.startSensitivity（未設定）
VAD 結束靈敏度...google.endSensitivity（未設定）
靜音持續時間...google.silenceDurationMs（未設定）
活動處理...google.activityHandlingGoogle 預設值，start-of-activity-interrupts
回合涵蓋範圍...google.turnCoverageGoogle 預設值，only-activity
停用自動 VAD...google.automaticActivityDetectionDisabledfalse
工作階段恢復...google.sessionResumptiontrue
上下文壓縮...google.contextWindowCompressiontrue
API 金鑰...google.apiKey退回使用 models.providers.google.apiKey、GEMINI_API_KEY 或 GOOGLE_API_KEY
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",
                speakerVoice: "Kore",
                activityHandling: "start-of-activity-interrupts",
                turnCoverage: "only-activity",
              },
            },
          },
        },
      },
    },
  },
}
Google Live API 透過 WebSocket 使用雙向音訊與函式呼叫。 OpenClaw 會將電話語音/Meet 橋接音訊轉接到 Gemini 的 PCM Live API 串流，並 讓工具呼叫維持在共用的即時語音合約上。除非你需要變更取樣，否則請讓 temperature 保持未設定；OpenClaw 會省略非正值，因為 Google Live 對 temperature: 0 可能會回傳沒有音訊的逐字稿。 Gemini API 逐字稿功能啟用時不使用 languageCodes；目前的 Google SDK 會拒絕此 API 路徑上的語言代碼提示。
Control UI Talk 支援使用受限一次性權杖的 Google Live 瀏覽器工作階段。 僅後端的即時語音提供者也可以透過通用閘道中繼傳輸執行，讓提供者憑證保留在閘道上。
若要進行維護者即時驗證，請執行 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。

​
進階設定

對於直接 Gemini API 執行（api: "google-generative-ai"），OpenClaw 會將已設定的 cachedContent 控制代碼傳遞給 Gemini 請求。
  • 使用 cachedContent 或舊版 cached_content 設定各模型或全域參數
  • 來自更特定範圍的參數（模型層級優先於全域）一律勝出。 在同一範圍內，如果兩個鍵都已設定，cached_content 會勝出。 每個範圍只使用一個鍵，以避免意外。
  • 範例值：cachedContents/prebuilt-context
  • Gemini 快取命中用量會從上游 cachedContentTokenCount 正規化為 OpenClaw cacheRead
{
  agents: {
    defaults: {
      models: {
        "google/gemini-2.5-pro": {
          params: {
            cachedContent: "cachedContents/prebuilt-context",
          },
        },
      },
    },
  },
}
使用 google-gemini-cli OAuth 提供者時，OpenClaw 預設會使用 Gemini 命令列介面的 stream-json 輸出，並從最終的 stats 承載正規化用量。 舊版 --output-format json 覆寫仍會使用 JSON 剖析器。
  • 串流回覆文字來自助理 message 事件。
  • 對於舊版 JSON 輸出，回覆文字來自命令列介面 JSON 的 response 欄位。
  • 當命令列介面讓 usage 保持空白時，用量會退回使用 stats。
  • stats.cached 會正規化為 OpenClaw cacheRead。
  • 如果缺少 stats.input，OpenClaw 會從 stats.input_tokens - stats.cached 推導輸入權杖。
如果閘道以常駐程式（launchd/systemd）執行，請確保 GEMINI_API_KEY 可供該程序使用（例如放在 ~/.openclaw/.env 中，或透過 env.shellEnv）。

​
相關

Model selection

選擇提供者、模型參照與容錯移轉行為。

Image generation

共用圖片工具參數與提供者選擇。

Video generation

共用影片工具參數與提供者選擇。

Music generation

共用音樂工具參數與提供者選擇。