OpenClaw với Gemini: thiết lập mô hình, khóa API và kiểm tra chi phí

OpenClaw truy cập Gemini thông qua plugin google đi kèm: đặt GEMINI_API_KEY hoặc GOOGLE_API_KEY, chạy openclaw onboard --auth-choice gemini-api-key, sau đó đặt model một cách rõ ràng — vì thêm xác thực không thay đổi model mặc định của bạn. Điều mà hầu hết bài viết hướng dẫn bỏ sót là với khóa AI Studio, OpenClaw có ba bề mặt Gemini riêng biệt, mỗi bề mặt có thông tin xác thực, endpoint và khoản phí riêng. (Vertex AI là tuyến thông tin xác thực thứ tư, riêng biệt, thông qua gcloud Application Default Credentials và không được đề cập ở đây.) Làm cho chat hoạt động không bật tìm kiếm Gemini, và bật tìm kiếm Gemini có thể phát sinh phí trên một Google project mà tuyến chat của bạn không bao giờ sử dụng.

Tích hợp Gemini không cần cài đặt riêng. Nó được tích hợp sẵn trong OpenClaw dưới dạng plugin nhà cung cấp google đi kèm (các plugin nhà cung cấp chính thức, ngày 21 tháng 9, 2026), và OpenClaw được cấp phép theo giấy phép MIT, được phát hành dưới dạng openclaw@2026.9.5 trên npm, yêu cầu Node >=24.16.0 <25 || >=26.1.0 (kho đăng ký npm, ngày 21 tháng 9, 2026). Phần mềm không tốn phí; mọi nội dung bên dưới nói về chi phí của các khóa.

Ba bề mặt Gemini, ba thông tin xác thực

Phần hữu ích là các quy tắc ưu tiên. Tìm kiếm web Gemini đọc plugins.entries.google.config.webSearch.apiKey trước, rồi GEMINI_API_KEY, rồi models.providers.google.apiKey, và webSearch.baseUrl chuyên dụng được ưu tiên trước models.providers.google.baseUrl. OpenClaw cũng không kế thừa các header của model provider ở đây, vì chúng “thuộc về endpoint của model provider, vốn có thể khác endpoint tìm kiếm web”, đồng thời giữ quyền quản lý Content-Type, x-goog-api-key và x-goog-api-client trên request tìm kiếm (Tài liệu tìm kiếm Gemini, ngày 21 tháng 9, 2026). Hai tuyến, độc lập có chủ đích.

Trước khi làm theo tutorial cũ: OpenClaw nói rằng họ “không cung cấp thiết lập OAuth Gemini CLI hoặc Antigravity OAuth mới”, viện dẫn việc kết thúc quyền truy cập Gemini CLI Login with Google dành cho người dùng phổ thông vào ngày 18 tháng 6, 2026 (tài liệu provider). Bài đăng chính thức của Google ngày 19 tháng 5, 2026 nói Gemini CLI và các tiện ích mở rộng Code Assist IDE ngừng phục vụ người đăng ký Google AI Pro và Ultra cùng người dùng miễn phí (blog dành cho nhà phát triển Google). Cả hai tuyên bố đều nói về bề mặt CLI và IDE, không nói về khóa API AI Studio — tuyến dùng khóa API là tuyến bên dưới.

Thiết lập khóa API Gemini

# The bundled google plugin reads either name.
export GEMINI_API_KEY="AIza..."   # or GOOGLE_API_KEY

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

# Auth alone does not change the default model — set it on purpose.
openclaw models list --provider google
openclaw models set google/<id-from-that-list>

Plugin đi kèm cũng đọc GEMINI_API_KEYS, GEMINI_API_KEY_1 và GEMINI_API_KEY_2 để xoay vòng khóa, cùng OPENCLAW_LIVE_GEMINI_KEY làm một giá trị ghi đè duy nhất (các plugin nhà cung cấp chính thức, ngày 21 tháng 9 năm 2026). Các biến này được ghi trong tài liệu là biến riêng của plugin google; tài liệu tham chiếu nhà cung cấp tùy chỉnh không liệt kê chúng cho một provider id do bạn tự khai báo, provider id này thiết lập khóa thông qua apiKey (cách khai triển ${ENV_VAR} được trình bày tại đó).

