Claude Apps Gatewayのスペンドリミットでユーザー別のコスト上限を設定する方法を試してみた

はじめに

こんにちは。DXソリューション営業本部の松浦です。

Claude Apps Gateway経由でClaude Code / Claude Desktop（Cowork）を組織展開する場合、推論はすべて1つの共有の認証情報（Amazon Bedrockのクレデンシャルなど）を通じて行われます。そのため、提供元（AWSなど）から届く請求は共有の認証情報単位でまとめられ、誰がどれだけ使ったかは請求そのものからは分かりません。ユーザーごとの上限を設けておかないと、特定の利用者やエージェントの誤動作によって、想定外の高額なコストが発生してしまうリスクがあります。

Claude Apps Gatewayには、この課題に対応する「スペンドリミット（spend limits）」という仕組みがあり、ユーザー単位・グループ単位・組織単位でコストの上限を設定し、超過したユーザーからのリクエストをGatewayが自動的に遮断できます。本記事では、実際にユーザー単位で上限を設定し、超過後にリクエストが遮断されるところまでを実機で確認した結果をご紹介します。

こんな方におすすめの内容です。

• Claude Code / Claude Desktopの利用コストが、特定のユーザーやエージェントに偏って膨らむことを防ぎたい方
• 共有の認証情報経由での利用において、コストの上限を設定できるか知りたい方
• 上限を超過した場合に、実際にどのようなエラーで利用がブロックされるのか知りたい方

まずは、スペンドリミットの全体像から見ていきましょう。

Claude Apps Gatewayのスペンドリミットとは

スペンドリミットは、Claude Apps Gateway経由の利用コストに、日次・週次・月次のいずれかの期間で上限（キャップ）を設定できる機能です。上限はユーザー単位・グループ単位・組織単位のいずれでも設定でき、上限を超えた利用者は次のリクエストから429エラーで拒否され、期間がリセットされるか管理者が上限を引き上げるまでブロックされ続けます。本記事では、このうちユーザー単位での設定を実機で検証します。

上限はgateway.yamlに直接書き込むのではなく、Gatewayが提供するAdmin API（/v1/organizations/spend_limits）経由で設定・変更します。このAPIは、Anthropicが公開しているAdmin APIのスペンドリミット関連エンドポイントと同じ形式（リクエスト・レスポンスの構造）を踏襲しているため、そちらのAPI向けに書かれたクライアントを、接続先のURLを変えるだけでGateway向けに転用できます。

リクエストのたびにGatewayが何を判定しているかを単純化すると、次のような流れになります。

前提として準備しておくもの

本記事は、Claude Apps GatewayとSSO IdPとの基本的な連携（クライアントID・シークレットの登録など、OIDCによるサインインそのものの設定）がすでに完了していることを前提とします。Gateway・Claude Desktop側の基本的な設定内容は以下の記事で紹介していますので、あわせてご参照ください。

Claude DesktopをSSO化！Apps Gateway + Bedrock連携を試してみた
Claude Desktop（Cowork）は、自社構築のClaude Apps Gatewayを経由させることでSSO認証を挟んだ状態のままAmazon Bedrockに接続して利用できます。Gateway・Desktopの設定の流れと、実機で確認できた動作結果を紹介します。
 

また、スペンドリミットのscope.typeには、後述のとおりuser（個人）だけでなくrbac_group（IdPのグループ）も指定でき、Gatewayが利用するグループ情報は以下の記事で紹介したグループ別アクセス制御と同じ、SSO IdP側のグループが使われます。グループ単位でのコスト管理を検討する場合は、こちらもあわせてご参照ください。

Claude CodeをIdPのグループ単位でアクセス制御する方法を実際に試してみた
Claude Apps GatewayのmanagedポリシーはSSO IdPのグループ情報をもとにClaude Desktop（Cowork）の利用可否を制御できます。非許可グループのユーザーが起動時点で完全にブロックされることを実機で確認した結果を紹介します。
 

本記事では、この前提の上に追加で必要になる、上限設定用のAdmin APIを有効化する部分から取り上げます。

設定の流れ

admin:ブロックの有効化

gateway.yamlにadmin:ブロックを追加すると、Gatewayが上限設定用のAdmin APIを/v1/organizations/spend_limitsとして提供するようになります。公式ドキュメント（Claude apps gateway configuration）に記載されている設定例は次のとおりです。

admin:
  write_keys:
    - { id: verify-write, key: "${GATEWAY_ADMIN_WRITE_KEY}" }   # 上限の作成・変更まで可能なキー
  read_keys:
    - { id: verify-read, key: "${GATEWAY_ADMIN_READ_KEY}" }     # 参照（GET）のみ可能なキー

write_keys・read_keysは、いずれも文字列の配列ではなく{id, key}オブジェクトの配列で指定する形式です（idは監査ログにadmin-key:<id>として記録されるための識別名で、read_keys・write_keys間で重複しない名前にする必要があります）。今回の検証では、このwrite_keysで発行したキーをx-api-keyヘッダーに指定してAdmin APIを呼び出しました。

Admin APIでの上限設定

上限そのものはgateway.yamlには書かず、admin:ブロックが有効化されたあとにAdmin APIへPOSTして設定します。1回のPOST /v1/organizations/spend_limitsリクエストが{scope, amount, period}の組で1つの上限を作成・置換する仕組みです。

今回の実機検証では、動作確認をしやすくするため、テストユーザー1名（scope.type: user）に対して日次$0.10（10セント）という、意図的に極端に小さい上限を設定しました。

