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

# GitHub Copilot CLI

> GitHub Copilot CLI 集成指南：通过环境变量接入 GravitexAI GPT 与 Claude 模型

## 一、产品简介

GitHub Copilot CLI 是终端中的编程 Agent，支持交互问答、代码修改、规划与自动驾驶。通过 **BYOK（自带密钥）** 配置，可以使用 GravitexAI 提供的 GPT 或 Claude 模型。

> [!NOTE]
>
> 本文配置依据 GitHub Copilot CLI **1.0.9x**，参考版本为 **1.0.98（2026-10）**。设置 `COPILOT_PROVIDER_BASE_URL` 后，CLI 直接调用指定的模型服务，无需登录 GitHub，也无需 Copilot 订阅。

## 二、环境要求

* macOS 或 Windows。
* 使用 npm 安装时，需要 **Node.js 22 及以上版本**。
* Windows 建议使用 **PowerShell 6 及以上版本**。

## 三、前置条件

* 已在 [GravitexAI 控制台](https://maas.gravitex.ai/#/api-keys) 创建 API Key（格式 `sk-xxxxxxxxxx`）。
* 已确认账户可使用的模型 ID，并可以连接 GravitexAI API。

## 四、接入参数

| 项目 | GPT 系列 | Claude 系列 |
| - | - | - |
| 协议类型 `COPILOT_PROVIDER_TYPE` | `openai` | `anthropic` |
| Base URL `COPILOT_PROVIDER_BASE_URL` | `https://api.gravitex.ai/v1` | `https://api.gravitex.ai`（**不带 `/v1`**） |
| 接口格式 `COPILOT_PROVIDER_WIRE_API` | `responses`（走 `/v1/responses`） | 不设置（走 `/v1/messages`） |
| API Key `COPILOT_PROVIDER_API_KEY` | `sk-你的密钥` | `sk-你的密钥`（同一个 Key） |
| 模型 `COPILOT_MODEL` | `gpt-5.5` 等 | `claude-sonnet-5-5` 等 |

> [!WARNING]
>
> **GPT 与 Claude 必须使用不同协议。** Claude 模型不支持 `/v1/responses`，请使用 `anthropic` 类型，并将 Base URL 设为 `https://api.gravitex.ai`（不带 `/v1`）。同一终端当前只能生效一套服务商配置，切换模型系列时需同时切换协议与地址。

**常用模型：**

* GPT：`gpt-5.5`、`gpt-5.4`、`gpt-5.4-mini`、`gpt-5.3-codex`、`gpt-6-sol`
* Claude：`claude-opus-5-5`、`claude-sonnet-5-5`、`claude-haiku-5-5`、`claude-fable-5-1`

模型 ID 以 [GravitexAI 模型广场](https://maas.gravitex.ai/#/api-models) 及账户实际可用模型为准，也可通过接口查询：

```bash theme={null}
curl -s https://api.gravitex.ai/v1/models -H "Authorization: Bearer sk-你的密钥"
```

## 五、安装与启动

### macOS

```bash theme={null}
# 方式 1：Homebrew（推荐）
brew install --cask copilot-cli

# 方式 2：npm（需要 Node.js 22+）
npm install -g @github/copilot

# 方式 3：官方安装脚本
curl -fsSL https://gh.io/copilot-install | bash
```

### Windows

```powershell theme={null}
# 方式 1：WinGet（推荐，需要 PowerShell 6+）
winget install GitHub.Copilot

# 方式 2：npm（需要 Node.js 22+）
npm install -g @github/copilot
```

也可以在 [GitHub Copilot CLI Releases](https://github.com/github/copilot-cli/releases) 页面下载可执行文件，解压后直接运行。

### 验证安装

```bash theme={null}
copilot --version
# GitHub Copilot CLI 1.0.98.
```

## 六、快速配置（当前终端生效）

只对**当前终端窗口**有效，关闭窗口后配置失效。先将 `sk-你的密钥` 替换为 GravitexAI API Key，按系统与模型系列选择一套命令执行。

> [tab] macOS（zsh / bash）
>
> **GPT：**
>
> ```bash theme={null}
> export COPILOT_PROVIDER_TYPE=openai
> export COPILOT_PROVIDER_BASE_URL=https://api.gravitex.ai/v1
> export COPILOT_PROVIDER_API_KEY=sk-你的密钥
> export COPILOT_PROVIDER_WIRE_API=responses
> export COPILOT_MODEL=gpt-5.5
> copilot
> ```
>
> **Claude：**
>
> ```bash theme={null}
> export COPILOT_PROVIDER_TYPE=anthropic
> export COPILOT_PROVIDER_BASE_URL=https://api.gravitex.ai
> export COPILOT_PROVIDER_API_KEY=sk-你的密钥
> unset COPILOT_PROVIDER_WIRE_API
> export COPILOT_MODEL=claude-sonnet-5-5
> copilot
> ```

> [tab] Windows PowerShell
>
> **GPT：**
>
> ```powershell theme={null}
> $env:COPILOT_PROVIDER_TYPE = "openai"
> $env:COPILOT_PROVIDER_BASE_URL = "https://api.gravitex.ai/v1"
> $env:COPILOT_PROVIDER_API_KEY = "sk-你的密钥"
> $env:COPILOT_PROVIDER_WIRE_API = "responses"
> $env:COPILOT_MODEL = "gpt-5.5"
> copilot
> ```
>
> **Claude：**
>
> ```powershell theme={null}
> $env:COPILOT_PROVIDER_TYPE = "anthropic"
> $env:COPILOT_PROVIDER_BASE_URL = "https://api.gravitex.ai"
> $env:COPILOT_PROVIDER_API_KEY = "sk-你的密钥"
> Remove-Item Env:COPILOT_PROVIDER_WIRE_API -ErrorAction SilentlyContinue
> $env:COPILOT_MODEL = "claude-sonnet-5-5"
> copilot
> ```

> [tab] Windows CMD
>
> ```bat theme={null}
> :: GPT
> set COPILOT_PROVIDER_TYPE=openai
> set COPILOT_PROVIDER_BASE_URL=https://api.gravitex.ai/v1
> set COPILOT_PROVIDER_API_KEY=sk-你的密钥
> set COPILOT_PROVIDER_WIRE_API=responses
> set COPILOT_MODEL=gpt-5.5
> copilot
> ```
>
> ```bat theme={null}
> :: Claude
> set COPILOT_PROVIDER_TYPE=anthropic
> set COPILOT_PROVIDER_BASE_URL=https://api.gravitex.ai
> set COPILOT_PROVIDER_API_KEY=sk-你的密钥
> set COPILOT_PROVIDER_WIRE_API=
> set COPILOT_MODEL=claude-sonnet-5-5
> copilot
> ```

## 七、持久化配置（可选）

Copilot CLI 的 `settings.json` **不支持**写 BYOK 服务商，只能通过环境变量配置。所以“写死”的做法是：把变量写进 Shell 配置文件。

由于 GPT 和 Claude 的协议类型不同，推荐定义**两个快捷命令** `copilot-gpt` 和 `copilot-claude`。这样可在启动时选择模型系列，无需每次手动填写全部变量。

### macOS：写入 `~/.zshrc`

```bash theme={null}
# 打开配置文件
open -e ~/.zshrc        # 或 vim ~/.zshrc
```

在文件末尾追加：

```bash theme={null}
# ===== Gravitex x GitHub Copilot CLI =====
export GRAVITEX_API_KEY="sk-你的密钥"

# GPT 系列：OpenAI 协议，走 /v1/responses
# 用法：copilot-gpt [模型名] [其他 copilot 参数...]
copilot-gpt() {
  local model="${1:-gpt-5.5}"; [ $# -gt 0 ] && shift
  COPILOT_PROVIDER_TYPE=openai \
  COPILOT_PROVIDER_BASE_URL=https://api.gravitex.ai/v1 \
  COPILOT_PROVIDER_API_KEY="$GRAVITEX_API_KEY" \
  COPILOT_PROVIDER_WIRE_API=responses \
  COPILOT_MODEL="$model" \
  copilot "$@"
}

# Claude 系列：Anthropic 协议，走 /v1/messages
# 用法：copilot-claude [模型名] [其他 copilot 参数...]
copilot-claude() {
  local model="${1:-claude-sonnet-5-5}"; [ $# -gt 0 ] && shift
  COPILOT_PROVIDER_TYPE=anthropic \
  COPILOT_PROVIDER_BASE_URL=https://api.gravitex.ai \
  COPILOT_PROVIDER_API_KEY="$GRAVITEX_API_KEY" \
  COPILOT_MODEL="$model" \
  env -u COPILOT_PROVIDER_WIRE_API copilot "$@"
}
```

使配置生效：

```bash theme={null}
source ~/.zshrc
```

使用：

```bash theme={null}
copilot-gpt                         # 默认 gpt-5.5
copilot-gpt gpt-5.3-codex           # 指定模型
copilot-claude                      # 默认 claude-sonnet-5-5
copilot-claude claude-opus-5-5 --yolo   # 指定模型 + 免确认模式
```

> [!TIP]
>
> 如果只使用一种模型系列，也可以把第六节对应的环境变量写入 `~/.zshrc`，以后直接运行 `copilot`。从 GPT 切换到 Claude 时，仍需清除 `COPILOT_PROVIDER_WIRE_API`。

### Windows：写入 PowerShell Profile

```powershell theme={null}
# 配置文件不存在时先创建，然后用记事本打开
if (!(Test-Path $PROFILE)) { New-Item -Path $PROFILE -ItemType File -Force }
notepad $PROFILE
```

在文件末尾追加：

```powershell theme={null}
# ===== Gravitex x GitHub Copilot CLI =====
$env:GRAVITEX_API_KEY = "sk-你的密钥"

# GPT 系列：OpenAI 协议，走 /v1/responses
# 用法：copilot-gpt [模型名] [其他 copilot 参数...]
function copilot-gpt {
    param([string]$Model = "gpt-5.5", [Parameter(ValueFromRemainingArguments)]$Rest)
    $env:COPILOT_PROVIDER_TYPE = "openai"
    $env:COPILOT_PROVIDER_BASE_URL = "https://api.gravitex.ai/v1"
    $env:COPILOT_PROVIDER_API_KEY = $env:GRAVITEX_API_KEY
    $env:COPILOT_PROVIDER_WIRE_API = "responses"
    $env:COPILOT_MODEL = $Model
    copilot @Rest
}

# Claude 系列：Anthropic 协议，走 /v1/messages
# 用法：copilot-claude [模型名] [其他 copilot 参数...]
function copilot-claude {
    param([string]$Model = "claude-sonnet-5-5", [Parameter(ValueFromRemainingArguments)]$Rest)
    $env:COPILOT_PROVIDER_TYPE = "anthropic"
    $env:COPILOT_PROVIDER_BASE_URL = "https://api.gravitex.ai"
    $env:COPILOT_PROVIDER_API_KEY = $env:GRAVITEX_API_KEY
    Remove-Item Env:COPILOT_PROVIDER_WIRE_API -ErrorAction SilentlyContinue
    $env:COPILOT_MODEL = $Model
    copilot @Rest
}
```

重新打开 PowerShell（或执行 `. $PROFILE`）后即可使用，用法同 macOS。

> [!NOTE]
>
> 如果 PowerShell 提示禁止运行 Profile 脚本，可继续使用第六节的临时配置。需要加载 Profile 时，请按本机管理要求配置脚本执行策略。

### Windows：只用一种模型时，可写入系统用户环境变量

```powershell theme={null}
# 以 GPT 为例，写入后需要重新打开终端
[Environment]::SetEnvironmentVariable("COPILOT_PROVIDER_TYPE", "openai", "User")
[Environment]::SetEnvironmentVariable("COPILOT_PROVIDER_BASE_URL", "https://api.gravitex.ai/v1", "User")
[Environment]::SetEnvironmentVariable("COPILOT_PROVIDER_API_KEY", "sk-你的密钥", "User")
[Environment]::SetEnvironmentVariable("COPILOT_PROVIDER_WIRE_API", "responses", "User")
[Environment]::SetEnvironmentVariable("COPILOT_MODEL", "gpt-5.5", "User")
```

删除：把第二个参数改成 `$null` 再执行一遍即可。

## 八、免确认模式与权限（可选）

默认情况下，Copilot CLI 只会自动批准只读操作；写文件、执行命令都会弹出确认。下面三种方式都可以关掉确认。

### 1. 免确认模式（YOLO，单次生效）

```bash theme={null}
copilot --yolo          # 免确认模式
copilot --allow-all     # 与 --yolo 完全等价
```

`--yolo` / `--allow-all` 等价于下面三个参数的组合：

| 参数 | 作用 |
| - | - |
| `--allow-all-tools` | 所有工具（写文件、执行命令、MCP）都不再确认 |
| `--allow-all-paths` | 允许访问任意路径（默认只能访问当前目录及其子目录） |
| `--allow-all-urls` | 允许访问任意 URL |

YOLO（`--yolo`）用于免确认授权；如需 Agent 持续执行直到任务完成，还需搭配 **`--autopilot`**：

```bash theme={null}
copilot --yolo --autopilot
```

### 2. 会话中切换

在 copilot 交互界面中输入：

| 命令 | 作用 |
| - | - |
| `/allow-all` | 当前会话开启全部权限 |
| `/permissions` | 在 manual（手动确认）/ assisted（AI 辅助审批）/ allow-all（全部放行）之间切换 |

### 3. 写入配置（永久默认开启）

```bash theme={null}
# 新的交互会话默认使用 allow-all 权限模式
copilot config defaultPermissionMode allow-all

# 可选：新会话默认进入 autopilot 模式
copilot config defaultMode autopilot
```

配置保存在 `~/.copilot/settings.json`（Windows：`%USERPROFILE%\.copilot\settings.json`），等价于手动写入：

```json theme={null}
{
  "defaultPermissionMode": "allow-all",
  "defaultMode": "autopilot"
}
```

恢复默认：

```bash theme={null}
copilot config defaultPermissionMode manual
copilot config defaultMode interactive
```

### 4. 非交互模式（脚本 / CI）

非交互模式（`-p`）**必须**带 `--allow-all-tools` 或 `--yolo`：

```bash theme={null}
copilot -p "给 main.go 补充单元测试" --yolo -s
```

也可以设置环境变量 `COPILOT_ALLOW_ALL=true`。注意：设为 `true` 时，CLI 还会自动信任当前目录，并加载该目录下的插件、MCP 和 hooks。

> [!WARNING]
>
> 全部放行后，Agent 可以不经确认地修改或删除文件、执行命令。仅在受信任且已使用 Git 管理的项目中按需开启，完成后检查变更。

## 九、日常使用

```bash theme={null}
# 交互模式
copilot

# 单次提问后退出（-s 只输出回答）
copilot -p "解释一下这个项目的目录结构" -s --allow-all-tools

# 临时指定模型（必须是同一协议类型的模型）
copilot --model gpt-5.4

# 恢复最近一次会话
copilot --continue

# 规划模式：先出方案，确认后再执行
copilot --mode plan
```

**交互界面常用命令：**

| 命令 | 作用 |
| - | - |
| `/model` | 切换模型 |
| `/allow-all` | 开启全部权限 |
| `/permissions` | 切换权限模式 |
| `/help` | 查看所有命令 |

## 十、验证与排错

### 验证是否成功

```bash theme={null}
# 执行第六节对应的环境变量配置后运行
copilot -p "Reply with exactly: OK" -s --allow-all-tools
```

返回 `OK` 且没有认证、协议或模型错误，说明当前配置可以正常调用。使用快捷命令时，将验证命令中的 `copilot` 替换为 `copilot-gpt gpt-5.5` 或 `copilot-claude claude-sonnet-5-5`，即可使用对应配置。

### 常见问题

> [accordion] Model 'claude-xxx' not found on provider ... (HTTP 404)
>
> Claude 被配成了 `openai` 类型 + `responses`，请改用 `anthropic` 类型

> [accordion] Claude 请求 404 / 路径重复 /v1/v1/messages
>
> `anthropic` 类型的 Base URL 多写了 `/v1`，改为 `https://api.gravitex.ai`

> [accordion] GPT 请求 404
>
> `openai` 类型的 Base URL 漏写了 `/v1`，改为 `https://api.gravitex.ai/v1`

> [accordion] 401 / Invalid API key
>
> Key 错误、余额不足或没有该模型的权限，可先用 `curl` 调 `/v1/models` 验证

> [accordion] 仍然要求登录 GitHub
>
> `COPILOT_PROVIDER_BASE_URL` 没有生效，执行 `echo $COPILOT_PROVIDER_BASE_URL`（PowerShell：`$env:COPILOT_PROVIDER_BASE_URL`）检查

> [accordion] 改了 \~/.zshrc 不生效
>
> 执行 `source ~/.zshrc`，或重新打开终端

### 查看所有可用参数

```bash theme={null}
copilot help providers     # BYOK 配置说明
copilot help environment   # 所有环境变量
copilot help permissions   # 权限说明
copilot help config        # settings.json 配置项
```

## 十一、相关资源

* 官方仓库与下载：[GitHub Copilot CLI](https://github.com/github/copilot-cli)
* 密钥管理：[GravitexAI 控制台](https://maas.gravitex.ai/#/api-keys)
* 可用模型：[GravitexAI 模型广场](https://maas.gravitex.ai/#/api-models)
* 桌面客户端配置：[GitHub Copilot App](https://docs.gravitex.ai/cn/integrations/github-copilot-app.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.