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能力模型标识说明图片生成vydra/grok-imagine仅支持文生图单次请求最多一张视频生成vydra/veo3文生视频拒绝图片参考输入视频生成vydra/kling图生视频必须提供恰好一张远程图片 URL语音合成elevenlabs/tts默认音色 Rachel21m00Tcm4TlvDq8ikWAM返回 MP3插件同时注册进三个能力契约见 extensions/vydra/index.tsapi.registerSpeechProvider、api.registerImageGenerationProvider、api.registerVideoGenerationProvider对应 openclaw.plugin.json 中声明的speechProviders、imageGenerationProviders、videoGenerationProviders三个契约。Provider 关键属性属性值Provider idvydra插件包openclaw/vydra-provider鉴权环境变量VYDRA_API_KEY交互式引导标志--auth-choice vydra-api-key直接 CLI 标志--vydra-api-key key契约imageGenerationProviders、videoGenerationProviders、speechProvidersBase URLhttps://www.vydra.ai/api/v1务必使用带www的主机关于 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.tshttps://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_KEYvydra_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_TEST1 \ OPENCLAW_LIVE_VYDRA_VIDEO1 \ pnpm test:live -- extensions/vydra/vydra.live.test.ts测试覆盖vydra/veo3文生视频vydra/kling使用远程图片 URL 的图生视频。需要时可覆盖远程图片 fixtureexport OPENCLAW_LIVE_VYDRA_KLING_IMAGE_URLhttps://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音色 id21m00Tcm4TlvDq8ikWAM即 Rachel插件只暴露这一个经过验证的默认音色VYDRA_SPEECH_VOICES数组中仅有 Rachel见 speech-provider.ts合成结果返回 MP3 音频文件。synthesize的请求体为{ text, voice_id }POST 到${baseUrl}/models/elevenlabs/tts。语音配置支持额外的环境变量覆盖speech-provider.ts环境变量作用VYDRA_BASE_URL覆盖 Base URLVYDRA_TTS_MODEL覆盖 TTS 模型VYDRA_TTS_VOICE_ID覆盖音色 id优先级为配置文件tts.providers.vydra.* 上述环境变量 代码内置默认值。此外 API Key 也支持双来源配置中的apiKey或process.env.VYDRA_API_KEY任一存在即视为已配置。底层机制Job 轮询与媒体下载三类能力共享同一套底层运行时核心实现在 extensions/vydra/shared.ts 的runVydraGeneration图片/视频与synthesize语音中可以归纳为四个阶段请求上下文解析resolveVydraRequestContext通过resolveApiKeyForProvider读取VYDRA_API_KEY缺失时抛出Vydra API key missing并组装Authorization: Bearer key请求头同时从models.providers.vydra.baseUrl读取用户自定义 Base URL 并做规范化。提交 JobPOST${baseUrl}/models/${model}携带能力对应的请求体。轮询结果若响应中状态不是completed且不含结果 URL则从jobId/id字段解析 Job 标识以 2.5 秒间隔POLL_INTERVAL_MS、最多 120 次MAX_POLL_ATTEMPTS轮询${baseUrl}/jobs/${jobId}status为failed/error/cancelled时立即以错误信息终止shared.ts。下载产物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 一律不带凭据resolveVydraAssetRequestHeadersshared.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.aiapex 主机。虽然插件会自动规范化但跨主机重定向的丢头问题在部分客户端上仍可能残留官方建议始终配置https://www.vydra.ai/api/v1。kling 图生视频失败确认传入的是远程图片 URL 而非本地路径插件同时回填image_url与video_url两个字段以兼容路由不一致若仍失败可观察响应中的error.message/error.detail字段。视频长时间无结果视频任务默认 120 秒超时且受MAX_POLL_ATTEMPTS120 次 × 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OpenClaw Vydra 插件接入指南：图片、视频与语音生成一站式配置
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能力模型标识说明图片生成vydra/grok-imagine仅支持文生图单次请求最多一张视频生成vydra/veo3文生视频拒绝图片参考输入视频生成vydra/kling图生视频必须提供恰好一张远程图片 URL语音合成elevenlabs/tts默认音色 Rachel21m00Tcm4TlvDq8ikWAM返回 MP3插件同时注册进三个能力契约见 extensions/vydra/index.tsapi.registerSpeechProvider、api.registerImageGenerationProvider、api.registerVideoGenerationProvider对应 openclaw.plugin.json 中声明的speechProviders、imageGenerationProviders、videoGenerationProviders三个契约。Provider 关键属性属性值Provider idvydra插件包openclaw/vydra-provider鉴权环境变量VYDRA_API_KEY交互式引导标志--auth-choice vydra-api-key直接 CLI 标志--vydra-api-key key契约imageGenerationProviders、videoGenerationProviders、speechProvidersBase URLhttps://www.vydra.ai/api/v1务必使用带www的主机关于 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.tshttps://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_KEYvydra_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_TEST1 \ OPENCLAW_LIVE_VYDRA_VIDEO1 \ pnpm test:live -- extensions/vydra/vydra.live.test.ts测试覆盖vydra/veo3文生视频vydra/kling使用远程图片 URL 的图生视频。需要时可覆盖远程图片 fixtureexport OPENCLAW_LIVE_VYDRA_KLING_IMAGE_URLhttps://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音色 id21m00Tcm4TlvDq8ikWAM即 Rachel插件只暴露这一个经过验证的默认音色VYDRA_SPEECH_VOICES数组中仅有 Rachel见 speech-provider.ts合成结果返回 MP3 音频文件。synthesize的请求体为{ text, voice_id }POST 到${baseUrl}/models/elevenlabs/tts。语音配置支持额外的环境变量覆盖speech-provider.ts环境变量作用VYDRA_BASE_URL覆盖 Base URLVYDRA_TTS_MODEL覆盖 TTS 模型VYDRA_TTS_VOICE_ID覆盖音色 id优先级为配置文件tts.providers.vydra.* 上述环境变量 代码内置默认值。此外 API Key 也支持双来源配置中的apiKey或process.env.VYDRA_API_KEY任一存在即视为已配置。底层机制Job 轮询与媒体下载三类能力共享同一套底层运行时核心实现在 extensions/vydra/shared.ts 的runVydraGeneration图片/视频与synthesize语音中可以归纳为四个阶段请求上下文解析resolveVydraRequestContext通过resolveApiKeyForProvider读取VYDRA_API_KEY缺失时抛出Vydra API key missing并组装Authorization: Bearer key请求头同时从models.providers.vydra.baseUrl读取用户自定义 Base URL 并做规范化。提交 JobPOST${baseUrl}/models/${model}携带能力对应的请求体。轮询结果若响应中状态不是completed且不含结果 URL则从jobId/id字段解析 Job 标识以 2.5 秒间隔POLL_INTERVAL_MS、最多 120 次MAX_POLL_ATTEMPTS轮询${baseUrl}/jobs/${jobId}status为failed/error/cancelled时立即以错误信息终止shared.ts。下载产物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 一律不带凭据resolveVydraAssetRequestHeadersshared.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.aiapex 主机。虽然插件会自动规范化但跨主机重定向的丢头问题在部分客户端上仍可能残留官方建议始终配置https://www.vydra.ai/api/v1。kling 图生视频失败确认传入的是远程图片 URL 而非本地路径插件同时回填image_url与video_url两个字段以兼容路由不一致若仍失败可观察响应中的error.message/error.detail字段。视频长时间无结果视频任务默认 120 秒超时且受MAX_POLL_ATTEMPTS120 次 × 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
