OpenClaw 集成 GitHub Copilot 指南
本文档介绍如何将 GitHub Copilot 作为模型提供商集成到 OpenClaw 中，实现通过 GitHub 账户调用 Copilot 模型能力。
什么是 OpenClaw
OpenClaw 是一个开源的 AI 助手平台，提供自托管的 AI 网关（Gateway）和代理（Agent）能力。它支持多种模型提供商（Anthropic、OpenAI、Google、GitHub Copilot 等），并能通过 Telegram、Discord、WhatsApp、iMessage 等多种渠道进行对话交互。
核心特性包括自托管 AI Gateway 支持多模型调度与故障转移，支持 30+ 种模型提供商，以及插件和技能扩展。系统兼容 macOS、Linux、Windows、Docker 和 Kubernetes 等多种环境。
什么是 GitHub Copilot
GitHub Copilot 是 GitHub 推出的 AI 编程助手，基于用户的 GitHub 账户和订阅计划，提供 GPT-4o、GPT-4.1、Claude 等多种大模型能力。将其接入 OpenClaw 后，可以免费或低成本地使用这些模型来驱动 AI 助手。
前提条件
在开始集成之前，请确保满足以下条件：
| 条件 | 说明 |
|---|---|
| GitHub 账户 | 需要已订阅 GitHub Copilot（个人版、商业版或企业版均可） |
| Node.js | 推荐 Node 24，最低支持 Node 22.14+ |
| 交互式终端（TTY） | 认证步骤需要在可交互的终端中执行，不支持纯脚本/CI 环境 |
| 操作系统 | macOS / Linux / WSL2（推荐）/ Windows 原生 |
检查 Node.js 版本：
node --version
安装 OpenClaw
macOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bash
Windows (PowerShell)
iwr -useb https://openclaw.ai/install.ps1 | iex
通过 npm 安装
npm install -g openclaw@latest
通过 pnpm 安装
pnpm add -g openclaw@latest
pnpm approve-builds -g # pnpm 需要显式批准含构建脚本的包
安装完成后运行引导程序
openclaw onboard --install-daemon
引导程序会帮助你选择模型提供商、配置 API Key，并启动 Gateway，整个过程约 2 分钟。
验证安装
openclaw --version
openclaw doctor
openclaw gateway status
确认 CLI 已安装，检查配置是否正常，并确认 Gateway 正在运行（默认监听端口 18789）。
两种集成方式
OpenClaw 提供两种方式集成 GitHub Copilot，根据实际使用场景选择：
| 方式 | 适用场景 | 是否需要 VS Code |
|---|---|---|
内置 github-copilot 提供商 | 大多数场景，最简便 | 不需要 |
| Copilot Proxy 插件 | 已在 VS Code 中运行 Copilot Proxy，或需要通过代理路由 | 需要（需保持运行） |
方式一：内置 GitHub Copilot 提供商（推荐）
这是最简单的集成方式，使用 GitHub 的设备授权（Device Flow）获取访问令牌，无需安装 VS Code。
第一步：执行登录命令
在可交互的终端中运行（不能在 CI/脚本中执行）：
openclaw models auth login-github-copilot
第二步：完成设备授权
命令执行后，终端会输出类似以下信息：
Visit: https://github.com/login/device
Enter code: XXXX-XXXX
Waiting for authorization...
- 使用浏览器访问
https://github.com/login/device - 输入终端中显示的一次性验证码
- 在 GitHub 页面授权 OpenClaw 访问你的 Copilot
- 授权完成后，保持终端开启，等待命令自动完成
注意： 请勿关闭终端，直到命令输出成功提示。
可选参数
指定自定义 Profile ID（适合管理多个 GitHub 账号）：
openclaw models auth login-github-copilot --profile-id github-copilot:work
跳过确认提示（自动接受）：
openclaw models auth login-github-copilot --yes
方式二：Copilot Proxy 插件
如果你已经在 VS Code 中安装并运行了 Copilot Proxy 扩展，可以让 OpenClaw 通过该代理的 /v1 端点访问 Copilot 模型。
前提： VS Code 中的 Copilot Proxy 扩展必须处于运行状态，OpenClaw 才能正常调用。
启用插件
在 OpenClaw 配置文件中启用 copilot-proxy 插件：
{
"plugins": {
"copilot-proxy": {
"enabled": true,
"baseUrl": "http://localhost:<代理端口>/v1"
}
}
}
将 <代理端口> 替换为 Copilot Proxy 实际监听地址。
设置默认模型
登录成功后，将 GitHub Copilot 提供的模型设置为默认模型：
# 设置 GPT-4o 为主模型
openclaw models set github-copilot/gpt-4o
# 或使用 GPT-4.1
openclaw models set github-copilot/gpt-4.1
查看当前可用模型：
openclaw models list
查看模型状态和认证信息：
openclaw models status
配置文件示例
手动编辑配置文件（位于 ~/.openclaw/config.json5）：
最简配置
{
agents: {
defaults: {
model: { primary: "github-copilot/gpt-4o" }
}
}
}
配置主模型 + 备用模型（故障转移）
{
agents: {
defaults: {
model: {
primary: "github-copilot/gpt-4o",
fallbacks: [
"github-copilot/gpt-4.1",
"openai/gpt-4o" // 可选：其他提供商作为最终备用
]
}
}
}
}
指定 Profile ID（多账号场景）
{
agents: {
defaults: {
model: { primary: "github-copilot/gpt-4o" }
}
},
auth: {
profiles: [
{ id: "github-copilot:work", provider: "github-copilot" }
]
}
}
配置模型允许列表（限制可用模型）
{
agents: {
defaults: {
model: { primary: "github-copilot/gpt-4o" },
models: {
"github-copilot/gpt-4o": { alias: "Copilot GPT-4o" },
"github-copilot/gpt-4.1": { alias: "Copilot GPT-4.1" }
}
}
}
}
模型管理
常用 CLI 命令速查
# 查看当前模型状态
openclaw models status
# 列出所有配置的模型
openclaw models list
# 列出所有可用模型（包含完整目录）
openclaw models list --all
# 切换主模型
openclaw models set github-copilot/gpt-4o
# 添加备用模型
openclaw models fallbacks add github-copilot/gpt-4.1
# 查看备用模型列表
openclaw models fallbacks list
# 删除备用模型
openclaw models fallbacks remove github-copilot/gpt-4.1
# 添加模型别名
openclaw models aliases add "copilot" github-copilot/gpt-4o
在对话中切换模型
在 Control UI 或支持的频道中，可以使用斜杠命令临时切换模型：
/model
/model list
/model github-copilot/gpt-4o
/model status
常见问题排查
1. 模型被拒绝访问（'Model rejected'）
原因： 当前 GitHub Copilot 订阅计划不支持该模型。
解决方案：
# 尝试切换到其他 Copilot 模型
openclaw models set github-copilot/gpt-4.1
# 查看订阅计划支持的模型
openclaw models list --provider github-copilot
2. 登录命令报错"requires interactive TTY"
原因： 在非交互式终端（如 CI 流水线、SSH 无 TTY 会话）中执行了登录命令。
解决方案： 在本机的普通终端窗口中直接执行登录命令，不要通过脚本调用。
3. 命令执行后提示"openclaw: command not found"
解决方案：
# 检查全局包安装路径
npm prefix -g
# 确认 bin 目录在 PATH 中
echo "$PATH"
# 若不在 PATH，手动添加（以 zsh 为例）
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
4. 认证令牌过期
GitHub Copilot 的令牌会定期过期，需要重新登录：
openclaw models auth login-github-copilot
5. 模型显示"not allowed"错误
原因： 配置了 agents.defaults.models 允许列表，但所选模型不在列表中。
解决方案： 将模型添加到允许列表，或清除允许列表：
// 在配置文件中添加该模型
{
agents: {
defaults: {
models: {
"github-copilot/gpt-4o": {}
}
}
}
}
6. 运行诊断检查
openclaw doctor
参考资料
| 资源 | 链接 |
|---|---|
| OpenClaw 官方文档 | docs.openclaw.ai |
| GitHub Copilot 集成页面 | docs.openclaw.ai/providers/github-copilot |
| OpenClaw 安装指南 | docs.openclaw.ai/install |
| 快速上手 | docs.openclaw.ai/start/getting-started |
| 模型 CLI 参考 | docs.openclaw.ai/concepts/models |
| 模型提供商总览 | docs.openclaw.ai/concepts/model-providers |
| 模型故障转移 | docs.openclaw.ai/concepts/model-failover |
| 配置参考 | docs.openclaw.ai/gateway/configuration-reference |
| OpenClaw GitHub 仓库 | github.com/openclaw/openclaw |