Dòng cuối quan trọng hơn vẻ ngoài của nó. openclaw configure “giữ lại một agents.defaults.model.primary hiện có khi bạn thêm hoặc xác thực lại một nhà cung cấp”, và openclaw models auth login cũng làm như vậy trừ khi bạn truyền --set-default (các quy tắc nhanh). Việc xác thực Gemini nhưng vẫn nhận câu trả lời từ mô hình cũ là hành vi được dự kiến, không phải lỗi.

Đừng sao chép model id từ bất kỳ hướng dẫn nào, kể cả hướng dẫn này. Khi đã cấu hình khóa, OpenClaw làm mới danh mục mô hình văn bản của Google AI Studio từ API models.list của Gemini, vì vậy các biến thể mới xuất hiện mà không cần bản phát hành OpenClaw — và chính các trang của OpenClaw cũng không thống nhất về id ví dụ: một nơi ghi google/gemini-3.5-flash, nơi khác ghi google/gemini-3.1-flash và google/gemini-3.1-pro-preview, còn công cụ tìm kiếm mặc định là gemini-3.6-flash. Danh sách trực tiếp là nguồn có thẩm quyền duy nhất. OpenClaw có chuẩn hóa một số tham chiếu cũ — google/gemini-3.1-pro được “chấp nhận và chuẩn hóa” thành google/gemini-3.1-pro-preview (các plugin nhà cung cấp chính thức) — và google/gemini-3-pro-preview “đã ngừng sử dụng vào ngày 2026-03-09”, với google/gemini-3.1-pro-preview được nêu là phiên bản thay thế (tài liệu nhà cung cấp, ngày 21 tháng 9 năm 2026).

Khóa API Gemini thực sự tính phí như thế nào

Token và tính năng grounding khi tìm kiếm là hai khoản mục riêng, nhưng thoạt nhìn trang của Google khiến chúng giống như một khoản. Mức giá Gemini Developer API bậc Standard theo mỗi 1 triệu token, lấy từ trang giá của Google (cập nhật lần cuối ngày 16 tháng 9 năm 2026, đọc ngày 21 tháng 9 năm 2026):

Hãy đọc cột cuối hai lần. Model tìm kiếm web Gemini mặc định của OpenClaw là gemini-3.6-flash, một mô hình Gemini 3.x có tính năng grounding “Không khả dụng” trong gói miễn phí của Google — vì vậy thiết lập tìm kiếm Gemini có sẵn cần một dự án tính phí, dù token của chính mô hình đó là miễn phí. Đơn vị tính cũng khác nhau: bản thân OpenClaw lưu ý rằng “grounding của Gemini 3 được tính phí theo mỗi truy vấn tìm kiếm, trong khi grounding của Gemini 2.5 được tính phí theo mỗi prompt”, và Google bổ sung rằng một yêu cầu “có thể tạo ra một hoặc nhiều truy vấn tới Google Search. Bạn sẽ bị tính phí cho từng truy vấn tìm kiếm riêng lẻ được thực hiện”. Chi phí grounding được cộng thêm vào chi phí token — “Chi phí cho Gemini luôn được áp dụng” (cả hai trích dẫn đều từ cùng trang giá). Ví dụ, một tháng có 6.500 truy vấn tìm kiếm Gemini 3.x sẽ tính phí 1.500 truy vấn trong số đó ở mức $14 cho mỗi 1.000, tức $21,00 chỉ riêng phí tìm kiếm, chưa bao gồm token.

