Claude CodeのforceRemoteSettingsRefreshで起動をブロックする

forceRemoteSettingsRefreshでできること

forceRemoteSettingsRefreshは、Claude Codeの管理者設定キーの1つです。組織が配布したサーバー管理設定(server-managed settings)を新規に取得できない限り起動をブロックし、取得に失敗した場合はキャッシュや無設定のまま動かすのではなくプロセスごと終了させます。

既定では、フェッチが失敗しても直前に取得できたキャッシュ設定で起動を続けます。管理ポリシーが一瞬でも欠けた状態でセッションが動くことを許容できない環境では、このキーを有効にして起動そのものを止めます。

対象はapi.anthropic.comへの直接接続を前提にしたサーバー管理設定です。Claude Codeのsettings.jsonが個人・プロジェクト・コマンドライン引数の階層を持つのに対し、サーバー管理設定と(MDMプロファイルやmanaged-settings.jsonによる)エンドポイント管理設定はどちらの階層よりも優先される最上位の管理層に属します。forceRemoteSettingsRefreshはこの管理層の中でも起動シーケンスそのものに介入する数少ないキーです。

設定のやり方

claude.aiの管理コンソール(Admin Settings > Claude Code > Managed settings)、またはMDMプロファイル・システムのmanaged-settings.jsonファイルに次のキーを追加します。サーバー管理設定を編集できるのは組織のPrimary OwnerとOwnerロールに限られ、変更は組織内の全ユーザーに一律で及ぶため、この権限を持つ担当者は絞っておく必要があります。機能自体もTeamプランまたはEnterpriseプランが前提です。

{
  "forceRemoteSettingsRefresh": true
}

設定を配布した後、対象マシンでClaude Codeを再起動してもらい、claude doctorを実行するとManaged settings (remote)の行でフェッチ結果を確認できます。この行の確認にはv2.1.248以降が必要です。

claude doctor

出力は「配信された設定が読み込まれた」「組織にサーバー管理設定が無い」「フェッチが失敗し、原因とキャッシュ適用の有無」「フェッチをスキップした(理由付き)」のいずれかを示します。実行中のセッションでは/statusでも同じ行が確認できます。

既定動作とfail-closedの分岐点

forceRemoteSettingsRefreshが変えるのは、フェッチの成否によって起動が枝分かれする挙動です。状況ごとの違いは次のとおりです。

このキーを有効にした状態でペイロードの一部がスキーマ検証に失敗し、かつ有効な項目を1つも救済できなかった場合も、CLIは通常の「最後に受理したキャッシュ設定を維持する」動作ではなく終了します。逆に一部のフィールドだけ救済できたときは、救済後のペイロードが承認ダイアログの対象になり、そのうえで適用されます。

フェッチしたペイロードがシェルコマンドの実行やフックの登録のように承認ダイアログを必要とする内容だった場合、forceRemoteSettingsRefreshによる待機はダイアログの表示をもって終わり、CLIは開発者が承認するまで待ってから起動します。ダイアログを表示できない非対話的な実行(claude -pやAgent SDK経由のセッションなど)では、承認が必要な設定はその回だけ適用されて記録は残らず、次に対話セッションを開いたときに改めてダイアログが表示されます。

承認の保存単位は認証情報の種類で変わります。claude.aiのログインでは組織ごとに1件の承認が記録され、直近に承認したアカウントの判定が優先されるため、別のアカウントで同じ組織にサインインし直すと設定内容が変わっていなくても承認ダイアログが再び表示されます。Claude apps gateway経由のサインインではゲートウェイごとに1件が記録され、承認対象の設定が変わらない限り再表示されません。

APIキーなど他の認証情報では、承認情報はキャッシュされた設定と同じ設定ディレクトリに保存され、/logoutやclaude auth logoutでキャッシュを削除するまで再表示されません。forceRemoteSettingsRefreshを有効にした環境で承認が必要な設定を配布する場合、この保存単位を理解していないと、想定していないタイミングで承認待ちが挟まり起動が止まったように見える原因になります。

この設定が効かない・注意が必要なケース

forceRemoteSettingsRefreshは「サーバー管理設定をフェッチするセッション」だけに効きます。次のケースは対象外か、挙動が変わるので事前に把握しておく必要があります。

