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

Issue

#329

作成日

2026-04-07

最終更新

2026-04-14（文献調査結果追記）

ステータス

設計確定（レビュー完了）

変更規模

新規1ファイル + 既存3ファイル小改修

設計者

W層 architect

フェーズ

Phase 0（実測検証 → 実装 → 本番）

A. 設計レビュー回答（12件）

CEOからの12件の技術質問に対する設計判断と、設計書への反映内容をまとめる。

{
  "cooldown_until": null,         // 既存: 全体のクールダウン（単一アカウント時の後方互換）
  "last_event": { ... },          // 既存: 最後のrate limitイベント
  "history": [ ... ],             // 既存: イベント履歴（24h TTL）
  "accounts": [                   // 新規: アカウント別の状態（active_countはメモリのみ）
    {
      "name": "account-a",
      "cooldown_until": null,
      "last_rate_limit": null
    }
  ],
  "updated_at": 1743984001.0
}

1. 概要

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

解決する問題

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

設計方針

• 最小変更: 新規 bot/account_pool.py（〜130行）を作成。claude_runner.py は30行追加のみ
• 冪等性: アカウント状態は rate_limit_status.json の拡張フィールドで永続化。再起動しても安全（active_countは永続化しない）
• 既存フロー維持: run_claude() のインターフェースは変更なし。内部でアカウント選択を注入
• 実測ファースト: コード実装前にrate limit粒度を実測検証する（Phase 0 Step 0）

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=制限なし）
    last_rate_limit: float = 0 # 最後にrate limit検知した時刻

3.2 AccountPool クラス

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

    active_countベースのスコアリングで負荷分散し、
    rate limit発生時は該当アカウントをクールダウンして別アカウントに振り替える。
    asyncio.Lock で並行アクセスを保護する（レビュー②反映）。
    """

    def __init__(self, accounts: list[dict]) -> None:
        """アカウント一覧から初期化
        accounts: [{"name": "account-a", "config_dir": "/path/to/.claude-a"}, ...]
        """
        self._lock = asyncio.Lock()  # レビュー②: 並行性制御

    async def acquire(self, *, exclude: str | None = None, wait: bool = False) -> AccountInfo | None:
        """最小スコアのアカウントを取得し、active_count += 1
        exclude: 除外するアカウント名（rate limit後のリトライ時）
        wait: 全アカウント制限中の場合、最短復帰まで待機するか（レビュー⑤反映）
        Returns: AccountInfo（利用可能なアカウントがなく wait=False なら None）
        """

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

    async def mark_rate_limited(self, name: str, cooldown_seconds: int = 300) -> None:
        """rate limit検知時にクールダウン期間を設定"""

    def _score(self, account: AccountInfo) -> tuple[float, str]:
        """アカウントのスコアを計算（低い = 優先）
        クールダウン中 → (float('inf'), name)
        それ以外 → (active_count, name)  # 同スコアは名前の辞書順で破壊
        """

    def _reconcile_active_counts(self) -> None:
        """ProcessRegistryの実行中PIDと突き合わせてactive_countを補正（レビュー③反映）"""

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

    def persist(self) -> None:
        """rate_limit_status.json の accounts フィールドに書出し（レビュー⑪反映）
        書出し前に _reconcile_active_counts() を実行して補正する"""

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

    @property
    def enabled(self) -> bool:
        """アカウントが2つ以上設定されている場合にTrue"""

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

3.4 rate_limit_status.json への統合（レビュー⑪反映）

{
  "cooldown_until": null,         // 既存: 全体のクールダウン（単一アカウント時の後方互換）
  "last_event": { ... },          // 既存: 最後のrate limitイベント
  "history": [ ... ],             // 既存: イベント履歴（24h TTL）
  "accounts": [                   // 新規: アカウント別の状態（active_countはメモリのみ、永続化しない）
    {
      "name": "account-a",
      "cooldown_until": null,
      "last_rate_limit": null
    },
    {
      "name": "account-b",
      "cooldown_until": 1743984000.0,
      "last_rate_limit": 1743983700.0
    },
    {
      "name": "account-c",
      "cooldown_until": null,
      "last_rate_limit": null
    }
  ],
  "updated_at": 1743984001.0
}

保存先: logs/rate_limit_status.json（既存ファイルの拡張）

• active_count は永続化しない（レビュー③）。起動時は 0 初期化 → ProcessRegistry と突き合わせて再計算
• total_runs フィールドは廃止（レビュー⑥）。rate limit はトークン消費量ベースのため実行回数は無意味
• 単一アカウント運用時は accounts が空配列 → 既存フィールドのみで動作（後方互換）
• config_dir は永続化しない（設定値なので .env から読めばよい）

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, ...):
    # ① アカウント取得（asyncio.Lock で保護）
    account = await 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:
            await pool.release(account.name)

    # ④ RateLimitError 検知時: 別アカウントでリトライ
    if is_rate_issue and not result_text.strip():
        if account:
            await 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通知（偏り検出）

    データソース: rate_limit_status.json の accounts フィールド（レビュー⑪反映）
    """

7.2 通知条件

7.3 データ読取

既存の reader.py に read_pool_accounts() メソッドを追加。rate_limit_status.json の accounts フィールドを読取る。

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

def read_pool_accounts(self) -> list[PoolAccountRecord]:
    """rate_limit_status.json の accounts フィールドからアカウント状態を読取"""

8. config.py の変更

8.1 追加設定

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

    # アカウントプール設定
    # 形式: "name1:/path1,name2:/path2,name3:/path3"
    claude_accounts: str = ""
    # クールダウン秒数（デフォルト5分。CLIが値を返さない場合のフォールバック）
    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。CLIがretry_afterを返さない場合のフォールバック）
# POOL_COOLDOWN_SECONDS=300

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

10. 不確実要素・リスク

11. Phase 0 スコープ

11.0 文献調査結果（2026-04-14）

実測検証が必要な理由

• 状況証拠は「成功する可能性が高い」ことを示すが、確定ではない
• 同一デバイスでのバグ報告（IP/デバイス単位の追加制御の可能性）を排除できない
• GASTOWN等の具体的なマルチアカウントプール管理の一次ソースは未確認

11.1 Step 0: 実測検証（コード実装前）

scripts/test_rate_limit_granularity.py（〜80行）を作成し、以下を検証する。

検証スクリプトの内容

1. 各アカウントの claude auth status でキーチェーン状態を確認
2. 2アカウント（account-a, account-b）で同時に claude -p "hello" --output-format stream-json を実行
3. 一方を意図的にrate limitに到達させた後、もう一方が制限なく動作するかを確認
4. rate_limit_event の rateLimitType/utilization を両アカウントで比較
5. /tmp/claude-{UID}/ の共有による干渉がないか検証（同一UIDで複数 CLAUDE_CONFIG_DIR が共存できるか）
6. CLI が retry_after / resetsAt をどの頻度で返すか記録
7. 結果を logs/rate_limit_granularity_test.json に保存

判定基準

11.2 Step 1: 実装（Step 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.3 Phase 0 完了条件（レビュー⑫反映）

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

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

12. セキュリティ考慮

入力バリデーション

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

機密情報

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

アトミック書込み

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

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

検討した代替案

14. レビュー設計決定サマリー

CEOレビュー（12件）の質問と設計決定を一覧にまとめる。