マルチアカウントローテーション＆クロスプロバイダーフェイルオーバー

Claude、Codex、Geminiをまたぐインテリジェントな認証情報スケジューリング——レート制限にもう遭わない。

たとえ話：家族のクレジットカード

家族が複数のクレジットカードを持っています：

カードA（妻の）：年会費無料、2%キャッシュバック、限度額$5,000
カードB（自分の）：高い限度額（$10,000）だが取引ごとに手数料
カードC（緊急用）：最高限度額（$20,000）、最高手数料、他が限度額に達した時だけ使用

賢い家族はまずカードA（最安）を使い、限度額に達したらカードBに切り替え、緊急時だけカードCを使います。

DuDuClawのアカウントローテーションはAPI認証情報に対してまったく同じことを行います——自動的に、リアルタイムで、ヘルスモニタリングとクールダウンロジック付きで。

仕組み

アカウントタイプ

システムは2種類のAPI認証情報をサポートします：

OAuthセッション — サブスクリプションプラン（Pro、Team、Max）に連携。通常、サブスクリプションの一部として月間の無料API呼び出し枠を含みます。「キャッシュバックカード」——優先して使用。

APIキー — トークン従量制。クォータ制限なしですが、すべての呼び出しにコストが発生。「緊急カード」——信頼できるが高コスト。

4つの戦略

運用者が1つのローテーション戦略を選択し、アカウントの選択方法を管理します：

Priority（優先順位） — アカウントに優先度番号を付与。システムは常に最も高い優先度でヘルシーなアカウントを使用。VIPリストのように：#1がすべての仕事を処理し、対応できなくなると#2が引き継ぎます。

リクエスト到着
     |
     v
アカウント#1を試行（priority: 1）
     |
  +--+--+
  |     |
ヘルシー  アンヘルシー
  |      |
  v      v
使用    アカウント#2を試行（priority: 2）
        |
     +--+--+
     |     |
   ヘルシー  アンヘルシー
     |      |
     v      v
   使用    アカウント#3を試行 ...

LeastCost（最低コスト） — 最も安いオプションを優先。OAuthアカウント（サブスクリプション込み）がAPIキー（従量制）より先。同タイプのアカウント間では、残りクォータが最も多いものを優先。

RoundRobin（ラウンドロビン） — すべてのヘルシーなアカウント間でリクエストを均等に分配。単一アカウントの過負荷を防ぎ、使用量（とコスト）を均一に分散。

Failover（フェイルオーバー） — 1つのアカウントをプライマリ、残りをバックアップに指定。プライマリがトラフィックの100%を処理、アンヘルシーにならない限り。シンプルで予測可能。

ヘルストラッキング

各アカウントが独立したヘルスステータスを持ちます：

アカウントヘルス状態：
     |
     +---> ヘルシー
     |       すべて正常動作中
     |
     +---> レート制限中
     |       短期間に多すぎるリクエスト
     |       クールダウン：2分
     |
     +---> 予算枯渇
     |       月間支出上限に到達
     |       クールダウン：24時間（次の請求サイクルまで）
     |
     +---> トークン期限切れ間近
     |       OAuthトークンが有効期限に接近
     |       警告：期限の30日前と7日前
     |
     +---> 認証死亡（Auth-Dead）
     |       Anthropicが認証情報そのものを拒否——
     |       トークンが無効／期限切れ、または組織が
     |       Claude Codeサブスクリプションアクセスを無効化
     |       クールダウン：15分から開始し、失敗のたびに
     |       倍増、上限6時間
     |
     +---> 破損（Broken）
     |       保存された認証情報が復号できない
     |       （または空に復号される）——起動時に
     |       ローテーションから除外され、認証情報なしの
     |       実行を起動することはない
     |
     +---> エラー
             その他の予期しない失敗（ネットワーク、サーバー）
             クールダウン：指数バックオフ

アカウントがクールダウン状態に入ると、ローテーション戦略は自動的にスキップし、次の利用可能なアカウントを使用します。クールダウンが終了すると、アカウントは自動的にローテーションプールに復帰します——ただし「認証死亡」のアカウントは例外で、実際の認証情報チェックが成功した場合（下記参照）、または新しい認証情報を保存した場合のみ早期に復帰します。「破損」のアカウントは自然には復帰せず、認証情報を再保存する必要があります。

