企业官网建设流程全解析

OpenClaw Qwen 插件参考：Qwen Cloud 多计划端点、模型目录与多模态契约全解析

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

本文以 OpenClaw 的 Qwen 插件参考文档为骨架，完整解析@openclaw/qwen-provider的分发方式、六个 provider 标识、端点与认证选项、按计费计划分层的模型目录、thinking 控制的数据线实现，以及媒体理解与视频生成两项契约能力。读完后可独立完成 Qwen Cloud / DashScope 各计划的接入配置，并理解插件在请求层做了哪些载荷约束。

插件概述与分发

Qwen 插件为 OpenClaw 增加Qwen、Qwen Cloud、Model Studio、DashScope、Qwen Token Plan、Bailian Token Plan模型提供者支持。它属于官方外部插件，不随核心捆绑发行，需要显式安装后重启 Gateway。

参考文档给出的分发信息（Distribution）如下：

• 包名：@openclaw/qwen-provider
• 安装路线：npm 或 ClawHub（clawhub:@openclaw/qwen-provider）

结合 plugins 入口说明，标准安装流程为：

openclaw plugins install @openclaw/qwen-provider openclaw gateway restart

从 package.json 可以确认该插件的版本约束与发布渠道：

• 当前版本2026.9.3，同时发布到 npm 与 ClawHub（publishToNpm与publishToClawHub均为true，默认安装渠道为 npm）；
• 要求宿主版本minHostVersion: ">=2026.6.8"，插件 API 兼容版本pluginApi: ">=2026.9.3"；
• 插件入口为./index.ts，即 插件入口文件。

Provider 面（Surface）

参考文档的 Surface 一节声明了两类接口面：

• Providers：qwen、qwencloud、modelstudio、dashscope、qwen-token-plan、bailian-token-plan
• Contracts：mediaUnderstandingProviders、videoGenerationProviders

六个 provider id 与家族映射

插件清单（openclaw.plugin.json）中，providers数组列出了全部六个 id；providerRequest字段则把它们统一归入modelstudio请求家族：

从 入口源码 的defineSingleProviderPluginEntry定义看，主 provider 的id为qwen，aliases显式包含modelstudio与qwencloud；dashscope作为请求家族别名同样被流包装器识别——stream.ts 的isQwenProviderId将qwen、qwen-token-plan、bailian-token-plan、modelstudio、qwencloud、dashscope六个规范化 id 都视为 Qwen 家族。

qwen-token-plan与bailian-token-plan并非在主入口注册，而是在register(api)回调中以独立 provider 形式注册：前者带完整认证与目录，后者仅作为“遗留自定义配置的所有者”注册（无认证方法、仅挂载流包装器），见 register 回调。这意味着：如果你已经在models.providers中手写了bailian-token-plan自定义条目，它的传输与目录归属不会被插件合并，插件只是“占有”这个 id 以避免冲突。

端点声明

清单中的providerEndpoints（清单 L15-L27 对应openclaw.plugin.json的providerEndpoints字段）声明了端点类modelstudio-native，并列出六个基地址：

这些常量在 models.ts 中有对应的导出（QWEN_BASE_URL、QWEN_CN_BASE_URL、QWEN_STANDARD_CN_BASE_URL、QWEN_STANDARD_GLOBAL_BASE_URL、QWEN_TOKEN_PLAN_GLOBAL_BASE_URL、QWEN_TOKEN_PLAN_CN_BASE_URL）。endpointClass: "modelstudio-native"的意义在于：凡是命中这些原生主机的传输都会被授予“流式 usage 兼容”行为（supportsNativeStreamingUsageCompat），因此指向相同原生主机的 DashScope 兼容自定义 provider 也能继承该行为，而不必使用内置qwenprovider id。

认证选项与环境变量

插件清单的setup字段（清单 L429-L440）声明了环境变量需求：

• qwen计划接受：QWEN_API_KEY、MODELSTUDIO_API_KEY、DASHSCOPE_API_KEY（三者互为兼容）
• qwen-token-plan计划接受：QWEN_TOKEN_PLAN_API_KEY

