GITHUB COPILOT CLI 구성 디렉터리

코파일럿 CLI 는 컴퓨터의 단일 디렉터리에 구성, 세션 기록, 로그 및 사용자 지정을 저장합니다. 기본적으로 이 디렉터리는 ~/.copilot (즉, $HOME/.copilot)입니다.

이 문서에서는 이 디렉터리의 내용과 이를 사용하는 방법을 설명합니다.

디렉터리 개요

~/.copilot 디렉터리에는 다음과 같은 최상위 항목이 포함됩니다.

사용자가 편집할 수 있는 파일

다음 파일은 사용자가 직접 편집하거나 CLI 명령을 통해 관리하도록 설계되었습니다.

settings.json

에 대한 기본 구성 파일입니다 코파일럿 CLI. 세션 내에서 대화형 /settings 명령을 사용하여 특정 값을 변경하거나 실행 /settings KEY VALUE 하여 단일 값을 설정하거나 텍스트 편집기에서 직접 파일을 편집할 수 있습니다. 파일은 주석이 있는 JSON(JSONC)을 지원합니다.

설정의 전체 목록 및 리포지토리 수준 구성과 상호 작용하는 방법은 이 문서의 뒷부분에 있는 구성 파일 설정을 참조하세요.

copilot-instructions.md

작업 중인 프로젝트에 관계없이 모든 세션에 적용되는 개인 사용자 지정 지침입니다. 이 파일은 리포지토리 수준 copilot-instructions.md 과 동일한 방식으로 작동하지만 전역적으로 적용됩니다.

자세한 내용은 GitHub Copilot 대한 리포지토리 사용자 지정 지침 추가을(를) 참조하세요.

instructions/

여기에 추가적인 개인 설명 파일을 *.instructions.md 파일로 저장하십시오. 이러한 항목은 함께 copilot-instructions.md 로드되고 모든 세션에 적용됩니다. 토픽별로 지침을 구성할 수 있습니다. 예를 들면 다음과 같습니다 ~/.copilot/instructions/code-style.instructions.md.

mcp-config.json

사용자 수준에서 사용할 수 있는 MCP(모델 컨텍스트 프로토콜) 서버를 정의합니다. 이러한 서버는 현재 있는 프로젝트 디렉터리에 관계없이 모든 세션에서 사용할 수 있습니다. Project 수준 MCP 구성(.mcp.json 또는 .github/mcp.json)은 서버 이름이 충돌할 때 사용자 수준 정의보다 우선합니다.

자세한 내용은 에 대한 MCP 서버 추가 GitHub Copilot 명령 줄 인터페이스 (CLI)을(를) 참조하세요.

lsp-config.json

사용자 수준에서 사용할 수 있는 LSP(Language Server Protocol) 서버를 정의합니다. 이러한 서버는 에이전트에 언어 인텔리전스(진단, 완료 등)를 제공합니다. 슬래시 명령을 사용하여 /lsp 이 파일을 관리하거나 직접 편집합니다.

자세한 내용은 GitHub Copilot 명령 줄 인터페이스 (CLI)에 대한 LSP 서버 추가을(를) 참조하세요.

agents/

여기에 개인 사용자 지정 에이전트 정의를 파일로 .agent.md 저장합니다. 이 디렉터리에 배치된 에이전트는 모든 세션에서 사용할 수 있습니다. 프로젝트 수준의 에이전트(.github/agents/)는 같은 이름을 가진 경우 개인 에이전트보다 우선적으로 적용됩니다.

자세한 내용은 사용자 지정 에이전트 만들기 및 사용 GitHub Copilot 명령 줄 인터페이스 (CLI)을(를) 참조하세요.

skills/

여기에 개인 사용자 지정 기술 정의를 저장합니다. 각 기술은 파일을 포함하는 SKILL.md 하위 디렉터리에 있습니다(예 ~/.copilot/skills/my-skill/SKILL.md: .). 개인 기술은 모든 세션에서 사용할 수 있습니다. Project 수준의 기술은 동일한 이름을 공유하는 경우 개인 기술보다 우선합니다.

자세한 내용은 GitHub Copilot 명령 줄 인터페이스 (CLI)에 에이전트 기술 추가을(를) 참조하세요.

