使用 Gemini 的 OpenClaw：模型設定、API 金鑰與成本檢查

OpenClaw 透過其內建的 google 外掛程式連線到 Gemini：設定 GEMINI_API_KEY 或 GOOGLE_API_KEY，執行 openclaw onboard --auth-choice gemini-api-key，然後明確設定模型——因為加入驗證資訊不會變更預設模型。大多數設定文章忽略的部分是，使用 AI Studio 金鑰時，OpenClaw 有三個獨立的 Gemini 介面，每個介面都有自己的憑證、端點與費用。（Vertex AI 是第四條獨立的憑證路徑，透過 gcloud Application Default Credentials 使用，本頁不涵蓋。）讓聊天正常運作不會啟用 Gemini 搜尋，而啟用 Gemini 搜尋可能會向聊天路徑從未使用的 Google 專案收取費用。

Gemini 整合不是獨立安裝項目。它以內建的 google provider 外掛程式形式隨 OpenClaw 本身提供（官方 provider 外掛程式，2026 年 9 月 21 日），而 OpenClaw 採用 MIT 授權，並以 openclaw@2026.9.5 發布於 npm，需要 Node >=24.16.0 <25 || >=26.1.0（npm registry，2026 年 9 月 21 日）。軟體本身不收費；以下內容全部關於金鑰的成本。

三個 Gemini 介面，三組憑證

優先順序規則才是實用的部分。Gemini 網頁搜尋會先讀取 plugins.entries.google.config.webSearch.apiKey，再讀取 GEMINI_API_KEY，接著讀取 models.providers.google.apiKey，而專用的 webSearch.baseUrl 會優先於 models.providers.google.baseUrl。OpenClaw 在此也不會繼承模型 provider 的標頭，因為它們「屬於模型 provider 端點，而該端點可能與網頁搜尋端點不同」，並在搜尋請求中保留 Content-Type、x-goog-api-key 與 x-goog-api-client 的管理權（Gemini 搜尋文件，2026 年 9 月 21 日）。兩條路徑刻意保持獨立。

在遵循較舊的教學之前請注意：OpenClaw 表示它「不提供新的 Gemini CLI OAuth 或 Antigravity OAuth 設定」，並指出消費者 Gemini CLI Login with Google 存取權已於 2026 年 6 月 18 日結束（provider 文件）。Google 於 2026 年 5 月 19 日發布的文章表示，Gemini CLI 與 Code Assist IDE 擴充功能將停止向 Google AI Pro 與 Ultra 訂閱者及免費使用者提供服務（Google developers blog）。兩項說明都針對 CLI 與 IDE 介面，而非 AI Studio API 金鑰——以下採用的是 API 金鑰路徑。

設定 Gemini API 金鑰

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

內建外掛程式也會讀取 GEMINI_API_KEYS、GEMINI_API_KEY_1 與 GEMINI_API_KEY_2 以進行輪替，並讀取 OPENCLAW_LIVE_GEMINI_KEY 作為單一覆寫值（官方 provider 外掛程式，2026 年 9 月 21 日）。這些變數被記載為 google 外掛程式自己的變數；自訂 provider 參考文件並未列出它們可供你自行宣告的 provider id 使用，後者會透過 apiKey 設定金鑰（其中顯示了 $${ENV_VAR} 的展開）。

最後一行的重要性超乎表面。openclaw configure「會在你加入或重新驗證 provider 時保留現有的 agents.defaults.model.primary」，而 openclaw models auth login 也會如此，除非你傳入 --set-default（快速規則）。完成 Gemini 驗證後仍從舊模型取得回答是預期行為，不是錯誤。

不要從任何教學（包括本篇）複製模型 id。設定金鑰後，OpenClaw 會透過 Gemini models.list API 重新整理 Google AI Studio 的文字模型目錄，因此新變體會在不發布 OpenClaw 新版本的情況下出現——而且 OpenClaw 自己的頁面對範例 id 的說法不一致，一處命名 google/gemini-3.5-flash，另一處命名 google/gemini-3.1-flash 與 google/gemini-3.1-pro-preview，並將搜尋工具預設為 gemini-3.6-flash。即時清單才是唯一權威來源。OpenClaw 確實會正規化部分舊版參照——google/gemini-3.1-pro「會被接受並正規化」為 google/gemini-3.1-pro-preview（官方 provider 外掛程式）——而 google/gemini-3-pro-preview「已於 2026-03-09 退役」，並將 google/gemini-3.1-pro-preview 指定為其替代項目（provider 文件，2026 年 9 月 21 日）。

Gemini API 金鑰實際計費的項目

詞元與搜尋資訊佐證是兩個收費項目，而 Google 的頁面乍看之下像是一個項目。標準層級 Gemini Developer API 每 100 萬詞元的費率，取自Google 的定價頁面（最近更新於 2026 年 9 月 16 日，於 2026 年 9 月 21 日查閱）：

