🔌 週次クォータ上限でジョブが全滅する前にサーキットブレーカーを張る

月商120万の自律基盤を支える15本の LaunchAgent ジョブが、週次クォータ上限を踏んだ瞬間から6時間、エラーを握りつぶしたまま走り続けていた──それに気づいたのは翌朝の手動確認でした。

なぜこの仕組みが効くのか

「止まっていることを知らない」という損失

自動化が壊れるとき、大きく二種類あります。クラッシュして叫ぶ失敗と、黙って消える失敗です。

Claude Code には週次の利用上限があります。上限に達すると、API 呼び出しが weekly usage limit を含むエラーメッセージを返します。問題はここからで、LaunchAgent で5分おきや1時間おきに回している自動化スクリプトは、このエラーを受け取っても大半が exit 1 を吐いて終わるだけです。launchd は exit 1 を「ジョブが失敗した」と記録しますが、次のサイクルで何事もなかったように再実行しようとします。そしてまた失敗します。

このループが月・火・水と続いても、ダッシュボードは存在しないので誰も気づきません。SNS 投稿の自動生成・サムネイルの AI 加工・ナレッジベースへの会話ログ取り込み、これらが全部飛んでいます。私の環境では15本の Claude 呼び出しジョブが並走しており、上限を踏むと一斉にスキップされます。6時間 × 15本 ＝ 90ジョブ分の仕事が無音で消えます。

LaunchAgent と Claude Code の相性問題

なぜ自動検知が難しいのか、少し掘り下げます。

macOS の launchd は、ジョブが失敗してもデフォルトでは通知しません。ThrottleInterval で再試行間隔を制御できますが、「クォータに当たった → 次の制限リセットまで一切実行しない」というロジックを plist で表現する方法はありません。また、Claude Code 本体の exit code は状況によって 0・1・その他と変わるため、「終了コードを見ればわかる」という単純な話にもなりません。

さらに厄介なのが、エラーメッセージが stderr に流れる点です。LaunchAgent は stdout/stderr を /tmp 以下のログに吐きますが、そのログを常時監視している人はほぼいません。grep -r "weekly usage limit" ~/Library/Logs/ を朝イチに走らせる習慣がある個人開発者は稀です。

環境として解く

2025年に大学生で月10万稼いでいたころ、私は「なんで昨日の投稿が上がってないんだろう」を手動確認で発見する毎日でした。掛け持ちで月60万になってからも、同じ問題が繰り返し起きていました。会社都合で解雇されて0になり、半年かけて Claude Code の自律環境を一から建て直して今の月商120万に至るわけですが、この過程で学んだことが一つあります。「止まっていることに気づかない」状態を放置すると、稼ぎではなく信頼が消えるということです。

仕組みの核心は「発火した瞬間に止める・知らせる・残す」の三点です。クォータに当たったら、以降の全 Claude 呼び出しを即座にブロック（exit 75）し、Discord に通知し、JSON ファイルにサーキット状態を永続化する。手動で確認しに行くのではなく、環境側から叫んでもらいます。

この考え方は電気回路のサーキットブレーカーと同じです。過電流が流れた瞬間に遮断器が落ちる。復旧したら手動でリセットする。ジョブが「無駄に何度も叩いてエラーを積む」状態を防ぎつつ、状態が外から観測できる形で止まります。

---

全体の流れ

アーキテクチャ概要

LaunchAgent (定期ジョブ群 × 15本)
      │
      │  CLAUDE=~/.claude/scripts/claude-quota-guard.py
      ▼
claude-quota-guard.py
      │
      ├─[CLOSED]─▶ ~/.local/bin/claude (本物) を実行
      │                    │
      │              stdout + stderr の末尾 128KB をスキャン
      │                    │
      │           "weekly usage limit" 等 7パターンに一致？
      │                    │
      │              YES ──┤
      │                    ▼
      │         open_until = now + 21600s (6時間)
      │         reason = "quota-message"
      │         ~/.claude/state/claude-quota-circuit.json に原子書き込み
      │         ~/.discord/notify.sh "alerts" へ即時通知
      │
      └─[OPEN]──▶ exit 75 で即ブロック（直接呼び出し時）
                  exit 0 でスキップ（--job モード時）

復旧フロー:
  制限リセット後 ─▶ claude-quota-guard.py --reset ─▶ CLOSED に戻る
  または open_until を過ぎると自動で CLOSED（normalize_expired）

サーキット状態は ~/.claude/state/claude-quota-circuit.json に原子的書き込みで永続化されます。複数のジョブが同時に状態を読み書きしても破損しないよう、fcntl.LOCK_EX でファイルロックをかけてから更新し、os.replace() でアトミックに置き換えます。

クォータパターンの検出

claude-quota-guard.py がクォータと判断する文字列は7種類あります。

QUOTA_PATTERNS = (
    r"weekly (?:usage )?limit",
    r"usage limit",
    r"rate limit",
    r"quota (?:exceeded|limit|reached)",
    r"(?:you(?:'ve| have) )?hit your limit",
    r"limit reached",
    r"resets? (?:at|in|on|tomorrow)",
)