hooks/

여기에 사용자 수준 후크 스크립트를 저장합니다. 이러한 후크는 모든 세션에 적용됩니다. 사용자 구성 파일(~/.copilot/settings.json)에서 hooks 키를 사용하여 후크를 인라인으로 정의할 수도 있습니다. 리포지토리 수준 후크(in .github/hooks/)는 사용자 수준 후크와 함께 로드됩니다.

자세한 내용은 GitHub Copilot 명령 줄 인터페이스 (CLI)로 후크 사용하기을(를) 참조하세요.

extensions/

여기에 사용자 수준 확장 파일을 저장합니다. 이 디렉터리의 확장은 세션 간에 사용할 수 있습니다.

이 디렉터리에 파일을 수동으로 만들거나 확장을 스캐폴드한 다음 생성된 파일을 편집할 수 있습니다.

자동으로 관리되는 파일

다음 항목은 CLI에서 관리됩니다. 일반적으로 수동으로 편집해서는 안 됩니다.

config.json

인증 데이터, 설치된 플러그 인 메타데이터 및 기타 런타임 정보를 포함하여 CLI에서 자동으로 관리되는 내부 애플리케이션 상태를 저장합니다. 일반적으로 이 파일을 편집할 필요가 없습니다.

permissions-config.json

프로젝트 위치별로 구성된 저장된 도구 및 디렉터리 권한 결정을 저장합니다. 도구를 승인하거나 현재 위치에 대한 디렉터리에 대한 액세스 권한을 부여하는 경우 CLI는 여기에 결정을 기록하므로 동일한 리포지토리 또는 디렉터리에 다시 메시지가 표시되지 않습니다.

파일 위치

코파일럿 CLI 는 구성 디렉터리에서 파일을 확인합니다.

이 --config-dir 옵션은 레거시 옵션입니다. 구성 디렉터리를 변경해야 할 때는 COPILOT_HOME를 사용하는 것이 좋습니다.

Windows 기본 파일은 일반적으로 다음과 같습니다.

C:\Users\YOUR-USER\.copilot\permissions-config.json

이전 빌드는 확장명 없는 파일을 사용했습니다 permissions-config. 존재하지 않지만 확장 없는 파일이 있는 경우 permissions-config.json CLI는 여전히 레거시 파일을 적용합니다. 새 편집에는 permissions-config.json를 사용합니다.

~/.copilot이 설정되지 않은 경우, 이전 XDG 기반 구성 위치는 시작 시 COPILOT_HOME로 마이그레이션됩니다.

위치 키

최상위 locations 개체는 절대 경로로 키가 지정됩니다.

• Git 리포지토리의 경우 권한 범위 지정에 사용되는 Git 루트를 사용합니다.
• 연결된 워크트리는 메인 리포지토리 루트로 해석되므로 메인 워크트리와 권한을 공유합니다.
• 하위 모듈은 자체 작업 디렉터리를 사용합니다.
• Git 리포지토리에 없는 디렉터리의 경우 정규화된 현재 작업 디렉터리를 사용합니다.

키가 실행 중인 위치 코파일럿 CLI 와 일치해야 합니다. 키가 일치하지 않으면 저장된 승인이 적용되지 않습니다.

CLI는 세션이 시작되고 활성 작업 디렉터리가 변경되는 경우 일치하는 위치의 승인을 로드합니다.

스키마

파일에는 JSON 개체가 포함되어야 합니다.

permissions-config.json 는 거부 규칙, "요청" 규칙, 기본 모드, URL 규칙, 도구 필터링 또는 리포지토리-로컬 공유 정책을 지원하지 않습니다. 이러한 동작의 경우 , --deny-tool, --available-tools``--excluded-tools및 --allow-url.와 같은 --deny-url명령줄 옵션을 사용합니다. 저장된 URL 규칙은 settings.json에 저장되고 permissions-config.json에는 저장되지 않습니다.

알 수 없는 필드는 스키마의 일부가 아닙니다. CLI는 이를 무시할 수 있으며 나중에 쓰기를 통해 제거할 수 있습니다.

승인 종류

각 항목은 tool_approvals 다음 개체 중 하나여야 합니다.

