{"meta":{"title":"로컬 CLI 설정","intro":"SDK의 자동 CLI 관리 대신 특정 CLI 이진 파일을 사용합니다. 이 옵션은 고급 옵션입니다. CLI 경로를 명시적으로 제공하고 SDK와의 버전 호환성을 보장할 책임이 있습니다.","product":"GitHub Copilot","breadcrumbs":[{"href":"/ko/copilot","title":"GitHub Copilot"},{"href":"/ko/copilot/how-tos","title":"방법"},{"href":"/ko/copilot/how-tos/copilot-sdk","title":"코필로트 SDK"},{"href":"/ko/copilot/how-tos/copilot-sdk/setup","title":"Copilot SDK 설정"},{"href":"/ko/copilot/how-tos/copilot-sdk/setup/local-cli","title":"로컬 CLI"}],"documentType":"article"},"body":"# 로컬 CLI 설정\n\nSDK의 자동 CLI 관리 대신 특정 CLI 이진 파일을 사용합니다. 이 옵션은 고급 옵션입니다. CLI 경로를 명시적으로 제공하고 SDK와의 버전 호환성을 보장할 책임이 있습니다.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n**사용 시기:** 특정 CLI 버전을 고정하거나 Go SDK(CLI를 자동으로 포함하지 않음)로 작업해야 합니다.\n\n## 작동 방식\n\n기본적으로 Node.js, Python 및 .NET SDK에는 자체 CLI 종속성이 포함됩니다([기본 설정(번들 CLI)](/ko/copilot/how-tos/copilot-sdk/setup/bundled-cli) 참조). 예를 들어 시스템에 설치된 CLI를 사용하기 위해 이를 재정의해야 하는 경우, `Connection` 옵션을 사용할 수 있습니다.\n\n![다이어그램: 설명된 프로세스를 보여 주는 순서도입니다.](/assets/images/help/copilot/copilot-sdk/setup-local-cli-diagram-0.png)\n\n**주요 특징:**\n\n* CLI 바이너리 경로를 명시적으로 지정합니다.\n* 사용자는 SDK와의 CLI 버전 호환성을 담당합니다.\n* 인증은 시스템 키 집합(또는 env vars)에서 로그인한 사용자의 자격 증명을 사용합니다.\n* stdio를 통한 통신 발생\n\n## 구성 / 설정\n\n### 로컬 CLI 바이너리 사용\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"typescript\" data-label=\"TypeScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">TypeScript</div>\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient({\n    cliPath: \"/usr/local/bin/copilot\",\n});\n\nconst session = await client.createSession({ model: \"gpt-5.4\" });\nconst response = await session.sendAndWait({ prompt: \"Hello!\" });\nconsole.log(response?.data.content);\n\nawait client.stop();\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\nfrom copilot import CopilotClient\nfrom copilot.session_events import AssistantMessageData\nfrom copilot.session import PermissionHandler\n\nclient = CopilotClient({\n    \"cli_path\": \"/usr/local/bin/copilot\",\n})\nawait client.start()\n\nsession = await client.create_session(on_permission_request=PermissionHandler.approve_all, model=\"gpt-5.4\")\nresponse = await session.send_and_wait(\"Hello!\")\nif response:\n    match response.data:\n        case AssistantMessageData() as data:\n            print(data.content)\n\nawait client.stop()\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n> \\[!NOTE]\n> Go SDK는 CLI를 자동으로 제공하지 않습니다.\n> `PATH`에 `copilot`을 설치하거나, `COPILOT_CLI_PATH` 환경 변수를 설정하거나, [bundler tool](https://github.com/github/copilot-sdk/tree/main/go/README.md#distributing-your-application-with-an-embedded-github-copilot-cli)로 CLI를 포함하거나, `StdioConnection.Path`가 설치된 바이너리를 가리키도록 하세요.\n\n```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n    Connection: copilot.StdioConnection{Path: \"/usr/local/bin/copilot\"},\n})\nif err := client.Start(ctx); err != nil {\n    log.Fatal(err)\n}\ndefer client.Stop()\n\nsession, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: \"gpt-5.4\"})\nresponse, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: \"Hello!\"})\nif response != nil {\n    if d, ok := response.Data.(*copilot.AssistantMessageData); ok {\n        fmt.Println(d.Content)\n    }\n}\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n```csharp\nvar client = new CopilotClient(new CopilotClientOptions\n{\n    Connection = RuntimeConnection.ForStdio(path: \"/usr/local/bin/copilot\"),\n});\n\nawait using var session = await client.CreateSessionAsync(\n    new SessionConfig { Model = \"gpt-5.4\" });\n\nvar response = await session.SendAndWaitAsync(\n    new MessageOptions { Prompt = \"Hello!\" });\nConsole.WriteLine(response?.Data.Content);\n```\n\n</div>\n\n</div>\n\n## 추가 옵션\n\n```typescript\nconst client = new CopilotClient({\n    cliPath: \"/usr/local/bin/copilot\",\n\n    // Set log level for debugging\n    logLevel: \"debug\",\n\n    // Pass extra CLI arguments\n    cliArgs: [\"--log-dir=/tmp/copilot-logs\"],\n\n    // Set working directory\n    cwd: \"/path/to/project\",\n});\n```\n\n## 환경 변수 사용\n\n키 집합 대신 환경 변수를 통해 인증할 수 있습니다. 이는 CI 또는 대화형 로그인을 원하지 않는 경우에 유용합니다.\n\n```bash\n# Set one of these (in priority order):\nexport COPILOT_GITHUB_TOKEN=\"gho_xxxx\"   # Recommended\nexport GH_TOKEN=\"gho_xxxx\"               # GitHub CLI compatible\nexport GITHUB_TOKEN=\"gho_xxxx\"           # GitHub Actions compatible\n```\n\nSDK는 코드 변경이 필요하지 않고 자동으로 선택합니다.\n\n## 세션 관리\n\n세션은 기본적으로 임시로 설정됩니다. 다시 시작 가능한 세션을 만들려면 사용자 고유의 세션 ID를 제공합니다.\n\n```typescript\n// Create a named session\nconst session = await client.createSession({\n    sessionId: \"my-project-analysis\",\n    model: \"gpt-5.4\",\n});\n\n// Later, resume it\nconst resumed = await client.resumeSession(\"my-project-analysis\");\n```\n\n세션 상태는 에 `~/.copilot/session-state/{sessionId}/`로컬로 저장됩니다.\n\n## Limitations\n\n| Limitation    | 세부 정보                              |\n| ------------- | ---------------------------------- |\n| **버전 호환성**    | CLI 버전이 SDK와 호환되는지 확인해야 합니다.       |\n| **단일 사용자**    | 자격 증명은 CLI에 로그인한 사용자와 연결됩니다.       |\n| **로컬 전용**     | CLI는 앱과 동일한 컴퓨터에서 실행됩니다.           |\n| **다중 테넌트 없음** | 하나의 CLI 인스턴스에서 여러 사용자를 제공할 수 없습니다. |\n\n## 다음 단계\n\n* **[기본 설정(번들 CLI)](/ko/copilot/how-tos/copilot-sdk/setup/bundled-cli)**: SDK의 기본 제공 CLI 사용(대부분의 사용 사례에 권장)\n* **[첫 번째 Copilot 기반 앱 빌드](/ko/copilot/how-tos/copilot-sdk/getting-started)**: 완전한 대화형 앱 빌드\n* **[인증](/ko/copilot/how-tos/copilot-sdk/auth/authenticate)**: 모든 인증 메서드 세부 정보"}