Claude Code managed settings 배포·점검

조직 관리자가 managed settings(용어 사전의 "managed settings·MDM")를 개발자 기기에 배포하고, 적용됐는지 확인하고, "정책이 안 먹는다"를 진단하는 절차다. 무엇을 강제할지(권한 모드·규칙 키)는 Claude Code 관리자 권한 통제에서 고른다.

준비물(필요한 것)#

1. 가장 빠른 길: 파일 하나 배포하기#

1단계. 파일을 쓴다. settings.json과 같은 JSON 모양으로 강제할 키만 담는다. 원본 예시(파일 읽기 둘 차단, bypass 모드 끄기, user·project·local 파일과 --allowedTools의 권한 규칙 무시): Claude Code managed settings 배포

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

2단계. 기기마다 시스템 디렉터리에 둔다. 기존에 기기에 파일을 까는 도구를 그대로 쓴다. Claude Code managed settings 배포

같은 디렉터리가 조직 CLAUDE.md(CLAUDE.md) 위치이기도 하다. Claude Code 메모리 → CLAUDE.md 작성·구성

3단계. 한 대에서 확인한다. Claude Code 안에서 /status를 실행해 Setting sources 줄에 Enterprise managed settings (file)이 보이는지 본다. 그다음 나머지 기기로 넓힌다. Claude Code managed settings 배포

2. 전달 방법 고르기 (2026-10-18 기준)#

근거: Claude Code managed settings 배포 (원본 표). Jamf·Iru·Intune·Group Policy 시작 템플릿은 anthropics/claude-code 저장소의 examples/mdm에 있다고 원본이 링크한다.

그룹별로 다른 정책: 파일·MDM 프로파일·claude.ai 콘솔은 닿는 모두에게 하나의 정책을 적용한다. 그룹마다 다르게 하려면 그룹마다 다른 파일·프로파일을 배포한다. claude.ai 콘솔은 아직 그룹을 대상으로 할 수 없고, 자체 호스팅 Claude apps gateway는 IdP 그룹별로 전달한다. Claude Code managed settings 배포

세션 종류별로 닿는 정책 (고객사 환경 점검 질문으로 쓴다): Claude Code managed settings 배포

• 개발자 기기의 터미널, VS Code·JetBrains 확장, 데스크톱 앱 Code 탭, Agent SDK 세션: 모든 출처를 읽는다. Agent SDK는 settingSources가 user·project·local을 빼도 managed settings를 로드한다.
• Anthropic 호스팅 클라우드 세션: 기기의 MDM·파일을 읽지 않으므로 서버 관리 설정으로만 정책이 간다. 자체 호스팅 환경은 러너 이미지의 관리 파일도 읽는다(기본은 서버 관리 설정이 정책 키를 주지 않을 때만).
• Claude Tag 세션: 클라우드에서 돌지만 서버 관리 설정을 받지 않는다. 자체 호스팅 환경이면 러너 이미지의 관리 파일은 읽는다.
• Cowork 세션: claude.ai 관리 콘솔의 서버 관리 설정을 가져오지 않는다(Team·Enterprise 계정으로 로그인해도). 사용자 기기에서 돌면 기기의 MDM·관리 파일을 읽고, requireCoworkFullVmSandbox로 전체 VM 샌드박스에서 돌면 기기 정책이 없고, 원격 Cowork 세션(Anthropic 관리 VM)도 읽을 기기 정책이 없다. → Claude Cowork

Settings 문서(2026-10-21)도 클라우드 세션에는 기기의 파일·MDM이 닿지 않고 서버 관리 설정이 닿는다는 점(어떤 클라우드 세션이 받는지는 surface coverage 표로 넘김), 자체 호스팅 러너 이미지 파일이 언제 적용되는지는 관리 출처 합치기 규칙을 따른다는 점, 기기에서 도는 Cowork 세션이 claude.ai 콘솔 설정을 가져오지 않고 requireCoworkFullVmSandbox가 없으면 기기 정책을 읽는다는 점을 확인한다. Claude Code 설정 파일과 우선순위

