OpenCode 接入 GitHub Copilot

📚 分类: AI 工具配置 ⏱️ 预计耗时: 15 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode，拥有 GitHub Copilot 订阅

你将学到什么

完成本教程后，你将能够：

[ ] 理解 OpenCode 如何与 GitHub Copilot 集成
[ ] 掌握两种为 OpenCode 配置 Copilot 授权的方法
[ ] 在 OpenCode 配置文件中启用并指定 Copilot 的 AI 模型
[ ] 排查并解决集成过程中常见的认证和配置错误

最终效果

在 OpenCode 终端中，你可以直接使用 Copilot 提供的各种 AI 模型（如 GPT-4o、Claude 3.5 Sonnet）来完成代码编写和任务处理，而无需离开终端环境。

前置准备

在开始前，请确认你的环境满足以下条件：

检查项	要求	验证方法
GitHub Copilot 订阅	个人版或企业版	访问 GitHub Settings > Copilot 查看状态
OpenCode	最新版本	`opencode --version`
网络连接	能够访问 `api.github.com` 和 `api.githubcopilot.com`	`ping api.github.com`

第 1 步：准备你的 GitHub 身份认证

🎯 目标：为 OpenCode 提供一个有效的 GitHub 身份凭证，使其能够代表你向 Copilot 服务发起请求。

📝 操作：

OpenCode 本身不存储你的 GitHub 密码，它通过读取你已在其他工具中创建的认证文件来获取权限。请选择以下一种你已经配置好的方式：

方式 A：使用 VS Code 的 Copilot 扩展（推荐）

如果你已经安装了 VS Code 的 GitHub Copilot 扩展并登录了账号，OpenCode 会自动读取该扩展生成的令牌文件。

打开 VS Code。
点击左侧活动栏的“扩展”图标。
搜索 GitHub Copilot 并确认已安装且状态为“已启用”。
点击 VS Code 右下角的 Copilot 图标，确保状态为 Sign in 或 Ready。如果未登录，请点击并按照提示完成登录。

方式 B：使用 GitHub CLI

如果你更喜欢使用命令行工具，可以通过 gh 命令行工具进行认证。

bash

# 1. 安装或更新 GitHub CLI (如果尚未安装)
# 官方安装指南：https://cli.github.com/

# 2. 登录你的 GitHub 账号
$ gh auth login

# 3. 按照终端提示，选择通过浏览器或令牌的方式完成登录

✅ 验证：

执行以下命令，确认认证成功：

bash

# 验证 gh cli 登录状态
$ gh auth status

# 预期输出：
# ✓ Logged in to github.com as <your_username> (keyring)
# ✓ Git operations for github.com: ... (credential helper)

💡 提示：OpenCode 会自动在以下路径查找认证文件：

~/.config/github-copilot/hosts.json
~/.config/github-copilot/apps.json

如果你使用的是 Neovim 的 copilot.vim 或 copilot.lua 插件，只要插件已登录，OpenCode 也能自动识别。

第 2 步（备选）：使用显式 GitHub Token 进行配置

🎯 目标：为那些不想通过其他 IDE 工具的开发者，提供一种直接配置 API 密钥的方法。

📝 操作：

如果你无法或不想使用上述工具，可以手动提供一个 GitHub 个人访问令牌。

获取 Token：
- 访问 GitHub Settings > Developer settings > Personal access tokens。
- 点击 Generate new token (classic)。
- 为 Token 起一个名字，例如 opencode-copilot。
- 重要：在 Scopes 区域，至少勾选 read:user 和 read:org。对于 Copilot 访问，有时需要 copilot 权限，如果选项存在，也请勾选。
- 点击 Generate token，并立即复制生成的 Token（例如：ghp_xxxxxxxxxxxxxxxxxxxx）。

配置 OpenCode：你有两种方式可以配置这个 Token：

方法 1：设置环境变量（推荐） 在你的 Shell 配置文件（如 ~/.bashrc、~/.zshrc）中添加：

bash

# 打开配置文件
$ nano ~/.zshrc

# 在文件末尾添加以下行
export GITHUB_TOKEN="ghp_your_token_here"    // 将 ghp_your_token_here 替换为你的真实 Token

# 保存并退出编辑器，然后使配置生效
$ source ~/.zshrc

方法 2：修改 OpenCode 配置文件 打开或创建你的 ~/.opencode.json 文件，并添加 apiKey 字段：

json

{
  "providers": {
    "copilot": {
      "apiKey": "ghp_your_token_here"  // 将 Token 粘贴在这里
    }
  }
}

✅ 验证：

bash

# 如果使用环境变量，运行以下命令检查是否生效
$ echo $GITHUB_TOKEN
# 预期输出：ghp_your_token_here

# 如果使用配置文件，确保文件格式正确，无语法错误

⚠️ 安全警告：请勿将你的 GitHub Token 提交到公开的代码仓库或分享给他人。.opencode.json 文件建议加入 .gitignore。

第 3 步：在 OpenCode 中启用并配置 Copilot

🎯 目标：完成 OpenCode 的配置文件，使其能够使用 Copilot 作为 AI 提供商。

📝 操作：

打开或创建你的 OpenCode 配置文件 ~/.opencode.json。

将以下配置内容添加到文件中。如果你已有其他配置，请将 providers 部分合并进去。

json

{
  "providers": {
    "copilot": {
      "disabled": false  // 确保 Copilot 提供商被启用
    }
  },
  "agents": {
    "coder": {
      "model": "copilot.gpt-4o",  // 指定 Copilot 的模型
      "maxTokens": 5000
    },
    "task": {
      "model": "copilot.gpt-4o",
      "maxTokens": 5000
    },
    "title": {
      "model": "copilot.gpt-4o",
      "maxTokens": 80
    }
  }
}

