Claude Code managed settings 배포

Claude Code 공식 문서 "Deploy managed settings". OS별 관리 파일 경로, 전달 방법 4가지(서버·MDM·파일·HKCU), 출처 우선순위와 first-wins·merge, 세션별로 닿는 정책, /status·claude doctor 확인, 잘못된 값 처리, managed 전용 키

확인 2026-10-18원본 자료 1건의 요약갱신 2026-10-21언급 22곳

한 줄 요약: Claude Code 공식 문서 "Deploy managed settings". 조직이 모든 개발자 기기에 배포하는 managed settings를 어떻게 전달하고(파일·MDM·서버·HKCU 네 경로), 여러 관리 출처를 어떻게 합치며(first-wins 기본, merge 선택), 정책이 실제로 적용됐는지 /status·claude doctor로 확인하고, 잘못된 값을 어떻게 처리하는지(일부 키는 가장 엄격한 값으로 읽음)를 다룬다. 관리자가 배포하거나 "정책이 안 먹는다"를 디버깅할 때 읽는 문서다.

원본 정보#

제목: Deploy managed settings
발행: Anthropic, Claude Code 공식 문서 (원본 날짜 미상)
URL: https://code.claude.com/docs/en/managed-settings (새 창)
수집(fetch)일: 2026-10-18. 본문의 경로, 설정 키, 버전 조건(v2.1.2xx), 주기(매시간·30분)는 이 날짜 기준이다.

핵심 주장#

managed settings는 다른 모든 레벨 위에 적용된다. 단 예외가 있다. user, project, local, --settings 값 어느 것도 managed 값을 덮어쓰지 못하고, 몇 가지 보안 민감 예외에서는 낮은 레벨의 더 엄격한 값이 여전히 효력을 갖는다. 그러나 원본은 이 규칙 밖의 경우도 따로 적는다: managed model과 autoCompactWindow는 잠금이 아니라 기본값이고(--model·ANTHROPIC_MODEL, --autocompact·CLAUDE_CODE_AUTO_COMPACT_WINDOW가 여전히 그 세션 값을 정한다), 기기의 로컬 관리자 권한이 있는 개발자는 관리 출처 자체를 고칠 수 있으며, 서버 관리 설정의 로컬 캐시 수정은 다음 성공한 fetch까지만 유효하고, managed settings는 Claude Code만 묶는다(다른 도구로 API를 부르면 적용되지 않는다). → managed settings, Claude Code 관리자 권한 통제
전달 경로는 네 가지이고, 경로마다 닿는 세션이 다르다. 서버 관리(claude.ai 관리 콘솔 또는 자체 호스팅 Claude apps gateway, 시작 때 가져오고 매시간 폴링), MDM·OS 정책(macOS 구성 프로파일, Windows HKLM 레지스트리, 시작 때 읽고 30분마다 변경 확인), 파일(managed-settings.json, 시작 때 읽고 파일이 바뀌면 다시 읽음), Windows HKCU 레지스트리(사용자 쓰기 가능, 위에 관리자 문서가 없고 호스트가 넘긴 parent settings가 제한 키를 주지 않을 때만). Anthropic 호스팅 클라우드 세션은 기기의 MDM·파일을 읽지 않고, Cowork 세션은 claude.ai 관리 콘솔의 서버 관리 설정을 가져오지 않으며, Claude Tag 세션은 서버 관리 설정을 받지 않는다. → Claude Code managed settings 배포·점검
여러 관리 출처가 한 기기에 오면 기본은 하나만 쓴다(first-wins). 순서는 원격(서버 관리) > MDM·OS 정책 > 관리 파일 > HKCU이고, 정책 키를 하나라도 가진 가장 높은 출처만 쓰고 나머지는 경고 없이 무시한다(일부 교차 출처 키 제외). managedSourcesBehavior: "merge"(v2.1.242 이상)를 가장 높은 출처에 두면 모든 관리자 출처를 키 종류별로 합친다. 원본은 낮은 출처의 permissions.allow·훅 같은 목록 항목이 정책에 더해지므로, 가장 높은 출처 아래의 모든 출처가 관리자 통제 아래 있을 때만 켜라고 한다. → managed settings
적용 확인은 /status와 claude doctor 두 명령으로 한다. /status의 Setting sources 줄이 선택된 관리 출처((file), (remote), (plist), (HKLM), , merged 등)를 보여 주고, Skipped sources 줄(v2.1.242 이상)이 무시된 출처를 보여 준다. claude doctor는 버려진 항목을 출처·필드와 함께 나열한다. → Claude Code managed settings 배포·점검
잘못된 값 처리: 일부는 닫힌 쪽(fail closed)으로, 일부는 열린 쪽으로. 관리 파일·MDM plist·HKLM 값이 JSON 객체로 파싱되지 않으면 다른 출처가 정상이어도 Claude Code가 시작을 거부한다. 제한 값이 하나뿐인 최상위 키(예: allowManagedPermissionRulesOnly, disableAutoMode, skipDangerousModePermissionPrompt)를 읽을 수 없으면 그 제한 값으로 읽는다(v2.1.282 이상). 반대로 requiredMinimumVersion·requiredMaximumVersion은 설계상 열린 쪽이라 잘못된 값은 버려진다. 이 관용은 managed settings에만 적용되고 user·project·local 파일은 여전히 엄격하다. → managed settings

