서버 관리 설정 구성

​

요구사항

• Claude for Teams 또는 Claude for Enterprise 플랜
• Claude 조직에서 구성을 보고 편집할 수 있는 Owner 또는 Primary Owner 역할
• api.anthropic.com에 대한 네트워크 액세스

​

서버 관리 설정과 엔드포인트 관리 설정 중 선택

​

서버 관리 설정 구성

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

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "/usr/local/bin/audit-edit.sh" }
        ]
      }
    ]
  }
}

​

설정 전달 확인

• 전달된 설정이 로드됨
• 조직에 서버 관리 설정이 구성되지 않음
• 가져오기 실패, 원인 및 캐시된 정책이 여전히 적용되는지 여부
• Claude Code가 가져오기를 건너뜀, 이유 포함. 플랫폼 가용성에서 건너뛰는 공급자 및 구성을 참조하십시오

​

액세스 제어

• 주 소유자
• 소유자

​

관리 전용 설정

​

현재 제한사항

• 설정은 조직의 모든 사용자에게 균일하게 적용됩니다. 그룹별 구성은 아직 지원되지 않습니다.
• managed-mcp.json 파일은 서버 관리 설정을 통해 배포할 수 없습니다. 대신 allowedMcpServers 및 deniedMcpServers 정책 키를 배포하십시오. Claude Code v2.1.259 이상에서는 managedMcpServers를 통해 원격 서버를 제공할 수도 있으며, 이는 http 및 sse 서버만 허용하고 파일이 하는 방식으로 독점적 제어를 하지 않습니다. Claude Code는 시스템 경로에 배포된 managed-mcp.json을 관리 설정 계층과 별도로 읽으므로, 서버 관리 설정이 적용 중일 때도 파일이 여전히 적용됩니다.
• OS 수준 정책 소스로 제한된 설정(예: policyHelper 및 wslInheritsWindowsSettings)은 적용되지 않습니다. 대신 MDM 또는 시스템 managed-settings.json 파일을 통해 배포하십시오. 그렇게 배포된 policyHelper는 관리 계층 내 우선순위에서 선택된 소스가 해당 소스일 때만 실행됩니다.

​

설정 전달

​

설정 우선순위

​

관리 소스 전체의 키별 예외

• 교차 소스 잠금 키: 샌드박스 허용 목록 잠금과 같은 작은 키 집합으로, 관리 설정 페이지에 나열되어 있습니다. Claude Code는 관리자 제어 관리 소스가 이를 설정할 때 이를 준수합니다. 사용자 쓰기 가능 HKCU 레지스트리 계층은 제외됩니다. policyHelper가 관리 설정을 제공할 때, 그 출력은 이러한 확인이 읽는 유일한 소스입니다. forceRemoteSettingsRefresh는 제외되며, Claude Code는 시작 시 관리 소스에서 직접 읽습니다.
• env 블록: 자격 증명 키와 쌍을 이루는 원격 분석 단위 및 라우팅 변수를 제외하고, 아래에서 다루는 것처럼 관리자 제어 소스 전체에서 키별로 병합됩니다. 각 환경 변수에 대해 이를 정의하는 최우선 소스가 우승하며, 낮은 관리 소스는 높은 소스가 설정하지 않은 변수를 채웁니다. 따라서 엔드포인트 관리 env 항목은 서버 관리 구성이 해당 변수를 설정하지 않을 때마다 적용되거나, 해당 변수에 대한 캐시된 서버 값이 서버 확인 대기 중일 때 적용됩니다. Claude Code v2.1.223 이상이 필요합니다. v2.1.223 이전에는 Claude Code가 선택된 소스의 전체 env 블록만 적용합니다.
  • 원격 분석 단위: OTEL_EXPORTER_OTLP_* 내보내기 키, OTEL_LOG_* 콘텐츠 캡처 토글, OTEL_LOGS_EXPORTER, 그리고 베타 추적 변수 ENABLE_BETA_TRACING_DETAILED 및 BETA_TRACING_ENDPOINT는 이들 중 하나를 설정하는 최우선 소스를 단위로 따릅니다. otelHeadersHelper 자격 증명 키를 전달하는 소스는 단위도 청구하지만, 선택된 소스일 때만 이러한 변수를 배치합니다. 선택되지 않았지만 키를 전달하는 소스는 이들 중 어느 것도 기여하지 않으며 여전히 낮은 소스가 이들을 채우는 것을 차단합니다. 어느 쪽이든 한 소스의 내보내기 엔드포인트는 다른 소스의 자격 증명과 쌍을 이룰 수 없습니다.
  • 자격 증명 쌍 라우팅: 라우팅 변수를 선택된 소스 전용 자격 증명 키(예: apiKeyHelper 또는 otelHeadersHelper)와 쌍을 이루는 소스는 해당 슬롯을 우승할 때만 이러한 라우팅 변수를 기여합니다.
