Copilot SDK のデバッグ

デバッグ ログを有効にし、 Copilot SDKでの一般的な接続、認証、ツールの実行に関する問題を解決します。

この機能を使用できるユーザーについて

GitHub Copilot SDK は、すべての Copilot プランで使用できます。

この記事で

メモ

          Copilot SDK は現在 パブリック プレビューです。 機能と可用性は変更される場合があります。

デバッグログを有効化する

トラブルシューティングを開始するには、詳細ログを有効にして、基になるプロセスを可視化します。

TypeScript
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient({
  logLevel: "debug",  // Options: "none", "error", "warning", "info", "debug", "all"
});

Python、Go、.NET の例については、 リポジトリのgithub/copilot-sdk参照してください。 Java については、 github/copilot-sdk-java リポジトリを参照してください。

ログ ディレクトリ

CLI は既定で ABC ディレクトリにログを書き込みます。 --log-dir引数を使用して、別の場所を指定できます。

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

現在、追加の CLI 引数の渡しをサポートしていない Python と Goは、 --log-dir を使用して CLI を手動で実行し、 cliUrl オプションを使用して接続します。 詳細については、 リポジトリのgithub/copilot-sdk参照してください。

一般的な問題

"CLI が見つかりません" または "copilot: コマンドが見つかりません"

          **原因:**GitHub Copilot CLI がインストールされていないか、PATH にありません。

          **Solution:**

  1. CLI をインストールします。 詳細については、「GitHub Copilot CLIをインストールする」を参照してください。

  2. インストールを確認します。

    Bash
    copilot --version

  3. または、完全なパスを指定します。

    TypeScript
    const client = new CopilotClient({
  cliPath: "/usr/local/bin/copilot",
});

    Python、Go、.NET の例については、 リポジトリのgithub/copilot-sdk参照してください。 Java については、 github/copilot-sdk-java リポジトリを参照してください。

"認証されていません"

          **原因：** CLI は、 GitHubでは認証されません。

          **Solution:**

  1. CLI を認証します。

    Bash
    copilot auth login

  2. または、プログラムでトークンを指定します。

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

    Python、Go、.NET の例については、 リポジトリのgithub/copilot-sdk参照してください。 Java については、 github/copilot-sdk-java リポジトリを参照してください。

"セッションが見つかりません"

          **原因：** 破棄されたセッションまたは存在しないセッションを使用しようとしています。

          **Solution:**

1. disconnect()後にメソッドを呼び出していないことを確認します。

TypeScript
await session.disconnect();
// Don't use session after this!

  1. セッションを再開する場合は、セッション ID が存在することを確認します。

    TypeScript
    const sessions = await client.listSessions();
console.log("Available sessions:", sessions);

"接続が拒否されました" または "ECONNREFUSED"

          **原因：** CLI サーバー プロセスがクラッシュしたか、開始に失敗しました。

          **Solution:**

  1. CLI が正しくスタンドアロンで実行されているかどうかを確認します。

    Bash
    copilot --server --stdio

  2. TCP モードを使用している場合は、ポートの競合を確認します。

    TypeScript
    const client = new CopilotClient({
  useStdio: false,
  port: 0,  // Use random available port
});

MCP サーバーのデバッグ

MCP (モデル コンテキスト プロトコル) サーバーは、デバッグが難しい場合があります。 包括的な MCP デバッグ ガイダンスについては、 Copilot SDK での MCP サーバーのデバッグ を参照してください。

クイック MCP チェックリスト

  • MCP サーバー実行可能ファイルが存在し、独立して実行される
  • コマンド パスが正しい (絶対パスを使用)
  • ツールが有効になっています。 tools: ["*"]
  • サーバーが initialize 要求に正しく応答する
  • 作業ディレクトリ (cwd) が必要に応じて設定される

MCP サーバーをテストする

SDK と統合する前に、MCP サーバーが動作することを確認します。