大文字・小文字を区別せず（re.IGNORECASE）、Claude 本体の stdout と stderr を合わせた末尾 131,072 バイト（128KB）を対象にスキャンします。

combined = (result.stdout + b"\n" + result.stderr)[-131072:].decode("utf-8", errors="replace")
record_claude_result(result.returncode, combined)

末尾を切り取るのは明確な理由があります。長時間稼働するジョブの序盤の正常ログを読み飛ばし、エラーが出やすい末尾だけを効率的に検査するためです。巨大な stdout をすべてメモリに展開せずに済むという副次効果もあります。

サーキットが開く二つのトリガー

クォータメッセージ検出以外にも、もう一つのトリガーがあります。10分以内に exit 1 が3回続くと強制 OPEN になります。

cooldown  = int(os.environ.get("CLAUDE_GUARD_COOLDOWN_SECONDS", "21600"))
window    = int(os.environ.get("CLAUDE_GUARD_FAILURE_WINDOW_SECONDS", "600"))
threshold = int(os.environ.get("CLAUDE_GUARD_FAILURE_THRESHOLD", "3"))

デフォルト値は cooldown=21600（6時間）・window=600（10分）・threshold=3（3回）です。Claude の週次制限は日本時間の早朝にリセットされる場合が多く、6時間後には制限が明ける可能性が高いという経験則からこの値にしています。環境変数で上書きできるので、自分の制限リセットタイミングに合わせて調整できます。

トリガー別に reason フィールドが記録されます。クォータメッセージ検出なら "quota-message"、連続失敗なら "repeated-exit-1" です。この区別が後の復旧判断に効いてきます。

OPEN 時の挙動──静かに止める

サーキットが OPEN の状態で呼ばれると、run_claude は即座に exit 75 を返します。

EXIT_CIRCUIT_OPEN = 75

def run_claude(arguments: list[str]) -> int:
    status = circuit_status()
    if status["is_open"]:
        print(
            "CLAUDE_QUOTA_CIRCUIT_OPEN "
            f"reason={status['reason']} remaining={status['remaining_seconds']}s",
            file=sys.stderr,
        )
        return EXIT_CIRCUIT_OPEN
    # 以下、本物の claude を実行する処理

exit 75 は POSIX 慣例の EX_TEMPFAIL（一時的な失敗）に対応する値で、「今は無理だが後で試せる」を意味します。launchd の plist で <key>SuccessfulExit</key><true/> を設定していれば exit 0 のみを成功扱いにする設定もありますが、exit 75 を別途 AbandonProcessGroup と組み合わせることで「クォータ中は静かに諦める」挙動を plist 側で明示的にコントロールできます。

--job モードはさらに穏やかです。OPEN のときは return 0（正常終了）を返してジョブをスキップします。ジョブスクリプト側は Claude が呼ばれたことすら知らずに終わります。

def run_job(label: str, command: list[str]) -> int:
    status = circuit_status()
    if status["is_open"]:
        print(
            "CLAUDE_QUOTA_JOB_SKIPPED "
            f"job={label} reason={status['reason']} remaining={status['remaining_seconds']}s",
            file=sys.stderr,
        )
        return 0
    # 以下、CLAUDE_AUTOMATION_GUARD=1 を env に渡してジョブを実行

Discord 通知──止まったことを外から知る

サーキットが OPEN になった瞬間、notify_circuit_open() が ~/.discord/notify.sh を叩きます。

def notify_circuit_open(reason: str, cooldown: int) -> None:
    """circuit OPENは15job一斉の6hサイレント停止になる — 必ずDiscordへ可視化する。"""
    script = Path.home() / ".discord" / "notify.sh"
    if not script.exists():
        return
    hours = round(cooldown / 3600, 1)
    subprocess.run(
        [str(script), "alerts",
         f"🚨 claude-quota-guard circuit OPEN (reason={reason}) "
         f"— Claude生成ジョブを{hours}hスキップします。"
         f"復旧済みなら `claude-quota-guard.py --reset`"],
        check=False, timeout=10, capture_output=True,
    )

コメントに「15job一斉の6hサイレント停止」と書いてあるのが私の環境の実態です。クールダウン秒数を時間に丸めて（round(cooldown / 3600, 1)）メッセージに埋め込むことで、スマホの Discord 通知を見た瞬間に「あと何時間待てばいいか」がわかります。timeout=10 で Discord への通知自体が詰まってもジョブ全体を止めない設計になっています。

health チェックとの統合

automation-health.sh はセクション 1.5「Claude生成quota circuit」でサーキット状態を毎回確認します。

quota_guard="$CLAUDE/scripts/claude-quota-guard.py"
quota_state=$("$quota_guard" --status 2>/dev/null || true)
quota_open=$(printf '%s' "$quota_state" | jq -r '.is_open // false')
if [ "$quota_open" = "true" ]; then
    quota_reason=$(printf '%s' "$quota_state" | jq -r '.reason // "unknown"')
    quota_remaining=$(printf '%s' "$quota_state" | jq -r '.remaining_seconds // 0')
    wn "OPEN: Claude生成15jobをskip中 / reason=$quota_reason / remaining=${quota_remaining}s"