• 게이트웨이 로그인 키: Claude Code는 forceLoginGatewayUrl 또는 forceLoginMethod의 "gateway" 값을 서버 관리 설정에서 절대 읽지 않으므로, 서버 관리 설정을 선택해도 게이트웨이 로그인을 제공하지 않으며 MDM 정책 또는 관리 설정 파일에 설정된 것을 숨기지 않습니다. managedSourcesBehavior 항목은 머신의 어느 관리 소스가 이들을 제공하는지 말합니다.

​

가져오기 및 캐싱 동작

• 개발자가 시작 시(예: 첫 실행 또는 /logout 후)에 로그인할 때, Claude Code는 세션을 열기 전에 가져오기를 최대 5초 동안 기다립니다. 정책이 시간 내에 도착하면 Claude Code는 첫 번째 화면부터 이를 적용하고 companyAnnouncements를 표시합니다. 페이로드가 보안 승인이 필요하면 Claude Code는 대기를 종료하고 개발자가 승인한 후 페이로드를 적용합니다.
• 다른 모든 시작에서, 그리고 5초 대기가 만료되면 Claude Code는 가져오기가 계속되는 동안 세션을 열므로 설정이 로드되고 제한이 적용되기 전에 짧은 시간이 지나갑니다.
• 가져오기가 실패하면 Claude Code는 서버 관리 설정 없이 계속되고 대화형 세션에서 원격 정책이 적용되지 않음을 경고합니다. 엔드포인트 관리 설정은 여전히 적용됩니다. 관리 소스가 forceRemoteSettingsRefresh를 설정하면 Claude Code는 대신 종료됩니다.

• 캐시된 설정은 시작 시 즉시 적용됩니다. 캐시된 modelPricing 및 managedMcpServers 값과 Claude Code가 서버가 페이로드를 확인할 때까지 보류하는 환경 변수는 제외됩니다.
• 캐시된 modelPricing은 세션의 가져오기가 페이로드를 확인할 때까지 적용되지 않습니다. 그때까지 개발자가 /usage에서 보는 비용 수치와 상태 줄은 정가입니다.
• 캐시된 managedMcpServers 블록은 세션의 가져오기가 페이로드를 확인할 때까지 적용되지 않습니다. Claude Code는 MCP 서버를 연결하기 전에 해당 가져오기를 최대 30초 동안 기다립니다. 가져오기가 실패하거나 시간 초과되면 세션은 조직의 서버 없이 시작되고, /status는 그렇게 표시하며, 나중에 가져오기가 이들을 확인하면 연결됩니다. 첫 시작을 포함한 전체 동작은 제공된 서버가 연결될 때를 참조하십시오. Claude Code v2.1.259 이상이 필요합니다.
• Claude Code는 백그라운드에서 새로운 설정을 가져옵니다.
• 캐시된 설정은 네트워크 장애를 통해 유지됩니다. 시작 가져오기가 실패하면 Claude Code는 대화형 세션에서 캐시된 정책이 적용 중임을 경고합니다.
• 가져오기가 성공할 때까지 시작 시 보류된 값은 보류된 상태로 유지됩니다.

