Paperclipの予算上限は、Claude Codeのサブスクでも止めてくれるのか？

AIエージェントを夜のあいだ回しておいて、朝起きたら請求が膨らんでいた、なんて想像するだけで胃が痛くなりませんか？ GitHubでスターが9万を超えたPaperclipは、エージェントごとに月の予算をつけて、上限に来たら止める仕組みを売りにしています。ただソースを読んでいくと、Claude Codeをサブスクのログインで動かしている人ほど、この上限が効かない作りになっていました。

test-driveで立ち上がるのは、CEOが1体だけ？

GitHub - paperclipai/paperclip: The open-source app everyone uses to manage agents at work

The open-source app everyone uses to manage agents at work - paperclipai/paperclip

github.com

Paperclipは、複数のAIエージェントに組織図・目標・予算を持たせて「会社」として動かすMITライセンスのOSSです。Claude Code、Codex、Cursor、OpenClawなどをエージェントとしてつなげます。いちばん手軽な入口がtest-driveで、READMEにはこの1行が載っています。

ANTHROPIC_API_KEY=... npx paperclipai test-drive

ここ、勘違いしやすいところです。doc/CLI.mdとcli/src/commands/test-drive.tsを読むと、作られるのは「Test Company」という会社とCEOロールのエージェント1体だけでした。ゴールもプロジェクトもタスクも、定期実行のハートビートも作りません。

つまりtest-driveを叩いただけでは、勝手に動き出すものは何もないんです。--data-dirを省くと毎回新しい一時ディレクトリが作られ、組込DBを使うのでDATABASE_URLが設定された環境では起動を拒否されます。複数体を並べて放置したいなら、UIからエージェントを足して、予算とハートビートを自分で設定することになります。

ハートビートを入れないと、エージェントは起きない

Paperclipのエージェントは、ハートビートと呼ばれる定期的な起床で仕事を確認し、割り当てられたタスクを進めます。ところがUIでエージェントを作るときの既定値（ui/src/components/agent-config-defaults.ts）はheartbeatEnabled: falseでした。オンにしたときの間隔は300秒が初期値で、仕様書では最短30秒まで縮められます。

同じファイルにはdangerouslySkipPermissions: trueも並んでいます。Claude Codeを権限確認なしで動かすオプションが、オンの状態で作成フォームが開くということです。自分のリポジトリを作業ディレクトリに指定するなら、ここは一度見直したい項目です。

放置運用は、ハートビートをオンにしたエージェントが5分おきに起きる状態から始まります。そこに予算がちゃんとブレーキとして効くのか。ここからが本題です。

上限に触れたエージェントは、どの時点で止まるのか？

予算の判定はserver/src/services/budgets.tsにまとまっています。掛けられる範囲は会社・エージェント・プロジェクトの3種類で、会社全体とエージェント個別に二重で掛けられます。会社とエージェントの予算は暦月単位、プロジェクトは既定で累計です。見ている指標はbilled_cents、つまり課金されたセント数でした。

既定では80%で警告、100%でハードストップです。100%に届くと、そのエージェントを一時停止し、実行中の作業をキャンセルし、新しい起動も拒否します。

気をつけたいのは判定のタイミングです。costs.tsでは、コストの記録をDBに書き込んだあとでevaluateCostEventを呼んでいます。1回の実行が上限をまたげば、またいだ分を使ってから止まる順番です。1回の実行で回せるターン数（maxTurnsPerRun）も既定で1,000あるので、重いタスクなら上限を少し超えてから止まると見ておくのが安全、というのが僕の読みです。

サブスクログインだと、予算は0のまま動かない

これは罠でした。Claude Codeのアダプタ（packages/adapters/claude-local/src/server/execute.ts）は、環境変数にANTHROPIC_API_KEYがあればAPI課金、なければサブスク扱いと判定します。そしてサブスク扱いの実行は、サーバー側でコストのセント数が0に揃えられます。

トークン数は記録されても、予算が見るbilled_centsは増えません。ProやMaxのログインで回している限り、月の予算を1,500円にしても、80%の警告も100%の停止も発火しない計算です。

コードの読み違いを疑って、GitHubのやりとりも確認しました。ダッシュボード表示を直すプルリクエスト#10871（9月29日時点で未マージ）が、まさにこの挙動を「サブスク課金では予算を強制できない」と説明しています。OpenAIのサブスクで動かしたエージェント1体が1時間で1,980万入力トークンを使っても止まらなかった、という報告もIssue #339に上がっていました。

サブスクは定額なので、請求そのものが青天井になるわけではありません。困るのは、プランの使用量の上限を一晩で溶かして、翌朝の自分の作業が止まるほうです。test-driveがAPIキーを前提にしているのも、この仕組みと噛み合っています。

止まったあと、誰が戻すのか？

ハードストップに届くと、budget_override_requiredという承認待ちのインシデントが立ちます。ボード、つまり人間側が「予算を上げて再開」か「止めたまま」を選ぶまで、そのエージェントは戻りません。再開の処理も、予算が理由で止まったエージェントだけを待機状態に戻す作りです。

もう1つの節目が月初のリセットです。窓はUTCの暦月なので、日本時間だと毎月1日の朝9時にカウントが0に戻ります。1日の0時から9時までに使った分は、まだ前月の予算として数えられるわけです。日本時間で区切る設定は見当たりませんでした。

手元で試すなら、APIキーと小さな上限から

予算で止めたいならAPIキー課金、サブスクで回すならPaperclipの予算には頼らない。この2択を先に決めてしまうのが早いです。予算の挙動を自分の目で確かめるなら、次の順で組むと財布へのダメージを小さく抑えられます。

1. Anthropic側でも月の使用上限をかけた、Paperclip専用のAPIキーを用意する
2. ANTHROPIC_API_KEY=... npx paperclipai test-drive --data-dir ./pc-trialで起動し、データを残す
3. 会社の予算を約1,500円（10ドル）、エージェント個別を約450円（3ドル）にする
4. ハートビートは300秒のまま、1体だけオンにする
5. ダッシュボードで80%の警告と、100%で止まったあとの実額を見る

データを残しておけば、止まった時点で上限をいくら超えていたかをあとから確認できます。あなたのClaude Code、今はサブスクとAPIキーのどちらで動いていますか？ その答えで、Paperclipの予算が財布の上限になるかどうかが決まります。