forceLoginGatewayUrlとは — ログイン画面にゲートウェイURLを固定する設定

forceLoginGatewayUrlでできること

forceLoginGatewayUrlは、/loginのCloud gateway画面が接続しにいくURLを、managed settingsであらかじめ設定しておくキーです。この画面にはURL入力欄がありません。設定済みなら画面がゲートウェイのURLを表示し、開発者がEnterキーを押すだけで接続します。未設定のままだと、画面は「IT管理者に問い合わせてください」というメッセージを表示するだけで、そこから先に進めません。

組織が自前でClaude apps gateway(/loginの画面上ではCloud gatewayと表示されます)を運用しているときに使います。社内の全開発者をそこ経由でログインさせたい場合の設定です。値はスキームを含む完全なURL(https://claude-gateway.example.comのような形)を文字列で指定します。既定値は未設定で、これは「ゲートウェイのURLをまだ配っていない」状態にあたります。

設定の書き方

managed-settings.jsonに1キーを追加するだけです。

{
  "forceLoginGatewayUrl": "https://claude-gateway.example.com"
}

値が有効なURLでない場合、サインイン画面がそのことを表示します。managed-settings.jsonの他のキーは引き続き適用されます。

ゲートウェイの構築手順に載っている実際の配布例は、forceLoginMethod: "gateway"とforceLoginGatewayUrlの2キーにparentSettingsBehavior: "merge"を足した3キー構成です。"merge"は、Claude Desktopが起動するClaude Codeセッションへ、ゲートウェイの通信許可リストを渡すための設定です。

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
  "parentSettingsBehavior": "merge"
}

開発者がEnterを押すと、初回接続ではTLSフィンガープリントの確認画面が出ます。この2キーはゲートウェイ側のmanaged.policies[].cliには書けません。そのブロックが届くのは、すでに接続済みのクライアントだけだからです。ログイン前のマシンに届く場所、つまり端末へ配るファイルかMDMに置きます。

配布方法によって反映のタイミングも変わります。managed-settings.jsonはファイルが変更されるたびに読み直されます。一方macOSの構成プロファイルやWindowsのHKLMレジストリは、MDM経由で配ったあと30分ごとにチェックされる仕組みです。ロールアウト直後に確認するなら、ファイルベースの配布のほうが反映を待たずに済みます。

forceLoginMethodとの関係

forceLoginGatewayUrlは単独でも、forceLoginMethod: "gateway"とセットでも使えます。ただし組み合わせによって/loginの見え方が変わります。

どちらか一方だけでも、そのマシンにはログイン方式の選択画面が出なくなります。エラーを経ずに接続まで完結するのは両方を設定したときで、公式ドキュメントも、エラー画面を出さないために両方を設定する構成を挙げています。接続先のプロバイダー自体を絞る設定はallowedProvidersの解説にあります。

適用範囲と要件

forceLoginGatewayUrlのScopeはManagedで、次のいずれかからしか読み込まれません。

• managed-settings.json(およびmanaged-settings.d/配下のファイル)
• macOSの構成プロファイル(com.anthropic.claudecode管理設定ドメイン)
• WindowsのHKLM\SOFTWARE\Policies\ClaudeCodeレジストリ
• policyHelperが計算するポリシー

ユーザー設定・プロジェクト設定・ローカル設定・--settingsフラグからは読み込まれません。加えてforceLoginGatewayUrlは、WindowsのHKCUレジストリとサーバー管理設定(server-managed settings)でも無視されます。forceLoginMethod: "gateway"も同じ制約を受け、管理者が意図せず一般ユーザーの設定ファイルに書いても効果はありません。パブリックIPv4で内部ネットワークを採番している組織向けのgatewayInternalNetworksも、同じ読み込み元の制約を受ける「gateway login keys」の一つです。

開発者が自分のユーザー設定・プロジェクト設定・--settingsでforceLoginGatewayUrlを上書きすることはできません。ただし例外が2つあります。1つは、そのマシンでローカル管理者権限を持つ開発者が、managed-settings.jsonやmacOSの構成プロファイル自体を直接書き換えられる場合です。MDMツールが定期的にプロファイルを再配布できるのも、この管理者権限の存在が前提にあります。もう1つは、managed settingsがClaude Codeのプロセスにしか効かない点で、開発者が別のツールから直接Anthropic APIを呼び出す場合はこの制約の外です。

適用される利用形態は端末・VS Code拡張・JetBrains拡張・デスクトップアプリのCodeタブ・Agent SDKセッションです。

Coworkセッションだけは事情が異なります。Coworkセッション内のClaude Codeは、claude.aiのadmin consoleからサーバー管理設定を取得しません。代わりに、ユーザーのマシン上で動くCoworkセッションはデバイスのMDMポリシーとmanaged settingsファイルを読みます。ただし2つ例外があります。requireCoworkFullVmSandboxが有効なフルVMサンドボックス内のセッションと、Anthropic管理VM上で動くリモートCoworkセッションです。どちらも、そもそも読み取れるデバイスポリシーがありません。組織全体にゲートウェイ専用ログインを徹底したい場合、この2つのCowork実行形態は対象外になる点に注意が必要です。