elif [ -n "$quota_state" ]; then
    ok "CLOSED: Claude生成jobは実行可能"
else
    ng "quota guard status の取得失敗"
fi

--status は現在の JSON をそのまま stdout に出力します。is_open と remaining_seconds はランタイムで計算されるフィールドで、ファイルに保存された open_until から現在時刻を引いて毎回算出します。

def circuit_status() -> dict:
    timestamp = now()
    with locked_state() as state:
        normalize_expired(state, timestamp)
        result = dict(state)
    result["is_open"] = int(result.get("open_until", 0) or 0) > timestamp
    result["remaining_seconds"] = max(0, int(result.get("open_until", 0) or 0) - timestamp)
    return result

normalize_expired() は open_until が現在時刻を過ぎていれば自動で CLOSED に戻します。つまり --reset を打たなくても、6時間後には自然にサーキットが閉じます。

実際の状態ファイル

この記事を書いている現時点のサーキット状態は次のとおりです。

{
  "consecutive_failures": [],
  "last_success": 1785280668,
  "open_until": 1785470423,
  "opened_at": 1785448823,
  "reason": "quota-message",
  "version": 1
}

opened_at から open_until を引くと 21,600 秒（6時間）ちょうどです。reason は "quota-message" なので、Claude 本体が返した出力の中に7パターンのいずれかが含まれていたことを示しています。last_success は最後に Claude の呼び出しが正常終了したタイムスタンプで、これが古くなるほど「ジョブが長期間スキップされている」サインになります。consecutive_failures が空配列なのは、クォータメッセージ検出でサーキットが開いた場合、連続失敗カウンターをリセットする仕様だからです。

if quota_message(output):
    state["open_until"] = timestamp + cooldown
    state["reason"] = "quota-message"
    state["opened_at"] = timestamp
    state["consecutive_failures"] = []   # ← 連続失敗カウンターをクリア
    opened_reason = "quota-message"

二つのトリガーが同時に走ることはなく、クォータメッセージが優先して評価される設計になっています。

実装の詳細

ファイルロックと原子書き込み──15本が同時に踏んでも壊れない

並走する15本のジョブが同時に claude-quota-circuit.json を読み書きしたとき、JSONが破損する最悪ケースを防ぐのが locked_state() コンテキストマネージャです。Pythonの threading.Lock は同一プロセス内しか制御できないので、別プロセス間を仕切るOSレベルのファイルロック（fcntl.LOCK_EX）を使っています。

@contextmanager
def locked_state():
    path = state_path()
    path.parent.mkdir(parents=True, exist_ok=True)
    lock_path = path.with_suffix(path.suffix + ".lock")
    with lock_path.open("a+") as lock:
        fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
        state = default_state()
        if path.exists():
            try:
                loaded = json.loads(path.read_text(encoding="utf-8"))
                if isinstance(loaded, dict):
                    state.update(loaded)
            except (OSError, ValueError):
                pass
        yield state
        # ... 書き込みフェーズ
        fcntl.flock(lock.fileno(), fcntl.LOCK_UN)

設計上のポイントが三つあります。

ロックはサイドカーファイル .json.lock に掛ける。本体JSONに直接ロックをかけると、書き込み途中のバイト列を別プロセスが読む余地が生まれます。ロック用ファイルを分離することで、本体JSONの読み書きを常にロック保持中の安全な窓の中に収めます。path.with_suffix(path.suffix + ".lock") は claude-quota-circuit.json.lock というパスを生成します。

書き込みは os.replace() でアトミックに。同ディレクトリ内に tempfile.mkstemp で一時ファイルを作り、json.dump してから os.replace(temp_name, path) で置き換えます。同一ファイルシステム上のrenameはPOSIXでアトミックなので、読み途中のJSONが生まれません。

fd, temp_name = tempfile.mkstemp(prefix=path.name + ".", dir=path.parent)
try:
    with os.fdopen(fd, "w", encoding="utf-8") as temp:
        json.dump(state, temp, ensure_ascii=False, sort_keys=True)
        temp.write("\n")
    os.replace(temp_name, path)
finally:
    if os.path.exists(temp_name):
        os.unlink(temp_name)

finally でテンポラリの残骸も消します。os.replace が失敗した場合でも一時ファイルが残り続けないようにしてあります。

状態は default_state() でベースを作り update() で補完。ファイルが存在しない初回でも、JSONが壊れていてKeyErrorが出そうな状況でも、デフォルト値を持つ辞書に対して update() を当てているのでKeyErrorが起きません。壊れたJSONを読んだOSError・ValueErrorは pass で黙って流し、デフォルト値で上書きします。「壊れたら何もしない」より「壊れたらデフォルトに戻す」の方がサーキットとして堅牢です。

本物の claude を探す──自己参照ガード

