将本地 CLI 与 Copilot SDK 配合使用

注意

          Copilot SDK 当前处于 技术预览版. 功能和可用性可能会发生更改。

将 GitHub Copilot SDK 连接到您本地登录的 CLI 是快速入门的最佳方法。

          **最适合：** 个人项目、原型制作、本地开发和学习 SDK。

工作原理

安装 Copilot CLI 并登录时，凭据将存储在系统密钥链中。 SDK 自动将 CLI 作为子进程启动，并使用这些存储的凭据。主要特征：

SDK 会自动生成 CLI，无需设置。
身份验证使用系统密钥链中已登录用户的凭据。
通信通过 stdio （stdin/stdout）发生 - 未打开任何网络端口。
会话是您计算机的本地会话。

快速入门

默认配置根本不需要任何选项。

Node.js/TypeScript

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

const client = new CopilotClient();
const session = await client.createSession({ model: "gpt-4.1" });

const response = await session.sendAndWait({ prompt: "Hello!" });
console.log(response?.data.content);

await client.stop();

Python

from copilot import CopilotClient, PermissionHandler

client = CopilotClient()
await client.start()

session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1")
response = await session.send_and_wait({"prompt": "Hello!"})
print(response.data.content)

await client.stop()

Go

client := copilot.NewClient(nil)
if err := client.Start(ctx); err != nil {
    log.Fatal(err)
}
defer client.Stop()

session, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: "gpt-4.1"})
response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Hello!"})
fmt.Println(*response.Data.Content)

.NET

await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(
    new SessionConfig { Model = "gpt-4.1" });

var response = await session.SendAndWaitAsync(
    new MessageOptions { Prompt = "Hello!" });
Console.WriteLine(response?.Data.Content);

SDK 处理所有内容：启动 CLI、身份验证和管理会话。

此操作在内部的工作原理是什么？

有关组件之间的交互顺序的详细信息，请参阅github/copilot-sdk中的序列图。

配置选项

虽然默认设置适用于大多数情况，但你可以自定义本地设置：

const client = new CopilotClient({
    // Override CLI location (default: bundled with @github/copilot)
    cliPath: "/usr/local/bin/copilot",

    // Set log level for debugging
    logLevel: "debug",

    // Pass extra CLI arguments
    cliArgs: ["--log-dir=/tmp/copilot-logs"],

    // Set working directory
    cwd: "/path/to/project",
});

使用环境变量

你可以通过环境变量进行身份验证，而不是密钥链。这对于 CI 或不需要交互式登录时非常有用。

# Set one of these (in priority order):
export COPILOT_GITHUB_TOKEN="YOUR-GITHUB-TOKEN"   # Recommended
export GH_TOKEN="YOUR-GITHUB-TOKEN"               # GitHub CLI compatible
export GITHUB_TOKEN="YOUR-GITHUB-TOKEN"           # GitHub Actions compatible

将 YOUR-GITHUB-TOKEN 替换为有效的 GitHubpersonal access token 或 OAuth 令牌。 SDK 会自动选取这些内容，无需更改代码。

管理会话

使用本地 CLI 时，会话默认为临时会话。若要创建可恢复会话，请提供会话 ID：

// Create a named session
const session = await client.createSession({
    sessionId: "my-project-analysis",
    model: "gpt-4.1",
});

// Resume it in a later run
const resumed = await client.resumeSession("my-project-analysis");

会话状态存储在本地 ~/.copilot/session-state/SESSION-ID/，而 SESSION-ID 是您提供的会话 ID。

局限性

限度	详细信息

          **单个用户** | 凭据与登录到 CLI 的人员相关联。 |

后续步骤

若要将应用寄送给其他用户，请参阅将捆绑 CLI 与 Copilot SDK 配合使用。
若要支持使用自己的 GitHub 帐户登录的多个用户，请参阅将 GitHub OAuth 与 Copilot SDK 配合使用。
若要在服务器上运行 SDK，请参阅为后端服务设置 Copilot SDK。
有关第一条消息和安装，请参阅开始使用 Copilot SDK。

谁可以使用此功能？

在本文中