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. HKCU 레지스트리, Windows에서, 그리고 HKLM 레지스트리 또는 Windows 관리형 설정 파일이 wslInheritsWindowsSettings를 켜고 HKCU 값도 이를 설정할 때 WSL에서. 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
• 샌드박스 바이너리 경로 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 블록만 적용했습니다

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

모든 관리형 소스 구성

배포하는 모든 관리 소스를 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"
  }
}