• HTTPS_PROXY, NODE_EXTRA_CA_CERTS, 그리고 mTLS 클라이언트 인증서 변수 CLAUDE_CODE_CLIENT_CERT 및 CLAUDE_CODE_CLIENT_KEY와 같은 프록시 및 TLS 구성
• ANTHROPIC_BASE_URL, CLAUDE_CODE_USE_BEDROCK 및 CLAUDE_CODE_USE_VERTEX와 같은 공급자 선택 변수를 포함한 API 라우팅 및 공급자 선택, 그리고 ANTHROPIC_BEDROCK_BASE_URL과 같은 공급자 엔드포인트 URL
• ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, 그리고 CLAUDE_CODE_OAUTH_TOKEN과 같은 인증 자격 증명
• 구성 디렉토리 선택기 CLAUDE_CONFIG_DIR
• Claude Code v2.1.223 이상의 자격 증명 소스 및 구성 디렉토리 선택기: ANTHROPIC_FEDERATION_RULE_ID 및 ANTHROPIC_IDENTITY_TOKEN과 같은 Workload Identity Federation 변수, 프로필 및 구성 디렉토리 선택기 ANTHROPIC_PROFILE 및 ANTHROPIC_CONFIG_DIR, 그리고 운영 체제 디렉토리 변수 HOME, XDG_CONFIG_HOME, APPDATA, 그리고 USERPROFILE

​

전달된 설정의 잘못된 항목

• ~/.claude/remote-settings.json의 캐시는 잘못된 항목이 제거된 구제된 페이로드를 저장합니다. 잘못된 cleanupPeriodDays 및 desktopSessionCleanupPeriodDays 값은 제외되며, 이는 캐시된 복사본에 머물러 있고 절대 적용되지 않습니다.
• 페이로드의 어떤 필드도 구제할 수 없고 페이로드가 이러한 보존 키만 아닌 경우, Claude Code는 페이로드를 거부하고, 마지막으로 수락된 캐시된 설정을 유지하며, 디버그 로그에 Remote settings: Settings validation failed - no fields could be salvaged를 씁니다. forceRemoteSettingsRefresh가 설정되면 CLI는 대신 종료됩니다.
• 보안 승인 대화는 구제된 페이로드를 평가하므로 제거된 잘못된 항목은 승인을 위해 표시되지 않으며 실행되지 않습니다.

​

강제 실패 폐쇄 시작

{
  "forceRemoteSettingsRefresh": true
}

​

보안 승인 대화

• 셸 명령 설정: apiKeyHelper, statusLine, 그리고 otelHeadersHelper와 같은 셸 명령을 실행하는 설정
• 샌드박스 바이너리 설정: sandbox.bwrapPath, sandbox.socatPath, 그리고 sandbox.ripgrep. 이러한 각 설정은 실행 파일을 가리키며 Claude Code는 해당 실행 파일을 실행합니다.
• 샌드박스 네트워크 및 격리 설정: 샌드박스 설정으로 샌드박스 프록시가 트래픽을 읽고, 재라우팅하거나, 인증하도록 하거나, 샌드박스의 격리를 약화시킵니다. sandbox.network.tlsTerminate, sandbox.network.httpProxyPort, sandbox.network.socksProxyPort, sandbox.credentials, sandbox.allowAppleEvents, sandbox.enableWeakerNestedSandbox, sandbox.enableWeakerNetworkIsolation, sandbox.filesystem.disabled, sandbox.network.allowAllUnixSockets, sandbox.network.allowUnixSockets, 그리고 sandbox.network.allowMachLookup. deny 규칙만 포함하는 sandbox.credentials 블록은 승인이 필요하지 않습니다. 프록시에 자격 증명을 제공하지 않고 샌드박스를 제한하기 때문입니다. v2.1.251 이전에는 Claude Code가 이러한 설정을 승인 없이 적용했습니다.
• 사용자 정의 환경 변수: 프록시 및 기본 URL 변수와 같은 사용자의 승인이 필요한 전달된 env 변수. 환경 변수 및 승인 대화를 참조하십시오.
• Hook 구성: 모든 hook 정의

​

승인 메모리

• /login 또는 claude auth login으로 저장된 claude.ai 로그인, 또는 키 없는 콘솔 로그인: 조직당 하나의 승인으로, 가장 최근에 승인한 계정이 보유합니다.
• Claude 앱 게이트웨이 로그인: 게이트웨이당 하나의 승인입니다. 같은 게이트웨이에서 로그아웃했다가 다시 로그인하면 승인이 필요한 설정이 변경되지 않는 동안 Claude Code는 대화를 다시 표시하지 않습니다. Claude Code는 이러한 설정이 변경될 때, 다른 게이트웨이에 로그인할 때, 그리고 같은 게이트웨이에 대해 새 인증서를 수락할 때 다시 표시합니다. Claude Code는 일반 HTTP를 통해 도달한 루프백 개발 게이트웨이에 대해 승인을 저장하지 않으므로 각 로그인 후 대화가 다시 나타납니다.
• API 키 또는 CLAUDE_CODE_OAUTH_TOKEN과 같은 다른 자격 증명: 전달된 설정에 대한 하나의 승인으로, 해당 구성 디렉토리의 설정 캐시된 복사본과 함께 유지됩니다. Claude Code는 승인이 필요한 설정이 변경될 때, 그리고 /logout 또는 claude auth logout을 실행한 후(둘 다 캐시된 복사본을 삭제함) 대화를 다시 표시합니다.

