엔터프라이즈 관리 설정

이 참조를 사용하여 Copilot의 엔터프라이즈 관리 설정을 이해하세요. managed-settings.json에서 대부분의 설정을 구성할 수 있습니다. 디바이스 관리가 필요한 설정은 아래에 나와 있습니다.

파일을 만드는 방법에 대한 지침은 엔터프라이즈 관리 설정 시작을 참조하세요.

지원되는 키

telemetry 지원은 하위 속성 및 하네스에 따라 다릅니다. 세분화된 캡처를 지원하는 클라이언트에 대해서는 캡처 컨트롤을 참조하세요.

구성 예

다음 예제에서는 관리되는 하나의 설정 파일에서 이러한 키를 보여 냅니다.

{
  "features": {
    "computerUse": false
  },
  "model": "auto",
  "autoTier": "intelligence",
  "permissions": {
    "disableBypassPermissionsMode": "disable",
    "deny": [
      "Shell(rm -rf *)",
      "Read(~/.ssh/**)",
      "Edit(//etc/**)",
      "Domain(*.unapproved.example)"
    ],
    "ask": [
      "Shell(git push *)",
      "Edit(/src/**)",
      "Domain(api.github.com)"
    ],
    "allow": [
      "Shell(npm test *)",
      "Read(/src/**)",
      "Domain(registry.npmjs.org)"
    ]
  },
  "enabledPlugins": {
    "my-plugin@agent-skills": true
  },
  "extraKnownMarketplaces": {
    "agent-skills": {
      "source": {
        "source": "github",
        "repo": "OWNER/REPO"
      },
      "autoUpdate": true
    }
  },
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "OWNER/REPO"
    }
  ],
  "telemetry": {
    "enabled": true,
    "endpoint": "https://otel-collector.example.com",
    "protocol": "http/protobuf",
    "capture": {
      "identity": true,
      "prompts": false,
      "responses": false,
      "toolArguments": false,
      "toolOutput": false,
      "policyDetail": false
    },
    "captureContent": false,
    "lockCaptureContent": true,
    "serviceName": "copilot",
    "resourceAttributes": {
      "deployment.environment": "production"
    },
    "headers": {
      "Authorization": "Bearer TOKEN"
    }
  },
  "remoteControl": {
    "mode": "requireSSO",
    "githubDotComOrganizations": ["ORG-NAME"]
  },
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverCommand": ["npx", "@playwright/mcp@latest"] },
    { "serverCommand": ["cmd", "/c", "uvx", "markitdown-mcp"] }
  ],
  "deniedMcpServers": [
    {
      "serverCommand": [
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/"
      ]
    }
  ],
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowBypass": false,
    "sandboxMcpServers": true,
    "sandboxLspServers": true
  }
}

features.computerUse

GitHub Copilot CLI 및 GitHub Copilot app에서 사용자가 컴퓨터 사용을 사용하도록 설정할 수 있는지 여부를 제어합니다. false 사용자가 컴퓨터 사용을 사용할 수 없도록 설정 features.computerUse 됩니다. 로컬 설정은 이 제한을 재정의할 수 없습니다. 사용자가 로컬 설정을 통해 컴퓨터 사용을 제어할 수 있도록 값을 true설정하거나 키를 생략합니다.

활성화된 플러그인

모든 엔터프라이즈 사용자에 대해 자동으로 설치되거나 차단되는 플러그 인을 정의합니다. 각 항목은 PLUGIN-NAME@MARKETPLACE-NAME를 키로 사용하는 형식이며, 불리언 값으로 true는 플러그인이 활성화되어 있어야 함을, false는 비활성화되어 있어야 함을 나타냅니다. 엔터프라이즈 관리 플러그 인 표준 정보을(를) 참조하세요.

extraKnownMarketplaces

사용자가 사용할 수 있는 추가 플러그 인 마켓플레이스를 정의합니다. 각 항목은 autoUpdate 속성과 선택적 source 부울 값을 포함하는 이름이 지정된 마켓플레이스 객체입니다.

true을(를) autoUpdate로 설정하여 클라이언트가 해당 마켓플레이스를 주기적으로 새로 고치고, 해당 마켓플레이스에서 제공되는 설치된 플러그인을 업데이트하도록 합니다. false 해당 마켓플레이스에 대해 자동 업데이트가 비활성화된 상태로 유지되도록 설정합니다. 생략 autoUpdate하면 클라이언트는 기존 기본 또는 사용자 구성 동작을 사용합니다.

관리되는 설정이 우선하기 때문에 사용자는 정의된 autoUpdate 값을 재정의할 수 없습니다. 이 설정은 해당 마켓플레이스에만 적용되며, 새로 고침 및 업데이트 작업 전에 strictKnownMarketplaces의 제한 사항은 계속 적용됩니다.