請把最後一欄讀兩遍。OpenClaw 預設的 Gemini 網頁搜尋模型是 gemini-3.6-flash，這是 Gemini 3.x 模型，而其搜尋資訊佐證功能在 Google 免費層級為「不提供」——因此，即使同一模型的詞元免費，開箱即用的 Gemini 搜尋設定仍需要已啟用計費的專案。單位也不同：OpenClaw 本身指出，「Gemini 3 的搜尋資訊佐證按每次搜尋查詢計費，而 Gemini 2.5 的搜尋資訊佐證按每個提示計費」，Google 另補充說，一個請求「可能會對 Google Search 產生一個或多個查詢。你會為執行的每個個別搜尋查詢付費」。搜尋資訊佐證的費用疊加在詞元成本之上——「Gemini 的費用一律適用」（兩段引文皆出自同一個定價頁面）。舉例來說，一個月執行 6,500 次 Gemini 3.x 搜尋查詢，其中 1,500 次按每 1,000 次 $14 計費，僅搜尋費用就是 $21.00，尚未計入任何詞元費用。

同一頁面還有兩項資訊：付費層級增加上下文快取，以及可降低 50% 成本的 Batch API；同時也改變資料使用說明——免費層級內容會「用於改善我們的產品」，付費內容則不會，這對全天候助理很重要。Gemini 也只是 OpenClaw 的搜尋 provider 之一；其網頁搜尋 provider 表將 DuckDuckGo（「無（免金鑰）」）、SearXNG（「無（自行託管）」）與 Parallel Search (Free)（「無（免費 Search MCP）」）列為免金鑰選項（網頁搜尋，2026 年 9 月 21 日），因此「我真的需要 Gemini 搜尋資訊佐證嗎」是合理的第一個問題。

透過 OpenAI 相容閘道路由 Gemini 聊天

OpenClaw 的自訂 provider 參考文件表示，只有在「想要覆寫預設基底 URL、標頭或模型清單」時才使用明確的 models.providers.<id> 項目，而閘道設定參考文件列出十一個 api 值：openai-completions、openai-responses、openai-chatgpt-responses、anthropic-messages、google-generative-ai、google-vertex、github-copilot、bedrock-converse-stream、ollama、pi-messages 與 azure-openai-responses。v2026.9.7 的設定結構描述接受第十二個值 google-interactions，於 2026 年 9 月 25 日加入。參考文件尚未列出它，但 OpenClaw 的Google provider 頁面將其記載為預設 google-generative-ai 傳輸方式的選擇性替代方案，使用 Gemini 的 Interactions API，位於 https://generativelanguage.googleapis.com/v1beta。Kunavo 的 Gemini 模型透過其 OpenAI 相容介面，在 POST /v1/chat/completions（聊天端點）上提供；Kunavo 沒有發布 generativelanguage、v1beta 或 Interactions 端點——因此 Google 的介面都無法連到它，而可行的路徑是獨立的 provider id，絕不是重新導向的 google 外掛程式。

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

那裡有四個不可忽略的細節。slug 使用連字號——Kunavo 的 id 是 gemini-3-8-flash，而 Google 與 OpenClaw 的 id 使用點號；它們是不同的字串。宣告 contextWindow 是因為沒有內容中繼資料的自訂模型會退回 200,000 權杖的預算，浪費 Kunavo 目錄在此記載的大部分視窗（1,048,576 個權杖——這是 Kunavo 的中繼資料，不是 Google 發布的限制）。input 會指定圖片支援，因為 OpenClaw 預設自訂模型僅支援文字。而 cost 被省略，因此 OpenClaw 的本機估算在此路徑上預設為零：$0 的讀數代表缺少中繼資料，不代表推論免費。

此路徑放棄的功能有文件依據，而不是猜測。在非 OpenAI 自有主機上使用 api: "openai-completions" 時，OpenClaw 會強制使用 compat.supportsDeveloperRole: false 並略過原生請求塑形——沒有 service_tier，沒有 Responses 或 Completions store，沒有提示快取提示，也沒有 reasoning-compat payload 塑形（自訂 provider）。Gemini 專屬的額外功能也會留在後方：params.cachedContent 已記載可用於直接 Gemini 執行，金鑰輪替變數是外掛程式功能，而 OpenClaw 的 thinkingLevel／thinkingBudget 對應是針對 google provider 所描述的——它是否能在閘道路徑上保留，並不是本頁驗證過的事項。

Kunavo 不提供 embedding 模型，也不提供文字轉語音或語音轉文字模型。因此 google 外掛程式的 embedding 與語音合約無論聊天如何路由，都會繼續使用 Google 金鑰。

談到能力時，請小心確認你引用的是誰的說法。Google 目前的模型頁面不再呈現各模型的權杖限制，因此其他地方引用的內容長度數字都是某人從較舊來源複製而來的內容。Kunavo 的目錄在其 Gemini 清單上標示 vision、function calling、streaming 與長內容，而除 gemini-2-5-flash 外的所有模型都標示 thinking。每項說法都只適用於發布該說法的人或來源——請先在自己的工作上驗證工具呼叫。

