qwen-code Auth Provider Registry以 Provider 为统一抽象重构 API Key、OAuth 与订阅套餐认证体系【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读本文基于 qwen-code 仓库中的 auth/motivation.md 设计文档系统讲解 Qwen Code 认证模块的一次关键重构把原本各自独立的 API Key、OAuth、订阅套餐Coding Plan / Token Plan与自定义 Provider 设置流程统一收敛到「Provider 配置 ProviderInstallPlan 安装计划」这一共享抽象之上。读完本文你将掌握ProviderConfig声明式契约的字段语义、buildInstallPlan如何把用户输入翻译成唯一可被设置写入器理解的安装计划、applyProviderInstallPlan的分步落盘与回滚机制以及如何通过新增一个 provider preset 文件为项目贡献一个新的内置第三方提供商。一、重构动机从「各自为政的认证流程」到「统一的 Provider 抽象」重构前的认证模块把每一条配置路径都建模为独立的流程API Key 是一种、OAuth 是一种、订阅套餐又是一种、自定义 Provider 还是一种。但在实践中所有这些路径产出的最终结果完全相同——都是对用户~/.qwen/settings.json中 provider 配置的更新。因此这次重构把Provider 设置提升为共享抽象一个 provider 描述它如何被展示、如何收集凭据、会安装哪些模型、以及应该应用哪份 settings 补丁。API Key、OAuth、Coding Plan、Token Plan、自定义向导本质上都是某个 provider 的设置方法setup methods而不是独立的认证架构。从当前仓库的实际代码布局看这套抽象最终落在 packages/core/src/providers/ 目录设计文档中的路径为packages/cli/src/auth/实现时下沉到 core 包以便 CLI、VS Code 插件、Web Shell 等多端复用结构为packages/core/src/providers/ ├── all-providers.ts # Provider 注册表与查找函数 ├── provider-config.ts # buildInstallPlan、模型构建、元数据版本计算 ├── types.ts # ProviderConfig / ProviderSetupInputs / ProviderInstallPlan 等类型 ├── install.ts # applyProviderInstallPlan 设置写入器 ├── model-discovery.ts # 从 /models 拉取账户模型推荐 └── presets/ ├── alibaba-coding-plan.ts ├── alibaba-token-plan.ts ├── alibaba-standard.ts ├── deepseek.ts ├── grok.ts ├── idealab.ts ├── minimax.ts ├── modelscope.ts ├── moonshot.ts ├── openrouter.ts ├── requesty.ts ├── zai.ts └── custom-provider.ts重构目标Goals保持/auth用户流程易于理解包括 Alibaba ModelStudio第一方 Qwen 设置、DeepSeek / MiniMax / Z.AI 等常见内置第三方集成、OpenRouter 等 OAuth Provider以及面向本地服务器、代理或未内置 provider 的自定义入口。把 provider 特有数据下沉到小型声明式配置每个 provider 的展示信息、协议、凭据键、模型清单全部声明化。让第三方 provider 贡献变得简单增加一个常见 provider 通常只需「新增一个 provider 配置 测试」。通过ProviderInstallPlan与applyProviderInstallPlan集中化 settings 写入。UI 分组与安装行为解耦分组只为用户在/auth中导航服务不驱动设置逻辑。保留模型列表归属model ownership与 provider 元数据的路径使 provider 模型更新可以被检测并安全应用。二、核心抽象ProviderConfig 声明式契约ProviderConfig是内置 provider 的声明式契约定义于 packages/core/src/providers/types.ts。它聚合了provider 标签、协议、base URL 选项、环境变量键、模型列表、模型元数据、UI 分组与设置行为。字段语义如下字段类型说明id/label/descriptionstringProvider 唯一标识、展示名与描述protocolAuthType通信协议如USE_OPENAI、USE_OPENAI_RESPONSES、USE_ANTHROPIC、USE_GEMINI当前 provider 固定baseUrlstring \| BaseUrlOption[] \| undefined固定字符串则跳过 UI 步骤选项数组则展示选择器undefined则由用户自由输入自定义 providerenvKeystring \| ((protocol, baseUrl) string)保存 API Key 的环境变量键自定义 provider 用函数派生modelsModelSpec[] \| undefined模型定义含可选逐模型元数据undefined表示用户必须自行输入全部模型 IDmodelsEditableboolean是否允许用户在设置 UI 中增删模型已知 ID 会继承其ModelSpec元数据supportsModelDiscoveryboolean是否从/models加载账户当前模型推荐modelNamePrefixstring \| ((baseUrl) string)模型条目显示名前缀protocolOptionsAuthType[]供自定义 provider 手动选择的协议选项多于 1 项时展示协议选择步骤showAdvancedConfigboolean是否展示高级配置步骤thinking、modalities 等validateApiKey(key, baseUrl) string \| null提交前校验 API Key返回错误消息或 nullcustomHeadersRecordstring, string随每个请求发送的自定义 HTTP 头如 OpenRouter/Requesty 网关期望的HTTP-Referer、X-Title安装时合并进每个模型的generationConfig.customHeadersownsModel(model) boolean自定义归属检查识别属于该 provider 的模型缺省时由字符串型envKeymodelNamePrefix自动推导mergeModelsByIdentityboolean安装时仅按「id baseUrl」替换传入的模型身份而非替换所有ownsModel匹配的模型适用于同一 provider 配置下可共存多端点多模型 ID 的用户自定义 providerwebSearch{ backend: dashscope }该 provider 可复用主模型凭据提供内置web_search后端uiGroupstringUI 分组提示AuthDialog据此把 provider 组织进不同区块一个真实的内置 provider 示例Z.AI文档中特别强调「Z.AI 必须使用 setup 专属的 base URL」这在 packages/core/src/providers/presets/zai.ts 中得到了精确落实——通过BaseUrlOption[]让用户在设置界面二选一export const zaiProvider: ProviderConfig { id: zai, label: Z.AI API Key, description: Quick setup for Z.AI models, protocol: AuthType.USE_OPENAI, baseUrl: [ { id: standard-api-key, label: Standard API Key, url: https://api.z.ai/api/paas/v4, documentationUrl: https://docs.z.ai/, }, { id: coding-plan, label: Coding Plan, url: https://api.z.ai/api/coding/paas/v4, documentationUrl: https://docs.z.ai/, }, ], envKey: ZAI_API_KEY, models: [ { id: GLM-5.2, contextWindowSize: 1000000, enableThinking: true }, { id: GLM-5.1, contextWindowSize: 204800, enableThinking: true }, { id: GLM-5, contextWindowSize: 204800 }, { id: GLM-5-Turbo, contextWindowSize: 204800 }, ], modelsEditable: true, modelNamePrefix: Z.AI, uiGroup: third-party, };可以看到Coding Plan指向https://api.z.ai/api/coding/paas/v4Standard API Key指向https://api.z.ai/api/paas/v4与设计文档完全一致。另一处示例Alibaba Coding Plan 的专属校验alibaba-coding-plan.ts 展示了 provider 级校验与地域 base URL 选项的配合——Coding Plan 的 API Key 必须以sk-sp-开头且中国区与国际区使用不同端点envKey: CODING_PLAN_ENV_KEY, // BAILIAN_CODING_PLAN_API_KEY baseUrl: [ { id: aliyun, label: China (Beijing), url: https://coding.dashscope.aliyuncs.com/v1, ... }, { id: alibabacloud, label: Singapore (International), url: https://coding-intl.dashscope.aliyuncs.com/v1, ... }, ], validateApiKey: (key) !key.startsWith(sk-sp-) ? Invalid API key. Coding Plan API keys start with sk-sp-. Please check. : null,三、安装计划buildInstallPlan与applyProviderInstallPlan设计文档定义了这条核心链路buildInstallPlan把 provider 配置 收集到的设置输入转换为ProviderInstallPlan——这是 settings 写入器唯一需要理解的对象applyProviderInstallPlan再应用该计划更新环境设置、modelProviders、选中的 auth 类型、可选的模型选择与 provider 元数据从而让 settings 持久化与收集输入的 UI 流程彻底解耦。ProviderInstallPlan 的结构定义于 types.tsexport interface ProviderInstallPlan { providerId: ProviderId; authType: AuthType; env?: Recordstring, string; // 例如 { ZAI_API_KEY: sk-... } legacyCredentials?: { apiKey?: string; baseUrl?: string }; modelSelection?: { modelId: string; baseUrl?: string }; modelProviders?: ProviderModelProvidersPatch[]; // 含 authType、models、mergeStrategy、ownsModel providerState?: ProviderInstallState; // 例如 providerMetadata.coding-plan.version display?: { successMessage?: string; nextSteps?: string[] }; }buildInstallPlanprovider-config.ts负责把ProviderConfig ProviderSetupInputs翻译为上述计划其中包括解析 envKey 与模型名前缀envKey与modelNamePrefix都支持「字符串」或「函数」两种形态函数形态在安装时按实际 protocol / baseUrl 动态求值构建模型配置固定模型清单直接映射ModelSpec可编辑清单则对已知 ID 查表继承元数据、未知 ID 走高级配置自定义 provider 完全由用户输入的 modelIds advancedConfig 生成模型并把enableThinking、multimodal、contextWindowSize、maxTokens翻译进generationConfig例如extra_body.enable_thinking、reasoning.effort、samplingParams.max_tokens空模型保护模型列表为空时直接抛错No models configured for provider ...默认模型选择取第一个模型作为modelSelection.modelId合并策略默认prepend-and-remove-owned新模型前置并移除旧的 owned 模型。applyProviderInstallPlan 的分步落盘applyProviderInstallPlaninstall.ts通过ProviderSettingsAdapter抽象执行写入完整执行顺序为backupsettings.backup?.()创建回滚备份env写入env.KEY并同步process.env。此处有双重防护一是拒绝清单——NODE_OPTIONS、NODE_PATH、LD_PRELOAD、PATH、HOME、TMPDIR等进程级环境变量一律禁止由安装计划写入防止代码注入 / PATH 劫持 / home 重定向二是遮蔽检测——若 shell 环境或.env文件已存在同名但不同值的变量会向用户输出警告提示重启后 shell/.env 值将优先modelProviders对每个 patch 按mergeStrategy合并append直接追加replace-owned替换 owned 模型默认prepend-and-remove-owned移除 owned 后前置新模型写入modelProviders.authTypeauthType写入security.auth.selectedTypelegacyCredentials按需写入security.auth.apiKey/security.auth.baseUrlmodelSelection这里有一个关键的保护逻辑——重复应用计划不得悄悄移走用户已选的模型见源码注释 #5819若计划仍然包含当前model.name且 baseUrl 匹配或为空则跳过模型切换真正首次设置才采纳 provider 默认模型。若确实切换且计划只按模型 ID 选择会用空字符串墓碑清掉旧model.baseUrl避免下次启动解析到共享同一模型 ID 的过期 providerproviderState逐字段写入providerMetadata.providerId.field如version、baseUrlpersist→reloadModelProviders→syncAuthState→refreshAuth→cleanupBackup。值得强调的是适配器契约中的一条关键警告见 types.ts 中ProviderSettingsAdapter注释CLI 的LoadedSettings适配器每次setValue都会立刻落盘因此进程中途崩溃可能留下部分写入——这正是backup()/restore()作为回滚路径存在的原因调用方不能假设「persist 之前磁盘未被触碰」。失败回滚与结构化错误整个 try/catch 链路对每一步失败都做了尽力而为的回滚settings.restore()恢复设置文件备份、还原已改写的process.env原值、把内存中的 runtime providers 恢复为安装前快照防止refreshAuth失败后会话持有未真正安装成功的 provider。最终抛出的ProviderInstallError是运行时类非接口携带step与authType结构化属性用于诊断cause保留原始错误同时保证用户可见的error.message干净可读。四、用户流程/auth 的四类入口如何汇聚到同一安装路径/auth依然呈现多个入口点但全部收敛到同一条 provider 安装路径1. Alibaba ModelStudio第一方 Qwen 设置包含三种子路径对应三个独立 presetCoding Planalibaba-coding-plan.ts面向个人开发者、含周配额环境变量键BAILIAN_CODING_PLAN_API_KEY提供中国北京与新加坡国际双区域端点API Key 以sk-sp-开头并由validateApiKey前置校验Token Planalibaba-token-plan.tsStandard API keyalibaba-standard.ts。Coding Plan preset 还开启了supportsModelDiscovery: true可从 ModelStudio 的/models接口拉取账户当前可用的模型推荐并支持 image / video 多模态如qwen3.5-plus、qwen3.6-plus的modalities: { image: true, video: true }。2. 第三方 Provider内置默认配置的常见提供商每个 provider 拥有自己的 base URL、env key、默认模型与模型元数据当前注册表all-providers.ts 的ALL_PROVIDERS内置DeepSeek、Grok、MiniMax、Z.AI、Moonshot、IdeaLab、ModelScope、OpenRouter、Requesty 等Z.AI 必须使用 setup 专属 base URLCoding Plan 为https://api.z.ai/api/coding/paas/v4Standard API key 为https://api.z.ai/api/paas/v4已在上文 preset 源码中验证。3. OAuth浏览器授权面向 OpenRouter 等路由平台的浏览器授权流程。OAuth 专属机制可以留在 provider 实现内部但最终产物仍然是一份 provider install plan——这正是「OAuth 只是 provider 的一种设置方法」这一核心论点的体现。4. 自定义 Provider本地服务器 / 代理 / 未内置提供商见 custom-provider.tsexport const customProvider: ProviderConfig { id: custom-openai-compatible, label: Custom Provider, description: Manually connect a local server, proxy, or unsupported provider, protocol: AuthType.USE_OPENAI, protocolOptions: [ AuthType.USE_OPENAI, AuthType.USE_OPENAI_RESPONSES, AuthType.USE_ANTHROPIC, AuthType.USE_GEMINI, ], baseUrl: undefined, envKey: generateCustomEnvKey, models: undefined, modelNamePrefix: , showAdvancedConfig: true, ownsModel: (model) typeof model.envKey string model.envKey.startsWith(CUSTOM_API_KEY_ENV_PREFIX), mergeModelsByIdentity: true, uiGroup: custom, };向导依次收集协议四选一、base URL、API Key、模型 ID以及高级模型选项thinking、多模态输入、上下文窗口、max tokens。两个实现细节值得注意派生环境变量键generateCustomEnvKey把(protocol, baseUrl)的 SHA-256 摘要前 12 位十六进制48 位作为后缀形如QWEN_CUSTOM_API_KEY_PROTOCOL_NORMALIZED_URL_12HEX避免结构不同的端点互相覆盖 API Key同时保持变量名可读、可粘贴进面板按身份合并mergeModelsByIdentity: true使/auth可以新增另一个自定义模型而不会删除同一端点下其他模型的既有配置。五、模型归属Model Ownership与更新检测设计文档对模型更新的要求是静态内置 provider 可以把元数据持久化在providerMetadata.providerId下含模型列表版本与 base URL从而在 provider 内置模型列表变化时提示用户更新 owned 模型同时不覆盖用户无关的自定义模型自定义 provider 的模型列表是用户自撰写的不应被视为可自动更新的内置列表。源码中的实现provider-config.tsPROVIDER_METADATA_NS providerMetadata是元数据命名空间前缀例如providerMetadata.coding-plan.versioncomputeModelListVersion对模型配置 JSON 做SHA-256 哈希作为模型列表版本指纹每次安装时写入providerMetadata.id.version与providerMetadata.id.baseUrlresolveMetadataKey只对带静态models列表的 provider 返回元数据键并拒绝含.的 provider id——因为setValue采用点路径遍历providerMetadata.foo.bar会被拆成嵌套对象导致设置树被悄悄破坏因此在注册期就显式抛错自定义 providermodels: undefined不产生元数据键天然不会被当作可自动更新的内置模型列表UI 侧通过useProviderUpdatespackages/cli/src/ui/hooks/useProviderUpdates.ts比对已保存版本与模板版本触发用户可感知的模型更新提示。归属判定则依靠ownsModel预设默认由envKeymodelNamePrefix推导模型须envKey相同且名称以[prefix]开头Coding Plan 等复杂预设自定义为「envKey 匹配且 baseUrl 属于中国区/国际区之一」自定义 provider 则以环境变量键前缀QWEN_CUSTOM_API_KEY_识别。findProviderByCredentialsall-providers.ts正是利用providerMatchesCredentials在/doctor、system-info 诊断中反查 provider。六、非目标Non-goals与贡献边界设计文档明确了四条红线用于约束后续演进方向不把 API Key、OAuth、Coding Plan、Token Plan 提升为顶层 settings 架构——它们只是 provider 的设置方法不让 settings 写入耦合到 React 组件或 CLI 命令处理器——统一经由applyProviderInstallPlanProviderSettingsAdapter不让 UI 分组成为业务逻辑轴——uiGroup只服务于/auth导航ALIBABA_PROVIDERS/THIRD_PARTY_PROVIDERS分组见 all-providers.ts不要求贡献者理解完整 auth UI 才能添加简单第三方 provider。这意味着贡献一个新内置 provider 的标准动作是在 presets/ 新增一个声明式ProviderConfig文件 → 在 all-providers.ts 的ALL_PROVIDERS注册 → 在tests/presets/ 补上对应测试现有 DeepSeek、MiniMax、Z.AI、Grok、Moonshot、IdeaLab、OpenRouter、Requesty 等均遵循此模式。另外若新 provider 从新环境变量键读取凭据还需按 all-providers.ts 头部注释的要求把该键加入 CI 无 AK 门禁的清除列表.github/workflows/ci.yml与scripts/tests/no-ak-integration-ci.test.js防止门禁泄漏 runner 凭据。安装与合并行为本身由tests/install.test.ts 与tests/provider-config.test.ts 覆盖包括合并策略、回滚、模型选择保留、元数据版本等核心语义。结语Auth Provider Registry 重构的实质是把「认证」从一组平行的 UI 流程收敛为「声明式 provider 配置 → 安装计划 → 统一设置写入器」的三段式管道。ProviderConfig让第三方贡献者只需描述「provider 长什么样、凭据怎么收、模型装哪些」ProviderInstallPlan让设置持久化与 UI 彻底解耦而applyProviderInstallPlan通过拒绝清单、遮蔽检测、分步回滚与版本化元数据为设置写入提供了可靠性与安全性兜底。这套设计不仅适用于当前 Qwen Code 的/auth界面也同时服务于 CLI、ACP 重连、VS Code 插件等所有需要安装 provider 的入口是理解项目认证与模型配置体系的枢纽。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考