对 GitHub Copilot CLI 进行身份验证

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

谁可以使用此功能？

GitHub Copilot CLI 适用于所有 Copilot 计划。 如果从组织收到 Copilot，必须在组织的设置中启用 Copilot CLI 策略。

在本文中

关于身份验证

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

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

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

  • OAuth：用于交互式使用的默认和建议方法。 有两种 OAuth 流程。 浏览器（Web）流程会打开您的浏览器，以授权登录，并通过本地回环回调完成登录。 设备代码流会显示一个一次性代码，您需要在浏览器中输入该代码。 在本地桌面环境中默认使用浏览器流程，而在已知的远程或无头环境（包括 SSH、GitHub Codespaces开发容器和 CI）中，则默认使用设备代码流程。 请参阅 使用 OAuth 进行身份验证。
  • 环境变量：建议用于 CI/CD 流水线、容器和非交互式环境。 将受支持的令牌设置为环境变量（COPILOT_GITHUB_TOKEN或GH_TOKEN``GITHUB_TOKEN），CLI 会自动使用它而不提示。 请参阅 使用环境变量进行身份验证。
  • GitHub CLI 回退：如果 GitHub CLI (gh)（注意：是 gh CLI，而不是 copilot）已安装并经过身份验证，Copilot CLI 可以自动使用其令牌。 这是最低优先级的方法，仅在未找到其他凭据时激活。 请参阅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
细粒度 PATgithub_pat_是的必须由个人帐户（而不是组织）拥有，并具有Copilot请求的帐户权限。
GitHub 应用用户到服务器ghu_是的通过环境变量
经典 PATghp_否不支持 Copilot CLI

COPILOT CLI 如何存储凭据

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

平台密钥链
macOS钥匙串访问
Windows凭据管理器
Linuxlibsecret （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）后备

注意

  • 环境变量以无提示方式替代存储的 OAuth 令牌。 如果您为另一个工具设置了GH_TOKEN，CLI 将使用该令牌，而不是从copilot login获得的 OAuth 令牌。 为了避免意外行为，请取消设置那些不希望 CLI 使用的环境变量。 有一个例外：在 GitHub Codespaces 中，自动注入的 GITHUB_TOKEN 不会优先于你使用 /login 登录的账户。 你显式导出的 GITHUB_TOKEN、COPILOT_GITHUB_TOKEN 或 GH_TOKEN 仍然如此。
  • 配置 BYOK 提供程序环境变量时（例如，COPILOT_PROVIDER_BASE_URL，COPILOT_PROVIDER_API_KEY），无论您的身份验证状态如何，Copilot CLI 都将这些变量用于 AI 模型请求。 仅 GitHub 托管功能需要 GitHub 令牌。

使用 OAuth 进行身份验证

OAuth 是用于交互式使用的默认身份验证方法。 可以通过从/login运行Copilot CLI或者从终端运行copilot login来进行身份验证。 两者都提供浏览器（Web）流和设备代码流。

使用 /login 进行身份验证

  1. 从 Copilot CLI中运行 /login。

    Bash
    /login

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

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

  3. 选择要登录的方式。 建议的选项首先列出，具体取决于你的环境：本地终端上的浏览器流，或远程或无外设环境中的设备代码流。 以下示例显示本地终端中的提示：

    How do you want to sign in?
 1. Sign in with your browser (recommended)
 2. Sign in with a device code

  4. 完成所选流程。

    • 浏览器： Copilot CLI 打开浏览器，以便你可以授权登录。 如果浏览器没有自动打开，终端会显示一个你可以转而访问的 URL。

    • 设备代码：CLI 显示一次性用户代码，并且可以将其复制到剪贴板并打开浏览器。

      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...

      如果浏览器未自动打开，请导航到验证 URL https://github.com/login/device ，然后将一次性代码粘贴到页面上的字段中。

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

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

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

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

使用 copilot login 进行身份验证

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

    Bash
    copilot login

    对于 GitHub Enterprise Cloud：

    Bash
    copilot login --host HOSTNAME

  2. 授权登录。

    在本地桌面上， copilot login 默认使用浏览器流。 它会打开浏览器以完成登录授权，并通过本地回环回调捕获结果。

    Opening your browser to authenticate...
If it doesn't open automatically, visit:
URL
Waiting for authorization...

    已知的远程或无外设环境（包括 SSH、 GitHub Codespaces开发容器和 CI）改用设备代码流。 CLI 显示一次性代码，当环境支持时，可以将它复制到剪贴板并打开浏览器。

    To authenticate, visit https://github.com/login/device and enter code 1234-5678
Waiting for authorization...

    若要强制特定流，请添加 --web-flow 或 --device-code 选项。

  3. 如果浏览器未自动打开，请导航到终端中显示的 URL。 对于设备代码流，请将一次性代码粘贴到页面上的字段中。

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

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

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

    Signed in successfully as Octocat.

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

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

  1. 访问 Fine-grained personal access tokens。
  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
    gh auth status

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

    Bash
    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. 在 Authorized OAuth Apps 下，单击 GitHub CLI</c2 旁边的 >，展开菜单并选择 Revoke。

后续步骤

如果遇到身份验证问题，请参阅 排查 GitHub Copilot CLI 身份验证问题。