curl -sSk https://<GatewayのURL>/v1/organizations/spend_limits \
  -H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope": {"type": "user", "user_id": "<testuser1のOIDC sub>"}, "amount": "10", "period": "daily"}'

※ user_idには、SSO IdP（今回はAmazon Cognito）がユーザーごとに発行する固定のID（OIDCのsub）を指定します。上記コマンド例のホスト名・IDは、検証環境固有の値を伏せた形に置き換えています。

設定した上限額や現在の消費額を確認する場合も、同じくAdmin API経由になります。特定ユーザーの適用上限と期間内消費額はGET /v1/organizations/spend_limits/effectiveで取得できます。

curl -sSk "https://<GatewayのURL>/v1/organizations/spend_limits/effective?user_ids[]=<testuser1のOIDC sub>" \
  -H "x-api-key: $GATEWAY_ADMIN_READ_KEY"

公式ドキュメントの機能一覧には「Admin UI: Not available（管理UIはない。設定はYAMLファイルで行い、変更にはGatewayの再デプロイが必要）」と明記されており、Gatewayには設定値や消費状況を画面上で確認できる管理UIは用意されていません。現時点では、上限額・消費額の確認はAdmin APIを直接呼び出す方法に限られます。

実機確認

上記の上限を設定した状態で、テストユーザーのアカウントからClaude Desktop（Cowork）でメッセージを送信し、日次$0.10の上限を使い切るまで送信を続けました。その結果、消費額（period_to_date_spend）が$0.13852まで進んだ時点で上限を超過し、続くメッセージ送信でClaude Desktop上に次のエラーが表示され、送信がブロックされることを確認しました。

※ 画面上部に写っている「Not enough disk space」の警告は、検証端末のワークスペース領域のディスク容量に関する別件の通知であり、スペンドリミットの判定とは無関係です

画面左下のアカウント表示のとおり、これはGateway経由で接続したテストユーザーのアカウントです。

補足：429応答の仕様と上限の優先順位

今回実機で確認できたのは、Claude Desktop（Cowork）の画面に表示される「API Error: Request rejected (429) · spend limit reached」というメッセージまでです。この429応答そのものの詳細な仕様として、公式ドキュメントには次のような記載があります。

• エラーの形式：
  上限を超えたリクエストにはerror.type: billing_error、レスポンスヘッダーx-should-retry: falseが付与されます。
• メッセージ内容とバージョン要件：
  Gatewayサーバーがv2.1.225以降の場合、エラーメッセージに超過した期間とリセット時刻（UTC）が含まれ（例：spend limit reached (daily; resets 2026-08-08 00:00 UTC)）、リセットまでの秒数を示すretry-afterヘッダーも付与されます。v2.1.225より前のバージョンでは、期間・リセット時刻を含まないspend limit reachedという簡潔なメッセージになります。
• リセットのタイミング：
  上限はUTCの暦日・暦週・暦月の境界でリセットされます（日次は毎日00:00 UTC、週次は月曜、月次は1日）。

また、上限はuser（個人）・rbac_group（グループ）・organization（組織）の3つの単位で設定でき、同じユーザーに複数の単位の上限が同時に設定されている場合にどれが優先されるかも、公式ドキュメントに明記されています。

期間（daily / weekly / monthly）ごとに、この①→②→③→④の順で実際に適用される上限が1つに解決される仕組みです。判定の流れを図にすると、次のようになります。

活用イメージ

ユーザー単位・グループ単位でコストの上限を設定できる仕組みは、ひとつのGateway構成のまま、次のような運用に活用できます。

• 特定ユーザー・チームの利用量の暴走防止：
  エージェント処理を多用するユーザーや、まだ利用に慣れていないユーザーに個別の上限を設定しておくことで、想定外の利用増加を早期に検知・抑制できます
• グループ単位でのコスト方針の使い分け：
  前提として紹介したグループ別アクセス制御と同じIdPグループ情報を使って、部署やチームごとに異なるコスト方針（上限額）を適用できます
• 組織全体のコスト超過防止：
  組織既定の上限を設定しておくことで、個別の上限を設定していないユーザーについても、想定外の高額コストが発生するリスクに一定の歯止めをかけられます

まとめ

Claude Apps Gatewayのスペンドリミットを使うと、共有の認証情報経由で利用するClaude Code / Claude Desktop（Cowork）のコストに、ユーザー単位・グループ単位・組織単位で上限を設定できます。今回の実機確認では、上限を超過したユーザーでは429エラーが発生し、ブロックされることが確認できました。

「共有の認証情報を使いながら、ユーザーごとのコストに歯止めをかけたい」といった要件を検討する際の、実装パターンのひとつとして参考にしていただければ幸いです。

QESでは、ガバナンス整備・セキュアな利用環境構築・利活用コンサルティング・セキュリティレビューまで、Claude / Claude Code の組織導入を一貫して支援しています。AWS（Amazon Bedrock）経由での提供にも対応しています。支援内容は下記のサービスページ、および無料の「Claude 導入チェックリスト」をご覧いただくか、お問い合わせフォームよりお気軽にご相談ください。

Claude 導入支援サービス | QES
Anthropic のAIエージェント「Claude」の導入を、ガバナンス整備・利用環境構築（Enterprise / Amazon Bedrock）・利活用コンサルティング・セキュリティレビューまでQESが一貫して支援します。
 

※このブログで参照されている、Anthropic、Claude、Claude Code、Claude Cowork は、Anthropic, PBCの米国およびその他の国における商標または登録商標です。

※このブログで参照されている、Amazon Web Services、AWS、Amazon Bedrockは、Amazon.com, Inc.またはその関連会社の商標です。