複数Claude Maxアカウントのリソース振り分け機能

Issue

#329

作成日

2026-04-07

ステータス

設計完了

変更規模

新規2ファイル + 既存4ファイル小改修

設計者

W層 architect

フェーズ

Phase 0（実証→本番）

1. 概要

3つのClaude Maxアカウントを使い分け、rate limitの影響を最小化する仕組みを実装する。CLAUDE_CONFIG_DIR + キーチェーンによるアカウント分離は技術的に実証済み。

解決する問題

• 単一アカウントではrate limit到達時に全エージェントが停止する
• アカウント間の負荷偏りを防ぎたい
• rate limit発生時に別アカウントで即座にリトライしたい

設計方針

• 最小変更: 新規 bot/account_pool.py（〜120行）を作成。claude_runner.py は30行追加のみ
• 冪等性: アカウント状態は pool_status.json で永続化。再起動しても安全
• 既存フロー維持: run_claude() のインターフェースは変更なし。内部でアカウント選択を注入

2. アーキテクチャ図

3. account_pool.py の設計

3.1 データモデル

@dataclass
class AccountInfo:
    name: str                  # 識別名（例: "account-a"）
    config_dir: str            # CLAUDE_CONFIG_DIR のパス
    active_count: int = 0      # 現在実行中のプロセス数
    cooldown_until: float = 0  # rate limit クールダウン終了時刻（time.time()ベース、0=制限なし）
    total_runs: int = 0        # 累計実行回数（統計用）
    last_rate_limit: float = 0 # 最後にrate limit検知した時刻

3.2 AccountPool クラス

class AccountPool:
    """Claude Maxアカウントのプール管理

    アクティブプロセス数ベースのスコアリングで負荷分散し、
    rate limit発生時は該当アカウントをクールダウンして別アカウントに振り替える。
    """

    def __init__(self, accounts: list[dict]) -> None:
        """アカウント一覧から初期化
        accounts: [{"name": "account-a", "config_dir": "/path/to/.claude-a"}, ...]
        """

    def acquire(self, *, exclude: str | None = None) -> AccountInfo | None:
        """最小スコアのアカウントを取得し、active_count += 1
        exclude: 除外するアカウント名（rate limit後のリトライ時）
        Returns: AccountInfo（利用可能なアカウントがなければ None）
        """

    def release(self, name: str) -> None:
        """プロセス完了時に active_count -= 1"""

    def mark_rate_limited(self, name: str, cooldown_seconds: int = 300) -> None:
        """rate limit検知時にクールダウン期間を設定（デフォルト5分）"""

    def _score(self, account: AccountInfo) -> float:
        """アカウントのスコアを計算（低い = 優先）
        クールダウン中 → float('inf')
        それ以外 → active_count
        """

    def status(self) -> list[dict]:
        """全アカウントの現在状態を返す（ダッシュボード / AI Ops用）"""

    def persist(self) -> None:
        """pool_status.json にアトミック書出し"""

    def all_limited(self) -> bool:
        """全アカウントがクールダウン中かどうかを返す"""

3.3 スコアリングアルゴリズム

3.4 pool_status.json の構造

{
  "accounts": [
    {
      "name": "account-a",
      "config_dir": "/Users/mnmladmin/.claude-a",
      "active_count": 2,
      "cooldown_until": null,
      "total_runs": 145,
      "last_rate_limit": null
    },
    {
      "name": "account-b",
      "config_dir": "/Users/mnmladmin/.claude-b",
      "active_count": 1,
      "cooldown_until": 1743984000.0,
      "total_runs": 132,
      "last_rate_limit": 1743983700.0
    },
    {
      "name": "account-c",
      "config_dir": "/Users/mnmladmin/.claude-c",
      "active_count": 0,
      "cooldown_until": null,
      "total_runs": 128,
      "last_rate_limit": null
    }
  ],
  "updated_at": 1743984001.0
}

保存先: logs/pool_status.json（既存の rate_limit_status.json と同階層）

4. 配分アルゴリズム — アカウント選択〜実行〜リトライのフロー

5. claude_runner.py の変更

5.1 変更方針

_run_claude_inner() 内で、subprocess起動直前にアカウントを取得し、完了時（正常/異常問わず）にリリースする。rate limit検知時は別アカウントでリトライする。

5.2 変更箇所（擬似コード）

# _run_claude_inner() の変更イメージ（約30行追加）

from bot.account_pool import pool  # グローバルインスタンス

