多帳號輪替與跨供應商容錯

跨 Claude、Codex、Gemini 的智慧認證資料排程：永遠不再碰到限速。

比喻：一家人有好幾張信用卡

你家有多張信用卡：

卡 A（太太的）：免年費、2% 回饋、額度 $5,000
卡 B（你的）：更高額度（$10,000），但每筆交易有手續費
卡 C（緊急用）：最高額度（$20,000），最高手續費，只在其他都刷爆時使用

聰明的家庭先用卡 A（最便宜），卡 A 額度到了換卡 B，緊急時才碰卡 C。

DuDuClaw 的帳號輪替對 API 認證資料做的是同一件事——自動、即時，帶健康監控和冷卻邏輯。

運作方式

帳號類型

系統支援兩種 API 認證資料：

OAuth Session — 連結到訂閱方案（Pro、Team、Max）。通常包含月度免費 API 呼叫配額。它們是「回饋卡」（優先使用）。

API Key — 按 token 付費。沒有配額限制，但每次呼叫都有成本。它們是「緊急卡」，可靠但昂貴。

四種策略

營運人員選擇一種輪替策略來管理帳號選擇方式：

Priority（優先順序） — 帳號按優先數字排列。系統總是使用最高優先且健康的帳號。像 VIP 名單：1 號處理所有工作直到無法繼續，然後 2 號接手。

請求到達
     |
     v
嘗試帳號 #1（priority: 1）
     |
  +--+--+
  |     |
健康   不健康
  |     |
  v     v
使用它  嘗試帳號 #2（priority: 2）
        |
     +--+--+
     |     |
   健康  不健康
     |     |
     v     v
   使用它  嘗試帳號 #3 ...

LeastCost（最低成本） — 優先選最便宜的。OAuth 帳號（包含在訂閱中）排在 API Key（按量付費）之前。同類帳號中，優先選剩餘配額最多的。

RoundRobin（輪流） — 在所有健康帳號之間均勻分配請求。防止任何單一帳號過載，均勻分散使用量（和成本）。

Failover（故障轉移） — 指定一個帳號為主要，其餘為備援。主要帳號處理 100% 流量，除非變得不健康。簡單且可預測。

健康追蹤

每個帳號有獨立的健康狀態：

帳號健康狀態：
     |
     +---> 健康
     |       一切正常運作
     |
     +---> 限速中
     |       短時間內太多請求
     |       冷卻時間：2 分鐘
     |
     +---> 預算耗盡
     |       月度支出上限已達
     |       冷卻時間：24 小時（至下個帳單週期）
     |
     +---> Token 即將過期
     |       OAuth token 接近到期
     |       預警於：到期前 30 天和 7 天
     |
     +---> 認證已死（Auth-Dead）
     |       Anthropic 直接拒絕了這個憑證——
     |       token 無效／過期，或該組織已停用
     |       Claude Code 訂閱存取
     |       冷卻時間：15 分鐘起跳，每再失敗一次
     |       就加倍，上限 6 小時
     |
     +---> 憑證損壞（Broken）
     |       儲存的憑證解不出來（或解出空字串）——
     |       開機時就被排除在輪替之外，不會拿著
     |       沒有憑證的殼去開子行程
     |
     +---> 錯誤
             其他非預期的失敗（網路、伺服器）
             冷卻時間：指數退避

帳號進入冷卻狀態時，輪替策略自動跳過它，使用下一個可用帳號。冷卻到期後，帳號自動恢復到輪替池中——但「認證已死」的帳號是例外：只有真的探測成功（見下）或重新儲存憑證，才能提前復活。「憑證損壞」的帳號則完全不會自己恢復，必須重新儲存憑證。

真探測，不再靠猜

過去復活一個帳號靠的是跑 claude auth status、相信它回報的 loggedIn: true。但這個訊號只證明環境裡「有某個」CLAUDE_CODE_OAUTH_TOKEN，跟「這個帳號的 token 是不是還能用」是兩回事——一顆已被撤銷或組織停用的 token 可以一直回報「已登入」，怎麼問都一樣。

