OpenClaw 中文文档
本页内容

本页内容

查看 Markdown以纯文本查看本页在 ChatGPT 中打开针对本页提问在 Claude 中打开针对本页提问

构建插件

提供商媒体和搜索

提供者插件可以与文本推理一起注册嵌入、生成和 Web 功能。在现有 api.registerProvider(...) 调用旁边的 register(api) 中注册每一个。 构建提供商插件指南的一部分。

捆绑的运行时适配器可以从私有 openclaw/plugin-sdk/concurrency-runtime 子路径使用 createDeferred 创建延迟承诺。它返回 promise、resolve 和 reject，而不加载日志记录或提供程序身份验证；适配器保留取消和终端结算的责任。

语音提供者可以使用轻量级 openclaw/plugin-sdk/speech-provider 子路径中的 createSpeechDirectiveParser。将每个覆盖字段映射到其策略密钥和接受的令牌别名；可选字段回调保留供应商验证和警告文本。共享解析器处理别名分派和策略门控并返回覆盖补丁。主机将这些补丁合并到提供商的累积覆盖中；仅当合并嵌套值（例如语音设置）时，回调才使用 currentOverrides。

媒体和搜索功能

嵌入

typescript
// 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-兼容的端点可以使用createRemoteEmbeddingProvider从openclaw/plugin-sdk/memory-core-host-engine-embeddings。其可选的buildRequestFields(kind)回调返回额外的JSON字段为"query" or "document"请求，例如dimensions or input_type。共享工厂始终供应客户的model和原来的input这些字段后面的数组，保留响应计数验证。

resolveRemoteEmbeddingClient 返回的客户端在每个 HTTP 请求之前通过 auth-profile 所有者解析 OAuth 授权。 API 密钥和显式授权标头保持静态。也通过批处理助手传递客户端的可选 resolveRequestHeaders 回调：它接收 { forceRefresh, signal } 并返回请求标头。 withRemoteHttpResponse 在受保护的调度之前应用这些标头，并提供实际标头作为第二个 onResponse 参数以进行错误编辑。如果该处理程序针对 401 token_expired 引发提供程序 HTTP 错误，则帮助程序将释放响应，使用 forceRefresh: true 解析标头一次，然后仅重试该请求。上传必须使用可重放的正文，例如批处理助手的 FormData。

嵌入适配器可以使用 openclaw/plugin-sdk/memory-core-host-engine-embeddings 中的 resolveEmbeddingProviderSsrFPolicy 来应用共享模型提供程序网络策略。传递嵌入提供者ID、API、有效基URL以及配置的request.allowPrivateNetwork值；将返回的策略重新用于嵌入请求以及批量上传、状态和下载请求。

如果端点记录了输入数组限制，请在创建的提供程序实例上设置可选的 maxInputsPerRequest 字段。对所选端点和模型使用正安全整数；未知时省略。在发送内联嵌入请求之前，内存将其限制在该数量，以及现有的字节预算。当端点报告支持的限制错误时，未声明或过时的限制仍使用反应式拆分。无效声明将被忽略。提供者批处理作业有自己的限制。

本机 OpenAI 适配器声明 2048 输入 。服务embedding-3的插件可以声明64；请勿将该限制应用于没有文档的其他模型。自定义 OpenAI- 兼容端点未声明。使用 createRemoteEmbeddingProvider 的捆绑适配器可以将相同的字段传递给该工厂。此可选字段保留现有插件合约、索引内容和嵌入缓存标识。

embed 和 embedBatch 接受可选的 onUsage 看涨期权。当响应没有有效计数时，报告使用情况的提供程序会在解析之前使用 { promptTokens, totalTokens } 或 undefined 对每个成功的上游请求调用一次。调用者可以总结这些报告，并将任何不可用的响应视为不完整的使用。共享远程工厂报告OpenAI-style使用情况；矢量返回值和现有插件保持不变。

接受模型别名的提供者可以公开normalizeModel(options): string。内存使用此同步挂钩来进行创建选项和冷索引身份检查。保持仅配置：不验证或访问网络。重复标准化使已经标准化的值保持不变，并在create，它可能接收一个已经标准化的模型或称为外部存储器。仅当模型在发现之前仍未知时才返回空字符串；不要将无效的显式模型转变为省略的选择。对于精确的预初始化身份，resolveIndexIdentity(options)另外提供所需的cacheKeyData以及任何等效的持久别名。

图像和视频生成

图像和视频能力使用感知模式的结构。图像提供方声明必需的 generate 和 edit 能力块；视频提供方声明 generate、imageToVideo 和 videoToVideo。类似 maxInputImages／maxInputVideos／maxDurationSeconds 的扁平聚合字段不足以清晰地公开变换模式支持或禁用的模式。音乐生成遵循相同的 generate／edit 模式。

捆绑提供程序可以使用私有 openclaw/plugin-sdk/video-generation 子路径中的 normalizeVideoGenerationDuration({ durationSeconds }) 来舍入可选持续时间，并在舍入后拒绝 1–9007199254740991 秒之外的值。遗漏返回undefined；提供商默认值仍归提供商所有。 selectSupportedVideoDuration 从非空列表中选择最接近的值，优先选择较长的平局持续时间。在提供者中保留提供者特定的界限。

typescript
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 共享有界轮询循环，同时插件提供其请求、completion/failure 检查和等待功能。 pollProviderOperationJson 添加了标准 HTTP JSON 传输。将供应商身份验证和截止日期范围保留在提供商适配器中。

当自定义正文读取器耗尽相同的截止日期时，重复使用 createProviderOperationTimeoutError(deadline)。它以共享错误格式保留操作标签和可选超时。

来自 openclaw/plugin-sdk/media-generation-runtime 的 readGeneratedVideoAsset 读取字节上限下的响应，并导出资产的 MIME 类型和文件名。设置 validateBinaryResponse 以拒绝非视频响应。可选的 overflowUrl 仅在主体超过该上限时提供交付；格式错误的媒体和传输错误仍然失败。调用者负责响应清理。 downloadGeneratedVideoAsset 还拥有获取、截止日期和清理功能。

本页有帮助吗？