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

# Copilot

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

这里的 `Copilot` 是指终端中的 `copilot` CLI，通过环境变量指定外部模型提供方来接入 HaiRoute。

<Note>
  本文档只覆盖 **Copilot CLI**（终端中的 `copilot` 命令）。VS Code Copilot Chat 的 BYOK 接入不在此覆盖范围——这条路径在不同 VS Code 版本和渠道中的入口差异较大，官方体验仍在变化中。
</Note>

## 前提条件

* HaiRoute API Key
* 至少一个可用模型 ID，例如 `gpt-5.4`
* HaiRoute OpenAI 兼容地址：`https://api.hairoute.ai/v1`

<Tip>
  这里说的模型 ID，指的是 HaiRoute 首页或模型列表中的**模型编号**，例如 `gpt-5.4`。不要把展示名称直接填给 `COPILOT_MODEL`，否则很容易报模型不存在。
</Tip>

## 接入步骤

<Note>
  Copilot CLI 官方同时支持 `openai` 和 `anthropic` 两种 Provider 类型。对 HaiRoute 来说，推荐优先使用 `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.hairoute.ai/v1"
$env:COPILOT_PROVIDER_TYPE = "openai"
$env:COPILOT_PROVIDER_API_KEY = "YOUR_API_KEY"
$env:COPILOT_MODEL = "gpt-5.4"
```

macOS / Linux：

```bash theme={null}
export COPILOT_PROVIDER_BASE_URL="https://api.hairoute.ai/v1"
export COPILOT_PROVIDER_TYPE="openai"
export COPILOT_PROVIDER_API_KEY="YOUR_API_KEY"
export COPILOT_MODEL="gpt-5.4"
```

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

Windows PowerShell：

```powershell theme={null}
$env:COPILOT_PROVIDER_BASE_URL = "https://api.hairoute.ai"
$env:COPILOT_PROVIDER_TYPE = "anthropic"
$env:COPILOT_PROVIDER_API_KEY = "YOUR_API_KEY"
$env:COPILOT_MODEL = "gpt-5.4"
```

macOS / Linux：

```bash theme={null}
export COPILOT_PROVIDER_BASE_URL="https://api.hairoute.ai"
export COPILOT_PROVIDER_TYPE="anthropic"
export COPILOT_PROVIDER_API_KEY="YOUR_API_KEY"
export COPILOT_MODEL="gpt-5.4"
```

### 步骤 2：启动 Copilot CLI

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

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

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

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

### 补充说明

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

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

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

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

## 验证步骤

1. 在同一终端里启动 `copilot` 并发送一条简单消息。
2. 如果能够正常返回内容，说明接入成功。

## 如何切换模型

**Copilot CLI 不是在会话里手动点选模型，而是读取启动前的环境变量。**

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

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

Windows PowerShell 示例：

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

macOS / Linux 示例：

```bash theme={null}
# 先退出当前 copilot 会话，然后执行：
export COPILOT_MODEL="gpt-5.4"
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`，通常说明它已经读到了你设置的自定义模型名

## 常见问题

| 问题                               | 解决方案                                                                                                                                      |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| 我已经改了 `COPILOT_MODEL`，但会话里还是旧模型  | `copilot` CLI 读取的是启动前的环境变量。请先退出当前会话，在同一个 shell 里修改 `COPILOT_MODEL` 后再重新启动 `copilot`。                                                      |
| Copilot CLI 提示 `400 Bad Request` | 先确认 `COPILOT_PROVIDER_TYPE` 是否为 `openai`，并确认 `COPILOT_PROVIDER_BASE_URL` 是否填写为 `https://api.hairoute.ai/v1`。                              |
| 我想改走 Claude / Anthropic 模式       | 把 `COPILOT_PROVIDER_TYPE` 改成 `anthropic`，并把 `COPILOT_PROVIDER_BASE_URL` 改成 `https://api.hairoute.ai`。不要继续使用 OpenAI 模式下的 `/v1` 地址。         |
| Copilot CLI 提示模型不存在              | 请确认 `COPILOT_MODEL` 与 HaiRoute 实际暴露的模型 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)