SpyBara
Go Premium

managed-settings.md 2026-09-11 23:01 UTC to 2026-09-12 03:02 UTC

This page contains 445 additions and 0 deletions.

2026
Sat 12 03:02 Fri 18 23:58 Tue 22 23:59 Thu 24 22:57 Fri 25 23:58

部署受管設定

將受管設定部署到每個開發者的機器：每個作業系統的傳遞機制、Claude Code 如何結合受管來源，以及如何驗證強制執行。

受管設定是您的組織部署到每個開發者機器的設定。Claude Code 將它們應用於所有其他層級之上，因此沒有使用者、專案、本機或 --settings 值可以覆蓋它們，除了少數安全敏感的例外，其中來自較低層級的更嚴格值仍然適用。

本頁面適用於部署受管設定或偵錯為什麼某個設定未應用的管理員。若要決定要強制執行什麼，請從決定要強制執行什麼表開始。如需 claude.ai 主控台路徑，請參閱伺服器受管設定。如需開發者自己的值放在哪個檔案中，請參閱設定。

部署受管設定檔案

這是在每台機器上放置原則的最快方式：一個 managed-settings.json 檔案。如果您還沒有選擇如何傳遞受管設定，或您的裝置在 MDM 下或開發者執行雲端工作階段，請先閱讀選擇傳遞機制。

1

編寫 managed-settings.json

編寫一個 managed-settings.json，其中包含您決定要強制執行的金鑰，採用與 settings.json 相同的 JSON 形狀。決定要強制執行什麼表列出每個控制項後面的金鑰，設定參考中的每個項目都說明受管來源是否可以設定它。此檔案會阻止兩個檔案讀取、關閉略過模式，並使 Claude Code 忽略來自使用者、專案和本機檔案以及 --allowedTools 的權限規則：

