自带密钥 (BYOK)

使用 Copilot SDK 与来自不同模型提供商的自有 API 密钥，绕过 GitHub Copilot 身份验证。

谁可以使用此功能？

GitHub Copilot SDK 在所有 Copilot 计划中均可使用。

本文内容

注意

Copilot SDK 目前处于公开预览阶段。功能和可用性可能会更改。

自带密钥 (BYOK) 允许你在使用 Copilot SDK 时使用来自模型提供商的自有 API 密钥，绕过 GitHub Copilot 身份验证。这在企业部署、自定义模型托管，或希望直接向模型提供商计费的场景中非常有用。

支持的提供商

提供商类型值注意
OpenAI"openai"OpenAI API 和兼容 OpenAI 的端点
Azure OpenAI / Azure AI Foundry"azure" 或 "openai"Azure 托管的模型（参见 Azure 端点类型）
Anthropic"anthropic"Claude 模型
Ollama"openai"通过兼容 OpenAI 的 API 使用本地模型
Microsoft Foundry Local"openai"在你的设备上本地运行 AI 模型，使用兼容 OpenAI 的 API
其他兼容 OpenAI 的提供商"openai"vLLM、LiteLLM 等类似服务

快速入门：Azure AI Foundry

Azure AI Foundry（前称 Azure OpenAI）是企业常用的 BYOK 部署目标。下面的示例展示了完整的 Node.js/TypeScript 设置。

  1. 使用你的 Azure AI Foundry 端点和 API 密钥创建会话

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

const client = new CopilotClient();
const session = await client.createSession({
    model: "YOUR-DEPLOYMENT-NAME",
    provider: {
        type: "openai",
        baseUrl: "https://YOUR-RESOURCE.openai.azure.com/openai/v1/",
        wireApi: "responses",  // Use "completions" for older models
        apiKey: process.env.FOUNDRY_API_KEY,
    },
});

session.on("assistant.message", (event) => {
    console.log(event.data.content);
});

await session.sendAndWait({ prompt: "What is 2+2?" });
await client.stop();

将 YOUR-RESOURCE 替换为你的 Azure 资源名称，将 YOUR-DEPLOYMENT-NAME 替换为模型部署名称。将 FOUNDRY_API_KEY 环境变量设置为你的 Azure API 密钥。

有关 Python、Go 和 .NET 示例，请参见 BYOK（位于 github/copilot-sdk 仓库）。Java 示例请参见 github/copilot-sdk-java 仓库。

提供商配置参考

ProviderConfig 字段

字段类型描述
type"openai" | "azure" | "anthropic"提供商类型。默认值为 "openai"。
baseUrlstring必填。 API 端点 URL。
apiKeystringAPI 密钥。对本地提供商（如 Ollama）为可选项。
bearerTokenstringBearer Token 认证。会覆盖 apiKey。
wireApi"completions" | "responses"API 格式。默认值为 "completions"。
azure.apiVersionstringAzure API 版本。默认值为 "2024-10-21"。

Wire API 格式

wireApi 设置决定使用哪种 OpenAI API 格式

  • "completions"（默认）：Chat Completions API（/chat/completions）。适用于大多数模型。
  • "responses"：Responses API。用于支持新版 responses 格式的 GPT-5 系列模型。

类型特定说明

OpenAI（type: "openai"）

  • 适用于 OpenAI API 以及任何兼容 OpenAI 的端点。
  • baseUrl 必须包含完整路径，例如 https://api.openai.com/v1。

Azure（type: "azure"）

  • 用于原生 Azure OpenAI 端点。
  • baseUrl 只需写主机，例如 https://YOUR-RESOURCE.openai.azure.com。
  • 不要在 URL 中加入 /openai/v1——SDK 会自行构造完整路径。

Anthropic（type: "anthropic"）

  • 用于直接访问 Anthropic API。
  • 使用 Claude 专有的 API 格式。

示例配置

OpenAI 直连

TypeScript
provider: {
    type: "openai",
    baseUrl: "https://api.openai.com/v1",
    apiKey: process.env.OPENAI_API_KEY,
}

Azure OpenAI（原生 Azure 端点）

对 *.openai.azure.com 的端点使用 type: "azure"

TypeScript
provider: {
    type: "azure",
    baseUrl: "https://YOUR-RESOURCE.openai.azure.com",  // Just the host
    apiKey: process.env.AZURE_OPENAI_KEY,
    azure: {
        apiVersion: "2024-10-21",
    },
}

将 YOUR-RESOURCE 替换为你的 Azure 资源名称。

Azure AI Foundry（兼容 OpenAI 的端点）

对于带有 /openai/v1/ 路径的 Azure AI Foundry 部署，使用 type: "openai"

TypeScript
provider: {
    type: "openai",
    baseUrl: "https://YOUR-RESOURCE.openai.azure.com/openai/v1/",
    apiKey: process.env.FOUNDRY_API_KEY,
    wireApi: "responses",  // For GPT-5 series models
}

Ollama（本地）

TypeScript
provider: {
    type: "openai",
    baseUrl: "https://:11434/v1",
    // No apiKey needed for local Ollama
}

Microsoft Foundry Local

Microsoft Foundry Local 让你在本地运行 AI 模型，并提供兼容 OpenAI 的 API。先通过 Foundry Local CLI 安装，然后将 SDK 指向你的本地端点。

TypeScript
provider: {
    type: "openai",
    baseUrl: "https://:YOUR-PORT/v1",
    // No apiKey needed for local Foundry Local
}

注意

Foundry Local 会在启动时使用动态端口，端口不是固定的。运行 foundry service status 可确认当前服务监听的端口，然后在 baseUrl 中使用该端口。

开始使用 Foundry Local 的步骤

Bash
# Windows: Install Foundry Local CLI (requires winget)
winget install Microsoft.FoundryLocal

# List available models
foundry model list

# Run a model (starts the local server automatically)
foundry model run phi-4-mini

# Check the port the service is running on
foundry service status

macOS / Linux 安装请参考 foundrylocal.ai。

Anthropic

TypeScript
provider: {
    type: "anthropic",
    baseUrl: "https://api.anthropic.com",
    apiKey: process.env.ANTHROPIC_API_KEY,
}

Bearer Token 认证

部分提供商需要使用 Bearer Token 而不是 API 密钥进行认证

TypeScript
provider: {
    type: "openai",
    baseUrl: "https://YOUR-CUSTOM-ENDPOINT.example.com/v1",
    bearerToken: process.env.MY_BEARER_TOKEN,  // Sets Authorization header
}

注意

bearerToken 选项仅接受静态的 Token 字符串。SDK 不会自动刷新该 Token。若 Token 失效，所有请求将失败，你需要使用新 Token 创建会话。

自定义模型列表

使用 BYOK 时，CLI 服务器可能不知道你的提供商支持哪些模型。你可以在客户端层提供自定义的 onListModels 处理函数，使 client.listModels() 返回符合标准 ModelInfo 格式的模型列表。

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

const client = new CopilotClient({
    onListModels: () => [
        {
            id: "my-custom-model",
            name: "My Custom Model",
            capabilities: {
                supports: { vision: false, reasoningEffort: false },
                limits: { max_context_window_tokens: 128000 },
            },
        },
    ],
});

首次调用后结果会被缓存。该处理函数会完全替代 CLI 的 models.list RPC——不会回退到服务器。

有关 Python、Go 和 .NET 示例，请参见 BYOK（位于 github/copilot-sdk 仓库）。Java 示例请参见 github/copilot-sdk-java 仓库。

限制

身份限制

BYOK 认证仅支持静态凭证。以下身份提供商不受支持：

  • Microsoft Entra ID（Azure AD）——不支持 Entra 托管身份或服务主体。
  • 第三方身份提供商——不支持 OIDC、SAML 或其他联合身份。
  • 托管身份——不支持 Azure 托管身份。

必须使用你自行管理的 API 密钥或静态 Bearer Token。

注意

虽然 Entra ID 会颁发 Bearer Token，但这些 Token 短期有效（通常约一小时），且需要通过 Azure Identity SDK 自动刷新。bearerToken 选项仅接受静态字符串——没有回调机制让 SDK 自动获取新 Token。对于需要长期运行且依赖 Entra 认证的工作负载，你必须自行实现 Token 刷新逻辑并使用更新后的 Token 创建新会话。

功能限制

某些 Copilot 功能在 BYOK 环境下可能表现不同

  • 模型可用性：仅限你的提供商支持的模型。
  • 速率限制：受限于你的提供商的速率限制，而非 Copilot 本身。
  • 使用统计：由你的提供商追踪，而非 GitHub。
  • 高级请求：不计入 Copilot 的高级请求配额。

提供商特定限制

提供商限制
Azure AI Foundry不支持 Entra ID 认证；必须使用 API 密钥。
Ollama无 API 密钥；仅本地；模型支持视具体实现而定。
Microsoft Foundry Local仅本地；模型可用性取决于设备硬件；不需要 API 密钥。
OpenAI受 OpenAI 速率限制和配额约束。

故障排除

"未指定模型" 错误

使用 BYOK 时，model 参数是必需的

// Error: model required with custom provider
const session = await client.createSession({
    provider: { type: "openai", baseUrl: "..." },
});

// Correct: model specified
const session = await client.createSession({
    model: "gpt-4",
    provider: { type: "openai", baseUrl: "..." },
});

Azure 端点类型混淆

针对 Azure OpenAI 端点（*.openai.azure.com），请确保使用正确的提供商类型

// Wrong: using "openai" type with native Azure endpoint
provider: {
    type: "openai",
    baseUrl: "https://YOUR-RESOURCE.openai.azure.com",
}

// Correct: using "azure" type
provider: {
    type: "azure",
    baseUrl: "https://YOUR-RESOURCE.openai.azure.com",
}

如果你的 Azure AI Foundry 部署提供了兼容 OpenAI 的端点路径（例如 /openai/v1/），请改用 type: "openai"

// Correct: OpenAI-compatible Azure AI Foundry endpoint
provider: {
    type: "openai",
    baseUrl: "https://YOUR-RESOURCE.openai.azure.com/openai/v1/",
}

连接被拒绝（Ollama）

确保 Ollama 正在运行并且可访问

Bash
# Check Ollama is running
curl https://:11434/v1/models

# Start Ollama if not running
ollama serve

连接被拒绝（Foundry Local）

Foundry Local 使用的端口是动态的，重启后可能会变化。请确认当前活动端口

Bash
foundry service status

将你的 baseUrl 更新为输出中显示的端口。如服务未启动，请先启动模型以启动服务

Bash
foundry model run phi-4-mini

身份验证失败

  1. 确认你的 API 密钥正确且未过期。
  2. 检查 baseUrl 是否符合提供商要求的格式。
  3. 对于 Bearer Token，请确保提供完整的 Token，而不是仅仅前缀。
© . This site is unofficial and not affiliated with GitHub, Inc.