Google (Gemini) - OpenClaw

Plugin Google cung cấp quyền truy cập vào các mô hình Gemini thông qua Google AI Studio, cùng với tạo hình ảnh, hiểu phương tiện (hình ảnh/âm thanh/video), chuyển văn bản thành giọng nói và tìm kiếm web qua Gemini Grounding.

Nhà cung cấp: google
Xác thực: GEMINI_API_KEY hoặc GOOGLE_API_KEY
API: Google Gemini API
Tùy chọn runtime: provider/model agentRuntime.id: "google-gemini-cli" tái sử dụng OAuth của Gemini CLI trong khi vẫn giữ các tham chiếu mô hình ở dạng chuẩn là google/*.

Bắt đầu

Chọn phương thức xác thực bạn muốn và làm theo các bước thiết lập.

API key
Gemini CLI (OAuth)

Phù hợp nhất cho: quyền truy cập Gemini API tiêu chuẩn thông qua Google AI Studio.

Chạy onboarding

openclaw onboard --auth-choice gemini-api-key

Hoặc truyền khóa trực tiếp:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY"

Đặt mô hình mặc định

{
  agents: {
    defaults: {
      model: { primary: "google/gemini-3.1-pro-preview" },
    },
  },
}

Xác minh mô hình có sẵn

openclaw models list --provider google

Cả hai biến môi trường GEMINI_API_KEY và GOOGLE_API_KEY đều được chấp nhận. Hãy dùng biến bạn đã cấu hình.

Phù hợp nhất cho: tái sử dụng phiên đăng nhập Gemini CLI hiện có qua PKCE OAuth thay vì dùng một API key riêng.

Nhà cung cấp google-gemini-cli là một tích hợp không chính thức. Một số người dùng báo cáo có hạn chế tài khoản khi dùng OAuth theo cách này. Bạn tự chịu rủi ro khi sử dụng.

Cài đặt Gemini CLI

Lệnh gemini cục bộ phải có sẵn trên PATH.

# Homebrew
brew install gemini-cli

# or npm
npm install -g @google/gemini-cli

OpenClaw hỗ trợ cả cài đặt Homebrew và cài đặt npm toàn cục, bao gồm các bố cục Windows/npm phổ biến.

Đăng nhập qua OAuth

openclaw models auth login --provider google-gemini-cli --set-default

Xác minh mô hình có sẵn

openclaw models list --provider google

Mô hình mặc định: google/gemini-3.1-pro-preview
Runtime: google-gemini-cli
Bí danh: gemini-cli

ID mô hình Gemini API của Gemini 3.1 Pro là gemini-3.1-pro-preview. OpenClaw chấp nhận dạng ngắn hơn google/gemini-3.1-pro như một bí danh tiện lợi và chuẩn hóa nó trước các lệnh gọi nhà cung cấp.Biến môi trường:

OPENCLAW_GEMINI_OAUTH_CLIENT_ID
OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET

(Hoặc các biến thể GEMINI_CLI_*.)

Nếu các yêu cầu Gemini CLI OAuth thất bại sau khi đăng nhập, hãy đặt GOOGLE_CLOUD_PROJECT hoặc GOOGLE_CLOUD_PROJECT_ID trên máy chủ gateway rồi thử lại.

Nếu đăng nhập thất bại trước khi luồng trình duyệt bắt đầu, hãy đảm bảo lệnh gemini cục bộ đã được cài đặt và có trên PATH.

Các tham chiếu mô hình google-gemini-cli/* là bí danh tương thích cũ. Cấu hình mới nên dùng tham chiếu mô hình google/* cùng với runtime google-gemini-cli khi muốn thực thi Gemini CLI cục bộ.

Khả năng

Khả năng	Được hỗ trợ
Hoàn tất chat	Có
Tạo hình ảnh	Có
Tạo nhạc	Có
Chuyển văn bản thành giọng nói	Có
Giọng nói thời gian thực	Có (Google Live API)
Hiểu hình ảnh	Có
Phiên âm âm thanh	Có
Hiểu video	Có
Tìm kiếm web (Grounding)	Có
Suy nghĩ/lập luận	Có (Gemini 2.5+ / Gemini 3+)
Mô hình Gemma 4	Có

Tìm kiếm web

Nhà cung cấp tìm kiếm web gemini đi kèm sử dụng Gemini Google Search grounding. Cấu hình một khóa tìm kiếm chuyên dụng trong plugins.entries.google.config.webSearch, hoặc để nó tái sử dụng models.providers.google.apiKey sau GEMINI_API_KEY:

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

Thứ tự ưu tiên thông tin xác thực là webSearch.apiKey chuyên dụng, sau đó là GEMINI_API_KEY, rồi models.providers.google.apiKey. webSearch.baseUrl là tùy chọn và tồn tại cho proxy của người vận hành hoặc các endpoint Gemini API tương thích; khi bị bỏ qua, tìm kiếm web Gemini tái sử dụng models.providers.google.baseUrl. Xem Tìm kiếm Gemini để biết hành vi công cụ riêng của nhà cung cấp.

Các mô hình Gemini 3 dùng thinkingLevel thay vì thinkingBudget. OpenClaw ánh xạ các điều khiển lập luận bí danh của Gemini 3, Gemini 3.1 và gemini-*-latest sang thinkingLevel để các lượt chạy mặc định/độ trễ thấp không gửi các giá trị thinkingBudget đã tắt./think adaptive giữ ngữ nghĩa suy nghĩ động của Google thay vì chọn một mức OpenClaw cố định. Gemini 3 và Gemini 3.1 bỏ qua thinkingLevel cố định để Google có thể chọn mức; Gemini 2.5 gửi sentinel động của Google thinkingBudget: -1.Các mô hình Gemma 4 (ví dụ gemma-4-26b-a4b-it) hỗ trợ chế độ suy nghĩ. OpenClaw ghi lại thinkingBudget thành thinkingLevel được Google hỗ trợ cho Gemma 4. Đặt suy nghĩ thành off sẽ giữ trạng thái tắt suy nghĩ thay vì ánh xạ sang MINIMAL.

Tạo hình ảnh

Nhà cung cấp tạo hình ảnh google đi kèm mặc định dùng google/gemini-3.1-flash-image-preview.

Cũng hỗ trợ google/gemini-3-pro-image-preview
Tạo: tối đa 4 hình ảnh mỗi yêu cầu
Chế độ chỉnh sửa: được bật, tối đa 5 hình ảnh đầu vào
Điều khiển hình học: size, aspectRatio và resolution

Để dùng Google làm nhà cung cấp hình ảnh mặc định:

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

Xem Tạo hình ảnh để biết các tham số công cụ dùng chung, cách chọn nhà cung cấp và hành vi chuyển đổi dự phòng.

Tạo video

Plugin google đi kèm cũng đăng ký tạo video thông qua công cụ dùng chung video_generate.

Mô hình video mặc định: google/veo-3.1-fast-generate-preview
Chế độ: luồng văn bản thành video, hình ảnh thành video và tham chiếu một video
Hỗ trợ aspectRatio (16:9, 9:16) và resolution (720P, 1080P); Veo hiện chưa hỗ trợ đầu ra âm thanh
Thời lượng được hỗ trợ: 4, 6 hoặc 8 giây (các giá trị khác sẽ được làm tròn về giá trị được phép gần nhất)

Để dùng Google làm nhà cung cấp video mặc định:

{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "google/veo-3.1-fast-generate-preview",
      },
    },
  },
}

Xem Tạo video để biết các tham số công cụ dùng chung, cách chọn nhà cung cấp và hành vi chuyển đổi dự phòng.

Tạo nhạc

Plugin google đi kèm cũng đăng ký tạo nhạc thông qua công cụ dùng chung music_generate.

Mô hình nhạc mặc định: google/lyria-3-clip-preview
Cũng hỗ trợ google/lyria-3-pro-preview
Điều khiển lời nhắc: lyrics và instrumental
Định dạng đầu ra: mặc định là mp3, cộng thêm wav trên google/lyria-3-pro-preview
Đầu vào tham chiếu: tối đa 10 hình ảnh
Các lượt chạy dựa trên phiên tách ra thông qua luồng tác vụ/trạng thái dùng chung, bao gồm action: "status"

Để dùng Google làm nhà cung cấp nhạc mặc định:

{
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "google/lyria-3-clip-preview",
      },
    },
  },
}

Xem Tạo nhạc để biết các tham số công cụ dùng chung, cách chọn nhà cung cấp và hành vi chuyển đổi dự phòng.

Chuyển văn bản thành giọng nói

Nhà cung cấp giọng nói google đi kèm sử dụng đường dẫn TTS của Gemini API với gemini-3.1-flash-tts-preview.

Giọng mặc định: Kore
Xác thực: messages.tts.providers.google.apiKey, models.providers.google.apiKey, GEMINI_API_KEY hoặc GOOGLE_API_KEY
Đầu ra: WAV cho tệp đính kèm TTS thông thường, Opus cho mục tiêu ghi chú thoại, PCM cho Talk/telephony
Đầu ra ghi chú thoại: Google PCM được bọc dưới dạng WAV và chuyển mã sang Opus 48 kHz bằng ffmpeg

Đường dẫn batch Gemini TTS của Google trả về âm thanh được tạo trong phản hồi generateContent đã hoàn tất. Để có các cuộc trò chuyện nói với độ trễ thấp nhất, hãy dùng nhà cung cấp giọng nói thời gian thực của Google được hỗ trợ bởi Gemini Live API thay vì batch TTS. Để dùng Google làm nhà cung cấp TTS mặc định:

{
  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 dùng lời nhắc ngôn ngữ tự nhiên để kiểm soát phong cách. Đặt audioProfile để thêm trước một lời nhắc phong cách có thể tái sử dụng trước văn bản được đọc. Đặt speakerName khi văn bản lời nhắc của bạn nhắc đến một người nói có tên. Gemini API TTS cũng chấp nhận các thẻ âm thanh biểu cảm trong ngoặc vuông trong văn bản, chẳng hạn như [whispers] hoặc [laughs]. Để giữ các thẻ không xuất hiện trong phản hồi chat hiển thị trong khi vẫn gửi chúng tới TTS, hãy đặt chúng bên trong khối [[tts:text]]...[[/tts:text]]:

Here is the clean reply text.

[[tts:text]][whispers] Here is the spoken version.[[/tts:text]]

API key trong Google Cloud Console bị giới hạn cho Gemini API là hợp lệ với nhà cung cấp này. Đây không phải là đường dẫn Cloud Text-to-Speech API riêng.

Giọng nói thời gian thực

Plugin google đi kèm đăng ký một nhà cung cấp giọng nói thời gian thực được hỗ trợ bởi Gemini Live API cho các cầu nối âm thanh backend như Voice Call và Google Meet.

Thiết lập	Đường dẫn cấu hình	Mặc định
Mô hình	`plugins.entries.voice-call.config.realtime.providers.google.model`	`gemini-2.5-flash-native-audio-preview-12-2025`
Giọng nói	`...google.voice`	`Kore`
Nhiệt độ	`...google.temperature`	(chưa đặt)
Độ nhạy bắt đầu VAD	`...google.startSensitivity`	(chưa đặt)
Độ nhạy kết thúc VAD	`...google.endSensitivity`	(chưa đặt)
Thời lượng im lặng	`...google.silenceDurationMs`	(chưa đặt)
Xử lý hoạt động	`...google.activityHandling`	Mặc định của Google, `start-of-activity-interrupts`
Phạm vi lượt	`...google.turnCoverage`	Mặc định của Google, `only-activity`
Tắt VAD tự động	`...google.automaticActivityDetectionDisabled`	`false`
Tiếp tục phiên	`...google.sessionResumption`	`true`
Nén ngữ cảnh	`...google.contextWindowCompression`	`true`
Khóa API	`...google.apiKey`	Dự phòng về `models.providers.google.apiKey`, `GEMINI_API_KEY`, hoặc `GOOGLE_API_KEY`

Ví dụ cấu hình thời gian thực cho cuộc gọi thoại:

{
  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 dùng âm thanh hai chiều và gọi hàm qua WebSocket. OpenClaw điều chỉnh âm thanh cầu nối điện thoại/Meet cho luồng PCM Live API của Gemini và giữ các lệnh gọi công cụ trên hợp đồng giọng nói thời gian thực dùng chung. Để temperature chưa đặt trừ khi bạn cần thay đổi lấy mẫu; OpenClaw bỏ qua các giá trị không dương vì Google Live có thể trả về bản chép lời mà không có âm thanh khi temperature: 0. Phiên âm Gemini API được bật mà không có languageCodes; Google SDK hiện tại từ chối gợi ý mã ngôn ngữ trên đường dẫn API này.

Control UI Talk hỗ trợ các phiên trình duyệt Google Live với token dùng một lần bị ràng buộc. Các nhà cung cấp giọng nói thời gian thực chỉ chạy ở backend cũng có thể chạy qua giao thức vận chuyển chuyển tiếp Gateway chung, giúp giữ thông tin xác thực của nhà cung cấp trên Gateway.

Để xác minh trực tiếp cho maintainer, chạy OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts. Bài smoke cũng bao phủ các đường dẫn backend/WebRTC của OpenAI; nhánh Google tạo cùng dạng token Live API bị ràng buộc mà Control UI Talk dùng, mở endpoint WebSocket của trình duyệt, gửi payload thiết lập ban đầu, và chờ setupComplete.

Cấu hình nâng cao

Direct Gemini cache reuse

Với các lần chạy Gemini API trực tiếp (api: "google-generative-ai"), OpenClaw chuyển một handle cachedContent đã cấu hình vào các yêu cầu Gemini.

Cấu hình tham số theo từng mô hình hoặc toàn cục bằng cachedContent hoặc cached_content cũ
Nếu có cả hai, cachedContent được ưu tiên
Giá trị ví dụ: cachedContents/prebuilt-context
Mức sử dụng cache-hit của Gemini được chuẩn hóa thành cacheRead của OpenClaw từ cachedContentTokenCount thượng nguồn

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

Gemini CLI usage notes

Khi dùng nhà cung cấp OAuth google-gemini-cli, OpenClaw dùng đầu ra stream-json của Gemini CLI theo mặc định và chuẩn hóa mức sử dụng từ payload stats cuối cùng. Các override --output-format json cũ vẫn dùng trình phân tích JSON.

Văn bản trả lời được stream lấy từ các sự kiện message của assistant.
Với đầu ra JSON cũ, văn bản trả lời lấy từ trường response trong JSON của CLI.
Mức sử dụng dự phòng về stats khi CLI để trống usage.
stats.cached được chuẩn hóa thành cacheRead của OpenClaw.
Nếu thiếu stats.input, OpenClaw suy ra token đầu vào từ stats.input_tokens - stats.cached.

Environment and daemon setup

Nếu Gateway chạy dưới dạng daemon (launchd/systemd), hãy đảm bảo GEMINI_API_KEY khả dụng cho tiến trình đó (ví dụ, trong ~/.openclaw/.env hoặc qua env.shellEnv).

Liên quan

Model selection

Chọn nhà cung cấp, tham chiếu mô hình và hành vi failover.

Image generation

Tham số công cụ hình ảnh dùng chung và lựa chọn nhà cung cấp.

Video generation

Tham số công cụ video dùng chung và lựa chọn nhà cung cấp.

Music generation

Tham số công cụ âm nhạc dùng chung và lựa chọn nhà cung cấp.

​Bắt đầu

​Khả năng

​Tìm kiếm web

​Tạo hình ảnh

​Tạo video

​Tạo nhạc

​Chuyển văn bản thành giọng nói

​Giọng nói thời gian thực

​Cấu hình nâng cao

​Liên quan

Model selection

Image generation

Video generation

Music generation

Bắt đầu

Khả năng

Tìm kiếm web

Tạo hình ảnh

Tạo video

Tạo nhạc

Chuyển văn bản thành giọng nói

Giọng nói thời gian thực

Cấu hình nâng cao

Liên quan