OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Providers

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 khả năng tạo hình ảnh, hiểu nội dung đa 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 trên 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: 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.

Khóa API

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

  • Lấy khóa API

    Tạo khóa miễn phí trong Google AI Studio.

  • Chạy quy trình thiết lập ban đầu

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

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

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

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

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

  • Xác minh mô hình khả dụng

    bash
    openclaw models list --provider google

    • Gemini CLI (OAuth)

    Phù hợp nhất cho: đăng nhập bằng tài khoản Google qua OAuth của Gemini CLI thay vì sử dụng khóa API riêng.

  • Cài đặt Gemini CLI

    Lệnh gemini cục bộ phải khả dụng trên PATH.

    bash
    # Homebrewbrew install gemini-cli # hoặc npmnpm install -g @google/gemini-cli

    OpenClaw hỗ trợ cả bản cài đặt Homebrew và bản 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

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

  • Xác minh mô hình khả dụng

    bash
    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 làm bí danh tiện dụng và chuẩn hóa nó trước khi gọi nhà cung cấp.

    Biến môi trường:

    • OPENCLAW_GEMINI_OAUTH_CLIENT_ID / GEMINI_CLI_OAUTH_CLIENT_ID
    • OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET / GEMINI_CLI_OAUTH_CLIENT_SECRET

    Tính năng tự động phát hiện trong quy trình thiết lập ban đầu liệt kê thông tin đăng nhập Gemini CLI hiện có nhưng không bao giờ tự động kiểm tra vì Gemini CLI không có phép thăm dò không dùng công cụ. Chọn OAuth của Gemini CLI hoặc khóa Gemini API để tiếp tục.

    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 sử dụng tham chiếu mô hình google/* cùng runtime google-gemini-cli khi cần thực thi Gemini CLI cục bộ.

    Khả năng

    Khả năng Được hỗ trợ
    Hoàn thành hội thoại 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 thanh Có
    Hiểu video Có
    Tìm kiếm web (Grounding) Có
    Tư duy/lập luận Có (Gemini 2.5+ / Gemini 3+)
    Các 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 khả năng grounding của Google Search trong Gemini. Cấu hình khóa tìm kiếm chuyên dụng trong plugins.entries.google.config.webSearch, hoặc cho phép tái sử dụng models.providers.google.apiKey sau GEMINI_API_KEY:

    json5
    {  plugins: {    entries: {      google: {        config: {          webSearch: {            apiKey: "AIza...", // không bắt buộc nếu GEMINI_API_KEY hoặc models.providers.google.apiKey được đặt            baseUrl: "https://generativelanguage.googleapis.com/v1beta", // dự phòng về 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à dành cho proxy của đơn vị vận hành hoặc các điểm cuối tương thích với Gemini API; khi bị bỏ qua, tìm kiếm web Gemini sẽ 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 sử dụng google/gemini-3.1-flash-image.

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

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

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

    Tạo video

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

    • 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à các luồng tham chiếu một video
    • Hỗ trợ aspectRatio (16:9, 9:16) và resolution (720P, 1080P); hiện nay Veo không 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 được điều chỉnh về giá trị được phép gần nhất)

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

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

    Tạo nhạc

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

    • 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ượt chạy dựa trên phiên được tách qua luồng tác vụ/trạng thái dùng chung, bao gồm action: "status"

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

    json5
    {  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 TTS của Gemini API với gemini-3.1-flash-tts-preview.

    • Giọng nói 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: PCM của Google được đóng gói dưới dạng WAV và chuyển mã thành 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. Đối với các cuộc hội thoại bằng giọng nói có độ trễ thấp nhất, hãy sử dụng nhà cung cấp giọng nói thời gian thực của Google dựa trên Gemini Live API thay vì TTS theo lô.

    Để sử dụng Google làm nhà cung cấp TTS mặc định:

    json5
    {  messages: {    tts: {      auto: "always",      provider: "google",      providers: {        google: {          model: "gemini-3.1-flash-tts-preview",          speakerVoice: "Kore",          audioProfile: "Nói chuyên nghiệp với giọng điềm tĩnh.",        },      },    },  },}

    TTS của Gemini API sử dụng lời nhắc bằng ngôn ngữ tự nhiên để kiểm soát phong cách. Đặt audioProfile để thêm 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ập đến một người nói có tên.

    TTS của Gemini API cũng chấp nhận các thẻ âm thanh biểu cảm trong dấu ngoặc vuông trong văn bản, chẳng hạn như [whispers] hoặc [laughs]. Để các thẻ không xuất hiện trong phản hồi trò chuyện nhưng vẫn gửi chúng đến TTS, hãy đặt chúng bên trong một khối [[tts:text]]...[[/tts:text]]:

    text
    Đây là văn bản phản hồi sạch. [[tts:text]][whispers] Đây là phiên bản được đọc thành tiếng.[[/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 dựa trên Gemini Live API cho các cầu nối âm thanh phía backend như Voice Call và Google Meet.

    Cài đặt Đường dẫn cấu hình Mặc định
    Mô hình plugins.entries.voice-call.config.realtime.providers.google.model gemini-3.1-flash-live-preview
    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 hội thoại ...google.turnCoverage Mặc định của Google, audio-activity-and-all-video
    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 sang models.providers.google.apiKey, GEMINI_API_KEY hoặc GOOGLE_API_KEY

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

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

    Để người bảo trì xác minh trực tiếp, hãy chạy OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts. Bài kiểm tra nhanh cũng bao quát các đường dẫn backend/WebRTC của OpenAI; nhánh Google tạo cùng dạng token Live API có giới hạn mà Talk trong Control UI sử dụng, mở điểm cuối WebSocket của trình duyệt, gửi tải trọng thiết lập ban đầu cùng một khung hình JPEG, rồi xác minh phản hồi văn bản và vòng khứ hồi của hàm describe_view.

    Cấu hình nâng cao

    Tái sử dụng trực tiếp bộ nhớ đệm Gemini

    Đối với các lượt chạy trực tiếp bằng Gemini API (api: "google-generative-ai"), OpenClaw chuyển tiếp mã định danh cachedContent đã cấu hình tới các yêu cầu Gemini.

    • Cấu hình tham số theo từng mô hình hoặc trên toàn cục bằng cachedContent hoặc cached_content cũ
    • Tham số từ phạm vi cụ thể hơn (cấp mô hình thay vì toàn cục) luôn được ưu tiên. Trong cùng một phạm vi, nếu cả hai khóa đều được đặt, cached_content được ưu tiên. Chỉ sử dụng một khóa cho mỗi phạm vi để tránh kết quả ngoài dự kiến.
    • Giá trị ví dụ: cachedContents/prebuilt-context
    • Mức sử dụng khi khớp bộ nhớ đệm Gemini được chuẩn hóa thành cacheRead của OpenClaw từ cachedContentTokenCount ở thượng nguồn
    json5
    {  agents: {    defaults: {      models: {        "google/gemini-2.5-pro": {          params: {            cachedContent: "cachedContents/prebuilt-context",          },        },      },    },  },}
    Lưu ý sử dụng Gemini CLI

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

    • Văn bản phản hồi được truyền trực tuyến đến từ các sự kiện message của trợ lý.
    • Đối với đầu ra JSON cũ, văn bản phản hồi đến từ trường response trong JSON của CLI.
    • Mức sử dụng dự phòng sang 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.
    Thiết lập môi trường và daemon

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

    Liên quan

    Lựa chọn mô hình

    Chọn nhà cung cấp, tham chiếu mô hình và hành vi chuyển đổi dự phòng.
    Tạo hình ảnh

    Các tham số công cụ hình ảnh dùng chung và lựa chọn nhà cung cấp.
    Tạo video

    Các tham số công cụ video dùng chung và lựa chọn nhà cung cấp.
    Tạo nhạc

    Các tham số công cụ âm nhạc dùng chung và lựa chọn nhà cung cấp.
    Was this useful?
    On this page

    On this page