Claude CodeのforceRemoteSettingsRefreshで起動をブロックする
forceRemoteSettingsRefreshはサーバー管理設定を新規取得できない限り起動をブロックし、失敗時はプロセスごと終了させる管理者設定キーです。
forceRemoteSettingsRefreshでできること
forceRemoteSettingsRefreshは、Claude Codeの管理者設定キーの1つです。組織が配布したサーバー管理設定(server-managed settings)を新規に取得できない限り起動をブロックします。取得に失敗した場合はキャッシュや無設定のまま動かすのではなくプロセスごと終了させます。
既定では、フェッチが失敗しても直前に取得できたキャッシュ設定で起動を続けます。管理ポリシーが一瞬でも欠けた状態でセッションが動くことを許容できない環境では、このキーを有効にして起動そのものを止めます。
サーバー管理設定はAnthropicのサーバーから取得され、有効化の前提は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に限られ、変更は組織内の全ユーザーに一律で及びます。機能自体もTeamsプランまたはEnterpriseプランが前提です。
{
"forceRemoteSettingsRefresh": true
}配布後にフェッチ結果を確かめる
全社展開の前に1台で試す
- 1
テスト機で設定を受け取る
管理設定を配布したら、テスト用の端末でClaude Codeを再起動します。承認ダイアログが必要な設定を含むなら、次の起動時か、起動中の対話セッションで1時間以内にダイアログが出ます。
- 2
claude doctorで結果の行を読む
Managed settings (remote)の行がフェッチの結果です。この行はv2.1.248以降で表示されます。 - 3
原因を追うならデバッグログを取る
claude --debug-file <path>で起動し、ログからRemote settingsを検索します。--debug-fileは起動オプションの1つです。 - 4
問題がなければ組織へ広げる
forceRemoteSettingsRefreshを含む変更は、フェッチに失敗した端末が起動できなくなる側の設定です。1台で結果の行まで見届けてから、組織全体へ配布します。
claude doctor行は「配信された設定が読み込まれた」「組織にサーバー管理設定が無い」「フェッチが失敗し、原因とキャッシュ適用の有無」「フェッチをスキップした(理由付き)」のいずれかを示します。実行中のセッションでは、フェッチ失敗後や一部のスキップ原因(シェルに第三者プロバイダー変数やANTHROPIC_BASE_URLをエクスポートしている場合など)で/statusにも同じ行が出ます。
サインインしていない端末で実行すると、行は次のようになります(v2.1.289の出力例)。
Managed settings (remote): not fetched — no usable credentials for the settings fetch
Organization policy: not fetched: no API key or claude.ai sign-in for the policy lookup (apiKeyHelper keys are not used for it)認証情報が無い端末はフェッチ自体をしないので、フェッチするセッション向けのこのキーは働きません。テスト機はサインイン済みの状態で確かめる必要があります。
既定動作とfail-closedの分岐点
forceRemoteSettingsRefreshが変えるのは、フェッチの成否によって起動が枝分かれする挙動です。状況ごとの違いは次のとおりです。
| 状況 | 既定(false) | forceRemoteSettingsRefresh: true |
|---|---|---|
| 初回起動でフェッチ成功 | 既定(false)開発者サインインを伴う起動では最大5秒待ち、それ以外はフェッチ継続中のままセッションを開く | forceRemoteSettingsRefresh: trueフェッチ完了を待ってから適用し、起動する |
| 初回起動でフェッチ失敗 | 既定(false)サーバー管理設定なしで起動を継続(エンドポイント管理設定は別途適用) | forceRemoteSettingsRefresh: true起動せず終了する(claude authサブコマンドは例外) |
| キャッシュありの再起動でフェッチ成功 | 既定(false)キャッシュを即適用し、確認後に一部の値を反映 | forceRemoteSettingsRefresh: trueフェッチの完了を待ってから起動する |
| キャッシュありの再起動でフェッチ失敗 | 既定(false)キャッシュされた設定のまま起動を継続する | forceRemoteSettingsRefresh: true起動せず終了する |
| Claude apps gateway経由のサインイン | 既定(false)このキーの有無に関わらず常にフェッチを待つ | forceRemoteSettingsRefresh: true同左(常にフェッチを待つ) |
ペイロードの全項目がスキーマ検証に失敗し、厳格な値へのフォールバックも起きない場合、通常のCLIは受理済みのキャッシュを維持して続行します。このキーを有効にした環境では、続行せず起動時に終了します。逆に一部のフィールドだけ救済できたときは、救済後のペイロードが承認ダイアログの対象になり、そのうえで適用されます。
フェッチしたペイロードがシェルコマンドの実行やフックの登録のように承認ダイアログを必要とする内容だった場合、待機はダイアログの表示で終わり、ペイロードは開発者が承認した時点で適用されます。ダイアログを表示できない非対話的な実行(claude -p、Agent SDK経由、VS Code拡張のチャットパネル、デスクトップアプリのCodeタブなど)では、承認が必要な設定はその回だけ適用され、記録は残りません。次に対話セッションを開くと、改めてダイアログが表示されます。
承認の保存単位は認証情報の種類で変わります。claude.aiのログインでは組織ごとに1件の承認が記録され、直近に承認したアカウントの判定が優先されます。別のアカウントで同じ組織にサインインし直すと設定内容が変わっていなくても承認ダイアログが再び表示されます。Claude apps gateway経由のサインインではゲートウェイごとに1件が記録され、承認対象の設定が変わらない限り再表示されません。
APIキーなど他の認証情報では、承認情報はキャッシュされた設定と同じ設定ディレクトリに保存され、承認が必要な設定が変わらない限り、/logoutやclaude auth logoutでキャッシュを削除するまで再表示されません。forceRemoteSettingsRefreshを有効にした環境で承認が必要な設定を配布する場合、この保存単位を理解していないと、想定していないタイミングで承認待ちが挟まり起動が止まったように見える原因になります。
起動が止まったときの切り分け
有効化した環境で「Claude Codeが起動しない」という報告が来たときは、止まり方で原因が分かれます。
| 症状 | 考えられる原因 | 次の一手 |
|---|---|---|
| 起動直後に終了する | 考えられる原因api.anthropic.comに到達できずフェッチが失敗した | 次の一手端末からの疎通とプロキシ設定を調べる |
| 承認ダイアログで止まる | 考えられる原因配信設定にシェルコマンドやフックが含まれる | 次の一手対話端末で承認する |
| 期限切れの認証でフェッチが失敗する | 考えられる原因認証情報が古い | 次の一手claude auth loginで再認証する(このサブコマンドは終了対象外) |
| パイプ経由のインストールが失敗する | 考えられる原因Raw mode is not supportedエラー | 次の一手対話的な端末で実行する |
Claude apps gatewayでサインインしている場合は、このキーが無くても起動時にフェッチを待ちます。キーが無く、対話起動でゲートウェイが401を返したときは、Cloud gateway session expired — run /login to reconnect.を表示し、ゲートウェイからサインアウトした状態でセッションを開きます。401以外の失敗のときと、対話起動以外の起動(claude authサブコマンドを除く)では、キーが無くてもエラーで終了します。
この設定が効かない・注意が必要なケース
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が有効でフェッチを待つ状況では、コマンド実行中にダイアログを表示します。CIやスクリプトからの導入では、この点が失敗の原因になります。
自己永続化とpolicyHelperとの関係
forceRemoteSettingsRefreshにはもう1つ特有の性質があります。サーバーから一度配信されると、この設定値自体もローカルにキャッシュされます。つまり次回起動時、新しいセッションがまだ一度もフェッチに成功していない段階でも、キャッシュされたtrueがすでに効いていて、フェッチ失敗時の終了動作を先に適用します。設定が「自分自身を延命させる」形になっている点は、他の管理キーと違う挙動として覚えておく価値があります。
優先順位の扱いにも例外があります。通常、管理層は複数のソース(サーバー管理設定・MDMポリシー・managed-settings.json)のうち、ポリシーキーを持つ最優先ソース1つだけを採用しマージしません。forceRemoteSettingsRefreshはv2.1.191以降この原則の例外で、管理者が制御するどのソースがtrueを設定していても、それが最優先ソースでなくても効きます。
サーバー管理設定が存在していても、MDM側で配布したtrueが無視されることはありません。サーバー管理設定を配布する前の初回起動から、fail-closedを強制したい場合に効く設計です。
policyHelperを使って管理設定を動的に計算している組織では、起動時のforceRemoteSettingsRefreshチェックはヘルパーの実行より先に走り、管理者が制御するソースを直接読みます。ヘルパーが終了コード0でmanagedSettingsを含まない結果を返した場合、そのヘルパーは管理設定に何も寄与しません。有効な管理ソースは/statusで確かめられます。組織全体のポリシー配信はClaude Code組織管理ガイドが、配信経路とモデル許可リスト・バージョン強制まで扱っています。個々のセキュリティレイヤーはClaude Codeセキュリティ・権限ガイドが参考になります。自社のランナーでClaude Codeを動かす構成は、Claude Code self-hosted-runnerの解説に分かれています。
この設定は何を防ぎ、何を防がないか
forceRemoteSettingsRefreshはクライアント側の制御であり、それ自体がセキュリティ境界になるわけではありません。管理対象外の端末では、ユーザーは管理者権限やsudo権限がなくてもこれを回避できます。
具体的な改変の種類ごとに、起きることは次のように変わります。
- ローカルの設定ファイルを書き換える: 書き換えた内容は次回起動時に一度適用されてしまい、そのあとの正規のフェッチで正しい値に戻ります。ただし
modelのように次回起動まで反映が遅れるキーは、改変された値のまま次のセッション開始まで有効になります。 - キャッシュファイルごと削除する: 初回起動と同じ扱いになるため、
forceRemoteSettingsRefreshが有効ならフェッチ失敗時に起動が止まります。 - 改変したClaude Codeバイナリを実行する: この設定は無力です。
- サーバー管理設定に対応する前の古いバージョンのCLIを使い続ける: この設定は無力です。
実務上は、forceRemoteSettingsRefreshを「運用ミスで管理ポリシーが欠けたまま動くセッションを止める仕組み」として位置づけ、実際の権限境界はサンドボックスの許可ドメインや権限ルール側で作る、という役割分担が実態に近い形です。
このキーが入った経緯
挙動の穴を埋める修正が続いたキーで、changelogに載っている版は次のとおりです。
forceRemoteSettingsRefreshの変遷
- v2.1.92(2026年4月4日)ポリシー設定として追加
リモート管理設定を新しく取得できるまで起動をブロックし、取得に失敗したら終了する、というfail-closedの形で入りました。
- v2.1.139(2026年5月11日)再認証の行き止まりを修正
期限切れの認証情報とこのキーが重なって
claude auth loginなどが止まる問題が直りました。claude authが起動時のブロックから外れている現在の仕様に通じます。 - v2.1.191(2026年6月24日)MDM・ファイル由来の値が効くように
MDMやファイルのポリシーで設定した場合にも有効になり、フェッチ時に
Cache-Control: no-cacheヘッダーを送って、中継するプロキシが古い応答を返さないようにしました。 - v2.1.259(2026年9月2日)policyHelper実行後の無視を修正
MDMや管理設定ファイルで構成したポリシーヘルパーが先に実行された場合に、起動時のこのキーが無視される問題が直りました。
まとめ
このキーは、管理ポリシーが欠けたまま動くセッションを許さない代わりに、ネットワーク障害のたびに端末が起動不能になる側の設定です。有効にするなら、api.anthropic.comへの疎通と承認ダイアログの扱いを、1台のテスト機でclaude doctorの行まで見届けてから広げる運用が現実的です。管理ポリシーの欠落を許さない強さを取るか、障害時にも起動できる可用性を取るかが、有効化の分かれ目になります。