• 人工智能
• AI Agent
• 即时通讯
• 后端
• 本地部署
• 语音

本文面向希望复用 VS Code 中 Copilot Proxy 扩展所暴露的模型能力、为 openclaw-cn（Clawdbot）补充模型提供方的开发者。文中基于仓库内 copilot-proxy 插件 及 插件主实现，完整讲解该插件的作用、启用流程、认证配置、默认参数与自动生成的配置结构，并给出源码级实现细节与常见问题排查建议。读完即可在本地将 openclaw-cn 的默认模型切换到由 Copilot Proxy 转发的 GPT / Claude / Gemini 等模型上。

插件定位：连接 VS Code 与 openclaw-cn 的模型桥

openclaw-cn 本身以“Provider 插件（Provider plugin）”的形式抽象模型提供方：任何模型来源都可以通过一个插件注册为 provider，进而被 CLI、Agent 与 Gateway 统一调用。copilot-proxy正是这样一类插件，它的官方定位是：

Provider plugin for theCopilot ProxyVS Code extension.

也就是说，它解决的是“VS Code 里的 Copilot Proxy 扩展已在本地启动，但 openclaw-cn 还不知道怎么用它”的问题。该插件在 openclaw-cn 内部注册一个 id 为copilot-proxy的 provider，使 Agent 可以像调用其他模型一样，把请求发送到 VS Code 中 Copilot Proxy 扩展暴露的本地 HTTP 端点，从而间接使用 Copilot 订阅所覆盖的模型（如 gpt-5.2、claude-opus-4.5、gemini-3-pro 等）。

与仓库中其他模型插件（如 openclaw 官方文档中的 models 说明）不同，copilot-proxy 不需要真正的 API Key：本地代理本身就充当鉴权方，插件侧只需要配置“代理地址 + 想暴露的模型 ID 列表”即可。

第一步：启用插件（默认禁用）

openclaw-cn 中随发行包一起打包的插件（bundled plugins）默认是禁用的，需要显式启用：

openclaw-cn plugins enable copilot-proxy

启用成功后，需要重启 Gateway使插件生效：

openclaw-cn gateway restart

从实现上看，这一步在底层写入的是配置中的插件条目。核心逻辑位于 src/plugins/enable.ts 的enablePluginInConfig：它会将该插件的enabled置为true写入plugins.entries，同时把它加入plugins.allow允许名单；如果全局plugins.enabled === false或该插件出现在plugins.deny中，则启用会被拒绝并返回对应原因。因此若后续发现启用无效，可先检查这两处配置是否拦截。

启用后，插件系统会在 Gateway 启动时加载本插件，Provider 注册逻辑 会将copilot-proxy登记进 provider 注册表（重复注册同一 id 会报 “provider already registered” 诊断错误）。

第二步：交互式认证与模型配置

启用并重启后，执行认证命令：

openclaw-cn models auth login --provider copilot-proxy --set-default

该命令需要交互式 TTY（从 认证命令实现 中可看到，非 TTY 环境会直接报错），执行后会依次向你询问两项输入：

1. Copilot Proxy base URL：默认值为http://localhost:3000/v1。输入时会即时校验 URL 合法性（非法地址会提示Enter a valid URL），并自动规范化：去除首尾空白与末尾多余的/，若不以/v1结尾则自动追加/v1。
2. Model IDs（comma-separated）：默认预填一组模型 ID（见下文“默认模型列表”），按逗号或换行分隔，去重后作为该 provider 对外暴露的模型集合；若一个模型 ID 都没有，会提示Enter at least one model id。

认证完成后，--set-default会把默认模型设为copilot-proxy/<第一个模型>，后续 Agent 未显式指定模型时将优先使用它。若不加--set-default，则该模型只是“可用”而不会改变默认值（命令输出会提示use --set-default to apply）。

认证流程在源码中的落地

models auth login的完整处理链位于 src/commands/models/auth.ts 的modelsAuthLoginCommand：

• 通过resolvePluginProviders找到已加载的 provider 插件，用--provider copilot-proxy精确匹配（也支持别名匹配）；
• 调用插件注册的 auth 方法run(ctx)，得到ProviderAuthResult；
• 其中返回的profiles通过upsertAuthProfile写入本机认证档案（credential 类型为token，token 值固定为占位符n/a，provider 为copilot-proxy，profileId 为copilot-proxy:local）；
• 返回的configPatch通过mergeConfigPatch深度合并进主配置；
• 若指定--set-default，调用applyDefaultModel把copilot-proxy/<model>设为agents.defaults.model.primary（同时保留原有 fallbacks）。

整个过程结束后，配置文件中会生成完整的 provider 与模型注册信息（详见下节），并打印 auth profile 与默认模型日志。

自动写入的配置结构与参数详解

认证命令不是简单存一个 Key，而是把整套模型提供方配置合并进 openclaw-cn 主配置。合并后的效果等价于在配置中加入：