推測ではなく実際の認証情報チェック

これまでアカウントの復帰は claude auth status を実行し、その loggedIn: true を信頼することで行われていました。しかしこのチェックが証明するのは環境内に「何らかの」CLAUDE_CODE_OAUTH_TOKEN が存在することだけで、「このアカウントの」トークンが依然として認証できるかどうかは何も示しません。失効または組織によって無効化されたトークンでも「ログイン中」と報告し続けることがあります。

自身のトークンを保存しているOAuthアカウントとAPIキーアカウントについて、ローテーターは今やそのアカウント自身の認証情報を使い、Anthropicの GET /v1/models へゼロコストの直接プローブを行います：

200 — 認証情報が有効。アカウントは復帰し、失敗カウントはリセット。
401 — トークン自体が無効。アカウントは停止したまま。
403 — 組織がClaude Codeサブスクリプションアクセスを無効化。アカウントは停止したまま。
429、またはネットワークエラー — 判断不能。アカウントはそのまま放置され、次のサイクルで再チェック。

APIに明確に拒否された（401/403）認証情報は、毎サイクル問い直す代わりにバックオフして再チェックされます：1分、2分、4分、8分、16分、上限30分。判断不能な結果がこのスケジュールを遅らせることはなく、認証情報が復活するか、実際のリクエストで新たな認証失敗が観測された時点で即座にリセットされます。

キーチェーンログインに依存する（保存されたトークンがない）アカウントは、プローブに渡すアカウント固有の秘密情報がないため引き続き claude auth status を使用しますが、そのようなアカウントが一度「認証死亡」になると、このチェックではもう早期復帰させられず、クールダウンが終わるのを待つしかありません。

保存前の認証情報検証

アカウントの追加（ダッシュボードまたは accounts.add 経由）では、今や書き込み前に同じチェックが実行されます：

拒否された認証情報（401）はそのまま拒否。
組織で無効化された認証情報（403）は、APIキーへの切り替えまたは組織管理者への連絡を案内して拒否。
短命のアクセストークン（sk-ant-at01-…、claude auth token が出力するもの）は、ローテーターが本来必要とする長命の sk-ant-oat01-… トークンを生成する claude setup-token への案内とともに拒否。
チェック自体が完了できない場合（多くはオフライン）——アカウントは保存されますが、次のヘルスチェックが確認するまで未確認としてフラグが立てられます。

ターミナルからの認証情報チェック

duduclaw doctor は、自分でトークンまたはキーを保存しているAnthropicアカウントごとに1行ずつ出力します：有効、トークン無効（401）、組織による無効化（403）、または接続不可。ローテーターと同じゼロコストのチェックを実行し、状態を一切変更しないため、稼働中のgatewayに対して実行しても安全です。キーチェーンログインに依存するアカウントはスキップされます——ここにはチェックできる秘密情報がありません。ネットワークに到達できない場合は常に警告として報告され、認証情報が死んでいるとは決して言いません。

また、その上にある claude auth status の行には注記が付きます：このチェックはログインファイルまたは環境変数の存在を証明するだけで、トークンが依然として有効であることは意味しません。

認証障害アラート

プール内のすべてのアカウントが同時に認証で失敗している場合、それはアカウント単位のクールダウンではなく、プラットフォーム全体の障害です。DuDuClawはActivity Feedイベントを1件投稿し、影響を受けたエージェントの通知チャネルへ通知を1件送信します——スケジュールされた作業と返信が停止していること、ダッシュボードのアカウント設定を確認するよう案内します。障害が続いている間は静かなまま（繰り返しの通知はなし）で、いずれかのアカウントが再び認証に成功した瞬間に、復旧通知を1件だけ送信します。

予算管理

各アカウントに月間支出上限を設定できます：

リクエスト送信前：
     |
     v
このリクエストのコストを推定
  （入力トークン + 予想出力トークンに基づく）
     |
     v