claude-quota-guard.py はシェルから見ると claude コマンドの代替として配置されるラッパーです。本物のバイナリを呼び出すのが real_claude() 関数の仕事です。

def real_claude() -> str:
    configured = os.environ.get("CLAUDE_REAL_BIN")
    if configured:
        return str(Path(configured).expanduser())
    candidate = Path.home() / ".local" / "bin" / "claude"
    try:
        resolved = candidate.resolve(strict=True)
    except OSError:
        return str(candidate)
    if resolved == Path(__file__).resolve():
        raise RuntimeError("CLAUDE_REAL_BIN points back to claude-quota-guard.py")
    return str(resolved)

CLAUDE_REAL_BIN 環境変数が設定されていればそちらを優先し、なければ ~/.local/bin/claude のシンボリックリンクを resolve(strict=True) で実体解決します。そして解決先が自分自身と一致しないかを比較しています。Path(__file__).resolve() がスクリプト自身の絶対パスです。一致すれば RuntimeError を投げて即停止します。これは私が実際に踏んだフォーク爆弾の対策で、後述します。

run_job() の環境変数インジェクション

--job LABEL -- COMMAND [ARG...] モードでは、ラップするコマンドを実行する前に環境変数を三本注入します。

env = os.environ.copy()
env["CLAUDE_AUTOMATION_GUARD"] = "1"
env["CLAUDE"] = guard       # claude-quota-guard.py の絶対パス
env["CLAUDE_BIN"] = guard

CLAUDE_AUTOMATION_GUARD=1 はジョブスクリプト側が「自動実行から呼ばれた」と判断するためのフラグです。CLAUDE と CLAUDE_BIN をガード自身のパスで上書きすることで、ジョブが内部で $CLAUDE・$CLAUDE_BIN を呼ぶと再びガードを経由します。ジョブが何十回 claude を呼ぼうとも、すべての呼び出しがサーキットチェックを通過する設計です。ただし $PATH 上の claude を直接呼ぶ場合はこの注入が効きません。私の環境では $PATH 上の claude もガードへのシンボリックリンクに統一しています。

テスト用の時刻注入──CLAUDE_GUARD_NOW

6時間後にサーキットが自動で CLOSED になる挙動を実際に6時間待たずに検証するため、now() 関数は環境変数 CLAUDE_GUARD_NOW を参照します。

def now() -> int:
    return int(os.environ.get("CLAUDE_GUARD_NOW", str(int(time.time()))))

現在の claude-quota-circuit.json の open_until は 1785470423 です。以下を実行すると「1秒過ぎた瞬間」をシミュレートできます。

CLAUDE_GUARD_NOW=1785470424 \
  ~/.claude/scripts/claude-quota-guard.py --status | jq .

is_open: false・remaining_seconds: 0 が返ってきます。本番の状態ファイルを書き換えずに時刻を動かせるので、launchd から実際に呼ばれる文脈でも安全にテストできます。--open SECONDS REASON サブコマンドと組み合わせれば、任意の状態を作ってから CLAUDE_GUARD_NOW で時間を進める一連のテストが可能です。

---

私が詰まった話

①「フォーク爆弾」──ラッパーが自分自身を呼び続けた

最初のセットアップ時、既存の ~/.local/bin/claude バイナリのパスを確認せずにガードスクリプトへのシンボリックリンクに書き換えました。

症状: claude を叩いた瞬間にターミナルが固まりました。別ウィンドウで ps aux | grep python を確認すると、同一スクリプトが数十プロセス並走しています。MacのActivity Monitorでは1〜2秒でPythonプロセスが雪崩のように増え、CPU使用率が100%に張り付きました。

原因: ~/.local/bin/claude → claude-quota-guard.py というリンクを作ったため、real_claude() が ~/.local/bin/claude を解決すると自分自身（claude-quota-guard.py）に戻ってきます。子プロセスとして自分を起動し、その子がまた自分を起動するフォーク爆弾です。resolve(strict=True) 自己参照チェックは後から追加された対策ですが、当時はこのチェックがなかったため無限ループが止まりませんでした。

直し方: まず killall python3 でプロセスを強制終了し、CLAUDE_REAL_BIN を明示するだけです。

# ~/.zshrc に追記してシェルを再起動
export CLAUDE_REAL_BIN="$HOME/.nvm/versions/node/v24.13.0/bin/claude"

現在のコードにある自己参照チェックは、この失敗を踏んだ後に追加しました。CLAUDE_REAL_BIN を最初から設定しておけばチェックを経由しないので、セットアップ手順の最初のステップをこれにするのが最も確実です。

②「ロックファイル残骸」──全ジョブがハングした朝

症状: ある朝から automation-health.sh のセクション 1.5「Claude生成quota circuit」が数十秒間返ってこなくなりました。quota_guard --status を手動で叩いてもハング。

原因: 前夜、私が kill -9 でプロセスを強制終了したとき、automation-health.sh の多重起動ガードが使う /tmp/automation-health.lock/pid に古いPIDが残留していました。