• claude authサブコマンド(claude auth loginなど)はこのチェックと、Claude apps gateway起動時の終了処理の両方から除外されます。期限切れの認証情報がフェッチ失敗の原因でも再認証はできます。
• サーバー管理設定のフェッチ自体が発生しない認証では、このキーは意味を持ちません。apiKeyHelperスクリプトが返すキーやWorkload Identity Federationの認証情報はフェッチをトリガーしません。シェルでCLAUDE_CODE_USE_*系のプロバイダー変数や既定値以外のANTHROPIC_BASE_URLをエクスポートしている場合も、そのセッションはフェッチをスキップします。
• Claude DesktopアプリのCoworkセッションは、Team・Enterpriseアカウントでサインインしていても、claude.aiの管理コンソールからサーバー管理設定を取得しません。
• claude install・claude update実行時は、通常このキーによる承認ダイアログを表示せず、直前に承認済みの設定のままコマンドを実行します。ただしforceRemoteSettingsRefreshが有効でフェッチを待つ状況では、コマンド実行中にダイアログを表示するため、パイプ経由でインストールを実行するとRaw mode is not supportedエラーで失敗します。CIやスクリプトからのインストールでこのキーが効いた組織向けに配布する場合は、対話的な端末での実行に切り替える必要があります。

自己永続化とpolicyHelperとの関係

forceRemoteSettingsRefreshにはもう1つ特有の性質があります。サーバーから一度配信されると、この設定値自体もローカルにキャッシュされます。つまり次回起動時、新しいセッションがまだ一度もフェッチに成功していない段階でも、キャッシュされたtrueがすでに効いていて、フェッチ失敗時の終了動作を先に適用します。設定が「自分自身を延命させる」形になっている点は、他の管理キーと違う挙動として覚えておく価値があります。

優先順位の扱いにも例外があります。通常、管理層は複数のソース(サーバー管理設定・MDMポリシー・managed-settings.json)のうち、ポリシーキーを持つ最優先ソース1つだけを採用しマージしません。forceRemoteSettingsRefreshはv2.1.191以降この原則の例外で、管理者が制御するどのソースがtrueを設定していても、それが最優先ソースでなくても効きます。

サーバー管理設定が存在していても、MDM側で配布したtrueが無視されることはありません。サーバー管理設定を配布する前の初回起動から、fail-closedを強制したい場合に効く設計です。

policyHelperを使って管理設定を動的に計算している組織では、起動時のforceRemoteSettingsRefreshチェックはヘルパーの実行より先に走り、管理者が制御するソースを直接読みます。ヘルパーが終了コード0でmanagedSettingsを含まない結果を返した場合、そのヘルパーは管理設定に何も寄与しません。組織全体のポリシー配信の設計(Claude Code組織管理ガイドが配信経路とモデル許可リスト・バージョン強制を扱います)と、個々のセキュリティレイヤーの実装推奨値(Claude Codeセキュリティ・権限ガイド)を合わせて確認すると、forceRemoteSettingsRefreshをどの段階で有効化すべきかが判断しやすくなります。自社のランナーで実行するセルフホスト環境では管理設定ファイルの反映経路自体が異なるため、Claude Code self-hosted-runnerの解説もあわせて確認してください。

この設定は何を防ぎ、何を防がないか

forceRemoteSettingsRefreshはクライアント側の制御であり、それ自体がセキュリティ境界になるわけではありません。管理対象外の端末では、ユーザーは管理者権限やsudo権限がなくてもこれを回避できます。

具体的な改変の種類ごとに、起きることは次のように変わります。

• ローカルの設定ファイルを書き換える: 書き換えた内容は次回起動時に一度適用されてしまい、そのあとの正規のフェッチで正しい値に戻ります。ただしmodelのように次回起動まで反映が遅れるキーは、改変された値のまま次のセッション開始まで有効になります。
• キャッシュファイルごと削除する: 初回起動と同じ扱いになるため、forceRemoteSettingsRefreshが有効ならフェッチ失敗時に起動が止まります。
• 改変したClaude Codeバイナリを実行する: この設定は無力です。
• サーバー管理設定に対応する前の古いバージョンのCLIを使い続ける: この設定は無力です。

実務上は、forceRemoteSettingsRefreshを「運用ミスで管理ポリシーが欠けたまま動くセッションを止める仕組み」として位置づけ、実際の権限境界はサンドボックスの許可ドメインや権限ルール側で作る、という役割分担で運用するのが実態に近い形です。

まとめ

forceRemoteSettingsRefreshは、サーバー管理設定のフェッチに失敗したときの挙動を「キャッシュや無設定での継続」から「起動の拒否」に切り替える管理者設定キーです。有効化すると、初回起動・再起動を問わずフェッチの成功を待ってから起動し、失敗すればプロセスごと終了します。claude authサブコマンドやサーバー管理設定をそもそもフェッチしない認証形態は対象外で、claude install・claude updateをパイプから実行する運用では承認ダイアログとの組み合わせで失敗することがあります。設定自体が一度配信されるとローカルにキャッシュされて自己永続化する点、MDMなど非最優先ソースからの値も無視されない例外である点も、他の管理キーと挙動が異なる部分として押さえておくと運用の見通しが立ちます。