アカウントの月間予算を超過するか？
     |
  +--+--+
  |     |
 いいえ  はい
  |     |
  v     v
送信   このアカウントをスキップ、
       ローテーションの次を試行

予想外の請求を防止します。運用者がアカウントごとに予算を設定し、システムが自動的に実施。アカウントの予算が枯渇すると、24時間のクールダウンに入り、次の請求サイクルを待ちます。

キャッシュ効率との連携

アカウントローテーションシステムはキャッシュ効率トラッキングと連動します：

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

cache_efficiency < 30%の場合：
  「ほとんどのトークンにフルプライスを支払っています。
   より多くのクエリをローカル推論にルーティングすることを検討。」
     |
     v
  信頼度ルーターでローカルモデルへの優先度を自動的に引き上げ

フィードバックループが形成されます：クラウドAPIの使用効率が低い（キャッシュヒット率が低い）場合、システムは自動的にトラフィックをローカル推論にシフトし、キャッシュの恩恵を受けるクエリのためにAPIクォータを温存します。

Direct APIショートカット

完全なClaude CLIパイプラインが不要なシナリオ（シンプルなチャット応答）では、Direct APIモードでAnthropic Messages APIを直接呼び出せます：

シンプルなチャットクエリ
     |
     v
Direct APIクライアント（シングルトンHTTPクライアント）
     |
     v
キャッシュヒント付きシステムプロンプトを追加
  （APIサーバーにこのプロンプトをキャッシュするよう指示）
     |
     v
APIレスポンス

システムプロンプトがキャッシュされるため、同じシステムプロンプトを使う後続の呼び出しは再処理ではなくキャッシュにヒットします。繰り返しの会話で95%+のキャッシュヒット率を達成し、実効コストを劇的に削減します。

なぜ重要か

途切れないサービス

レート制限はAPIサービスの現実です。ローテーションなしでは、レート制限はエージェントの応答停止を意味します。ローテーションありでは、レート制限されたアカウントのクールダウン中にトラフィックが次の利用可能なアカウントにシームレスにシフトします。

コスト最適化

LeastCost戦略が無料クォータ（サブスクリプションから）を優先消費。有料API呼び出しは無料オプションが枯渇した時だけ発生。ほとんどのユーザーにとって、API使用量の大部分はサブスクリプション費用以上のコストがかかりません。

予算管理

アカウントごとの月間上限が暴走支出を防止。CostTelemetryダッシュボードと組み合わせ、運用者はすべてのトークンの行き先とコストを完全に可視化できます。

ハンズフリー運用

システム全体が自動。設定完了後、運用者はアカウントの手動切替、レート制限の監視、トラフィックの再バランスは不要。ローテーション戦略がすべてを処理します。

クロスプロバイダーフェイルオーバー

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 用量已達上限..."
  }

障害カテゴリは、旧来の汎用的な「claude auth statusを実行してください」というヒントの代わりに、カテゴリ別のzh-TWメッセージをレンダリングします。障害ログはダッシュボードでの可観測性のためにフィードされます。

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で起動されたゲートウェイがPATHの継承に依存せずにCLIバイナリを発見できます。

他システムとの連携

Multi-Runtime：アカウントローテーションはClaude、Codex、Gemini、OpenAI-compatの各プロバイダーをまたいで機能します。
信頼度ルーター：ローカル推論にルーティングされたクエリはAPIアカウントを消費せず、クォータの寿命が延長。
CostTelemetry：予算管理とキャッシュ効率フィードバックに必要なデータを提供。
FailoverManager：クロスプロバイダーのヘルストラッキングとフェイルオーバー判断を調整。
Direct API：シンプルなクエリに高キャッシュヒット率のバイパスを提供。
ダッシュボード：リアルタイムのアカウントヘルス、使用量、残予算、チャネル障害ログを表示。

まとめ

API認証情報は有限のリソースです——そしてマルチプロバイダーの世界では、それは有限リソースのフリートです。マルチアカウントローテーションはこれらを管理されたフリートとして扱います——プロバイダーをまたいで最適な利用可能オプションを自動選択、過負荷アカウントをクールダウン、予算を実施、クラウド使用効率が低い場合はローカル推論にシフト。