> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # Google (Gemini) 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. **Phù hợp nhất cho:** quyền truy cập Gemini API tiêu chuẩn thông qua Google AI Studio. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw onboard --auth-choice gemini-api-key ``` Hoặc truyền khóa trực tiếp: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw onboard --non-interactive \ --mode local \ --auth-choice gemini-api-key \ --gemini-api-key "$GEMINI_API_KEY" ``` ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { model: { primary: "google/gemini-3.1-pro-preview" }, }, }, } ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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. Lệnh `gemini` cục bộ phải có sẵn trên `PATH`. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 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. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw models auth login --provider google-gemini-cli --set-default ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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`: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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](/vi/tools/gemini-search) để 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: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { imageGenerationModel: { primary: "google/gemini-3.1-flash-image-preview", }, }, }, } ``` Xem [Tạo hình ảnh](/vi/tools/image-generation) để 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: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { videoGenerationModel: { primary: "google/veo-3.1-fast-generate-preview", }, }, }, } ``` Xem [Tạo video](/vi/tools/video-generation) để 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: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { musicGenerationModel: { primary: "google/lyria-3-clip-preview", }, }, }, } ``` Xem [Tạo nhạc](/vi/tools/music-generation) để 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: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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]]`: ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} 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: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 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 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { models: { "google/gemini-2.5-pro": { params: { cachedContent: "cachedContents/prebuilt-context", }, }, }, }, }, } ``` 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`. 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 Chọn nhà cung cấp, tham chiếu mô hình và hành vi failover. Tham số công cụ hình ảnh dùng chung và lựa chọn nhà cung cấp. Tham số công cụ video dùng chung và lựa chọn nhà cung cấp. Tham số công cụ âm nhạc dùng chung và lựa chọn nhà cung cấp.