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: agents.defaults.agentRuntime.id: "google-gemini-cli" tái sử dụng OAuth của Gemini CLI trong khi vẫn giữ tham chiếu mô hình theo dạng chính tắc là google/*.

# Bắt đầu

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

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

# Homebrew
brew install gemini-cli

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

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

openclaw models list --provider google

# Khả năng

# Tìm kiếm web

Nhà cung cấp tìm kiếm web gemini đi kèm sử dụng grounding của Gemini Google Search. Cấu hình 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 nhà vận hành hoặ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ụ dành riêng cho nhà cung cấp.

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

# 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ế độ: văn bản thành video, hình ảnh thành video và luồng tham chiếu một video
• Hỗ trợ aspectRatio, resolution và audio
• Giới hạn thời lượng hiện tại: 4 đến 8 giây

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

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

# 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 với wav trên google/lyria-3-pro-preview
• Đầu vào tham chiếu: tối đa 10 hình ảnh
• Các lần chạy được hỗ trợ bằng phiên sẽ 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",
      },
    },
  },
}

# 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 Gemini API TTS 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 đích ghi chú thoại, PCM cho Talk/điện thoại
• Đầ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 Gemini TTS theo lô của Google trả về âm thanh đã 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 Google được hỗ trợ bởi Gemini Live API thay vì TTS theo lô.

Để 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",
          voiceName: "Kore",
          audioProfile: "Speak professionally with a calm tone.",
        },
      },
    },
  },
}

Gemini API TTS sử dụng lời nhắc ngôn ngữ tự nhiên để điều khiển phong cách. Đặt audioProfile để thêm một lời nhắc phong cách có thể tái sử dụng vào 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ẻ ngoài phản hồi trò chuyện hiển thị trong khi vẫn gửi chúng tới TTS, hãy đặt chúng bên trong một khối [[tts:text]]...[[/tts:text]]:

Here is the clean reply text.

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

# 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.

Ví dụ cấu hình thời gian thực 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",
                voice: "Kore",
                activityHandling: "start-of-activity-interrupts",
                turnCoverage: "only-activity",
              },
            },
          },
        },
      },
    },
  },
}

Để kiểm chứng trực tiếp dành cho maintainer, chạy OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts. Nhánh Google tạo cùng dạng token Live API có giới hạn mà Control UI Talk sử 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

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

# Liên quan