managed settings

확인 날짜 안내

원본 날짜 미상인 Claude Code 공식 문서들의 수집일(2026-10-18) 기준이다. 키 이름·경로·버전 조건은 빨리 바뀌므로 대외 자료에 쓰기 전에 공식 문서를 다시 확인한다. 블로그 Steering Claude Code(2026-06-18)의 주장은 이 페이지에 옮기지 않고 "관련"의 링크로 넘겼다(페이지 날짜를 블로그 날짜로 내리지 않기 위해).

정의#

조직이 모든 개발자 기기에 배포하는 Claude Code 설정이다. 키 모양은 settings.json(용어 사전)과 같고, Claude Code는 이를 다른 모든 레벨 위에 적용한다. Claude Code managed settings 배포

• 덮어쓰기: user, project, local, --settings 값 어느 것도 managed 값을 덮어쓰지 못한다. 단 몇 가지 보안 민감 예외에서는 낮은 레벨의 더 엄격한 값이 여전히 효력을 갖는다. Claude Code managed settings 배포 예외 목록은 공식 Settings 문서에 있다(2026-10-21 기준 11개 키: disableClaudeAiConnectors, enableArtifact, isolatePeerMachines, permissions.blockReadsOutsideWorkingDirectories, autoMode.classifyAllShell, remoteControlAtStartup, crossSessionInbound, useAutoModeDuringPlan, syncClaudeAiSkills, syncClaudeAiPlugins, maxEffortLevel). 키마다 엄격한 값을 받아 주는 범위가 다르다(예: remoteControlAtStartup은 project·local의 false만, useAutoModeDuringPlan은 .claude/settings.json의 false를 무시). 표 전체는 Claude Code 설정 파일. Claude Code 설정 파일과 우선순위
• 전체 층에서의 자리: managed > 명령줄 --settings > project local > shared project > user. 목록 키는 합쳐지고, 환경 변수는 이 층에 속하지 않는다. Claude Code 설정 파일과 우선순위 → Claude Code 설정 파일
• 같은 관리 위치에 둘 수 있는 것: 권한 규칙과 잠금, 조직 메모리(CLAUDE.md)(파일 또는 claudeMd 키), Enterprise 스킬, 관리 MCP 서버, 마켓플레이스 제한 등. Claude Code 메모리, Claude Code 스킬, Claude Code managed settings 배포
• 공식 메모리 문서의 역할 구분: 기술적 강제(도구·명령·경로 차단, 샌드박스, 로그인 제한)는 managed settings, 행동 안내는 managed CLAUDE.md. Claude Code 메모리
• (2026-10-21 기준) 샌드박스를 조직에 강제할 때: managed가 sandbox.enabled·failIfUnavailable 같은 Boolean을 두면 managed 값을 쓰고, allowRead 같은 배열 키는 범위끼리 합쳐져 개발자가 항목을 더할 수 있으므로 allowManagedReadPathsOnly·allowManagedDomainsOnly 같은 잠금을 따로 건다. managed allowUnsandboxedCommands: false나 allowManagedDomainsOnly: true는 샌드박스를 관리자 필수로 만들어 저장소 파일의 느슨한 샌드박스 설정을 무시하게 하지만(v2.1.285 이상), 개발자의 ~/.claude/settings.json·--settings 항목은 managed 전용 잠금이 없는 한 계속 적용된다. Claude Code 샌드박스 → 샌드박스, Claude Code 샌드박스 설정하기

무엇은 막지 못하는가 (원본이 적은 한계)#

원본은 "덮어쓰지 못한다" 규칙 밖에 있는 경우를 따로 든다. 고객에게 "managed settings로 강제된다"고 말할 때 같이 말해야 할 조건이다. Claude Code managed settings 배포

편집자 해석: 마지막 줄은 다른 원본(권한 모드 문서)의 사실이다. managed settings 배포 문서의 "덮어쓰지 못한다"는 설정 파일과 --settings 값에 대한 말이고(원문: "A developer's own settings files, --settings values, and project files never override a managed value"), 배포 문서는 --permission-mode 같은 시작 플래그를 이 규칙의 대상에 넣지도, 규칙 밖 경우의 목록("These cases sit outside that rule", --model은 있다)에 넣지도 않는다. 그래서 두 원본이 충돌한다고 단정할 근거는 없다고 볼 수 있다. defaultMode가 잠금이 아닌 시작값이라는 말은 권한 모드 문서에만 있다. 권한 모드 문서에서 모드를 막는 것은 disableAutoMode·disableBypassPermissionsMode 같은 잠금 키다. → Claude Code 관리자 권한 통제