• 로그아웃했다가 다시 로그인하거나 다른 조직으로 전환했다가 나중에 돌아오면 이러한 설정이 변경되지 않는 동안 Claude Code는 대화를 다시 표시하지 않습니다. 다른 계정이 같은 구성 디렉토리의 해당 조직에 대해 승인한 경우는 제외됩니다.
• 다른 계정으로 같은 조직에 로그인하면 설정이 변경되지 않았더라도 Claude Code는 대화를 다시 표시합니다. 해당 계정의 승인이 이전 승인을 대체하므로 다시 전환하면 Claude Code는 한 번 더 대화를 표시합니다.

• 대화를 표시할 수 없는 대화형 세션: Claude Code는 전달된 설정을 적용하지 않고 마지막으로 승인된 설정을 유지합니다. 대화는 대화를 표시할 수 있는 다음 세션에 나타납니다. Claude Code v2.1.211 이상이 필요합니다.
• claude install 또는 claude update: Claude Code는 두 명령 중 어느 것 중에도 대화를 표시하지 않습니다. 명령은 마지막으로 승인된 설정으로 실행되고 대화는 다음 대화형 세션에 나타납니다. Claude Code가 시작 시 설정 가져오기를 기다리는 경우(예: forceRemoteSettingsRefresh가 설정되었거나 Claude 앱 게이트웨이 배포에서), 대신 명령 중에 대화를 표시하고 파이프에서 설치 실행이 실패합니다. Raw mode is not supported during install을 참조하십시오. v2.1.246 이전에는 Claude Code가 이러한 명령 중에도 대화를 표시하려고 시도했습니다.
• 오류가 응답 전에 대화를 닫음: Claude Code는 전달된 설정을 적용하지 않고 마지막으로 승인된 설정을 유지합니다. 대화를 표시할 수 있는 다음 세션에 다시 표시합니다.
• 비대화형 실행(예: claude -p 또는 Agent SDK 세션): Claude Code는 대화를 표시할 수 없으므로 전달된 설정이 승인을 요구할 때 해당 실행에만 이를 적용합니다. 로컬 캐시에 승인된 것으로 기록하거나 쓰지 않으며, 다음 대화형 세션은 대화를 표시합니다. 사용자가 대화형 세션에서 승인할 때까지 각 비대화형 실행은 시작 시 설정을 다시 가져옵니다. v2.1.207 이전에는 비대화형 실행이 설정을 승인된 것으로 저장했으므로 나중에 대화형 세션은 이에 대한 대화를 절대 표시하지 않았습니다.

​

환경 변수 및 승인 대화

• 기능 및 명령 토글
• ANTHROPIC_MODEL, DISABLE_PROMPT_CACHING, 그리고 CLAUDE_CODE_EFFORT_LEVEL과 같은 모델 선택 및 동작 설정
• DISABLE_AUTO_COMPACT와 같은 컨텍스트 윈도우 및 압축 설정
• 터미널 UI 및 접근성 옵션
• 숫자 제한, 예산, 그리고 시간 초과

​

플랫폼 가용성

• Team 또는 Enterprise OAuth 로그인
• CLAUDE_CODE_OAUTH_TOKEN을 통해 제공되는 OAuth 토큰
• 직접 구성된 API 키
• Anthropic 프로필의 user_oauth Anthropic 프로필, 프로필이 Anthropic API 이외의 base_url을 설정하지 않는 한. Claude Code v2.1.257 이상이 필요합니다.

​

감사 로깅

​

보안 고려사항

​

참고 항목

• 모든 설정: 모든 설정 키
• 엔드포인트 관리 설정: IT에서 기기에 배포하는 관리 설정
• 인증: Claude Code에 대한 사용자 액세스 설정
• 보안: 보안 보호 및 모범 사례