Hai thông tin đầu vào khác từ cùng trang: gói trả phí bổ sung bộ nhớ đệm ngữ cảnh và Batch API với mức giảm 50% chi phí, đồng thời đảo ngược mục về việc sử dụng dữ liệu — nội dung ở gói miễn phí được “sử dụng để cải thiện sản phẩm của chúng tôi”, còn nội dung ở gói trả phí thì không, điều này quan trọng đối với một trợ lý luôn hoạt động. Gemini cũng chỉ là một trong các nhà cung cấp tìm kiếm của OpenClaw; DuckDuckGo (“Không có (không cần khóa)”), SearXNG (“Không có (tự lưu trữ)”) và Parallel Search (Free) (“Không có (Search MCP miễn phí)”) được liệt kê là các tùy chọn không cần khóa trong bảng nhà cung cấp tìm kiếm web của OpenClaw (tìm kiếm web, ngày 21 tháng 9 năm 2026), vì vậy “tôi có thực sự cần grounding của Gemini không” là câu hỏi đầu tiên hợp lý.

Định tuyến cuộc trò chuyện Gemini qua gateway tương thích với OpenAI

Tài liệu tham chiếu nhà cung cấp tùy chỉnh của OpenClaw nói rằng chỉ dùng các mục models.providers.<id> tường minh “khi bạn muốn ghi đè URL cơ sở, các header hoặc danh sách mô hình mặc định”, còn tài liệu tham chiếu cấu hình gateway liệt kê mười một giá trị api: openai-completions, openai-responses, openai-chatgpt-responses, anthropic-messages, google-generative-ai, google-vertex, github-copilot, bedrock-converse-stream, ollama, pi-messages và azure-openai-responses. Lược đồ cấu hình ở v2026.9.7 chấp nhận giá trị thứ mười hai, google-interactions, được thêm vào ngày 25 tháng 9 năm 2026. Tài liệu tham chiếu chưa liệt kê giá trị này, nhưng trang nhà cung cấp Google của OpenClaw ghi nhận đây là lựa chọn thay thế cần được chủ động bật cho phương thức truyền tải google-generative-ai mặc định, sử dụng Interactions API của Gemini dưới https://generativelanguage.googleapis.com/v1beta. Các mô hình Gemini của Kunavo được truy cập qua giao diện tương thích với OpenAI tại POST /v1/chat/completions (điểm cuối chat), và Kunavo không công bố generativelanguage, v1beta hoặc điểm cuối Interactions — vì vậy không adapter Google nào truy cập được nó, và tuyến có thể truy cập là một provider id riêng biệt, không bao giờ là plugin google được chuyển hướng.

{
  "models": {
    "mode": "merge",
    "providers": {
      "kunavo": {
        "baseUrl": "https://api.kunavo.com/v1",
        "apiKey": "${KUNAVO_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "gemini-3-8-flash",
            "name": "Gemini 3.8 Flash",
            "input": [
              "text",
              "image"
            ],
            "contextWindow": 1048576,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "kunavo/gemini-3-8-flash"
      }
    }
  }
}

Có bốn chi tiết mang tính nền tảng. Slug sử dụng dấu gạch ngang — id của Kunavo là gemini-3-8-flash trong khi id của Google và OpenClaw dùng dấu chấm, và đây là các chuỗi khác nhau. contextWindow được khai báo vì một mô hình tùy chỉnh không có siêu dữ liệu ngữ cảnh sẽ mặc định về ngân sách 200.000 token, làm lãng phí phần lớn cửa sổ mà danh mục của Kunavo ghi nhận ở đây (1.048.576 token — siêu dữ liệu của Kunavo, không phải giới hạn do Google công bố). input chỉ rõ hình ảnh vì OpenClaw mặc định mô hình tùy chỉnh chỉ hỗ trợ văn bản. Và cost bị bỏ qua, nên ước tính cục bộ của OpenClaw mặc định bằng không trên tuyến này: số tiền $0 là do thiếu siêu dữ liệu, không phải suy luận miễn phí.

Những gì tuyến này từ bỏ đã được ghi nhận trong tài liệu, không phải phỏng đoán. Với api: "openai-completions" tới một máy chủ không phải của OpenAI, OpenClaw buộc compat.supportsDeveloperRole: false và bỏ qua việc định hình yêu cầu gốc — không có service_tier, không có store Responses hoặc Completions, không có gợi ý bộ nhớ đệm prompt, không có định hình payload tương thích với suy luận (nhà cung cấp tùy chỉnh). Các tính năng bổ sung dành riêng cho Gemini cũng bị bỏ lại: params.cachedContent được ghi nhận cho các lần chạy Gemini trực tiếp, các biến xoay vòng khóa là tính năng của plugin, còn ánh xạ thinkingLevel / thinkingBudget của OpenClaw được mô tả cho nhà cung cấp google — việc chúng có tồn tại qua tuyến gateway hay không chưa được trang này xác minh.

