Claude Code LLM gatewayとは — 選び方と全体設計
Claude Codeをゲートウェイ経由で使う設計を、Anthropic製のClaude apps gatewayと社内の既存LLMゲートウェイの前提条件・制限・詰まりどころで比べます。
Claude Codeをゲートウェイ経由で使う設計とは
ゲートウェイは、Claude Codeとモデルプロバイダーの間に組織が立てるプロキシです。Claude Codeはプロバイダーへ直接ではなくゲートウェイの宛先へAPIトラフィックを送り、ゲートウェイが組織側の認証情報を使って転送します。開発者はプロバイダーの認証情報を持たず、ゲートウェイに対して認証するだけになります。認証・利用状況の追跡・予算管理・監査ログが1か所に集まります。
ここで動く認証情報は2種類です。開発者ごとの開発者クレデンシャルは、ゲートウェイが発行し、ゲートウェイへの認証と利用状況の紐付けに使います。組織で1つだけ持つプロバイダークレデンシャルは、転送されたトラフィックすべてが共有します。
選択肢は2つあります。Claude Codeのclaudeバイナリに組み込まれたAnthropic製のClaude apps gatewayを使うか、組織がすでに運用している社内の既存LLMゲートウェイへ接続するかです。
ゲートウェイを介さずプロバイダーへ直接つなぐ設定もあります。Bedrockなら/setup-bedrockウィザード、Google CloudのAgent Platformなら/setup-vertexウィザードが用意されています。
2つの選択肢の出発点
Claude apps gateway
Claude Codeの各リリースと一緒にテストされるセルフホスト型です。企業のIdP経由の/loginでサインインし、IdPグループ単位でモデルアクセスとmanaged settingsを強制します。OTLPの利用状況メトリクスは自社の可観測性スタックへ流れます。
社内の既存LLMゲートウェイ
すでに投資済みの製品をそのまま使います。Anthropicはこうした製品を推奨・保守・監査せず、Claude以外のモデルへのルーティングもサポート対象外です。Claude Code側はANTHROPIC_BASE_URLと認証情報の設定で向け先を変えます。
Claude apps gatewayを立てる前に満たす条件
「別製品の調達が要らない」ことと「何も用意せず立ち上がる」ことは別です。claude gatewayは--configでYAMLを渡して起動するサブコマンドで、v2.1.287で出したヘルプは次のとおりです。
$ claude gateway --help
Usage: claude gateway [options]
Run the enterprise auth/telemetry gateway
Options:
--config <path> Path to gateway YAML config
-h, --help Display help for commandオプションは--configだけで、設定は全部YAMLに入ります。設定ファイルを渡さずに起動すると、error: required option '--config <path>' not specifiedで終了します。存在しないパスを渡したときはclaude gateway: ENOENT: no such file or directory, open './nope.yaml'でした。upstreamsを欠いたYAMLは、upstreamsが必須だと名指しするバリデーションエラーのJSONで止まります(いずれもv2.1.287で、一時ディレクトリの中で試したものです)。
起動前に必要なものは、公式の前提条件の表にこう並んでいます。
- Claude Code v2.1.195以降。サーバー側も各開発者の端末側も同じ条件で、Claude Platform on AWSをアップストリームにするならサーバー側はv2.1.198以降です
- OIDC対応のIdP(Okta・Microsoft Entra ID・Google Workspace・Keycloak・Dexなど)。SAMLとLDAPは非対応です
- PostgreSQL 14以降。デバイスサインインの状態とレート制限のカウンターを持ちます
https://で開発者の端末とサインイン用ブラウザから届くこと- プライベートネットワーク上のアドレス。
/loginは、ホスト名がプライベートアドレスにしか解決されないゲートウェイにしか接続しません - Linuxのネイティブバイナリ(macOSはローカル開発用で、Windowsはサーバーとして非対応)
最後から2番目の条件は、セキュリティ上の仕様です。信頼したゲートウェイは開発者の端末でコマンドを走らせる設定を配れるため、公開アドレスのゲートウェイは受け付けません。社内網が自組織所有の公開IPv4空間で振られているなら、そのブロックを宣言して許可します。
起動時の失敗は握りつぶされません。設定、Postgres接続、OIDC discovery、アップストリームのクライアント構築のどれかが失敗すると、ゲートウェイはエラーで終了します。縮退したまま配信は続けません。ゲートウェイに届かない端末では、サインイン済みのセッションが約10秒後にエラーで終了します。
稼働中のゲートウェイは、自身のプロトコル参照をGET /protocolで返します。SSOサインイン、推論、managed settings配布、モデル検出、テレメトリのエンドポイントが載っています。
IdPがSAMLだけの組織は、OIDCブリッジを前段に置かない限りこの選択肢から外れます。ここが最初の分かれ目です。
構築そのものはコードで管理できます。AWS/GCPそれぞれの公式Terraformバンドルが、2パスのapplyを必要とする理由まで含めClaude apps gatewayをTerraformで構築するにあります。クラウド別の手順はAWSにデプロイする編とGCPにデプロイする編が別にあります。
ゲートウェイ経由のセッションで変わる機能
Claude apps gatewayでサインインしたセッションは、Claude Code本体の機能にも差が出ます。公式の「Availability and limitations」の表から、選定に響く行を抜きます。
gatewayセッションで使えないもの
サーバー側のWeb検索
CLIはゲートウェイの先のアップストリームを判別できないため、Web検索の対応を確認できず、WebSearchを無効にします。
1時間のキャッシュTTL
すべてのアップストリームが1時間TTLに対応するとは限らないため、CLIは拡張キャッシュTTLのベータを省きます。プロンプトキャッシュ自体は使えますが、有効期間は5分です。
claude.aiが必要な機能
Remote Control、
/design-sync、/design-loginは使えません。/importのようにフィーチャーフラグの取得を要する機能も同じ扱いです。
一方、標準のプロンプトキャッシュ(cache_controlの転送)、IdPグループ単位の支出上限、Claude Desktopへの設定配布(ポリシーでの有効化が必要)は使えます。社内の既存ゲートウェイでは、どの機能が通るかは、ヘッダーやフィールドをどこまで転送するかで決まります。公式の互換性ガイドでは、feature pass-throughの節がその一覧です。
評価軸と比較表
比較の軸は次の5つです。
- 認証方式: ブラウザSSOか、ゲートウェイ製品固有の方式か
- 保守負担: Claude Codeのリリースに自動追従するか、ヘッダーやリクエストフィールドの変更を自分たちで追いかけるか
- アップストリームの切替容易性: 開発者の端末設定を変えずにプロバイダーを切り替えられるか
- CI・非対話パイプラインへの対応: サービストークンのような無人認証の手段があるか
- 実行環境: ゲートウェイを動かすOSや前提が決まっているか
| 評価軸 | Claude apps gateway | 社内の既存LLMゲートウェイ |
|---|---|---|
| 認証 | Claude apps gateway企業IdP経由のブラウザSSO(/login) | 社内の既存LLMゲートウェイ製品ごとの認証方式に依存 |
| 保守 | Claude apps gatewayClaude Codeと同時リリースされ自動追従 | 社内の既存LLMゲートウェイヘッダー・フィールドの変更を自分たちで追従 |
| アップストリーム切替 | Claude apps gateway単一のAnthropic形式エンドポイントで端末を変えずに切替可能 | 社内の既存LLMゲートウェイAnthropic形式のエンドポイントを1つ公開していれば同様。プロバイダー固有形式だと端末側の再設定が要る |
| CI・非対話パイプライン | Claude apps gatewayブラウザのデバイスフローのみで、承認する開発者がいないパイプラインは認証できない。サインイン済みの端末上のclaude -pやAgent SDKはそのセッションを使える | 社内の既存LLMゲートウェイ製品次第。GitHub ActionsではANTHROPIC_BASE_URLをworkflowのenvに置き、認証情報をanthropic_api_key入力で渡せる |
| 実行環境 | Claude apps gatewayLinuxのネイティブバイナリ(macOSはローカル開発用) | 社内の既存LLMゲートウェイ製品依存 |
強みと弱みはどこに出るか
Claude apps gatewayと既存ゲートウェイの得意不得意
Claude apps gateway
SSOとOTLPテレメトリが標準で入り、オフボーディングはIdP側のユーザー停止で済みます。停止後のアクセスはセッション有効期間(既定1時間)で切れます。設定はgateway.yamlで行います。
社内の既存LLMゲートウェイ
運用体制をそのまま活かせて、Claude以外のモデルも扱う基盤に載せられます。
既存ゲートウェイで繋ぐときの固定と詰まりどころ
既存ゲートウェイは、ANTHROPIC_BASE_URLと認証情報を端末へ配って成立します。配布が効いているかは、開発者が/statusで確かめられます。
配布の確認
- 1
claudeを起動する
ログイン画面が出たら、ゲートウェイの認証情報は配られていません。
- 2
/statusのStatusタブを見る
Anthropic base URLの行はゲートウェイのアドレスが設定されているときだけ出ます。Auth tokenかAPI keyの行、またはapiKeyHelperの表示が認証情報の有効を示し、Login methodにclaude.aiのアカウントが出ていれば未配布です。 - 3
テストメッセージを送る
エラーなく応答が返れば、接続は通っています。
認証情報の変数は、ヘッダーが違います。ANTHROPIC_AUTH_TOKENはAuthorization: Bearer、ANTHROPIC_API_KEYはx-api-key、apiKeyHelperは両方で送ります。ゲートウェイが読まないヘッダーに入れると401になるため、検証で401が返ったら変数を替えて試します。
端末を管理する側には、向け先を固定する手段もあります。managed settingsでallowedProvidersを["customEndpoint"]にし、同じファイルのenvブロックにANTHROPIC_BASE_URLを置きます。Claude Codeは他の向け先(Anthropic直結や開発者個人のプロキシ)のセッションを拒否し、ANTHROPIC_BASE_URLもこのファイルの値しか受け付けません。v2.1.285以降が必要です。
Claude apps gateway側では、端末のmanaged settingsでforceLoginMethodを"gateway"、forceLoginGatewayUrlをゲートウェイのpublic_urlにします。/loginが最初からCloud gatewayの画面で開きます。
ゲートウェイ側の仕様の食い違いで起きるエラーは、公式のトラブルシューティング表に症状別に載っています。
| 症状 | 原因と対処 |
|---|---|
400でcontext_managementやExtra inputs are not permitted | 原因と対処アップストリームがClaude Codeの送るフィールドを拒否。CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1で多くが止まる |
400でthinkingやadaptive(Input tag 'adaptive' found) | 原因と対処アップストリームのモデルがadaptive reasoningを受けない。ゲートウェイ側の更新が基本で、Opus 4.6・Sonnet 4.6ならCLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1でも回避できる |
ゲートウェイ独自の文言でコンテキスト超過の400 | 原因と対処ゲートウェイが小さい上限を課してエラーを書き換えるため、自動コンパクトが動かない。/compactで復旧する |
/fastがFast mode unavailable due to network connectivity issues | 原因と対処可用性チェックはANTHROPIC_BASE_URLに従わずapi.anthropic.comへ直接出る。直接の出口を許可する |
| モデルピッカーにゲートウェイのモデルが出ない | 原因と対処内蔵リストに無い名前なので、ゲートウェイのモデル検出を有効にするか環境変数で名前を足す |
サブスクリプションとの関係で誤解しやすい点
ゲートウェイ用の認証情報を使って接続すると、その開発者のclaude.aiサブスクリプションは使われず、利用は組織のプロバイダーアカウントに従量課金で計上されます。ANTHROPIC_AUTH_TOKENを設定するか、Claude apps gatewayに/loginでサインインした時点で、そのセッションのサブスクリプションログインは無効になります。
見落としやすいのは、ANTHROPIC_BASE_URLだけを設定して認証情報を設定しないケースです。トラフィックはゲートウェイ経由になりますが、保存済みのclaude.aiログインが有効な認証情報として残り、サブスクリプションの利用上限と課金がそのまま適用されます。「向け先を変えたから課金も切り替わった」と思うと、想定と違う請求区分になります。
認証情報の変数と保存済みログインが両方あると、起動時にauth may not work as expectedで終わる警告が出ます(古い版ではAuth conflict: Both a token (SOURCE) and an API key (SOURCE) are set)。変数を外せば保存済みのログイン、/logoutすればゲートウェイの認証情報が残ります。
ゲートウェイの外で決まること
ゲートウェイが担うのはモデルAPIリクエストのルーティングです。次の点は別の場所で設定します。
- どのモデルが応答するか:
/modelコマンドやモデル関連の環境変数で開発者が選びます。Claude apps gatewayはグループ単位のavailableModels許可リストで選択肢を絞れますが、その範囲内で選ぶのは開発者です - ゲートウェイを通らないネットワークトラフィック: バージョンチェックやダウンロードは、ゲートウェイとは別にAnthropicへ直接送られます。必要なドメインへの疎通が要り、任意のストリームは
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICで止めます - 社内のHTTPプロキシ:
HTTPS_PROXYはゲートウェイを含むすべての通信先の手前に立つため、別に設定します。自社ホストのClaude apps gatewayでは、サインイン時のチェックがプロキシのホストにもプライベートアドレスを求めます。そうでなければゲートウェイのホストをNO_PROXYに加え、CLIが直接つなぐようにします - クライアント側のテレメトリ: Claude apps gatewayにサインインすると、Anthropic宛てのクライアント分析は無効になります。サインイン前の起動時の分析も止めるなら、各端末のクライアント側managed settingsで
DISABLE_TELEMETRYを配ります。他のゲートウェイでの既定はプロバイダーで変わります
これらはいずれも、端末に配るmanaged settingsファイルで組織側から統制するのが基本です。ゲートウェイのURLや許可モデルを開発者に手で設定させると、「1か所で管理する」という前提が崩れます。
使い分け早見表
| 状況 | 向く選択肢 |
|---|---|
| 追加のインフラ製品を増やしたくない、Claude Codeのリリースに自動で追従したい | 向く選択肢Claude apps gateway(IdPがOIDC対応であることが前提) |
| IdPがSAMLやLDAPだけで、OIDCブリッジも置けない | 向く選択肢既存のLLMゲートウェイを継続 |
| すでに社内LLMゲートウェイに投資済みで、Claudeの利用もそこで一元管理したい | 向く選択肢既存のLLMゲートウェイを継続 |
| WebSearchや1時間キャッシュTTLをClaude Codeで使い続けたい | 向く選択肢既存ゲートウェイでAnthropic形式のエンドポイントを公開し、転送できる範囲を確かめる |
| BedrockやGoogle Cloud、Microsoft Foundryへ送りたい | 向く選択肢どちらも対応(Claude apps gatewayは複数アップストリームのフェイルオーバー付き) |
| CI/CDや評価ハーネスのような無人パイプラインが多い | 向く選択肢Claude apps gatewayでは無人パイプラインはプロバイダー直結。既存ゲートウェイならworkflowのenvで接続できる。サインイン済み端末のclaude -pやAgent SDKはゲートウェイセッションを使える |
| Claude以外のモデルも同じ基盤でルーティングしたい | 向く選択肢社内の既存LLMゲートウェイ(サポート範囲は冒頭のとおり) |
まとめ
最初の分かれ目はIdPがOIDCかどうかで、次がWebSearchや1時間キャッシュを使い続ける必要があるかです。後者が要るなら、既存ゲートウェイで転送できる範囲を先に確かめる選択肢があります。