# automation-health.sh の多重起動ガード抜粋
if ! mkdir "$_ah_lock" 2>/dev/null; then
  if kill -0 "$(cat "$_ah_lock/pid" 2>/dev/null)" 2>/dev/null; then
    echo "automation-health: 別インスタンス稼働中のためスキップ" >&2
    exit 0   # ← ここで黙って終了していた
  fi
  rm -rf "$_ah_lock"
  ...
fi

kill -0 はプロセスの存在確認です。kill -9 で殺したプロセスのPIDが、その後に起動した全く別のプロセスに再利用されると、kill -0 が成功してしまいます。「別インスタンス稼働中」と誤認して exit 0 で黙って終わるため、呼び出し元から見ると「health checkが一瞬で終わってOKを返した」に見えます。実際には一度も走っていません。これが「全ジョブが問題なく動いているように見えるのに実態は誰も確認していない」という最悪のケースです。

直し方: /tmp/automation-health.lock を手動で削除するだけです。

rm -rf /tmp/automation-health.lock

kill -9 を使わず、必ず Ctrl+C（SIGINT）か kill -TERM で終了するようにしました。trap EXIT が走れば rm -rf "$_ah_lock" でロックが解放されます。kill -9 は「どうしても終わらないとき」だけの最終手段で、使った後は必ず /tmp/automation-health.lock を手動で掃除します。

③「repeated-exit-1 の誤発火」──Wi-Fi 不調がサーキットを開けた

クォータとは無関係な状況でサーキットが OPEN になり、翌朝まで15本のジョブがスキップされていた事例です。

症状: Discord に reason=repeated-exit-1 の通知が来ました。その時点で週次クォータは十分残っていたはずです。

原因: その夜、Wi-Fi ルーターを再起動していました。10分（CLAUDE_GUARD_FAILURE_WINDOW_SECONDS=600）以内に Claude の呼び出しが3回（CLAUDE_GUARD_FAILURE_THRESHOLD=3）exit 1 で失敗すれば、理由に関係なくサーキットが開きます。

failures = [
    int(value)
    for value in state.get("consecutive_failures", [])
    if timestamp - int(value) <= window   # 10分以内の失敗だけ残す
]
failures.append(timestamp)
state["consecutive_failures"] = failures
if len(failures) >= threshold:            # 3回以上でOPEN
    state["open_until"] = timestamp + cooldown
    state["reason"] = "repeated-exit-1"

ネットワーク障害は exit 1 を返します。15本中3本が先にこの条件を踏んでサーキットが開いた瞬間、残り12本はジョブスキップ（exit 0）に切り替わります。

直し方: reason=repeated-exit-1 は翌朝にクォータ制限が原因ではないとわかった時点で即 --reset を打てばよいので、Discord 通知に repeated-exit-1 と quota-message で文面を変えることを検討しました。しかし最終的には「理由を問わず OPEN になったら人間が判断して --reset を打つ」運用に統一しています。自動 --reset にするとネットワーク障害中でも Claude を叩こうとして失敗ループが続くからです。通知メッセージには既に 復旧済みなら claude-quota-guard.py --reset と書いてあります。

誤発火を減らしたい場合は環境変数で閾値を上げられます。

export CLAUDE_GUARD_FAILURE_THRESHOLD=5

ただし私の環境では「5回以上exit 1が続く＝確かに何かおかしい」という判断で3のままにしています。

④「--reset を忘れてまる一日スキップした」

クォータ制限が明けた後も --reset を打たずに放置した失敗です。

症状: その日の深夜に automation-health.sh を走らせると OPEN: Claude生成15jobをskip中 / remaining=3600s が出ていました。一日分のジョブが全部飛んでいます。

原因: open_until の計算を誤解していました。クォータのリセットタイミングと6時間クールダウンは完全に独立しています。日曜22時にサーキットが開けば open_until は月曜4時です。週次クォータが月曜3時にリセットされていても、サーキットは4時まで OPEN のままです。「クォータが明けたらサーキットも自動で戻る」わけではありません。normalize_expired() が open_until を過ぎていたら自動で CLOSED に戻してくれますが、その open_until はあくまで opened_at + 21600 です。

直し方: 復旧ワンライナーを .zshrc にエイリアスとして登録しました。

alias claude-recover='~/.claude/scripts/claude-quota-guard.py --reset && \
  bash ~/.claude/scripts/automation-health.sh'

Discord でクォータ上限通知を受け取ったらその場でスレッドにリマインダーを立てておき、翌朝 claude-recover を打つワークフローが定着しています。--reset 直後に automation-health.sh をセットで走らせることで、CLOSED に戻ったことと15本の launchd ジョブが正常稼働していることを一度に確認できます。

remaining_seconds の値はスマホの Discord からも読めるので、OPEN を検知したら残り秒数をそのまま日程アプリのリマインダーに変換するショートカットも設定しました。「あと21600秒後に確認」ではなく「月曜朝4時にアラーム」です。自動化が止まっている時間を知っていると、手動でカバーすべき作業を判断できます。

つまずきポイント（実運用で踏んだ地雷リスト）

