企业官网建设流程全解析

OpenClaw Vydra 插件接入指南：图片、视频与语音生成一站式配置

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

本指南以 OpenClaw 仓库内 Vydra 官方文档 为核心，结合extensions/vydra插件源码，系统讲解如何在 OpenClaw 中接入 Vydra 媒体生成能力：通过vydra/grok-imagine文生图、vydra/veo3文生视频与vydra/kling图生视频，以及基于 ElevenLabs 路线的语音合成。读完本文，你将掌握从插件安装、API Key 配置到三大能力默认模型的完整配置方法，并理解插件底层基于 Job 轮询的媒体生成与下载机制，能够独立排查"base URL 重定向导致鉴权失败"等典型问题。

Vydra 插件能力总览

Vydra 官方插件（包名@openclaw/vydra-provider）为 OpenClaw 提供三类媒体生成能力，全部复用同一个VYDRA_API_KEY：

插件同时注册进三个能力契约，见 extensions/vydra/index.ts：api.registerSpeechProvider、api.registerImageGenerationProvider、api.registerVideoGenerationProvider，对应 openclaw.plugin.json 中声明的speechProviders、imageGenerationProviders、videoGenerationProviders三个契约。

Provider 关键属性

关于 Base URL 的重要警告

官方文档明确指出：必须使用https://www.vydra.ai/api/v1作为 Base URL。Vydra 的 apex 主机（https://vydra.ai/api/v1）当前会重定向到www，部分 HTTP 客户端在跨主机重定向时会丢弃Authorization头，导致"明明 API Key 有效却报鉴权失败"的误导性错误。

为避免这一问题，插件内置了 URL 规范化逻辑。在 defaults.ts 的normalizeVydraBaseUrl中：若解析出的url.hostname === "vydra.ai"，则强制改写为www.vydra.ai；同时去除路径末尾多余的/，若未指定路径则补齐/api/v1。也就是说，即使你在配置里写了 apex 主机，插件也会在请求前自动纠正，这是一道额外的安全网。默认 Base URL 常量定义在 extensions/vydra/defaults.ts：https://www.vydra.ai/api/v1。

安装与鉴权配置

安装插件并重启网关：

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

安装后运行交互式引导，选择 Vydra API Key 选项：

openclaw onboard --auth-choice vydra-api-key

也可以直接设置环境变量（跳过交互引导）：

export VYDRA_API_KEY="vydra_live_..."

鉴权相关的注册逻辑位于 extensions/vydra/index.ts，通过createProviderApiKeyAuthMethod定义了名为api-key的鉴权方式，其flagName为--vydra-api-key、envVar为VYDRA_API_KEY。从源码可以看出，引导时若配置中尚未设置图片模型的默认值，applyVydraConfig会自动将vydra/grok-imagine写入agents.defaults.mediaModels.image.primary（见 extensions/vydra/onboard.ts），这也是该插件 onboarding scope 为image-generation的原因。

配置默认能力

完成安装与 Key 配置后，从图片、视频、语音三种能力中任选其一（或组合），按下述配置写入 OpenClaw 配置文件。

图片生成（text-to-image）

默认且唯一的图片模型是vydra/grok-imagine。设为默认图片提供方：

{ agents: { defaults: { mediaModels: { image: { primary: "vydra/grok-imagine", }, }, }, }, }

从 image-generation-provider.ts 的实现看，该能力有明确的边界约束：

• 仅支持文生图：如果请求携带inputImages，会直接抛出"Vydra image generation currently supports text-to-image only"错误；
• 单次最多一张：req.count > 1时抛出"at most one image per request"；
• 不支持尺寸/宽高比/分辨率参数：capabilities.generate中supportsSize、supportsAspectRatio、supportsResolution均为false；
• 编辑能力关闭：capabilities.edit.enabled = false。文档补充说明，Vydra 托管的编辑路由期望远程图片 URL，而插件没有为其添加专属上传桥接，因此不做图生图/编辑。

请求体构造很简单：{ prompt, model: "text-to-image" }，POST 到${baseUrl}/models/grok-imagine。

视频生成（text-to-video 与 image-to-video）

注册的视频模型有两个：

• vydra/veo3：文生视频（拒绝图片参考输入）；
• vydra/kling：图生视频（必须恰好一张远程图片 URL）。

设为默认视频提供方：

{ agents: { defaults: { mediaModels: { video: { primary: "vydra/veo3", }, }, }, }, }

视频请求体的组装逻辑在 video-generation-provider.ts 的resolveVydraVideoRequestBody中，几个关键细节：

• kling 拒绝本地文件上传：req.inputImages[0].url为空时会抛出"Vydra kling currently requires a remote image URL reference"，必须使用远程 URL 引用；
• kling 路由字段兼容：源码注释说明 Vydra 的 kling HTTP 路由对到底需要image_url还是video_url一直不一致，因此插件把同一远程图片 URL同时写入两个字段（image_url与video_url），以兼容两种行为；
• veo3 拒绝图片输入：携带inputImages时抛出"Vydra veo3 does not support image reference inputs"；
• 拒绝视频参考输入：req.inputVideos非空时报错，videoToVideo能力为false；
• 不做保守外传：插件不转发文档未声明的风格旋钮（如宽高比、分辨率、水印、生成音频），只发送prompt（及 kling 的图片 URL）。