MCP 승인의 serverName 경우 구성된 MCP 서버 이름과 정확히 일치해야 합니다. 삭제된 도구 이름 접두사는 아닌 MCP 구성의 원시 서버 이름을 사용합니다.

셸 명령 일치

commandIdentifiers 는 셸 요청에서 추출된 명령 식별자와 일치합니다. :* 접미사를 제외하면 정확히 일치합니다.

:* 접미사는 일반적인 glob 패턴이 아닙니다. 정확히 stem과 일치하거나, stem 뒤에 공백과 추가 텍스트가 오는 경우와 일치합니다.

디렉터리 일치

allowed_directories 항목을 사용하면 별도의 경로 프롬프트 없이 해당 디렉터리 내의 경로에 액세스할 수 코파일럿 CLI 있습니다. 그들은 도구의 작동 자체를 승인하지 않습니다. 예를 들어 허용된 디렉터리에서 파일을 편집하려면 승인이 write 필요할 수 있습니다.

각 allowed_directories 항목은 비어있지 않은 절대 액세스 가능한 디렉터리여야 합니다. CLI는 경로를 비교하기 전에 심볼릭 링크를 해석하고, 확장 길이의 로컬 경로가 아닌 경우 UNC 네트워크 경로를 차단하며, Windows에서는 경로를 대/소문자를 구분하지 않고 비교하고 다른 플랫폼에서는 경로를 대/소문자를 구분하여 비교합니다. 항목을 적용할 수 없는 경우 CLI는 경고를 기록하고 해당 항목을 건너뜁니다.

예제

모든 Git 하위 명령을 허용하고 추가 로컬 디렉터리에 액세스합니다.

{
  "locations": {
    "C:\\src\\my-repo": {
      "tool_approvals": [
        {
          "kind": "commands",
          "commandIdentifiers": ["git:*"]
        }
      ],
      "allowed_directories": ["C:\\src\\shared-docs"]
    }
  }
}

{
  "locations": {
    "C:\\src\\my-repo": {
      "tool_approvals": [
        {
          "kind": "commands",
          "commandIdentifiers": ["git:*"]
        }
      ],
      "allowed_directories": ["C:\\src\\shared-docs"]
    }
  }
}

파일을 쓰기 전에 계속 묻는 동안 선택한 명령을 허용합니다.

{
  "locations": {
    "/Users/YOUR-USER/src/my-repo": {
      "tool_approvals": [
        {
          "kind": "commands",
          "commandIdentifiers": [
            "git status",
            "git diff",
            "git log",
            "npm test",
            "npm run build"
          ]
        }
      ]
    }
  }
}

{
  "locations": {
    "/Users/YOUR-USER/src/my-repo": {
      "tool_approvals": [
        {
          "kind": "commands",
          "commandIdentifiers": [
            "git status",
            "git diff",
            "git log",
            "npm test",
            "npm run build"
          ]
        }
      ]
    }
  }
}

리포지토리에 대한 파일 쓰기 및 MCP 서버 1개를 승인합니다.

{
  "locations": {
    "/home/YOUR-USER/src/my-repo": {
      "tool_approvals": [
        {
          "kind": "write"
        },
        {
          "kind": "mcp",
          "serverName": "github-mcp-server",
          "toolName": null
        }
      ]
    }
  }
}

{
  "locations": {
    "/home/YOUR-USER/src/my-repo": {
      "tool_approvals": [
        {
          "kind": "write"
        },
        {
          "kind": "mcp",
          "serverName": "github-mcp-server",
          "toolName": null
        }
      ]
    }
  }
}

하나의 MCP 도구, 메모리 쓰기 및 확장 권한 액세스를 승인합니다.

{
  "locations": {
    "C:\\src\\my-repo": {
      "tool_approvals": [
        {
          "kind": "mcp",
          "serverName": "github-mcp-server",
          "toolName": "search_code"
        },
        {
          "kind": "memory"
        },
        {
          "kind": "extension-permission-access",
          "extensionName": "my-extension"
        }
      ]
    }
  }
}

{
  "locations": {
    "C:\\src\\my-repo": {
      "tool_approvals": [
        {
          "kind": "mcp",
          "serverName": "github-mcp-server",
          "toolName": "search_code"
        },
        {
          "kind": "memory"
        },
        {
          "kind": "extension-permission-access",
          "extensionName": "my-extension"
        }
      ]
    }
  }
}