前段ではフォーク爆弾・ロックファイル残骸・repeated-exit-1 誤発火・--reset 忘れの4件を取り上げました。ここではそれ以外に実運用で踏んだ地雷を網羅します。

① --job の -- 区切りを忘れると exit 2 でサイレント全滅する

claude-quota-guard.py --job LABEL -- COMMAND [ARG...] の -- を書き忘れて --job note-autolike bash /path/to/run.sh と書くと、コード内の判定 arguments[2] != "--" が True になり即 exit 2 で終わります。

if len(arguments) < 4 or arguments[2] != "--":
    print("usage: claude-quota-guard.py --job LABEL -- COMMAND [ARG...]", file=sys.stderr)
    return 2

launchd は last exit=2 と記録するだけで次のサイクルも再実行しようとします。automation-health.sh のセクション 1（launchd バッチ）が RED として拾いますが、「なぜ exit 2 なのか」は /tmp/com.shun.xxxx.stderr.log を直接開くまでわかりません。新しい plist を launchctl load する前に、手動で1回ローカル実行して exit code を確認する習慣がなければ、デプロイ初日から全滅します。

② launchd は ~/.zshrc を読まないため $CLAUDE が空になる

run_job() は子プロセスに CLAUDE と CLAUDE_BIN をガード自身のパスで上書きします。しかしその**親プロセス（launchd ジョブ自体）**に $CLAUDE が渡っていなければ意味がありません。~/.zshrc で export CLAUDE=~/.claude/scripts/claude-quota-guard.py をしていても、launchd 起動のジョブはその設定を見ません。空の $CLAUDE を展開したシェルスクリプトが $CLAUDE --print "..." を実行しようとして exit 127 → 10分以内に3回続けば repeated-exit-1 でサーキットが開きます。クォータとは無関係な誤発火です。全 plist の <key>EnvironmentVariables</key> セクションに直書きするのが唯一確実な解です。

<key>EnvironmentVariables</key>
<dict>
  <key>CLAUDE_REAL_BIN</key>
  <string>~/.nvm/versions/node/v24.13.0/bin/claude</string>
  <key>CLAUDE</key>
  <string>~/.claude/scripts/claude-quota-guard.py</string>
  <key>CLAUDE_BIN</key>
  <string>~/.claude/scripts/claude-quota-guard.py</string>
</dict>

③ stdout が大きいジョブでクォータメッセージが 128KB 末尾の外に押し出される

record_claude_result がスキャンするのは stdout と stderr を合わせた末尾 131,072 バイト（128KB）です。

combined = (result.stdout + b"\n" + result.stderr)[-131072:].decode("utf-8", errors="replace")

数万行のファイルをそのまま --print に流し込むジョブや、長大なドキュメントを出力するジョブでは、正常出力が 128KB を超えてクォータメッセージが末尾から外れることがあります。その場合 quota-message として検知されず、3回 exit 1 を繰り返してようやく repeated-exit-1 で開きます。その間の2回分のジョブは「静かに失敗している」期間として存在します。入力が 100KB を超えるジョブは 50KB 前後に分割するか、中間ファイルに落としてから Claude に渡す設計に切り替えました。

④ jq が未インストールだと health チェックが誤 RED を出す

automation-health.sh のセクション 1.5 は jq で JSON を解析します。

quota_open=$(printf '%s' "$quota_state" | jq -r '.is_open // false' 2>/dev/null)

jq がなければ quota_open が空文字列になり、ng "quota guard status の取得失敗" が出て exit 1 します。ガード自体は正常に動いているのに health が RED になるという混乱が生まれます。brew install jq で即解決ですが、「サーキット状態の取得に失敗している」と誤解してセットアップをやり直す前に which jq を確認してください。

⑤ ~/.discord/notify.sh が存在しないとサーキット開放が完全に無音になる

def notify_circuit_open(reason: str, cooldown: int) -> None:
    script = Path.home() / ".discord" / "notify.sh"
    if not script.exists():
        return  # エラーなし・ログなし・通知なし

notify.sh が存在しなければ関数は何もせず戻ります。サーキット自体は正常に開き状態ファイルにも記録されますが、外から知る手段がゼロになります。この仕組みを入れた意義が半分消えます。私は最初の2週間この設定を怠り、朝に automation-health.sh を走らせるまで前夜のクォータ超過に気づかなかったことが3回ありました。既製スクリプトがなければ Webhook URL への curl を1行書くだけで動きます。Discord Webhook のセットアップは15分で終わります。環境構築当日に済ませてください。

⑥ CLAUDE_GUARD_COOLDOWN_SECONDS を短くしすぎてサーキットが途中で閉じる

CLAUDE_GUARD_COOLDOWN_SECONDS=3600 に設定した場合、日曜22時にサーキットが開いても月曜0時には CLOSED に戻ります。週次クォータが月曜3時にリセットされる環境なら、0〜3時の間にジョブが再実行されて失敗を繰り返し、repeated-exit-1 で再び OPEN というループに入ります。現在のサーキット状態ファイルを確認すると opened_at=1785448823・open_until=1785470423 の差分はちょうど 21,600 秒（6時間）です。この値は1週間の観測でリセットタイミングを実測してから決めています。デフォルト 21,600 秒を変えるなら必ず同じプロセスを踏んでください。

