Claude appsゲートウェイで開発者ごとの利用上限を決める

公開 更新 著者 永上裕之導入とルール
財布の上に小さな門があり、決まった額を超えるとそっと閉まるイメージ

この記事の要点

  • ゲートウェイは、開発者ごとの利用額に日・週・月の上限をかけ、超えたら次の要求から429で止める
  • 上限は設定ファイルではなく、管理用の API で入れる。個人・グループ・組織の順に、より細かい指定が優先される
  • 金額は見積もりで、請求書そのものではない。保存先のデータベースが落ちたときは、初期設定では止めずに通す

活用例:開発者が増えても、AI の利用額が想定を超えないよう、人ごとの上限をかける

部署
情報システム・経営管理
使うもの
Claude apps ゲートウェイの利用上限(spend limits)
AIに任せる
管理用の要求の下書きと、上限の一覧づくり
人が決める
上限の金額・グループの分け方・超えたときの案内文

開発者が増えると、AI の利用額も増えます。ところが、ゲートウェイの初期設定では、すべての利用が1つの共通の資格情報を通って送られます。請求書には「誰がいくら使ったか」が出ません。

この記事では、公式ドキュメント「Spend limits」(2026年11月16日確認)にもとづいて、開発者ごとの上限のかけ方をまとめます。ゲートウェイそのものの考え方は Claude appsゲートウェイ の記事で説明しています。

結論:上限は管理用 API で入れ、超えたら次から止まる

ゲートウェイの設定ファイルに admin の項目を書くと、/v1/organizations/spend_limits という管理用の窓口が使えます。上限の金額そのものは設定ファイルではなく、この窓口へ要求を送って決めます。

開発者が上限を超えると、その後の要求にはエラー429が返ります。上限が0円より大きければ、期間が切り替わるとまた使えます。上限を上げれば、すぐ再開できます。

上限の入れ方

組織全体の初期値として、月500ドルを入れる例です(金額はセント単位の整数の文字列で、50000は500ドル)。

curl -sS -H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" -H "Content-Type: application/json" -d '{"scope": {"type": "organization"}, "amount": "50000", "period": "monthly"}' https://(ゲートウェイの住所)/v1/organizations/spend_limits

契約社員のグループには、もっと厳しい日ごとの上限を重ねられます。

curl -sS -H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" -H "Content-Type: application/json" -d '{"scope": {"type": "rbac_group", "rbac_group_id": "contractors"}, "amount": "10000", "period": "daily"}' https://(ゲートウェイの住所)/v1/organizations/spend_limits

3つの項目の意味は次のとおりです。

項目値意味
scope.typeuser・rbac_group・organization個人、認証基盤のグループ、組織全体
amountセントの整数の文字列、または nullnull は無制限。"0" は、すべての要求を止める
perioddaily・weekly・monthly期間ごとに1つずつ持てる。どれか1つでも超えれば止まる

優先順位:いちばん細かい指定が勝つ

グループや組織の上限は、全員で分け合う「共有の財布」ではなく、1人ずつに配る初期値です。ある人に実際にかかる上限は、期間ごとに次の順で決まります。

  1. その人個人への指定
  2. 所属するグループの上限のうち、いちばん厳しいもの
  3. 組織全体の初期値
  4. どれも無ければ、無制限

管理 API を使う人の認証

管理用の窓口に入る方法は2つです。

超えたときの応答

要求のたびに、ゲートウェイがデータベースで、その人の上限と期間内の利用額を1回の問い合わせで確かめます。超えていると、429と「billing_error」が返り、再試行しない指示も付きます。

上限が0より大きいときは、メッセージにいつ復活するか(UTCの日付)が入ります。管理者が blocked_message を設定していると、問い合わせ先の案内も足されます。たとえば「spend limit reached · resets Dec 1 · request an increase at …」のような文です。

上限が"0"のときは日付が入りません。リセットでは解除されないためです。複数の上限を超えたときは、いちばん最後に復活するものが示されます。

期間の区切りは、UTC の暦どおりです。日は0時、週は月曜、月は1日に切り替わります。トークンを数えるだけの要求は、無料なので止めません。

金額はどう見積もられるか

応答のあとに、利用量の計測が、トークン数から金額を足していきます。この金額は見積もりで、請求書ではありません。 歯止めのための仕組みなので、請求の照合は、プロバイダー側の利用記録でします。

単価は次の順で決まります。

  1. 設定の pricing.overrides の一致する行(v2.1.227 以降)
  2. 実際に送るモデルの名前から分かる定価
  3. 設定で対応づけたモデル名の定価(v2.1.218 以降。名前にモデル名が入らない接続先用)
  4. 分からないときは、100万トークンあたり入力5ドル・出力25ドルの高めの値。無料にはならない

さらに pricing.multiplier(初期値1)を掛けられます。途中で中断した通信にも、すでに送った文字数から出力の下限を見積もって課金するので、早く切って上限をすり抜けることはできません。

データベースが落ちたとき

事前の確認は、保存先のデータベースに2秒の制限で問い合わせます。届かないときは、初期設定では止めずに通し、警告を記録します。 止めたいときは enforcement.fail_closed_on_error: true にします。どちらにするかは、「止まる不便」と「超過のリスク」のどちらが大きいかで決めます。

会社での決め方の例

まとめ

  1. 上限は管理用 API で入れ、日・週・月ごとに持てる
  2. 個人、グループ、組織の順に、細かい指定が優先される
  3. 超えると429で止まり、メッセージに復活日が出る
  4. 金額は見積もり。データベース障害時は初期設定では通す

出典:Spend limits(公式ドキュメント)

永上裕之

ユニコスクール株式会社 代表取締役。AIエージェント専門のスクール&コミュニティを運営しています。

この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。

関連する記事