providerAuthChoices（清单 L441-L536）进一步定义了六个认证选项，每个选项带choiceId、CLI 标志、optionKey与端点提示：

注意qwen-*四个选项的deprecatedChoiceIds均指向旧的modelstudio-*id：旧 id 仍按兼容别名工作，但新的接入流程应使用规范的qwen-*id 与qwen/...模型引用。

认证选项在 入口源码 中逐一落地为methodId（standard-api-key-cn、standard-api-key、api-key-cn、api-key），全部使用环境变量QWEN_API_KEY，并通过applyConfig调用 onboard.ts 中的五个配置应用函数：

• applyQwenConfig/applyQwenConfigCn：写入 Coding Plan 的 Global / China 基地址；
• applyQwenStandardConfig/applyQwenStandardConfigCn：写入 Standard 的 Global / China 基地址；
• applyQwenTokenPlanConfig(region)：按区域解析 Token Plan 基地址（见 resolveQwenTokenPlanBaseUrl）。

这些函数基于createModelCatalogPresetAppliers生成：写入api: "openai-completions"传输、按认证选项确定的baseUrl、默认模型引用（Coding/Standard 为qwen/qwen3.5-plus，Token Plan 为qwen-token-plan/qwen3.7-plus），并为每个目录模型生成qwen/<model>与modelstudio/<model>双别名。若用户配置了models.mode: "replace"，则把完整目录模型行一并写入配置；否则仅保留连接设置与别名，不复制生成的目录行。

Token Plan 认证选项在 createQwenTokenPlanAuthMethod 中按global/cn区域工厂化生成，密钥提示为sk-sp-...前缀的专用密钥。相关文档特别强调：Token Plan 的密钥、Coding Plan 的密钥与按量付费密钥互不通用；且 Token Plan 仅适用于交互式 OpenClaw 会话，用于定时任务、无人值守脚本或应用后端可能触发订阅暂停或密钥吊销。

若 Gateway 以守护进程（launchd/systemd）方式运行，需确保QWEN_API_KEY或QWEN_TOKEN_PLAN_API_KEY对该进程可见（例如放在~/.openclaw/.env或通过env.shellEnv注入），这一点在 Qwen 使用文档 的“Environment and daemon setup”一节中有明确说明。

模型目录与按计划的目录抑制

qwen provider 种子目录

清单的modelCatalog.providers.qwen使用openai-completionsAPI，声明了 13 个种子模型（清单 L133-L273）。运行时通过 models.ts 的QWEN_MODEL_CATALOG从清单构建，默认模型引用为qwen/qwen3.5-plus（QWEN_DEFAULT_MODEL_REF）：

其中qwen3.8-max与qwen3.8-flash在清单中携带额外元数据：maxTokens提升至 131,072，并声明thinkingLevelMap（minimal→low、high/max→xhigh）与compat块（codeMode: "capable"、supportsReasoningEffort: true、supportedReasoningEfforts: ["low","medium","xhigh"]、同样的reasoningEffortMap）。

Coding Plan 的目录抑制

清单的modelCatalog.suppressions（清单 L55-L132）定义了 8 条按主机条件生效的抑制规则：当baseUrl主机为coding.dashscope.aliyuncs.com或coding-intl.dashscope.aliyuncs.com时，从目录中剔除qwen3.8-max、qwen3.8-flash、qwen3.6-flash、qwen3.7-max（对qwen与modelstudio两个 provider 各写一条）。抑制原因（reason字段）均说明这些模型不在 Qwen Coding Plan 端点支持范围，应改用 Standard 按量付费或 Token Plan 端点。

抑制逻辑在运行时有两处落点：

1. buildQwenModelCatalogForBaseUrl：buildQwenProvider构建 provider 时，若 baseUrl 命中 isQwenCodingPlanBaseUrl（解析 URL 主机并精确匹配两个 coding 主机），则过滤掉 isQwenStandardOnlyModelId 标记的“仅 Standard”模型集合（qwen3.6-flash、qwen3.7-max、qwen3.8-max、qwen3.8-flash）；
2. 入口的 normalizeConfig：对已是 Coding Plan 基地址的 provider 配置再执行一次同样的模型过滤，作为防御性收尾。

