{"meta":{"title":"디버깅 가이드","intro":"이 가이드에서는 지원되는 모든 언어에서 Copilot 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/troubleshooting","title":"Troubleshooting"},{"href":"/ko/copilot/how-tos/copilot-sdk/troubleshooting/debugging","title":"디버깅"}],"documentType":"article"},"body":"# 디버깅 가이드\n\n이 가이드에서는 지원되는 모든 언어에서 Copilot SDK에 대한 일반적인 문제 및 디버깅 기술에 대해 설명합니다.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n## 목차\n\n* [디버그 로깅 사용](#enable-debug-logging)\n* [일반적인 문제](#common-issues)\n* [MCP 서버 디버깅](#mcp-server-debugging)\n* [연결 문제](#connection-issues)\n* [도구 실행 문제](#tool-execution-issues)\n* [플랫폼별 문제](#platform-specific-issues)\n\n## 디버그 로깅 활성화\n\n디버깅의 첫 번째 단계는 세부 정보 로깅을 사용하여 내부적으로 어떤 일이 일어나고 있는지 확인하는 것입니다.\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  logLevel: \"debug\",  // Options: \"none\", \"error\", \"warning\", \"info\", \"debug\", \"all\"\n});\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\n\nclient = CopilotClient(log_level=\"debug\")\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```golang\nimport copilot \"github.com/github/copilot-sdk/go\"\n\nclient := copilot.NewClient(&copilot.ClientOptions{\n    LogLevel: \"debug\",\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<!-- docs-validate: skip -->\n\n```csharp\nusing GitHub.Copilot;\nusing Microsoft.Extensions.Logging;\n\n// Using ILogger\nvar loggerFactory = LoggerFactory.Create(builder =>\n{\n    builder.SetMinimumLevel(LogLevel.Debug);\n    builder.AddConsole();\n});\n\nvar client = new CopilotClient(new CopilotClientOptions\n{\n    LogLevel = \"debug\",\n    Logger = loggerFactory.CreateLogger<CopilotClient>()\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n```java\nimport com.github.copilot.CopilotClient;\nimport com.github.copilot.rpc.*;\n\nvar client = new CopilotClient(new CopilotClientOptions()\n    .setLogLevel(\"debug\")\n);\n```\n\n</div>\n\n</div>\n\n### 로그 디렉터리\n\nCLI는 디렉터리에 로그를 씁니다. 사용자 지정 위치를 지정할 수 있습니다.\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\nconst client = new CopilotClient({\n  cliArgs: [\"--log-dir\", \"/path/to/logs\"],\n});\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\n# The Python SDK does not currently support passing extra CLI arguments.\n# Logs are written to the default location or can be configured via\n# the CLI when running in server mode.\n```\n\n> \\[!NOTE]\n> Python SDK 로깅 구성이 제한됩니다. 고급 로깅을 위해 CLI를 `--log-dir`로 수동 실행하고 `RuntimeConnection.for_uri(...)`를 통해 연결합니다.\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```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n    Connection: copilot.StdioConnection{\n        Args: []string{\"--log-dir\", \"/path/to/logs\"},\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(args: new[] { \"--log-dir\", \"/path/to/logs\" })\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n<!-- docs-validate: skip -->\n\n```java\n// The Java SDK does not currently support passing extra CLI arguments.\n// For custom log directories, run the CLI manually with --log-dir\n// and connect via cliUrl.\n```\n\n</div>\n\n</div>\n\n## 일반적인 문제\n\n### \"CLI를 찾을 수 없음\" / \"Copilot: 명령을 찾을 수 없음\"\n\n**원인:** Copilot CLI가 설치되어 있지 않거나 PATH에 없습니다.\n\n**Solution:**\n\n1. CLI 설치: [설치 가이드](/ko/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli)\n\n2. 설치 확인:\n\n   ```bash\n   copilot --version\n   ```\n\n3. 또는 전체 경로를 지정합니다.\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"javascript\" data-label=\"JavaScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">JavaScript</div>\n\n```typescript\nconst client = new CopilotClient({\n  cliPath: \"/usr/local/bin/copilot\",\n});\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\nclient = CopilotClient({\"cli_path\": \"/usr/local/bin/copilot\"})\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```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n    Connection: copilot.StdioConnection{Path: \"/usr/local/bin/copilot\"},\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    CliPath = \"/usr/local/bin/copilot\"\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n```java\nvar client = new CopilotClient(new CopilotClientOptions()\n    .setCliPath(\"/usr/local/bin/copilot\")\n);\n```\n\n</div>\n\n</div>\n\n### \"인증되지 않음\"\n\n**Cause:** CLI는 GitHub 인증되지 않습니다.\n\n**Solution:**\n\n1. CLI 인증:\n\n   ```bash\n   copilot auth login\n   ```\n\n2. 또는 프로그래밍 방식으로 토큰을 제공합니다.\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"javascript\" data-label=\"JavaScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">JavaScript</div>\n\n```typescript\nconst client = new CopilotClient({\n  gitHubToken: process.env.GITHUB_TOKEN,\n});\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\nimport os\nclient = CopilotClient({\"github_token\": os.environ.get(\"GITHUB_TOKEN\")})\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```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n    GitHubToken: os.Getenv(\"GITHUB_TOKEN\"),\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    GitHubToken = Environment.GetEnvironmentVariable(\"GITHUB_TOKEN\")\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n```java\nvar client = new CopilotClient(new CopilotClientOptions()\n    .setGitHubToken(System.getenv(\"GITHUB_TOKEN\"))\n);\n```\n\n</div>\n\n</div>\n\n### \"세션을 찾을 수 없음\"\n\n**원인:** 제거되었거나 존재하지 않는 세션을 사용하려고 시도합니다.\n\n**Solution:**\n\n1. 다음 후에 `disconnect()`메서드를 호출하지 않는지 확인합니다.\n\n   ```typescript\n   await session.disconnect();\n   // Don't use session after this!\n   ```\n\n2. 세션을 다시 열려면 세션 ID가 있는지 확인합니다.\n\n   ```typescript\n   const sessions = await client.listSessions();\n   console.log(\"Available sessions:\", sessions);\n   ```\n\n### \"연결이 거부됨\" / \"ECONNREFUSED\"\n\n**원인:** CLI 서버 프로세스가 충돌하거나 시작하지 못했습니다.\n\n**Solution:**\n\n1. CLI가 올바르게 독립 실행형으로 실행되는지 확인합니다.\n\n   ```bash\n   copilot --server --stdio\n   ```\n\n2. TCP 모드를 사용하는 경우 포트 충돌을 확인합니다.\n\n   ```typescript\n   const client = new CopilotClient({\n     useStdio: false,\n     port: 0,  // Use random available port\n   });\n   ```\n\n## MCP 서버 디버깅\n\nMCP(모델 컨텍스트 프로토콜) 서버는 디버그하기 어려울 수 있습니다. 포괄적인 MCP 디버깅 지침은 전용 **[MCP 서버 디버깅 가이드](/ko/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging)** 을 참조하세요.\n\n### 빠른 MCP 검사 목록\n\n* [ ] MCP 서버 실행 파일이 존재하며 독립적으로 실행됩니다.\n* [ ] 명령 경로가 올바르다(절대 경로 사용)\n* [ ] 도구를 사용할 수 있습니다. `tools: [\"*\"]`\n* [ ] 서버가 요청에 올바르게 응답합니다 `initialize` .\n* [ ] 작업 디렉터리(`cwd`)가 필요한 경우 설정됨\n\n### MCP 서버 테스트\n\nSDK와 통합하기 전에 MCP 서버가 작동하는지 확인합니다.\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}' | /path/to/your/mcp-server\n```\n\n자세한 문제 해결은 [MCP 서버 디버깅 가이드](/ko/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging) 을 참조하세요.\n\n## 연결 문제\n\n### stdio 및 TCP 모드\n\nSDK는 두 가지 전송 모드를 지원합니다.\n\n| 모드              | Description                       | 사용 사례            |\n| --------------- | --------------------------------- | ---------------- |\n| **Stdio** (기본값) | CLI는 하위 프로세스로 실행되며 파이프를 통해 통신합니다. | 로컬 개발, 단일 프로세스   |\n| **TCP**         | CLI는 별도로 실행되며 TCP 소켓을 통해 통신합니다.   | 여러 클라이언트, 원격 CLI |\n\n**Stdio 모드(기본값):**\n\n```typescript\nconst client = new CopilotClient({\n  useStdio: true,  // This is the default\n});\n```\n\n**TCP 모드:**\n\n```typescript\nconst client = new CopilotClient({\n  useStdio: false,\n  port: 8080,  // Or 0 for random port\n});\n```\n\n**기존 서버에 연결:**\n\n```typescript\nconst client = new CopilotClient({\n  cliUrl: \"localhost:8080\",  // Connect to running server\n});\n```\n\n### 연결 오류 진단\n\n1. **클라이언트 상태 확인:**\n\n   ```typescript\n   console.log(\"Connection state:\", client.getState());\n   // Should be \"connected\" after start()\n   ```\n\n2. **상태 변경 내용 수신 대기:**\n\n   ```typescript\n   client.on(\"stateChange\", (state) => {\n     console.log(\"State changed to:\", state);\n   });\n   ```\n\n3. **CLI 프로세스가 실행 중인지 확인합니다.**\n\n   ```bash\n   # Check for copilot processes\n   ps aux | grep copilot\n   ```\n\n## 도구 실행 문제\n\n### 사용자 지정 도구가 호출되지 않음\n\n1. **도구 등록 확인:**\n\n   ```typescript\n   const session = await client.createSession({\n     tools: [myTool],\n   });\n\n   // Check registered tools\n   console.log(\"Registered tools:\", session.getTools?.());\n   ```\n\n2. **도구 스키마가 유효한 JSON 스키마인지 확인합니다.**\n\n   ```typescript\n   const myTool = {\n     name: \"get_weather\",\n     description: \"Get weather for a location\",\n     parameters: {\n       type: \"object\",\n       properties: {\n         location: { type: \"string\", description: \"City name\" },\n       },\n       required: [\"location\"],\n     },\n     handler: async (args) => {\n       return { temperature: 72 };\n     },\n   };\n   ```\n\n3. **처리기가 유효한 결과를 반환하는지 확인합니다.**\n\n   ```typescript\n   handler: async (args) => {\n     // Must return something JSON-serializable\n     return { success: true, data: \"result\" };\n     \n     // Don't return undefined or non-serializable objects\n   }\n   ```\n\n### 도구 오류가 표면에 드러나지 않음\n\n오류 이벤트 구독:\n\n```typescript\nsession.on(\"tool.execution_error\", (event) => {\n  console.error(\"Tool error:\", event.data);\n});\n\nsession.on(\"error\", (event) => {\n  console.error(\"Session error:\", event.data);\n});\n```\n\n## 플랫폼별 문제\n\n### Windows\n\n1. **경로 구분 기호:** 원시 문자열 또는 슬래시 사용:\n\n   ```csharp\n   CliPath = @\"C:\\Program Files\\GitHub\\copilot.exe\"\n   // or\n   CliPath = \"C:/Program Files/GitHub/copilot.exe\"\n   ```\n\n2. **PATHEXT 해결 방법:** SDK는 이 작업을 자동으로 처리하지만 문제가 지속되면 다음을 수행합니다.\n\n   ```csharp\n   // Explicitly specify .exe\n   Command = \"myserver.exe\"  // Not just \"myserver\"\n   ```\n\n3. **콘솔 인코딩:** 적절한 JSON 처리를 위해 UTF-8을 확인합니다.\n\n   ```csharp\n   Console.OutputEncoding = System.Text.Encoding.UTF8;\n   ```\n\n### macOS\n\n1. **게이트키퍼 문제:** CLI가 차단된 경우:\n\n   ```bash\n   xattr -d com.apple.quarantine /path/to/copilot\n   ```\n\n2. **GUI 앱의 PATH 문제:** GUI 애플리케이션은 셸 PATH를 상속할 수 없습니다.\n\n   ```typescript\n   const client = new CopilotClient({\n     cliPath: \"/opt/homebrew/bin/copilot\",  // Full path\n   });\n   ```\n\n### 리눅스\n\n1. **권한 문제:**\n\n   ```bash\n   chmod +x /path/to/copilot\n   ```\n\n2. **누락된 라이브러리:** 필요한 공유 라이브러리를 확인합니다.\n\n   ```bash\n   ldd /path/to/copilot\n   ```\n\n## 도움 받기\n\n여전히 막혀 있다면:\n\n1. **디버그 정보 수집:**\n   * SDK 버전\n   * CLI 버전(`copilot --version`)\n   * 운영 체제\n   * 디버그 로그\n   * 최소 복제 코드\n\n2. **기존 이슈 검색:**[GitHub Issues](https://github.com/github/copilot-sdk/issues)\n\n3. 수집된 정보**로 새 문제 열기**\n\n## 참고하십시오\n\n* [첫 번째 Copilot 기반 앱 빌드](/ko/copilot/how-tos/copilot-sdk/getting-started)\n* [GitHub Copilot SDK에서 MCP 서버 사용](/ko/copilot/how-tos/copilot-sdk/features/mcp) - MCP 구성 및 설정\n* [MCP 서버 디버깅 가이드](/ko/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging) - 자세한 MCP 문제 해결\n* [API 참조](https://github.com/github/copilot-sdk)"}