對於自己存了 token 的 OAuth 帳號、以及 API key 帳號，輪替器現在會直接用該帳號自己的憑證，打一次零成本的 GET /v1/models 探測：

200 — 憑證有效，帳號復活，失敗次數歸零。
401 — token 本身無效，帳號維持停擺。
403 — 該組織已停用 Claude Code 訂閱存取，帳號維持停擺。
429 或網路錯誤 — 無法判斷，帳號維持原狀，下一輪再試。

被 API 明確拒絕（401/403）的憑證改成退避重試，不再每一輪都問一次：1 分鐘、2 分鐘、4、8、16，到 30 分鐘封頂。無法判斷的結果不會拖慢這個排程；憑證恢復可用、或實際請求又撞上一次認證失敗，排程就立刻歸零。

依賴 keychain 登入、沒有存 token 的帳號（沒有帳號專屬的憑證可探測）維持用 claude auth status——但一旦這類帳號進入「認證已死」，這個訊號就不再能提前復活它，只能等冷卻到期。

寫入前先驗證憑證

新增帳號（不論從儀表板或 accounts.add）現在會在寫入前先跑同一套探測：

憑證被拒絕（401）直接拒絕新增。
組織已停用（403）拒絕新增，並提示改用 API key 或洽組織管理員。
貼上短效 access token（sk-ant-at01-…，claude auth token 印出的那種）會被拒絕，並指引改跑 claude setup-token，取得輪替器真正要用的長效 sk-ant-oat01-… token。
若探測本身完全跑不了（多半是離線）——帳號仍會儲存，只是標記為未驗證，等下一輪健康檢查確認。

從終端機檢查憑證

duduclaw doctor 會為每個「自己存了 token 或金鑰」的 Anthropic 帳號各印一行：有效、token 無效（401）、組織停用（403），或無法連線。它跑的是與輪換器相同的零成本探測，且不會改動任何狀態，所以對著執行中的 gateway 跑也安全。只靠鑰匙圈登入的帳號會略過——這裡沒有可以拿去認證的東西。連不上網一律回報為警告，不會謊稱憑證已死。

同時，上方 claude auth status 那一行加了註記：它只證明登入檔或環境變數存在，不代表 token 仍然有效。

認證失效告警

當帳號池裡的每一個帳號同時卡在認證失敗，這已經不是單一帳號的冷卻問題，而是整個平台的斷線。DuDuClaw 會發一則 Activity Feed 事件，並推一則通知到受影響 agent 的通知管道，說明排程與自動回覆已停擺、請到儀表板的帳號設定處理。故障持續期間保持安靜（不會重複打擾），直到任一帳號再次認證成功，才發一次復原通知。

預算執行

每個帳號可設定月度支出上限：

發送請求前：
     |
     v
估算此請求的成本
  （基於輸入 token + 預期輸出 token）
     |
     v
是否會超出帳號的月度預算？
     |
  +--+--+
  |     |
 否     是
  |     |
  v     v
發送   跳過此帳號，
       嘗試輪替中的下一個

這防止意外帳單。營運人員設定每帳號預算，系統自動執行。帳號預算耗盡時，進入 24 小時冷卻，等待下個帳單週期。

與快取效率的整合

帳號輪替系統與快取效率追蹤攜手運作：

CostTelemetry 計算：
  cache_efficiency = cache_read / (input + cache_read + cache_creation)

如果 cache_efficiency < 30%：
  「我們正在為大多數 token 支付全價。
   考慮將更多查詢路由到本地推論。」
     |
     v
  自動增加信心路由器中對本地模型的偏好

這形成一個回饋迴圈：當雲端 API 使用效率低（低快取命中率）時，系統自動將更多流量轉移到本地推論，為受益於快取的查詢保留 API 配額。

Direct API 捷徑

對不需要完整 Claude CLI 管線的場景（簡單聊天回應），系統提供 Direct API 模式，直接呼叫 Anthropic Messages API：