지원되는 원본 유형은 다음과 같습니다.

• "github" — repo 형식의 OWNER/REPO이 필요합니다. 선택 사항: ref(브랜치, 태그 또는 SHA) 및 path(하위 디렉터리)
• "git" — url 필요; ref 및 path 선택 사항
• "directory" — path 필요

엔터프라이즈 관리 플러그 인 표준 정보을(를) 참조하세요.

서버에서 관리되는 엔터프라이즈 팀 재정의의 경우 전체 마켓플레이스 맵을 overridable로 감싸세요.

{
  "extraKnownMarketplaces": {
    "overridable": {
      "enterprise-plugins": {
        "source": {
          "source": "github",
          "repo": "OWNER/REPO"
        }
      }
    }
  }
}

그런 다음 팀 파일은 이 기본값을 대체할 일반 마켓플레이스 맵을 제공할 수 있습니다. 팀이 유지해야 하는 기본 마켓플레이스를 포함합니다. 팀에서 키를 생략하면 엔터프라이즈 기본값이 그대로 유지됩니다.

strictKnownMarketplaces

플러그 인 설치를 엔터프라이즈에서 명시적으로 정의한 마켓플레이스로만 제한합니다. 빈 배열은 전체 잠금을 의미합니다. 각 항목은 원본 형식을 나타내는 속성이 있는 source Marketplace 개체입니다. 지원되는 원본 유형은 다음과 같습니다.

• "github" — repo 형식의 OWNER/REPO이(가) 필요합니다. ref 및 path는 선택 사항입니다.
• "git" — url 필요; ref 및 path 선택 사항
• "url" — url 필요; 선택 사항 headers 개체
• "npm" — package 필요
• "file" — path 필요
• "directory" — path 필요
• "hostPattern" — 필요함 hostPattern (정규식과 일치하는 마켓플레이스 호스트)
• "pathPattern" — 필요함 pathPattern (마켓플레이스 경로와 일치하는 정규식)

이 키는 엔터프라이즈 팀에서 재정의할 수 있습니다. 엔터프라이즈 수준에서는 전체 허용 목록을 overridable로 감쌉니다.

{
  "strictKnownMarketplaces": {
    "overridable": [
      { "source": "github", "repo": "OWNER/REPO" }
    ]
  }
}

팀 파일에서 일반 배열을 사용하여 기본 허용 목록을 대체합니다. 키를 생략하면 엔터프라이즈 기본값이 유지됩니다. 명시적 빈 배열은 []관리되지 않는 정책이 아니라 완전한 잠금을 의미합니다.

모델

기본 설정 모델을 새 대화의 기본값으로 설정합니다. 이렇게 하면 엔터프라이즈 워크플로에 가장 적합한 기본 모델을 선택할 수 있습니다. 사용자는 여전히 대화별로 다른 모델을 선택할 수 있습니다.

• model를 기본값으로 사용하려면 "auto"을(를) auto model selection(으)로 설정하세요. 그러면 사용자가 대화별로 다른 모델을 지정하지 않는 한 새 세션에서 자동으로 모델이 선택됩니다. 정보 Copilotauto model selection을(를) 참조하세요.
• 특정 모델 및 버전으로 설정하여 해당 모델을 새 대화의 기본값으로 설정합니다 model . 예를 들면 다음과 같습니다 "kimi-k3".

이 키는 엔터프라이즈 팀 매핑으로 재정의할 수 있습니다. managed-settings.json에서 { "overridable": "auto" } 구문을 사용하여 팀별로 키 구성을 지정합니다. 그런 다음 팀 설정 파일에서 "model": "unmanaged"을(를) 설정하여 해당 팀 구성원에게는 managed-settings.json보다 우선 적용되는 특수화를 제공할 수 있습니다.

autoTier

선택한 모델이 "auto"인 경우 새 대화의 기본 라우팅 계층을 설정합니다. 허용되는 값은 가장 제한적인 값에서 가장 제한적인 값, 즉 "efficiency", "intelligence"``"balance"및 "unmanaged". 이 설정은 모델 자체를 선택하지 않습니다.

이 설정에는 Copilot CLI버전 1.0.87-0 이상이 필요합니다. 에서는 VS Code버전 1.140.0 이상이 필요합니다.

사용자 및 리포지토리 재정의에 대해 계층을 잠그는 것 이외의 "unmanaged" 문자열로 설정합니다autoTier. 사용자, 리포지토리 및 엔터프라이즈 팀이 재정의할 수 있는 기본값을 제공하려면 다음을 사용합니다: overridable

{
  "model": "auto",
  "autoTier": { "overridable": "balance" }
}