원본의 경로·키·숫자 (2026-10-18 기준)#

관리 파일 위치: macOS /Library/Application Support/ClaudeCode/managed-settings.json, Linux·WSL /etc/claude-code/managed-settings.json, Windows C:\Program Files\ClaudeCode\managed-settings.json. Windows 예전 경로 C:\ProgramData\ClaudeCode\managed-settings.json은 읽지 않는다. 같은 디렉터리에 managed-settings.d/(선택)와 managed-mcp.json을 둔다.
MDM 저장 위치: macOS 관리 환경설정 도메인 com.anthropic.claudecode, Windows HKLM\SOFTWARE\Policies\ClaudeCode의 Settings 값(REG_SZ 또는 REG_EXPAND_SZ, JSON), HKCU는 HKCU\SOFTWARE\Policies\ClaudeCode의 같은 값.
원본 첫 예시(managed-settings.json): permissions.deny에 Read(./.env)·Read(./secrets/**), permissions.disableBypassPermissionsMode: "disable", 최상위 allowManagedPermissionRulesOnly: true. 원본 설명: 파일 읽기 둘을 막고, bypass 모드를 끄고, user·project·local 파일과 --allowedTools의 권한 규칙을 무시하게 한다.
managed-settings.d/ 합치기: managed-settings.json 먼저, 그다음 디렉터리의 *.json을 알파벳 순(예: 10-telemetry.json, 20-security.json). 숨김 파일과 .json이 아닌 파일은 무시. 단일 값은 뒤 파일이 이기고, 목록은 중복 없이 합치고, 중첩 블록(env, sandbox)은 키별로 합친다. fallbackModel·modelPicker는 통째로, extraKnownMarketplaces·managedMcpServers는 같은 이름 항목을 통째로 바꾼다.
텔레메트리 끄기: managed settings env에 "DISABLE_TELEMETRY": "1". 값 1은 승인 대화상자 없이 적용된다. 끄면 조직 분석 대시보드용 사용 데이터와 기능 플래그 가져오기도 꺼진다.
버전 조건(일부): managedSourcesBehavior: "merge"·Skipped sources·enableArtifact v2.1.242, env 출처별 변수 병합 v2.1.223, maxEffortLevel v2.1.267, allowManagedMcpServersOnly·deniedMcpServers·disableClaudeAiConnectors의 교차 출처 동작 v2.1.273, fail-closed 규칙·블록별 수리 v2.1.282, sandbox 필드별 검증 v2.1.283, allowedProviders v2.1.285, Remote Control 끄면 연결된 세션도 끊김 v2.1.286, claude doctor의 Organization policy 줄 v2.1.261.
그 밖: Jamf·Iru·Intune·Group Policy 시작 템플릿은 anthropics/claude-code 저장소의 examples/mdm, HIPAA 구성용 예시는 examples/settings의 settings-hipaa.json에 있다고 원본이 링크한다.

원본이 링크만 한 문서#

이후 수집함(2026-10-21): Settings(우선순위 예외 목록) → Claude Code 설정 파일과 우선순위, Settings reference(키별 Scope) → Claude Code 설정 키 전체 레퍼런스, Permissions(Read·Edit 규칙 경로 문법) → Claude Code 권한 설정.
이 사이트에서 아직 다루지 않음: Server-managed settings, Admin setup("Decide what to enforce" 표), Managed MCP configuration, Claude apps gateway. 이 문서들이 다루는 키의 전체 동작은 해당 참조 문서를 다시 확인한다.