OpenClaw Vydra Provider 插件实战指南：图像、视频与语音生成的一体化接入-编程实验室

OpenClaw Vydra Provider 插件实战指南：图像、视频与语音生成的一体化接入

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

导读

本文基于 OpenClaw 仓库中官方 Vydra Provider 插件（extensions/vydra）的源码与文档，系统讲解如何通过openclaw plugins install安装插件、配置VYDRA_API_KEY鉴权，并深度剖析其图像生成、视频生成与语音合成三大 Provider 的实现原理——包括异步任务轮询、结果资产下载、SSRF 防护与超时控制等底层机制。读完本文，你将掌握在 OpenClaw 网关中一键接入 Vydra 媒体生成能力，并理解插件与 Plugin SDK 之间的契约调用关系。

插件概览：OpenClaw 官方 Vydra 媒体生成 Provider

Vydra Provider 是 OpenClaw 的官方插件，为图像、视频与语音三类媒体生成能力提供统一接入。插件以@openclaw/vydra-provider为名发布，插件元数据中声明了分类models、voice、media，且enabledByDefault: true、onStartup: false（即默认启用但不在启动时激活，见 openclaw.plugin.json）。

从插件入口 index.ts 可以看到，插件在注册阶段一次性挂载了三条能力：

api.registerSpeechProvider(buildVydraSpeechProvider())— 语音合成
api.registerImageGenerationProvider(buildVydraImageGenerationProvider())— 图像生成
api.registerVideoGenerationProvider(buildVydraVideoGenerationProvider())— 视频生成

三条能力统一以vydra为 Provider ID，并共同依赖VYDRA_API_KEY这一个环境变量完成鉴权。openclaw.plugin.json中的contracts字段也与此对应，声明了speechProviders、imageGenerationProviders、videoGenerationProviders三个契约各含vydra，这是网关侧发现与路由能力的基础。

安装与鉴权配置

安装插件

官方 README（extensions/vydra/README.md）给出了两条命令完成安装与生效：

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

package.json中的openclaw.install元数据显示，该插件同时发布到 ClawHub 与 npm（clawhubSpec与npmSpec均为@openclaw/vydra-provider），默认安装渠道为 npm，并要求宿主版本>=2026.7.2，Plugin API 兼容版本>=2026.9.3。安装后必须重启网关，新的 Provider 才会被加载。

配置 API Key

插件通过环境变量VYDRA_API_KEY鉴权。入口注册的 auth 方法（index.ts）提供了多种配置途径：

环境变量：VYDRA_API_KEY
CLI 参数：--vydra-api-key
配置文件：vydraApiKey选项
交互式引导：openclaw初始化向导中的vydra-api-key选项（属于vydra分组，引导范围覆盖image-generation）

值得说明的是，插件在完成 API Key 配置后还会自动执行一次"开机自检式"的配置注入（onboard.ts）：若agents.defaults.mediaModels.image尚未设置，则自动将其主模型指向vydra/grok-imagine，让图像生成能力在配置完成后立即可用，无需手动指定模型。

自定义 Base URL 与语音参数

除 API Key 外，插件还支持若干可选配置项。语音 Provider 的配置归一化逻辑（speech-provider.ts）逐级回退读取配置，优先级从高到低为：会话/Provider 级配置 → 环境变量 → 内置默认值：

配置项	环境变量	默认值	说明
`baseUrl`	`VYDRA_BASE_URL`	`https://www.vydra.ai/api/v1`	API 端点地址，可指向自建代理
`model`	`VYDRA_TTS_MODEL`	`elevenlabs/tts`	语音合成模型
`voiceId`	`VYDRA_TTS_VOICE_ID`	`21m00Tcm4TlvDq8ikWAM`	默认音色，对应 "Rachel"

Base URL 的归一化逻辑在 defaults.ts 中实现：传入vydra.ai域名会统一补全为www.vydra.ai，路径为空时自动补/api/v1，并去除末尾斜杠——这保证了无论用户配置时是否写全路径，请求端点都保持一致。

图像与视频生成的 Base URL 同样支持通过models.providers.vydra.baseUrl配置覆盖（见 shared.ts），并且models.providers.vydra.request配置会被传入sanitizeConfiguredModelProviderRequest做净化处理，再与默认请求头合并。

图像生成：文生图与能力边界

图像生成 Provider 实现在 image-generation-provider.ts，默认模型为grok-imagine。其能力声明非常明确：

generate：单次最多 1 张，不支持尺寸、宽高比、分辨率参数；
edit：关闭（enabled: false），即不支持图生图编辑；
传入输入图片会直接抛错："currently supports text-to-image only"；
count > 1会抛错："at most one image per request"。

请求体构造为：

{ "prompt": "你的提示词", "model": "text-to-image" }

即插件目前只开放 Vydra 的 text-to-image 能力，调用方（Agent 或上层工具）只需提供prompt。返回结果中除生成的图片资产外，还会携带jobId、imageUrl与status元数据，便于上层追踪任务状态。

视频生成：veo3 与 kling 双模型

视频生成 Provider 实现在 video-generation-provider.ts，默认模型为veo3，同时支持kling模型，能力声明为：

generate：单次最多 1 个视频；
imageToVideo：开启，最多 1 张输入图、1 个输出视频；
videoToVideo：关闭，传入参考视频会抛错。

两个模型的行为差异体现在请求体的构造逻辑resolveVydraVideoRequestBody中：