Kunavo không cung cấp mô hình embedding, cũng không cung cấp mô hình chuyển văn bản thành giọng nói hoặc giọng nói thành văn bản. Vì vậy, các hợp đồng embedding và speech của plugin google vẫn sử dụng khóa Google bất kể cuộc trò chuyện được định tuyến như thế nào.

Về khả năng, hãy cẩn thận với nguồn mà bạn tin. Trang mô hình hiện tại của Google không còn hiển thị giới hạn token theo từng mô hình, vì vậy bất kỳ con số ngữ cảnh nào được trích dẫn ở nơi khác đều là bản sao từ một nguồn cũ hơn của ai đó. Danh mục của Kunavo đánh dấu khả năng xử lý hình ảnh, gọi hàm, streaming và ngữ cảnh dài cho các danh sách Gemini của mình, cùng khả năng suy luận cho tất cả trừ gemini-2-5-flash. Mỗi tuyên bố chỉ thuộc phạm vi của bên đã công bố nó — trước tiên hãy tự xác minh lệnh gọi công cụ trong tác vụ của bạn.

Định giá đúng mô hình bạn đã chọn

Theo từng mô hình, so với bậc Standard của Google, vì phiên bản so sánh chung cho cả dòng hiện nay là không đúng:

Mức giá của Kunavo lấy từ danh mục trực tiếp, còn mức giá của Google lấy từ trang giá được đọc ngày 21 tháng 9 năm 2026; thời gian giới thiệu kết thúc vào ngày 31 tháng 12 năm 2026, sau đó so sánh Flash lại đảo chiều.

Một ước tính minh họa, là phép tính token chứ không phải tác vụ OpenClaw được đo lường hay mức trần hóa đơn. Giả sử một tuần làm việc của trợ lý gửi 4.000.000 token đầu vào không được lưu trong bộ nhớ đệm và nhận 150.000 token đầu ra, không caching và không tìm kiếm. Với Gemini 3.8 Flash ở mức giá của Kunavo, chi phí là $2,49; cùng phép tính trên với mức giá Flash giới thiệu của Google là $3,56, tăng lên $7,13 theo mức giá năm 2027. Chạy cùng khối lượng trên Gemini 3.6 Flash tại Kunavo cho kết quả $4,99 — cao hơn con số giới thiệu của Google, đó chính là lý do model id, không phải tên nhà cung cấp, là yếu tố quyết định.

Số tiền trong danh mục của Kunavo là mức sàn tính phí chứ không phải mức trần: khi upstream báo chi phí, hóa đơn là giá trị lớn hơn giữa chi phí trong danh mục và chi phí upstream nhân với mức markup áp dụng. Phí bộ nhớ đệm, grounding tìm kiếm và lưu trữ nằm ngoài ví dụ này, còn mức nạp tối thiểu là $10 tín dụng trả trước — mức tối thiểu để nạp tiền, không phải phí tác vụ hay gói đăng ký. Xem chi tiết thanh toán và giá OpenClaw để biết toàn bộ chi phí vận hành.

Xác minh bằng một yêu cầu, sau đó đọc cả hai sổ cái

openclaw config validate
openclaw gateway restart
openclaw models list --provider kunavo
openclaw infer model run --model kunavo/gemini-3-8-flash --prompt "hi" --json

openclaw models list đọc danh mục đã công bố và openclaw models status hiển thị mặc định cùng trạng thái xác thực đã được phân giải; không lệnh nào chứng minh một tác vụ trả phí hoạt động, còn openclaw models set trên một nhà cung cấp đã biết sẽ lưu mô hình chưa có trong danh mục chỉ với một cảnh báo. openclaw doctor --json --severity-min info cũng hiển thị các mô hình đang hoạt động mà danh mục cục bộ không thể xác nhận (tài liệu CLI). Yêu cầu duy nhất ở trên là bằng chứng đầu tiên thực sự phát sinh chi phí.

