企业官网建设流程全解析

OpenClaw 接入阿里云百炼（Alibaba Model Studio）Wan 视频生成完全指南

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

OpenClaw 内置的alibaba插件以 DashScope（Model Studio 国际版）为后端，为 Agent 提供阿里通义万相（Wan）系列模型的视频生成能力，开箱即用、默认启用，只需一个 API Key 即可完成接入。本文将以 docs/providers/alibaba.md 为主线，结合 extensions/alibaba 插件源码与测试用例，完整讲解认证配置、模型选型、能力边界、高级配置与底层调用原理，帮助你在 OpenClaw 中快速跑通从文本/图片/参考视频生成 AI 视频的完整链路。

插件概览：Provider 身份与默认值

alibaba插件是 OpenClaw 内置（bundled）插件，用于在 Alibaba Model Studio（DashScope 的国际名称）上注册 Wan 系列模型的 video-generation provider。它默认启用（enabledByDefault: true），属于媒体（media）类目，无需手动激活——只要提供 API Key 即可使用。

从 openclaw.plugin.json 可以看到，插件通过contracts.videoGenerationProviders: ["alibaba"]声明其能力契约；而 index.ts 中register钩子同时做了两件事：注册alibabaprovider（含 API Key 认证方式），并调用api.registerVideoGenerationProvider(...)注册视频生成 provider。

官方文档给出的 Provider 核心属性如下：

对应到源码，video-generation-provider.ts 中定义了默认 Base URL 常量https://dashscope-intl.aliyuncs.com，与文档一致；index.ts 中envVars数组依次声明了三个可接受的环境变量，解析时取第一个非空值。

认证方式的实现细节

index.ts 通过createProviderApiKeyAuthMethod注册了 API Key 认证：

• flagName: "--alibaba-model-studio-api-key"——对应直传 CLI 参数；
• optionKey: "alibabaModelStudioApiKey"——对应配置/命令行选项键；
• envVar: "MODELSTUDIO_API_KEY"——向导写入时优先使用的主环境变量；
• wizard.choiceId: "alibaba-model-studio-api-key"——onboarding 交互中的认证选项 ID；
• onboardingScopes: ["image-generation"]——该认证仅服务于媒体生成类目。

测试用例 video-generation-provider.test.ts 验证了该注册行为：捕获插件注册结果后，videoGenerationProviders只包含alibaba一个 provider、modelCatalogProviders为空、provider 列表长度为 1，且非交互式校验（validateNonInteractive）会把--alibaba-model-studio-api-key的值正确解析为MODELSTUDIO_API_KEY对应的 API Key。

快速开始：三种方式配置 API Key

方式一：通过 onboarding 向导存储

openclaw onboard --auth-choice alibaba-model-studio-api-key

交互式向导会把 Key 持久化到alibabaprovider 的认证存储中。

方式二：命令行直传

openclaw onboard --alibaba-model-studio-api-key <your-key>

该方式对应源码中flagName: "--alibaba-model-studio-api-key"的定义，适合脚本化接入。

方式三：导出环境变量（在启动 Gateway 之前）

export MODELSTUDIO_API_KEY=sk-... # or DASHSCOPE_API_KEY=... # or QWEN_API_KEY=...

三个变量按MODELSTUDIO_API_KEY→DASHSCOPE_API_KEY→QWEN_API_KEY的优先级取第一个非空值。从测试 video-generation-provider.test.ts 可以看到，仅设置MODELSTUDIO_API_KEY时isConfigured即返回true，说明环境变量发现机制是生效的。

值得注意的一个细节：环境变量QWEN_API_KEY是 Qwen 插件与 Alibaba 插件共享的。测试 video-generation-provider.test.ts 证明，如果继承到的是 Qwen Coding Plan 的sk-sp-前缀 Key，provider 不会将其视为有效认证。

设置默认视频模型

在 OpenClaw 配置文件中，通过agents.defaults.mediaModels.video.primary指定默认视频模型：

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

设置后，Agent 调用video_generate工具时会自动使用该模型，无需每次显式指定。该配置项与 docs/gateway/config-agents.md 中关于 agent defaults 的模型配置体系一致；video_generate工具的完整参数与运行模式见 docs/tools/video-generation.md。

验证配置是否生效

openclaw models list --provider alibaba

该命令会列出全部五个内置 Wan 模型。如果MODELSTUDIO_API_KEY无法解析（例如未设置、值为空），openclaw models status --json会在auth.unusableProfiles中报告缺失的凭据，便于在自动化脚本中快速诊断。

凭据有效性检查的源码依据

插件在提交请求前就会做一次"能力门禁"检查。从 video-generation-provider.ts 的credentialPolicy可以看到两层校验：

1. acceptsApiKey：拒绝以sk-sp-开头的 Key——这类 Key 属于阿里云 Coding Plan / Token Plan 凭据，虽然与 Alibaba 共用环境变量别名，但无法通过 Wan 请求认证；
2. acceptsBaseUrl：拒绝coding.dashscope/token-plan.*.maas等非标准端点。

对应测试 video-generation-provider.test.ts 验证了"解析到 Coding Plan Key 时直接抛错且不发起任何 HTTP 请求"的行为，错误信息为：Alibaba Wan video generation requires a Standard DashScope endpoint and a same-region Standard API key; Coding Plan and Token Plan credentials are not supported.

内置 Wan 模型清单

其中wan2.6-r2v-flash是快速版参考视频生成模型。测试 video-generation-provider.test.ts 通过expectExplicitVideoGenerationCapabilities断言了每个模型只对外声明其匹配的运行时模式（mode），且defaultModel与models列表与 SDK 中的DEFAULT_DASHSCOPE_WAN_VIDEO_MODEL、DASHSCOPE_WAN_VIDEO_MODELS常量保持一致。