session-state/

하위 디렉터리의 세션 ID별로 구성된 세션 기록 데이터를 포함합니다. 각 세션 디렉터리에는 이벤트 로그(events.jsonl) 및 작업 영역 아티팩트(계획, 검사점, 추적된 파일)가 저장됩니다. 이 데이터는 세션 다시 시작(--resume 또는 --continue)을 사용하도록 설정합니다.

이 디렉터리에서 파일을 삭제하면 로컬 복사본만 제거됩니다. 계정에 세션을 GitHub 동기화한 경우 동기화된 데이터는 별도로 저장되며 로컬 파일 삭제의 영향을 받지 않습니다. 에서 동기화된 세션을 삭제하거나 숨길 수 있습니다 GitHub.com. 자세한 내용은 세션 데이터에 대한 정보 GitHub Copilot 명령 줄 인터페이스 (CLI)을(를) 참조하세요.

command-history-state/

대화형 인터페이스에서 역방향 검색(Ctrl+R) 및 기록 탐색에 사용되는 명령 기록 데이터를 포함합니다. 이 디렉터리가 자동으로 관리되므로 편집하면 안 됩니다.

session-store.db

검사점 인덱싱 및 검색과 같은 세션 간 데이터에 대해 CLI에서 사용하는 SQLite 데이터베이스입니다. 이 파일은 자동으로 관리되며 편집해서는 안 됩니다.

이 파일을 삭제하면 /chronicle reindex 명령을 사용하여 다시 빌드할 수 있습니다. 또한 다시 인덱싱하면 세션 데이터가 계정에 동기화됩니다.

logs/

CLI 세션에 대한 로그 파일을 포함합니다. 각 세션은 .라는 process-{timestamp}-{pid}.log로그 파일을 만듭니다. 이러한 파일은 문제를 디버깅하는 데 유용합니다.

CLI는 아래에 logs/extensions/확장 관련 로그를 만들 수도 있습니다.

이는 사용자가 작성한 확장 코드를 저장하는 ~/.copilot/extensions/와는 별개입니다.

installed-plugins/

설치한 플러그 인에 대한 파일을 포함합니다. 마켓플레이스에서 설치된 플러그 인은 .에 installed-plugins/{marketplace-name}/{plugin-name}/저장됩니다. 직접 설치된 플러그 인은 아래에 installed-plugins/_direct/저장됩니다. 이 디렉터리를 직접 편집하는 대신 명령을 사용하여 copilot plugin 플러그 인을 관리합니다.

자세한 내용은 GitHub Copilot CLI 플러그 인 참조을(를) 참조하세요.

plugin-data/

마켓플레이스 및 플러그 인 이름으로 구성된 설치된 플러그 인에 대한 영구 데이터를 포함합니다. 이 데이터는 플러그 인 자체에서 관리되며 수동으로 편집해서는 안됩니다.

ide/

IDE 통합을 위한 잠금 파일 및 상태를 포함합니다(예: 코파일럿 CLI가 Visual Studio Code에 연결할 때). 이 디렉터리가 자동으로 관리됩니다.

mcp-oauth-config/

키 집합 지원 스토리지를 사용할 수 없는 경우 MCP OAuth 토큰, 등록 및 PKCE 대체 파일을 포함합니다. 이 디렉터리가 자동으로 관리됩니다.

mcp-secrets/

키체인 기반 저장소를 사용할 수 없는 경우, MCP 비밀 자리 표시자를 위한 대체 파일 저장소와 인덱스를 포함합니다. 이 디렉터리가 자동으로 관리됩니다.

구성 디렉터리의 위치 변경

기본 ~/.copilot 위치를 재정의하려면 환경 변수를 COPILOT_HOME 사용하려는 디렉터리의 경로로 설정합니다.

export COPILOT_HOME=/path/to/my/copilot-config

export COPILOT_HOME=/path/to/my/copilot-config

알아야 할 사항

• COPILOT_HOME 는 전체 ~/.copilot 경로를 바꿉니다. 설정한 값은 구성 파일 및 하위 디렉터리에 사용할 디렉터리의 전체 경로여야 합니다.