⑦ CLAUDE_GUARD_NOW をテスト後に .zshrc に残すと本番の時刻判定が壊れる

テスト目的で .zshrc に export CLAUDE_GUARD_NOW=1785470424 と書いた後に削除を忘れると、全ての now() 呼び出しがそのタイムスタンプを返し続けます。

def now() -> int:
    return int(os.environ.get("CLAUDE_GUARD_NOW", str(int(time.time()))))

未来の値ならサーキットが開かない（open_until との比較で常に CLOSED 判定）、過去の値なら normalize_expired() が常時 CLOSED に戻すという状況になります。テスト後は必ず unset CLAUDE_GUARD_NOW してください。時刻操作はコマンドの前置き形式で渡すのが安全です。

CLAUDE_GUARD_NOW=1785470424 ~/.claude/scripts/claude-quota-guard.py --status | jq .

この形式なら .zshrc には残りません。

⑧ CLAUDE_AUTOMATION_GUARD=1 チェックを入れていないジョブを手動実行して本番データを上書きした

run_job() が注入する CLAUDE_AUTOMATION_GUARD=1 は、ジョブスクリプト自身がチェックしなければ意味がありません。デバッグ目的で bash run.sh を直接叩くと、launchd 経由と同じ動作をします。実際に note-autolike のスクリプトをデバッグ実行したとき、本番の自動いいねが40件走りました。重要ジョブのスクリプト先頭には必ず以下を入れています。

[ "${CLAUDE_AUTOMATION_GUARD:-0}" = "1" ] || { echo "自動実行専用です" >&2; exit 1; }

SNS 投稿・API 書き込み・ファイル上書きを伴う全ジョブに適用しています。

⑨ last_success の古さに気づかず長期スキップを見逃す

サーキットが repeated-exit-1 で開いた場合、consecutive_failures はリセットされますが last_success はそのまま保持されます。現在の状態ファイルを確認すると last_success=1785280668・opened_at=1785448823 で、差分は 168,155 秒、約 46.7 時間です。サーキットが開く約2日前から Claude の正常終了が1度もなかったことになります。この値を定期監視していれば「サーキットが開く前から何かがおかしかった」と事前に気づけます。--status で取得できる値なので、automation-health.sh の次の改善として追加する予定です。

---

ベストプラクティス

1. セットアップ第一歩は CLAUDE_REAL_BIN の設定

フォーク爆弾の防止策はただ一点です。~/.local/bin/claude をガードへのシンボリックリンクに書き換える前に、必ず CLAUDE_REAL_BIN を設定してください。~/.zshrc と全 plist の EnvironmentVariables の両方に書かないと launchd ジョブで効きません。

2. plist の EnvironmentVariables に依存変数を全て直書きする

CLAUDE_REAL_BIN・CLAUDE・CLAUDE_BIN・CLAUDE_GUARD_COOLDOWN_SECONDS・CLAUDE_GUARD_FAILURE_THRESHOLD。これらを ~/.zshrc に書いただけでは launchd ジョブに届きません。シェルラッパー経由でも動きますが、依存が増えて障害点が増えます。plist 直書きが最も確実です。

3. jq のインストールを先に確認する

which jq || brew install jq を環境構築手順の最初のステップにしてください。automation-health.sh の JSON 解析は全て jq に依存しています。

4. Discord 通知を初日に設定する

~/.discord/notify.sh が存在しなければサーキット開放は完全無音です。Webhook URL への curl を1行書くだけで動きます。これを後回しにすると「止まっていることに気づかない」という元の問題に戻ります。

5. ジョブスクリプトの先頭に CLAUDE_AUTOMATION_GUARD=1 チェックを入れる

[ "${CLAUDE_AUTOMATION_GUARD:-0}" = "1" ] || { echo "自動実行専用です" >&2; exit 1; }

手動デバッグ実行での本番操作事故を防ぎます。API 書き込み・SNS 投稿・ファイル上書きを伴う全ジョブに適用してください。

6. --job の plist は launchctl load 前にローカルで手動テストする

python3 ~/.claude/scripts/claude-quota-guard.py --job LABEL -- bash script.sh を手動で1回走らせて exit code を確認してください。-- の抜け・ラベルのタイポ・パスの誤りはここで全部拾えます。exit 2 であれば構文ミスです。

7. claude-status エイリアスで毎朝の確認を1行にする

alias claude-status='~/.claude/scripts/claude-quota-guard.py --status | \
  jq -r "if .is_open then \"🔴 OPEN reason=\(.reason) remaining=\(.remaining_seconds | . / 3600 | floor)h\" else \"🟢 CLOSED\" end"'

Discord 通知が飛ばなかった場合の保険として、朝の確認ルーティンに組み込んでください。

8. claude-recover は --reset と automation-health.sh をセットにする