Token Plan 目录与发现模式

modelCatalog.providers["qwen-token-plan"]使用新加坡区基地址与独立的精确字符串允许名单，所有模型cost均为零（Token Plan 为信用制计费，按 token 标价不适用，见 models.ts 注释）：

发现模式在清单discovery字段中声明为：qwen采用runtime（凭已配置密钥实时调用端点/models接口发现），qwen-token-plan采用refreshable。modelsDev字段把两个 provider 分别映射到alibaba-coding-plan与alibaba-token-plan两个目录快照源。端点实时返回的模型即便不在种子目录中也可以出现（buildOpenAICompatibleLiveProviderCatalog以discoveryMode: "strict"运行），但“Standard 端点的模型列表不代表 Token Plan / Coding Plan 可用”这一边界仍然成立。

Thinking 控制的数据线实现

参考文档声明的 Surface 之外，Qwen 插件在流层实现了一整套 thinking 载荷约束，这是理解请求行为的关键。入口为 wrapQwenProviderStream，底层实现在 stream.ts。

通用规则：enable_thinking 开关

对openai-completions传输且reasoning: true（或被强制 thinking）的模型，createQwenThinkingWrapper 在每次请求上把 OpenClaw 的 thinking 级别映射为 DashScope 的顶层enable_thinking布尔量：关闭 thinking 发送enable_thinking: false，其余任何级别发送enable_thinking: true。模型条目的compat.thinkingFormat: "qwen-chat-template"可切换到聊天模板载荷（setQwenChatTemplateThinking），用于自定义模型的替代传输格式。

qwen3.8 家族：reasoning_effort 映射

patchQwen38Payload 对qwen3.8-max/qwen3.8-flash（判断见 isQwen38ModelId）：

• 级别minimal/low→reasoning_effort: "low"；medium→"medium"；high/xhigh/max→"xhigh"；
• 若请求中已存在显式thinking_budget，则删除reasoning_effort而保留调用方预算——Qwen 会拒绝同时携带两个字段的请求，即显式 token 预算优先于映射出来的 effort；
• 入口处 resolveQwenThinkingProfile 为该家族暴露off / low / medium / xhigh四个档位，默认xhigh。

Token Plan 各模型家族的差异化契约

resolveQwenThinkingContract（stream.ts L82-L102）按模型家族分派：

• DeepSeek V4（deepseek-v4*）：minimal–high映射为high，xhigh/max映射为max（patchTokenPlanDeepSeekV4Payload）；
• Kimi：thinking-only，即使会话请求/think off也保持 thinking 开启；
• GLM：minimal–xhigh直接透传为reasoning_effort，max仅glm-5.2接受（supportsQwenTokenPlanGlmMaxThinking），其余版本降级为xhigh（patchTokenPlanGlmPayload）；携带tools时追加tool_stream: true；
• thinking-only 模型（MiniMax-M2.5、kimi-k2.7-code*，见 isQwenTokenPlanThinkingOnlyModelId）：forceThinking置真，禁止关闭；
• tool_choice 归一化：normalizeTokenPlanThinkingToolChoice 处理 Token Plan 端点下 thinking 与工具选择的组合——{type: "auto"|"none"}的对象形式被改写为字符串形式；固定工具选择（tool/function）且非强制 thinking 时，直接回退为enable_thinking: false而不是破坏固定选择。

此外，createQwenConstraintWrapper 会在调用方的onPayload钩子（配置级extra_body等）之后再次执行 enforceQwenPayloadAfterCaller，确保无效字段（reasoningEffort、reasoning等）无法逃逸出插件边界。

多模态契约：媒体理解与视频生成

Surface 一节声明的两个契约在注册时落地：api.registerMediaUnderstandingProvider(buildQwenMediaUnderstandingProvider())与api.registerVideoGenerationProvider(qwenVideoGenerationProvider)。

媒体理解

