媒体和搜索

提供商插件可随文本推理一起注册的嵌入、生成和 Web 功能。在 register(api) 内注册每一项，并将其放在现有 api.registerProvider(...) 调用旁边。属于构建提供商插件指南的一部分。

内置运行时适配器可以使用私有 openclaw/plugin-sdk/concurrency-runtime 子路径中的 createDeferred 创建延迟 Promise。它返回 promise、resolve 和 reject，而不会加载日志或提供商身份验证；适配器仍负责取消和终态结算。

媒体与搜索功能¶

嵌入图像和视频生成

// fetchAcmeEmbedding is your plugin's own vendor API call, not an SDK export.
api.registerEmbeddingProvider({
  id: "acme-ai",
  defaultModel: "acme-embed",
  transport: "remote",
  authProviderId: "acme-ai",
  create: async ({ model }) => ({
    provider: {
      id: "acme-ai",
      model,
      dimensions: 1536,
      embed: async (input) => {
        const text = typeof input === "string" ? input : input.text;
        return fetchAcmeEmbedding(text);
      },
      embedBatch: async (inputs) =>
        Promise.all(
          inputs.map((input) =>
            fetchAcmeEmbedding(typeof input === "string" ? input : input.text),
          ),
        ),
    },
  }),
});

在 contracts.embeddingProviders 中声明相同的 id。这是用于可复用向量生成的通用嵌入契约，包括记忆搜索。已弃用的记忆专用注册器和清单契约不再被接受。

兼容 OpenAI 的端点可以使用 openclaw/plugin-sdk/memory-core-host-engine-embeddings 中的 createRemoteEmbeddingProvider。其可选的 buildRequestFields(kind) 回调会为 "query" 或 "document" 请求返回额外的 JSON 字段，例如 dimensions 或 input_type。共享工厂始终会在这些字段之后提供客户端的 model 和原始 input 数组，以保留响应数量验证。

接受模型别名的提供商可以暴露 normalizeModel(options): string。记忆会使用该同步钩子来处理创建选项和冷索引身份检查。请保持其仅用于配置：不要进行身份验证或访问网络。使规范化具有幂等性，并在 create 中复用，因为 create 可能接收到已规范化的模型，或在记忆之外被调用。仅当模型在发现之前仍未知时返回空字符串；不要将无效的显式模型转换为省略的选择。对于精确的初始化前身份，resolveIndexIdentity(options) 还会额外提供所需的 cacheKeyData 以及任何等效的已持久化别名。

图像和视频功能使用模式感知的结构。图像提供商声明必需的 generate 和 edit 功能块；视频提供商声明 generate、imageToVideo 和 videoToVideo。像 maxInputImages / maxInputVideos / maxDurationSeconds 这样的扁平聚合字段不足以清晰地声明转换模式支持或已禁用的模式。音乐生成遵循相同的 generate / edit 模式。

内置提供商可以使用私有 openclaw/plugin-sdk/video-generation 子路径中的 selectSupportedVideoDuration，从非空列表中选择最接近的值，在平局时优先选择较长的时长。请将输入验证、舍入、边界和默认时长保留在提供商中。

api.registerImageGenerationProvider({
  id: "acme-ai",
  label: "Acme Images",
  capabilities: {
    generate: { maxCount: 4, supportsSize: true },
    edit: { enabled: false },
  },
  generateImage: async (req) => ({
    images: [
      {
        buffer: await generateAcmeImageBytes(req),
        mimeType: "image/png",
        fileName: "acme-image.png",
      },
    ],
  }),
});

api.registerVideoGenerationProvider({
  id: "acme-ai",
  label: "Acme Video",
  defaultTimeoutMs: 600_000,
  models: ["acme-video", "acme-image-video"],
  capabilities: {
    generate: { maxVideos: 1, maxDurationSeconds: 10, supportsResolution: true },
    imageToVideo: {
      enabled: true,
      maxVideos: 1,
      maxInputImages: 1,
      maxInputImagesByModel: { "acme/reference-to-video": 9 },
      maxDurationSeconds: 5,
    },
    videoToVideo: { enabled: false },
  },
  catalogByModel: {
    "acme-image-video": {
      modes: ["imageToVideo"],
      capabilities: {
        imageToVideo: {
          enabled: true,
          maxVideos: 1,
          maxInputImages: 1,
          resolutions: ["480P", "720P", "1080P"],
          supportsResolution: true,
        },
        videoToVideo: { enabled: false },
      },
    },
  },
  generateVideo: async (req) => ({
    videos: [
      {
        url: await generateAcmeVideoUrl(req),
        mimeType: "video/mp4",
      },
    ],
  }),
});

