准备账号
创建 UniKeyX API Key
登录 UniKeyX 控制台, 在令牌或 API Key 页面创建密钥,并确认目标模型在当前账号中可用。建议 GPT 和 Claude 各使用一个 Key,便于独立管理额度和排查问题。
- 打开 UniKeyX 控制台并登录账号。
- 新建 API Key,复制一次并保存到密码管理器。
- 不要把 API Key 提交到 Git 仓库、截图、聊天记录或共享配置文件。
- 准备 GitHub Copilot App、GitHub Desktop 或 Copilot CLI;不同客户端的入口见下文。
最重要的一步
按模型选择正确的协议
GPT 系列选择 OpenAI / OpenAI-compatible;Claude 系列选择 Anthropic。
UniKeyX 页面中的“Azure Claude”表示 Claude 的 Azure 线路,不等于 GitHub Copilot 设置里的“Azure OpenAI”类型。
OpenAI / OpenAI-compatibleBase URL:
https://www.unikeyx.com/v1API 格式:
Chat completions模型 ID:
gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-5.5
AnthropicBase URL:
https://www.unikeyx.comAPI 格式:Anthropic Messages(请求路径为
/v1/messages)模型 ID:
claude-sonnet-5、claude-opus-4-6、claude-opus-4-7、claude-opus-4-8
gpt-5.6-sol
适合复杂代码、架构分析、长步骤推理和高难度 Agent 任务。
gpt-5.6-terra
在能力、速度和成本之间取平衡,适合日常开发。
gpt-5.6-luna
适合高频调用、快速修改和成本敏感的编码任务。
claude-sonnet-5
适合代码阅读、重构、分析、Agent 工作流和持续对话。
模型目录和权限会随 UniKeyX 控制台调整。模型 ID 必须与控制台显示完全一致,不要自行添加 azure-、openai/ 等前缀。
桌面应用
GitHub Copilot App 接入
GitHub Copilot App 支持通过 BYOK 添加自定义模型提供商。不同版本的界面文字可能略有变化;核心字段始终是提供商、Base URL、认证信息和模型 ID。
- 打开 GitHub Copilot App,进入应用设置。
- 打开 Model providers,点击 Add provider。
- 配置 GPT 时选择 Any OpenAI-compatible HTTP endpoint,填写
https://www.unikeyx.com/v1。 - 配置 Claude 时选择 Anthropic,填写
https://www.unikeyx.com。 - 认证方式选择 API Key 或 Bearer token(以当前界面显示为准),粘贴 UniKeyX API Key。
- 添加模型 ID,例如
gpt-5.6-sol或claude-sonnet-5,保存提供商。 - 回到会话,在模型选择器中选中刚添加的模型后再开始任务。
GitHub Copilot App 的自定义提供商功能处于公开预览阶段,菜单名称可能变化。凭据应由应用保存到系统凭据存储中,不要把 Key 写进项目文件。
GitHub Desktop
在 GitHub Desktop 中添加两个模型提供商
- 打开 GitHub Desktop,进入 Settings(macOS 为 GitHub Desktop → Settings)。
- 打开左侧 Copilot,切换到 Providers,点击 Add Provider。
- 按下面两个配置分别添加 GPT 和 Claude。建议不要把两种协议放在同一个提供商里。
- 保存后,在 Copilot 的模型选择处选择对应模型,再用于提交说明、冲突解决等功能。
Type:OpenAI / OpenAI-compatible
Base URL: https://www.unikeyx.com/v1
API Format:Chat completions
Authentication:Bearer token
Models:gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-5.5
Type:Anthropic
Base URL: https://www.unikeyx.com
Authentication:Bearer token
Models:claude-sonnet-5、claude-opus-4-6、claude-opus-4-7、claude-opus-4-8
GitHub Desktop 的 Azure provider 主要用于 Azure OpenAI。即使模型名称带有 Azure,UniKeyX 的 Claude 仍应选择 Anthropic。
命令行
Copilot CLI 配置(Windows PowerShell)
Copilot CLI 使用环境变量选择自定义提供商。下面的配置只在当前 PowerShell 窗口生效,适合先验证;确认可用后,再按团队安全规范保存凭据。
$env:COPILOT_PROVIDER_TYPE = "openai"
$env:COPILOT_PROVIDER_BASE_URL = "https://www.unikeyx.com/v1"
$env:COPILOT_PROVIDER_API_KEY = "YOUR_UNIKEYX_API_KEY"
$env:COPILOT_MODEL = "gpt-5.6-sol"
copilot
$env:COPILOT_PROVIDER_TYPE = "anthropic"
$env:COPILOT_PROVIDER_BASE_URL = "https://www.unikeyx.com"
$env:COPILOT_PROVIDER_API_KEY = "YOUR_UNIKEYX_API_KEY"
$env:COPILOT_MODEL = "claude-sonnet-5"
copilot
从 GPT 切换到 Claude 时,必须同时修改 COPILOT_PROVIDER_TYPE、COPILOT_PROVIDER_BASE_URL 和 COPILOT_MODEL。
如果只改模型名,常见结果是 500、not implemented 或 convert_request_failed。
macOS / Linux 写法
export COPILOT_PROVIDER_TYPE=openai
export COPILOT_PROVIDER_BASE_URL=https://www.unikeyx.com/v1
export COPILOT_PROVIDER_API_KEY=YOUR_UNIKEYX_API_KEY
export COPILOT_MODEL=gpt-5.6-sol
copilot
export COPILOT_PROVIDER_TYPE=anthropic
export COPILOT_PROVIDER_BASE_URL=https://www.unikeyx.com
export COPILOT_PROVIDER_API_KEY=YOUR_UNIKEYX_API_KEY
export COPILOT_MODEL=claude-sonnet-5
copilot
团队 / 企业
组织管理员的统一配置
如果组织使用 GitHub Copilot Business 或 Enterprise,管理员可以在 GitHub 的组织或企业设置中配置自定义模型,并让 Copilot Chat、Copilot CLI 和 IDE 使用这些模型。
- 进入 GitHub 组织或企业的 Copilot 管理设置,打开自定义模型或 BYOK 配置。
- 为 GPT 添加 OpenAI-compatible provider,Base URL 使用
https://www.unikeyx.com/v1,添加需要开放的 GPT 模型 ID。 - 为 Claude 单独添加 Anthropic provider,Base URL 使用
https://www.unikeyx.com,添加需要开放的 Claude 模型 ID。 - 完成组织策略、模型可见范围和密钥权限设置后,让成员重新打开 Copilot 客户端。
个人客户端可以本地配置自己的 UniKeyX Key;组织管理员配置则由 GitHub 组织策略统一控制。两者的菜单、可用客户端和计费归属可能不同,请以当前 GitHub 管理页面为准。
完成接入
用最小测试确认请求已走 UniKeyX
保存配置并完全退出、重新打开对应 Copilot 客户端。
在模型选择器中确认显示的是 UniKeyX 提供商下的目标模型。
发送测试指令:只返回 pong,不要添加其他文字。
再发送一个小型代码任务,确认代码上下文、工具调用和流式输出都正常。
copilot -p "Return exactly: pong"
随后再测试代码补全、代码解释、提交说明或 Agent 任务;不要一开始就用大仓库长任务排查连接问题。
Troubleshooting
常见问题
401 Unauthorized
检查 API Key 是否填写、是否已失效,以及请求是否使用 Authorization: Bearer。不要把 GitHub 登录凭据、Copilot 会话令牌或其他平台 Key 当作 UniKeyX API Key。
提示 model not found 或模型不显示
模型 ID 必须完全匹配控制台,例如 gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-5.5 或 claude-sonnet-5。
同时确认当前 API Key 已获得该模型权限。
Claude 返回 500、not implemented 或 convert_request_failed
先检查提供商类型:Claude 必须使用 Anthropic,Base URL 使用 https://www.unikeyx.com;不要把 Claude 放进 OpenAI Responses 配置,也不要选择 GitHub Copilot 的 Azure OpenAI 类型。
GPT 可以用,Claude 不可以
这通常是协议配置不匹配,而不是账号整体失效。为 Claude 新建独立 Anthropic provider,并使用 claude-sonnet-5 等控制台中的精确模型 ID。
修改环境变量后 Copilot 仍使用旧模型
关闭当前 CLI 窗口并重新打开;如果同时设置过 GPT 和 Claude 的变量,请检查 COPILOT_PROVIDER_TYPE、COPILOT_PROVIDER_BASE_URL、COPILOT_PROVIDER_API_KEY 和 COPILOT_MODEL 是否来自同一套配置。
请求超时或长任务中断
先用短提示词验证连接,再逐步增加仓库上下文。GitHub Desktop 可以在提供商设置中增加 Request Timeout;同时检查 UniKeyX 账号额度、模型权限和当前网络连接。
如何保护 API Key
App 和 Desktop 优先使用其系统凭据存储;CLI 先用当前窗口环境变量验证,长期使用时使用操作系统凭据管理或安全的用户级变量。不要把真实 Key 写入仓库、脚本、截图或公共文档。
官方参考: GitHub Copilot App BYOK · GitHub Desktop Copilot · Copilot CLI BYOK