OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构,使用聚焦且有文档说明的导入。如果你的插件是在新架构之前构建的,本指南可帮助你迁移。Documentation Index
Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
有哪些变化
旧插件系统提供了两个完全开放的表面,让插件可以从单一入口点导入它们需要的任何内容:openclaw/plugin-sdk/compat- 一个单一导入,会重新导出数十个辅助工具。它的引入是为了在新插件架构构建期间,让较旧的基于钩子的插件继续工作。openclaw/plugin-sdk/infra-runtime- 一个宽泛的运行时辅助工具桶,混合了系统事件、Heartbeat 状态、投递队列、fetch/proxy 辅助工具、文件辅助工具、审批类型和无关实用工具。openclaw/plugin-sdk/config-runtime- 一个宽泛的配置兼容桶,在迁移窗口期间仍携带已弃用的直接加载/写入辅助工具。openclaw/extension-api- 一个桥接层,让插件可以直接访问主机侧辅助工具,例如嵌入式 Agent 运行器。api.registerEmbeddedExtensionFactory(...)- 一个已移除的仅限 Pi 的内置插件钩子,可观察嵌入式运行器事件,例如tool_result。
为什么做出此变更
旧方法会导致问题:- 启动缓慢 - 导入一个辅助工具会加载数十个无关模块
- 循环依赖 - 宽泛的重新导出很容易产生导入循环
- API 表面不清晰 - 无法判断哪些导出是稳定的,哪些是内部的
openclaw/plugin-sdk/\<subpath\>)都是一个小型、自包含的模块,具有清晰用途和已记录的契约。
用于内置渠道的旧版提供商便捷衔接点也已移除。带渠道品牌的辅助衔接点是私有单仓库快捷方式,不是稳定的插件契约。请改用窄范围的通用 SDK 子路径。在内置插件工作区内,将提供商所有的辅助工具保留在该插件自己的 api.ts 或 runtime-api.ts 中。
当前内置提供商示例:
- Anthropic 将 Claude 专用流辅助工具保留在它自己的
api.ts/contract-api.ts衔接点中 - OpenAI 将提供商构建器、默认模型辅助工具和实时提供商构建器保留在它自己的
api.ts中 - OpenRouter 将提供商构建器和新手引导/配置辅助工具保留在它自己的
api.ts中
Talk 和实时语音迁移计划
实时语音、电话、会议和浏览器 Talk 代码正在从表面本地的轮次记账迁移到由openclaw/plugin-sdk/realtime-voice 导出的共享 Talk 会话控制器。新的控制器负责通用 Talk 事件信封、活动轮次状态、采集状态、输出音频状态、最近事件历史和过期轮次拒绝。提供商插件应继续负责厂商专用实时会话;表面插件应继续负责采集、播放、电话和会议差异。
这次 Talk 迁移有意采用破坏性清理:
- 将共享控制器/运行时原语保留在
plugin-sdk/realtime-voice中。 - 将内置表面迁移到共享控制器:浏览器中继、托管房间交接、语音通话实时、语音通话流式 STT、Google Meet 实时和原生按键通话。
- 用最终的
talk.session.*和talk.client.*API 替换旧 Talk RPC 系列。 - 在 Gateway 网关
hello-ok.features.events中公开一个实时 Talk 事件渠道:talk.event。 - 删除旧的实时 HTTP 端点和任何请求时指令覆盖路径。
createTalkEventSequencer(...),除非它正在实现低层适配器或测试夹具。优先使用共享控制器,这样没有轮次 id 就无法发出轮次范围事件,过期的 turnEnd / turnCancel 调用无法清除较新的活动轮次,并且输出音频生命周期事件可在电话、会议、浏览器中继、托管房间交接和原生 Talk 客户端之间保持一致。
目标公共 API 形态如下:
talk.client.create,因为浏览器拥有提供商协商和媒体传输,而 Gateway 网关拥有凭证、指令和工具策略。talk.session.* 是由 Gateway 网关管理的通用表面,适用于 gateway-relay 实时、gateway-relay 转录和 managed-room 原生 STT/TTS 会话。
将实时选择器放在 talk.provider / talk.providers 旁边的旧版配置,应使用 openclaw doctor --fix 修复;运行时 Talk 不会将语音/TTS 提供商配置重新解释为实时提供商配置。
受支持的 talk.session.create 组合有意保持很小:
| 模式 | 传输 | 大脑 | 所有者 | 说明 |
|---|---|---|---|---|
realtime | gateway-relay | agent-consult | Gateway 网关 | 通过 Gateway 网关桥接的全双工提供商音频;工具调用通过 agent-consult 工具路由。 |
transcription | gateway-relay | none | Gateway 网关 | 仅流式 STT;调用方发送输入音频并接收转录事件。 |
stt-tts | managed-room | agent-consult | 原生/客户端房间 | 按键通话和对讲式房间,其中客户端拥有采集/播放,Gateway 网关拥有轮次状态。 |
stt-tts | managed-room | direct-tools | 原生/客户端房间 | 面向受信任第一方表面的仅管理员房间模式,可直接执行 Gateway 网关工具动作。 |
| 旧 | 新 |
|---|---|
talk.realtime.session | talk.client.create |
talk.realtime.toolCall | talk.client.toolCall |
talk.realtime.relayAudio | talk.session.appendAudio |
talk.realtime.relayCancel | talk.session.cancelOutput 或 talk.session.cancelTurn |
talk.realtime.relayToolResult | talk.session.submitToolResult |
talk.realtime.relayStop | talk.session.close |
talk.transcription.session | talk.session.create({ mode: "transcription" }) |
talk.transcription.relayAudio | talk.session.appendAudio |
talk.transcription.relayCancel | talk.session.cancelTurn |
talk.transcription.relayStop | talk.session.close |
talk.handoff.create | talk.session.create({ transport: "managed-room" }) |
talk.handoff.join | talk.session.join |
talk.handoff.revoke | talk.session.close |
| 方法 | 适用于 | 契约 |
|---|---|---|
talk.session.appendAudio | realtime/gateway-relay、transcription/gateway-relay | 向由同一 Gateway 网关连接拥有的提供商会话追加一个 base64 PCM 音频块。 |
talk.session.startTurn | stt-tts/managed-room | 启动一个托管房间用户轮次。 |
talk.session.endTurn | stt-tts/managed-room | 在过期轮次验证后结束活动轮次。 |
talk.session.cancelTurn | 所有 Gateway 网关所有的会话 | 取消某个轮次的活动采集/提供商/Agent/TTS 工作。 |
talk.session.cancelOutput | realtime/gateway-relay | 停止助手音频输出,但不一定结束用户轮次。 |
talk.session.submitToolResult | realtime/gateway-relay | 完成由中继发出的提供商工具调用;传入 options.willContinue 表示中间输出,或传入 options.suppressResponse 以在不生成另一条助手响应的情况下满足该调用。 |
talk.session.close | 所有统一会话 | 停止中继会话或撤销托管房间状态,然后忘记统一会话 id。 |
兼容性策略
对于外部插件,兼容性工作按此顺序进行:- 添加新契约
- 保持旧行为通过兼容性适配器连接
- 发出诊断或警告,指出旧路径和替代方案
- 在测试中覆盖两条路径
- 记录弃用和迁移路径
- 仅在已公告的迁移窗口后移除,通常在主版本发布中移除
pnpm plugins:boundary-report 审计当前迁移队列。使用 pnpm plugins:boundary-report:summary 获取
紧凑计数,使用 --owner <id> 针对单个插件或兼容性所有者,并在 CI 门禁需要因到期的
兼容性记录、跨所有者保留 SDK 导入或未使用的保留 SDK
子路径而失败时使用 pnpm plugins:boundary-report:ci。报告会按移除日期分组已弃用的
兼容性记录,统计本地代码/文档引用,暴露跨所有者保留 SDK 导入,并总结私有
memory-host SDK 桥接,使兼容性清理保持显式,而不是依赖临时搜索。保留 SDK 子路径必须有已跟踪的所有者用法;
未使用的保留辅助导出应从公共 SDK 中移除。
如果某个清单字段仍被接受,插件作者可以继续使用它,直到
文档和诊断另行说明。新代码应优先使用已记录的
替代项,但现有插件不应在普通次版本
发布期间中断。
如何迁移
Migrate runtime config load/write helpers
api.runtime.config.loadConfig() 和
api.runtime.config.writeConfigFile(...)。优先使用
已经传入活跃调用路径的配置。需要当前进程快照的长生命周期处理器可以使用 api.runtime.config.current()。长生命周期
agent 工具应在 execute 内使用工具上下文的 ctx.getRuntimeConfig(),这样在配置写入前创建的工具仍能看到刷新的
运行时配置。配置写入必须通过事务式辅助工具,并选择一个
写入后策略:afterWrite: { mode: "restart", reason: "..." };
仅当调用方负责后续处理,并且有意抑制重载规划器时,才使用
afterWrite: { mode: "none", reason: "..." }。
变更结果包含一个带类型的 followUp 摘要,用于测试和日志;
Gateway 网关仍负责应用或安排重启。
loadConfig 和 writeConfigFile 在迁移窗口期间仍作为已弃用的兼容性
辅助工具保留给外部插件,并使用
runtime-config-load-write 兼容性代码警告一次。内置插件和仓库
运行时代码受
pnpm check:deprecated-api-usage 和
pnpm check:no-runtime-action-load-config 中的扫描器护栏保护:新的生产插件用法
会直接失败,直接配置写入会失败,Gateway 网关服务器方法必须使用
请求运行时快照,运行时渠道发送/action/client 辅助工具
必须从其边界接收配置,并且长生命周期运行时模块
不允许任何环境式 loadConfig() 调用。新插件代码还应避免导入宽泛的
openclaw/plugin-sdk/config-runtime 兼容性桶。请使用与任务匹配的窄
SDK 子路径:| 需求 | 导入 |
|---|---|
配置类型,例如 OpenClawConfig | openclaw/plugin-sdk/config-contracts |
| 已加载配置断言和插件入口配置查找 | openclaw/plugin-sdk/plugin-config-runtime |
| 当前运行时快照读取 | openclaw/plugin-sdk/runtime-config-snapshot |
| 配置写入 | openclaw/plugin-sdk/config-mutation |
| 会话存储辅助工具 | openclaw/plugin-sdk/session-store-runtime |
| Markdown 表格配置 | openclaw/plugin-sdk/markdown-table-runtime |
| 群组策略运行时辅助工具 | openclaw/plugin-sdk/runtime-group-policy |
| 密钥输入解析 | openclaw/plugin-sdk/secret-input-runtime |
| 模型/会话覆盖 | openclaw/plugin-sdk/model-session-runtime |
Migrate Pi tool-result extensions to middleware
api.registerEmbeddedExtensionFactory(...) 工具结果处理器替换为
运行时中立的中间件。Migrate approval-native handlers to capability facts
approvalCapability.nativeRuntime 加上共享运行时上下文注册表暴露原生审批行为。关键变更:- 将
approvalCapability.handler.loadRuntime(...)替换为approvalCapability.nativeRuntime - 将审批专用认证/投递从旧版
plugin.auth/plugin.approvals接线迁移到approvalCapability ChannelPlugin.approvals已从公共渠道插件 契约中移除;将投递/native/render 字段迁移到approvalCapabilityplugin.auth仅保留用于渠道登录/登出流程;核心不再读取其中的审批认证 钩子- 通过
openclaw/plugin-sdk/channel-runtime-context注册渠道拥有的运行时对象,例如客户端、令牌或 Bolt 应用 - 不要从原生审批处理器发送插件拥有的重路由通知; 核心现在根据实际投递结果负责路由到别处的通知
- 将
channelRuntime传入createChannelManager(...)时,请提供真实的createPluginRuntime().channel表面。部分 stub 会被拒绝。
/plugins/sdk-channel-plugins 了解当前审批能力
布局。Audit Windows wrapper fallback behavior
openclaw/plugin-sdk/windows-spawn,未解析的 Windows
.cmd/.bat 包装器现在会默认失败关闭,除非你显式传入
allowShellFallback: true。allowShellFallback,而是处理抛出的错误。Replace with focused imports
| 旧导入 | 现代等价项 |
|---|---|
resolveAgentDir | api.runtime.agent.resolveAgentDir |
resolveAgentWorkspaceDir | api.runtime.agent.resolveAgentWorkspaceDir |
resolveAgentIdentity | api.runtime.agent.resolveAgentIdentity |
resolveThinkingDefault | api.runtime.agent.resolveThinkingDefault |
resolveAgentTimeoutMs | api.runtime.agent.resolveAgentTimeoutMs |
ensureAgentWorkspace | api.runtime.agent.ensureAgentWorkspace |
| 会话存储辅助工具 | api.runtime.agent.session.* |
Replace broad infra-runtime imports
openclaw/plugin-sdk/infra-runtime 仍为外部
兼容性存在,但新代码应导入它实际需要的聚焦辅助表面:| 需求 | 导入 |
|---|---|
| 系统事件队列辅助工具 | openclaw/plugin-sdk/system-event-runtime |
| Heartbeat 唤醒、事件和可见性辅助工具 | openclaw/plugin-sdk/heartbeat-runtime |
| 待处理投递队列清空 | openclaw/plugin-sdk/delivery-queue-runtime |
| 渠道活动遥测 | openclaw/plugin-sdk/channel-activity-runtime |
| 内存中去重缓存 | openclaw/plugin-sdk/dedupe-runtime |
| 安全本地文件/媒体路径辅助工具 | openclaw/plugin-sdk/file-access-runtime |
| 感知 dispatcher 的 fetch | openclaw/plugin-sdk/runtime-fetch |
| 代理和受保护 fetch 辅助工具 | openclaw/plugin-sdk/fetch-runtime |
| SSRF dispatcher 策略类型 | openclaw/plugin-sdk/ssrf-dispatcher |
| 审批请求/解决类型 | openclaw/plugin-sdk/approval-runtime |
| 审批回复 payload 和命令辅助工具 | openclaw/plugin-sdk/approval-reply-runtime |
| 错误格式化辅助工具 | openclaw/plugin-sdk/error-runtime |
| 传输就绪等待 | openclaw/plugin-sdk/transport-ready-runtime |
| 安全令牌辅助工具 | openclaw/plugin-sdk/secure-random-runtime |
| 有界异步任务并发 | openclaw/plugin-sdk/concurrency-runtime |
| 数值强制转换 | openclaw/plugin-sdk/number-runtime |
| 进程本地异步锁 | openclaw/plugin-sdk/async-lock-runtime |
| 文件锁 | openclaw/plugin-sdk/file-lock |
infra-runtime,因此仓库代码
不能回退到宽泛桶。Migrate channel route helpers
openclaw/plugin-sdk/channel-route。
较旧的 route-key 和 comparable-target 名称在迁移窗口期间仍作为兼容性
别名保留,但新插件应使用直接描述行为的 route
名称:| 旧版辅助函数 | 现代辅助函数 |
|---|---|
channelRouteIdentityKey(...) | channelRouteDedupeKey(...) |
channelRouteKey(...) | channelRouteCompactKey(...) |
ComparableChannelTarget | ChannelRouteParsedTarget |
resolveComparableTargetForChannel(...) | resolveRouteTargetForChannel(...) |
resolveComparableTargetForLoadedChannel(...) | resolveRouteTargetForLoadedChannel(...) |
comparableChannelTargetsMatch(...) | channelRouteTargetsMatchExact(...) |
comparableChannelTargetsShareRoute(...) | channelRouteTargetsShareConversation(...) |
{ channel, to, accountId, threadId }。
如果你的插件拥有自定义目标语法,请使用 resolveChannelRouteTargetWithParser(...)
将该解析器适配到相同的路由目标契约中。导入路径参考
常用导入路径表
常用导入路径表
scripts/lib/plugin-sdk-entrypoints.json;包导出会从
公共子集生成。
预留的内置插件辅助衔接面已从公共 SDK
导出映射中退役,但明确记录的兼容性门面除外,例如已弃用的
plugin-sdk/discord shim,它是为已发布的
@openclaw/discord@2026.3.13 包保留的。所有者专属辅助函数位于
所属插件包内;共享主机行为应通过通用 SDK
契约移动,例如 plugin-sdk/gateway-runtime、plugin-sdk/security-runtime
和 plugin-sdk/plugin-config-runtime。
使用与任务匹配的最窄导入。如果找不到导出,
请检查 src/plugin-sdk/ 中的源代码,或询问维护者哪个通用契约
应拥有它。
活跃弃用项
适用于插件 SDK、提供商契约、 运行时表面和清单的更窄弃用项。每一项现在仍可工作,但会在 未来的主版本中移除。每个条目下方的内容会把旧 API 映射到其 规范替代项。command-auth help builders → command-status
command-auth help builders → command-status
openclaw/plugin-sdk/command-auth):buildCommandsMessage,
buildCommandsMessagePaginated, buildHelpMessage.新(openclaw/plugin-sdk/command-status):相同签名、相同
导出,只是从更窄的子路径导入。command-auth
会将它们重新导出为兼容性桩。Mention gating helpers → resolveInboundMentionDecision
Mention gating helpers → resolveInboundMentionDecision
openclaw/plugin-sdk/channel-inbound 或
openclaw/plugin-sdk/channel-mention-gating 的
resolveInboundMentionRequirement({ facts, policy }) 和
shouldDropInboundForMention(...)。新:resolveInboundMentionDecision({ facts, policy }),返回一个
单一决策对象,而不是两个拆分调用。下游渠道插件(Slack、Discord、Matrix、MS Teams)已经切换。Channel runtime shim and channel actions helpers
Channel runtime shim and channel actions helpers
openclaw/plugin-sdk/channel-runtime 是面向旧渠道插件的兼容性 shim。
不要在新代码中导入它;请使用
openclaw/plugin-sdk/channel-runtime-context 注册运行时对象。openclaw/plugin-sdk/channel-actions 中的 channelActions* 辅助函数
与原始 “actions” 渠道导出一并弃用。改为通过语义化的
presentation 表面公开能力,渠道插件声明它们渲染什么
(卡片、按钮、选择器),而不是它们接受哪些原始操作名称。Web search provider tool() helper → createTool() on the plugin
Web search provider tool() helper → createTool() on the plugin
openclaw/plugin-sdk/provider-web-search 的 tool() 工厂。新:直接在提供商插件上实现 createTool(...)。
OpenClaw 不再需要 SDK 辅助函数来注册工具包装器。Plaintext channel envelopes → BodyForAgent
Plaintext channel envelopes → BodyForAgent
formatInboundEnvelope(...)(以及
ChannelMessageForAgent.channelEnvelope)从入站渠道消息构建扁平的纯文本提示
信封。新:BodyForAgent 加结构化用户上下文块。渠道插件将路由元数据
(线程、主题、回复目标、回应)作为类型化字段附加,而不是把它们
拼接进提示字符串。formatAgentEnvelope(...) 辅助函数仍支持用于合成的
面向助手的信封,但入站纯文本信封正在逐步退出。受影响区域:inbound_claim、message_received,以及任何对
channelEnvelope 文本做后处理的自定义渠道插件。Provider discovery types → provider catalog types
Provider discovery types → provider catalog types
| 旧别名 | 新类型 |
|---|---|
ProviderDiscoveryOrder | ProviderCatalogOrder |
ProviderDiscoveryContext | ProviderCatalogContext |
ProviderDiscoveryResult | ProviderCatalogResult |
ProviderPluginDiscovery | ProviderPluginCatalog |
ProviderCapabilities 静态包。提供商插件
应使用显式提供商钩子,例如 buildReplayPolicy、
normalizeToolSchemas 和 wrapStreamFn,而不是静态对象。Thinking policy hooks → resolveThinkingProfile
Thinking policy hooks → resolveThinkingProfile
ProviderThinkingPolicy 上的三个独立钩子):
isBinaryThinking(ctx)、supportsXHighThinking(ctx) 和
resolveDefaultThinkingLevel(ctx)。新:单个 resolveThinkingProfile(ctx),返回一个
ProviderThinkingProfile,其中包含规范 id、可选 label 和
排序后的级别列表。OpenClaw 会按配置文件排名自动降级过时的已存储值。实现一个钩子,而不是三个。旧钩子在弃用窗口期间仍会工作,
但不会与配置文件结果组合。External OAuth provider fallback → contracts.externalAuthProviders
External OAuth provider fallback → contracts.externalAuthProviders
resolveExternalOAuthProfiles(...),但不在插件清单中
声明提供商。新:在插件清单中声明 contracts.externalAuthProviders,
并且实现 resolveExternalAuthProfiles(...)。旧的 “auth
fallback” 路径会在运行时发出警告,并将被移除。Provider env-var lookup → setup.providers[].envVars
Provider env-var lookup → setup.providers[].envVars
providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }.新:把相同的环境变量查找镜像到清单上的 setup.providers[].envVars。
这会把设置/Status 环境元数据合并到一个位置,并避免仅为了回答环境变量
查找而启动插件运行时。providerAuthEnvVars 会通过兼容性适配器继续受支持,
直到弃用窗口关闭。Memory plugin registration → registerMemoryCapability
Memory plugin registration → registerMemoryCapability
api.registerMemoryPromptSection(...),
api.registerMemoryFlushPlan(...),
api.registerMemoryRuntime(...).新:在 memory-state API 上进行一次调用:
registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime }).相同槽位,单次注册调用。增量记忆辅助函数
(registerMemoryPromptSupplement、registerMemoryCorpusSupplement、
registerMemoryEmbeddingProvider)不受影响。Subagent session messages types renamed
Subagent session messages types renamed
src/plugins/runtime/types.ts 导出的两个旧类型别名:| 旧 | 新 |
|---|---|
SubagentReadSessionParams | SubagentGetSessionMessagesParams |
SubagentReadSessionResult | SubagentGetSessionMessagesResult |
readSession 已弃用,请改用
getSessionMessages。签名相同;旧方法会转调到新方法。runtime.tasks.flow → runtime.tasks.managedFlows
runtime.tasks.flow → runtime.tasks.managedFlows
runtime.tasks.flow(单数)返回实时任务流访问器。新:runtime.tasks.managedFlows 保留托管 TaskFlow 变更
运行时,供需要从流程创建、更新、取消或运行子任务的插件使用。
当插件只需要基于 DTO 的读取时,请使用 runtime.tasks.flows。Embedded extension factories → agent tool-result middleware
Embedded extension factories → agent tool-result middleware
api.registerEmbeddedExtensionFactory(...) 路径由
api.registerAgentToolResultMiddleware(...) 替代,并在
contracts.agentToolResultMiddleware 中提供显式运行时列表。OpenClawSchemaType alias → OpenClawConfig
OpenClawSchemaType alias → OpenClawConfig
openclaw/plugin-sdk 重新导出的 OpenClawSchemaType 现在是
OpenClawConfig 的单行别名。请优先使用规范名称。extensions/ 下的内置渠道/提供商插件内部)
会在它们自己的 api.ts 和 runtime-api.ts
桶中跟踪。它们不影响第三方插件契约,因此不会列在这里。
如果你直接使用某个内置插件的本地桶,请在升级前阅读该桶中的
弃用注释。移除时间线
| 时间 | 会发生什么 |
|---|---|
| 现在 | 已弃用表面会发出运行时警告 |
| 下一个主版本 | 已弃用表面将被移除;仍使用它们的插件将失败 |