buildQwenMediaUnderstandingProvider 声明capabilities: ["image", "video"]，图像与视频理解的默认模型均为qwen3.6-plus，并设置autoPriority.video: 15（与 清单 mediaUnderstandingProviderMetadata 一致）。视频描述走 OpenAI 兼容传输，默认基地址为Standard Global端点（dashscope-intl.aliyuncs.com/compatible-mode/v1）。

媒体理解仅挂在 Standard DashScope 端点上，Coding Plan 端点不支持，且由已配置的 Qwen 认证自动解析密钥，无需额外配置。

视频生成（Wan 系列）

qwenVideoGenerationProvider 基于buildDashscopeVideoGenerationProvider构建，默认基地址为dashscope-intl.aliyuncs.com，并实现了区域路由：配置的 Qwen 区域（Global/Intl 或 China）会被映射到对应区域的 DashScope AIGC 主机后提交视频任务；即使models.providers.qwen.baseUrl指向 Coding Plan 或 Standard 聊天主机，视频生成仍路由到匹配区域的 DashScope 视频端点（主机解析见 resolveDashscopeAigcApiBaseUrl）。

credentialPolicy明确了凭据边界：

• acceptsApiKey：拒绝以sk-sp-开头的密钥（那是 Token Plan 专用前缀）；
• acceptsBaseUrl：拒绝 Coding Plan 主机（isQwenCodingPlanBaseUrl）与token-plan.*.maas.aliyuncs.com主机；
• 不支持时的提示语：Wan 视频生成要求 Standard DashScope 端点与同区域的 Standard 密钥，Coding Plan 与 Token Plan 凭据均不支持。

按 Qwen 使用文档 的 Wan 模型矩阵，插件随附wan2.6-t2v（默认，文生视频，15 s）、wan2.6-i2v（图生视频，15 s）、wan2.6-r2v/wan2.6-r2v-flash（参考生视频，10 s）、wan2.7-r2v（10 s，音频恒开）。可将 Qwen 设为默认视频提供方：

{ agents: { defaults: { mediaModels: { video: { primary: "qwen/wan2.6-t2v" } }, }, }, }

参考图像/视频输入要求远程 http(s) URL；本地文件路径会被提前拒绝，因为 DashScope 视频端点不接受上传的本地缓冲作为参考素材。共享工具参数、provider 选择与故障转移行为见 视频生成文档。

高级配置要点

• 模型可用性边界：qwen3.7-plus、qwen3.6-plus在 Coding Plan 与 Standard 均可用；qwen3.8-max、qwen3.8-flash、qwen3.7-max、qwen3.6-flash仅限 Standard 或 Token Plan。若 Coding Plan 端点返回“不支持的模型”错误，应切换到对应 Standard / Token Plan 端点及其专用密钥。
• baseUrl 覆盖：认证选项自动选择端点；也可在models.providers.qwen.baseUrl中自定义基地址（入口的resolveConfiguredQwenBaseUrl会优先读取该配置，见 index.ts L47-L65）。
• models.mode: "replace"：显式替换模式会保留目录播种并保留自定义模型行。
• 流式 usage 兼容：六个原生端点主机（含 Token Plan 两个 maas 主机）在共享openai-completions传输上启用流式 usage 兼容，指向同一主机的自定义 provider id 自动继承。
• 能力路线图：文本/聊天模型、工具调用、结构化输出与 thinking 已可用（继承自 OpenAI 兼容传输）；图像/视频理解在 Standard 端点可用；视频生成已可用；图像生成与语音/音频、内存嵌入与重排处于 provider 插件层规划中。
• 认证历史：qwen-oauthPortal 提供者及其 OAuth 流程已移除，Portal 令牌与 Qwen Cloud / DashScope API 密钥不通用，现有 Portal 凭据不会被自动转换，必须用所选端点重新进行 API 密钥认证。

相关文档

• Qwen 插件参考（本文依据）
• Qwen 使用指南
• 模型选择与 provider
• 视频生成工具
• Alibaba Model Studio 提供方
• Ollama 本地发现、LM Studio 本地发现
• 故障排查

插件源码索引：入口、模型与端点常量、provider 构建、onboard 配置应用、流包装与 thinking 约束、视频生成 provider、媒体理解 provider、插件清单。

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw