> ## Documentation Index
> Fetch the complete documentation index at: https://docs.haitoken.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Copilot

> 通过 HaiToken 接入 GitHub Copilot 相关工作流

这里的 `Copilot` 需要区分两种接入方式，因为它们不是同一条配置链路：

1. **VS Code / Copilot Chat BYOK**：在 VS Code 的语言模型管理界面里接入自定义模型
2. **Copilot CLI BYOK**：在终端里通过环境变量指定外部模型提供方

两种方式都可以接 HaiToken，但配置入口和限制并不完全一样。

## 先准备好这些信息

* HaiToken API Key
* 至少一个可用模型 ID，例如 `deepseek-v4-flash`
* HaiToken OpenAI 兼容地址：`https://api.haitoken.ai/v1`

## 方式一：通过 VS Code / Copilot Chat 接入

这一条路径适合你希望在 VS Code Chat 中使用 HaiToken 模型。

<Note>
  GitHub / VS Code 官方已经提供 BYOK 能力，但不同版本和套餐支持范围并不完全一致。对 OpenAI 兼容自定义端点来说，某些能力在部分版本中可能仍属于预览或仅在特定版本中可见。请以你当前版本实际看到的入口为准。
</Note>

### 步骤 1：打开语言模型管理界面

在 VS Code 中打开聊天模型选择器，进入 **Manage Language Models**，或者通过命令面板运行 **Chat: Manage Language Models**。

### 步骤 2：添加自定义模型或提供方

如果当前版本直接提供 **OpenAI Compatible** 入口，优先使用它。

如果当前版本没有这个入口，则需要按当前版本支持的方式添加模型提供方，例如：

* 使用内置 BYOK 提供方
* 安装语言模型 Provider 扩展后再接入

### 步骤 3：填写 HaiToken 配置

如果当前版本支持 OpenAI 兼容提供方，推荐按下面的值填写：

| 字段                  | 推荐填写值                                                  |
| ------------------- | ------------------------------------------------------ |
| API Type            | `chat-completions` 或当前版本对应的 OpenAI Chat Completions 选项 |
| Endpoint / Base URL | `https://api.haitoken.ai/v1`                           |
| API Key             | 你的 HaiToken API Key                                    |
| Model ID            | HaiToken 实际可用的模型 ID，例如 `deepseek-v4-flash`             |

### 步骤 4：在聊天模型选择器里切换模型

保存后回到 Chat 面板，在模型选择器里切换到刚刚添加的 HaiToken 模型。

### 补充说明

<Warning>
  这条接入路径主要覆盖 VS Code Chat / Agent 相关体验，不应直接理解为“所有 Copilot 功能都已经改走 HaiToken”。尤其是代码补全这类能力，官方文档明确说明不在 BYOK 覆盖范围内。
</Warning>

## 方式二：通过 Copilot CLI 接入

这条路径适合终端中的 `copilot` CLI。GitHub 官方对这条 BYOK 链路的环境变量说明比较明确，接 HaiToken 也更稳。

<Note>
  Copilot CLI 官方同时支持 `openai` 和 `anthropic` 两种 Provider 类型。对 HaiToken 来说，推荐优先使用 `openai`，但如果你明确要走 Claude / Anthropic 生态，也可以改用 `anthropic`。
</Note>

### 步骤 1：设置 Provider 环境变量

<Warning>
  如果你使用的是 Windows Terminal，要特别注意：不同 tab / pane 不会共享你在某个 PowerShell 会话里临时设置的环境变量。也就是说，你必须先在**同一个 shell**里设置 `COPILOT_*` 变量，再从这个 shell 直接启动 `copilot`，否则 Copilot CLI 可能继续使用默认模型或旧配置。
</Warning>

Windows PowerShell：

```powershell theme={null}
$env:COPILOT_PROVIDER_BASE_URL = "https://api.haitoken.ai/v1"
$env:COPILOT_PROVIDER_TYPE = "openai"
$env:COPILOT_PROVIDER_API_KEY = "YOUR_API_KEY"
$env:COPILOT_MODEL = "deepseek-v4-flash"
```

macOS / Linux：

```bash theme={null}
export COPILOT_PROVIDER_BASE_URL="https://api.haitoken.ai/v1"
export COPILOT_PROVIDER_TYPE="openai"
export COPILOT_PROVIDER_API_KEY="YOUR_API_KEY"
export COPILOT_MODEL="deepseek-v4-flash"
```

如果你明确要走 Claude / Anthropic 模式，可以改成下面这种写法：

Windows PowerShell：

```powershell theme={null}
$env:COPILOT_PROVIDER_BASE_URL = "https://api.haitoken.ai"
$env:COPILOT_PROVIDER_TYPE = "anthropic"
$env:COPILOT_PROVIDER_API_KEY = "YOUR_API_KEY"
$env:COPILOT_MODEL = "deepseek-v4-flash"
```

macOS / Linux：

```bash theme={null}
export COPILOT_PROVIDER_BASE_URL="https://api.haitoken.ai"
export COPILOT_PROVIDER_TYPE="anthropic"
export COPILOT_PROVIDER_API_KEY="YOUR_API_KEY"
export COPILOT_MODEL="deepseek-v4-flash"
```

### 步骤 2：启动 Copilot CLI

在同一个终端会话中启动：

```bash theme={null}
copilot
```

### 步骤 3：发送一条简单测试请求

输入一条简单问题，例如 `hello` 或让它解释当前文件作用。如果能够正常返回，说明 CLI 已经通过 HaiToken 工作。

### 补充说明