能力与限制

每个模型只声明与其匹配的运行时模式；几何参数（geometry）也遵循该模型族在厂商协议中的约定，而不是发送一个通用的参数形状。各模式的具体限制如下：

各模式的请求参数语义

• Wan 2.6 文本/参考模型：将resolution与aspectRatio换算为文档规定的精确size；
• Wan 2.6 图生视频：发送resolution档位，并沿用输入图片自身的宽高比；
• Wan 2.7 参考视频：发送更新的media、resolution、ratio字段，且始终生成音频（audio 不可关闭）。

请求未指定durationSeconds时，采用 DashScope 接受的默认值5 秒。

底层请求形状：从测试用例看实际 HTTP 调用

测试 video-generation-provider.test.ts 完整还原了一次异步生成流程，可以据此确认真实请求结构：

• 提交端点：https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis（POST JSON）；
• 请求体model为模型名（如wan2.6-r2v-flash）；
• input.prompt为提示词文本；
• input.reference_urls为参考素材 URL 数组；
• parameters.duration、parameters.audio、parameters.watermark一一映射到用户传入的durationSeconds、audio、watermark参数；
• 提交后轮询任务状态（GET/api/v1/tasks/{task-id}），完成后下载最终视频文件（示例中为https://example.com/out.mp4）。

这套"提交异步任务 → 轮询 → 下载"的流程与 docs/tools/video-generation.md 中描述的异步生成机制完全吻合：任务在后台处理期间，同一会话内的重复video_generate调用会返回当前任务状态而不是重复发起新任务。

⚠️ 参考素材必须是远程 URL

参考图片与参考视频必须为远程http(s)URL；DashScope 的参考模式会拒绝本地文件路径。请先上传到对象存储，或使用 media tool 流程（该流程产出的就是公网 URL）。

对应的快速失败逻辑有测试覆盖：video-generation-provider.test.ts 验证了当inputImages传入本地 buffer（{ buffer, mimeType }）时，provider 直接抛出Alibaba Wan video generation currently requires remote http(s) URLs for reference images/videos.错误，且不会发起任何 HTTP 请求。

高级配置

覆盖 DashScope Base URL（切换国内区端点）

Provider 默认使用 DashScope 国际端点。要切换到国内区端点，在配置文件的models.providers.alibaba下设置baseUrl：

{ models: { providers: { alibaba: { baseUrl: "https://dashscope.aliyuncs.com", }, }, }, }

Provider 在拼接 AIGC 任务 URL 前会去除尾部斜杠（trailing slashes），因此两种写法...com与...com/均可用。注意：国内与国际端点需要对应区域的 Standard API Key，混用会导致认证失败。

认证环境变量优先级

OpenClaw 按以下顺序解析 Alibaba API Key，取第一个非空值：

1. MODELSTUDIO_API_KEY
2. DASHSCOPE_API_KEY
3. QWEN_API_KEY

通过openclaw models auth login配置的auth.profiles条目优先于环境变量解析。轮换（rotation）、冷却（cooldown）与覆盖（override）机制详见 Auth profiles in the models FAQ。

源码与测试对"profile 优先于环境变量"的语义有明确验证：video-generation-provider.test.ts 分别验证了 profile 中sk-ws-Standard Key 与环境变量sk-sp-Coding Key 共存时以 profile 为准、反之 profile 中 Coding Key 不会让 provider 生效的两种情况。

与 Qwen 插件的关系

两个内置插件都对接 DashScope，且接受重叠的 API Key。使用建议：

• alibaba/wan*.*模型 ID：用于本页介绍的专用 Wan 视频生成能力；
• qwen/*模型 ID：用于 Qwen 的对话（chat）、向量化（embedding）、媒体理解（media understanding），见 Qwen。

只要设置一次MODELSTUDIO_API_KEY，两个插件即可同时完成认证（认证环境变量列表是刻意重叠的），无需分别对两个插件执行 onboarding。

请求策略（request policy）的应用

从源码与测试还可以看到，provider 支持在models.providers.alibaba.request下配置请求策略，例如允许访问私有网络或附加自定义请求头。video-generation-provider.test.ts 验证了request.allowPrivateNetwork、request.headers会被正确传递到任务轮询与视频下载请求，并应用 SSRF 策略与调度器策略（dispatcherPolicy）。这为需要内网/代理环境的部署提供了灵活的出口控制能力。

实战排查清单

1. models list看不到 Wan 模型：检查MODELSTUDIO_API_KEY/DASHSCOPE_API_KEY/QWEN_API_KEY是否已设置且非空；用openclaw models status --json查看auth.unusableProfiles中是否报告缺失凭据。
2. 提交报 Coding/Token Plan 不支持：确认 Key 不是sk-sp-前缀，且baseUrl不是coding.dashscope或token-plan.*.maas端点；必须使用 Standard 端点与同区域 Standard Key。
3. 参考模式报本地路径错误：参考图片/视频必须使用http(s)公网 URL，先走 media tool 或对象存储完成上传。
4. 生成的视频时长不对：未传durationSeconds时按 5 秒默认值处理，且不同模式有 10 s / 15 s 的上限约束。
5. 任务长时间无结果：视频生成为异步任务，OpenClaw 提交后轮询任务状态；可用openclaw tasks list/openclaw tasks show <lookup>查看后台任务，详见 Background tasks（若该文档路径在仓库中存在）。

相关资源

• Video generation：video_generate工具的参数与多 Provider 选择逻辑；
• Qwen：基于同一 DashScope 认证的 Qwen 对话/向量化/媒体理解配置；
• Configuration reference：agent defaults 与模型配置体系；
• Models FAQ：auth profiles、模型切换与 "no profile" 错误的排查。

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