# 示意结构（实际由 models auth login 自动生成） models: providers: copilot-proxy: baseUrl: http://localhost:3000/v1 apiKey: n/a api: openai-completions authHeader: false models: - { id: gpt-5.2, name: gpt-5.2, api: openai-completions, reasoning: false, input: [text, image], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 128000, maxTokens: 8192 } # ... 其余模型同理 agents: defaults: models: copilot-proxy/gpt-5.2: {} copilot-proxy/claude-opus-4.5: {} # ... 每个模型 ID 一个条目

对应配置类型的定义可参见 src/config/types.models.ts：ModelProviderConfig支持baseUrl、apiKey、api、authHeader、headers、models等字段；ModelDefinitionConfig则描述单个模型的contextWindow、maxTokens、cost、input、reasoning等能力指标。这也意味着你随时可以手动编辑models.providers.copilot-proxy来调整这些参数，而不必重新执行认证命令。

插件默认参数一览（来自 index.ts）

默认模型列表

认证命令默认预填以下模型 ID（源码常量DEFAULT_MODEL_IDS）：

• gpt-5.2、gpt-5.2-codex
• gpt-5.1、gpt-5.1-codex、gpt-5.1-codex-max
• gpt-5-mini
• claude-opus-4.5、claude-sonnet-4.5、claude-haiku-4.5
• gemini-3-pro、gemini-3-flash
• grok-code-fast-1

需要注意：这份列表只是插件允许暴露的“候选”模型，实际能否调用取决于你的 Copilot 订阅计划，且代理服务端必须能识别这些模型名。模型不可用或想增减条目时，直接编辑models.providers.copilot-proxy.models即可（插件源码的 notes 也明确提示了这一点）。

源码实现细节：地址规范化、模型解析与模型定义

copilot-proxy插件的全部逻辑都集中在 extensions/copilot-proxy/index.ts，约 140 行，无外部运行时依赖，非常值得作为“最小 Provider 插件”范本阅读：

• 地址规范化normalizeBaseUrl：先trim，再循环去除尾部/，最后确保以/v1结尾。所以输入http://localhost:3000/、http://localhost:3000或http://localhost:3000/v1/都会被统一成http://localhost:3000/v1。
• 地址校验validateBaseUrl：基于new URL()做合法性检查，非法时返回Enter a valid URL，直接作为 CLI 输入校验提示。
• 模型解析parseModelIds：按\n与,分割、逐项trim、过滤空串，最后用Set去重。这意味着你可以粘贴一行逗号分隔的模型名，也可以粘贴多行模型名。
• 模型定义buildModelDefinition：为每个模型生成符合 ModelDefinitionConfig 结构的条目，id与name相同，协议固定为openai-completions，上下文窗口与最大输出 token 统一取默认值。
• 注册方式register(api)：调用api.registerProvider注册 id 为copilot-proxy的 provider，其auth数组只有一项kind: "custom"的交互式认证方法（id: "local"），这正是上面models auth login所执行的交互流程。

插件的元数据则由 openclaw.plugin.json（声明插件 id、providers、空配置 schema）与 package.json（声明入口./index.ts）共同构成。

使用前提与注意事项

综合 README 与源码中的 notes，使用本插件有三个硬性前提：

1. Copilot Proxy 必须正在 VS Code 中运行。openclaw-cn 只是代理的客户端，真正的模型鉴权与转发由 VS Code 扩展完成；插件启动前未打开 VS Code / 未启动该扩展，请求会失败。对应 defaultModel 的 notes 明确写着：Start the Copilot Proxy VS Code extension before using these models.
2. Base URL 必须包含/v1。因为 Copilot Proxy 暴露的是 OpenAI 兼容的/v1/chat/completions接口；虽然插件会自动补全/v1，但如果你手动编辑配置，请务必保留该路径段。
3. 模型可用性取决于 Copilot 订阅计划。默认列表中的模型是否真实可用由你的订阅与代理端决定，不可用时优先调整models.providers.copilot-proxy.models列表。

常见问题排查

• plugins enable无效果：检查主配置中plugins.enabled是否为false，或plugins.deny是否包含copilot-proxy；也可确认启用后是否重启了 Gateway。
• models auth login提示非 TTY 错误：该命令必须在交互式终端中执行，远程/脚本环境下无法完成交互输入。
• 请求超时或连接拒绝：确认 VS Code 已打开且 Copilot Proxy 扩展处于运行状态，并核对baseUrl端口（默认3000）是否被占用或修改。
• 某个模型不可用：默认列表为候选集合，实际可用模型取决于 Copilot 订阅计划；在配置中增删models.providers.copilot-proxy.models即可。

相关仓库路径速查

• 插件 README（启用、认证命令）
• 插件主实现（默认值、交互认证、配置生成）
• 插件清单 与 package.json
• 认证命令实现（models auth login全流程）
• 插件启用逻辑（plugins enable底层）
• Provider 注册表（registerProvider注册与去重）
• 模型配置类型（ModelProviderConfig/ModelDefinitionConfig字段定义）

• 人工智能
• AI Agent
• 即时通讯
• 后端
• 本地部署
• 语音