> ## 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 App

> GitHub Copilot 桌面客户端集成指南：通过 GravitexAI 接入 GPT 与 Claude 模型

## 一、产品简介

GitHub Copilot App 是 GitHub 的桌面编程 Agent 客户端，支持添加本地项目或 GitHub 仓库，通过自然语言完成编程任务。通过 **BYOK（自带模型服务商）** 功能接入 GravitexAI 后，可以在客户端中选择 GPT 或 Claude 模型。

| 能力 | 说明 |
| - | - |
| 图形化配置 | 在 Model providers 中填写接口地址、API Key 并添加模型，无需修改配置文件 |
| 多模型切换 | 分别配置 GPT 与 Claude 服务商，在会话中选择需要的模型 |
| 自主程度可调 | 支持 Interactive、Plan 和 Autopilot 三种会话模式 |
| 按量计费 | 自有服务商会话按 GravitexAI 账户计费，不消耗 GitHub Copilot 额度 |

> [!NOTE]
>
> 本文适用于 **GitHub Copilot App 1.1.x（2026-10）**。BYOK 功能处于 **Public Preview**，界面文字可能随版本变化。下文保留英文按钮名称，并提供中文说明，方便对照操作。

## 二、环境要求

* macOS 或 Windows 桌面系统。
* 已安装 [Git](https://git-scm.com/)。
* 可以访问 GitHub 完成登录，并连接 GravitexAI API。

## 三、前置条件

* 一个 GitHub 账号，用于登录客户端。
* 已在 [GravitexAI 控制台](https://maas.gravitex.ai/#/api-keys) 创建 API Key（格式 `sk-xxxxxxxxxx`）。

> [!NOTE]
>
> 只使用自己的模型服务商时，无需 GitHub Copilot 付费订阅。本文使用客户端的英文界面名称。

## 四、快速开始

### 第一步：安装客户端

> [tab] macOS
>
> 使用 Homebrew 安装：
>
> ```bash theme={null}
> brew install --cask github-copilot-app
> ```
>
> 也可以按芯片类型下载安装包：
>
> * [Apple Silicon（M 系列芯片）](https://github.com/github/app/releases/latest/download/GitHub-Copilot-darwin-arm64.dmg)
> * [Intel 芯片](https://github.com/github/app/releases/latest/download/GitHub-Copilot-darwin-x64.dmg)
>
> 双击 DMG，将 **GitHub Copilot** 拖入“应用程序”文件夹，然后打开客户端。

> [tab] Windows
>
> 按系统架构下载安装包，双击运行并完成安装：
>
> * [Windows x64（大多数电脑）](https://github.com/github/app/releases/latest/download/GitHub-Copilot-windows-x64-setup.exe)
> * [Windows ARM64](https://github.com/github/app/releases/latest/download/GitHub-Copilot-windows-arm64-setup.exe)

其他版本可前往 [GitHub Releases](https://github.com/github/app/releases) 查看。

### 第二步：登录 GitHub

打开客户端，点击 **Sign in to GitHub**（登录 GitHub），在浏览器中完成授权。

* **没有 Copilot 订阅**：在引导页选择 **continue with your own model provider**（使用自己的模型服务商），按第四步的参数填写，然后点击 **Save and continue**（保存并继续）。
* **已有 Copilot 订阅**：进入主界面后，按下一步打开设置并添加服务商。

### 第三步：打开模型服务商设置

按系统打开 **Settings**（设置）：

| 系统 | 操作 |
| - | - |
| macOS | 菜单栏 **GitHub Copilot → Settings**，或按 `⌘ ,` |
| Windows | 左下角头像或菜单中的 **Settings**，或按 `Ctrl + ,` |

在左侧选择 **Model providers**（模型服务商），点击 **Add provider**（添加服务商）。

![在 Model providers 设置中点击 Add provider](https://mintcdn.com/gravitexai/QXITE-rsvJBzaoaP/images/github-copilot-app-1.png?fit=max\&auto=format\&n=QXITE-rsvJBzaoaP\&q=85\&s=22a7af4e2a7f430c5055ab78be1e12e9)

### 第四步：填写 GravitexAI 接入信息

按需要添加 GPT 或 Claude 服务商；如果两类模型都要使用，分别添加一个服务商，可复用同一个 GravitexAI API Key。

| 字段 | GPT 服务商 | Claude 服务商 |
| - | - | - |
| **服务商类型** | **Any OpenAI-compatible HTTP endpoint** | **Anthropic** |
| **Display name**（显示名称） | `Gravitex GPT` | `Gravitex Claude` |
| **Base URL**（接口地址） | `https://api.gravitex.ai/v1` | `https://api.gravitex.ai` |
| **API key**（密钥） | 你的 GravitexAI API Key | 同一个 GravitexAI API Key |
| **Wire API / API format**（如有） | **Responses**，对应 `/v1/responses` | 无需设置，对应 `/v1/messages` |

填写完成后，点击 **Add provider** 保存；编辑已有配置时，点击 **Save changes**（保存修改）。

> [!WARNING]
>
> **两类模型的协议与地址必须匹配：**
>
> * GPT：选择 OpenAI 兼容类型，Base URL **带 `/v1`**，接口格式选择 **Responses**（如有此选项）。
> * Claude：选择 **Anthropic**，Base URL **不带 `/v1`**。Claude 不支持 `/v1/responses`，不要添加到 GPT 服务商下。

下图为 Anthropic 服务商的配置示例。截图中的显示名称为 `Anthropic`，可改为 `Gravitex Claude`，便于在模型选择器中识别；**Custom headers (JSON)** 无特殊需求时留空。

![Anthropic 服务商配置，Base URL 不带 /v1](https://mintcdn.com/gravitexai/QXITE-rsvJBzaoaP/images/github-copilot-app-2.png?fit=max\&auto=format\&n=QXITE-rsvJBzaoaP\&q=85\&s=1f7b5a0498201a44f3e79152a642818a)

### 第五步：添加模型

保存服务商后，从模型目录中勾选需要的模型；也可以按模型 ID 手动添加。常用模型 ID 示例：

| 服务商 | 模型 ID 示例 |
| - | - |
| **Gravitex GPT** | `gpt-5.5`、`gpt-5.4`、`gpt-5.4-mini`、`gpt-5.3-codex`、`gpt-6-sol` |
| **Gravitex Claude** | `claude-opus-5-5`、`claude-sonnet-5-5`、`claude-haiku-5-5`、`claude-fable-5-1` |

> [!TIP]
>
> 模型 ID 必须与 [GravitexAI 模型广场](https://maas.gravitex.ai/#/api-models) 中的名称一致，以账户实际可用模型为准。浏览模型目录前，请先保存 API Key。

### 第六步：添加项目并选择模型

1. 在左侧边栏 **Projects** 旁点击 **+**（Add project），选择项目来源：

   | 选项 | 说明 |
   | - | - |
   | **Local folder or repository** | 本地文件夹或仓库 |
   | **GitHub repository** | GitHub 上的仓库 |
   | **Repository URL** | 输入仓库地址 |

2. 新建会话（**New session**）。

3. 点击输入框下方的模型选择器，在 **Gravitex GPT** 或 **Gravitex Claude** 分组中选择模型；如有 **Reasoning effort**（推理强度）选项，可按任务需要调整。

4. 发送一条测试消息，确认能够正常收到回复。

![在会话输入框下方选择已配置的 Claude 模型](https://mintcdn.com/gravitexai/QXITE-rsvJBzaoaP/images/github-copilot-app-3.png?fit=max\&auto=format\&n=QXITE-rsvJBzaoaP\&q=85\&s=b7ac69928e0ba21e80c44cd5887debb2)

> [!NOTE]
>
> 截图中服务商沿用默认名称 `Anthropic`。如果按上文设置了显示名称，模型旁会显示你填写的服务商名称。

## 五、会话模式

输入框下方的模式选择器用于控制 Agent 的自主程度：

| 模式 | 中文 | 适用方式 |
| - | - | - |
| **Interactive** | 交互模式 | 默认模式，Agent 给出修改建议，等待确认后继续 |
| **Plan** | 规划模式 | 先生成方案，审核通过后再执行 |
| **Autopilot** | 自动驾驶 | 自主修改代码、执行命令、运行测试并持续迭代 |

> [!WARNING]
>
> Autopilot 模式会在执行过程中直接修改文件、运行命令，建议在已使用 Git 管理的项目中开启，并在任务完成后检查变更。

## 六、验证是否成功

* **Model providers** 中已保存服务商，并添加了至少一个与协议匹配的模型。
* 新建会话后，模型选择器中能看到并选中已配置的模型。
* 发送消息后正常收到回复，没有出现 `invalid api key`、`endpoint_not_found` 或模型不可用等错误。

> [!NOTE]
>
> 自有服务商会话的费用由 GravitexAI 账户结算，不消耗 GitHub Copilot 额度；遇到限流时，也不会自动切换到 Copilot 的 Auto 模型。

## 七、常见问题

> [accordion] Claude 报 404 / endpoint\_not\_found 怎么办？
>
> 确认服务商类型为 **Anthropic**，Base URL 为 `https://api.gravitex.ai`，不带 `/v1`。如果请求路径出现 `/v1/v1/messages`，请去掉 Base URL 末尾的 `/v1`。不要将 Claude 配置为 OpenAI 兼容类型或 Responses 接口。

> [accordion] GPT 报 404 怎么办？
>
> 确认服务商类型为 **Any OpenAI-compatible HTTP endpoint**，Base URL 为 `https://api.gravitex.ai/v1`，末尾带 `/v1`；如有接口格式选项，选择 **Responses**。

> [accordion] 提示 Invalid API key for this provider？
>
> 在 **Model providers** 中编辑对应服务商，重新填写完整的 GravitexAI API Key，确认没有多余空格并保存。可在 [GravitexAI 控制台](https://maas.gravitex.ai/#/api-keys) 检查密钥是否有效。

> [accordion] 提示服务商没有 /models 接口？
>
> 报错为 `Provider doesn't expose a /models endpoint at this base URL` 时，先核对服务商类型与 Base URL 是否匹配。GPT 使用 `https://api.gravitex.ai/v1`，Claude 使用 `https://api.gravitex.ai`。仍无法浏览模型目录时，可尝试按模型 ID 手动添加。

> [accordion] 浏览模型目录时提示先添加 API Key？
>
> 报错为 `Add an API key for this provider before browsing the catalog` 时，请先在服务商配置中填写并保存 API Key，再打开模型目录。

> [accordion] 模型选择器里看不到 GravitexAI 模型？
>
> 回到 **Model providers**，确认服务商已保存，并已勾选或手动添加所需模型。显示名称只用于界面展示；如果保留了 `Anthropic` 等默认名称，请在对应分组中查找。必要时重启客户端后再试。

> [accordion] API Key 保存在哪里？
>
> 客户端将 API Key 保存在系统凭据库中：macOS 使用钥匙串，Windows 使用凭据管理器。不要在公开截图、聊天记录或代码仓库中暴露密钥。

### 用命令行验证接口（可选）

如果客户端配置后仍无法调用，可用下面的请求检查密钥与接口。将 `sk-你的密钥` 替换为实际 API Key，模型 ID 替换为账户可用的模型。

```bash GPT（Responses） theme={null}
curl https://api.gravitex.ai/v1/responses \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","input":"say OK"}'
```

```bash Claude（Messages） theme={null}
curl https://api.gravitex.ai/v1/messages \
  -H "x-api-key: sk-你的密钥" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":20,"messages":[{"role":"user","content":"say OK"}]}'
```

> [!NOTE]
>
> Windows PowerShell 中请使用 `curl.exe` 代替 `curl`，并把行尾的 `\` 换成反引号 `` ` ``。

## 八、相关资源

* 客户端下载：[GitHub Copilot App Releases](https://github.com/github/app/releases)
* 密钥管理：[GravitexAI 控制台](https://maas.gravitex.ai/#/api-keys)
* 可用模型：[GravitexAI 模型广场](https://maas.gravitex.ai/#/api-models)


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