OpenClaw + GitHub Copilot GPT-5.4 技术修复指南
背景与问题
本文档记录了如何在 OpenClaw 中解决 github-copilot/gpt-5.4 模型可用但无法正常工作的问题。虽然该模型在 OpenCode 中运行正常，但在 OpenClaw 环境下却会出现各种报错。
最终解决方案需要两步走：
- 修改
~/.openclaw/openclaw.json配置文件。 - 对已安装的 OpenClaw 运行时包进行补丁修补。
这是因为问题不仅仅在于模型注册，更涉及 OpenClaw 对 GitHub Copilot Responses API 流量的传输路由机制缺失。
常见报错现象
调试过程中可能会遇到以下错误：
1. 模型被拒绝
github-copilot/gpt-5.4 ... not allowed
2. IDE 认证头缺失
HTTP 400: bad request: missing Editor-Version header for IDE auth
3. 不支持的提供者模式
No API provider registered for api: github-copilot
4. 端点错误
HTTP 400: model "gpt-5.4" is not accessible via the /chat/completions endpoint
5. 网关不稳定
gateway disconnected: closed | idle
原因深度分析
主要有四个层面的问题导致上述故障。
1. 模型配置与白名单不匹配
OpenClaw 虽然能识别到提供者，但 github-copilot/gpt-5.4 并未完全接入 Agent 默认使用的活动模型配置路径。
2. 缺少 GitHub Copilot IDE 请求头
GitHub Copilot 需要特定的 IDE 风格请求头来进行身份验证。OpenClaw 默认通过通用的 OpenAI 兼容路径发送请求，导致这些关键头信息丢失。
必须包含以下请求头：
User-Agent: GitHubCopilotChat/0.35.0
Editor-Version: vscode/1.107.0
Editor-Plugin-Version: copilot-chat/0.35.0
Copilot-Integration-Id: vscode-chat
如果没有这些头信息，Copilot 会直接返回：
missing Editor-Version header for IDE auth
3. GPT-5.4 不是 Chat Completions 模型
gpt-5.4 必须使用 Responses API，而不是 /chat/completions。
因此，对于 gpt-5.4，以下配置是错误的：
"api":"openai-completions"
正确的配置应该是：
"api":"openai-responses"
4. OpenClaw 传输路由仅支持 openai
即使将 gpt-5.4 改为 openai-responses，如果 OpenClaw 的嵌入式 Runner 只为 openai 提供者激活了 Responses 传输通道，它仍会回退到通用流路径。
这会导致 OpenClaw 继续向 GitHub Copilot GPT-5.4 发送 /chat/completions 请求，从而引发错误。
涉及的文件
- 配置文件：
~/.openclaw/openclaw.json - 运行时包：
~/.nvm/versions/node/v22.22.0/lib/node_modules/openclaw/dist/reply-DhtejUNZ.js（请根据实际 Node 版本调整路径） - 重应用脚本：
~/.openclaw/workspace/patches/reapply-openclaw-copilot-gpt54-patches.mjs
第一步：修改 OpenClaw 配置
更新 ~/.openclaw/openclaw.json 中的 GitHub Copilot 提供者块。
提供者级别要求
使用以下配置：
{
"baseUrl": "https://api.individual.githubcopilot.com",
"api": "openai-completions"
}
为什么保持提供者 API 为 openai-completions？
因为 OpenClaw 运行时期望提供者保持在支持的通用适配器路径上。将整个提供者切换为 github-copilot 会导致运行时/提供者注册失败。
GPT-5.4 模型级别要求
设置 gpt-5.4 模型条目如下：
{"id":"gpt-5.4","name":"GPT-5.4","api":"openai-responses","reasoning":true,"input":["text","image"],"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0},"contextWindow":128000,"maxTokens":64000}
Agent 模型注册
确保存在以下配置：
"agents":{"defaults":{"models":{"github-copilot/gpt-5.4":{}}}}
第二步：修补 OpenClaw 注入 Copilot IDE 头信息
OpenClaw 需要在发送提供者请求前附加 Copilot IDE 头信息。
在运行时包文件中（路径见上文），在其他提供者包装器附近添加如下包装函数：
const GITHUB_COPILOT_IDE_HEADERS = {
"User-Agent": "GitHubCopilotChat/0.35.0",
"Editor-Version": "vscode/1.107.0",
"Editor-Plugin-Version": "copilot-chat/0.35.0",
"Copilot-Integration-Id": "vscode-chat"
};
function createGitHubCopilotHeadersWrapper(baseStreamFn) {
const underlying = baseStreamFn ?? streamSimple;
return (model, context, options) => {
return underlying(model, context, {
...options,
headers: { ...GITHUB_COPILOT_IDE_HEADERS, ...options?.headers }
});
};
}
然后在提供者包装器逻辑中应用它：
if (provider === "github-copilot") agent.streamFn = createGitHubCopilotHeadersWrapper(agent.streamFn);
第三步：修补 OpenClaw 正确路由 GitHub Copilot Responses
找到决定使用哪个流传输通道的分支代码。
原始行为如下：
} else if (params.model.api === "openai-responses" && params.provider === "openai") {
将其替换为：
} else if (params.model.api === "openai-responses" && (params.provider === "openai" || params.provider === "github-copilot")) {
为什么要这么做？
- 修补前，
github-copilot永远不会进入 Responses 传输分支。 - OpenClaw 会回退到
streamSimple。 streamSimple会命中/chat/completions。- GPT-5.4 会拒绝该端点。
修补后：
github-copilot+openai-responses会使用正确的 Responses 传输通道。- GPT-5.4 不再回退到 Chat Completions。
第四步：验证并重启
验证配置 JSON
node -e "JSON.parse(require('fs').readFileSync('/home/user/.openclaw/openclaw.json','utf8')); console.log('OK')"
验证修补后的包语法
node --check "/home/user/.nvm/versions/node/v22.22.0/lib/node_modules/openclaw/dist/reply-DhtejUNZ.js"
重启网关
openclaw gateway restart
验证流程
- 将模型设置为
github-copilot/gpt-5.4。 - 发送简单提示词，例如
hi。 - 确认网关保持连接状态。
- 确认不再出现以下错误：
missing Editor-Version header for IDE auth model "gpt-5.4" is not accessible via the /chat/completions endpoint No API provider registered for api: github-copilot
升级后重新应用补丁
由于运行时修复是直接打补丁到已安装的 OpenClaw 包上的，升级或重装可能会覆盖它。
请使用重应用脚本：
node ~/.openclaw/workspace/patches/reapply-openclaw-copilot-gpt54-patches.mjs openclaw gateway restart
设计说明
为什么不直接将整个提供者切换到 api: "github-copilot"？
这看起来很诱人，但 OpenClaw 的运行时路径在此设置下没有兼容的已注册流式提供者，会导致运行时/提供者注册失败。
为什么不保持 GPT-5.4 在 openai-completions 上？
因为 GitHub Copilot GPT-5.4 无法通过 /chat/completions 访问。它必须经过 Responses API。
为什么之前 OpenCode 可以工作？
OpenCode 已经正确处理了 GitHub Copilot 传输路径，包括所需的 Copilot 头信息和正确的 API 模式，而 OpenClaw 需要同时修复配置和运行时。
维护建议
- 将此指南与重应用脚本路径一起保存。
- 每次 OpenClaw 升级后，重新运行补丁脚本。
- 如果 OpenClaw 更改了包文件名，请相应更新脚本路径目标。
- 如果 GitHub Copilot 更改了所需的 IDE 头版本，请同时更新运行时补丁和重应用脚本。
快速恢复命令
node ~/.openclaw/workspace/patches/reapply-openclaw-copilot-gpt54-patches.mjs openclaw gateway restart openclaw status
最终状态
完成配置修复和运行时补丁后，github-copilot/gpt-5.4 可在 OpenClaw 中正常运行，且网关保持稳定。