• 디렉터리를 변경하면 기존 구성, 세션 기록, 설치된 플러그 인 및 저장된 권한이 새 위치에서 찾을 수 없습니다. 내용을 유지하려는 경우 내용을 ~/.copilot 복사하거나 새 위치로 이동합니다.

• 캐시 디렉터리(마켓플레이스 캐시, 자동 업데이트 패키지 및 기타 임시 데이터에 사용됨)는 플랫폼 규칙을 따르며 영향을 COPILOT_HOME받지 않습니다. 다음 위치에 있습니다.

  • macOS: ~/Library/Caches/copilot
  • Linux: $XDG_CACHE_HOME/copilot 또는 ~/.cache/copilot
  • Windows:%LOCALAPPDATA%/copilot

  캐시 디렉터리를 별도로 재정의하려면 COPILOT_CACHE_HOME을 설정합니다.

안전하게 삭제할 수 있는 항목

구성 파일 설정

설정은 다음 순서로 적용됩니다(나중의 설정이 앞선 설정을 재정의함):

1. 내장 기본값
2. MDM(모바일 장치 관리) 관리 설정
3. 사용자 설정(~/.copilot/settings.json)
4. 리포지토리 설정(.github/copilot/settings.json)
5. 로컬 설정(.github/copilot/settings.local.json)
6. 환경 변수
7. 명령줄 플래그

MDM 관리 설정은 시작 시 로드되고 사용자 설정과 정책 기준으로 병합됩니다. 대부분의 키에서 사용자 설정은 해당 기준을 재정의할 수 있습니다. 의 경우 permissions.disableBypassPermissionsModeMDM 값이 "disable" 항상 우선합니다. 자세한 내용은 MDM 관리 설정을 참조하세요.

CLI는 또한 리포지토리 설정의 여러 도구에서 공유되는 하위 집합(예: .claude/settings.json, .claude/settings.local.json, companyAnnouncements, disableAllHooks, enabledPlugins)에 대해 extraKnownMarketplaces 및 hooks도 읽습니다.

사용자 설정(~/.copilot/settings.json)

이러한 설정은 모든 세션 및 리포지토리에 적용됩니다. 슬래시 명령을 사용하여 /settings 대화형 대화 상자를 실행하거나 특정 슬래시 명령을 사용하여 개별 값을 업데이트하거나 이 파일을 직접 편집할 수 있습니다.

리포지토리 설정(.github/copilot/settings.json)

리포지토리 설정은 리포지토리에서 작동하는 모든 사용자에게 적용됩니다. 리포지토리에 커밋되고 공동 작업자와 공유됩니다.

다음 표에 나열된 키만 리포지토리 수준에서 지원됩니다. 사용자 구성 파일에서 유효한 키를 포함한 다른 키는 자동으로 무시됩니다.

로컬 설정(.github/copilot/settings.local.json)

리포지토리에서 커밋되지 않아야 할 개인 재정의를 위해 .github/copilot/settings.local.json를 만듭니다. 에 이 파일을 추가합니다 .gitignore.

로컬 구성 파일은 리포지토리 구성 파일(.github/copilot/settings.json)과 동일한 스키마를 사용하며 이보다 우선합니다.

MDM 관리 설정

IT 관리자는 사용자별 구성을 요구하지 않고 MDM(모바일 장치 관리) 관리 설정을 사용하여 기준 정책을 푸시할 수 있습니다. 이러한 설정은 지원되는 키에 대한 디바이스 수준 기본값을 적용하고 사용자 설정 전에 로드합니다.

MDM 관리 설정 원본

코파일럿 CLI 는 플랫폼별 MDM 또는 파일 기반 위치에서 관리되는 설정을 읽습니다.

파일 형식

파일 기반 관리 설정을 JSON으로 작성합니다.

{
    "permissions": {
        "disableBypassPermissionsMode": "disable"
    }
}

지원되는 키

MDM 관리 설정에서는 다음 키만 지원됩니다.

추가 읽기

• GitHub Copilot 명령 줄 인터페이스 (CLI)
• GitHub Copilot CLI 명령 참조
• GitHub Copilot CLI 프로그래밍 방식 참조
• GitHub Copilot CLI 플러그 인 참조
• GitHub Copilot 후크 참조