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

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

managed settingsのforceLoginGatewayUrlは、/loginのCloud gateway画面に接続先URLを事前設定するキー。forceLoginMethodとの関係と適用範囲をまとめます。

読了目安 約7分

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の他のキーには影響しません。1つのキーの入力ミスがポリシー全体を無効にすることはない設計です。

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

forceLoginMethodとの関係

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

設定/loginの挙動
両方設定/loginの挙動Cloud gateway画面にURLが表示され、Enterで接続する
forceLoginMethod: "gateway"のみ/loginの挙動Cloud gateway画面は出るが、URLが無く「IT管理者に問い合わせて」で止まる
forceLoginGatewayUrlのみ/loginの挙動ゲートウェイ専用モードになり、URLを表示してEnterで接続する
どちらも未設定/loginの挙動通常どおりclaude.ai・Claude Console・ゲートウェイのログイン方式選択画面が出る

どちらか一方を設定するだけで、そのマシンはログイン方式の選択画面自体が出ないゲートウェイ専用機になります。両方を設定して初めて、エラーを経ずに接続まで完結する画面になるという関係です。公式ドキュメントも、エラー画面を出さないために両方を設定する構成を挙げています。

なお、CLAUDE_CODE_USE_GATEWAYという環境変数でもゲートウェイへのサインインを促す挙動が一時的にありました。これは未ドキュメントの変数で、forceLoginMethodとforceLoginGatewayUrlの代わりにはなりません。Claude Code v2.1.266では、この変数を単体で設定した構成がAPIキーやapiKeyHelperと衝突し、全リクエストが弾かれる回帰が起きました。ゲートウェイへの強制ログインを組むなら、managed settingsの2キーが正規の経路です。

適用範囲と要件

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"も同じ制約を受け、管理者が意図せず一般ユーザーの設定ファイルに書いても効果はありません。

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

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

Coworkセッションだけは事情が異なります。Claude Desktopは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)はサーバー管理設定を指します。forceLoginGatewayUrlを配ったソースがここに出ていなければ、別の管理ソースに上書きされています。Skipped sourcesの行があれば、それより優先度の高い管理ソースが存在し、配ったファイルやポリシーが無視されていることを意味します
  2. 値そのものが読めない場合(JSONの構文が壊れているなど)は、claude doctorが問題のエントリをソースとフィールドの組み合わせで列挙します。管理設定ファイルが存在しないだけならSetting sourcesの行自体が出ません

v2.1.212・v2.1.261での挙動変化

forceLoginMethodの強制は、当初は端末の対話式ログイン画面にしか及んでいませんでした。v2.1.212以降、VS Code拡張・Agent SDK・claude setup-token・/install-github-appにも同じ制限が適用されるようになっています。ただし/loginや初回起動時のオンボーディングで出る端末の対話式ログイン画面だけは例外で、ログイン方式を事前選択はしても強制はしません。

もう1つの変化はv2.1.261です。それ以前は、managed sourceがforceLoginMethod: "gateway"を設定したマシンでも挙動が違いました。残っていた過去のログイン・APIキー・apiKeyHelperの資格情報があれば、Claude Codeはそれをそのまま使ってしまっていたのです。v2.1.261以降は、ゲートウェイ専用マシンでこうした残存資格情報を使わなくなり、ポリシーどおりゲートウェイ経由のサインインに揃うようになっています。CLAUDE_CODE_USE_BEDROCKのようなクラウドプロバイダー指定の環境変数を使っている場合は、この対象外でゲートウェイサインインを求められません。

よくあるつまずき

  • URL欄が無いので焦る: 画面に入力欄が無いのは仕様です。forceLoginGatewayUrlが設定されていなければ、そこから先に進む方法は「IT管理者に問い合わせる」以外にありません
  • HKCUに書いて反映されない: Windowsで検証用にHKCUへ書いても、forceLoginGatewayUrlは無視されます。HKLMかファイルベースの管理設定を使う必要があります
  • 部署ごとに違うURLを配れない: managed-settings.jsonやMDMプロファイルは、それが届く全員に同じポリシーを適用します。claude.aiのadmin consoleもグループ単位の配布にはまだ対応していません。部署ごとに接続先ゲートウェイを変えたい場合は、セルフホストのClaude apps gatewayがIdPグループ単位でmanaged settingsを配る機能を使う必要があります
  • ゲートウェイの中身までは面倒を見ない: このキーはログイン画面が向かうURLを指定するだけで、ゲートウェイ自体の構築・認証・料金設定は別の作業です。構築手順はClaude apps gatewayの使い方、組織のmanaged settings全般の設計はClaude Code組織管理ガイドにまとめています

まとめ

forceLoginGatewayUrlは、/loginのCloud gateway画面が向かう接続先を管理者側で固定するmanaged settings専用キーです。forceLoginMethod: "gateway"と組み合わせて初めて、開発者はURL入力もIT問い合わせも不要でゲートウェイにサインインできます。設定できるのはmanaged-settings.json・macOSの構成プロファイル・WindowsのHKLMレジストリ・policyHelperのいずれかからのみです。HKCUやサーバー管理設定、ユーザー・プロジェクト設定ファイルには効きません。Coworkのフルサンドボックスやリモート実行のように、そもそもデバイスポリシーが届かないサーフェスがある点も、全社導入前に確認しておく価値があります。ログイン方式全体の比較はClaude Codeログイン方法3種の使い分けで扱っています。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →