Managed settings 배포

기준일: 2026-10-23
공식 기준: Deploy managed settings

개요

Managed settings는 조직이 모든 개발자 머신에 배포하는 설정입니다. Claude Code는 이를 다른 모든 수준 위에 적용하므로 사용자, 프로젝트, 로컬, --settings 값이 override할 수 없습니다(낮은 수준의 더 엄격한 값이 여전히 인정되는 보안 예외 몇 가지 제외). 이 페이지는 managed settings를 배포하거나 적용되지 않는 이유를 디버깅하는 관리자를 위한 것입니다. 무엇을 강제할지는 admin setup의 "Decide what to enforce" 표에서 시작하고, claude.ai 콘솔 경로는 Server-managed settings를 보세요.

핵심 개념

메커니즘	전달 방식	Claude Code가 읽는 시점	사용할 때
Server-managed settings	claude.ai 관리 콘솔 또는 자체 호스팅 Claude apps gateway	시작 시 fetch, 매시간 폴링	머신을 건드리지 않고 claude.ai 조직 정책을 한 곳에서 바꾸고 싶을 때
MDM / OS 수준 정책	macOS configuration profile 또는 Windows HKLM 레지스트리 값 (Jamf, Intune, Group Policy 등)	시작 시 읽고 30분마다 변경 확인	이미 MDM이나 Group Policy로 기기를 관리할 때
파일 기반	각 머신의 시스템 디렉터리에 managed-settings.json	시작 시 읽고 파일이 바뀌면 재로드	MDM이 없는 머신, Linux 호스트, 직접 빌드한 이미지
HKCU 레지스트리 (Windows·WSL)	Windows HKCU 레지스트리 값	시작 시 읽고 30분마다 확인. 위에 admin 문서가 없고 호스트가 제한 키를 주지 않을 때만 사용	머신 수준 HKLM 키에 쓸 수 없을 때

모든 메커니즘이 settings.json과 같은 정책 키를 싣습니다. MDM과 파일 행을 합쳐 endpoint-managed settings라 부릅니다(정책이 개발자 기기에 저장되므로). 일부 키는 특정 소스에 묶입니다: 전달 제어 policyHelper, wslInheritsWindowsSettings, managedSourcesBehavior, 그리고 gateway 로그인 키 forceLoginGatewayUrl, gatewayInternalNetworks, forceLoginMethod의 "gateway" 값.

managed settings 파일, MDM profile, claude.ai 콘솔은 닿는 모두에게 하나의 정책을 적용합니다. 개발자 그룹별로 다른 정책을 주려면 그 그룹에 다른 파일/profile을 배포합니다. claude.ai 콘솔은 아직 그룹을 대상으로 지정할 수 없고 자체 호스팅 Claude apps gateway는 IdP 그룹별로 managed settings를 전달합니다. 같은 머신에 여러 메커니즘이 정책을 전달하면 기본적으로 하나만 쓰고 나머지는 무시합니다.

Jamf, Iru, Intune, Group Policy 시작 템플릿은 MDM examples repository에 있습니다. HIPAA 구성 조직은 settings examples repository의 settings-hipaa.json과 README-hipaa.md(샌드박싱, 네트워크 allowlist, 자격 증명 보호, 로컬 데이터 보존)를 참고하세요. managed MCP 서버는 managed-mcp.json 또는 managedMcpServers 키로 함께 배포합니다(Managed MCP).

상세

managed settings 파일 배포

가장 빠른 방법은 각 머신에 managed-settings.json 파일을 두는 것입니다.

1. managed-settings.json 작성: 강제하기로 한 키를 settings.json과 같은 JSON 모양으로 씁니다. 각 제어의 뒤에 있는 키는 "Decide what to enforce" 표에, managed 소스가 설정할 수 있는지는 settings reference의 각 항목에 있습니다. 다음 파일은 두 파일 읽기를 차단하고, bypass 모드를 끄고, Claude Code가 user·project·local 파일과 --allowedTools의 permission 규칙을 무시하게 합니다.

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

로그인 방법, 모델, MCP 서버, 마켓플레이스까지 더 많은 managed 키의 모양은 An organization's managed settings를 보세요.

2. 각 머신에 파일 배치: 플릿에 이미 파일을 배포하는 도구로 OS의 시스템 디렉터리에 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)가 표시됩니다. 그 뒤에 나머지 플릿에 롤아웃합니다.

정책이 적용되는 곳과 시점

• Surface: 개발자 머신에서 터미널, VS Code·JetBrains 확장, 데스크톱 앱의 Code 탭, Agent SDK 세션이 이 모든 소스를 읽습니다. Agent SDK 세션은 settingSources가 user/project/local 파일을 제외해도 managed settings를 로드합니다.
• 클라우드 세션: Anthropic 호스티드 환경의 세션은 기기의 MDM profile이나 파일을 읽지 않으므로 정책은 server-managed settings에서 와야 합니다. 셀프호스티드 환경의 세션은 러너 이미지의 managed settings 파일도 읽되, 기본으로는 server-managed settings가 정책 키를 전달하지 않을 때만(모든 admin 소스에서 읽는 키 제외)입니다.
• Claude Tag 세션: 클라우드 환경에서 돌지만 server-managed settings를 받지 않습니다. 셀프호스티드 환경에서는 러너 이미지의 managed settings 파일을 읽습니다. Claude Tag 자체는 Claude Tag admin 설정에서 구성합니다.
• Cowork 세션: Claude Desktop의 Cowork는 Claude Code 위에서 돕니다. Cowork 세션에서 Claude Code는 Team/Enterprise 계정으로 로그인해도 claude.ai 관리 콘솔의 server-managed settings를 fetch하지 않으므로 정책은 세션이 도는 곳에 따라 다릅니다. 사용자 머신에서는 기본으로 그 기기의 MDM/OS 정책과 managed settings 파일을 읽습니다. 전체 VM 샌드박스(Claude Desktop managed configuration의 requireCoworkFullVmSandbox)에서는 기기 MDM 정책과 파일이 없습니다. 원격 Cowork 세션은 Anthropic 관리 VM에서 돌아 읽을 기기 정책이 없습니다. 어디서 돌든 claude.ai는 claude.ai의 git 저장소나 Cowork의 Customize에서 마켓플레이스를 추가할 때 관리 콘솔의 strictKnownMarketplaces와 blockedMarketplaces 목록을 자체 적용합니다.
• 실행 중 세션: 대부분의 변경은 위 표의 주기에 따라 재시작 없이 반영됩니다. forceRemoteSettingsRefresh, requiredMinimumVersion와 일부 사용자 편집 가능 키는 다음 세션 시작에 적용됩니다. 새로 추가·변경된 policyHelper 항목은 다음 실행에 적용되며, 그 실행에서 server-managed settings가 helper를 가렸다면 fetch가 그 설정이 제거됐다고 보고하는 즉시 helper가 실행됩니다.
• 승인이 필요한 변경: 다음 실행까지 기다리는 업데이트 외에, hook이나 env 변수처럼 승인이 필요한 설정에 대한 server-managed 변경은 대화형 세션에서 개발자가 대화상자를 수락할 때까지 대기하고 IDE 확장이나 Agent SDK가 호스팅하는 세션에서는 현재 실행에 적용됩니다. 그 외 server-managed 변경은 다음 폴링에 적용됩니다.
• 장수 세션: 몇 주간 열어 둔 세션은 롤아웃보다 뒤처질 수 있습니다. requiredMinimumVersion은 오래된 바이너리의 시작을 막을 뿐 이미 실행 중인 세션을 끝내지 않습니다.

메커니즘별 정책 저장 위치

키는 어디서나 같지만 저장 위치와 모양이 다릅니다.

• Server-managed: Anthropic 서버 또는 gateway가 정책을 보유. Claude Code는 시작 시 적용하는 로컬 캐시를 유지하고 성공적인 fetch마다 교체
• macOS configuration profile: com.anthropic.claudecode managed preferences 도메인. managed-settings.json과 같은 최상위 키를 쓰되 중첩 설정은 dictionary, 목록은 plist array
• Windows HKLM 레지스트리: HKLM\SOFTWARE\Policies\ClaudeCode 아래 Settings라는 이름의 REG_SZ 또는 REG_EXPAND_SZ 값에 JSON
• 파일 기반: 시스템 디렉터리의 managed-settings.json, 선택적 managed-settings.d/ 디렉터리, managed-mcp.json. macOS /Library/Application Support/ClaudeCode/, Linux·WSL /etc/claude-code/, Windows C:\Program Files\ClaudeCode\. 레거시 Windows 경로 C:\ProgramData\ClaudeCode\managed-settings.json은 읽지 않습니다. 이 파일들은 심볼릭 링크로 배포할 수 있고 링크가 가리키는 파일을 읽으며, 링크가 시스템 디렉터리 밖을 가리키거나 그 안에 머무는지 확인할 수 없어도 정책은 적용됩니다. 이때 /status와 claude doctor에 파일 이름이 든 경고가 나타나며, 링크를 시스템 디렉터리 안의 대상으로 지정하면 경고가 사라집니다.
• Windows HKCU 레지스트리: HKCU\SOFTWARE\Policies\ClaudeCode 아래 같은 Settings 값

파일 기반 정책을 팀별로 분할

여러 팀이 한 정책의 일부를 소유하면 공유 파일 하나를 편집하는 대신 같은 시스템 디렉터리의 managed-settings.json 옆 managed-settings.d/에 부분마다 파일을 둡니다. Claude Code는 managed-settings.json을 먼저 merge하고 이어서 디렉터리의 모든 *.json을 알파벳 순으로 merge합니다. 순서는 10-telemetry.json, 20-security.json처럼 숫자 접두사로 제어하세요. 숨김 파일과 .json으로 끝나지 않는 파일은 무시합니다. 두 파일이 같은 키를 설정하면:

• 단일 값("model": "opus", "cleanupPeriodDays": 7): 나중 파일의 값이 이전 값을 대체
• 목록(permissions.deny, sandbox.network.allowedDomains): 두 목록을 중복 제거하며 결합
• 중첩 블록(env, sandbox): 키 단위로 merge하고 그 안의 각 키가 같은 규칙을 따름
• fallbackModel: 나중 체인이 이전 것을 통째로 대체
• extraKnownMarketplaces와 managedMcpServers: 같은 이름의 나중 항목이 이전 항목을 통째로 대체
• modelPicker: 나중 구성이 이전 것을 통째로 대체

managed 소스 결합 규칙

한 머신에 managed 소스가 여러 개 전달되면 managedSourcesBehavior 키가 나머지를 어떻게 다룰지 정합니다.

• "first-wins"(기본): 정책 키를 하나 이상 전달하는 가장 높은 순위의 소스를 쓰고 나머지는 merge하지 않고 무시합니다(모든 admin 소스에서 읽는 키 제외). 건너뛴 소스에 경고를 표시하지 않으며 /status가 사용한 소스와 건너뛴 소스를 명시합니다.
• "merge": 정책 키를 전달하는 모든 admin 소스를 적용하고 키 종류별로 결합합니다. 대부분의 키는 높은 순위 소스의 값, 목록은 합집합, lock은 가장 엄격한 값을 씁니다. 2.1.242+

용어: 정책 키는 두 제어 키 wslInheritsWindowsSettings, managedSourcesBehavior를 제외한 모든 설정 키입니다(그 둘만 든 파일/MDM 정책은 정책 키로 치지 않아 다음 소스로 넘어감). admin 소스는 아래 처음 세 가지입니다(HKCU 레지스트리는 사용자가 쓸 수 있어 해당 안 됨). 우선순위(높은 순):

1. 원격 설정: claude.ai server-managed settings 또는 Claude apps gateway가 전달. 세션이 적격 자격 증명으로 Anthropic API에 직접 인증하거나, /login으로 gateway에 로그인하거나, 세션 설정을 제공하는 gateway 뒤의 Claude Desktop Code 탭에서 실행될 때만 fetch. 다른 프로바이더나 ANTHROPIC_BASE_URL이 Anthropic API가 아닌 곳을 가리키면 다음 소스부터 시작
2. MDM / OS 수준 정책: macOS plist 또는 HKLM 레지스트리 키
3. managed settings 파일: managed-settings.d/*.json과 managed-settings.json을 함께 merge
4. HKCU 레지스트리: Windows, 그리고 HKLM 레지스트리나 Windows managed settings 파일이 wslInheritsWindowsSettings를 켜고 HKCU 값도 설정한 WSL. 위에 admin 문서가 없고 호스트가 제한 키를 주지 않을 때만 읽음

admin 문서가 "있는" 경우: HKCU 레지스트리는 존재하는 admin 문서 아래에서는 적용되지 않습니다. 문서가 있다는 것은 (a) null이 아닌 값으로 정책 키를 하나라도 설정(Claude Code가 읽을 수 없는 값이어도), (b) 존재하지만 읽을 수 없는 HKLM 값, managed settings 파일, managed-settings.d 디렉터리입니다. WSL의 /etc/claude-code도 사용자가 쓸 수 있으므로 Windows 문서가 위에 서는 때는 wslInheritsWindowsSettings 항목에 있습니다.

모든 admin 소스에서 읽는 키: 기본 "first-wins"에서도 대부분의 키는 선택된 소스에서만 읽고, 선택된 소스가 그 키를 설정하지 않았어도 낮은 순위 소스의 값은 무시합니다. 일부 키는 모든 admin 소스에서 읽으므로 낮은 순위 MDM 정책이나 managed settings 파일이 선택된 소스가 설정하지 않은 값을 설정할 수 있습니다(사용자가 쓸 수 있는 HKCU는 이 스캔에서 제외하며, HKCU가 유일한 소스이고 호스트가 parent settings를 주지 않으면 선택된 소스처럼 적용).

• sandbox.network.allowManagedDomainsOnly, sandbox.filesystem.allowManagedReadPathsOnly: 어느 admin 소스든 true면 lock이 켜짐. lock이 켜진 동안 Claude Code는 잠그는 allowlist(sandbox.network.allowedDomains와 WebFetch(domain:...) allow 규칙, 또는 sandbox.filesystem.allowRead)를 모든 admin 소스에 걸쳐 합집합으로 만듦. lock이 없으면 allowlist는 다른 키처럼 취급되어 "first-wins"에서 선택되지 않은 admin 소스의 allowlist는 무시
• allowAllClaudeAiMcps
• allowManagedMcpServersOnly: 어느 admin 소스든 true면 MCP allowlist lock이 켜짐. 켜진 동안 managed allowedMcpServers 목록은 하나라도 설정한 가장 높은 순위 admin 소스에서 옴(server-managed 목록이 낮은 소스 목록과 결합하지 않고 대체). 어느 admin 소스도 목록을 설정하지 않으면 denylist를 통과하는 모든 서버가 로드(parent settings가 목록을 주는 경우 제외). lock이 없으면 적용되는 managed 소스에서 allowedMcpServers를 읽음. 2.1.273+
• deniedMcpServers, disableClaudeAiConnectors: 어느 admin 소스든 항목이나 true가 있으면 적용. 2.1.273+
• sandbox 바이너리 경로 sandbox.bwrapPath, sandbox.socatPath, sandbox ripgrep 바이너리 sandbox.ripgrep
• sandbox.filesystem.disabled, sandbox.network.strictAllowlist
• useAutoModeDuringPlan, syncClaudeAiSkills, syncClaudeAiPlugins: 어느 admin 소스든 false면 동작이 꺼짐(개발자의 user/local 설정의 false도 끔, 각 키는 거부만 가능)
• enableArtifact: 어느 admin 소스의 false가 Artifact tool을 끔(개발자의 user/project/local의 false도 끄고 어떤 소스도 다시 켜지 못함). 2.1.242+
• maxEffortLevel: 어느 admin 소스든 가장 낮은 상한이 적용. 개발자가 자기 설정이나 --settings로 더 낮은 상한을 두면 그것이 적용되며 어떤 소스도 상한을 올릴 수 없음. 2.1.267+
• attribution(또는 deprecated includeCoAuthoredBy)의 커밋 트레일러 opt-out(어느 tier든)
• forceRemoteSettingsRefresh
• env: admin 소스에 걸쳐 변수 단위로 merge. 각 변수는 정의한 가장 높은 우선순위 소스에서 오고 낮은 소스가 높은 소스가 설정하지 않은 변수를 채움. 일부 변수는 자체 규칙을 따름(Per-key exceptions 참고). 2.1.223+, 이전에는 선택된 소스의 env 블록 전체만 적용

gateway 로그인 키는 별도 규칙을 따릅니다. server-managed settings에서는 읽지 않으므로, server-managed settings가 선택된 소스인 동안에도 정책 키를 가진 머신의 가장 높은 순위 admin 소스가 공급합니다. 그보다 낮은 admin 소스나 HKCU의 값은 무시됩니다. allowedProviders는 머신에 설정한 목록이 server-managed 목록과 결합하는 방식에 대해 자체 규칙이 있습니다(2.1.285+). admin 소스가 allowManagedMcpServersOnly나 allowedMcpServers 목록을 설정했는데 적용 중인 값이 아니면 /status와 claude doctor가 그 소스와 키를 알려줍니다.

모든 managed 소스 합치기 ("merge")

조직이 전달하는 모든 admin 소스를 적용하려면 배포하는 가장 높은 순위 소스에 managedSourcesBehavior를 "merge"로 설정합니다. 키 또는 정책 키를 가진 가장 높은 순위 소스에서만 읽으므로 낮은 소스가 스스로 위 소스와의 merge에 참여할 수 없고, server-managed settings를 받지 않는 머신은 MDM profile에도 키가 필요합니다. 사용자가 쓸 수 있는 HKCU는 다른 소스와 절대 merge되지 않습니다. 2.1.242+. "merge"에서는 낮은 소스의 permissions.allow 규칙과 hook 같은 목록 항목이 정책에 더해지므로, 가장 높은 소스 아래의 모든 소스가 관리자 통제 하에 있을 때만 켜세요.

키 종류	결합 방식	예
목록	모든 소스의 항목을 결합	permissions.allow, hooks, sandbox.network.allowedDomains, deniedMcpServers, deniedModels
Lock	어느 소스든 설정한 가장 엄격한 값 적용. 느슨한 값은 가장 높은 순위 소스에서만 적용	allowManagedHooksOnly, permissions.disableBypassPermissionsMode, crossSessionInbound, availableModelsMatch
제한 allowlist	설정한 가장 높은 순위 소스의 목록을 통째로 사용, 낮은 소스 항목을 더하지 않음	availableModels, allowedMcpServers, strictKnownMarketplaces, allowedChannelPlugins, fallbackModel 체인
통째로 취하는 값	설정한 가장 높은 순위 소스의 값을 통째로 사용	sandbox.credentials.awsPairs, sandbox.ripgrep (2.1.257에서 합치기 대신 통째로 취하도록 변경)
제공 MCP 서버	모든 소스의 서버 이름을 결합, 같은 이름이면 높은 소스의 항목 전체 적용	managedMcpServers
가장 높은 순위 소스에서만 읽는 키	가장 높은 소스가 설정하지 않아도 모든 낮은 소스의 키를 무시	apiKeyHelper 같은 자격 증명 helper, forceLoginOrgUUID 같은 로그인 pin, modelPicker, permissions.defaultMode
env	어느 설정에서든 admin 소스에 걸쳐 변수 단위로 merge
그 외 모든 키	설정한 가장 높은 순위 소스의 값	model, cleanupPeriodDays

머신에서 어떤 소스가 합쳐졌는지는 /status의 Setting sources 줄로 확인합니다.

policy helper 프로그램으로 정책 계산

policyHelper는 MDM 정책이나 managed settings 파일이 지정하는 실행 파일이며, Claude Code가 시작 시 실행해 managed settings를 계산합니다. 선택된 소스가 helper를 구성하고 helper가 managedSettings 객체를 내보내면, 내보낸 managedSettings 객체가 세션의 유일한 managed settings입니다(다른 경우 모든 admin 소스에서 읽는 키 포함, 자체 시작 규칙이 있는 forceRemoteSettingsRefresh 제외). 어떤 helper 실행이 실패하는지와 실패 시 동작은 settings reference의 Helper failures를 보세요. (2.1.257: policyHelper의 timeoutMs/refreshIntervalMs가 타이머 최대값 2147483647을 넘으면 clamp, 갱신 실패가 /status에 표시, 타임아웃을 타임아웃으로 보고)

임베딩 호스트가 정책 추가 (parent settings)

Claude Desktop, IDE 확장, Agent SDK 앱 같은 다른 애플리케이션이 Claude Code를 시작하면 그 호스트가 SDK managedSettings 옵션으로 자체 managed settings를 전달할 수 있으며 이를 parent settings라 부릅니다. 기본으로 Claude Code는 admin 소스(server-managed settings, MDM/OS 정책, managed settings 파일)가 있으면 parent settings를 무시합니다. admin 소스 옆에 parent settings를 merge하려면 가장 높은 우선순위 managed 소스에 parentSettingsBehavior를 "merge"로 설정합니다(그 소스에서만 읽음). 그러면 Claude Code는 호스트의 값 중 Claude가 할 수 있는 것을 제한하는 값만 유지하며, allowManaged*Only lock도 설정하지 않으면 호스트의 permission allow 규칙과 sandbox allowlist는 여전히 적용된다는 공백이 있습니다(Restrict parent settings 참고). policyHelper는 이 키와 무관하게 parent merge를 끌 수 있습니다.

parent가 준 값에 대한 별도 검사:

• admin 소스가 allowManagedPermissionRulesOnly를 설정하면, 더 높은 우선순위 소스가 그 키를 설정하지 않았어도 parent가 준 permission allow 규칙과 additionalDirectories를 읽을 때 버림
• forceLoginOrgUUID나 allowedMcpServers는 적용되는 managed settings의 값을 강제하고 parent가 준 값을 차단. MCP allowlist lock 밖에서는 Claude Code가 적용하지 않는 낮은 admin 소스의 값은 parent의 값을 적용하지도 차단하지도 않음. 2.1.273+에서 allowManagedMcpServersOnly가 켜진 동안 목록을 설정한 가장 높은 순위 admin 소스의 allowedMcpServers가 적용되고 parent의 것을 차단(cross-source 키). 어느 admin 소스도 목록을 설정하지 않을 때만 parent 목록 적용. v2.1.223 이전에는 어느 admin 소스의 값이든 parent의 값을 차단
• availableModels는 적용되는 managed settings의 값을 강제하고 parent 목록을 차단
• strictKnownMarketplaces도 적용되는 managed settings의 목록을 강제하고 parent 목록을 차단(적용되는 managed 소스가 설정하지 않을 때만 parent 목록 적용). 2.1.282+
• allowedProviders는 선택된 managed 소스의 목록이 parent 목록을 차단하고, "merge"에서는 어느 admin 소스의 목록이든 차단. 2.1.285+
• parent가 준 blockedMarketplaces는 managed 소스가 설정한 blocklist에 더해 적용. 2.1.282+

managed 규칙만 적용될 때 Cowork 폴더 접근 유지

Claude Desktop의 Cowork는 세션을 시작할 때 자체 공급하는 allow 규칙으로 각 세션의 작업 폴더 접근을 부여합니다. managed 정책이 allowManagedPermissionRulesOnly를 설정하면 Claude Code는 managed 정책의 allow 규칙만 유지하고 호스트가 parent settings, --allowedTools, settings 파일로 공급한 규칙을 버려서 그 폴더에 쓰기의 사전 승인이 사라집니다. 편집 전에 묻는 Cowork 세션에서는 Cowork가 프롬프트를 표시할 수 없어 Claude가 경로가 보호된 위치로 해석되거나 연결된 폴더 밖이라 각 쓰기가 차단됐다고 보고합니다. 복원하려면 그 머신에서 Claude Code가 선택하는 managed 소스에 그 폴더의 allow 규칙을 추가합니다(MDM으로 관리되는 플릿이면 별도 managed settings 파일이 아니라 MDM 정책). 아래는 파일 형태 예시이며 MDM 정책도 같은 키를 씁니다. 사용자 홈의 CoworkProjects 폴더 아래 편집을 허용하는 예(경로는 사용자가 연결하는 폴더로 교체):

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

배포 후 새 Cowork 세션에서 Claude가 그 폴더 아래에 파일을 저장할 수 있습니다. 경로 문법(절대 경로의 // 형태 포함)은 Read and Edit 규칙에 있습니다.

개발자가 바꿀 수 있는 것

개발자의 settings 파일, --settings 값, 프로젝트 파일은 managed 값을 override하지 못하며 예외는 더 엄격한 낮은 수준 값을 인정할 뿐입니다. 이 규칙 밖의 경우:

• 세션의 모델: managed model은 lock이 아니라 기본값입니다. --model과 ANTHROPIC_MODEL이 여전히 그 세션의 모델을 고르므로 선택을 제한하려면 availableModels를 배포하세요.
• 세션의 auto-compact window: managed autoCompactWindow도 기본값입니다. --autocompact 플래그와 CLAUDE_CODE_AUTO_COMPACT_WINDOW 변수가 그 세션의 window를 설정합니다.
• 로컬 관리자 권한: 머신의 관리자인 개발자는 managed 소스 자체를 편집할 수 있습니다. 그래서 MDM 도구가 profile/파일을 주기적으로 재배포하고 HKLM 레지스트리와 macOS managed preferences 도메인이 존재합니다.
• server-managed 캐시: server-managed settings는 Anthropic 서버에서 오며 로컬 캐시 편집은 다음 성공적인 fetch까지만 유지됩니다.
• 다른 도구: managed settings는 Claude Code만 구속합니다. 다른 도구로 API를 호출하는 개발자는 해당되지 않습니다.

정책 적용 확인

정책이 적용되지 않는다는 보고를 받았거나 플릿 롤아웃 전에 확인하려면 그 머신에서 두 명령이 답합니다. /status는 Claude Code가 선택한 managed 소스를, claude doctor는 버린 것을 보여줍니다.

/status의 소스 읽기: Setting sources 줄에 managed 소스가 적용 중이면 Enterprise managed settings와 괄호 안에 선택된 소스가 표시됩니다.

• (remote): claude.ai 또는 gateway의 server-managed settings
• (plist) 또는 (HKLM): MDM/OS 정책
• (file), (drop-ins), (file + drop-ins): managed-settings.json, drop-in 디렉터리, 또는 둘 다
• (remote + file, merged) 같은 , merged로 끝나는 목록: 조직이 모든 managed 소스를 합치며 나열된 소스가 정책에 merge됨. 낮은 소스가 목록에 안 나와도 env 변수를 공급할 수 있음. 2.1.242+
• (HKCU): 사용자가 쓸 수 있는 레지스트리 fallback
• (parent process): 임베딩 호스트가 제한 설정을 공급
• (helper): 선택된 MDM/파일 소스가 구성한 policyHelper

Claude Code가 머신에서 managed 소스를 찾았지만 선택하지 않았으면 둘째 줄 Skipped sources가 각 소스를 명시합니다(머신에 정책이 도달하지 않은 경우와 도달했으나 높은 우선순위 소스가 override한 경우를 구분, 2.1.242+). 정책이 적용되지 않으면 Setting sources 줄이 두 문제 중 어느 쪽인지 알려줍니다.

• 줄이 없음: 정책 키를 전달하는 managed 소스를 못 찾음. managed settings 파일을 배포했다면 OS 경로와, 제어 키만이 아니라 정책 키를 포함하는지 확인(유효한 JSON이 아닌 파일은 이 상태가 아니라 Claude Code가 시작을 거부). server-managed settings라면 fetch 결과를 보고하는 claude doctor를 실행
• 배포한 것과 다른 소스를 명시: 더 높은 우선순위 소스가 있고 Claude Code가 내 것을 무시한 것이며 Skipped sources에 나열됨

Claude Code가 버린 항목 찾기

managed settings 파일, MDM profile, 레지스트리 값, server-managed payload가 스키마 검증에 실패하면 Claude Code는 먼저 복구 가능한 개별 항목(예: 잘못된 permission 규칙 하나)을 건너뛰고 각각 경고합니다. 그래도 실패하는 값은 fail closed되는 키의 값이 아닌 한 버립니다. policyHelper가 내보내는 managedSettings는 더 엄격해서 같은 항목 복구는 하지만 남은 스키마 위반이 helper 실행 전체를 실패시키고 시작 시 Claude Code는 0이 아닌 코드로 종료한 helper처럼 시작을 거부합니다.

managed settings 파일, drop-in 파일, MDM plist, HKLM 레지스트리 값이 있지만 JSON 객체로 파싱되지 않으면 다른 admin 소스가 유효한 정책을 전달해도 Claude Code는 시작을 거부하고 소스를 명시하는 오류를 출력합니다. 각 소스가 이렇게 실패하는 경우: 파일/drop-in 유효한 JSON이 아니거나 최상위가 객체가 아님, MDM plist macOS plutil이 plist가 잘못됐다고 보고하거나 변환 결과가 JSON 객체가 아님, HKLM 값 Settings 값이 문자열이 아니거나 비었거나 JSON 객체가 아님. 이 거부를 일으키지 않는 세 상태: 없는 파일/profile/레지스트리 값(해당 소스 없이 실행), 빈 managed settings 파일({}로 간주), 사용자가 쓸 수 있는 HKCU 키의 잘못된 값(시작을 막지 않고 /status와 claude doctor에 알림으로 보고).

managed 소스가 있지만 읽을 수 없고 정책을 공급하는 admin 소스가 없으면 읽기 실패 이유에 따라 달라집니다. OS가 읽기를 거부했으면(예: root 전용 파일) 모든 세션이 그 소스 정책 없이 시작하고 /status와 claude doctor가 실패를 기록하며 -p 실행은 stderr에도 출력합니다. 그 외 읽기 실패(I/O 오류 등)는 모든 세션이 시작 시 관리자에게 문의하라는 메시지와 함께 종료합니다. 버려진 항목은 (1) 시작 시 잘못된 항목을 나열하는 대화형 대화상자, (2) -p 비대화형 실행의 stderr 요약, (3) 소스와 필드별로 나열하는 claude doctor에서 찾습니다.

fail closed 키

managed 소스가 allowManagedPermissionRulesOnly, disableAutoMode, skipDangerousModePermissionPrompt처럼 하나의 제한적 값을 갖는 최상위 키를 읽을 수 없는 값으로 설정하면, 고치기 전까지 그 키는 그 제한적 값으로 읽힙니다. 보고서는 키가 was present but invalid라고 하고 Claude Code가 취급하는 값을 명시합니다(sandbox 내부 키는 별도 절). 다음은 fail closed가 아닙니다.

• null은 키를 제거
• 잘못된 disableAllHooks는 따옴표 붙은 Boolean이어도 경고와 함께 버림(true를 강제하면 내 managed settings가 배포한 hook까지 내려가므로)
• 규칙이 다루는 나머지 Boolean 키는 문자열 "true"/"false"를 그 Boolean으로 읽고 /status에 따옴표를 빼라는 알림

permissions, autoMode, worktree, attribution 블록은 통째로 버리지 않고 필드별로 복구합니다. 블록 내부의 lock(permissions.disableBypassPermissionsMode 등)은 제한적 값으로 읽고, 잘못된 permissions.defaultMode는 default로 읽습니다. permissions의 deny 또는 ask 목록을 전혀 읽을 수 없는 동안 Claude Code는 allow와 additionalDirectories를 보류해 옆에 쓴 제한 없이 grant가 적용되지 않게 하며, 보고서가 보류된 grant와 읽을 수 없는 목록을 명시합니다. autoMode에서는 읽을 수 없거나 잘못된 항목이 있는 soft_deny/hard_deny 목록이 allow와 environment를 같은 방식으로 보류시킵니다. 단일 제한값 키의 fail-closed 규칙과 필드별 복구는 v2.1.282+가 필요합니다.

이 키들은 자체 fallback이 있습니다(present but invalid일 때).

필드	동작
allowedMcpServers	고칠 때까지 빈 allowlist로 강제(사용자가 추가한 MCP 서버 불허). managedMcpServers로 조직이 전달한 서버는 계속 로드, managed-mcp.json 서버는 allowlist 검사를 건너뛰는 서버 규칙대로 로드. 개별 잘못된 항목은 제거하고 유효 부분을 강제
allowedProviders	고칠 때까지 빈 allowlist로 강제 -> 모든 API 프로바이더 거부, 머신에서 Claude Code가 시작되지 않음. 알려지지 않은 프로바이더 이름 항목 하나만 문제면 그 항목만 버리고 보고하며 나머지 강제
allowedHttpHookUrls	고칠 때까지 빈 managed allowlist로 강제(HTTP hook은 다른 settings 파일이 그 URL을 나열한 경우에만 실행). 개별 항목만 잘못이면 그 항목만 제거
httpHookAllowedEnvVars	고칠 때까지 빈 managed allowlist로 강제(다른 settings 파일이 이름을 지정한 경우에만 헤더 변수 보간). 개별 항목만 잘못이면 그 항목만 제거
allowedChannelPlugins	고칠 때까지 빈 allowlist로 강제 -> --channels에 전달한 channel 플러그인 불허. 개별 항목만 잘못이면 제거
strictKnownMarketplaces	고칠 때까지 빈 allowlist로 강제 -> 어떤 마켓플레이스 소스도 불허. 컴파일되지 않는 hostPattern regex 같은 잘못된/강제할 수 없는 개별 항목은 제거하고 유효 부분 강제
availableModels	고칠 때까지 빈 allowlist -> Default 모델만 사용 가능. 문자열이 아닌 항목은 제거하고 유효 부분 강제
availableModelsMatch	고칠 때까지 exact로 취급
forceLoginOrgUUID	고칠 때까지 어떤 조직도 로그인 불허
gatewayInternalNetworks	잘못된 값이 머신의 가장 높은 managed 소스에서 오면 고칠 때까지 /login이 그 머신의 모든 새 클라우드 gateway 로그인을 거부
crossSessionInbound	가장 제한적인 refuse로 취급 -> 고칠 때까지 cross-session 메시지 수신 거부. 개발자는 경고를 봄
deniedMcpServers	개별 잘못된 항목은 제거하고 유효 부분 강제. 전체가 잘못되면 경고와 함께 버림(모든 서버 거부는 정책이 지명하지 않은 서버도 막으므로)
deniedModels	문자열이 아닌 항목은 제거하고 나머지 강제. 전체가 잘못되면 경고와 함께 버리고 고칠 때까지 모델을 막지 않음
blockedMarketplaces	개별 잘못된 항목은 제거하고 유효 부분 강제. 파싱되지만 절대 매치될 수 없는 항목(컴파일 안 되는 hostPattern regex 등)은 경고와 함께 유지(고칠 때까지 막는 것은 없으나 마켓플레이스 제한은 활성). 전체가 잘못되면 경고와 함께 버림
sandbox	블록 내부 값 하나가 잘못되어도 블록 전체를 버리지 않음. 필드 종류별 처리는 아래 "sandbox 내부의 잘못된 값"
sandbox.credentials	복구 가능한 잘못된 항목은 경고와 함께 mode: "deny"로 강등, 복구 불가능한 항목은 제거, 유효 항목은 강제 유지
strictPluginOnlyCustomization	값이 boolean도 배열도 아니면 네 surface를 모두 잠그는 true로 취급. 이 버전이 surface로 인식하지 못하는 배열 항목은 아무것도 잠그지 않으며 상태 노트가 이런 항목 수를 세어 오타를 확인하게 함
enabledPlugins	잘못된 항목은 경고와 함께 버리고 나머지 항목은 강제 유지. 플러그인 ID 맵이 아니거나 모든 항목이 잘못이면 경고와 함께 통째로 버림

allowedHttpHookUrls와 httpHookAllowedEnvVars는 settings 파일들에 걸쳐 merge되므로 managed 목록이 비어 있는 동안에도 user/project/local 설정의 항목은 계속 적용됩니다. 이 두 키와 allowedChannelPlugins의 fallback은 Claude Code v2.1.267+가 필요합니다(이전 버전은 값이나 항목이 잘못이면 키 전체를 버림). strictKnownMarketplaces, blockedMarketplaces fallback은 v2.1.277+, strictPluginOnlyCustomization, enabledPlugins fallback은 v2.1.282+가 필요합니다. requiredMinimumVersion과 requiredMaximumVersion은 설계상 fail open입니다(잘못된 값은 강제하지 않고 버림). 이 관용은 managed settings에만 적용되며 user/project/local settings 파일은 엄격합니다. JSON이나 최상위 모양이 검증에 실패하는 파일은 통째로 거부·보고되고, 잘못된 permission 규칙 같은 개별 항목은 경고와 함께 건너뛰고 나머지 파일은 적용됩니다.

sandbox 내부의 잘못된 값

managed sandbox 블록의 값 하나가 잘못되어도 필드마다 따로 검증하므로 블록 전체를 버리지 않습니다. 필드별 처리는 v2.1.283+가 필요하며 그 이전에는 credentials 밖의 값이 잘못이면 credentials를 제외한 모든 sandbox 필드를 버렸습니다. 잘못된 필드에 대한 경고는 필드를 명시하고 어떻게 되는지 알려주며, 처리는 필드가 제어하는 것에 따라 다릅니다.

• Boolean 키를 따옴표 붙은 "true"/"false"로 설정하면 그 Boolean으로 계산되고 경고 대신 /status가 따옴표를 빼라는 알림을 표시
• failIfUnavailable이 잘못되면 true로 취급하지 않고 값을 버려 읽을 수 없는 값이 플릿 전체의 세션 시작을 막지 않게 함
• 그 외 잘못된 Boolean은 고칠 때까지 sandbox를 가장 엄격하게 유지하는 값으로 취급. sandbox나 그 제한을 켜는 키(enabled, network.allowManagedDomainsOnly)는 true, 완화하는 키(allowUnsandboxedCommands)는 false
• credentials 밖의 목록(excludedCommands, network.allowedDomains)에서는 잘못된 항목을 버리고 나머지 목록을 유지. 배열이 아니거나 유효 항목이 없는 목록은 전혀 적용되지 않음
• network.deniedDomains 또는 그 항목이 잘못된 동안 Claude Code는 network.allowedDomains도 보류해 deny 목록을 고치기 전까지 managed allowlist가 아무것도 허용하지 않음
• filesystem.denyRead, filesystem.denyWrite 또는 그 항목이 잘못된 동안 deny 목록을 고칠 때까지 filesystem.allowRead와 filesystem.allowWrite를 모두 보류

managed 소스만 설정할 수 있는 키

다음 키는 managed 소스에서만 읽으며 user/project settings 파일에 두면 효과가 없습니다. 대부분은 lock이며, lock이 다스리는 값(permission 규칙, sandbox.network.allowedDomains 등)은 어떤 수준에서나 설정할 수 있는 일반 키이고 lock이 Claude Code에게 managed 값만 존중하라고 알립니다. 표에 없는 키는 settings reference 인덱스의 Scope 열을 보세요.

설정	설명
allowAllClaudeAiMcps	배포한 managed-mcp.json과 함께 Claude Code가 직접 fetch하는 claude.ai 커넥터를 억제하지 않고 로드
allowedChannelPlugins	메시지를 push할 수 있는 channel 플러그인 allowlist. 설정하면 기본 Anthropic allowlist를 대체. channelsEnabled: true 필요
allowManagedHooksOnly	true면 실행되는 hook을 제한
allowManagedMcpServersOnly	true면 managed settings의 allowedMcpServers만 존중. deniedMcpServers는 여전히 모든 소스에서 merge
allowManagedPermissionRulesOnly	managed settings를 permission 규칙의 유일한 소스로 만듦
blockedMarketplaces	마켓플레이스 소스 blocklist. 차단된 소스는 다운로드 전에 확인해 파일시스템에 닿지 않음
channelsEnabled	조직에 channels 허용
disableCommandPluginSources	true면 command 플러그인 소스를 완전 차단(마켓플레이스가 선언한 명령 실행 안 됨). managed settings 자체가 선언한 마켓플레이스를 제외하고 마켓플레이스 headersHelper 명령도 차단. 미설정 시 allowManagedHooksOnly를 따름. v2.1.229+, headersHelper 차단은 v2.1.238+
disableSideloadFlags	시작 시 --plugin-dir, --plugin-url, --agents, --mcp-config 플래그 거부. 클라우드 세션에서는 세션을 시작하되 서버가 전달한 --mcp-config 서버를 버림. v2.1.193+
forceRemoteSettingsRefresh	true면 원격 managed settings를 새로 fetch할 때까지 CLI 시작을 막고 fetch 실패 시 종료
managedMcpServers	모든 사용자에게 자신의 서버와 함께 제공되는 원격 MCP 서버(잠그는 것이 아니라 제공). v2.1.259+
managedSourcesBehavior	가장 높은 우선순위 managed 소스만 적용할지, 모두 합칠지
parentSettingsBehavior	호스트가 준 parent settings를 managed 정책 아래에 merge할지
pluginSuggestionMarketplaces	Claude Code가 사용자에게 제안할 수 있는 플러그인의 마켓플레이스
pluginTrustMessage	설치 전 표시되는 플러그인 신뢰 경고에 덧붙이는 사용자 지정 메시지
policyHelper	시작 시 managed settings를 계산하는 실행 파일
sandbox.filesystem.allowManagedReadPathsOnly	true면 managed settings의 filesystem.allowRead 경로만 존중. denyRead는 여전히 모든 소스에서 merge
sandbox.network.allowManagedDomainsOnly	managed allowedDomains와 WebFetch(domain:...) allow 규칙만 존중하고 다른 도메인은 묻지 않고 차단
strictKnownMarketplaces	사용자가 추가·설치할 수 있는 플러그인 마켓플레이스 소스를 제어
strictPluginOnlyCustomization	user·project 소스의 skills, agents, hooks, MCP 서버를 차단. true는 네 가지 모두 잠그고 배열은 이름 지정
wslInheritsWindowsSettings	HKLM 레지스트리나 C:\Program Files\ClaudeCode 아래 파일에 설정하면 WSL이 Windows 정책 체인을 읽고 Windows admin 문서가 없을 때만 /etc/claude-code를 읽음

Team/Enterprise 플랜에서 Owner는 Claude Code admin settings에서 Remote Control과 클라우드 세션을 조직 전체에서 켜고 끕니다. Owner가 Remote Control을 끄면 v2.1.286+에서 이미 연결된 세션도 조직 정책을 다음에 갱신할 때(약 한 시간에 한 번) 연결이 끊깁니다. Remote Control은 disableRemoteControl 설정으로 기기별로 끌 수도 있습니다(클라우드 세션에는 기기별 managed settings 키가 없음). 이 조직 설정이 특정 머신에 도달했는지는 그 머신에서 claude doctor를 실행해 Organization policy 줄(Claude Code가 정책을 어디서 로드했는지 또는 왜 로드하지 못했는지)을 읽습니다. v2.1.261+. 실행 중 세션에서는 정책이 로드되지 않았을 때 /status가 같은 줄을 보여줍니다.

조직 전체 텔레메트리 끄기

Claude Code는 Anthropic API를 쓰는 세션(직접, LLM gateway, 사용자 지정 ANTHROPIC_BASE_URL 경유)에서 기본으로 Anthropic 운영 텔레메트리를 보냅니다. 개발자 각자의 셸에 의존하지 않고 모두에게 끄려면 managed settings의 env 블록으로 DISABLE_TELEMETRY를 전달합니다.

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

Claude Code는 값 1을 사용자에게 승인 대화상자를 보이지 않고 적용합니다. 텔레메트리를 끄면 정책이 닿는 개발자에 대해 조직 분석 대시보드에 쓰이는 사용 데이터 전송이 멈추고, 이 변수는 그 개발자들의 feature-flag fetching도 끕니다. 고객 관리 암호화 키를 쓰며 Claude Code를 gateway로 라우팅하는 조직은 third-party integrations 문서의 "Configure proxies and gateways"가 이 변수가 필요한 이유를 설명합니다.

함께 보기

• Set up Claude Code for your organization
• Server-managed settings
• Managed MCP configuration
• Settings
• Settings reference (all keys)
• Example settings files