| 项目            | 说明                                                                                  |
| ------------- | ----------------------------------------------------------------------------------- |
| Provider Type | 推荐 `openai`；也可选 `anthropic`                                                         |
| Base URL      | `openai` 模式用 `https://api.haitoken.ai/v1`；`anthropic` 模式用 `https://api.haitoken.ai` |
| 鉴权头           | `Authorization: Bearer YOUR_API_KEY`                                                |
| 模型要求          | 官方说明模型应支持 streaming 和 tool calling                                                  |

如果你是在离线或隔离环境中使用，还可以按官方说明额外设置 `COPILOT_OFFLINE=true`，但这不影响 HaiToken 的基础接入写法。

### 不同系统下如何持久化环境变量

* Windows：通常写入 PowerShell Profile，或写入你自己的启动脚本
* macOS：如果你使用 `zsh`，通常写入 `~/.zshrc`
* Linux：如果你使用 `bash`，通常写入 `~/.bashrc`；如果使用 `zsh`，通常写入 `~/.zshrc`

## 验证步骤

1. 如果你走的是 VS Code Chat 路径，在模型选择器里切换到 HaiToken 模型后发送一条简单消息。
2. 如果你走的是 Copilot CLI 路径，在同一终端里启动 `copilot` 并发送一条简单消息。
3. 如果能够正常返回内容，说明接入成功。

## 如何切换模型

### VS Code / Copilot Chat

如果你走的是 VS Code / Copilot Chat 这条路径，直接回到聊天面板，在模型选择器里切换到另一个模型即可。

如果当前版本已经把 HaiToken 模型添加到了语言模型列表中，你可以在这里直接改成另一个模型，不需要重新配环境变量。

### Copilot CLI

如果你走的是 `copilot` CLI，这里要特别注意：**Copilot CLI 不是在会话里手动点选模型，而是读取启动前的环境变量。**

也就是说，切换模型的正确方法不是在已经打开的 `copilot` 会话里输入某个命令，而是：

1. 先退出当前 `copilot` 会话
2. 修改 `COPILOT_MODEL`
3. 在同一个 shell 里重新启动 `copilot`

Windows PowerShell 示例：

```powershell theme={null}
# 先退出当前 copilot 会话，然后执行：
$env:COPILOT_MODEL = "deepseek-v4-pro"
copilot
```

macOS / Linux 示例：

```bash theme={null}
# 先退出当前 copilot 会话，然后执行：
export COPILOT_MODEL="deepseek-v4-pro"
copilot
```

如果你同时还要改 Provider 地址或 API Key，也要一起在重新启动前修改。

### Windows Terminal 用户特别注意

如果你使用的是 Windows Terminal，不同 tab / pane 不共享你在某个 PowerShell 会话里临时设置的环境变量。

所以正确顺序一定是：

1. 在当前 PowerShell 会话里设置 `COPILOT_MODEL`
2. 不要切到别的 tab / pane
3. 直接在这个 shell 里启动 `copilot`

### 怎么确认模型已经切换成功

你可以用下面几种方式确认：

* 先在启动前检查环境变量：`Get-ChildItem Env:COPILOT*`
* 进入 `copilot` 后，查看右下角显示的模型名
* 如果 CLI 提示 `Model "xxx" is not in the built-in catalog`，通常说明它已经读到了你设置的自定义模型名

## 常见问题

| 问题                               | 解决方案                                                                                                                                      |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| VS Code 里看不到自定义 OpenAI 兼容入口      | 先确认当前 VS Code / Copilot 版本是否提供对应的 BYOK 或 OpenAI Compatible 入口；不同版本和渠道可见的入口不完全一致，必要时以当前版本实际支持的 Provider 扩展方案为准。                            |
| 切到 HaiToken 模型后，聊天能用但代码补全没有变化    | 这是正常现象。官方文档明确说明 BYOK 主要覆盖 Chat 和相关 Agent 体验，不覆盖标准代码补全。                                                                                    |
| 我已经改了 `COPILOT_MODEL`，但会话里还是旧模型  | `copilot` CLI 读取的是启动前的环境变量。请先退出当前会话，在同一个 shell 里修改 `COPILOT_MODEL` 后再重新启动 `copilot`。                                                      |
| Copilot CLI 提示 `400 Bad Request` | 先确认 `COPILOT_PROVIDER_TYPE` 是否为 `openai`，并确认 `COPILOT_PROVIDER_BASE_URL` 是否填写为 `https://api.haitoken.ai/v1`。                              |
| 我想改走 Claude / Anthropic 模式       | 把 `COPILOT_PROVIDER_TYPE` 改成 `anthropic`，并把 `COPILOT_PROVIDER_BASE_URL` 改成 `https://api.haitoken.ai`。不要继续使用 OpenAI 模式下的 `/v1` 地址。         |
| Copilot CLI 提示模型不存在              | 请确认 `COPILOT_MODEL` 与 HaiToken 实际暴露的模型 ID 完全一致。                                                                                           |
| 环境变量修改后不生效                       | 请确认你是否在设置变量的**同一个 shell**里启动了 `copilot`。如果你使用的是 Windows Terminal，还要注意不同 tab / pane 不共享某个 PowerShell 会话里临时设置的环境变量；必要时把变量写入对应 shell 的配置文件中。 |

## 下一步

* 查看 [获取 API Key](/docs/zh/quickstart/get-api-key)
* 查看 [OpenAI 格式 API 文档](/docs/zh/api-reference/chat/openai-format)
* 查看 [模型列表](/docs/zh/api-reference/models/list-models)