# GitHub Copilot 接入

> **最后核实**：2026-09-18 · 📄 依据官方文档（VS Code 1.138.0 / 内置 Copilot 扩展 0.66.0，Copilot CLI v1.0.86 2026-09-17 发布）

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | Claude ✅（仅 `messages` 类型）· GPT ✅（Chat / Responses）· 国产 ✅（Chat）· Gemini ❌（无该协议选项） |
| 协议与 Base URL | VS Code 的 `url` 填**完整路径**：`https://api.qcode.cc/api/v1/messages` · `https://api.qcode.cc/openai/v1/chat/completions` · `https://api.qcode.cc/openai/v1/responses`；CLI 只填**根地址**（见路径 B） |
| 配置位置 | VS Code：命令面板 `Chat: Manage Language Models` → `chatLanguageModels.json`；CLI：环境变量 |
| 官方文档 | [VS Code 语言模型](https://code.visualstudio.com/docs/agent-customization/language-models) · [Copilot CLI BYOK](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/use-byok-models) |

## 前提条件

- **路径 A**：VS Code ≥ 1.122（Custom Endpoint 于 2026-05-28 进入 Stable）。
- **路径 B**：已安装 GitHub Copilot CLI。
- 一把 QCode.cc 的 `cr_` 密钥（[控制台](https://qcode.cc/dashboard)创建）。模型按 QCode 的 token 计费，与 Copilot 订阅费用是两回事（见 [订阅、官方 API 与 QCode Key](/docs/reference/subscription-vs-api-key)）。

## 配置步骤

### 路径 A：VS Code Custom Endpoint（推荐）

打开命令面板（`Ctrl/Cmd+Shift+P`）→ **`Chat: Manage Language Models`** → 选择 **Custom Endpoint**，VS Code 会打开 `chatLanguageModels.json` 让你编辑。三条官方规则：

- `vendor` 必须是 `customendpoint`；密钥字段叫 `apiKey`。
- `apiType` 三个合法取值：`messages`（Anthropic 协议）、`chat-completions`、`responses`。**Claude 模型只能用 `messages`**。
- `url` 填**含路径的完整请求地址**（官方建议）；不填完整路径时 VS Code 会自动插 `/v1`，很容易拼出 404。
- 想在 Agent 模式里用，必须 `"toolCalling": true`，否则模型不进选择器。

Claude + GPT/国产两个端点并存的示例：

```json
[
  { "name": "QCode Claude", "vendor": "customendpoint", "apiKey": "cr_your-QCode-key",
    "apiType": "messages",
    "url": "https://api.qcode.cc/api/v1/messages",
    "toolCalling": true,
    "models": [ { "id": "claude-sonnet-5" } ] },
  { "name": "QCode OpenAI", "vendor": "customendpoint", "apiKey": "cr_your-QCode-key",
    "apiType": "chat-completions",
    "url": "https://api.qcode.cc/openai/v1/chat/completions",
    "toolCalling": true,
    "models": [ { "id": "gpt-5.6" }, { "id": "glm-5.3" } ] }
]
```

GPT 走 Responses 协议（Codex 那条腿，只服务 GPT 系）：

```json
[
  { "name": "QCode Responses", "vendor": "customendpoint", "apiKey": "cr_your-QCode-key",
    "apiType": "responses",
    "url": "https://api.qcode.cc/openai/v1/responses",
    "toolCalling": true,
    "models": [ { "id": "gpt-5.6" } ] }
]
```

保存后在聊天面板的模型选择器里就能见到这些模型。

### 路径 B：Copilot CLI 的 BYOK

Copilot CLI 用四个环境变量声明一个自带模型，`COPILOT_PROVIDER_TYPE` 官方取值仅三种：`openai`（默认）、`azure`、`anthropic`。接 QCode 的 Anthropic 腿：

```bash
# Anthropic Messages route — base URL is the ROOT, no path appended
export COPILOT_PROVIDER_TYPE=anthropic
export COPILOT_PROVIDER_BASE_URL="https://api.qcode.cc/api"
export COPILOT_PROVIDER_API_KEY="cr_your-QCode-key"
export COPILOT_MODEL="claude-sonnet-5"

# OpenAI-compatible route — base URL includes /v1 but not /chat/completions
export COPILOT_PROVIDER_TYPE=openai
export COPILOT_PROVIDER_BASE_URL="https://api.qcode.cc/openai/v1"
export COPILOT_PROVIDER_API_KEY="cr_your-QCode-key"
export COPILOT_MODEL="gpt-5.6"
```

两组变量二选一（后写的覆盖先写的）：上面第一组接 Claude（Anthropic 腿），第二组接 GPT / 国产模型（OpenAI 兼容腿，base URL 形态**只到 `/v1`**，与路径 A 相反）。

🔴 这是本页最容易踩的坑：**VS Code 的 `url` 要写到完整路径，CLI 的 `BASE_URL` 只写根地址**——两处形态相反，照抄必错。

### JetBrains 里的 Copilot

GitHub 官方把 JetBrains 列为支持本地 BYOK 的客户端之一，Custom Endpoint（OpenAI 兼容）自 2026-07-14 起支持，入口在 Copilot 的 **Manage Models**。字段级细节官方尚未公开文档化，接入 QCode 的 OpenAI 兼容腿时按该入口的提示填写；Anthropic 类型在 JetBrains 端是否可用未在官方页确认。以 [GitHub Copilot 文档](https://docs.github.com/copilot)为准。

## 验证是否接通

在 Copilot Chat（或 `copilot` CLI）里选中自定义模型发一句话：

- 返回内容 = 接通。
- `401` = `apiKey` / `COPILOT_PROVIDER_API_KEY` 没填对（`cr_` 前缀完整）。
- `404` = `url` 路径形态错了——对照上表：VS Code 补全路径、CLI 退回根地址。
- 每次请求可在 [probe.qcode.cc](https://probe.qcode.cc) 按密钥查到。排查顺序见 [故障排查](/docs/reference/troubleshooting)。

## 已知限制

- **行内补全仍走 GitHub 后端**：Custom Endpoint / BYOK 只作用于 Chat 与 Agent 场景（官方边界说明）。
- **没有 Gemini 协议选项**：`apiType` 不含 Gemini，接不了 `gemini-*` 模型；要 Gemini 用别的客户端（见 [工具兼容总览](/docs/ide/tool-compatibility)）。
- 组织策略可能禁用自定义模型端点；企业账号先确认策略。
- Anthropic 腿的 `messages` 路径（`/api/v1/messages`）为完整 URL 写法下的形态；若你的 VS Code 版本行为不同（自动插 `/v1` 之类），以 404/400 报错对照上面「验证」一节修正。
- 端点支持能力（vision 等）可在条目里用 `vision` / `maxInputTokens` / `maxOutputTokens` 等字段声明，语义见官方页。

## 相关文档

- [VS Code 集成（Claude Code 扩展）](/docs/ide/vscode)
- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)
- [工具兼容总览](/docs/ide/tool-compatibility)
- [订阅、官方 API 与 QCode Key](/docs/reference/subscription-vs-api-key)
- [JetBrains IDE 集成](/docs/ide/jetbrains)