参考插件内部
api.runtime 向插件代码公开的内容，以及匹配提供者注册的所有权规则。 插件架构内部指南的一部分。
运行时辅助工具
插件可以通过 api.runtime 访问选定的核心辅助工具。对于 TTS：
tsconst clip = await api.runtime.tts.textToSpeech({ text: "Hello from OpenClaw", cfg: api.config,}); const result = await api.runtime.tts.textToSpeechTelephony({ text: "Hello from OpenClaw", cfg: api.config,}); const voices = await api.runtime.tts.listVoices({ provider: "elevenlabs", cfg: api.config,});
注意：
textToSpeech 返回 file/voice-note 表面的正常核心 TTS 输出有效负载。- 使用核心
tts 配置和提供方选择。
- 返回PCM音频缓冲区+采样率。对于提供商来说，插件必须为 resample/encode。
listVoices 对每个提供方来说都是可选的。将其用于供应商自有的语音选择器或设置流程。- 核心会向提供方的
listVoices 钩子传递解析后的请求截止时间；提供方特定的超时设置可能会覆盖该时间。
- 语音列表可以包含更丰富的元数据，例如区域设置、性别和个性标签，以便支持提供方感知的选择器。
- Telephony 需要一个实现
synthesizeTelephony 的提供者；如果没有它，核心会跳过提供程序并报告 unsupported_for_telephony。实现它的捆绑提供程序：azure-speech、elevenlabs、fish-audio-speech、google、gradium、inworld、openai、tts-local-cli 和 xai。 microsoft 没有。
插件也可以通过 api.registerSpeechProvider(...) 注册语音提供方。
tsapi.registerSpeechProvider({ id: "acme-speech", label: "Acme Speech", isConfigured: ({ config }) => Boolean(config.messages?.tts), synthesize: async (req) => { return { audioBuffer: Buffer.from([]), outputFormat: "mp3", fileExtension: ".mp3", voiceCompatible: false, }; },});
注意：
- 将 TTS 策略、回退和回复投递保留在核心中。
- 对于供应商自有的合成行为，请使用语音提供方。
- 旧版 Microsoft
edge 输入会被规范化为 microsoft 提供方 id。
- 推荐的所有权模型是公司导向的：一个供应商插件可以拥有文本、语音、图像，以及 OpenClaw 增加这些能力合同时的未来媒体提供方。
对于 image/audio/video 的理解，插件注册一种类型化媒体理解提供程序，而不是通用的 key/value 包：
tsapi.registerMediaUnderstandingProvider({ id: "google", capabilities: ["image", "audio", "video"], describeImage: async (req) => ({ text: "..." }), transcribeAudio: async (req) => ({ text: "..." }), describeVideo: async (req) => ({ text: "..." }),});
注意：
- 将编排、回退、配置和通道接线保留在核心中。
- 将供应商行为保留在提供方插件中。
- 增量扩展应保持类型化：新增可选方法、新增可选结果字段、新增可选能力。
- 视频生成已经遵循相同模式：
- 核心负责能力合约和运行时辅助工具
- 供应商插件注册
api.registerVideoGenerationProvider(...)
- feature/channel 插件消耗
api.runtime.videoGeneration.*
对于媒体理解运行时辅助工具，插件可以调用：
tsconst image = await api.runtime.mediaUnderstanding.describeImageFile({ filePath: "/tmp/inbound-photo.jpg", cfg: api.config, agentDir: "/tmp/agent",}); const video = await api.runtime.mediaUnderstanding.describeVideoFile({ filePath: "/tmp/inbound-video.mp4", cfg: api.config,}); const extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({ provider: "codex", model: "gpt-6-astra", input: [ { type: "image", buffer: receiptImageBuffer, fileName: "receipt.png", mime: "image/png", }, { type: "text", text: "Use the printed fields as the source of truth." }, ], instructions: "Return entities and searchable tags.", schemaName: "example.evidence", jsonSchema: { type: "object", properties: { entities: { type: "array", items: { type: "string" } }, tags: { type: "array", items: { type: "string" } }, }, }, cfg: api.config,});
对于音频转写，插件可以使用媒体理解运行时，或者旧的 STT 别名：
tsconst { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, mime: "audio/ogg",});
注意：
api.runtime.mediaUnderstanding.* 是 image/audio/video 理解的首选共享表面。extractStructuredWithModel(...) 是面向插件的接口，用于有界提供商拥有的图像优先提取。包括至少一张图像输入；文本输入是补充上下文。产品插件拥有自己的路由和架构，而 OpenClaw 拥有 provider/runtime 边界。- 使用核心媒体理解音频配置（
tools.media.audio）和提供方回退顺序。
- 当未生成转录输出（例如 skipped/unsupported 输入）时，返回
{ text: undefined }。
插件还可以通过 api.runtime.subagent 启动后台子代理运行：
tsconst result = await api.runtime.subagent.run({ sessionKey: "agent:main:subagent:search-helper", message: "Expand this query into focused follow-up searches.", toolsAlsoAllow: ["my_plugin_progress"], provider: "openai", model: "gpt-4.1-mini", deliver: false,});
注意：
provider 和 model 是每次运行可选的覆盖项，不是持久的会话更改。toolsAlsoAllow 接受由调用插件注册的、精确且唯一拥有的工具名称。核心和含糊不清的名称会被拒绝。它会在正常配置文件的基础上进行叠加，但操作员的允许列表和拒绝列表仍然具有最终权威。- OpenClaw 仅对受信任的调用方认可这些覆盖字段。
- 对于插件拥有的回退运行，操作员必须显式启用
plugins.entries.<id>.subagent.allowModelOverride: true。
- 使用
plugins.entries.<id>.subagent.allowedModels 将受信任插件限制为特定规范化 provider/model 目标，或使用 "*" 显式允许任何目标。
- 不受信任的插件子代理运行仍然可以工作，但覆盖请求会被拒绝，而不是静默回退。
- 由插件创建的子代理会话会标记创建它的插件 id。兼容的
api.runtime.subagent.deleteSession(...) 只能删除这些所属会话；任意会话删除仍然需要具有管理员范围的 Gateway 请求。
对于网络搜索，插件可以消费共享运行时辅助工具，而不是直接进入代理工具接线：
tsconst providers = api.runtime.webSearch.listProviders({ config: api.config,}); const result = await api.runtime.webSearch.search({ config: api.config, args: { query: "OpenClaw plugin runtime helpers", count: 5, },});
插件也可以通过 api.registerWebSearchProvider(...) 注册网络搜索提供方。
注意：
- 将提供方选择、凭据解析和共享请求语义保留在核心中。
- 对于供应商特定的搜索传输，请使用网络搜索提供方。
api.runtime.webSearch.* 是 feature/channel 插件的首选共享表面，这些插件需要搜索行为而不依赖于代理工具包装器。
api.runtime.imageGeneration
tsconst result = await api.runtime.imageGeneration.generate({ config: api.config, args: { prompt: "A friendly lobster mascot", size: "1024x1024" },}); const providers = api.runtime.imageGeneration.listProviders({ config: api.config,});
generate(...)：使用已配置的图像生成提供方链生成图像。listProviders(...)：列出可用的图像生成提供方及其能力。