관리 출처와 우선순위 (2026-10-18 기준)#

전달 경로는 넷이다. 서버 관리(claude.ai 관리 콘솔 또는 자체 호스팅 Claude apps gateway), MDM·OS 정책(macOS 구성 프로파일, Windows HKLM), 관리 파일(managed-settings.json과 managed-settings.d/), Windows HKCU 레지스트리. MDM과 파일을 합쳐 endpoint-managed settings라 부른다. Claude Code managed settings 배포

Claude Code가 확인하는 순서(높은 것부터): Claude Code managed settings 배포

1. 원격 설정(서버 관리 또는 gateway). 세션이 적격 자격 증명으로 Anthropic API에 직접 인증하거나, /login으로 gateway에 로그인하거나, 그 세션에 설정을 주는 gateway 뒤 Claude Desktop Code 탭에서 돌 때만 가져온다. 다른 제공자나 ANTHROPIC_BASE_URL이 Anthropic API가 아닌 곳을 가리키면 다음 출처부터 본다
2. MDM·OS 정책(macOS plist, HKLM)
3. 관리 파일(managed-settings.d/*.json과 managed-settings.json을 합친 것)
4. HKCU 레지스트리. 위에 관리자 문서가 있거나 호스트가 넘긴 parent settings가 제한 키를 주면 쓰지 않는다(사용자가 쓸 수 있는 위치라 "관리자 출처"가 아니다)

1. 원격

   서버 관리·gateway

2. MDM·OS 정책

   plist·HKLM

3. 관리 파일

   managed-settings.json + .d

4. HKCU 레지스트리

   위에 관리자 문서가 없고 parent settings가 제한 키를 주지 않을 때만

합치는 방식 두 가지 (managedSourcesBehavior): Claude Code managed settings 배포

• "first-wins"(기본): 정책 키를 하나라도 가진 가장 높은 출처만 쓰고 나머지는 합치지 않고 무시한다. 건너뛴 출처에 경고를 띄우지 않는다. /status가 쓴 출처와 건너뛴 출처를 보여 준다.
• "merge"(v2.1.242 이상): 정책 키가 있는 모든 관리자 출처를 키 종류별로 합친다. 대부분의 키는 높은 출처 값, 목록은 합집합, 잠금은 가장 엄격한 값. 가장 높은 출처에 두어야 하고, 낮은 출처가 스스로 merge를 켤 수 없다. 원본 경고: 낮은 출처의 permissions.allow 규칙과 훅 같은 목록 항목이 정책에 더해지므로, 가장 높은 출처 아래의 모든 출처가 관리자 통제 아래 있을 때만 켠다. HKCU는 어느 출처와도 합쳐지지 않는다.
  • (2026-10-21 기준) settings reference의 키 종류별 합치기 표: 목록(permissions.allow, sandbox.network.allowedDomains 등)은 모든 출처 항목을 합치고, 잠금(allowManagedPermissionRulesOnly, permissions.disableBypassPermissionsMode 등)은 어느 출처든 가장 엄격한 값을 쓰며, 제한 허용 목록(availableModels, allowedMcpServers, allowedProviders, strictKnownMarketplaces, allowedChannelPlugins, fallbackModel 체인)은 가장 높은 출처의 목록을 통째로 쓰고 낮은 출처 항목을 더하지 않는다. apiKeyHelper 같은 자격 증명 helper, forceLoginOrgUUID, modelPicker, policyHelper, permissions.defaultMode는 가장 높은 출처에서만 읽고, managedMcpServers는 이름별로 합치며, env는 두 방식 모두 변수별로 합친다. 그 밖의 키는 가장 높은 출처 값. Claude Code 설정 키 전체 레퍼런스

first-wins에서도 모든 관리자 출처에서 읽는 교차 출처 키가 있다. 예: 샌드박스 잠금(sandbox.network.allowManagedDomainsOnly, sandbox.filesystem.allowManagedReadPathsOnly, 어느 출처든 true면 켜짐), allowManagedMcpServersOnly, deniedMcpServers, maxEffortLevel(가장 낮은 상한), env(변수별로 가장 높은 출처 값, v2.1.223 이상), forceRemoteSettingsRefresh. Claude Code managed settings 배포

임베딩 호스트의 parent settings: Claude Desktop, IDE 확장, Agent SDK 앱처럼 Claude Code를 띄우는 호스트는 SDK managedSettings 옵션으로 자기 managed settings를 넘길 수 있다. 관리자 출처가 있으면 기본으로 무시하고, 가장 높은 관리 출처에 parentSettingsBehavior: "merge"를 두면 호스트 값 중 제한하는 값만 남긴다. 단 policyHelper는 이 키와 상관없이 parent 합치기를 끌 수 있다(원본: "A policyHelper can turn parent merging off regardless of this key"). 원본 경고: "unless you also set the allowManaged*Only locks, the host's permission allow rules and sandbox allowlists still apply"(merge를 켜도 allowManaged*Only 잠금이 없으면 호스트의 허용 규칙과 샌드박스 허용 목록은 그대로 적용된다). Claude Code managed settings 배포 권한 문서(2026-10-21)도 같은 내용을 적는다: 임베딩 호스트는 SDK managedSettings 옵션으로 관리 정책을 더할 수 있고, 관리자가 allowManaged*Only 잠금을 걸지 않으면 권한 allow 규칙도 포함된다. Claude Code 권한 설정

관리 출처에서만 읽는 키 (일부, 2026-10-18 기준)#

user·project 설정 파일에 두면 효과가 없는 키다. 대부분은 잠금이다: 잠금이 다스리는 값(권한 규칙, sandbox.network.allowedDomains 등)은 어느 레벨에서나 쓸 수 있는 보통 키이고, 잠금은 managed 값만 존중하라고 한다. Claude Code managed settings 배포

전체 목록은 원본 표와 settings reference의 Scope 열을 본다. Claude Code managed settings 배포

settings reference(2026-10-21)에서 Scope가 Managed인 키 중 위 표에 없는 것(일부): deniedModels·availableModelsMatch(모델 잠금, v2.1.283 이상, 다른 파일에 두면 경고와 함께 무시), allowedProviders(쓸 수 있는 API 제공자, v2.1.285 이상), requiredMinimumVersion·requiredMaximumVersion(범위 밖 버전은 시작 때 종료, v2.1.163 이상, 다른 곳에 두면 경고 없이 무시), modelPricing(계약 단가로 비용 표시), managedMcpServers(사용자가 지우지 못하는 원격 MCP 서버, v2.1.259 이상), claudeMd(파일 없이 조직 CLAUDE.md), sandbox.filesystem.allowManagedReadPathsOnly, disableCommandPluginSources. 반대로 disableAutoMode와 permissions.disableBypassPermissionsMode는 Scope가 Any file이라 managed 전용이 아니다. managed에 두면 사용자가 덮어쓰지 못하는 것이다. 키별 타입·기본값은 Claude Code 설정 키 레퍼런스. Claude Code 설정 키 전체 레퍼런스

잘못된 값의 처리 (2026-10-18 기준)#

• 관리 파일·드롭인 파일·MDM plist·HKLM 값이 있는데 JSON 객체로 파싱되지 않으면 다른 관리자 출처가 정상이어도 Claude Code가 시작을 거부하고 출처를 밝힌 오류를 낸다. 파일이 없거나 빈 파일({}로 침), HKCU의 잘못된 값은 시작을 막지 않는다. Claude Code managed settings 배포
• 읽기 실패: 관리 파일·드롭인·MDM 프로파일·HKLM 값이 있는데 읽을 수 없고 정책을 주는 다른 관리자 출처도 없으면, OS가 읽기를 거부한 경우(root 전용 파일 등) 모든 세션이 그 출처의 정책 없이 시작하고 /status·claude doctor에 기록만 남는다. I/O 오류 같은 다른 실패면 모든 세션이 시작 때 종료한다. Claude Code managed settings 배포
• 제한 값이 하나뿐인 최상위 키(예: allowManagedPermissionRulesOnly, disableAutoMode, skipDangerousModePermissionPrompt)를 읽을 수 없으면 그 제한 값으로 읽는다(fail closed, v2.1.282 이상). 예외: null은 키를 지우고, 잘못된 disableAllHooks는 경고와 함께 버린다(true로 강제하면 조직이 배포한 훅까지 내려가기 때문). Claude Code managed settings 배포
• 참고: 공식 훅 가이드는 정상 값의 disableAllHooks 범위를 이렇게 적는다. 설정 우선순위를 적용한 뒤의 값을 읽으므로 프로젝트 설정이 사용자 설정을 덮을 수 있고, managed settings에 있는 훅은 managed settings에도 disableAllHooks가 있지 않으면 계속 실행된다. Claude Code 훅 가이드 → 훅 공식 훅 레퍼런스는 한 번의 실행만 훅을 끄는 --settings '{"disableAllHooks": true}'(프로젝트·로컬 설정보다 우선)도 적고, 이것도 managed 훅은 끄지 못한다. ConfigChange 훅은 policy_settings 변경을 막지 못하고 기록만 할 수 있으며, 서버 관리 설정이 도착하거나 갱신될 때는 돌지 않는다. Claude Code 훅 레퍼런스
• permissions 블록은 필드별로 고친다. 그 안의 잠금(permissions.disableBypassPermissionsMode)은 제한 값으로 읽고, 잘못된 permissions.defaultMode는 default로 읽고, deny·ask 목록을 읽을 수 없으면 allow·additionalDirectories를 보류한다. Claude Code managed settings 배포
• 허용 목록 키 일부는 잘못되면 빈 목록으로 강제된다. 예: allowedMcpServers가 잘못되면 사용자가 추가한 MCP 서버가 들어오지 못하고, allowedProviders가 잘못되면 모든 API 제공자가 거부돼 Claude Code가 그 기기에서 시작하지 않는다. Claude Code managed settings 배포
• 차단 목록은 반대다. deniedMcpServers·deniedModels·blockedMarketplaces가 통째로 잘못되면 경고와 함께 버려진다(모든 대상을 막으면 정책이 이름 붙이지 않은 대상까지 막기 때문). deniedModels는 고칠 때까지 어떤 모델도 막지 않는다. 잘못된 sandbox.failIfUnavailable도 true로 읽지 않고 버린다. Claude Code managed settings 배포
• 열린 쪽(fail open) 예외: requiredMinimumVersion·requiredMaximumVersion의 잘못된 값은 버려진다. Claude Code managed settings 배포

서브에이전트에 닿는 managed 통제 (2026-10-18 기준)#

• managed settings 디렉터리 안 .claude/agents/에 서브에이전트 정의를 두면 조직 전체에 배포되고, 같은 이름의 --agents·프로젝트·사용자·플러그인 정의보다 우선한다. managed 서브에이전트에 omitClaudeMd를 두면 managed 정책 CLAUDE.md까지 빼고 시작한다. Claude Code 서브에이전트 → 서브에이전트 정의 파일 레퍼런스
• managed MCP 제한(Enterprise managed MCP, allowedMcpServers·deniedMcpServers)은 정의 방식과 상관없이 모든 서브에이전트의 frontmatter 서버에 적용된다. 조직의 availableModels는 서브에이전트의 호출별·frontmatter·환경 변수 모델 값에도 적용돼 막힌 값을 다른 모델로 바꾼다. managed 정책의 훅은 서브에이전트 안에서도 돈다. Claude Code 서브에이전트
• managed 정의 파일의 인라인 MCP 서버는 폴더 신뢰 확인 없이 로드된다. Claude Code 서브에이전트

관련#

• 배포·확인·문제 해결 절차: Claude Code managed settings 배포·점검
• 권한 모드·규칙을 managed settings로 통제하는 키와 고객 질문별 근거: Claude Code 관리자 권한 통제
• 조직용 출력 스타일: managed settings 디렉터리 안의 .claude/output-styles에 둔다(2026-10-18 기준). Claude Code 출력 스타일 → Claude Code 출력 스타일 설정·만들기
• 네 설정 파일과 전체 우선순위, 예외 표, 클라우드 세션에 닿는 설정: Claude Code 설정 파일
• 블로그 Steering Claude Code가 managed settings에 대해 한 주장과 공식 문서의 확인 범위 대조: Claude Code 확장 기능 고르기, 권한 모드