示例辅助函数代替提供商调用：图像辅助函数返回非空编码字节，而视频辅助函数返回托管媒体 URL。视频提供商也可以返回非空编码字节，或者当 URL 是交付回退时同时返回两者。空结果数组和空缓冲区属于候选失败，但具有可用 URL 的视频资产会忽略空缓冲区并继续使用 URL。

两种提供商类型都要求提供 capabilities；edit 和视频转换块（imageToVideo、videoToVideo）始终需要显式的 enabled 标志。

当某个已列出模型的静态模式或功能与提供商默认值不同时，请使用 catalogByModel。此元数据可在不调用提供商代码的情况下保持 video_generate action=list 和模型目录的准确性。请求时的功能查找和执行仍应放在 resolveModelCapabilities 和 generateVideo 中；尽可能在两条路径中复用相同的功能常量。

以下私有本地辅助函数仅支持捆绑发布和单独发布的官方插件。

对于异步提供方任务，`openclaw/plugin-sdk/provider-http` 中的
`pollProviderOperation` 共享有界轮询循环，而插件提供其请求、完成/失败检查和等待函数。
`pollProviderOperationJson` 添加标准 HTTP JSON 传输。
将供应商身份验证和截止时间范围保留在提供方适配器中。

当自定义正文读取器耗尽同一截止时间时，复用
`createProviderOperationTimeoutError(deadline)`。它会在共享错误格式中保留操作标签和可选超时。

`openclaw/plugin-sdk/media-generation-runtime` 中的
`readGeneratedVideoAsset` 在字节上限下读取响应，并推导资产的 MIME 类型和文件名。
设置 `validateBinaryResponse` 以拒绝非视频响应。可选的
`overflowUrl` 仅在正文超过该上限时提供交付；格式错误的媒体和传输错误仍会失败。调用方负责响应清理。
`downloadGeneratedVideoAsset` 同样负责获取、截止时间和清理。

网页抓取与搜索

api.registerWebFetchProvider({
  id: "acme-ai-fetch",
  label: "Acme Fetch",
  hint: "Fetch pages through Acme's rendering backend.",
  envVars: ["ACME_FETCH_API_KEY"],
  placeholder: "acme-...",
  signupUrl: "https://acme.example.com/fetch",
  credentialPath: "plugins.entries.acme.config.webFetch.apiKey",
  getCredentialValue: (fetchConfig) => fetchConfig?.acme?.apiKey,
  setCredentialValue: (fetchConfigTarget, value) => {
    const acme = (fetchConfigTarget.acme ??= {});
    acme.apiKey = value;
  },
  createTool: () => ({
    description: "Fetch a page through Acme Fetch.",
    parameters: {},
    execute: async (args) => ({ content: [] }),
  }),
});

api.registerWebSearchProvider({
  id: "acme-ai-search",
  label: "Acme Search",
  hint: "Search the web through Acme's search backend.",
  envVars: ["ACME_SEARCH_API_KEY"],
  placeholder: "acme-...",
  signupUrl: "https://acme.example.com/search",
  credentialPath: "plugins.entries.acme.config.webSearch.apiKey",
  getCredentialValue: (searchConfig) => searchConfig?.acme?.apiKey,
  setCredentialValue: (searchConfigTarget, value) => {
    const acme = (searchConfigTarget.acme ??= {});
    acme.apiKey = value;
  },
  createTool: () => ({
    description: "Search the web through Acme Search.",
    parameters: {},
    execute: async (args) => ({ content: [] }),
  }),
});

两种提供方类型共享相同的凭据接线结构： hint、envVars、placeholder、signupUrl、credentialPath、 getCredentialValue、setCredentialValue 和 createTool 均为必填。

搜索提供方可以声明 configPath，作为相对于其自身插件配置的搜索设置页路径。它默认为 ["webSearch"]；当提供方没有内联设置时使用 null。共享同一插件的提供方可以公开不同的设置，而无需显示仅适用于同级提供方的字段。凭据仍由 credentialPath 描述，并使用现有的掩码凭据编辑器。

使用 openclaw/plugin-sdk/provider-web-search 的搜索提供方应在每次执行时解析一次 resolveSearchCacheTtlMs(searchConfig)，并将该值同时传递给 readCachedSearchPayload(cacheKey, ttlMs) 和 writeCachedSearchPayload(cacheKey, payload, ttlMs)。零 TTL 会绕过读取和写入；正 TTL 会限制条目年龄，而不会延长其原始过期时间。读取会返回标记为 cached: true 的负载，或在未命中时返回 undefined。读取器的 ttlMs 参数是可选的：现有的一参数调用将继续仅使用存储的过期时间。

两种工具定义都接受 execute(args, context?)，其中可选的 context 携带 signal?: AbortSignal。将该信号转发到网络请求，并在异步工作后检查取消。现有的一参数实现仍然有效；OpenClaw 会在取消后拒绝迟到的抓取结果，然后再将其发布到其抓取缓存。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw