GitHub Copilot SDK 的 BYOK 模式：使用自有 API Key 接入 OpenAI、Azure、Anthropic 与本地模型

GitHub Copilot SDK 的 BYOK 模式使用自有 API Key 接入 OpenAI、Azure、Anthropic 与本地模型【免费下载链接】copilot-sdkMulti-platform SDK for integrating GitHub Copilot Agent into apps and services项目地址: https://gitcode.com/GitHub_Trending/co/copilot-sdk导读BYOKBring Your Own Key自带密钥是 GitHub Copilot SDK 提供的一种认证模式开发者跳过 GitHub Copilot 认证链路直接使用自己从 OpenAI、Microsoft FoundryAzure OpenAI、Anthropic、Ollama 等模型提供商获取的 API Key 或 Bearer Token 来驱动会话。它特别适合企业私有化部署、自定义模型托管以及希望与模型提供商直接结算的场景。读完本文你将掌握 BYOK 的完整配置模型ProviderConfig、五种语言的接入代码、wireApi传输协议选择、Bearer Token 动态获取回调以及自定义模型列表与常见故障排查方法。什么是 BYOK在默认的 GitHub Copilot 认证流程中SDK 会使用 GitHub 账号凭证如 Copilot CLI 存储的凭据、环境变量中的 GitHub Token 或显式传入的 SDK Token访问 Copilot API。而 BYOK 模式完全绕开这条链路应用在创建会话时显式传入一个provider配置SDK 运行时直接向你所指定的模型提供商端点发起请求。这意味着计费归属请求费用直接计入你的模型提供商账户而非 GitHub Copilot 配额模型自主权可用模型完全由你的提供商决定不受 GitHub Copilot 模型列表限制部署灵活性既可以对接云端 API也可以对接本机运行的 Ollama、Microsoft Foundry Local 等本地推理服务。从源码结构看BYOK 的核心载体是各语言 SDK 中的ProviderConfig类型如 Go 的 ProviderConfig、Node.js 的 ProviderConfig它承载了端点地址、凭据、传输协议等一系列字段是连接 SDK 与外部模型服务的接线端子。支持的提供商一览ProviderType Value说明OpenAIopenaiOpenAI 官方 API 及任何 OpenAI 兼容端点Microsoft Foundry / Azure OpenAIopenai或azure走/openai/v1/兼容路径用openai走 Azure 原生端点用azureAnthropicanthropicClaude 系列模型Ollamaopenai通过 OpenAI 兼容 API 访问本地模型Microsoft Foundry Localopenai在本机设备上通过 OpenAI 兼容 API 运行 AI 模型其他 OpenAI 兼容服务openaivLLM、LiteLLM 等可以看出openai是覆盖面最广的类型只要端点对外暴露的是 OpenAI 兼容协议都可以用它接入。ProviderConfig 配置参考创建 BYOK 会话时provider参数接受以下字段字段类型说明typeopenai|azure|anthropic提供商类型默认openaibaseUrl/base_urlstring必填。API 端点 URLapiKey/api_keystringAPI Key本地提供商如 Ollama 可省略bearerToken/bearer_tokenstringBearer Token 认证优先级高于apiKeybearerTokenProvider/bearer_token_providercallback按需返回 Bearer Token 的回调优先级高于apiKey和bearerTokenwireApi/wire_apicompletions|responses选择 Chat Completions API 以获得广泛模型兼容性或选择 Responses API 以获得多轮状态管理、工具命名空间与推理支持。Anthropic 模型不受此字段影响始终走 Messages APIazure.apiVersion/azure.api_versionstringAzure API 版本。设置后运行时使用带版本的部署路由省略时使用 GA 的v1无版本路由在 SDK 源码中这一配置模型还有若干未写入文档的扩展字段理解它们有助于深度调优transporthttp/websockets仅对 OpenAI 兼容提供商且wireApi: responses生效。设为websockets后Responses API 请求通过持久 WebSocket 连接传输适合长时间运行、工具调用密集且依赖previous_response_id增量续接的会话见 Node.js 类型定义 与 Go 类型定义默认值为httpheaders附加到所有出站提供商请求的自定义 HTTP 头modelId/wire_modelmodelId是运行时用于查找 Agent 配置工具、提示词、推理行为与默认 token 上限的已知模型名wireModel是实际发送给提供商进行推理的模型名适合提供商模型名如 Azure 部署名、自定义微调名与标准模型名不一致的场景缺省时依次回退到modelId、SessionConfig.modelmaxPromptTokens/maxOutputTokens覆盖模型默认的提示词/输出 token 上限前者触发会话压缩的阈值后者决定生成被截断的边界transport之外SDK 各语言会对字段名做 snake_case / camelCase 的自动映射例如 Python 的base_url、wire_api会转换成线上的baseUrl、wireApi见 Python 客户端实现。wireApi选择 Chat Completions 还是 ResponseswireApi决定 SDK 以何种 OpenAI 协议格式与提供商通信completions默认使用 Chat Completions API/chat/completions兼容面最广几乎任何 OpenAI 兼容服务都支持responses使用 Responses API提供多轮状态管理、工具命名空间和推理支持适合 GPT-5 系列等较新模型。Anthropic 模型则不受此设置影响只要type: anthropicSDK 始终使用 Anthropic Messages API。快速开始接入 Microsoft FoundryMicrosoft Foundry 是企业 BYOK 部署的常见目标。下面给出完整示例以gpt-5.2-codex为部署名FOUNDRY_API_KEY从环境变量读取Pythonimport asyncio import os from copilot import CopilotClient from copilot.session import PermissionHandler FOUNDRY_MODEL_URL https://resource-name.openai.azure.com/openai/v1/ # 设置 FOUNDRY_API_KEY 环境变量 async def main(): client CopilotClient() await client.start() session await client.create_session(on_permission_requestPermissionHandler.approve_all, modelgpt-5.2-codex, provider{ type: openai, base_url: FOUNDRY_MODEL_URL, wire_api: responses, # 旧模型使用 completions api_key: os.environ[FOUNDRY_API_KEY], }) done asyncio.Event() def on_event(event): if event.type.value assistant.message: print(event.data.content) elif event.type.value session.idle: done.set() session.on(on_event) await session.send(What is 22?) await done.wait() await session.disconnect() await client.stop() asyncio.run(main())Node.js / TypeScriptimport { CopilotClient } from github/copilot-sdk; const FOUNDRY_MODEL_URL https://resource-name.openai.azure.com/openai/v1/; const client new CopilotClient(); const session await client.createSession({ model: gpt-5.2-codex, // 你的部署名 provider: { type: openai, baseUrl: FOUNDRY_MODEL_URL, wireApi: responses, // 旧模型使用 completions apiKey: process.env.FOUNDRY_API_KEY, }, }); session.on(assistant.message, (event) { console.log(event.data.content); }); await session.sendAndWait({ prompt: What is 22? }); await client.stop();Gopackage main import ( context fmt os copilot github.com/github/copilot-sdk/go ) func main() { ctx : context.Background() client : copilot.NewClient(nil) if err : client.Start(ctx); err ! nil { panic(err) } defer client.Stop() session, err : client.CreateSession(ctx, copilot.SessionConfig{ Model: gpt-5.2-codex, // 你的部署名 Provider: copilot.ProviderConfig{ Type: openai, BaseURL: https://resource-name.openai.azure.com/openai/v1/, WireAPI: responses, // 旧模型使用 completions APIKey: os.Getenv(FOUNDRY_API_KEY), }, }) if err ! nil { panic(err) } response, err : session.SendAndWait(ctx, copilot.MessageOptions{ Prompt: What is 22?, }) if err ! nil { panic(err) } if d, ok : response.Data.(*copilot.AssistantMessageData); ok { fmt.Println(d.Content) } }.NETusing GitHub.Copilot; await using var client new CopilotClient(); await using var session await client.CreateSessionAsync(new SessionConfig { Model gpt-5.2-codex, // 你的部署名 Provider new ProviderConfig { Type openai, BaseUrl https://resource-name.openai.azure.com/openai/v1/, WireApi responses, // 旧模型使用 completions ApiKey Environment.GetEnvironmentVariable(FOUNDRY_API_KEY), }, }); var response await session.SendAndWaitAsync(new MessageOptions { Prompt What is 22?, }); Console.WriteLine(response?.Data.Content);Javaimport com.github.copilot.CopilotClient; import com.github.copilot.rpc.*; var client new CopilotClient(); client.start().get(); var session client.createSession(new SessionConfig() .setModel(gpt-5.2-codex) // 你的部署名 .setOnPermissionRequest(PermissionHandler.APPROVE_ALL) .setProvider(new ProviderConfig() .setType(openai) .setBaseUrl(https://resource-name.openai.azure.com/openai/v1/) .setWireApi(responses) // 旧模型使用 completions .setApiKey(System.getenv(FOUNDRY_API_KEY))) ).get(); var response session.sendAndWait(new MessageOptions() .setPrompt(What is 22?)).get(); System.out.println(response.getData().content()); client.stop().get();五种语言的调用骨架高度一致启动客户端 → 以provider配置创建会话 → 发送消息并消费事件/响应 → 停止客户端。唯一差异在于事件模型的表达方式Python 与 TypeScript 使用事件回调assistant.message、session.idleGo、.NET、Java 使用同步的SendAndWait风格调用。分类型配置示例OpenAI 直连provider: { type: openai, baseUrl: https://api.openai.com/v1, apiKey: process.env.OPENAI_API_KEY, }注意baseUrl需要包含完整路径含/v1。Azure OpenAIAzure 原生端点对*.openai.azure.com端点使用type: azureprovider: { type: azure, baseUrl: https://my-resource.openai.azure.com, // 仅主机名 apiKey: process.env.AZURE_OPENAI_KEY, azure: { apiVersion: 2024-10-21, }, }关键区别baseUrl只写主机名不要包含/openai/v1路径——SDK 会根据apiVersion自动构造请求路由设置azure.apiVersion时走带版本的部署路由省略时走 GA 的v1无版本路由。Microsoft FoundryOpenAI 兼容端点如果 Foundry 部署暴露的是/openai/v1/兼容路径则改用type: openaiprovider: { type: openai, baseUrl: https://resource-name.openai.azure.com/openai/v1/, apiKey: process.env.FOUNDRY_API_KEY, wireApi: responses, // GPT-5 系列模型 }Ollama本地provider: { type: openai, baseUrl: http://localhost:11434/v1, // 本地 Ollama 无需 apiKey }Microsoft Foundry LocalFoundry Local 让你在自己设备上本地运行 AI 模型同样暴露 OpenAI 兼容 API。通过 Foundry Local CLI 安装后把 SDK 指向本地端点provider: { type: openai, baseUrl: http://localhost:PORT/v1, // 本地 Foundry Local 无需 apiKey }[!NOTE] Foundry Local 启动在动态端口上——端口号不固定。使用foundry service status确认服务当前监听的端口再将其填入baseUrl。快速上手 Foundry Local# Windows安装 Foundry Local CLI需要 winget winget install Microsoft.FoundryLocal # macOS / Linux参见 foundrylocal.ai 的安装说明 # 列出可用模型 foundry model list # 运行模型会自动启动本地服务 foundry model run phi-4-mini # 查看服务运行端口 foundry service statusAnthropicprovider: { type: anthropic, baseUrl: https://api.anthropic.com, apiKey: process.env.ANTHROPIC_API_KEY, }Anthropic 模型始终使用 Claude 专属的 Messages API 格式不受wireApi影响。认证方式静态 API Key 与 Bearer Token部分提供商要求 Bearer Token 认证而非 API Key。SDK 提供两种方式静态 Bearer TokenbearerToken适用于应用已经持有 token 的场景provider: { type: openai, baseUrl: https://resource-name.openai.azure.com/openai/v1/, bearerToken: process.env.MY_BEARER_TOKEN, // 设置 Authorization 头 }[!NOTE]bearerToken只接受静态 token 字符串。SDK 不会自动刷新该 token。如果 token 过期请求会失败你需要用新 token 重新创建会话。动态 Bearer Token 回调bearerTokenProvider对于需要按需获取、自动续期的场景典型如 Microsoft Entra ID / Azure Managed Identity使用回调provider: { type: openai, baseUrl: https://my-custom-endpoint.example.com/v1, bearerTokenProvider: async () { return await acquireBearerToken(); }, }从源码看这是一个回调留在客户端、运行时按需回拨的设计SDK 不会把回调本身序列化进 RPC 配置而是发送hasBearerTokenProvider: true标志运行时在每次出站模型请求前通过会话级的providerToken.getTokenRPC 回调到客户端获取 token并将其作为Authorization: Bearer头应用见 Go 实现 与 Node.js 类型定义。回调还接收providerName与sessionId上下文参数便于按提供商或按会话区分 token 的作用域与缓存。SDK 自身不做 token 缓存缓存与刷新逻辑由回调或其所包裹的身份库如DefaultAzureCredential负责。关于使用 Microsoft Entra Bearer Token 获取与刷新的详细流程参见 Azure Managed Identity with BYOK。自定义模型列表onListModels使用 BYOK 时CLI 服务端并不知道你的提供商支持哪些模型。此时可以在客户端级别提供onListModels处理器让client.listModels()返回你的提供商模型标准ModelInfo格式下游消费者无需查询 CLI 即可发现可用模型。Node.js / TypeScriptimport { 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 }, }, }, ], });Pythonfrom copilot import CopilotClient from copilot.client import ModelInfo, ModelCapabilities, ModelSupports, ModelLimits client CopilotClient( on_list_modelslambda: [ ModelInfo( idmy-custom-model, nameMy Custom Model, capabilitiesModelCapabilities( supportsModelSupports(visionFalse, reasoning_effortFalse), limitsModelLimits(max_context_window_tokens128000), ), ) ], )Gopackage main import ( context copilot github.com/github/copilot-sdk/go ) func main() { client : copilot.NewClient(copilot.ClientOptions{ OnListModels: func(ctx context.Context) ([]copilot.ModelInfo, error) { return []copilot.ModelInfo{ { ID: my-custom-model, Name: My Custom Model, Capabilities: copilot.ModelCapabilities{ Supports: copilot.ModelSupports{Vision: false, ReasoningEffort: false}, Limits: copilot.ModelLimits{MaxContextWindowTokens: copilot.Int(128000)}, }, }, }, nil }, }) _ client }.NETusing GitHub.Copilot; var client new CopilotClient(new CopilotClientOptions { OnListModels (ct) Task.FromResultIListModelInfo(new ListModelInfo { new() { Id my-custom-model, Name My Custom Model, Capabilities new ModelCapabilities { Supports new ModelSupports { Vision false, ReasoningEffort false }, Limits new ModelLimits { MaxContextWindowTokens 128000 } } } }) });Javaimport com.github.copilot.CopilotClient; import com.github.copilot.rpc.*; import java.util.List; import java.util.concurrent.CompletableFuture; var client new CopilotClient(new CopilotClientOptions() .setOnListModels(() - CompletableFuture.completedFuture(List.of( new ModelInfo() .setId(my-custom-model) .setName(My Custom Model) .setCapabilities(new ModelCapabilities() .setSupports(new ModelSupports().setVision(false).setReasoningEffort(false)) .setLimits(new ModelLimits().setMaxContextWindowTokens(128000))) ))) );需要注意两点行为语义结果缓存首次调用后结果即被缓存与默认行为一致完全接管该处理器会完整替换 CLI 的models.listRPC——不会回退到服务端。从 Node.js 客户端实现 可以看到listModels()检测到自定义处理器存在时直接调用它并返回结果。限制与注意事项功能层面的差异模型可用性只有你的提供商支持的模型可用限流策略受你的提供商限流约束而非 GitHub Copilot 的限流用量统计用量由你的提供商统计而非 GitHub CopilotPremium 请求BYOK 请求不计入 Copilot premium 请求配额。各提供商特定限制Provider限制Microsoft Foundry Local仅限本地模型可用性取决于设备硬件无需 API KeyOllama无 API Key仅限本地模型支持程度不一OpenAI受 OpenAI 限流与配额约束故障排查Model not specified 错误使用 BYOK 时model参数是必填的// ❌ 错误使用自定义 provider 时必须指定模型 const session await client.createSession({ provider: { type: openai, baseUrl: ... }, }); // ✅ 正确指定模型 const session await client.createSession({ model: gpt-4, // 必填 provider: { type: openai, baseUrl: ... }, });Azure 端点类型混淆对 Azure OpenAI 端点*.openai.azure.com要使用正确的类型// ❌ 错误Azure 原生端点使用 openai 类型 provider: { type: openai, // 无法正常工作 baseUrl: https://my-resource.openai.azure.com, } // ✅ 正确使用 azure 类型 provider: { type: azure, baseUrl: https://my-resource.openai.azure.com, }但如果你的 Microsoft Foundry 部署提供 OpenAI 兼容端点路径例如/openai/v1/则应使用type: openai// ✅ 正确OpenAI 兼容的 Microsoft Foundry 端点 provider: { type: openai, baseUrl: https://your-resource.openai.azure.com/openai/v1/, }连接被拒绝Ollama确认 Ollama 正在运行且可访问# 检查 Ollama 是否运行 curl http://localhost:11434/v1/models # 未运行时启动 ollama serve连接被拒绝Foundry LocalFoundry Local 使用动态端口重启后可能变化。确认当前端口# 查看服务状态与端口 foundry service status根据输出更新baseUrl中的端口。如果服务未运行启动一个模型即可拉起服务foundry model run phi-4-mini认证失败确认 API Key 正确且未过期检查baseUrl是否符合你的提供商预期格式尤其注意 Azure 原生端点不要带/openai/v1对于 Bearer Token确保提供完整的 token而非仅前缀。进一步探索BYOK 只是 GitHub Copilot SDK 的认证方式之一SDK 还支持显式 Token、环境变量 GitHub Token、Copilot CLI 凭据等认证路径完整对比见 认证总览 与 Authenticate Copilot SDK若你的场景是在 GitHub Actions 或 GitHub App 中以组织身份运行自动化可参考 服务端到服务端认证。入门构建第一个 Copilot 应用参见 Getting Started 指南。【免费下载链接】copilot-sdkMulti-platform SDK for integrating GitHub Copilot Agent into apps and services项目地址: https://gitcode.com/GitHub_Trending/co/copilot-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考