部署受管設定

​

部署受管設定檔案

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

​

選擇傳遞機制

• 傳遞控制項：policyHelper、wslInheritsWindowsSettings 和 managedSourcesBehavior
• 閘道登入金鑰：forceLoginGatewayUrl、gatewayInternalNetworks 和 forceLoginMethod 的 "gateway" 值

​

原則應用的位置和時間

• 表面：在開發者的機器上，終端機、VS Code 和 JetBrains 擴充功能、桌面應用程式的 Code 標籤和 Agent SDK 工作階段讀取所有這些來源。Agent SDK 工作階段即使在 settingSources 排除使用者、專案和本機檔案時也會載入受管設定。
• 雲端工作階段：Anthropic 託管環境中的工作階段不會讀取裝置的 MDM 設定檔或檔案，因此其原則必須來自伺服器受管設定。自託管環境中的工作階段也會讀取其執行器映像中的受管設定檔案，預設情況下僅當伺服器受管設定不傳遞原則金鑰時，除了 Claude Code 從每個管理來源讀取的金鑰。Claude Code 如何結合受管來源涵蓋適用於兩者的選擇加入。
• Claude Tag 工作階段：Claude Tag 工作階段在雲端環境中執行，但不會接收伺服器受管設定。在自託管環境中，它們仍會讀取執行器映像中的受管設定檔案。在 Claude Tag 管理設定中設定 Claude Tag 本身。
• 共同工作工作階段：Claude Desktop 應用程式中的 Cowork 在 Claude Code 上執行其工作階段。在共同工作工作階段中，Claude Code 永遠不會從 claude.ai 管理主控台擷取伺服器受管設定，即使使用者使用團隊或企業帳戶登入，因此適用的原則取決於工作階段執行的位置：
  • 在使用者的機器上：預設情況下，共同工作工作階段中的 Claude Code 讀取該裝置上的 MDM 或作業系統層級原則和受管設定檔案，因此在那裡部署原則。
  • 在完整 VM 沙箱中：當您的 Claude Desktop 受管設定將 requireCoworkFullVmSandbox 設定時，Claude Code 在虛擬機器內執行，其中裝置的 MDM 原則和受管設定檔案不存在。
  • 遠端共同工作工作階段：這些在 Anthropic 受管 VM 上執行，其中 Claude Code 沒有裝置原則可讀取。
  無論工作階段在何處執行，claude.ai 在任何人從 claude.ai 上的 git 儲存庫或從 Cowork 標籤中的自訂新增市集時，會自行應用管理主控台的 strictKnownMarketplaces 和 blockedMarketplaces 列表。限制如何運作描述該檢查。表面涵蓋表比較共同工作與其他表面。
• 執行中的工作階段：大多數變更在傳遞機制表中的排程上到達執行中的工作階段，無需重新啟動。
  • 對 forceRemoteSettingsRefresh、requiredMinimumVersion 和某些使用者可編輯的金鑰的變更在下一個工作階段啟動時生效。
  • 新的或變更的 policyHelper 項目在下一次啟動時生效。如果伺服器受管設定在該啟動時遮蔽協助程式，協助程式會在擷取報告這些設定已移除時立即執行。
• 需要批准的變更：除了等待下一次啟動的更新，伺服器受管變更到需要批准的設定，例如掛鉤或 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 值。

​

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

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

​

Claude Code 如何結合受管來源

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

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

1. 遠端設定，從 claude.ai 作為 伺服器管理的設定 或通過 Claude 應用程式閘道 提供。Claude Code 僅在工作階段使用 符合條件的憑證 直接向 Anthropic 的 API 進行身份驗證、使用 /login 登入閘道，或在 Claude Desktop 的 Code 分頁中於 為該工作階段提供設定 的閘道後方執行時，才會擷取此來源。在其他提供者上，或當 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 僅在 其上方沒有存在的管理員文件 且沒有 主機提供的父設定 提供限制性金鑰時才讀取它

​

管理員文件何時視為存在

