조직용 Claude Code 관리자 설정
기준일: 2026-07-26 · CLI 기준 2.1.220
개요
조직 정책은 managed settings로 강제되며, 개발자 로컬 설정보다 우선합니다. 전달 경로는 Claude admin console, MDM, 또는 디스크 파일입니다. 이 설정은 Claude가 접근할 수 있는 도구, 명령, 서버, 네트워크 대상을 제어합니다.
SSO, SCIM, seat 배정은 Claude 계정 수준에서 구성합니다. Claude Enterprise Administrator Guide와 seat assignment 문서를 참고하세요.
| 결정 | 선택 내용 | 참고 |
|---|---|---|
| API provider 선택 | 인증 위치·과금 방식 | Authentication, Bedrock, Vertex AI, Foundry |
| 설정 전달 방식 | managed policy를 기기까지 전달하는 방법 | Server-managed settings, Settings files |
| 강제할 정책 | 허용 도구·명령·통합 | Permissions, Sandboxing |
| 사용량 가시성 | 지출·도입 추적 | Analytics, Monitoring, Costs |
| 데이터 처리 | 보존·컴플라이언스 | Data usage, Security |
핵심 개념
- Managed settings: 로컬 설정보다 우선하는 조직 정책
- 설정 소스 우선순위: server-managed → plist/registry → file-based → HKCU
- 제어 표면: 권한, 샌드박스, MCP, 플러그인 마켓, 훅, 로그인, 모델 제한
- 사용량 가시성: OTel, Analytics 대시보드, 비용 API, spend controls
상세
API provider 선택
Claude Code는 여러 API provider로 Claude에 연결합니다. 선택에 따라 과금, 인증, 컴플라이언스 포스처, 사용 가능한 기능이 달라집니다.
| Provider | 선택 시점 |
|---|---|
| Claude for Teams / Enterprise | Claude Code와 claude.ai를 좌석 구독으로 통합. 기본 권장 |
| Claude Console | API 중심 또는 pay-as-you-go |
| Amazon Bedrock | 기존 AWS 컴플라이언스·과금 상속 |
| Google Cloud Agent Platform | 기존 GCP 컴플라이언스·과금 상속 |
| Microsoft Foundry | 기존 Azure 컴플라이언스·과금 상속 |
일부 기능은 claude.ai 계정이 필요합니다. Claude Code on the web, Routines, Code Review, Remote Control, Chrome extension은 Console API 키나 클라우드 provider 자격증명만으로는 사용할 수 없습니다. Bedrock/Vertex/Foundry 배포 시 Teams/Enterprise seat 필요 여부를 함께 계획하세요.
프록시·방화벽 요구사항은 provider와 무관하게 Network configuration을 따릅니다. 다중 provider 앞단 단일 엔드포인트·요청 로깅이 필요하면 LLM gateway를 검토합니다.
설정이 기기에 도달하는 방식
Claude Code는 아래 네 소스를 우선순위 순으로 검사하고, non-empty 설정을 반환한 첫 소스를 적용합니다. policyHelper가 구성되면 네 소스 모두를 선점합니다.
| 메커니즘 | 전달 | 우선순위 | 플랫폼 |
|---|---|---|---|
| Server-managed | claude.ai admin console, 또는 gateway 로그인용 self-hosted Claude apps gateway | Highest | All |
| plist / registry | macOS: com.anthropic.claudecode plist / Windows: HKLM\SOFTWARE\Policies\ClaudeCode |
High | macOS, Windows |
| File-based managed | macOS: /Library/Application Support/ClaudeCode/managed-settings.json · Linux/WSL: /etc/claude-code/managed-settings.json · Windows: C:\Program Files\ClaudeCode\managed-settings.json |
Medium | All |
| Windows user registry | HKCU\SOFTWARE\Policies\ClaudeCode |
Lowest | Windows only |
Server-managed settings는 인증 시 전달되고 활성 세션 중 시간당 갱신됩니다. claude.ai admin console 전달은 Teams/Enterprise 플랜이 필요합니다. 클라우드 provider 배포는 Claude apps gateway로 원격 전달을 얻거나 file/OS 메커니즘을 사용합니다.
provider를 혼합하면 claude.ai 사용자용 server-managed + 기타 사용자용 file/plist/registry 폴백을 함께 구성합니다.
plist와 HKLM은 admin 권한이 필요해 변조에 강합니다. HKCU는 elevation 없이 쓰이므로 강제 채널이 아니라 편의 기본값으로 취급하세요.
기본 WSL은 /etc/claude-code Linux 경로만 읽습니다. 동일 머신의 Windows registry·C:\Program Files\ClaudeCode 정책을 WSL에 확장하려면 admin-only Windows 소스에 wslInheritsWindowsSettings: true를 설정합니다.
Managed 값은 user/project 설정보다 우선합니다. permissions.allow/deny 같은 배열은 모든 소스 항목을 병합해 개발자가 확장만 가능하고 제거는 불가합니다. fallbackModel과 availableModels는 예외로 managed 값이 하위 레이어를 대체합니다.
Claude Code Desktop의 WSL 세션
Windows에서 Desktop이 WSL 2 안에서 Code 세션을 실행할 수 있습니다. 세션 프로세스는 distro 내부이므로 Windows-only 소스는 wslInheritsWindowsSettings: true 없이는 도달하지 않습니다.
managed settings가 있는 기기에서는 Desktop WSL 세션이 기본 비활성입니다. 활성화 시:
- HKLM 또는
C:\Program Files\ClaudeCode로wslInheritsWindowsSettings: true배포 - WSL 세션에서
/status→Setting sources에Enterprise managed settings와(HKLM)또는(file)확인
WSL 2 utility VM 내부 프로세스는 Windows endpoint detection에 보이지 않습니다. CrowdStrike Falcon 사용 시 WSL 문서 요구 제외 2개와 함께 Linux Falcon sensor를 활성화하세요. OpenTelemetry tool-execution telemetry는 WSL/native 동일하게 방출됩니다.
강제할 정책 결정
| 제어 | 역할 | 주요 설정 키 |
|---|---|---|
| Permission rules | 도구·명령 allow/ask/deny | permissions.allow, permissions.deny |
| Permission lockdown | managed 규칙만 적용, --dangerously-skip-permissions 비활성 |
allowManagedPermissionRulesOnly, permissions.disableBypassPermissionsMode |
| Sandboxing | OS 수준 파일시스템·네트워크 격리 + domain allowlist | sandbox.enabled, sandbox.network.allowedDomains |
| Managed policy CLAUDE.md | 모든 세션에 조직 지침 로드, 제외 불가 | managed policy 경로 파일 |
| MCP server control | 추가/연결 가능 MCP 제한 또는 고정 세트 배포 | allowedMcpServers, deniedMcpServers, allowManagedMcpServersOnly, managed-mcp.json |
| Plugin marketplace control | 마켓 소스 제한, sideload 플래그 거부, 제안 allowlist | strictKnownMarketplaces, blockedMarketplaces, disableSideloadFlags, pluginSuggestionMarketplaces |
| Customization lockdown | user/project의 skills/agents/hooks/MCP 차단 | strictPluginOnlyCustomization |
| Hook restrictions | managed 훅만 로드, HTTP hook URL 제한 | allowManagedHooksOnly, allowedHttpHookUrls |
| Login enforcement | 로그인 방법·조직 제한 (v2.1.212+ 여러 표면) | forceLoginMethod, forceLoginOrgUUID |
| Disable agent view | claude agents, --bg, /background, on-demand supervisor 끔 |
disableAgentView |
| Corporate launcher | background 프로세스를 필수 런처로 prefix | processWrapper |
| Model restrictions | 피커 모델 필터·기본 모델 강제 | availableModels, enforceAvailableModels |
| Version floor / required range | 최소 버전 또는 허용 범위 밖 시작 거부 | minimumVersion, requiredMinimumVersion, requiredMaximumVersion |
claude.ai 또는 Anthropic API로 인증하는 조직은 Enterprise 플랜의 organization model restrictions, default model, effort limits로 서버 측 모델 거버넌스도 가능합니다. Bedrock/Vertex/Foundry/Claude Platform on AWS 세션에는 이 서버 측 제어가 도달하지 않으므로 managed settings의 availableModels/model을 사용합니다.
Claude Code on the web은 Cloud environments admin 표면에서 organization-shared environments(네트워크 수준, env, setup script, 기본 환경)를 관리합니다.
권한 규칙과 샌드박스는 계층이 다릅니다. WebFetch를 deny해도 Bash가 허용이면 curl/wget이 우회할 수 있습니다. 샌드박스의 OS 수준 domain allowlist가 그 간극을 막습니다.
사용량 가시성
| 기능 | 내용 | 가용성 |
|---|---|---|
| Usage monitoring | 세션·도구·토큰 OpenTelemetry export | 모든 provider |
| Analytics dashboard | Teams/Enterprise 도입·기여 지표; Console per-user 사용·지출 | Teams/Enterprise, Console |
| Programmatic reporting | per-user 사용·비용 API | Enterprise Analytics API, Claude Code Analytics API |
| Spend controls | 지출·rate limit | Teams/Enterprise admin, Console workspace, 클라우드 budget 또는 gateway spend limits |
Teams/Enterprise의 per-user 사용·지출 숫자는 analytics 대시보드가 아니라 spend report에서 옵니다. 클라우드 provider는 AWS Cost Explorer, GCP Billing, Azure Cost Management를 사용합니다.
데이터 처리 검토
Team, Enterprise, Claude API, 클라우드 provider 플랜에서 Anthropic은 코드·프롬프트로 모델을 학습하지 않습니다. 보존·컴플라이언스는 API provider가 결정합니다.
| 주제 | 요점 |
|---|---|
| Data usage policy | 수집 항목, 보존 기간, 학습 미사용 |
| Zero Data Retention (ZDR) | 요청 완료 후 저장 없음. Enterprise 적격 계정 |
| Security architecture | 네트워크, 암호화, 인증, 감사 추적 |
요청 단위 감사 로그·민도별 라우팅이 필요하면 self-hosted Claude apps gateway 또는 LLM gateway를 개발자와 provider 사이에 둡니다.
검증 및 온보딩
managed settings 구성 후 개발자가 Claude Code에서 /status를 실행합니다. Status 탭의 Setting sources에 Enterprise managed settings와 (remote)/(plist)/(HKLM)/(HKCU)/(file)이 표시되어야 합니다.
개발자 온보딩 자료:
- Quickstart, Common workflows
- Claude 101, Claude Code in Action (Anthropic Academy)
로그인 이슈 일반 조치: /logout → /login, claude update, 업데이트 후 터미널 재시작. "You haven't been added to your organization yet"는 seat에 Claude Code 접근이 없다는 뜻입니다.
체크리스트
- API provider와 과금·기능 격차를 확정했다
- managed settings 전달 메커니즘(server/plist/file)을 선택했다
- 권한·샌드박스·MCP·플러그인·훅·로그인·모델 제한 키를 정의했다
- WSL 사용 시
wslInheritsWindowsSettings와/status검증 계획을 세웠다 - 사용량 모니터링·spend control·데이터 정책(ZDR 포함)을 검토했다
- 개발자
/status로Enterprise managed settings소스를 확인했다