本地 CLI 配置是最零配置的 SDK 启动方式：SDK 自动找到并启动本地 Copilot CLI，使用 CLI 登录时存储的 GitHub 凭证。适合个人项目和原型开发，只支持单用户本地场景，不能部署给其他人使用。

GitHub Copilot SDK 本地 CLI 配置：个人开发和快速原型的最简方案

适用场景

• 个人项目和工具
• 快速原型开发
• 学习和探索 SDK 功能

不适合：部署给其他用户使用（每个用户需要自己安装并登录 CLI）

前提条件

1. 已安装 Copilot CLI
2. 已执行 gh auth login 或 gh copilot auth 完成 GitHub 登录
3. 登录账号有 Copilot 订阅

零配置启动

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

// SDK 自动找到并启动本地 CLI，无需任何配置
const session = await createSession()

const response = await session.sendPrompt({
  messages: [{ role: 'user', content: 'Hello, Copilot!' }]
})
console.log(response.content)

SDK 会：

1. 在 PATH 中查找 Copilot CLI 可执行文件
2. 自动启动 CLI 子进程
3. 从系统钥匙串读取之前登录时存储的 GitHub token
4. 通过 JSON-RPC 与 CLI 通信

使用环境变量认证

在 CI/CD 或不方便交互登录的场景，通过环境变量提供 token：

export COPILOT_GITHUB_TOKEN="your-github-token"

// SDK 自动读取 COPILOT_GITHUB_TOKEN 环境变量
const session = await createSession()

会话管理

默认创建的会话是临时的（重启后不恢复），通过 sessionId 可以跨进程复用：

// 创建可复用的会话
const session = await createSession({
  sessionId: 'my-dev-session'  // 下次启动用同一 ID 恢复
})

// 程序退出后，下次用同一 ID 恢复会话历史
const resumed = await createSession({
  sessionId: 'my-dev-session',  // 会加载上次的对话历史
  persist: true
})

排查常见问题

CLI 找不到：

# 确认 CLI 已安装并在 PATH 中
which gh
gh copilot --version

# 如果 CLI 在非标准路径，手动指定
const session = await createSession({
  cliPath: '/custom/path/to/gh-copilot'
})

认证失败：

# 重新登录
gh auth login
gh auth status

常见问题

Q: 这种方式可以在 GitHub Actions 中使用吗？

A: 可以，但需要通过 COPILOT_GITHUB_TOKEN 或 GITHUB_TOKEN 环境变量提供 token，CI 环境无法交互登录。

Q: 多个 Node.js 进程可以同时使用同一个 CLI 吗？

A: 不建议。本地 CLI 模式每次启动都是独立进程，多进程共用同一个 CLI 会产生竞态条件。多进程场景考虑后端服务模式。

Q: 能指定 CLI 版本吗？

A: 通过 cliPath 参数指定 CLI 可执行文件路径，可以指向特定版本的 CLI 二进制文件。