변경이 반영되는 때: 대부분은 위 표의 주기로 재시작 없이 실행 중 세션에 닿는다. forceRemoteSettingsRefresh, requiredMinimumVersion, 일부 키는 다음 세션 시작 때 적용된다. 서버 관리로 바꾼 훅이나 env 변수처럼 승인이 필요한 설정은 대화형 세션에서 개발자가 대화상자를 수락할 때까지 기다리고, IDE 확장이나 Agent SDK가 띄운 세션에서는 이번 실행에 바로 적용된다. 몇 주씩 열어 둔 세션은 배포를 늦게 따라올 수 있고, requiredMinimumVersion은 낡은 바이너리의 시작을 막지만 이미 도는 세션을 끝내지는 않는다. Claude Code managed settings 배포

3. 여러 팀이 정책을 나눠 가질 때#

공유 파일 하나를 함께 고치는 대신, 같은 시스템 디렉터리의 managed-settings.d/에 팀별 파일을 둔다. managed-settings.json을 먼저, 그다음 *.json을 알파벳 순으로 합치므로 10-telemetry.json, 20-security.json처럼 숫자 접두어로 순서를 정한다. 숨김 파일과 .json이 아닌 파일은 무시한다. Claude Code managed settings 배포

여러 전달 방법(서버·MDM·파일)을 한 기기에 함께 쓰는 경우는 다르다. 기본은 가장 높은 출처 하나만 쓰고 나머지는 무시한다. 모두 합치려면 managedSourcesBehavior: "merge"를 가장 높은 출처에 둔다(v2.1.242 이상). 낮은 출처의 허용 규칙·훅이 더해지므로 아래 출처가 모두 관리자 통제 아래 있을 때만 쓴다. → managed settings

4. "정책이 안 먹는다" 점검 순서#

4-0. 먼저 세션을 재시작한다. 관리 출처는 전달 방식별 주기로 실행 중인 세션에 닿으므로, 개발자 쪽에서는 재시작부터 하고 /status를 본다. /status가 관리자가 바꾼 출처와 다른 출처를 보여 주면 더 높은 관리 출처가 적용 중이다. 개발자 자신의 파일·--settings 값이 안 먹는 경우의 점검은 Claude Code 설정 바꾸기·확인·문제 해결. Claude Code 설정 파일과 우선순위

4-1. /status의 Setting sources 줄을 읽는다. 괄호 안이 선택된 출처다: (remote) 서버·gateway, (plist)·(HKLM) MDM·OS, (file)·(drop-ins)·(file + drop-ins) 파일, , merged로 끝나면 합친 출처들, (HKCU), (parent process) 임베딩 호스트, (helper) policyHelper. 출처가 있는데 선택되지 않았으면 Skipped sources 줄에 나온다(v2.1.242 이상). Claude Code managed settings 배포

• 줄이 없다: 정책 키를 가진 관리 출처를 찾지 못한 것이다. 파일이 OS 경로에 있는지, 제어 키(wslInheritsWindowsSettings, managedSourcesBehavior)만 있지 않고 정책 키가 들어 있는지 본다. 서버 관리로 배포했다면 claude doctor로 가져오기 결과를 본다.
• 다른 출처 이름이 나온다: 더 높은 출처가 있어 내 것이 무시됐다. Skipped sources에 내 출처가 있다.

4-2. claude doctor로 버려진 항목을 찾는다. 스키마 검증에 실패한 항목을 출처·필드와 함께 나열한다. 대화형 세션은 시작 때 대화상자로, -p 실행은 stderr로 요약을 보여 준다. Claude Code managed settings 배포

4-3. 시작이 안 되면 파싱 오류를 의심한다. 관리 파일·드롭인·MDM plist·HKLM 값이 JSON 객체로 파싱되지 않으면 Claude Code가 출처를 밝힌 오류와 함께 시작을 거부한다. 다른 출처가 정상이어도 그렇다. 읽기 자체가 안 되고 정책을 주는 다른 관리자 출처도 없는 경우: OS가 거부했으면(root 전용 파일 등) 그 출처 없이 시작하고 기록만 남기고, I/O 오류 같은 다른 실패면 관리자에게 연락하라는 메시지와 함께 종료한다. Claude Code managed settings 배포