• 它將任何原則金鑰設定為 null 以外的值，即使是 Claude Code 無法讀取的值
• 它是存在但無法讀取的 HKLM 值、受管設定檔或 managed-settings.d 目錄

​

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

• sandbox.network.allowManagedDomainsOnly 和 sandbox.filesystem.allowManagedReadPathsOnly：任何管理員來源中的 true 會開啟鎖定。當鎖定開啟時，Claude Code 聯合它鎖定的允許清單，sandbox.network.allowedDomains 與 WebFetch(domain:...) 允許規則，或 sandbox.filesystem.allowRead，跨每個管理員來源。沒有鎖定，Claude Code 將允許清單視為任何其他金鑰，因此在 "first-wins" 下，未選定的管理員來源的允許清單被忽略
• allowAllClaudeAiMcps
• allowManagedMcpServersOnly：任何管理員來源中的 true 會開啟 MCP 允許清單鎖定。當鎖定開啟時，受管的 allowedMcpServers 列表來自設定列表的最高排名管理員來源。伺服器管理的列表替換較低來源的列表，而不是與其結合。 如果沒有管理員來源設定列表，每個通過拒絕清單的伺服器都會載入，除非 父設定 提供列表。 沒有鎖定，Claude Code 從它應用的受管來源讀取 allowedMcpServers，因此在 "first-wins" 下，未選定的管理員來源的列表被忽略。需要 Claude Code v2.1.273 或更新版本
• deniedMcpServers 和 disableClaudeAiConnectors：任何管理員來源中的項目或 true 適用。需要 Claude Code v2.1.273 或更新版本
• 沙箱二進位路徑 sandbox.bwrapPath 和 sandbox.socatPath
• 沙箱 ripgrep 二進位，sandbox.ripgrep
• sandbox.filesystem.disabled 和 sandbox.network.strictAllowlist
• useAutoModeDuringPlan、syncClaudeAiSkills 和 syncClaudeAiPlugins，其中任何管理員來源的 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 區塊

​

組合每個受管來源

​

使用幫助程式計算原則

• 發出的 managedSettings 物件是工作階段的唯一受管設定，包括 它在其他情況下從每個管理員來源讀取的金鑰，除了 forceRemoteSettingsRefresh，它有自己的啟動規則

​

讓嵌入主機添加原則

• 當任何管理員來源設定 allowManagedPermissionRulesOnly 時，Claude Code 在讀取時刪除 父提供的 權限允許規則和 additionalDirectories，即使較高優先順序來源未設定金鑰。金鑰對您自己的權限規則的影響來自 Claude Code 應用的受管設定，或來自您選擇合併的父設定
• Claude Code 強制執行它應用的受管設定中的 forceLoginOrgUUID 或 allowedMcpServers 值，並阻止父提供的值。在 MCP 允許清單鎖定之外，Claude Code 不應用的較低管理員來源中的值既不適用也不阻止父的。 在 Claude Code v2.1.273 或更新版本上，當 allowManagedMcpServersOnly 開啟時，來自設定列表的最高排名管理員來源的 allowedMcpServers 列表適用並阻止父的，作為 跨來源金鑰。父的列表僅在沒有管理員來源設定列表時適用。managedSourcesBehavior 項目說明在 "merge" 下哪個來源提供每個金鑰。在 v2.1.223 之前，任何管理員來源中的值阻止父的
• 對於 availableModels，Claude Code 強制執行它應用的受管設定中的值，並阻止父提供的列表
• 對於 strictKnownMarketplaces，Claude Code 同樣強制執行它應用的受管設定中的列表，並阻止父提供的列表。父的列表僅在沒有應用的受管來源設定列表時適用。需要 Claude Code v2.1.282 或更新版本
• 對於 allowedProviders，選定的受管來源 中的列表會阻止父提供的列表，而在 managedSourcesBehavior "merge" 選擇加入下，任何管理員來源中的列表都會阻止父提供的列表。需要 Claude Code v2.1.285 或更新版本
• 父提供的 blockedMarketplaces 除了受管來源設定的任何拒絕清單外還適用。需要 Claude Code v2.1.282 或更新版本