async def _run_claude_inner(..., *, _account_name: str | None = None, ...):
    # ① アカウント取得
    account = pool.acquire(exclude=_account_name) if pool.enabled else None

    # ② env構築時に CLAUDE_CONFIG_DIR を注入
    env = {k: v for k, v in os.environ.items() if k not in _env_exclude}
    if account:
        env["CLAUDE_CONFIG_DIR"] = account.config_dir

    try:
        # ... 既存のsubprocess実行ロジック（変更なし） ...
        pass
    finally:
        # ③ 必ずリリース
        if account:
            pool.release(account.name)

    # ④ RateLimitError 検知時: 別アカウントでリトライ
    # （既存のRateLimitError送出箇所を変更）
    if is_rate_issue and not result_text.strip():
        if account:
            pool.mark_rate_limited(account.name, cooldown_seconds=wait_seconds)
            # 別アカウントで即リトライ（1回のみ）
            if not _account_name:  # 初回のみリトライ
                return await _run_claude_inner(
                    ..., _account_name=account.name, ...
                )
        raise RateLimitError(wait_seconds=wait_seconds)

5.3 インターフェース変更

内部関数 _run_claude_inner() に _account_name: str | None 引数を追加（プライベート、リトライ時の除外用）。

6. Rate Limit 対応

6.1 検知〜リトライの流れ

6.2 クールダウンの設計

6.3 既存リトライ機構との関係

• アカウント切替リトライ（本設計）: _run_claude_inner 内で1回だけ。同一タスク実行内で即座に別アカウントに切り替え
• タスクリトライ（既存）: Task.retry_count で管理。タスク全体を再実行。exponential backoff
• アカウント切替が成功すればタスクリトライは不要。切替も失敗した場合のみ RateLimitError が送出され、既存のタスクリトライが発動

7. AI Ops 監視

7.1 監視対象

AI Ops Monitor（agents/ai-ops/monitor/watcher.py）に _check_pool_status() メソッドを追加。

async def _check_pool_status(self) -> None:
    """アカウントプールの状態を監視

    チェック項目:
    1. 全アカウントがクールダウン中 → CRITICAL通知
    2. 1アカウントが長時間（15分超）クールダウン中 → WARNING通知
    3. 特定アカウントのrate limit頻度が高い → INFO通知（偏り検出）
    """

7.2 通知条件

7.3 データ読取

既存の reader.py に read_pool_status() メソッドを追加。logs/pool_status.json を読取専用でパースする。

# reader.py に追加
@dataclass(frozen=True)
class PoolAccountRecord:
    name: str
    config_dir: str
    active_count: int
    cooldown_until: float | None
    total_runs: int
    last_rate_limit: float | None

def read_pool_status(self) -> list[PoolAccountRecord]:
    """pool_status.json からアカウント状態を読取"""

8. config.py の変更

8.1 追加設定

class Settings(BaseSettings):
    # ... 既存設定 ...

    # アカウントプール設定
    # 形式: "name1:/path1,name2:/path2,name3:/path3"
    claude_accounts: str = ""
    # クールダウン秒数（デフォルト5分）
    pool_cooldown_seconds: int = 300
    # クールダウン上限（デフォルト30分）
    pool_cooldown_max: int = 1800

8.2 .env の設定例

# アカウントプール（カンマ区切り、各 "名前:config_dirパス"）
CLAUDE_ACCOUNTS=account-a:/Users/mnmladmin/.claude-a,account-b:/Users/mnmladmin/.claude-b,account-c:/Users/mnmladmin/.claude-c

# クールダウン秒数（任意、デフォルト300）
# POOL_COOLDOWN_SECONDS=300

9. 変更対象ファイル一覧

10. 不確実要素・リスク

11. Phase 0 スコープ

11.1 Phase 0 でやること

1. bot/account_pool.py 新規作成
2. bot/claude_runner.py にアカウント選択ロジック組込み
3. bot/config.py に設定追加
4. .env に3アカウント設定
5. 単体テスト: AccountPool の acquire/release/mark_rate_limited
6. 統合テスト: 実際に3アカウントでCLI実行し、アカウント振り分けを確認
7. 実測検証: 1アカウントを意図的にrate limitさせ、別アカウントへの切替が有効か確認

11.2 Phase 0 でやらないこと（Phase 1以降）

• AI Ops Monitor への組込み（Phase 0の実測結果を待つ）
• ダッシュボードへのアカウント状態表示
• IPローテーション（rate limitがIP単位だった場合の代替策）
• アカウント自動追加/削除（現時点では3固定で十分）

11.3 Phase 0 完了条件

12. セキュリティ考慮

入力バリデーション

• CLAUDE_ACCOUNTS のパース: 不正な形式（区切り文字不正、パス不存在）は起動時にログ警告し、該当アカウントをスキップ
• config_dir のパス: 絶対パスのみ許可。相対パスは拒否
• cooldown_seconds: 0〜pool_cooldown_max の範囲にクランプ

機密情報

• アカウントのOAuthトークンはキーチェーンに格納。ファイルやログに出力しない
• pool_status.json にはトークン情報を含めない（config_dir パスのみ）
• .env は .gitignore 済み

アトミック書込み

• pool_status.json は既存の rate_limit_status.json と同じパターン（tmpfile → os.replace）で書出し
• 読取失敗時はデフォルト状態（全アカウント active_count=0）にフォールバック

13. トレードオフ・代替案

検討した代替案