Phân loại theo mã trạng thái. OpenClaw ghi nhận chữ ký model_not_found cho một máy chủ tương thích với OpenAI cục bộ, và ba trường mà nó nêu chính là ba trường mà một mục nhà cung cấp tùy chỉnh thiết lập: xác minh baseUrl bao gồm /v1, rằng api là "openai-completions" đối với backend /v1/chat/completions, và rằng models[].id là id thuần của nhà cung cấp, trong đó tiền tố nhà cung cấp chỉ được dùng lúc chọn (khắc phục sự cố). Với Kunavo, kiểm tra cho biết URL cơ sở đúng là một yêu cầu chưa xác thực tới đường dẫn API thực: GET https://api.kunavo.com/v1/models trả lời 401 với nội dung authentication_error, nghĩa là URL đúng nhưng khóa không hợp lệ. Host thuần và đường dẫn /v1 thuần không phải đường dẫn API và trả về HTML, vì vậy client trỏ tới một trong hai sẽ thất bại trước khi tiếp cận bất kỳ mô hình nào (kiểm tra ngày 21 tháng 9 năm 2026). Mã 403 là trường hợp cần dừng lại và đọc kỹ: OpenClaw cảnh báo mã này “có thể đến từ một lớp bảo mật upstream như CDN, WAF, quy tắc quản lý bot hoặc reverse proxy”, và một curl tối giản thành công không đảm bảo các yêu cầu kiểu SDK thực tế vượt qua cùng lớp đó. Xem không tìm thấy mô hình và khóa API Gemini không hoạt động để đọc phiên bản dài hơn.

Đối với tuyến gốc, hãy bắt đầu với ghi chú khóa API Gemini của Kunavo và Google AI Studio; đối với tuyến gateway, tạo khóa trong Khóa API và mở tài khoản Kunavo, sau đó làm theo hướng dẫn nhà cung cấp tùy chỉnh trong API tốt nhất cho OpenClaw. Hãy giữ tuyến đang hoạt động của bạn sẵn sàng trong khi kiểm thử.

Tuyến nào thắng trong trường hợp nào

Nếu bạn vẫn đang chọn nhà cung cấp thay vì cấu hình một nhà cung cấp, Giá API Gemini và API tương thích với OpenAI trình bày hai nửa của quyết định đó.

Câu hỏi thường gặp

Được thu thập cho trang này vào ngày 21 tháng 9 năm 2026: tài liệu về nhà cung cấp Google, plugin nhà cung cấp chính thức, tìm kiếm Gemini, tìm kiếm web, nhà cung cấp tùy chỉnh (cả tài liệu khái niệm và tài liệu tham chiếu gateway), quy tắc nhanh, mô hình CLI và khắc phục sự cố của OpenClaw; trang giá API Gemini của Google (cập nhật lần cuối ngày 16 tháng 9 năm 2026), trang mô hình, trang grounding bằng Google Search và bài đăng blog dành cho nhà phát triển ngày 19 tháng 5 năm 2026; mục đăng ký npm cho openclaw; cùng danh mục riêng của Kunavo. Ngày 1 tháng 10 năm 2026, các giá trị api của nhà cung cấp tùy chỉnh được kiểm tra lại dựa trên tài liệu tham chiếu gateway, trang nhà cung cấp Google, lược đồ cấu hình của OpenClaw và phương thức truyền tải Interactions trong mã nguồn của OpenClaw ở v2026.9.7. Yêu cầu trực tiếp duy nhất được thực hiện cho trang này là GET chưa xác thực tới /v1/models của Kunavo, để ghi nhận mã 401 được mô tả ở trên. Không nội dung nào ở đây được kiểm thử khi chạy với một bản cài đặt OpenClaw, trên endpoint của Kunavo hoặc của Google; mọi con số đô la đều là phép tính minh họa dựa trên mức giá đã công bố.