為你實際選擇的模型定價

逐一比較各模型，採用 Google 標準層級，因為今天以整個系列來比較是錯誤的：

Kunavo 費率取自即時目錄，Google 費率取自 2026 年 9 月 21 日查閱的定價頁面；初期優惠期間於 2026 年 12 月 31 日結束，之後 Flash 比較會再次反轉。

一個實際估算，這是權杖算術，不是經測量的 OpenClaw 工作，也不是帳單上限。假設一週的助理工作會傳送4,000,000 個未快取輸入權杖並接收150,000 個輸出權杖，不使用快取，也不使用搜尋。使用 Gemini 3.8 Flash 並採 Kunavo 費率，費用為 $2.49；以 Google 導入期間的 Flash 費率計算相同算術，費用為 $3.56，按 2027 年費率則上升至 $7.13。在 Gemini 3.6 Flash 上以 Kunavo 執行相同用量，費用為 $4.99——高於 Google 導入期間的數字，這正是模型 id，而不是 provider 名稱，才是決策依據的原因。

Kunavo 的目錄金額是計費下限，而不是上限：當上游回報其費用時，帳單會取目錄成本與上游成本乘以適用加成兩者中較高者。快取費用、搜尋 grounding 與託管不包含在此範例中，而最低加值金額為預付額度中的 $10——這是資金下限，不是工作費或訂閱費。請參閱計費詳細資訊與 OpenClaw 定價，了解完整的運作帳單。

先用一項請求驗證，再讀取兩本帳

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 讀取已發布的庫存，而 openclaw models status 顯示解析後的預設值與驗證狀態；兩者都不能證明付費工作可成功執行，而對已知 provider 執行 openclaw models set 時，對未列入目錄的模型只會儲存並顯示警告。openclaw doctor --json --severity-min info 也會顯示本機目錄無法確認的作用中模型（CLI 參考）。上面的單一請求才是第一項會產生成本的證據。

依狀態碼進行分類處理。OpenClaw 記載了本機 OpenAI 相容伺服器的 model_not_found 特徵，而它列出的三個欄位正是自訂 provider 項目設定的三個欄位：確認 baseUrl 包含 /v1，確認對於 /v1/chat/completions 後端 api 為 "openai-completions"，並確認 models[].id 是該 provider 內部使用、不含 provider 前綴的 id，provider 前綴只在選取時使用（疑難排解）。針對 Kunavo，能告訴你基底 URL 正確的檢查方式，是向真正的 API 路徑發出未驗證請求：GET https://api.kunavo.com/v1/models 會以 authentication_error 內容回傳 401，表示 URL 正確而金鑰不正確。純主機名稱與純 /v1 路徑都不是 API 路徑，會回傳 HTML，因此指向任一者的用戶端會在到達模型前失敗（查核日期：2026 年 9 月 21 日）。遇到 403 時，需要停下來仔細閱讀回應：OpenClaw 警告它「可能來自上游安全層，例如 CDN、WAF、機器人管理規則或反向代理」，而成功的最小 curl 並不保證真正的 SDK 形式請求能通過同一層。請參閱找不到模型與Gemini API 金鑰無法運作，了解較完整的版本。

對於原生路由，請從 Kunavo 的 Gemini API 金鑰說明和 Google AI Studio 開始；對於閘道路由，請在 API 金鑰中建立金鑰並開立 Kunavo 帳戶，然後依照OpenClaw 的最佳 API中的自訂提供者教學操作。測試期間請保留目前使用的路由。

哪條路由勝出，取決於

如果您還在選擇提供者，而不是設定提供者，Gemini API 定價和OpenAI 相容 API涵蓋了這項決策的兩個面向。

常見問題

本頁於 2026 年 9 月 21 日擷取：OpenClaw 的 Google 提供者、官方提供者外掛程式、Gemini-search、web-search、自訂提供者（概念與閘道參考）、quick-rules、CLI-models 和疑難排解文件；Google 的 Gemini API 定價頁面（最後更新於 2026 年 9 月 16 日）、模型頁面、Google Search grounding 頁面，以及其 2026 年 5 月 19 日的開發者部落格文章；openclaw的 npm registry 項目；以及 Kunavo 自有的目錄。2026 年 10 月 1 日，根據閘道參考、Google 提供者頁面，以及 OpenClaw v2026.9.7 原始碼中的設定結構描述和 Interactions 傳輸，重新核對了自訂提供者 api值。本頁唯一發出的即時請求，是未驗證的 GET至 Kunavo 的/v1/models，用於記錄上述的 401。本文沒有任何內容在 OpenClaw 安裝、Kunavo 端點或 Google 端點上進行執行時測試；所有美元數字都是根據已發布費率計算的示意算術。