调试 Copilot SDK 的第一步是开启 debug 级别日志——大多数问题都能从日志中找到线索。常见问题包括 CLI 未安装/不在 PATH、token 未配置、Session 生命周期错误、TCP 端口冲突。MCP 服务器问题单独通过 stdin 发 JSON-RPC 请求来隔离定位。

GitHub Copilot SDK 调试指南：排查连接、认证和工具执行问题

开启调试日志

遇到问题时，先把日志级别调到 debug：

import { CopilotClient } from '@github/copilot-sdk'

const client = new CopilotClient({
  logLevel: 'debug'  // 可选: "none" | "error" | "warning" | "info" | "debug" | "all"
})

日志会打印 CLI 与 SDK 之间的 JSON-RPC 通信细节，大多数问题都能从这里看出来。

指定日志目录

CLI 默认把日志写到系统临时目录，也可以自定义：

const client = new CopilotClient({
  cliArgs: ['--log-dir', '/path/to/logs']
})

注意：Python 和 Go SDK 目前不支持传递额外 CLI 参数，需要手动启动 CLI 时加 --log-dir，然后通过 cliUrl 连接。

常见问题排查

"CLI not found" 或 "copilot: command not found"

原因：Copilot CLI 未安装或不在 PATH 中。

解决：

# 确认 CLI 已安装
copilot --version

# 如果 CLI 在非标准路径，手动指定
const client = new CopilotClient({
  cliPath: '/usr/local/bin/copilot'
})

"Not authenticated"

原因：CLI 未完成 GitHub 认证。

解决：

# 交互式登录
copilot auth login

或在代码中提供 token：

const client = new CopilotClient({
  githubToken: process.env.GITHUB_TOKEN
})

"Session not found"

原因：调用了已销毁或不存在的 Session。

解决：

// 不要在 disconnect() 后继续使用 session
await session.disconnect()
// ❌ 错误：之后不要再调用 session 的任何方法

// 恢复 Session 前先检查是否存在
const sessions = await client.listSessions()
console.log('可用 Sessions:', sessions)

"Connection refused" / "ECONNREFUSED"

原因：CLI 服务进程崩溃或启动失败。

解决：

# 单独测试 CLI 能否正常运行
copilot --server --stdio

如果用 TCP 模式，检查端口是否被占用：

const client = new CopilotClient({
  useStdio: false,
  port: 0  // 让系统自动分配可用端口
})

传输模式：Stdio vs TCP

SDK 支持两种与 CLI 通信的方式：

模式	说明	适用场景
Stdio（默认）	CLI 作为子进程，通过管道通信	本地开发、单进程
TCP	CLI 独立运行，通过 TCP Socket 通信	多客户端、远程 CLI

// Stdio 模式（默认）
const client = new CopilotClient({ useStdio: true })

// TCP 模式
const client = new CopilotClient({
  useStdio: false,
  cliUrl: 'http://localhost:3001'
})

MCP 服务器快速检查

在接入 SDK 之前，先单独测试 MCP 服务器：

# 发送 initialize 请求测试服务器是否响应
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | /path/to/your/mcp-server

如果服务器正常，会返回包含 serverInfo 的 JSON 响应。详细的 MCP 调试参考调试 MCP 服务器。

常见问题

Q: debug 日志太多，怎么只看我关心的部分？

A: 把日志写到文件后用 grep 过滤：grep "tool\|error\|session" /path/to/logs/copilot.log。重点关注 error 和 tool.call 相关的日志行。

Q: 日志里看到 JSON-RPC 请求发出去了，但没有收到响应，是什么问题？

A: 通常是 CLI 进程挂起。检查 CLI 进程是否存活（ps aux | grep copilot），并查看 CLI 自身的日志文件看是否有 panic 或 OOM 错误。

Q: 本地调试正常，部署到 CI 后报认证错误，怎么办？

A: CI 环境无法交互登录，需要通过环境变量 GITHUB_TOKEN 或 COPILOT_GITHUB_TOKEN 提供 token。确认该 token 有 copilot scope 且未过期。