簡單聊天查詢
     |
     v
Direct API 客戶端（單例 HTTP 客戶端）
     |
     v
加入帶快取提示的系統提示
  （告訴 API 伺服器快取此提示）
     |
     v
API 回應

因為系統提示被快取，後續使用相同系統提示的呼叫會直接命中快取，不必重新處理。這對重複性對話達到 95%+ 的快取命中率，大幅降低實際成本。

這為什麼重要

不間斷服務

限速是 API 服務的現實。沒有輪替，限速意味著你的 Agent 停止回應。有了輪替，流量在被限速的帳號冷卻期間無縫轉移到下一個可用帳號。

成本最佳化

LeastCost 策略確保免費配額（來自訂閱）優先消耗。付費 API 呼叫只在免費選項耗盡時才發生。對大多數使用者，這意味著大部分 API 使用量不需要額外付費。

預算控制

每帳號月度上限防止費用失控。搭配 CostTelemetry 儀表板，營運人員對每個 token 的去向和成本有完整的能見度。

免操心運作

整個系統是自動的。一旦設定完成，營運人員不需要手動切換帳號、監控限速或重新平衡流量。輪替策略全部搞定。

跨供應商容錯

搭配 DuDuClaw 的 Multi-Runtime 架構（Claude / Codex / Gemini / OpenAI-compat），帳號輪替延伸到跨供應商層級。FailoverManager 協調跨供應商的健康狀態：

主要供應商（Claude）被限速
     |
     v
FailoverManager 檢查替代方案：
  - Codex CLI 可用？→ 路由過去
  - Gemini CLI 可用？→ 路由過去
  - 本地推論可用？→ 路由過去
     |
     v
不可重試的錯誤？（認證失敗、帳單停權）
  → 標記供應商為不健康，較長冷卻時間
可重試的錯誤？（逾時、暫時性伺服器錯誤）
  → 短冷卻時間，很快重試

通道失敗追蹤

當通道回覆失敗時（面向使用者的路徑），系統會記錄結構化的失敗資料：

失敗紀錄 → ~/.duduclaw/channel_failures.jsonl：
  {
    "ts": "2026-04-15T10:30:00Z",
    "agent": "dudu",
    "channel": "telegram",
    "reason": "RateLimited",      // 或 Billing、Timeout、BinaryMissing 等
    "account": "oauth-pro-1",
    "message_zh": "API 用量已達上限..."
  }

失敗類別會渲染成分類專屬的 zh-TW 訊息，取代舊版那句籠統的「請執行 claude auth status」提示。失敗日誌會餵進儀表板供觀察。

CLI 執行檔探測

DuDuClaw 以系統服務方式執行（透過 duduclaw service install），這代表 PATH 可能不包含 AI CLI 執行檔的位置。which_claude() 函式會探測：

Homebrew（Intel + Apple Silicon 路徑）
Bun 全域安裝
Volta 工具鏈
npm 全域
.claude/bin
.local/bin
asdf shims
NVM 版本目錄

這確保由 launchd/systemd 啟動的 gateway 能找到 CLI 執行檔，不依賴 PATH 繼承。

與其他系統的互動

Multi-Runtime：帳號輪替橫跨 Claude、Codex、Gemini 與 OpenAI-compat 供應商運作。
信心路由器：路由到本地推論的查詢不消耗任何 API 帳號，延長配額使用期限。
CostTelemetry：提供支持預算執行和快取效率回饋的數據。
FailoverManager：協調跨供應商的健康追蹤與容錯決策。
Direct API：為簡單查詢提供高快取命中率的旁路。
儀表板：即時顯示帳號健康、使用量、剩餘預算與通道失敗日誌。

總結

API 認證資料是有限的資源；在多供應商世界裡，它們是一整支有限資源組成的車隊。多帳號輪替將它們視為一支受管理的車隊。系統會自動跨供應商選擇最佳可用選項、冷卻過載帳號、執行預算，並在雲端使用效率低時轉移到本地推論。