Bash
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

詳細なトラブルシューティングについては、 Copilot SDK での MCP サーバーのデバッグ を参照してください。

接続に関する問題

Stdio と TCP モード

SDK では、次の 2 つのトランスポート モードがサポートされています。

モード説明利用シーン
          **Stdio** (既定) | CLI はサブプロセスとして実行され、パイプ経由で通信します | ローカル開発、単一プロセス |

| TCP | CLI は個別に実行され、TCP ソケット経由で通信します | 複数のクライアント、リモート CLI |

          **Stdio モード (既定):**
TypeScript
const client = new CopilotClient({
  useStdio: true,  // This is the default
});

          **TCP モード:**
TypeScript
const client = new CopilotClient({
  useStdio: false,
  port: 8080,  // Or 0 for random port
});

          **既存のサーバーに接続します。**
TypeScript
const client = new CopilotClient({
  cliUrl: "localhost:8080",  // Connect to running server
});

接続エラーの診断

  1. クライアントの状態を確認します。

    TypeScript
    console.log("Connection state:", client.getState());
// Should be "connected" after start()

  2. 状態の変更を監視します。

    TypeScript
    client.on("stateChange", (state) => {
  console.log("State changed to:", state);
});

  3. CLI プロセスが実行されていることを確認します。

    Bash
    # Check for copilot processes
ps aux | grep copilot

ツールの実行に関する問題

カスタム ツールが呼び出されない

  1. ツールの登録を確認します。

    TypeScript
    const session = await client.createSession({
  tools: [myTool],
});

// Check registered tools
console.log("Registered tools:", session.getTools?.());

  2. ツール スキーマが有効な JSON スキーマであることを確認します。

    TypeScript
    const myTool = {
  name: "get_weather",
  description: "Get weather for a location",
  parameters: {
    type: "object",
    properties: {
      location: { type: "string", description: "City name" },
    },
    required: ["location"],
  },
  handler: async (args) => {
    return { temperature: 72 };
  },
};

  3. ハンドラーが有効な結果を返すことを確認します。

    TypeScript
    handler: async (args) => {
  // Must return something JSON-serializable
  return { success: true, data: "result" };

  // Don't return undefined or non-serializable objects
}

ツール エラーが表示されない

エラーイベントを購読する:

TypeScript
session.on("tool.execution_error", (event) => {
  console.error("Tool error:", event.data);
});

session.on("error", (event) => {
  console.error("Session error:", event.data);
});

プラットフォーム固有の問題

ウィンドウズ

  1.        **パス区切り記号:** 生の文字列またはフォワードスラッシュを使用します。 For .NET 固有の例については、[](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) リポジトリの`github/copilot-sdk`参照してください。

  2.        **コンソール エンコード:** 適切な JSON 処理のために UTF-8 を確認します。 For .NET 固有の例については、[](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md) リポジトリの`github/copilot-sdk`参照してください。

macOS

  1.        **ゲートキーパーの問題:** CLI がブロックされている場合:
    Bash
    xattr -d com.apple.quarantine /path/to/copilot

  2.        **GUI アプリでの PATH の問題:** GUI アプリケーションはシェル PATH を継承できません。
    TypeScript
    const client = new CopilotClient({
  cliPath: "/opt/homebrew/bin/copilot",  // Full path
});

リナックス

  1.        **アクセス許可の問題:**
    Bash
    chmod +x /path/to/copilot

  2.        **不足しているライブラリ:** 必要な共有ライブラリを確認します。
    Bash
    ldd /path/to/copilot

ヘルプを受ける

それでも問題が解決しない場合は、問題を開く前に次のデバッグ情報を収集してください。

  • SDK バージョン
  • CLI バージョン (copilot --version)
  • オペレーティング システム
  • デバッグ ログ
  • 最小限の再現コード

既存の問題を検索するか、 github/copilot-sdk リポジトリで新しい問題を開きます。