예를 들어 팀 설정 파일은 설정할 "autoTier": "intelligence"수 있습니다. 팀이 autoTier를 설정하지 않으면 엔터프라이즈 기본값이 적용됩니다.

forceRemoteSettingsRefresh

시작 시 Copilot CLI, VS Code, 및 GitHub Copilot app에서 서버 관리 설정을 새로 다운로드해야 합니다. true을(를) forceRemoteSettingsRefresh로 설정하여 이 요구 사항을 사용하도록 설정합니다.

GitHub Copilot app 및 Copilot CLI에서는 일반 1시간 캐시를 건너뛰고 다운로드가 실패할 경우 이전 캐시된 정책으로 폴백하지 않도록 합니다. 새로 고침에 실패하면 정책이 확인되지 않으므로 영향을 받는 작업이 제한됩니다. Copilot에서 VS Code 기능은 필수 새로 고침이 성공할 때까지 차단됩니다. 따라서 사용자는 클라이언트를 시작할 때 네트워크 연결이 필요합니다.

디바이스를 처음 시작할 때부터 적용되도록 해야 하는 요구 사항은 MDM 관리 또는 파일 기반 설정을 통해 전달합니다. 서버 관리형 값은 클라이언트가 이를 수신한 후 이후 시작할 때마다 새로 고쳐야 할 수 있습니다. 정책 도우미 스크립트는 이 키를 설정할 수 없습니다.

managed-settings.json에서는 JSON 부울을 사용합니다. 예: "forceRemoteSettingsRefresh": true Windows 레지스트리 또는 macOS 관리 기본 설정을 통해 Copilot CLI를 구성할 때 이 값을 false 또는 true를 포함하는 문자열로 저장합니다. DWORD 또는 네이티브 부울을 사용하지 마세요.

permissions

거부, 요청, 허용

에서 VS Code이러한 세분화된 권한 규칙은 에이전트 호스트를 Copilot 사용하는 세션에 적용됩니다. 이 permissions.disableBypassPermissionsMode 설정은 더 폭넓게 VS Code 지원되며 Agent Host로 제한되지 않습니다.

permissions.ask, permissions.allow, 및 permissions.deny 키는 거부 > 요청 > 허용 우선순위를 사용합니다. MDM으로 관리되는, 서버로 관리되는 또는 파일 기반 원본이 사용 권한 규칙을 하나라도 정의하거나, 적용 가능한 원본이 allow 목록을 선언하는 경우, 일치하는 규칙이 없는 지원 작업은 기본적으로 승인이 필요합니다. 그렇지 않으면 일반 권한 흐름을 따릅니다.

• deny 는 규칙과 일치하는 ask``allow 지 여부에 관계없이 특정 작업을 차단합니다. 관리되는 설정 원본에서 설정한 거부 규칙은 다른 원본의 규칙에 관계없이 모든 사용자에 대한 작업을 차단합니다.
• ask는 해당 작업이 원래는 허용되는 경우에도 특정 작업을 수행하기 전에 매번 새로운 승인을 받아야 합니다. 관리형 ask 규칙은 우회 모드(모두 허용 또는 YOLO 모드라고도 함), 자동 승인 설정, 후크 또는 기타 승인 지름길, 또는 이전 승인으로 인해 유지된 권한으로는 충족될 수 없습니다. 같은 작업이 다음에 요청될 때 다시 메시지가 표시됩니다.
• allow 는 프롬프트 없이 특정 작업을 진행할 수 있도록 허용합니다. 유효한 허용 목록은 허용 목록을 선언한 모든 소스의 합집합이 아니라 교집합입니다. 목록을 선언하지 않는 원본은 allow 이 키에 자체 제한을 두지 않습니다.

규칙은 다음 선택기를 사용합니다.

선택기	일치 항목
Shell(...)	셸 명령. 명령 접두사와 일치시키려면 <command> *(예: git push *)를 사용하세요. 그렇지 않으면 규칙은 정확히 일치하는 텍스트에만 적용됩니다.
Bash(...)는 Shell(...)의 호환성 별칭입니다.
PowerShell(...) 는 대/소문자를 구분하지 않는 명령 일치와 동일한 선택기 패밀리를 사용합니다.
Read(...)	파일 읽기 및 보기 경로입니다. glob 패턴과 다음 루트를 지원합니다: ~/ 파일 시스템 루트, / 작업 영역 루트, ./ 홈 디렉터리, // 현재 작업 디렉터리.
Edit(...)	파일 쓰기 및 편집 경로는 Read(...)와 동일한 방식으로 일치합니다.
Write(...)는 Edit(...)의 별칭입니다.
Domain(...)	네트워크 출처. 스킴이 없는 호스트는 기본적으로 HTTPS를 사용하며, 호스트 매칭은 대/소문자를 구분하지 않습니다. 하위 도메인을 포함하는 데 사용합니다 *. . 예를 들어 *.example.com example.com 하위 도메인과 일치합니다.

