[!IMPORTANT] 非官方互通性研究專案。 本專案與 Google 無任何關聯、合作或背書關係。使用第三方客戶端或閘道可能違反 Google 服務條款 —— 你的帳戶，風險自負。你需要自行準備合資格的 Google 帳戶與相容的 OAuth client profile；本專案不分發任何憑證、Token 或 Google 二進位程式。請先詳閱完整免責聲明。

為什麼需要 Gemini App2API？

_{🧢 MGGA — Make Gemini Great Again：頂級 GigaChad 底層模型，不該被困在消費級聊天外殼裡。}

為什麼在官方 Gemini App 內處理大型程式開發時總是綁手綁腳、容易遺失上下文？瓶頸往往不在底層模型，而在於官方 App 面向一般消費者所設計的封閉外殼（Harness）。

• 將模型解放到真正的工程工具鏈： 透過標準 /v1/chat/completions 與 /v1/responses 介面，直接連接 Cursor、Cline、Roo Code、OpenAI Codex CLI、PI-Desktop、Cherry Studio 或 Open WebUI，由你的本地客戶端完整掌管對話歷史與專案工具執行。
• 原生 HTTP/2 協定直連（非脆弱網頁爬蟲）： 直接使用 Node.js 內建模組（node:http2、node:crypto）實作 Gemini Robin 原生 HTTP/2 傳輸與可續傳圖片上傳，不依賴無頭瀏覽器、網頁 Cookie 擷取或修改桌面版二進位檔案。
• 多帳戶池應對滾動額度視窗： 高強度 Agent 多輪工具呼叫容易迅速觸及單一帳戶的 5 小時或每週滾動上限。支援匯集多個你合法持有的帳戶，提供軟性 Session 路由偏好、唯讀官方用量進度條與自動配額容錯（Failover）。
• 專為 Agent 迴圈穩定性設計： 當上游長連線在中途斷開時，自動保留已送出的可用程式碼與工具呼叫並平穩收尾，防止 Agent 客戶端丟棄數千 bytes 已生成內容或陷入無限重送整份歷史的死循環（詳見完成與失敗語義）。
• 誠實標示上游邊界： 解耦本地客戶端並不代表繞過 Google 伺服器管控；所有上游 Context 容量、頻率限制、安全審查與帳戶方案權限依然由 Google 強制執行。

架構方案比較

核心特色

• 精確定義的 OpenAI 相容介面（Chat 與 Responses）： 支援 GET /v1/models、POST /v1/chat/completions 與 POST /v1/responses，涵蓋 JSON 與增量 SSE 串流、reasoning_effort / reasoning.effort 思考強度對應，以及靜態 PNG/JPEG/WebP 圖片輸入。
• 客戶端自主工具權限（Caller-Owned Tools）： 由客戶端宣告函數與 JSON Schema（含 Responses type: "namespace" 工具分組）、在本機執行獲准呼叫並回傳結果；閘道嚴格驗證工具名稱與參數結構，絕不代為執行 Shell 指令或存取你的專案目錄。
• 零第三方 Runtime 依賴與嚴密安全邊界： 零外部生產套件；強制檢查 0700/0600 私密目錄與檔案權限、採用 scrypt 管理密碼雜湊、以 SHA-256 驗證雜湊搭配 0600 本機私密金鑰保存（僅於建立當下或通過驗證與 CSRF 保護後按需回傳）、嚴格 Origin/Host/X-CSRF-Token 後台寫入保護，以及預設關閉且具 SSRF 防護的公開圖片下載。
• 中英雙語現代化維運後台（English / 繁體中文）： 支援桌面與手機響應式檢視及深淺色主題；內建帳戶池狀態脈搏與請求延遲快照圖、側欄帳戶檢視器（Inspector Drawer）、一鍵批量唯讀更新 目前用量（Current usage） 與 每週限額（Weekly limit）、客戶端快速連接設定範本（Codex CLI、Cline、cURL）、可隨時複製或撤銷的 API 金鑰管理、明確記錄或確認接受 Gemini 服務條款，以及遮罩後的上游 HTTP/gRPC 診斷資訊。

淺色主題 —— 帳戶側欄檢視與狀態脈搏	手機版後台 —— 繁體中文介面

快速開始

1. 準備工作

• Node.js 22+（>= 22.0.0）、npm、現代瀏覽器，以及具備相應 Gemini 模型權限的 Google 帳戶（適用於 macOS 與 Linux）。
• 從獲授權的私密來源取得相容的靜態 OAuth client profile（本儲存庫不隨附任何憑證，亦無法以 Google AI Studio API key 替代）。請先參閱私密初始化與 Profile 格式要求。

2. 初始化並啟動閘道

在專案根目錄執行：

npm ci --omit=dev --ignore-scripts
export GATEWAY_DATA_DIR="$HOME/.gemini-app2api"

# 建立權限為 0600 的私密 .env 設定檔（若已存在則不覆寫）：
test -e .env || cp .env.example .env
chmod 600 .env
# 編輯 .env，將 GATEWAY_ADMIN_PASSWORD 設為獨立的 12–256 字元密碼。

