# 对 GitHub Copilot CLI 进行身份验证

进行身份验证 Copilot CLI ，以便可以直接从命令行使用 Copilot 。

## 关于身份验证

如果使用自己的 LLM 提供程序 API 密钥（BYOK）， GitHub 则不需要身份验证。

任何其他 GitHub Copilot CLI 用法都需要身份验证。

需要身份验证时， Copilot CLI 支持三种方法。 使用的方法取决于是以交互方式工作，还是在自动化环境中工作。

* **OAuth 设备流**：这是交互式使用的默认方法，也是推荐的方法。 在`/login`中运行Copilot CLI时，CLI 会生成一次性代码，并指示你在浏览器中进行身份验证。 这是进行身份验证的最简单方法。 请参阅 [使用 OAuth 进行身份验证](#authenticating-with-oauth)。
* **环境变量**：建议用于 CI/CD 流水线、容器和非交互式环境。 将受支持的令牌设置为环境变量（`COPILOT_GITHUB_TOKEN`或`GH_TOKEN``GITHUB_TOKEN`），CLI 会自动使用它而不提示。 请参阅 [使用环境变量进行身份验证](#authenticating-with-environment-variables)。
* **GitHub CLI 回退**：如果 GitHub CLI (`gh`)（注意：是 `gh` CLI，而不是 `copilot`）已安装并经过身份验证，Copilot CLI 可以自动使用其令牌。 这是最低优先级的方法，仅在未找到其他凭据时激活。 请参阅[GitHub CLI的身份验证](#authenticating-with-github-cli)。

进行身份验证后，Copilot CLI 会记住您的登录信息，并自动为所有 Copilot API 请求使用令牌。 可以使用多个帐户登录，CLI 将记住上次使用的帐户。 令牌生存期和过期时间取决于如何在帐户或组织设置上创建令牌。

## 未经身份验证的使用

如果配置为 Copilot CLI 使用自己的 LLM 提供程序 API 密钥（BYOK）， GitHub**则不需要**身份验证。
Copilot CLI 可以在不需要 GitHub 帐户或令牌的情况下直接连接到您配置的提供程序。

但是，如果没有 GitHub 身份验证，则 **以下功能不可用**：

* `/delegate`：需要 Copilot cloud agent，在 GitHub的服务器上运行
* GitHub MCP 服务器：需要身份验证才能访问 GitHub API
* GitHub 代码搜索：需要身份验证才能查询 GitHub的搜索索引

可以将 BYOK 和 GitHub 身份验证相结合，以充分利用两者的优势：AI 响应的首选模型，以及访问 GitHub 托管的功能（如 `/delegate` 和代码搜索）。

### 脱机模式

如果将环境变量`COPILOT_OFFLINE`设置为`true`，Copilot CLI则运行而不联系GitHub的服务器。 在脱机模式下：

* 没有尝试进行GitHub 身份验证。
* CLI 仅向配置的 BYOK 提供程序发出网络请求。
* 遥测已完全禁用。

只有在你的 BYOK 提供程序位于本地或位于同一隔离环境内（例如，在没有外部网络访问的本地运行的模型）时，离线模式才**是实体隔离的**。 如果 `COPILOT_PROVIDER_BASE_URL` 指向远程或 Internet 可访问的终结点，则仍会通过网络将提示和代码上下文发送到该提供程序。 如果没有脱机模式，即使在不使用 GitHub 身份验证的情况下使用 BYOK，遥测仍会正常发送。

### 支持的令牌类型

| 令牌类型            | 前缀            | 已支持 | 注释                                      |
| --------------- | ------------- | --- | --------------------------------------- |
| OAuth 令牌（设备流）   | `gho_`        | 是的  | 默认方法通过`copilot login`                   |
| 细粒度 PAT         | `github_pat_` | 是的  | 必须由个人帐户（而不是组织）拥有，并具有**Copilot请求**的帐户权限。 |
| GitHub 应用用户到服务器 | `ghu_`        | 是的  | 通过环境变量                                  |
| 经典 PAT          | `ghp_`        | 否   | 不支持 Copilot CLI                         |

### COPILOT CLI 如何存储凭据

默认情况下，CLI 会将 OAuth 令牌存储在操作系统的密钥链中，并使用服务名称 `copilot-cli`。

| 平台      | 密钥链                                |
| ------- | ---------------------------------- |
| macOS   | 钥匙串访问                              |
| Windows | 凭据管理器                              |
| Linux   | libsecret （GNOME Keyring， KWallet） |

如果系统密钥链不可用（例如，在没有安装的无头 Linux 服务器上 `libsecret` ），CLI 会提示你将令牌存储在纯文本配置文件中 `~/.copilot/config.json`。

运行命令时， Copilot CLI 按以下顺序检查凭据：

1. `COPILOT_GITHUB_TOKEN` 环境变量
2. `GH_TOKEN` 环境变量
3. `GITHUB_TOKEN` 环境变量
4. 来自系统密钥链的 OAuth 令牌
5. GitHub CLI （`gh auth token`）后备

> \[!NOTE]
>
> * 环境变量以无提示方式替代存储的 OAuth 令牌。 如果您为另一个工具设置了`GH_TOKEN`，CLI 将使用该令牌，而不是从`copilot login`获得的 OAuth 令牌。 为了避免意外行为，请取消设置那些不希望 CLI 使用的环境变量。
> * 配置 BYOK 提供程序环境变量时（例如，`COPILOT_PROVIDER_BASE_URL`，`COPILOT_PROVIDER_API_KEY`），无论您的身份验证状态如何，Copilot CLI 都将这些变量用于 AI 模型请求。               仅 GitHub 托管功能需要 GitHub 令牌。

## 使用 OAuth 进行身份验证

OAuth 设备流是用于交互式使用的默认身份验证方法。 可以通过从`/login`运行Copilot CLI或者从终端运行`copilot login`来进行身份验证。

### 使用 `/login` 进行身份验证

1. 从 Copilot CLI中运行 `/login`。

   ```bash copy
   /login
   ```

2. 选择要进行身份验证的帐户。 对于实现数据驻留的 GitHub Enterprise Cloud，请输入你的实例的主机名。

   ```text
   What account do you want to log into?
    1. GitHub.com
    2. GitHub Enterprise Cloud with data residency (*.ghe.com)
   ```

3. CLI 显示一次性用户代码，并自动将其复制到剪贴板并打开浏览器。

   ```text
   Waiting for authorization...
   Enter one-time code: 1234-5678 at https://github.com/login/device
   Press any key to copy to clipboard and open browser...
   ```

4. 如果浏览器未自动打开，请导航到 `https://github.com/login/device` 的验证 URL。

5. 将一次性代码粘贴到页面上的字段中。

6. 如果组织使用 SAML SSO，请单击每个要授予访问权限的组织旁边的 **Authorize**。

7. 查看请求的权限，然后单击 **Authorize GitHub Copilot CLI**。

8. 返回到终端。 身份验证完成后，CLI 会显示一条成功消息。

   ```text
   Signed in successfully as Octocat. You can now use Copilot.
   ```

### 使用 `copilot login` 进行身份验证

1. 从终端运行 `copilot login`。 如果你使用的是实现数据驻留的 GitHub Enterprise Cloud，请传递实例的主机名。

   ```bash copy
   copilot login
   ```

   对于 GitHub Enterprise Cloud：

   ```bash copy
   copilot login --host HOSTNAME
   ```

   CLI 显示一次性用户代码，并自动将其复制到剪贴板并打开浏览器。

   ```text
   To authenticate, visit https://github.com/login/device and enter code 1234-5678.
   ```

2. 如果浏览器未自动打开，请导航到 `https://github.com/login/device` 的验证 URL。

3. 将一次性代码粘贴到页面上的字段中。

4. 如果组织使用 SAML SSO，请单击每个要授予访问权限的组织旁边的 **Authorize**。

5. 查看请求的权限，然后单击 **Authorize GitHub Copilot CLI**。

6. 返回到终端。 身份验证完成后，CLI 会显示一条成功消息。

   ```text
   Signed in successfully as Octocat.
   ```

## 使用环境变量进行身份验证

对于非交互式环境，可以通过使用支持的令牌设置环境变量进行身份验证。 这非常适合 CI/CD 流水线、容器或无头服务器。

1. 访问 [Fine-grained personal access tokens](https://github.com/settings/personal-access-tokens/new)。
2. 在 **“资源所有者**”下，选择 **个人帐户**。 请勿选择组织。
   \*\*
   Copilot请求\*\*权限仅适用于用户拥有的 fine-grained personal access tokens。
3. 在 **存储库访问**下，选择适合用例的访问级别：
   * **公共存储库**，如果你只需要使用公共存储库。
   * **所有存储库** 如果需要跨所有当前和将来的存储库进行访问。
   * 仅当想要限制对特定存储库的访问时 **，才选择存储库**。
4. 在 **“权限**”下，选择“ **帐户** ”选项卡。
5. 单击“ **添加权限** ”并选择“ **Copilot 请求**”。
6. 单击“生成令牌”。\*\*\*\*
7. 在终端或环境配置中导出令牌。 使用`COPILOT_GITHUB_TOKEN`、`GH_TOKEN`或`GITHUB_TOKEN`环境变量（按优先级顺序）。

## 使用 GitHub CLI 进行身份验证

如果安装了 GitHub CLI 并完成身份验证，Copilot CLI 可以将其令牌作为备用。 此方法的优先级最低，仅在未设置环境变量且未找到存储令牌时激活。

1. 验证 GitHub CLI 是否已认证。

   ```bash copy
   gh auth status
   ```

   如果使用 GitHub Enterprise Cloud 的数据驻留功能，请验证正确的主机名是否经过身份验证。

   ```bash copy
   gh auth status --hostname HOSTNAME
   ```

2. 运行 `copilot`。 Copilot CLI 自动使用 GitHub CLI 令牌。

3. 运行 `/user` 以验证 CLI 中经过身份验证的帐户。

## 在帐户之间切换

Copilot CLI 支持多个帐户。 可以列出可用帐户，并从 CLI 中切换它们。
要列出可用帐户，请在 `/user list` 提示符下运行 Copilot CLI。
若要切换到其他帐户，请在提示符上键入 `/user switch` 。

若要添加另一个帐户，请从新的终端会话运行 `copilot login` ，或者从 CLI 中运行登录命令，并使用其他帐户授权。

## 退出登录并删除凭据

若要注销，请在`/logout`提示符处键入Copilot CLI。 这会删除本地存储的令牌，但不会在GitHub上撤销它。

若要撤消 OAuth 应用授权 GitHub 并将其阻止在其他位置使用，请执行以下步骤。

1. 导航到 **“设置** > **应用程序** > **授权的 OAuth 应用**”。
2. 导航到设置页面：
   1. 在任何页面 GitHub的右上角，单击个人资料图片。
   2. 单击“设置”。
3. 在左侧栏中，单击“ **应用程序**”。
4. 在 <c0>Authorized OAuth Apps</c0> 下，单击 <c2>GitHub CLI\</c2 旁边的 <c1 />>，展开菜单并选择 <c3>Revoke</c3>。

## 后续步骤

如果遇到身份验证问题，请参阅 [排查 GitHub Copilot CLI 身份验证问题](/zh/copilot/how-tos/copilot-cli/set-up-copilot-cli/troubleshoot-copilot-cli-auth)。