视频生成默认超时为 120 秒（DEFAULT_VYDRA_VIDEO_TIMEOUT_MS，见 video-generation-provider.ts），以deadlineTimeoutMs形式传入并联动整个 Job 轮询与下载流程。

视频实时测试（live tests）

插件附带 provider 级实时测试，用于验证两条视频链路：

OPENCLAW_LIVE_TEST=1 \ OPENCLAW_LIVE_VYDRA_VIDEO=1 \ pnpm test:live -- extensions/vydra/vydra.live.test.ts

测试覆盖：

• vydra/veo3文生视频；
• vydra/kling使用远程图片 URL 的图生视频。

需要时可覆盖远程图片 fixture：

export OPENCLAW_LIVE_VYDRA_KLING_IMAGE_URL="https://example.com/reference.png"

此外，仓库还包含完整的单元测试：video-generation-provider.test.ts 用桩 fetch 验证了完整的调用链——先 POSThttps://www.vydra.ai/api/v1/models/veo3提交 Job（返回{ jobId, status: "processing" }），再 GET/jobs/job-123轮询至completed，最后下载结果并产出video-1.webm这样的本地文件。同目录下的 image-generation-provider.test.ts 与 speech-provider.test.ts 分别覆盖图片与语音链路的等价行为。

语音合成（TTS）

将 Vydra 设为语音提供方：

{ tts: { provider: "vydra", providers: { vydra: { apiKey: "${VYDRA_API_KEY}", voiceId: "21m00Tcm4TlvDq8ikWAM", }, }, }, }

默认值：

• 模型：elevenlabs/tts
• 音色 id：21m00Tcm4TlvDq8ikWAM（即 "Rachel"）

插件只暴露这一个经过验证的默认音色（VYDRA_SPEECH_VOICES数组中仅有 Rachel，见 speech-provider.ts），合成结果返回 MP3 音频文件。synthesize的请求体为{ text, voice_id }，POST 到${baseUrl}/models/elevenlabs/tts。

语音配置支持额外的环境变量覆盖（speech-provider.ts）：

优先级为：配置文件tts.providers.vydra.*> 上述环境变量 > 代码内置默认值。此外 API Key 也支持双来源：配置中的apiKey或process.env.VYDRA_API_KEY，任一存在即视为已配置。

底层机制：Job 轮询与媒体下载

三类能力共享同一套底层运行时，核心实现在 extensions/vydra/shared.ts 的runVydraGeneration（图片/视频）与synthesize（语音）中，可以归纳为四个阶段：

1. 请求上下文解析：resolveVydraRequestContext通过resolveApiKeyForProvider读取VYDRA_API_KEY（缺失时抛出"Vydra API key missing"），并组装Authorization: Bearer <key>请求头；同时从models.providers.vydra.baseUrl读取用户自定义 Base URL 并做规范化。
2. 提交 Job：POST${baseUrl}/models/${model}，携带能力对应的请求体。
3. 轮询结果：若响应中状态不是completed且不含结果 URL，则从jobId/id字段解析 Job 标识，以 2.5 秒间隔（POLL_INTERVAL_MS）、最多 120 次（MAX_POLL_ATTEMPTS）轮询${baseUrl}/jobs/${jobId}；status为failed/error/cancelled时立即以错误信息终止（shared.ts）。
4. 下载产物：extractVydraResultUrls递归扫描响应中的imageUrl(s)/videoUrl(s)/audioUrl(s)以及resultUrl、outputUrl、url等常见字段（shared.ts），取第一个 URL 下载为本地文件；文件名形如image-1.png、video-1.mp4、audio-1.mp3（扩展名优先由 MIME 推断）。

值得注意的安全细节：下载资产时，只有与 API 同源的 URL 才会携带配置的鉴权头，跨域的结果 URL 一律不带凭据（resolveVydraAssetRequestHeaders，shared.ts），避免把 Vydra API Key 泄露给第三方 CDN。所有 HTTP 请求均受 SSRF 策略、超时截止（默认 120 秒）与maxBytes大小上限保护（resolveGeneratedMediaMaxBytes取自 OpenClaw 媒体生成配置）。

常见问题与排查建议

• 报错Vydra API key missing：确认已设置VYDRA_API_KEY，且网关在设置后已重启（openclaw gateway restart）。
• Key 有效却提示鉴权失败：优先检查 Base URL 是否写成了vydra.ai（apex 主机）。虽然插件会自动规范化，但跨主机重定向的丢头问题在部分客户端上仍可能残留，官方建议始终配置https://www.vydra.ai/api/v1。
• kling 图生视频失败：确认传入的是远程图片 URL 而非本地路径；插件同时回填image_url与video_url两个字段以兼容路由不一致，若仍失败可观察响应中的error.message/error.detail字段。
• 视频长时间无结果：视频任务默认 120 秒超时，且受MAX_POLL_ATTEMPTS（120 次 × 2.5 秒 ≈ 5 分钟）轮询上限约束，超时会抛出带 Job id 的明确错误信息。

延伸阅读

• Provider 目录：浏览 OpenClaw 全部可用 Provider
• 图片生成工具：共享图片工具参数、Provider 选择与故障转移行为
• 视频生成工具：共享视频工具参数、Provider 选择与故障转移行为
• 配置参考：Agent 默认值与模型配置

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