🤔 为什么要这样做？

providers.copilot.disabled: false 告诉 OpenCode，你要使用 Copilot 作为 AI 模型来源。
agents 下的 model 字段使用了 copilot. 前缀，这告诉 OpenCode 去 Copilot 提供商那里寻找名为 gpt-4o 的模型。

✅ 验证：

保存配置文件。
启动 OpenCode（例如，在终端输入 opencode）。
在 OpenCode 交互界面中，尝试向“coder”代理发送一个简单的指令，例如：“写一个 Python 的 Hello World”。
如果配置成功，你应该会看到来自 Copilot 模型的回复。

💡 关于模型命名：模型名称的格式是 提供商.模型名。你可以从下面的可用模型列表中选择你想要的模型。

第 4 步：探索可用模型并切换

🎯 目标：了解 Copilot 提供哪些模型，并学会在配置文件中切换它们。

📝 操作：

GitHub Copilot 提供了多个 AI 模型，包括 OpenAI、Anthropic 和 Google 的模型。要切换模型，只需修改 model 字段的值。

可用模型列表（部分）：

提供商	模型名称 (在 OpenCode 中使用)
OpenAI	`copilot.gpt-4o`, `copilot.gpt-4o-mini`, `copilot.gpt-4.1`, `copilot.o1`, `copilot.o3-mini`, `copilot.o4-mini`
Anthropic	`copilot.claude-3.5-sonnet`, `copilot.claude-3.7-sonnet`, `copilot.claude-sonnet-4`
Google	`copilot.gemini-2.0-flash`, `copilot.gemini-2.5-pro`

例如，切换到 Claude 3.5 Sonnet：

json

{
  "agents": {
    "coder": {
      "model": "copilot.claude-3.5-sonnet",  // 修改模型名称
      "maxTokens": 5000
    }
  }
}

✅ 验证：保存配置后，再次向 OpenCode 发送指令，观察回复的风格和效果是否发生变化。

⚠️ 注意：某些模型（如 o1）可能不在你当前的 Copilot 订阅计划中。如果切换后无法使用，请检查你的订阅等级或换回一个你确定可用的模型。

进阶技巧：配置推理模型

对于支持“推理”的模型（如 o1、o3-mini），你可以调整其推理深度。

📝 操作：

在 agent 配置中添加 reasoningEffort 字段：

json

{
  "agents": {
    "coder": {
      "model": "copilot.o1",
      "maxTokens": 5000,
      "reasoningEffort": "high"  // 可选: low, medium, high
    }
  }
}

low: 响应快，推理少。
medium: 平衡模式（默认）。
high: 推理更深，响应更慢，但结果可能更准确。

💡 提示：此设置对不支持推理的模型无效，会被 OpenCode 忽略。

常见问题与排错

Q1: 报错 GitHub token not foundA: OpenCode 没有找到任何有效的 GitHub 凭证。 解决方案：

确认你已按照第 1 步（使用 VS Code、gh CLI 等）完成认证。
如果使用环境变量，确认 GITHUB_TOKEN 已正确设置并加载（echo $GITHUB_TOKEN）。
如果使用配置文件，确认 apiKey 字段已正确填写。

Q2: 报错 Failed to exchange GitHub tokenA: 你的 GitHub Token 没有换取 Copilot 服务的权限。 解决方案：

访问 GitHub Settings > Copilot，确保 Copilot Chat in the IDE 选项已启用。
确认你的 GitHub Copilot 订阅是激活状态。
如果你使用的是个人访问令牌，请确认它拥有 read:user、read:org 等必要权限，或者直接使用 gh auth login 方式。

Q3: 报错 Authentication failed (401)A: OpenCode 用于访问 Copilot API 的临时令牌已过期。 解决方案：

OpenCode 通常会自动刷新令牌。如果问题持续，请尝试：
1. 重新运行 gh auth login（如果使用 gh CLI）。
2. 在 VS Code 中退出并重新登录 GitHub Copilot 账号。
3. 如果使用了环境变量，确认 Token 本身没有过期。

Q4: 模型不可用A: 你选择的模型在当前 Copilot 订阅计划中不存在。 解决方案：

尝试使用列表中的其他模型，如 copilot.gpt-4o 或 copilot.claude-3.5-sonnet，这些通常是基础订阅计划包含的。
检查你的 GitHub Copilot 订阅详情，了解可用的模型范围。

总结

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

认证方式：OpenCode 通过复用 VS Code、gh CLI 等工具的认证文件，或手动配置 Token 来获取 GitHub 权限。
配置文件：通过修改 ~/.opencode.json 文件中的 providers.copilot 和 agents 部分，可以启用、禁用和切换 Copilot 模型。
模型选择：Copilot 提供了多个提供商（OpenAI, Anthropic, Google）的模型，你可以根据任务需求灵活切换。

OpenCode 接入 GitHub Copilot ​

你将学到什么 ​

最终效果 ​

前置准备 ​

第 1 步：准备你的 GitHub 身份认证 ​

第 2 步（备选）：使用显式 GitHub Token 进行配置 ​

第 3 步：在 OpenCode 中启用并配置 Copilot ​

第 4 步：探索可用模型并切换 ​

进阶技巧：配置推理模型 ​

常见问题与排错 ​

总结 ​

OpenCode 接入 GitHub Copilot

你将学到什么

最终效果

前置准备

第 1 步：准备你的 GitHub 身份认证

第 2 步（备选）：使用显式 GitHub Token 进行配置

第 3 步：在 OpenCode 中启用并配置 Copilot

第 4 步：探索可用模型并切换

进阶技巧：配置推理模型

常见问题与排错

总结