{"meta":{"title":"デバッグ ガイド","intro":"このガイドでは、サポートされているすべての言語でCopilot SDK の一般的な問題とデバッグ手法について説明します。","product":"GitHub Copilot","breadcrumbs":[{"href":"/ja/copilot","title":"GitHub Copilot"},{"href":"/ja/copilot/how-tos","title":"方法"},{"href":"/ja/copilot/how-tos/copilot-sdk","title":"Copilot SDK"},{"href":"/ja/copilot/how-tos/copilot-sdk/troubleshooting","title":"Troubleshooting"},{"href":"/ja/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 ログの構成は制限されています。 高度なログ記録を行う場合は、 `--log-dir` を使用して CLI を手動で実行し、 `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**Cause:** Copilot CLI が PATH にインストールされていないか、インストールされていません。\n\n**Solution:**\n\n1. CLI のインストール: [インストール ガイド](/ja/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 サーバー デバッグ ガイド](/ja/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 サーバー デバッグ ガイド](/ja/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging) を参照してください。\n\n## 接続に関する問題\n\n### stdio と TCP モード\n\nSDK では、次の 2 つのトランスポート モードがサポートされています。\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### ウィンドウズ\n\n1. **パス区切り文字:** raw 文字列またはフォワードスラッシュを使用します。\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### Linux\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搭載アプリを構築する](/ja/copilot/how-tos/copilot-sdk/getting-started)\n* [GitHub Copilot SDK での MCP サーバーの使用](/ja/copilot/how-tos/copilot-sdk/features/mcp) - MCP の構成とセットアップ\n* [MCP サーバー デバッグ ガイド](/ja/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging) - MCP の詳細なトラブルシューティング\n* [API リファレンス](https://github.com/github/copilot-sdk)"}