4-4. 잘못 쓴 키는 엄격한 쪽으로 읽힐 수 있다. disableAutoMode 같은 제한 키나 허용 목록(allowedMcpServers, allowedProviders 등)이 잘못되면 가장 제한적인 값으로 강제될 수 있다. 제한 값이 하나뿐인 최상위 키는 그 제한 값으로 읽히고, 보고서가 그 키를 was present but invalid라고 알린다(v2.1.282 이상). 허용 목록 키는 키마다 대체 동작이 다르다. 예: 잘못된 allowedProviders는 빈 허용 목록으로 강제돼 모든 API 제공자가 거부되고 Claude Code가 그 기기에서 시작하지 않는다. 반대로 차단 목록(deniedMcpServers·deniedModels·blockedMarketplaces)이 통째로 잘못되면 경고와 함께 버려진다. 그중 deniedModels는 고칠 때까지 어떤 모델도 막지 않는다(원본: "blocks no models until it is fixed"). Claude Code managed settings 배포 → managed settings

4-5. Cowork에서 폴더 쓰기가 막히면 allowManagedPermissionRulesOnly를 의심한다. 이 키는 호스트가 넘긴 허용 규칙도 버리므로 Cowork가 연결 폴더에 준 사전 승인이 사라지고, Cowork는 확인 창을 띄울 수 없어 쓰기가 차단으로 보고된다. 원본 해법: 키는 유지하고 그 기기가 선택하는 관리 출처(MDM 관리 기기면 MDM 정책)에 폴더 허용 규칙을 넣는다. Claude Code managed settings 배포

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

(원본 예시. ~/CoworkProjects는 사용자가 연결하는 실제 폴더로 바꾼다.)

5. 조직 텔레메트리 끄기#

개인 셸 설정에 기대지 않고 모두에게 끄려면 managed settings env로 DISABLE_TELEMETRY를 보낸다. 값 1은 승인 대화상자 없이 적용된다. 끄면 그 개발자들의 조직 분석 대시보드용 사용 데이터와 기능 플래그 가져오기도 꺼진다. Claude Code managed settings 배포

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

됐는지 확인하는 법#

• /status의 Setting sources 줄: 파일로 배포했으면 Enterprise managed settings (file)이 보인다. 괄호 안이 Claude Code가 고른 출처다((remote), (plist)·(HKLM), (drop-ins) 등, 4-1). 줄이 없으면 정책 키를 가진 관리 출처를 찾지 못한 것이고, 다른 출처 이름이 나오면 더 높은 출처가 내 것을 덮은 것이다. Claude Code managed settings 배포
• Skipped sources 줄 (v2.1.242 이상): 기기에 있지만 선택되지 않은 출처를 보여 준다. 정책이 기기에 아예 안 닿은 것과, 닿았지만 더 높은 출처에 밀린 것을 가른다. Claude Code managed settings 배포
• claude doctor: 스키마 검증에서 버려진 항목을 출처·필드와 함께 보여 주고, 서버 관리로 배포했다면 가져오기 결과도 보여 준다(4-2). Claude Code managed settings 배포
• Claude Code가 아예 시작하지 않으면: 관리 파일이 JSON 객체로 파싱되지 않았을 수 있다. 출처를 밝힌 오류가 뜬다(4-3). Claude Code managed settings 배포

이 확인은 그 기기의 Claude Code 세션 기준이다. Anthropic 호스팅 클라우드 세션과 Claude Tag에는 기기 파일·MDM이 닿지 않으므로 기기의 /status로 확인한 것을 그 세션에 그대로 적용하지 않는다(2절). Claude Code managed settings 배포

언제 쓰고 언제 쓰지 않는가#

• 쓴다: 금융·공공 고객사에 Claude Code를 여러 대 배포할 때, 보안팀이 "정책이 실제로 걸렸는지 어떻게 확인하나"를 물을 때, 개발자가 "관리자 정책이 안 먹는다"고 할 때.
• 쓰지 않는다: 개발자 자신의 값을 어느 파일에 둘지는 이 절차가 아니라 Settings 문서가 다룬다고 원본은 안내한다(Claude Code 설정 파일, Claude Code 설정 파일과 우선순위). Anthropic 호스팅 클라우드 세션과 Claude Tag에는 기기 파일·MDM이 닿지 않으니 이 절차만으로 통제했다고 말하지 않는다. Claude Code managed settings 배포
• 한계를 함께 말한다: 로컬 관리자 권한이 있는 개발자는 관리 출처를 고칠 수 있고, managed settings는 Claude Code만 묶는다. → managed settings