{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./secrets/**)"
],
"disableBypassPermissionsMode": "disable"
},
"allowManagedPermissionRulesOnly": true
}

如需顯示更多受管金鑰形狀的更完整範例，包括登入方法、模型、MCP 伺服器和市場，請參閱組織的受管設定。

2

將檔案放在每台機器上

使用已經在您的機隊上放置檔案的任何工具，將檔案儲存為 managed-settings.json 在作業系統的系統目錄中：

  • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
  • Linux 和 WSL: /etc/claude-code/managed-settings.json
  • Windows: C:\Program Files\ClaudeCode\managed-settings.json
3

確認原則已應用

在一台機器上，在 Claude Code 內執行 /status。Setting sources 行顯示 Enterprise managed settings (file)。在此之後推出到機隊的其餘部分；當該行遺失時，檢查原則是否有效涵蓋要查看的內容。

選擇傳遞機制

上述步驟中的檔案是將受管設定放到機器上的四種方式之一。每個機制都帶有與 settings.json 檔案相同的原則金鑰，因此設定參考適用於所有機制。少數金鑰與特定來源相關聯，每個項目的 Scope 行說明哪些：

受管設定檔案、MDM 設定檔或 claude.ai 主控台對其到達的每個人應用一個原則。若要為一組開發者提供不同的原則，請將不同的檔案或設定檔部署到該組；claude.ai 主控台還不能針對一個群組，而自託管Claude 應用程式閘道按 IdP 群組傳遞受管設定。

當多個機制將原則傳遞到同一台機器時，Claude Code 預設使用一個並忽略其他機制。Claude Code 如何結合受管來源給出順序和適用於每個來源的選擇加入。

MDM 和檔案行一起稱為端點受管設定，因為原則儲存在開發者的裝置上，而不是伺服器受管行，其中 Claude Code 會擷取它。

使用下表根據您已經管理裝置的方式選擇機制。

機制 您如何傳遞它 Claude Code 何時讀取它 何時使用
伺服器受管設定 在 claude.ai 管理主控台中，或在自託管Claude 應用程式閘道上 在啟動時擷取並每小時輪詢一次；請參閱需要批准的變更 您想要一個地方為 claude.ai 組織變更原則，而不需要接觸每台機器
MDM 或作業系統層級原則 作為 macOS 設定設定檔或 Windows HKLM 登錄值，透過 Jamf、Intune、群組原則或類似工具；請參閱每個機制儲存原則的位置 在啟動時讀取並每 30 分鐘檢查一次變更 您已經使用 MDM 或群組原則管理裝置
基於檔案 作為每台機器上系統目錄中的 managed-settings.json；請參閱每個機制儲存原則的位置 在啟動時讀取並在檔案變更時重新載入 沒有 MDM 的機器、Linux 主機或您自己建置的映像
HKCU 登錄、Windows 和 WSL 作為 Windows HKCU 登錄值；請參閱每個機制儲存原則的位置 在啟動時讀取並每 30 分鐘檢查一次變更；Claude Code 僅在沒有其他受管來源傳遞原則金鑰且沒有主機提供的父設定提供限制性金鑰時才使用它 您無法寫入機器層級 HKLM 金鑰

Jamf、Iru、Intune 和群組原則的入門範本位於 MDM 範例儲存庫。

對於受管 MCP 伺服器，您可以透過 managed-mcp.json 與這些伺服器一起部署或透過 managedMcpServers 金鑰提供，請參閱受管 MCP 設定。

原則應用的位置和時間

部署的原則到達開發者的工作階段如下：

  • 表面：在開發者的機器上，終端機、VS Code 和 JetBrains 擴充功能、桌面應用程式的 Code 標籤和 Agent SDK 工作階段讀取所有這些來源。Agent SDK 工作階段即使在 settingSources 排除使用者、專案和本機檔案時也會載入受管設定。

  • 雲端工作階段：Anthropic 託管環境中的工作階段不會讀取裝置的 MDM 設定檔或檔案，因此其原則必須來自伺服器受管設定。自託管環境中的工作階段也會讀取其執行器映像中的受管設定檔案，預設情況下僅當伺服器受管設定不傳遞原則金鑰時，除了 Claude Code 從每個管理來源讀取的金鑰。Claude Code 如何結合受管來源涵蓋適用於兩者的選擇加入。

  • 共同工作工作階段：Claude Desktop 應用程式中的 Cowork 在 Claude Code 上執行其工作階段。在共同工作工作階段中，Claude Code 永遠不會從 claude.ai 管理主控台擷取伺服器受管設定，即使使用者使用團隊或企業帳戶登入，因此適用的原則取決於工作階段執行的位置：

    • 在使用者的機器上：預設情況下，共同工作工作階段中的 Claude Code 讀取該裝置上的 MDM 或作業系統層級原則和受管設定檔案，因此在那裡部署原則。
    • 在完整 VM 沙箱中：當您的 Claude Desktop 受管設定將 requireCoworkFullVmSandbox 設定時，Claude Code 在虛擬機器內執行，其中裝置的 MDM 原則和受管設定檔案不存在。
    • 遠端共同工作工作階段：這些在 Anthropic 受管 VM 上執行，其中 Claude Code 沒有裝置原則可讀取。

    表面涵蓋表比較共同工作與其他表面。

  • 執行中的工作階段：大多數變更在傳遞機制表中的排程上到達執行中的工作階段，無需重新啟動。

  • 需要批准的變更：除了等待下一次啟動的更新，伺服器受管變更到需要批准的設定，例如掛鉤或 env 變數，等待開發者在互動式工作階段中接受對話，並在 IDE 擴充功能或 Agent SDK 託管的工作階段中應用於目前執行。其他伺服器受管變更在下一次輪詢時應用。

  • 長期執行的工作階段：保持開啟數週的工作階段仍然可能滯後於推出。requiredMinimumVersion 阻止過時的二進位檔啟動，不會結束已在執行的工作階段。

每個機制儲存原則的位置

金鑰在任何地方都是相同的，但每個機制以不同的位置和形狀儲存它們：

  • 伺服器受管：Anthropic 的伺服器或您的閘道持有原則。Claude Code 保留一個本機快取，在啟動時應用它，並在每次成功擷取時替換。
  • macOS 設定設定檔：com.anthropic.claudecode 受管偏好設定網域。使用與 managed-settings.json 相同的頂層金鑰，嵌套設定為字典，列表為 plist 陣列。
  • Windows HKLM 登錄：JSON 作為 HKLM\SOFTWARE\Policies\ClaudeCode 下名為 Settings 的 REG_SZ 或 REG_EXPAND_SZ 值。
  • 基於檔案：managed-settings.json、可選的 managed-settings.d/ 目錄和 managed-mcp.json 在系統目錄中：macOS 上的 /Library/Application Support/ClaudeCode/、Linux 和 WSL 上的 /etc/claude-code/，以及 Windows 上的 C:\Program Files\ClaudeCode\。Claude Code 不讀取舊版 Windows 路徑 C:\ProgramData\ClaudeCode\managed-settings.json。
  • Windows HKCU 登錄：HKCU\SOFTWARE\Policies\ClaudeCode 下相同的 Settings 值。

跨團隊分割基於檔案的原則

如果多個團隊擁有一個原則的部分，請將每個部分放在 managed-settings.d/ 中的自己的檔案中，位於與 managed-settings.json 相同的系統目錄旁邊，而不是編輯一個共享檔案。

Claude Code 首先合併 managed-settings.json，然後按字母順序合併目錄中的每個 *.json 檔案。使用數字前綴命名檔案以控制順序，例如 10-telemetry.json 和 20-security.json。Claude Code 忽略隱藏檔案和不以 .json 結尾的檔案。

當兩個檔案設定相同的金鑰時，Claude Code 按這些規則合併它們：

  • 單一值，例如 "model": "opus" 或 "cleanupPeriodDays": 7：較晚檔案的值替換較早的值
  • 列表，例如 permissions.deny 或 sandbox.network.allowedDomains：兩個列表合併，移除重複項
  • 嵌套區塊，例如 env 或 sandbox：兩個區塊按金鑰合併，每個金鑰內遵循這些相同的規則
  • fallbackModel：較晚的鏈完整替換較早的鏈
  • extraKnownMarketplaces 和 managedMcpServers：具有相同名稱的較晚項目完整替換較早的項目
  • modelPicker：較晚的陣容完整替換較早的陣容

Claude Code 如何結合受管來源

當您的組織將多個受管來源傳遞到同一台機器時，managedSourcesBehavior 金鑰決定 Claude Code 對其他來源的處理方式：

  • "first-wins"，預設值：Claude Code 使用傳遞至少一個原則金鑰的最高排名來源，並忽略其餘來源，而不是合併它們，除了從每個管理來源讀取的金鑰中的少數金鑰。Claude Code 對它跳過的來源不顯示警告；/status 命名它使用的來源和它跳過的來源。
  • "merge"：Claude Code 應用傳遞原則金鑰的每個管理來源，並按金鑰類型合併它們：在大多數金鑰上，最高排名來源的值適用，列表聯合，鎖定採用最嚴格的值。組成每個受管來源說明在哪裡設定金鑰以及每種金鑰類型如何合併。需要 Claude Code v2.1.242 或更新版本。

兩個設定以相同的方式排名來源。本節中重複出現兩個術語：

  • 原則金鑰：除了兩個控制金鑰 wslInheritsWindowsSettings 和 managedSourcesBehavior 之外的任何設定金鑰。只包含這些的受管設定檔案或 MDM 原則不計算，Claude Code 移動到下一個來源。
  • 管理來源：下面前三個來源之一。HKCU 登錄是使用者可寫的，不是一個。

Claude Code 按此順序檢查來源，最高優先順序優先：

  1. 遠端設定，從 claude.ai 作為伺服器受管設定或由Claude 應用程式閘道傳遞。Claude Code 僅在工作階段使用符合條件的登入或金鑰直接向 Anthropic 的 API 驗證，或使用 /login 登入閘道時擷取此來源。在其他提供者上，或當 ANTHROPIC_BASE_URL 指向 Anthropic 的 API 以外的地方時，它從下一個來源開始
  2. MDM 或作業系統層級原則：macOS plist 或 HKLM 登錄金鑰
  3. 受管設定檔案，managed-settings.d/*.json 和 managed-settings.json 合併在一起
  4. HKCU 登錄，在 Windows 上，以及在 WSL 上，一旦 HKLM 登錄或 Windows 受管設定檔案開啟 wslInheritsWindowsSettings 並且 HKCU 值也設定它。Claude Code 僅在沒有上面的來源傳遞原則金鑰且沒有主機提供的父設定提供限制性金鑰時讀取它

此圖表顯示排名，以及 Claude Code 在任一設定下從前三個來源讀取的跨來源金鑰的範例：

圖表顯示四個受管設定來源，從頂部的遠端設定排名到 MDM、受管設定檔案和底部的 HKCU 登錄。預設情況下，具有原則金鑰的第一個來源提供原則，其餘的被跳過；將 managedSourcesBehavior 設定為合併時，每個具有原則金鑰的管理來源都有貢獻，按金鑰類型合併，HKCU 登錄保持不變。側面板顯示跨來源金鑰，例如沙箱鎖、forceRemoteSettingsRefresh 和每個變數 env 合併，從每個管理來源讀取，不包括 HKCU 登錄。 圖表顯示四個受管設定來源，從頂部的遠端設定排名到 MDM、受管設定檔案和底部的 HKCU 登錄。預設情況下，具有原則金鑰的第一個來源提供原則，其餘的被跳過；將 managedSourcesBehavior 設定為合併時，每個具有原則金鑰的管理來源都有貢獻，按金鑰類型合併，HKCU 登錄保持不變。側面板顯示跨來源金鑰，例如沙箱鎖、forceRemoteSettingsRefresh 和每個變數 env 合併，從每個管理來源讀取，不包括 HKCU 登錄。

從每個管理來源讀取的金鑰

在預設 "first-wins" 設定下，Claude Code 僅從它選擇的來源讀取大多數金鑰，並忽略較低排名來源中的值，即使選定的來源未設定該金鑰。

少數金鑰的工作方式不同。Claude Code 從每個管理來源讀取它們，因此當選定的來源不設定時，較低排名的 MDM 原則或受管設定檔案仍然可以設定它們。Claude Code 將使用者可寫的 HKCU 登錄排除在該掃描之外；當 HKCU 是唯一的來源且沒有主機提供父設定時，HKCU 應用就像任何選定的來源。

跨來源金鑰包括：

  • sandbox.network.allowManagedDomainsOnly 和 sandbox.filesystem.allowManagedReadPathsOnly：任何管理來源中的 true 開啟鎖定。當鎖定開啟時，Claude Code 聯合它鎖定的允許清單，sandbox.network.allowedDomains 與 WebFetch(domain:...) 允許規則，或 sandbox.filesystem.allowRead，跨每個管理來源。沒有鎖定，Claude Code 將允許清單視為任何其他金鑰，因此在 "first-wins" 下，未選定的管理來源的允許清單被忽略
  • allowAllClaudeAiMcps
  • 沙箱二進位路徑 sandbox.bwrapPath 和 sandbox.socatPath
  • 沙箱 ripgrep 二進位，sandbox.ripgrep
  • sandbox.filesystem.disabled 和 sandbox.network.strictAllowlist
  • useAutoModeDuringPlan 和 syncClaudeAiSkills，其中任何管理來源的 false 關閉行為。開發者的使用者或本機設定中的 false 也關閉它；每個金鑰只能拒絕
  • enableArtifact，其中任何管理來源的 false 關閉 Artifact 工具。開發者的使用者、專案或本機設定中的 false 也關閉它，沒有來源將其打開；請參閱哪些較低層級的值仍然計算。需要 Claude Code v2.1.242 或更新版本
  • maxEffortLevel，其中任何管理來源中的最低上限適用。如果開發者在自己的設定或 --settings 中設定較低的上限，Claude Code 應用那個；沒有來源可以提高上限。需要 Claude Code v2.1.267 或更新版本
  • attribution 中的提交預告片選擇退出，或在已棄用的 includeCoAuthoredBy 中，來自任何層級
  • forceRemoteSettingsRefresh
  • env，跨管理來源按變數合併：每個變數來自定義它的最高優先順序來源，因此較低來源填充較高來源未設定的變數。少數變數遵循自己的規則；跨受管來源的每個金鑰例外命名每個。需要 Claude Code v2.1.223 或更新版本。在 v2.1.223 之前，Claude Code 僅應用選定來源的整個 env 區塊

組成每個受管來源

若要讓 Claude Code 應用您的組織傳遞的每個管理來源，請在您部署的最高排名來源中將 managedSourcesBehavior 設定為 "merge"。Claude Code 僅從攜帶金鑰或原則金鑰的最高排名來源讀取金鑰，因此較低來源無法選擇自己合併到上面的來源，並且從不接收伺服器受管設定的機器也需要其 MDM 設定檔中的金鑰。使用者可寫的 HKCU 登錄永遠不會與另一個來源合併。需要 Claude Code v2.1.242 或更新版本。

在 "merge" 下，Claude Code 添加較低來源的列表項目，例如 permissions.allow 規則和掛鉤，到原則，因此僅在您最高排名來源下排名的每個來源都在管理員的控制下時才開啟它。

此表顯示 Claude Code 在 "merge" 下如何組合每種金鑰。managedSourcesBehavior 項目命名限制允許清單、值取整和最高來源僅行中的每個金鑰。

金鑰類型 Claude Code 如何組合它 範例
列表 組合來自每個來源的項目 permissions.allow、hooks、sandbox.network.allowedDomains、deniedMcpServers
鎖定 應用任何來源設定的最嚴格值；較寬鬆的值僅從最高排名來源應用 allowManagedHooksOnly、permissions.disableBypassPermissionsMode、crossSessionInbound
限制允許清單 從設定它的最高排名來源取整個列表，不添加來自較低來源的項目 availableModels、allowedMcpServers、strictKnownMarketplaces、allowedChannelPlugins 和 fallbackModel 鏈
值取整 從設定它的最高排名來源取整個值，不組合來自較低來源的項目或欄位 sandbox.credentials.awsPairs、sandbox.ripgrep
提供的 MCP 伺服器 組合來自每個來源的伺服器名稱；當兩個來源設定相同的名稱時，應用最高排名來源的整個項目 managedMcpServers
僅從最高排名來源讀取的金鑰 忽略每個較低來源中的金鑰，即使最高排名來源未設定它 認證協助程式，例如 apiKeyHelper、登入 pin，例如 forceLoginOrgUUID、modelPicker、permissions.defaultMode
env 在任一設定下跨管理來源按變數合併，如從每個管理來源讀取的金鑰所述
每個其他金鑰 從設定它的最高排名來源取值 model、cleanupPeriodDays

若要確認機器上組合了哪些來源，請讀取 /status 中的 Setting sources 行；該部分說明每個標籤的含義。

使用協助程式程式計算原則

policyHelper 是您的 MDM 原則或受管設定檔案命名的可執行檔，Claude Code 在啟動時執行它以計算受管設定。當選定的來源配置一個並且協助程式發出 managedSettings 物件時，該輸出改變 Claude Code 讀取的內容：

如需協助程式執行失敗的情況以及 Claude Code 在執行失敗時的處理方式，請參閱協助程式失敗。

讓嵌入主機添加原則

當另一個應用程式啟動 Claude Code 時，例如 Claude Desktop、IDE 擴充功能或 Agent SDK 應用程式，該主機可以透過 SDK managedSettings 選項傳遞自己的受管設定。Claude Code 將這些稱為父設定。

預設情況下，只要存在管理來源，Claude Code 就會忽略父設定：伺服器受管設定、MDM 或作業系統層級原則或受管設定檔案。

若要讓 Claude Code 將父設定與管理來源合併，請在最高優先順序受管來源中將 parentSettingsBehavior 設定為 "merge"；Claude Code 僅從該來源讀取金鑰。

Claude Code 然後僅保留主機限制 Claude 可以做什麼的值，有一個要知道的間隙：除非您也設定 allowManaged*Only 鎖定，主機的權限允許規則和沙箱允許清單仍然適用。請參閱限制父設定以了解鎖定。

policyHelper 可以關閉父合併，無論此金鑰如何；其項目說明何時。

Claude Code 也將這些檢查應用於父提供的值本身：

  • 當任何管理來源設定 allowManagedPermissionRulesOnly 時，Claude Code 在讀取時刪除父提供的權限允許規則和 additionalDirectories，即使較高優先順序來源未設定金鑰。金鑰對您自己的權限規則的影響來自 Claude Code 應用的受管設定，或來自您選擇合併的父設定
  • Claude Code 強制執行它應用的受管設定中的 forceLoginOrgUUID 或 allowedMcpServers 值，並阻止父提供的值。較低管理來源中的值，Claude Code 不應用既不應用也不阻止父的值。managedSourcesBehavior 項目說明在 "merge" 下哪個來源提供每個金鑰。在 v2.1.223 之前，任何管理來源中的值阻止父的值
  • availableModels 值遵循與 allowedMcpServers 相同的規則

當僅應用受管規則時保持 Cowork 資料夾存取

Claude Desktop 應用程式中的 Cowork 在 Claude Code 上執行其工作階段，並透過在啟動工作階段時提供的允許規則授予每個工作階段對其工作資料夾（例如使用者連接的資料夾）的存取權。當您的受管原則設定 allowManagedPermissionRulesOnly 時，Claude Code 僅保留受管原則中的允許規則：它刪除主機作為父設定提供的允許規則、--allowedTools 或設定檔案中的允許規則，因此對這些資料夾的寫入失去其預先批准。在要求編輯前的 Cowork 工作階段中，Cowork 無法顯示提示，Claude 將每次寫入報告為被阻止，因為路徑解析為受保護的位置或連接資料夾外的路徑。

若要恢復寫入，請為這些資料夾添加允許規則到 Claude Code 選擇的受管來源在這些機器上：在 MDM 受管機隊上，那是 MDM 原則而不是單獨的受管設定檔案。此範例使用檔案形式，MDM 原則採用相同的金鑰。它保持 allowManagedPermissionRulesOnly 設定並允許在每個使用者主目錄中的 CoworkProjects 資料夾下編輯；將路徑替換為您的使用者連接的資料夾：

{
  "allowManagedPermissionRulesOnly": true,
  "permissions": {
    "allow": [
      "Edit(~/CoworkProjects/**)"
    ]
  }
}

部署原則後，Claude 可以在新的 Cowork 工作階段中將檔案儲存在該資料夾下。讀取和編輯規則涵蓋路徑語法，包括絕對路徑的 // 形式。

開發者可以變更什麼

開發者自己的設定檔案、--settings 值和專案檔案永遠不會覆蓋受管值；例外僅讓較嚴格的較低層級值計算。四件事在該規則之外：

  • 工作階段的模型：受管 model 是預設值，不是鎖定。--model 和 ANTHROPIC_MODEL 仍然為該工作階段選擇模型，因此部署 availableModels 以限制選擇。
  • 本機管理員權限：作為機器上管理員的開發者可以編輯受管來源本身，這就是為什麼 MDM 工具可以按排程重新部署設定檔或檔案，以及為什麼 HKLM 登錄和 macOS 受管偏好設定網域存在。
  • 伺服器受管快取：伺服器受管設定來自 Anthropic 的伺服器，對本機快取的編輯僅持續到下一次成功擷取。
  • 其他工具：受管設定僅綁定 Claude Code。從另一個工具呼叫 API 的開發者不在它們下。

檢查原則是否有效

開發者報告原則未應用，或您想在推出到機隊之前確認推出已著陸。該機器上的兩個命令回答它：/status 顯示 Claude Code 選擇了哪個受管來源，claude doctor 列出它刪除的內容。

讀取 /status 中的來源

在開發者的機器上，在 Claude Code 內執行 /status 並讀取 Setting sources 行。當受管來源有效時，該行列出 Enterprise managed settings 以及 Claude Code 在括號中選擇的來源：

  • (remote)：來自 claude.ai 或閘道的伺服器受管設定
  • (plist) 或 (HKLM)：MDM 或作業系統原則
  • (file)、(drop-ins) 或 (file + drop-ins)：managed-settings.json、放置目錄或兩者
  • (remote + file, merged) 或另一個以 , merged 結尾的列表：您的組織組成每個受管來源，Claude Code 將列出的來源合併到原則中。較低來源仍然可以提供 env 變數而不出現在列表中。需要 Claude Code v2.1.242 或更新版本
  • (HKCU)：使用者可寫登錄回退
  • (parent process)：嵌入主機提供了限制性設定
  • (helper)：由選定的 MDM 或檔案來源配置的 policyHelper

當 Claude Code 在機器上找到受管來源但未選擇它時，第二行 Skipped sources 命名每個這樣的來源。讀取它以區分從不到達機器的原則與到達它並被較高優先順序來源覆蓋的原則。需要 Claude Code v2.1.242 或更新版本。

當原則未應用時，Setting sources 行告訴您您有以下兩個問題中的哪一個：

  • 該行遺失：Claude Code 找不到傳遞原則金鑰的受管來源。

    如果您部署了受管設定檔案，請檢查它位於作業系統的路徑，並且它包含原則金鑰而不是僅控制金鑰。不是有效 JSON 的檔案不會產生此狀態；Claude Code 拒絕啟動。

    當您改為透過伺服器受管設定部署時，執行 claude doctor，它報告擷取結果。

  • 該行命名您部署的來源以外的來源：存在較高優先順序的來源，Claude Code 忽略了您的，Skipped sources 列出它。Claude Code 如何結合受管來源給出順序。

尋找 Claude Code 刪除的項目

當受管設定檔案、MDM 設定檔、登錄值或伺服器受管有效負載無法通過架構驗證時，Claude Code 首先跳過它可以修復的個別項目，例如一個無效的權限規則，每個都有警告，然後刪除任何頂層金鑰，其值仍然失敗，並繼續強制執行每個剩餘的有效金鑰。

Claude Code 對 policyHelper 發出的 managedSettings 更嚴格：它進行相同的項目修復，但任何倖存的架構違規都會導致整個協助程式執行失敗，在啟動時 Claude Code 拒絕啟動，與協助程式退出非零相同。

當受管設定檔案、放置檔案、MDM plist 或 HKLM 登錄值存在但無法解析為 JSON 物件時，Claude Code 拒絕啟動並列印命名來源的錯誤，即使另一個管理來源傳遞有效原則。每個來源在以下情況下以這種方式失敗：

  • 受管設定檔案或放置檔案：檔案不是有效的 JSON，或其頂層不是物件
  • MDM plist：macOS 的 plutil 報告 plist 格式不正確，或其轉換的內容不是 JSON 物件
  • HKLM 登錄值：Settings 值不是字串、為空或不持有 JSON 物件

三個來源狀態不會導致此拒絕：

  • 缺少的檔案、設定檔或登錄值不是失敗；Claude Code 在沒有該來源的情況下執行。
  • 空的受管設定檔案計為 {}。
  • 使用者可寫 HKCU 登錄金鑰中的格式不正確的值永遠不會阻止啟動。Claude Code 將其報告為 /status 和 claude doctor 中的通知。

如果受管設定檔案、放置檔案或 managed-settings.d/ 目錄無法讀取，且沒有管理來源提供原則，使用 claude.ai 或 Claude Console 認證登入的工作階段在啟動時退出，並顯示聯絡管理員的訊息。

若要尋找刪除的項目，請查看以下三個位置之一：

  • 互動式工作階段在啟動時顯示列出無效項目的對話。
  • 使用 -p 的非互動式執行將摘要列印到 stderr。
  • claude doctor 列出每個無效項目及其來源和欄位。

失敗關閉的金鑰

少數強制執行金鑰在無效時不會被刪除。Claude Code 強制執行更嚴格的回退，直到值被修復；表格顯示它對每個金鑰強制執行的內容：

欄位 存在但無效時的行為
allowedMcpServers 強制執行為空允許清單，直到值被修復，因此使用者添加的沒有 MCP 伺服器被允許。您的組織透過 managedMcpServers 傳遞的伺服器仍然載入，managed-mcp.json 伺服器按伺服器如何被評估載入。個別無效項目被剝離，有效子集被強制執行。
allowedHttpHookUrls Claude Code 強制執行空允許清單，直到您修復值。如果僅個別項目無效，它會剝離該項目並強制執行其餘項目。
httpHookAllowedEnvVars Claude Code 強制執行空允許清單，直到您修復值。如果僅個別項目無效，它會剝離該項目並強制執行其餘項目。
allowedChannelPlugins Claude Code 強制執行空允許清單，直到您修復值，因此傳遞給 --channels 的沒有頻道外掛被允許。如果僅個別項目無效，它會剝離該項目並強制執行其餘項目。
allowManagedHooksOnly 視為 true 直到修復：掛鉤限制適用，除非 disableCommandPluginSources 明確為 false，否則命令來源的外掛被禁用。
allowManagedMcpServersOnly 視為 true。
disableCommandPluginSources 視為 true，因此命令來源的外掛保持禁用，直到值被修復。
availableModels 強制執行為空允許清單，直到修復，因此僅預設模型可用；非字串項目被剝離，有效子集被強制執行。
enforceAvailableModels 視為 true。
forceLoginOrgUUID 沒有組織被允許登入，直到值被修復。
crossSessionInbound 視為 refuse，最嚴格的值，因此入站跨工作階段訊息被拒絕，直到值被修復。開發者看到警告。
deniedMcpServers 個別無效項目被剝離，有效子集被強制執行。完全無效的值被刪除並顯示警告，因為拒絕每個伺服器會阻止原則從未命名的伺服器。
sandbox.credentials 可恢復的無效項目降級為 mode: "deny" 並顯示警告；無法恢復的項目被剝離；有效項目保持強制執行。請參閱受管設定中的無效認證項目

allowedHttpHookUrls 和 httpHookAllowedEnvVars 跨設定檔案合併，因此您的使用者、專案或本機設定中的項目在受管清單為空時仍然適用。這兩個金鑰和 allowedChannelPlugins 的回退需要 Claude Code v2.1.267 或更新版本；較早版本在其值或任何項目無效時刪除整個金鑰。

requiredMinimumVersion 和 requiredMaximumVersion 按設計失敗開放：無效值被刪除而不是強制執行。

此容差僅適用於受管設定。使用者、專案和本機設定檔案保持嚴格：JSON 或頂層形狀失敗驗證的檔案被整體拒絕並報告，無效的個別項目（例如格式不正確的權限規則）被跳過並顯示警告，而檔案的其餘部分適用。

僅受管來源可以設定的金鑰

Claude Code 僅從受管來源讀取以下金鑰；將它們放在使用者或專案設定檔案中無效。

大多數是鎖定：鎖定管理的值，例如權限規則或 sandbox.network.allowedDomains，是任何層級都可以設定的普通金鑰，鎖定告訴 Claude Code 僅尊重受管值。

表格涵蓋權限、外掛和傳遞控制項。對於此處未列出的任何金鑰，設定參考索引的 Scope 列說明它是否僅受管；其餘僅受管金鑰包括閘道登入 URL、版本、瀏覽器、行動模擬器、SSH 主機、Desktop 本機工作階段、沙箱二進位路徑、模型定價和 CLAUDE.md 控制項。

設定 描述
allowAllClaudeAiMcps 載入 Claude Code 自己擷取的 claude.ai 連接器，與部署的 managed-mcp.json 一起，而不是抑制它們
allowedChannelPlugins 可能推送訊息的頻道外掛的允許清單。設定時替換預設 Anthropic 允許清單。需要 channelsEnabled: true。請參閱限制哪些頻道外掛可以執行
allowManagedHooksOnly 當 true 時，限制哪些掛鉤執行；請參閱在 allowManagedHooksOnly 下執行什麼以了解完整效果清單
allowManagedMcpServersOnly 當 true 時，僅受管設定中的 allowedMcpServers 被尊重。deniedMcpServers 仍然從所有來源合併。請參閱受管 MCP 設定
allowManagedPermissionRulesOnly 使受管設定成為權限規則的唯一設定來源。項目列出它忽略的每個來源
blockedMarketplaces 市場來源的封鎖清單。被封鎖的來源在下載前被檢查，因此它們永遠不會接觸檔案系統。請參閱受管市場限制
channelsEnabled 允許組織的頻道。請參閱企業控制項以了解每個計畫上的預設值
disableCommandPluginSources 當 true 時，完全阻止command 外掛來源，因此市場聲明的命令永遠不會執行。也阻止市場headersHelper 命令，除了受管設定本身聲明的市場。未設定時，遵循 allowManagedHooksOnly。需要 Claude Code v2.1.229 或更新版本，headersHelper 區塊需要 v2.1.238 或更新版本
disableSideloadFlags 在啟動時拒絕 --plugin-dir、--plugin-url、--agents 和 --mcp-config 標誌。在雲端工作階段中，Claude Code 刪除伺服器透過 --mcp-config 傳遞的 MCP 伺服器，除了進程內 type: "sdk" 項目，並啟動工作階段。需要 Claude Code v2.1.193 或更新版本
forceRemoteSettingsRefresh 當 true 時，阻止 CLI 啟動，直到遠端受管設定被新鮮擷取，如果擷取失敗則退出。請參閱失敗關閉強制執行
managedMcpServers 提供給每個使用者與他們自己的遠端 MCP 伺服器。它提供伺服器而不是鎖定任何東西。請參閱透過受管設定提供伺服器。需要 Claude Code v2.1.259 或更新版本
managedSourcesBehavior Claude Code 是否僅應用最高優先順序受管來源或組成它們中的每一個
parentSettingsBehavior 主機提供的父設定是否在受管原則下合併
pluginSuggestionMarketplaces Claude Code 可能向使用者建議其外掛的市場
pluginTrustMessage 附加到安裝前顯示的外掛信任警告的自訂訊息
policyHelper 在啟動時計算受管設定的可執行檔；請參閱使用原則協助程式計算受管設定
sandbox.filesystem.allowManagedReadPathsOnly 當 true 時，僅受管設定中的 filesystem.allowRead 路徑被尊重。denyRead 仍然從所有來源合併
sandbox.network.allowManagedDomainsOnly 僅尊重受管 allowedDomains 和 WebFetch(domain:...) 允許規則；阻止其他網域而不提示
strictKnownMarketplaces 控制使用者可以添加和安裝外掛的外掛市場來源。請參閱受管市場限制
strictPluginOnlyCustomization 阻止技能、代理、掛鉤和 MCP 伺服器來自使用者和專案來源；true 鎖定所有四個，陣列命名哪些
wslInheritsWindowsSettings 當在 HKLM 登錄或 C:\Program Files\ClaudeCode 下的檔案中設定時，讓 WSL 讀取 Windows 原則鏈，並僅當該目錄下的受管設定檔案或放置不傳遞原則金鑰時讀取 /etc/claude-code；項目給出順序

為您的組織關閉遙測

Claude Code 預設在使用 Anthropic API 的工作階段上發送 Anthropic 操作遙測，無論是直接、透過 LLM 閘道還是透過自訂 ANTHROPIC_BASE_URL；按 API 提供者的預設行為說明哪些提供者發送它。若要為每個開發者關閉它而不依賴每個人的 shell，請透過受管設定的 env 區塊傳遞 DISABLE_TELEMETRY。此範例為原則到達的每個人設定 DISABLE_TELEMETRY：

{
  "env": {
    "DISABLE_TELEMETRY": "1"
  }
}

Claude Code 應用 1 的值而不向使用者顯示批准對話。

如果您關閉遙測，Claude Code 停止發送為原則到達的開發者提供您的組織分析儀表板的使用資料。變數也關閉功能標誌擷取，這使得遠端控制、預設自動模式和其他需要功能標誌擷取的功能對這些開發者不可用。

原則應用的位置和時間說明哪個傳遞機制到達每個表面，平台可用性說明哪些工作階段跳過伺服器受管設定擷取。

如果您的組織使用客戶受管加密金鑰並透過閘道路由 Claude Code，設定代理和閘道說明為什麼這些工作階段需要此變數。

另請參閱