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 또는 OS 수준 정책: macOS plist 또는 HKLM 레지스트리 키
3. 관리되는 설정 파일, managed-settings.d/*.json 및 managed-settings.json이 함께 병합됨
4. Windows의 HKCU 레지스트리, 그리고 HKLM 레지스트리 또는 Windows 관리 설정 파일이 wslInheritsWindowsSettings를 켜고 HKCU 값도 이를 설정할 때 WSL의 HKCU 레지스트리입니다. Claude Code는 위의 소스가 정책 키를 제공하지 않고 호스트 제공 부모 설정이 제한적인 키를 제공하지 않을 때만 읽습니다.

이 다이어그램은 순위를 보여주며, Claude Code가 두 설정 중 하나에서 처음 세 소스에서 읽는 교차 소스 키의 예를 포함합니다:

모든 관리 소스에서 읽은 키

기본 "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

• 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 블록만 적용했습니다.

게이트웨이 로그인 키는 별도의 규칙을 따릅니다. Claude Code는 서버 관리 설정에서 이들을 읽지 않으므로, 서버 관리 설정이 선택된 소스인 동안 정책 키를 전달하는 머신의 가장 높은 순위의 관리 소스가 여전히 이들을 제공합니다. 그 아래에 순위가 지정된 관리 소스의 값이나 HKCU 레지스트리의 값은 무시됩니다.

관리 소스가 allowManagedMcpServersOnly를 설정하거나 allowedMcpServers 목록을 설정하고 그 값이 적용 중인 값이 아닐 때, /status 및 claude doctor는 해당 소스와 키의 이름을 지정합니다.

모든 관리되는 소스 구성

Claude Code가 조직에서 제공하는 모든 관리 소스를 적용하도록 하려면, 배포하는 가장 높은 순위의 소스에서 managedSourcesBehavior를 "merge"로 설정합니다. Claude Code는 키 또는 정책 키를 전달하는 가장 높은 순위의 소스에서만 키를 읽으므로, 더 낮은 소스가 위의 소스와 병합하도록 자신을 선택할 수 없으며, 서버 관리 설정을 받지 않는 머신은 MDM 프로필에도 키가 필요합니다. 사용자가 쓸 수 있는 HKCU 레지스트리는 다른 소스와 병합되지 않습니다. Claude Code v2.1.242 이상이 필요합니다.

"merge" 아래에서 Claude Code는 더 낮은 소스의 목록 항목(예: permissions.allow 규칙 및 hooks)을 정책에 추가하므로, 가장 높은 소스 아래에 순위가 지정된 모든 소스가 관리자의 제어 아래에 있을 때만 켭니다.

이 표는 "merge" 아래에서 Claude Code가 각 종류의 키를 결합하는 방식을 보여줍니다. managedSourcesBehavior 항목은 세 행의 모든 키를 이름 지정합니다: 제한 허용 목록, 전체로 취한 값, 그리고 가장 높은 순위의 소스에서만 읽은 키입니다.

머신에서 결합된 소스를 확인하려면 /status의 Setting sources 줄을 읽으세요. 해당 섹션은 각 레이블의 의미를 설명합니다.

도우미 프로그램으로 정책 계산

policyHelper는 MDM 정책이나 관리되는 설정 파일이 이름을 지정하는 실행 파일이며, Claude Code는 이를 실행하여 시작 시 관리되는 설정을 계산합니다. 선택된 소스가 하나를 구성하고 도우미가 managedSettings 객체를 내보낼 때, 해당 출력은 Claude Code가 읽는 것을 변경합니다:

• 내보낸 managedSettings 객체는 세션의 유일한 관리되는 설정입니다, 그렇지 않으면 모든 관리 소스에서 읽은 키를 포함하여, forceRemoteSettingsRefresh 제외, 자신의 시작 규칙이 있음

도우미 실행이 실패하는 경우와 실패할 때 Claude Code가 수행하는 작업은 도우미 실패를 참조하세요.

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

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