veo3（纯文生视频）：仅发送prompt；若误传输入图片会抛错提示该模型不支持图片参考输入；
kling（图生视频）：必须提供远程图片 URL（inputImages[0].url），否则抛错 "requires a remote image URL reference"。请求体会同时写入image_url与video_url两个字段——源码注释说明这是因为 Vydra 的 kling 路由对字段要求并不一致，插件做兼容性双写以规避问题。

视频任务的默认超时被放宽到120_000ms（DEFAULT_VYDRA_VIDEO_TIMEOUT_MS），以适配视频生成耗时更长的现实。

语音合成：TTS 与结果下载

语音 Provider 实现在 speech-provider.ts，默认模型elevenlabs/tts、默认音色 "Rachel"。其synthesize流程完整展示了 HTTP 请求、鉴权与资产下载的串联：

解析 Provider 配置与覆盖项（支持按次调用传入model/voiceId覆盖）；
通过resolveSpeechProviderApiKey解析 API Key（配置值优先于环境变量），缺失时抛 "Vydra API key missing"；
构造请求：POST {baseUrl}/models/{model}，请求体为{ "text": ..., "voice_id": ... }，携带Authorization: Bearer <key>与Content-Type: application/json；
从响应中提取音频 URL，若缺失则抛 "response missing audio URL"；
下载音频资产，输出格式根据 MIME 判定为wav或mp3，并返回audioBuffer、fileExtension等字段。

底层原理：任务轮询、结果提取与安全下载

图像与视频生成共用的核心实现位于 shared.ts，其流程是一个典型的"提交—轮询—下载"三步式异步任务模型：

1. 提交任务

runVydraGeneration首先解析鉴权上下文（resolveVydraRequestContext），再向POST {baseUrl}/models/{model}提交请求体。请求头默认注入 Bearer Token，且允许传入自定义request配置（经净化后合入）。

2. 轮询任务状态

提交响应若未直接携带完成状态或结果 URL，插件会提取jobId（兼容jobId/id两种字段），然后轮询GET {baseUrl}/jobs/{jobId}。轮询参数：

轮询间隔POLL_INTERVAL_MS = 2500ms；
最大尝试次数MAX_POLL_ATTEMPTS = 120；
判完成条件：状态为completed，或已能从响应中提取到结果 URL；
判失败条件：状态为failed/error/cancelled，并从error.message、error.detail或顶层message中提取失败原因。

轮询过程受统一的操作截止时间（ProviderOperationDeadline）约束，超时会抛出带标签的Vydra job {jobId} did not finish in time错误。

3. 结果 URL 提取

Vydra 不同接口的响应结构并不统一，因此插件实现了健壮的递归提取器extractVydraResultUrls（shared.ts）：

按媒体类型匹配主键：音频查audioUrl/audioUrls，图像查imageUrl/imageUrls，视频查videoUrl/videoUrls；
统一兜底键：resultUrl(s)、outputUrl(s)、url(s)；
递归下钻键：output(s)、result(s)、data、asset(s)，深度上限 5 层；
仅接受http://或https://开头的值。

该函数同样服务于语音合成的音频 URL 提取，是三个 Provider 共用的关键工具，并有专门的单元测试覆盖（见 shared.test.ts）。

4. 资产下载与安全防护

downloadVydraAsset负责把最终结果下载为本地资产，安全细节值得关注：

凭据不跨域泄露：仅当结果 URL 与 API 同源（origin 一致）时才附加 Vydra 的鉴权头与自定义头，跨域 CDN 地址一律不带凭据（shared.ts）；
SSRF 防护：默认不允许访问私网地址，请求通过fetchWithTimeoutGuarded携带ssrfPolicy与dispatcherPolicy执行，审计上下文标记为vydra-media-download；
大小限制：按媒体类型调用resolveGeneratedMediaMaxBytes限制下载体积，超限抛exceeds {maxBytes} bytes错误；
超时控制：HTTP 默认超时120_000ms，下载阶段按操作截止时间动态解析剩余额度，防止整体任务被单个慢下载拖死；
MIME 兜底：响应无Content-Type时按类型回退（图片image/png、音频audio/mpeg、视频video/mp4），文件扩展名由 MIME 推导，推导失败再按类型兜底（png/mp3/mp4）。

测试验证

插件测试集中在 shared.test.ts 与各 Provider 测试（image-generation-provider.test.ts、video-generation-provider.test.ts、speech-provider.test.ts），另有连接真实服务的 vydra.live.test.ts。shared 测试使用本地 HTTP 服务器模拟"滴流式"（chunked drip）慢速响应，验证下载在墙钟截止时间内被强制终止——这直接印证了插件对慢服务与挂起连接的兜底能力。

典型接入流程总结

将以上内容串成一次完整的实战流程：

安装：openclaw plugins install @openclaw/vydra-provider，随后openclaw gateway restart；
配置：设置VYDRA_API_KEY（或使用--vydra-api-key/ 引导向导）；可选设置VYDRA_BASE_URL、VYDRA_TTS_MODEL、VYDRA_TTS_VOICE_ID；
使用：配置 API Key 后插件会自动将默认图像模型设为vydra/grok-imagine；此后即可通过 OpenClaw 的媒体生成能力发起图像（grok-imagine）、视频（veo3/kling）与语音（elevenlabs/tts，音色 Rachel）生成请求；
观测：每次生成返回的jobId与status元数据可用于任务追踪与日志审计。