{"meta":{"title":"Guía de depuración","intro":"En esta guía se tratan los problemas comunes y las técnicas de depuración del SDK de Copilot en todos los lenguajes admitidos.","product":"GitHub Copilot","breadcrumbs":[{"href":"/es/copilot","title":"GitHub Copilot"},{"href":"/es/copilot/how-tos","title":"Procedimientos"},{"href":"/es/copilot/how-tos/copilot-sdk","title":"SDK de Copilot"},{"href":"/es/copilot/how-tos/copilot-sdk/troubleshooting","title":"Solución de problemas"},{"href":"/es/copilot/how-tos/copilot-sdk/troubleshooting/debugging","title":"Depuración"}],"documentType":"article"},"body":"# Guía de depuración\n\nEn esta guía se tratan los problemas comunes y las técnicas de depuración del SDK de Copilot en todos los lenguajes admitidos.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n## Tabla de contenido\n\n* [Habilitar el registro de depuración](#enable-debug-logging).\n* [Problemas comunes](#common-issues)\n* [Depuración del servidor MCP](#mcp-server-debugging)\n* [Problemas de conexión](#connection-issues)\n* [Problemas de ejecución de herramientas](#tool-execution-issues)\n* [Problemas específicos de la plataforma](#platform-specific-issues)\n\n## Habilitación del registro de depuración\n\nEl primer paso en la depuración es habilitar el registro detallado para ver lo que sucede en segundo plano.\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### Directorio de logs\n\nLa CLI escribe registros en un directorio. Puede especificar una ubicación personalizada:\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> La configuración de registro del SDK de Python está limitada. Para el registro avanzado, ejecute la CLI manualmente con `--log-dir` y conéctese mediante `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## Problemas comunes\n\n### \"CLI no encontrada\" / \"Copilot: comando no encontrado\"\n\n**Cause:** La CLI de Copilot no está instalada o no en PATH.\n\n**Solution:**\n\n1. Instalación de la CLI: [Guía de instalación](/es/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli)\n\n2. Compruebe la instalación:\n\n   ```bash\n   copilot --version\n   ```\n\n3. O especifique la ruta de acceso completa:\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### \"No autenticado\"\n\n**Cause:** La CLI no se autentica con GitHub.\n\n**Solution:**\n\n1. Autenticar la CLI:\n\n   ```bash\n   copilot auth login\n   ```\n\n2. O bien, proporcione un token mediante programación:\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### \"Sesión no encontrada\"\n\n**Causa:** Intentar usar una sesión que se destruyó o no existe.\n\n**Solution:**\n\n1. Asegúrese de que no llama a métodos después de `disconnect()`.\n\n   ```typescript\n   await session.disconnect();\n   // Don't use session after this!\n   ```\n\n2. Para reanudar sesiones, compruebe que el identificador de sesión existe:\n\n   ```typescript\n   const sessions = await client.listSessions();\n   console.log(\"Available sessions:\", sessions);\n   ```\n\n### \"Conexión rechazada\" / \"ECONNREFUSED\"\n\n**Causa:** El proceso del servidor de la CLI se bloqueó o no se pudo iniciar.\n\n**Solution:**\n\n1. Compruebe si la CLI se ejecuta correctamente de forma independiente:\n\n   ```bash\n   copilot --server --stdio\n   ```\n\n2. Compruebe si hay conflictos de puertos si usa el modo TCP:\n\n   ```typescript\n   const client = new CopilotClient({\n     useStdio: false,\n     port: 0,  // Use random available port\n   });\n   ```\n\n## Depuración del servidor MCP\n\nLos servidores MCP (Protocolo de Contexto de Modelo) pueden resultar complicados de depurar. Para obtener una guía completa sobre la depuración de MCP, consulte **[Guía de depuración del servidor MCP](/es/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging)**.\n\n### Lista de comprobación rápida de MCP\n\n* [ ] El ejecutable del servidor MCP existe y se ejecuta de forma independiente\n* [ ] La ruta de acceso del comando es correcta (utilice rutas de acceso absolutas)\n* [ ] Las herramientas están habilitadas: `tools: [\"*\"]`\n* [ ] El servidor responde a la `initialize` solicitud correctamente\n* [ ] El directorio de trabajo (`cwd`) se establece si es necesario.\n\n### Prueba del servidor MCP\n\nAntes de realizar la integración con el SDK, compruebe que el servidor MCP funciona:\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\nConsulte [Guía de depuración del servidor MCP](/es/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging) para obtener una solución de problemas detallada.\n\n## Problemas de conexión\n\n### stdio frente al modo TCP\n\nEl SDK admite dos modos de transporte:\n\n| Modo                             | Description                                                                | Caso de uso                     |\n| -------------------------------- | -------------------------------------------------------------------------- | ------------------------------- |\n| **Stdio** (valor predeterminado) | La CLI se ejecuta como subproceso, se comunica a través de canalizaciones. | Desarrollo local, proceso único |\n| **TCP**                          | La CLI se ejecuta por separado, se comunica a través del socket TCP.       | Varios clientes, CLI remota     |\n\n**Modo Stdio (valor predeterminado):**\n\n```typescript\nconst client = new CopilotClient({\n  useStdio: true,  // This is the default\n});\n```\n\n**Modo TCP:**\n\n```typescript\nconst client = new CopilotClient({\n  useStdio: false,\n  port: 8080,  // Or 0 for random port\n});\n```\n\n**Conéctese al servidor existente:**\n\n```typescript\nconst client = new CopilotClient({\n  cliUrl: \"localhost:8080\",  // Connect to running server\n});\n```\n\n### Diagnóstico de errores de conexión\n\n1. **Compruebe el estado del cliente:**\n\n   ```typescript\n   console.log(\"Connection state:\", client.getState());\n   // Should be \"connected\" after start()\n   ```\n\n2. **Escuche los cambios de estado:**\n\n   ```typescript\n   client.on(\"stateChange\", (state) => {\n     console.log(\"State changed to:\", state);\n   });\n   ```\n\n3. **Compruebe que el proceso de la CLI se está ejecutando:**\n\n   ```bash\n   # Check for copilot processes\n   ps aux | grep copilot\n   ```\n\n## Problemas de ejecución de herramientas\n\n### No se llama a la herramienta personalizada\n\n1. **Compruebe el registro de herramientas:**\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. **Comprobar el esquema de la herramienta es un esquema JSON válido:**\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. **Asegúrese de que el controlador devuelve un resultado válido:**\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### Errores de herramientas que no se muestran\n\nSuscríbase a eventos de error:\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## Problemas específicos de la plataforma\n\n### Windows\n\n1. **Separadores de ruta:** Use cadenas literales o barras diagonales:\n\n   ```csharp\n   CliPath = @\"C:\\Program Files\\GitHub\\copilot.exe\"\n   // or\n   CliPath = \"C:/Program Files/GitHub/copilot.exe\"\n   ```\n\n2. **Resolución PATHEXT:** El SDK controla esto automáticamente, pero si los problemas persisten:\n\n   ```csharp\n   // Explicitly specify .exe\n   Command = \"myserver.exe\"  // Not just \"myserver\"\n   ```\n\n3. **Codificación de la consola:** Asegúrese de usar UTF-8 para un manejo correcto de JSON:\n\n   ```csharp\n   Console.OutputEncoding = System.Text.Encoding.UTF8;\n   ```\n\n### macOS\n\n1. **Problemas de Gatekeeper:** Si la CLI está bloqueada:\n\n   ```bash\n   xattr -d com.apple.quarantine /path/to/copilot\n   ```\n\n2. **Problemas de PATH en las aplicaciones de GUI:** Es posible que las aplicaciones de GUI no hereden path del shell:\n\n   ```typescript\n   const client = new CopilotClient({\n     cliPath: \"/opt/homebrew/bin/copilot\",  // Full path\n   });\n   ```\n\n### Linux\n\n1. **Problemas de permisos:**\n\n   ```bash\n   chmod +x /path/to/copilot\n   ```\n\n2. **Faltan bibliotecas:** Compruebe si hay bibliotecas compartidas necesarias:\n\n   ```bash\n   ldd /path/to/copilot\n   ```\n\n## Obtener ayuda\n\nSi sigues atascado:\n\n1. **Recopilar información de depuración:**\n   * Versión del SDK\n   * Versión de la CLI (`copilot --version`)\n   * Sistema operativo\n   * Registros de depuración\n   * Código de reproducción mínimo\n\n2. **Buscar problemas existentes:**[problemas de GitHub](https://github.com/github/copilot-sdk/issues)\n\n3. **Abrir una nueva incidencia** con la información recopilada\n\n## Consulte también\n\n* [Crea tu primera aplicación con tecnología Copilot](/es/copilot/how-tos/copilot-sdk/getting-started)\n* [Uso de servidores MCP con el SDK de GitHub Copilot](/es/copilot/how-tos/copilot-sdk/features/mcp) - configuración y puesta en marcha de MCP\n* [Guía de depuración del servidor MCP](/es/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging) : solución de problemas detallada de MCP\n* [Referencia de API](https://github.com/github/copilot-sdk)"}