​

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

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

​

開發人員可以更改的內容

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

​

檢查政策是否生效

​

在 /status 中讀取來源

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

• 該行缺失：Claude Code 找不到傳遞政策金鑰的受管理來源。 如果您部署了受管理設定檔案，請檢查它是否位於作業系統的路徑中，以及它是否包含政策金鑰而不僅僅是控制金鑰。不是有效 JSON 的檔案不會產生此狀態；Claude Code 拒絕啟動。 當您改為通過伺服器管理設定部署時，執行 claude doctor，它會報告擷取結果。
• 該行命名的來源不是您部署的來源：存在更高優先級的來源，Claude Code 忽略了您的來源，Skipped sources 列出了它。Claude Code 如何組合受管理來源給出了順序。

​

尋找 Claude Code 丟棄的項目

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

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

• 如果作業系統拒絕讀取，例如在僅限根目錄的檔案上，每個工作階段都會在沒有該來源政策的情況下啟動。/status 和 claude doctor 記錄失敗，使用 -p 執行也會將其列印到 stderr。
• 對於任何其他讀取失敗，例如 I/O 錯誤，每個工作階段都會在啟動時退出，並顯示聯絡管理員的訊息。

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

​

失敗關閉的金鑰

• null 移除金鑰。
• 無效的 disableAllHooks（即使是引號的布林值）被丟棄並發出警告，因為強制執行 true 也會卸載您自己的受管理設定部署的 hook。
• 對於規則涵蓋的每個其他布林金鑰，字串 "true" 或 "false" 讀取為該布林值，在 /status 中發出通知要求您移除引號。

• 其中的鎖（例如 permissions.disableBypassPermissionsMode）讀取為其限制性值。
• 無效的 permissions.defaultMode 讀取為 default。
• 當 permissions 中的 deny 或 ask 列表根本無法讀取時，Claude Code 扣留 allow 和 additionalDirectories，因此授予永遠不會應用而沒有寫在旁邊的限制。報告命名每個扣留的授予和無法讀取的列表。
• 在 autoMode 中，無法讀取的 soft_deny 或 hard_deny 列表，或失去無效項目的列表，以相同方式扣留 allow 和 environment。

​

sandbox 內的無效值

• 如果您將布林金鑰設定為引號的 "true" 或 "false"，該值計為該布林值。而不是警告，/status 顯示通知要求您移除引號。
• 如果 failIfUnavailable 無效，Claude Code 會丟棄該值而不是將其視為 true，因此無法讀取的值永遠不會停止整個機隊中的工作階段啟動。
• Claude Code 將每個其他無效布林視為保持沙箱最嚴格的值，直到您修復它。打開沙箱或其限制之一的金鑰（例如 enabled 或 network.allowManagedDomainsOnly）計為 true。鬆散它的金鑰（例如 allowUnsandboxedCommands）計為 false。
• 在 credentials 外的列表中，例如 excludedCommands 或 network.allowedDomains，Claude Code 會丟棄無效項目並保留清單的其餘部分。不是陣列的列表，或沒有有效項目的列表，根本不適用。
• 當 network.deniedDomains 或其中任何項目無效時，Claude Code 也會扣留 network.allowedDomains，因此受管理允許清單不會授予任何內容，直到您修復拒絕清單。
• 當 filesystem.denyRead、filesystem.denyWrite 或其中任何項目無效時，Claude Code 也會扣留 filesystem.allowRead 和 filesystem.allowWrite，直到您修復拒絕清單。

​

只有受管理來源可以設定的金鑰

​

為您的組織關閉遙測

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

​

另請參閱

• 為您的組織設定 Claude Code：決定要強制執行什麼以及如何強制執行
• 伺服器受管設定：從 claude.ai 主控台或閘道傳遞原則
• 受管 MCP 設定：控制開發者可以使用哪些 MCP 伺服器
• 所有設定：每個金鑰，以及受管來源是否可以設定它
• 範例設定檔案：完整的 managed-settings.json 顯示受管金鑰的形狀