엔터프라이즈 팀의 경우 각 하위 키를 재정의할 수 있습니다. <VALUE>을 규칙 배열로 바꾸어 엔터프라이즈 값을 { "overridable": <VALUE> }로 설정합니다. 그런 다음, 일반 구문을 사용하여 각 팀의 파일에서 대체 규칙을 정의합니다.

권한 우회 비활성화 모드

사용자가 바이패스 모드("YOLO 모드"라고도 함)를 사용하도록 설정하지 못하도록 합니다. 바이패스 모드를 사용하면 에이전트가 승인을 요청하지 않고 명령을 실행하고, 파일에 액세스하고, URL을 가져올 수 있습니다.

disableBypassPermissionsMode을(를) "disable"(으)로 설정하면 사용자는 바이패스 모드를 켤 수 없습니다:

• Copilot CLI에서는 모든 권한을 허용하는 모든 명령줄 옵션(--yolo, --allow-all, 그리고 개별 --allow-all-tools, --allow-all-paths, --allow-all-urls 옵션)이 시작 시 비활성화되며, 권한 상승을 허용할 수 없습니다. /yolo 및 /allow-all 슬래시 명령도 차단됩니다.
• 에서 VS Code전역 자동 승인 설정(chat.tools.global.autoApprove)이 해제되어 다시 사용하도록 설정할 수 없습니다.
• 에서 GitHub Copilot app"도구 사용 권한"에 대한 "모두 허용" 설정이 세션 설정에서 차단됩니다.
• 이 키는 엔터프라이즈 팀 매핑으로 재정의할 수 있습니다. managed-settings.json에서 { "overridable": "disable" } 구문을 사용하여 팀별로 키 구성을 지정합니다. 그런 다음 팀 설정 파일에서 "disableBypassPermissionsMode": "unmanaged"을(를) 설정하여 해당 팀 구성원에게는 managed-settings.json보다 우선 적용되는 특수화를 제공할 수 있습니다.

원격 측정

선택한 수집기로 사용량 현황 데이터를 라우팅하여 Copilot OpenTelemetry 내보내기를 구성합니다.

클라이언트 지원 여부는 지원되는 키 표를 참조하세요.

telemetry 속성을 설정하면 Copilot 원격 분석 데이터가 사용자가 지정한 엔드포인트로 전송됩니다. 지원되는 하위 속성은 다음과 같습니다.