--reset 単体では「CLOSED になったか」と「15本のジョブが正常再開したか」の両方が確認できません。

alias claude-recover='~/.claude/scripts/claude-quota-guard.py --reset && \
  bash ~/.claude/scripts/automation-health.sh'

このエイリアス1本で復旧と確認を一気に済ませます。

9. CLAUDE_GUARD_FAILURE_THRESHOLD をネットワーク環境に合わせる

デフォルト 3（10分以内に3回 exit 1）は Wi-Fi 不安定環境では誤発火しやすいです。VPN 切断が頻繁な場合は CLAUDE_GUARD_FAILURE_THRESHOLD=5 か、ウィンドウを CLAUDE_GUARD_FAILURE_WINDOW_SECONDS=300（5分）に絞ることを検討してください。ただし感度を下げすぎると本物のクォータ超過の検知が遅れます。自分の環境の障害パターンを1週間観察してから調整してください。

10. クールダウン値は実測から決める

Claude Code の週次クォータのリセットタイミングは公式に明示されていません。1週間、サーキットが開いた時刻と次の正常応答時刻を記録して平均を取ってから CLAUDE_GUARD_COOLDOWN_SECONDS を設定してください。デフォルト 21,600 秒（6時間）を変えるなら根拠を持って変えてください。

11. last_success の古さを定期監視する

24時間以上 last_success が更新されていなければ何かがおかしいサインです。automation-health.sh に以下のチェックを追加すると事前検知できます。

last_success=$(printf '%s' "$quota_state" | jq -r '.last_success // 0')
gap=$(( $(date +%s) - last_success ))
[ "$gap" -gt 86400 ] && wn "last_success が $((gap/3600))h 前 — Claude呼び出し成功が24h以上ない"

12. 入力が大きいジョブは分割して 128KB 制約を避ける

クォータメッセージが末尾 128KB 外に押し出されると repeated-exit-1 判定になります。入力ファイルが 100KB を超えるジョブは 50KB ずつ分割するか、要約→詳細の2段階処理にして各呼び出しの出力サイズを抑えてください。

13. CLAUDE_GUARD_NOW はコマンド前置きで渡す・.zshrc に書かない

テスト用の時刻注入は CLAUDE_GUARD_NOW=xxx ~/.claude/scripts/claude-quota-guard.py --status の形で渡してください。.zshrc に書くと本番環境に残留してサーキットの時刻判定が狂います。

14. automation-health.sh 自体を launchd で毎朝定期実行する

手動確認を習慣に頼るのは危険です。com.shun.daily-health-check.plist として毎朝6時に実行し、RED があれば Discord に通知するラッパーを噛ませれば確認漏れがゼロになります。私の環境では health check の結果も alerts チャンネルに流しています。

15. --reset は状態を確認してから打つ

--reset を打つ前に claude-status（または --status | jq .）で reason と remaining_seconds を確認してください。reason=quota-message で残り時間が数千秒残っている場合、クォータが本当に明けているかを確かめてから打つ判断が必要です。早すぎる --reset → 全ジョブ一斉再試行 → 連続 exit 1 → 再び repeated-exit-1 OPEN というループを避けるための一手間です。

---

まとめ

クォータに当たったとき、「何が起きているかを環境が叫んでくれる」状態を作るのがこの仕組みの全体像です。

claude-quota-guard.py がクォータメッセージを検知してサーキットを OPEN にする。notify_circuit_open() が ~/.discord/notify.sh を叩いて alerts チャンネルに通知する。翌朝の automation-health.sh がセクション 1.5 で WARN として拾う。claude-recover エイリアスで --reset と health チェックをセットで実行して復旧を確認する。この一連のフローが確立されれば、「止まっていることに気づかない」状態は存在しなくなります。

現在のサーキット状態ファイル（reason=quota-message・opened_at=1785448823・open_until=1785470423）は、この仕組みが実際に発動した証拠です。last_success=1785280668 から opened_at までの差は約 46.7 時間であり、これは「サーキットが開く前から何かが静かにおかしかった」ことを示しています。この観察自体が次の改善ポイントを示してくれます。

月120万の自動化基盤は「動いている」ことを前提に稼いでいるわけではなく、「止まったときに即座に検知して最短で復旧できる」構造で稼いでいます。クォータは必ず当たります。問題は当たったときに何が起きるかです。

---

仕組みの全体像・月120万の内訳・30日手順は有料noteにまとめています。
📕 Claude Code自律環境で、実際どう稼ぐか ― 仕組み・実例・始め方・サポート

---

Lily（@bokuwalily）― 個人開発者。Claude Code で自動化基盤を組みながら、iOSアプリやWebサービスを量産しています

• 制作物・記事は bokuwalily.com にまとめています🖥️
• AIで「寝てても回る仕組み」を作って月120万にした話は noteの有料記事 に💰
• OSS: github.com/bokuwalily 🐙
• 最新情報・お問い合わせは X @bokuwalily へ🌍

皆さんの ❤️ やシェアが励みになります！