サーバー管理設定との優先順位

managed sourceが複数あるマシンでは、通常managedSourcesBehaviorの既定値"first-wins"が使われます。優先順は1. サーバー管理設定、2. MDM/OSポリシー、3. managed-settings.json、4. HKCUレジストリの順です。この中で最も優先度の高いソースが1つでもポリシーキーを持てば、そのソースだけが使われ、他は無視されます。

forceLoginGatewayUrlとforceLoginMethodの"gateway"値は、この既定ルールに従いません。Claude Codeはこの2つをサーバー管理設定からは一切読み込みません。そのため、そのマシンでサーバー管理設定が選択ソースになっている場合でも扱いは変わりません。forceLoginGatewayUrlは、マシン上で最も優先度の高い管理ソース(MDMポリシーかmanaged-settings.json)から供給されます。それより優先度の低い管理ソースやHKCUレジストリに書いても無視されます。claude.aiのadmin consoleでサーバー管理設定を配っている組織が、ゲートウェイ専用ログインだけはMDMやファイルで別途配る必要があるのはこのためです。

設定が効いているか確認する

ロールアウト後に反映を確認する、あるいは開発者から「ゲートウェイ画面にURLが出ない」と報告を受けたときは、対象マシンで次の2つを確認します。

1. /statusを実行し、Setting sourcesとSkipped sourcesの行を読みます。Enterprise managed settingsに続けて、選択されたソースがかっこ書きで表示されます。(file)はmanaged-settings.json、(plist)はmacOS、(HKLM)はWindows、(remote)はサーバー管理設定を指します。通常のポリシーキーなら、配ったソースがここに出ていなければ別の管理ソースに上書きされています。Skipped sourcesの行は、より優先度の高いソースがあり、配ったファイルやポリシーが無視されていることを示します。ただしゲートウェイ用の2キーは例外です。(remote)が選ばれ、ファイルがSkipped sourcesに出ていても、MDMかファイルのうち最上位のものから読まれます。判断材料になるのは、MDMとファイルのどちらが上位かです
2. ファイルがJSONとして読めない場合、Claude Codeは起動を拒否し、問題のソースを示すエラーを出します。値が検証に通らず落とされた場合は、claude doctorがエントリをソースとフィールドの組み合わせで列挙します。ポリシーキーを届ける管理ソースが無ければ(置き場所の誤りや、制御キーだけのファイルを含みます)、Setting sourcesの行自体が出ません

ログインで止まったとき、画面のメッセージから原因を切り分ける

ゲートウェイ専用になったマシンで開発者が目にするのは、主に2種類のメッセージです。どちらが出ているかで、直す場所が変わります。

起動時メッセージは、設定されている認証情報の名前と設定場所、外す手順まで示します。たとえばANTHROPIC_API_KEYが原因なら、末尾に「unset ANTHROPIC_API_KEYしてからclaudeを起動し、/loginでサインインする」という案内が出ます。

v2.1.284より前の表示は、候補をまとめて列挙するだけでした。「the Anthropic-issued credential configured here ... is not used」で始まる古い表示が出る場合は、v2.1.284以降へ更新すると、どれを外すかが分かります。

そのマシンが本来ゲートウェイを必要としないなら、管理者にforceLoginMethodとforceLoginGatewayUrlを管理設定から外してもらうのが、公式エラーページの案内です。

バージョンごとの挙動の変化

forceLoginMethodとforceLoginGatewayUrlの周辺は、2026年7月から9月にかけて挙動が何度か変わっています。展開前に端末のバージョンを確かめる際の目安になります。

CLAUDE_CODE_USE_GATEWAYはforceLoginMethodとforceLoginGatewayUrlの代わりにはなりません。ゲートウェイへの強制ログインを組むなら、managed settingsの2キーが正規の経路です。

よくあるつまずき

• 部署ごとに違うURLを配れない: managed-settings.jsonやMDMプロファイルは、それが届く全員に同じポリシーを適用します。claude.aiのadmin consoleもグループ単位の配布にはまだ対応していません。部署ごとに接続先ゲートウェイを変えたい場合は、セルフホストのClaude apps gatewayがIdPグループ単位でmanaged settingsを配る機能を使う必要があります
• ゲートウェイの中身までは面倒を見ない: このキーはログイン画面が向かうURLを指定するだけで、ゲートウェイ自体の構築・認証・料金設定は別の作業です。Claude Desktopはゲートウェイの接続先を自身の管理設定から読み、サインインも独自の流れで行うため、この2キーでは設定しません。構築手順はClaude apps gatewayの使い方、組織のmanaged settings全般の設計はClaude Code組織管理ガイドにまとめています

まとめ

ゲートウェイ専用のログインを配るなら、forceLoginMethod: "gateway"とforceLoginGatewayUrlの2キーを、サーバー管理設定ではなくMDMかファイルで配ります。展開後に開発者が止まったら、まず/statusのSetting sourcesで届いたソースを見て、出たメッセージがリクエスト失敗か起動時終了かで原因を切り分けます。ログイン方式全体の比較はClaude Codeログイン方法3種の使い分けで扱っています。