node bin/gemini-gateway init
node bin/gemini-gateway import-profile < /private/path/oauth-profile.json
node bin/gemini-gateway start

偏好使用 Docker？ 請參閱強化安全設定的 Docker Compose 部署指南（預設以 uid 1000、唯讀根目錄、最小權限及本機 loopback 連接埠運行）。

3. 登入 Google 帳戶並建立客戶端金鑰

在瀏覽器開啟 http://127.0.0.1:18989/admin/：

1. 輸入 GATEWAY_ADMIN_PASSWORD 登入後台（若留空，僅限本機 loopback 免密碼管理；遠端連線必須設定密碼與 TLS 反向代理）。
2. 在 帳戶（Accounts） 頁面點擊 + Google 登入，親自於瀏覽器完成 Google 授權與 MFA 驗證。
3. 在帳戶卡片點擊 Test 測試模型連線（注意：Test 會發送真實請求並消耗配額；單純完成 OAuth 登入不代表模型權限已驗證）。
4. 前往 API 金鑰（API keys）→ 建立金鑰，建立並複製客戶端金鑰（之後亦可在該頁隨時複製、顯示或撤銷有效金鑰）。

連接你的客戶端

在任何支援自訂 OpenAI 相容介面的客戶端填入以下設定：

測試模型清單連線（不消耗生成額度）：

curl -fsS http://127.0.0.1:18989/v1/models \
  -H "Authorization: Bearer $GEMINI_GATEWAY_KEY"

發送對話請求（如需增量串流，請在 JSON 加入 "stream": true 並搭配 curl -N）：

curl -fsS http://127.0.0.1:18989/v1/chat/completions \
  -H "Authorization: Bearer $GEMINI_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-argon","messages":[{"role":"user","content":"Hello!"}]}'

常用客戶端設定範例

model = "gemini-hydrogen" # 或改設 "gemini-argon" 用於旗艦 Pro 推理
model_provider = "gemini_app2api"
model_reasoning_summary = "none"
web_search = "disabled"

[model_providers.gemini_app2api]
name = "Gemini App2API"
base_url = "http://127.0.0.1:18989/v1"
env_key = "GEMINI_GATEWAY_KEY"
wire_api = "responses"

模型與支援能力

模型別名對應 Gemini App 原生執行模式，並非 Google Cloud Vertex / AI Studio 的固定版本代號；實際可用性取決於各登入帳戶的上游方案權限。context_window: 128000（gemini-argon）與 context_window: 512000（gemini-hydrogen）為根據單輪長上下文召回率、prefill 延遲及閘道 4 MiB 請求上限實測訂立之客戶端建議預算，並非閘道強制截斷上限或 Google 官方 SLA 保證容量。

配額消耗提醒：gemini-argon vs gemini-hydrogen

[!WARNING] 在相同的程式開發任務下，gemini-argon 消耗的帳戶配額約為 gemini-hydrogen 的 60x。 以單一 Gemini AI Pro 帳戶為例，在 gemini-argon 上僅執行 ~4-5 輪重度編碼任務（約 15 KB 輸出）即可能耗盡整個 5 小時滾動視窗（觸發 429 NATIVE_QUOTA_EXHAUSTED）；相較之下，gemini-hydrogen 在同一個 5 小時視窗內可容納約 ~290 輪重度編碼任務（或約 ~1,800 步 Agent tool_call 工具呼叫），且回應速度快約 ~2x-4x。建議將 gemini-hydrogen 作為日常多輪程式開發與工具呼叫的主力模型，並將 gemini-argon 留給架構規劃、疑難排錯，或已配置多帳戶池自動切換（GATEWAY_QUOTA_FAILOVER=1）的環境。

以下為使用相同真實工程任務（非空白測試）透過 GetUsageInfo 實測之配額消耗對照（Gemini AI Pro 帳戶，付費與試用方案實測比例為 1:1）：

以上數據為透過唯讀 GetUsageInfo 介面觀測所得之實測經驗值（並非 Google 官方 SLA 保證數據），上游配額權重與視窗計算方式可能隨時調整。

支援功能範圍

安全運行與操作原則

• 嚴格保護私密憑證： 切勿公開或提交 .env、OAuth client profile、refresh token、API 金鑰或 GATEWAY_DATA_DIR 目錄。詳見安全性政策。
• 對話歷史與執行權歸屬客戶端： 閘道不會代執行任何本機指令、不會暗中摘要或刪減歷史訊息，亦絕不在上游發生降級時暗中替換成低階模型。
• 誠實標示中斷與未完成狀態： 已輸出可用內容但中途斷線的串流會附帶明確的 incomplete: true 標記收尾，以保護客戶端已收到的工作成果；若需判斷上游是否完整結束，請一併檢查 incomplete 欄位。詳見完成與失敗語義。
• 審慎配置自動恢復： 開啟 GATEWAY_QUOTA_FAILOVER=1 或 GATEWAY_AUTOMATIC_RECOVERY=1 可在單一帳戶觸頂或瞬斷時自動切換其他合資格帳戶，但故障重試亦可能消耗額外配額。詳見維運設定與鎖與限制清單。

文件索引