在 Copilot SDK 中使用本地 CLI

将 GitHub Copilot SDK 连接到本地已登录的 CLI 是最快的入门方式。

最佳适用场景： 个人项目、原型设计、本地开发和学习 SDK。

它是如何工作的

当您安装 Copilot CLI 并登录后，凭据会存储在系统钥匙串中。SDK 会自动将 CLI 作为子进程启动并使用这些存储的凭据。关键特性

• CLI 由 SDK 自动生成——无需设置。
• 身份验证使用系统钥匙串中已登录用户的凭据。
• 通信通过 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 替换为有效的 GitHub 个人访问令牌或 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 在与您的应用相同的机器上运行。
无多租户	无法从一个 CLI 实例为多个用户提供服务。
需要 CLI 登录	用户必须先运行 copilot 并进行身份验证。

后续步骤

• 若要将您的应用分发给其他用户，请参见 使用捆绑 CLI 与 Copilot SDK。
• 若要支持多个用户使用各自的 GitHub 账户登录，请参见 使用 GitHub OAuth 与 Copilot SDK。
• 若要在服务器上运行 SDK，请参见 后端服务的 Copilot SDK 设置。
• 关于您的第一条消息和安装，请参见 Copilot SDK 入门指南。