• enabled: 원격 분석 내보내기를 true 켜거나 false 해제하도록 설정합니다.
• endpoint: OTLP 수집기의 URL(예: https://otel-collector.example.com)입니다.
• protocol: 원격 분석 내보내기를 위한 전송 프로토콜입니다. 허용되는 값은 "http/json" 및 "http/protobuf"입니다.
• capture: ID 및 중요한 콘텐츠에 대한 독립적이고 세분화된 컨트롤이 있는 개체입니다. 모든 하위 속성의 기본값은 false입니다. 자세한 내용은 캡처 컨트롤을 참조하세요.
• captureContent: responses, toolArguments, toolOutput, policyDetail, prompts 캡처 클래스를 함께 사용하거나 사용하지 않도록 설정하는 레거시 약식입니다. 영향을 주지 identity않습니다. 명시적으로 구성된 capture 하위 속성은 해당 클래스에서 captureContent보다 우선합니다.
• lockCaptureContent: captureContent로 설정하여, 관리되는 true 개체에서 해당 클래스 또는 telemetry를 명시적으로 구성하지 않는 한 로컬 설정이 레거시 콘텐츠 클래스를 사용하도록 설정하지 못하게 합니다. 이 속성은 신원을 제어하지 않습니다.
• serviceName: 원격 분석 서비스 이름(예: "copilot")에 대한 레이블입니다.
• resourceAttributes: 내보낸 모든 텔레메트리에 추가할 OpenTelemetry 리소스 특성 객체입니다(예: {"deployment.environment": "production"}).
• headers: 각 원격 분석 요청(예: 수집기용 Authorization 헤더)에 포함할 리터럴 HTTP 헤더의 개체입니다. 동일한 endpoint 개체에서 telemetry를 구성해야 합니다. 헤더 값은 로그 또는 상태 출력에 포함되지 않습니다. HTTP는 일반 텍스트로 값을 보내기 때문에 헤더에 자격 증명이 포함된 경우 HTTPS를 사용하세요.
• headersProvider: 새 OTLP 헤더를 제공하는 명령을 실행하는 개체 또는 동적 헤더를 비활성화하는 false입니다. 관리되는 도우미가 사용자 도우미를 재정의하고, 관리되는 정적 도우미 headers는 사용자 도우미 출력보다 우선합니다. 이 속성은 Copilot CLI에 적용됩니다. 필드 및 동작은 GitHub Copilot CLI 명령 참조을 참조하세요.

관리 telemetry 되는 값은 로컬 설정, SDK 구성 및 환경 변수보다 우선합니다. 둘 이상의 관리되는 원본이 telemetry를 정의하는 경우, 우선 순위가 가장 높은 원본은 완전한 관리 telemetry 개체를 제공합니다. 우선 순위가 낮은 관리되는 원본의 개체는 그 원본에 병합되지 않습니다.

캡처 제어

에이전트 활동의 귀속을 나타내야 하지만 프롬프트, 응답 또는 도구 콘텐츠를 수집할 필요가 없을 때는 capture.identity를 사용합니다. 다른 캡처 클래스를 사용하여 감사 또는 조사에 필요한 추가 콘텐츠만 수집합니다.

세분화된 캡처 컨트롤은 Agent Host를 사용한 GitHub Copilot app 세션, VS Code 세션, 및 Copilot CLI 세션에서 지원됩니다. VS Code의 로컬 에이전트 하네스는 capture.identity 및 레거시 captureContent 설정을 지원하지만, policyDetail, prompts, responses, toolArguments, 또는 toolOutput을(를) 독립적으로 적용하지는 않습니다.

예를 들어 다음 구성 특성은 프롬프트, 응답, 도구 콘텐츠 또는 원시 정책 세부 정보를 캡처하지 않고 사용자와 머신에 연결할 수 있습니다.

{
  "telemetry": {
    "capture": {
      "identity": true
    }
  }
}

원격 제어

디바이스에서 호스트되는 세션을 원격으로 제어할 수 있는지 여부를 Copilot 제한합니다. 이는 다른 디바이스에서 호스트되는 세션을 원격으로 제어하는 사용자의 기능에 영향을 주지 않습니다.

• mode: 디바이스에서 세션의 원격 제어를 방지하거나"disabled", 나열된 "requireSSO"조직에 대해 SSO 권한이 부여된 클라이언트의 원격 제어만 허용하거나githubDotComOrganizations, 제한 없이 허용 "enabled" 하도록 설정됩니다.
• githubDotComOrganizations: 조직 로그인의 배열입니다. mode이 "requireSSO"인 경우 필요합니다.

allowedMcpServers

실행할 수 있는 MCP 서버의 허용 목록을 정의합니다. 설정하면 하나 이상의 항목과 일치하는 서버만 허용됩니다. 일치하지 않는 모든 서버가 차단됩니다.

deniedMcpServers의 항목이 있는 경우 해당 항목의 적용을 받으며, 모든 서버를 허용하려면 이 키를 아예 생략하세요. 기본 제공 서버를 제외한 모든 서버를 차단하려면 빈 배열로 설정합니다.

여러 설정 원본에서 allowedMcpServers를 정의하는 경우, 유효한 허용 목록은 모든 원본의 교집합입니다. 서버를 실행하려면 모든 소스의 허가를 받아야 합니다.

각 항목은 정확히 하나의 매처 속성만 가져야 합니다.

재산	매칭 동작	적용 가능한 서버
serverName	사용자 할당 서버 레이블과 정확히 일치합니다. 와일드카드는 지원되지 않습니다. 허용 목록 항목은 대/소문자를 구분하며 문자, 숫자 및 문자 _, /, ., -로만 제한되므로 microsoft/playwright-mcp와 같은 레지스트리 이름이 허용됩니다. 사용자가 서버 이름을 선택하므로 서버의 신원을 강제해야 할 때는 serverUrl 또는 serverCommand을 사용하세요.	모든 서버.
serverName은(는) 인메모리 서버에서만 사용할 수 있습니다.
serverUrl	원격 서버 URL과 일치합니다. 하위 도메인 또는 경로 접두사에 대한 * 와일드카드를 지원합니다. 예: https://mcp.example.com/* 또는 https://*.internal.example.com/*.	HTTP 또는 SSE(서버 전송 이벤트)를 통해 연결하는 원격 서버입니다. URL이 있더라도 이 속성은 로컬 서버에 적용되지 않습니다.
serverCommand	로컬 서버에 대한 정확한 명령 및 각 인수와 일치합니다(예: ["npx", "-y", "my-mcp-server"].). 와일드카드 및 명령줄 확장은 지원되지 않습니다.	표준 입력 및 출력(stdio)을 사용하는 로컬 서버입니다. 이 속성은 명령이 있더라도 원격 서버에는 적용되지 않습니다.

이 키는 엔터프라이즈 팀에서 재정의할 수 있습니다. 엔터프라이즈 수준에서 overridable 아래에 매처 객체를 묶은 다음, 일반 구문을 사용하여 각 팀의 파일에서 허용 목록과 거부 목록을 정의합니다.

URL 정식화

패턴을 서버 URL과 비교 serverUrl 하기 전에 클라이언트는 두 값을 모두 정규화합니다.

• 스키마 및 호스트를 소문자로 변환합니다.
• 국제화된 호스트 또는 유니코드 호스트 이름을 Punycode로 변환합니다.
• HTTP 또는 :80 HTTPS에 대한 기본 포트 :443 를 제거합니다.
• 백분율로 인코딩된 호스트 옥텟을 디코딩합니다. 예를 들어 %65vil는 evil로 변합니다.
• DNS 이름에서 URL 조각 및 후행 점을 제거합니다.
• 권한 구성 요소의 와일드카드가 경계를 넘어 / 경로로 일치하지 않도록 합니다.

deniedMcpServers

무조건 차단되는 MCP 서버를 정의합니다. 어느 항목이든 하나라도 일치하는 서버는 allowedMcpServers의 항목과도 일치하더라도 차단됩니다. 거부 규칙은 항상 허용 규칙보다 우선합니다.

기본 제공 Copilot MCP 서버와 같은 자사 GitHub 서버는 거부 규칙에서 제외되며 차단할 수 없습니다.

여러 설정 원본이 deniedMcpServers를 정의하는 경우, 최종 차단 목록은 모든 원본의 합집합입니다. 모든 원본에 의해 차단된 서버는 모두 차단됩니다.

각 항목은 동일한 serverName또는 serverUrl``serverCommand 에 설명된 allowedMcpServers속성을 사용합니다.

sandbox

Copilot CLI, Copilot Agent Host 세션, VS Code의 세션 및 GitHub Copilot app에 대해 최소 로컬 샌드박스 제한을 적용합니다. 관리되는 샌드박스 설정은 기본값이 아닌 제한을 적용합니다.

• 강제 사용 설정의 경우 true의 관리 값이 해당 설정을 강제합니다. false 또는 생략하면 사용자의 구성이 변경되지 않습니다.
• 기능 설정에서 false의 관리 값은 해당 기능을 금지합니다. true 또는 생략하면 사용자의 구성이 변경되지 않습니다.
• 관리되는 읽기/쓰기 및 읽기 전용 경로 목록은 사용자 구성 부여를 제한하지만 관리되는 거부 경로는 사용자 구성 거부에 추가됩니다.

VS Code 1.138.0 이상에서는 이러한 설정이 에이전트 호스트의 기본 제공 샌드박스를 사용하는 Copilot 세션에 적용됩니다. VS Code에서는 이 지원이 모든 유형의 채팅 세션 또는 터미널에 확장되지 않습니다. VS Code 1.140.0 이상에서는 sandbox.enabled을 true로 설정하면 사용자가 세션의 샌드박스 토글로 샌드박싱을 해제하지 못하게 됩니다. 정책이 바이패스를 허용하는 경우 사용자는 샌드박스 바이패스 권한 프롬프트에 응답할 때 현재 세션에 대해 비활성화할 수 있습니다. 조직의 정책이 변경되지 않습니다.

Copilot app의 세션에서는 포함된 런타임은 앱의 리포지토리 설정에서 사용할 수 없는 속성을 포함하여 전체 관리 sandbox 개체를 구문 분석, 결합 및 적용합니다. 앱은 완전한 유효 관리 정책이 아닌 사용자의 리포지토리 설정을 표시하고 설정별 관리 잠금을 표시하지 않습니다.

지원되는 하위 속성은 다음과 같습니다.

• enabled: true 기본적으로 샌드박싱이 필요합니다. 사용자는 자신의 구성 또는 CLI의 --no-sandbox 옵션을 통해 이를 사용하지 않도록 설정할 수 없습니다. GitHub Copilot app에서는 리포지토리 설정 및 /sandbox off 명령으로 재정의할 수 없습니다. 유효 정책이 바이패스를 허용하는 경우 사용자는 활성 샌드박스 바이패스 권한 프롬프트에서 현재 세션의 나머지 부분에 대해 샌드박싱을 사용하지 않도록 설정할 수 있습니다. Copilot CLI에서는 이번 세션 전용 옵트아웃에 /sandbox disable를 사용할 수도 있습니다. 저장된 정책은 변경되지 않습니다.
• failIfUnavailable: true,와 함께 enabled: true관리되는 샌드박스를 필수로 만듭니다. 사용 가능한 샌드박스 백 엔드를 사용하여 샌드박스 정책의 유효성을 검사, 컴파일 또는 적용할 수 없는 경우 Copilot 명령이 실패하거나 실행되지 않도록 허용하는 대신 모델 및 도구 실행을 차단합니다. 이 속성은 샌드박싱 자체를 사용하도록 설정하지 않습니다.
• allowBypass: false 개별 명령이 샌드박스 외부에서 실행되지 않도록 하고 활성 샌드박스 바이패스 권한 프롬프트에서 현재 세션의 나머지 부분에 대한 샌드박싱을 사용하지 않도록 설정합니다. Copilot CLI에서는 또한 사용자가 /sandbox disable로 샌드박스 기능을 비활성화하지 못하게 합니다.
• addCurrentWorkingDirectory: false 런타임이 샌드박스의 읽기/쓰기 경로에 현재 작업 디렉터리를 자동으로 추가하지 못하게 합니다.
• sandboxMcpServers: true 샌드박스에서 실행하려면 세션에서 시작된 로컬 MCP 서버가 필요합니다. 원격 MCP 서버는 로컬 샌드박스에서 실행되지 않습니다.
• sandboxLspServers: true 샌드박스에서 실행하려면 세션에서 시작된 언어 서버가 필요합니다.
• auth.git: false 샌드박스에서 인증된 Git HTTPS 작업에 대한 토큰을 런타임에서 삽입 GitHub 하지 못하게 합니다.
• auth.gh: false은(는) 런타임이 샌드박스에서 GitHub에 대한 GitHub CLI 토큰을 삽입하지 못하도록 합니다.
• allowDevToolAccess: false 개발 도구 구성, 캐시, 레지스트리 및 도구 체인에 대한 자동 액세스를 방지합니다. 이러한 위치에는 패키지 레지스트리 자격 증명 또는 토큰이 포함될 수 있습니다. 액세스를 사용하지 않도록 설정하면 필요한 경로를 명시적으로 부여하지 않으면 패키지 복원, 인증된 레지스트리 작업 또는 공유 캐시를 사용하는 빌드가 실패할 수 있습니다.
• learningMode: 지원되는 Windows 호스트의 샌드박스 명령이 차단된 액세스를 기록할지, 아니면 기록하고 허용할지를 제어합니다. sandbox.learningMode 를 참조하세요.
• userPolicy: 파일 시스템, 네트워크 및 macOS 관련 안전 벨트 제한을 구성하는 개체입니다. 지원되는 속성은 다음 섹션에서 설명합니다.

지원되지 않는 CLI 호스트에서는 failIfUnavailable: true 서버 관리가 enabled: true에도 적용이 필요한 경우가 아니면 거부될 수 있습니다. 네이티브 MDM, 파일 기반 관리 설정 및 정책 도우미 설정은 여전히 enabled: true를 계속 강제하므로 샌드박스가 없는 상태로 실행되는 대신 샌드박스 처리된 명령이 실패합니다. 둘 다 enabled와 failIfUnavailable가 필요한 경우 CLI는 강제 적용을 보장할 수 없는 경우 모델 및 도구 실행을 차단합니다. 보고된 호스트 또는 정책 문제를 해결한 다음 새 세션을 시작합니다.

서버에서 관리되는 엔터프라이즈 팀 재정의의 경우, 전체 샌드박스 개체를 overridable로 감싸세요:

{
  "sandbox": {
    "overridable": {
      "enabled": true,
      "allowBypass": false
    }
  }
}

sandbox 바로 내부에는 wrapper 속성만 있어야 합니다. 개별 하위 속성(예: sandbox.enabled)은 자체 overridable 래퍼를 사용할 수 없습니다. 팀 파일의 일반 샌드박스 개체는 래핑된 전체 기본값을 대체하므로 유지해야 하는 모든 제한을 포함합니다. 생략하면 sandbox 엔터프라이즈 기본값이 유지됩니다.

sandbox.learningMode

Windows에서 샌드박스 처리된 명령의 액세스 기록 기능을 제어합니다. 샌드박싱이 꺼져 있거나 Windows 호스트에서 액세스 기록을 지원하지 않는 경우에는 이 설정이 적용되지 않습니다.

• "deny" (기본값): 파일 시스템 및 프로세스 제한을 적용하고 차단된 액세스를 기록합니다.
• "allow": 그렇지 않으면 차단되는 파일 시스템 및 프로세스 액세스를 기록하고 허용합니다. 네트워크 제한 사항은 그대로 유지됩니다. 이 모드는 일반 파일 시스템 및 프로세스 보호를 제공하지 않습니다.

이 "allow" 값은 Intune 또는 Windows 레지스트리와 같은 네이티브 Windows 디바이스 관리를 통해서만 허용됩니다. managed-settings.json에서는 무시됩니다. 관리되는 모든 소스의 "deny" 값이 우선합니다.

sandbox.userPolicy.filesystem

샌드박스 처리 프로세스에 대한 파일 시스템 액세스를 구성합니다. 경로는 절대적이어야 합니다. 관리되는 권한 부여 목록은 부모 또는 자식 경로 범위가 아닌 정확한 경로 문자열로 사용자 구성 목록과 일치합니다.

• readwritePaths: 샌드박스 처리에서 읽고 쓸 수 있는 경로 배열입니다. 사용자가 구성한 경로는 이 속성을 지정하는 모든 관리되는 원본에도 정확한 문자열이 표시되는 경우에만 사용할 수 있습니다. 빈 관리형 배열은 사용자가 구성한 모든 읽기/쓰기 경로 부여를 제거하지만 임시 디렉터리 또는 현재 작업 디렉터리처럼 별도로 어셈블된 액세스는 제거하지 않습니다.
• readonlyPaths: 샌드박스 처리에서 읽을 수 있지만 쓸 수 없는 경로의 배열입니다. 사용자가 구성한 경로는 이 속성을 지정하는 모든 관리되는 원본에도 정확한 문자열이 표시되는 경우에만 사용할 수 있습니다. 빈 관리형 배열은 사용자가 구성한 모든 읽기 전용 경로 부여를 제거하지만 별도로 어셈블된 액세스는 제거하지 않습니다.
• deniedPaths: 샌드박스 처리에서 액세스할 수 없는 경로 배열입니다. 관리되는 값은 사용자의 거부된 경로를 대체하는 대신에 추가됩니다.

sandbox.userPolicy.network

샌드박스 처리 프로세스에 대한 네트워크 액세스를 구성합니다.

• allowOutbound: false 아웃바운드 네트워크 액세스를 차단합니다.
• allowLocalNetwork: false 로컬 네트워크 액세스를 제한합니다. 샌드박스 명령에 미치는 영향은 운영 체제에 따라 다릅니다. Windows 프록시 및 호스트 규칙에는 로컬 네트워크 액세스가 필요하므로, 이를 false와 결합하는 정책에서는 해당 명령은 시작할 수 없습니다.
• allowedHosts: 샌드박스 처리에 도달할 수 있는 호스트 이름 또는 IP 주소의 배열입니다. 비어 있지 않은 목록은 일치하지 않는 호스트를 차단합니다. 항목은 정확한 호스트 이름, 정확한 IP 주소, 루트 도메인이 아닌 하위 도메인에 대한 *.example.com 또는 모든 호스트에 대한 *일 수 있습니다. URL 또는 포트를 포함하지 마십시오. 사용자 및 관리형 허용 목록은 가장 제한적인 방식으로 결합됩니다. 겹치는 호스트가 없으면 모든 호스트가 거부됩니다.
• blockedHosts: 샌드박스 처리에 연결할 수 없는 호스트 이름 또는 IP 주소의 배열입니다. 차단된 호스트는 허용된 호스트보다 우선하며 도메인 차단은 해당 하위 도메인도 차단합니다.
• proxy: 업스트림 HTTP 프록시를 통해 샌드박스 네트워크 트래픽을 라우팅하는 개체입니다. proxy.url을(를) 프록시 URL로 설정합니다. 플랫폼 지원 및 적용은 다양합니다.

Copilot CLI에서는 호스트 규칙 및 업스트림 프록시는 기본 제공 로컬 프록시를 사용합니다. macOS 및 Linux에서 샌드박스는 프로그램이 직접 연결을 통해 우회하는 것을 방지합니다. Windows 샌드박스는 프록시 설정을 따르는 프로그램에 의존합니다. 따라서 Windows에서는 이러한 컨트롤은 직접 연결에 대해 동일한 보호를 제공하지 않습니다. 플랫폼 요구 사항 및 제한 사항은 네트워크 설정 구성을 참조하세요.

sandbox.userPolicy.seatbelt

macOS 관련 안전 벨트 옵션을 구성합니다.

• keychainAccess: false 샌드박스 처리가 macOS 키 집합에 액세스하지 못하도록 합니다.

sandbox에 대한 최소 클라이언트 버전 적용

관리되는 설정에 Copilot 키를 추가하면 sandbox는 범위 내 모든 사용자에게 로컬 샌드박스를 적용합니다. 이러한 사용자는 로컬 샌드박스를 지원하는 Copilot 클라이언트 버전을 사용해야 합니다. 사용자가 클라이언트를 지원되는 최소 버전 이상으로 업데이트할 때까지 연결이 Copilot 차단됩니다.

지원되는 클라이언트	최소 버전
VS Code
1.141.0
코파일럿 CLI
1.0.93
GitHub Copilot 앱
1.1.26