OpenClaw 智能路由升級：導入 Gemini 3.5 Flash 的極速實裝計畫

為了進一步提升自動化流程的執行效率並控制運算成本，OpenClaw 個人知識作業系統 (PKOS) 正式迎來核心升級！本計畫旨在引進 Google I/O 2026 最新發布之 Gemini 3.5 Flash，全面替換舊有的 gemini-2.0-flash，並整合其「4 倍極速、思考等級控制 (Thinking Levels) 與 Agentic 原生優化」之核心優勢，以徹底解決先前高負載下的 429 RESOURCE_EXHAUSTED（資源耗盡）告警，保障系統的極致穩定性。

🚀 核心架構升級與審查重點

1. API 金鑰與通道安全
本計畫將直接調用系統環境變數中已配置之 GEMINI_API_KEY，透過 google-genai 正式 SDK 直連，不額外增加多餘的計費節點，且能完全釋放 Gemini 3.5 Flash 極高 Rate Limits（速率限制）的特點，在面對複雜任務時依然能保持穩定性。

2. 智能分流與路由權衡 (#權衡分析)
目前系統的雲端主力為「ChatGPT Pro OAuth (無限吃到飽通道)」，而 Gemini 3.5 Flash 將作為「最速雲端備援通道」與「長程 Agentic 工作流（如 CKO 日記編譯、YouTube 專家系統、/video 製片流水線）的特定首選模型」。這能顯著降低主通道壓力，並大幅提升非同步背景任務的執行速度。

3. 啟用「動態推理深度 (Thinking Levels)」
在 model_selector.py 路由中心中，我們將透過新版 SDK 配置 Gemini 3.5 Flash 的 thinking_budget（推理預算）。在 Medium/Low 複雜度的日常任務使用標準模式；而在 CKO 深度知識編譯、ADR 自動生成等 High/Ultra 任務中，自動激發 3.5 Flash 的 High-effort 強推理能力，以獲取最嚴謹 of 邏輯演繹。

🛠️ 預期變更與組件實裝

1. 架構決策記錄 (ADR) 歸檔

起草並歸檔 ADR，以固化本次架構升級的技術決策：

• 新增文件： ADR_003_Adopt_Gemini_3_5_Flash_In_Agentic_Workflows.md
• 核心內容： 詳述從 gemini-2.0-flash 升級至 gemini-3.5-flash 的決策脈絡、系統思考與成本/性能權衡。

2. 智能路由中心 (Model Selector) 重構

更新動態分流引擎，將備用與專屬 Gemini 通道全面升級：

• 修改檔案： model_selector.py
• 重構細節： 將 _call_gemini 內部的 model 硬編碼 gemini-2.0-flash 升級為 gemini-3.5-flash；在模型清單（Catalog）中更新規格說明；並加入對 thinking 推理預算參數的設定支援。

3. 整合驗證與實體測試 (Tests)

建立獨立的測試與驗證腳本，以確保 API 連通性與路由機制運作無誤：

• 新增檔案： test_gemini_35_integration.py
• 驗證內容： 輕量級獨立測試，載入環境變數並直連調用 gemini-3.5-flash，實時監測 Token 消耗並輸出標準繁體中文結果。

🔍 嚴謹的驗證計畫 (Verification Plan)

自動化測試項目

1. 連通性驗證： 執行 python scripts/test_gemini_35_integration.py，確保 API 能在 5 秒內返回正確回應。
2. 分流邏輯驗證： 運行 python scripts/test_model_routing_v3.py，確保 8/8 測試用例 100% 綠色通過，完美相容現有智能路由。

人工驗證項目

檢查系統控制台與 PM2 背景日誌，確保在長程工作流中沒有任何 Vertex AI 429 或模型調用異常報錯。