OpenClaw 已经从一个广泛的向后兼容层迁移到了现代插件架构,采用了聚焦且有文档说明的导入方式。如果你的插件是在新架构之前构建的,本指南将帮助你完成迁移。Documentation Index
Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt
Use this file to discover all available pages before exploring further.
正在发生的变化
旧的插件系统提供了两个开放面,让插件可以从单一入口导入所需的任何内容:openclaw/plugin-sdk/compat— 一个单一导入,重新导出了几十个辅助工具。它的引入是为了在构建新插件架构期间,让旧的基于 hook 的插件继续工作。openclaw/plugin-sdk/infra-runtime— 一个广泛的运行时辅助工具总入口,混合了系统事件、心跳状态、投递队列、fetch/proxy 辅助工具、文件辅助工具、审批类型以及无关的实用工具。openclaw/plugin-sdk/config-runtime— 一个广泛的配置兼容总入口,在迁移窗口期间仍保留了已弃用的直接加载/写入辅助工具。openclaw/extension-api— 一个桥接层,使插件能够直接访问宿主侧辅助工具,例如嵌入式 agent 运行器。api.registerEmbeddedExtensionFactory(...)— 一个已移除的仅 Pi 可用的捆绑扩展 hook,它可以观察嵌入式运行器事件,例如tool_result。
为什么会这样改
旧方案带来了这些问题:- 启动慢 — 导入一个辅助工具会加载几十个无关模块
- 循环依赖 — 广泛的重导出让创建导入循环变得很容易
- API 面不清晰 — 无法判断哪些导出是稳定的,哪些是内部的
openclaw/plugin-sdk/\<subpath\>)都是一个小型、自包含的模块,具有明确用途和文档化契约。
捆绑通道的旧 provider 便利接缝也已经移除。带通道品牌的辅助接缝是私有的单仓库快捷方式,不是稳定的插件契约。请改用更窄的通用 SDK 子路径。在捆绑插件工作区内部,将 provider 自有的辅助工具保留在该插件自己的 api.ts 或 runtime-api.ts 中。
当前的捆绑 provider 示例:
- Anthropic 将 Claude 专用流式辅助工具保留在自己的
api.ts/contract-api.ts接缝中 - OpenAI 将 provider 构建器、默认模型辅助工具以及实时 provider 构建器保留在自己的
api.ts中 - OpenRouter 将 provider 构建器以及 onboarding/config 辅助工具保留在自己的
api.ts中
兼容性政策
对于外部插件,兼容性工作遵循以下顺序:- 添加新的契约
- 通过兼容适配器继续保持旧行为
- 发出诊断或警告,说明旧路径和替代路径
- 在测试中覆盖两条路径
- 记录弃用和迁移路径
- 仅在公布的迁移窗口之后才移除,通常是在某个大版本中
pnpm plugins:boundary-report 审核当前迁移队列。使用 pnpm plugins:boundary-report:summary 获取简要计数,使用 --owner <id> 查看单个插件或兼容性负责人,使用 pnpm plugins:boundary-report:ci 让 CI 在存在待处理兼容记录、跨负责人保留的 SDK 导入或未使用的保留 SDK 子路径时失败。该报告会按移除日期分组已弃用的兼容记录,统计本地代码/文档引用,展示跨负责人保留的 SDK 导入,并汇总私有内存主机 SDK 桥接,以便兼容性清理保持明确,而不是依赖临时搜索。保留的 SDK 子路径必须具有已追踪的负责人使用情况;未使用的保留辅助导出应从公共 SDK 中移除。
如果某个清单字段仍被接受,插件作者可以继续使用它,直到文档和诊断另有说明。新代码应优先使用文档化的替代方案,但现有插件在常规次版本发布期间不应被破坏。
如何迁移
迁移运行时配置的加载/写入辅助工具
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-internal-config-api 和
pnpm check:no-runtime-action-load-config 保护:新的生产插件用法会直接失败,直接配置写入会失败,gateway 服务器方法必须使用请求运行时快照,运行时通道的 send/action/client 辅助工具必须从其边界接收配置,长生命周期运行时模块不允许出现任何环境中的 loadConfig() 调用。新的插件代码还应避免导入宽泛的 openclaw/plugin-sdk/config-runtime 兼容总入口。请使用与任务匹配的窄 SDK 子路径:| 需求 | 导入 |
|---|---|
OpenClawConfig 等配置类型 | openclaw/plugin-sdk/config-types |
| 已加载配置断言和插件入口配置查找 | 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 |
将 Pi 的 tool-result 扩展迁移到中间件
api.registerEmbeddedExtensionFactory(...) tool-result 处理器。将基于审批的处理器迁移到能力事实
approvalCapability.nativeRuntime 以及共享的运行时上下文注册表暴露原生审批行为。关键变化:- 将
approvalCapability.handler.loadRuntime(...)替换为approvalCapability.nativeRuntime - 将审批特定的认证/投递逻辑从旧的
plugin.auth/plugin.approvals绑定中移出,并迁移到approvalCapability ChannelPlugin.approvals已从公共 channel-plugin 契约中移除;请将 delivery/native/render 字段迁移到approvalCapability上plugin.auth仍仅用于通道登录/登出流程;其中的审批认证 hook 不再被核心读取- 通过
openclaw/plugin-sdk/channel-runtime-context注册通道拥有的运行时对象,例如客户端、token 或 Bolt 应用 - 不要从原生审批处理器发送插件拥有的 reroute 通知;核心现在从实际投递结果中负责“转到其他位置”的通知
- 在将
channelRuntime传入createChannelManager(...)时,请提供真实的createPluginRuntime().channel面。部分 stub 会被拒绝
/plugins/sdk-channel-plugins 获取当前审批能力布局。审计 Windows wrapper 回退行为
openclaw/plugin-sdk/windows-spawn,那么未解析的 Windows
.cmd/.bat wrapper 现在会默认失败关闭,除非你显式传入 allowShellFallback: true。allowShellFallback,而应改为处理抛出的错误。替换为聚焦导入
| 旧导入 | 现代等价项 |
|---|---|
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.* |
替换宽泛的 infra-runtime 导入
openclaw/plugin-sdk/infra-runtime 仍为外部兼容性而存在,但新代码应导入它实际需要的聚焦辅助工具面:| 需求 | 导入 |
|---|---|
| 系统事件队列辅助工具 | openclaw/plugin-sdk/system-event-runtime |
| 心跳事件和可见性辅助工具 | 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 |
| 感知调度器的 fetch | openclaw/plugin-sdk/runtime-fetch |
| 代理和受控 fetch 辅助工具 | openclaw/plugin-sdk/fetch-runtime |
| SSRF 调度器策略类型 | openclaw/plugin-sdk/ssrf-dispatcher |
| 审批请求/解析类型 | openclaw/plugin-sdk/approval-runtime |
| 审批回复载荷和命令辅助工具 | 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 扫描防护限制,因此仓库代码不能退回到这个宽泛总入口。迁移通道 route 辅助工具
openclaw/plugin-sdk/channel-route。
较旧的 route-key 和可比较目标名称在迁移窗口期间仍保留为兼容别名,但新插件应使用能直接描述行为的 route 名称:| 旧辅助工具 | 现代辅助工具 |
|---|---|
channelRouteIdentityKey(...) | channelRouteDedupeKey(...) |
channelRouteKey(...) | channelRouteCompactKey(...) |
ComparableChannelTarget | ChannelRouteParsedTarget |
resolveComparableTargetForChannel(...) | resolveRouteTargetForChannel(...) |
resolveComparableTargetForLoadedChannel(...) | resolveRouteTargetForLoadedChannel(...) |
comparableChannelTargetsMatch(...) | channelRouteTargetsMatchExact(...) |
comparableChannelTargetsShareRoute(...) | channelRouteTargetsShareConversation(...) |
{ channel, to, accountId, threadId }。如果你的插件拥有自定义 target 语法,请使用 resolveChannelRouteTargetWithParser(...) 将该解析器适配到相同的 route target 契约中。导入路径参考
常见导入路径表
常见导入路径表
scripts/lib/plugin-sdk-entrypoints.json。
已保留的捆绑插件辅助接缝已从公共 SDK 导出映射中移除,除了明确文档化的兼容外观,例如为已发布的 @openclaw/discord@2026.3.13 包保留的已弃用 plugin-sdk/discord shim。特定 owner 的辅助工具保留在所属插件包内部;共享宿主行为应通过通用 SDK 契约迁移,例如 plugin-sdk/gateway-runtime、plugin-sdk/security-runtime 和 plugin-sdk/plugin-config-runtime。
请使用最符合任务的最窄导入。如果找不到某个导出,请检查 src/plugin-sdk/ 下的源代码,或者询问维护者它应该归属哪个通用契约。
当前弃用项
下面这些更窄的弃用项适用于整个 plugin SDK、provider 契约、运行时面和清单。它们现在仍然可用,但会在未来的大版本中移除。每一项下面的条目都会把旧 API 映射到其标准替代项。command-auth 帮助构建器 → command-status
command-auth 帮助构建器 → command-status
openclaw/plugin-sdk/command-auth):buildCommandsMessage、
buildCommandsMessagePaginated、buildHelpMessage。新(openclaw/plugin-sdk/command-status):签名相同,导出相同——只是从更窄的子路径导入。command-auth
通过兼容 stub 重新导出它们。提及门控辅助工具 → resolveInboundMentionDecision
提及门控辅助工具 → 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 和 channel actions 辅助工具
Channel runtime shim 和 channel actions 辅助工具
openclaw/plugin-sdk/channel-runtime 是为旧通道插件提供的兼容 shim。不要在新代码中导入它;请使用
openclaw/plugin-sdk/channel-runtime-context 来注册运行时对象。openclaw/plugin-sdk/channel-actions 中的 channelActions* 辅助工具与原始的 “actions” 通道导出一起已弃用。
请改为通过语义化的 presentation 面暴露能力——通道插件声明它们渲染什么(cards、buttons、selects),而不是它们接受哪些原始 action 名称。Web search provider tool() 辅助工具 → 插件上的 createTool()
Web search provider tool() 辅助工具 → 插件上的 createTool()
openclaw/plugin-sdk/provider-web-search 的 tool() 工厂。新:直接在 provider 插件上实现 createTool(...)。
OpenClaw 不再需要 SDK 辅助工具来注册工具包装器。纯文本通道信封 → BodyForAgent
纯文本通道信封 → BodyForAgent
formatInboundEnvelope(...)(以及
ChannelMessageForAgent.channelEnvelope),用于从入站通道消息构建扁平的纯文本 prompt 信封。新:BodyForAgent 加上结构化的用户上下文块。通道插件将路由元数据(线程、主题、回复对象、反应)作为带类型的字段附加,而不是把它们拼接进 prompt 字符串。formatAgentEnvelope(...) 辅助工具仍支持为生成的面向 assistant 的信封使用,但入站纯文本信封正在退出。受影响的区域:inbound_claim、message_received,以及任何对 channelEnvelope 文本进行后处理的自定义通道插件。Provider 发现类型 → provider catalog 类型
Provider 发现类型 → provider catalog 类型
| 旧别名 | 新类型 |
|---|---|
ProviderDiscoveryOrder | ProviderCatalogOrder |
ProviderDiscoveryContext | ProviderCatalogContext |
ProviderDiscoveryResult | ProviderCatalogResult |
ProviderPluginDiscovery | ProviderPluginCatalog |
ProviderCapabilities 静态集合——provider 插件应使用显式的 provider hooks,例如 buildReplayPolicy、
normalizeToolSchemas 和 wrapStreamFn,而不是静态对象。Thinking policy hooks → resolveThinkingProfile
Thinking policy hooks → resolveThinkingProfile
ProviderThinkingPolicy 上的三个独立 hook):
isBinaryThinking(ctx)、supportsXHighThinking(ctx) 和
resolveDefaultThinkingLevel(ctx)。新:单个 resolveThinkingProfile(ctx),返回一个带有标准 id、可选 label 和分级 level 列表的 ProviderThinkingProfile。OpenClaw 会根据 profile 等级自动降级陈旧的存储值。请实现一个 hook,而不是三个。旧 hook 在弃用窗口期间仍可工作,但不会与 profile 结果组合。外部 OAuth provider 回退 → contracts.externalAuthProviders
外部 OAuth provider 回退 → contracts.externalAuthProviders
resolveExternalOAuthProfiles(...)。新:在插件清单中声明 contracts.externalAuthProviders
并且实现 resolveExternalAuthProfiles(...)。旧的“auth 回退”路径会在运行时发出警告,并将在以后移除。Provider 环境变量查找 → setup.providers[].envVars
Provider 环境变量查找 → setup.providers[].envVars
providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }。新:将同样的环境变量查找映射到清单中的 setup.providers[].envVars。
这样可以将 setup/status 的环境元数据集中在一个地方,并避免仅为回答环境变量查找而启动插件运行时。在弃用窗口结束之前,providerAuthEnvVars 仍通过兼容适配器受支持。Memory 插件注册 → registerMemoryCapability
Memory 插件注册 → registerMemoryCapability
api.registerMemoryPromptSection(...)、
api.registerMemoryFlushPlan(...)、
api.registerMemoryRuntime(...)。新:在 memory-state API 上一次调用——
registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })。位置相同,注册调用变为单次。增量 memory 辅助工具
(registerMemoryPromptSupplement、registerMemoryCorpusSupplement、
registerMemoryEmbeddingProvider) 不受影响。子 agent 会话消息类型重命名
子 agent 会话消息类型重命名
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(单数)返回一个活动 task-flow 访问器。新:runtime.tasks.managedFlows 为创建、更新、取消或运行子任务的插件保留受管理的 TaskFlow 变更运行时。仅当插件只需要基于 DTO 的读取时,请使用 runtime.tasks.flows。嵌入式扩展工厂 → agent tool-result 中间件
嵌入式扩展工厂 → agent tool-result 中间件
api.registerEmbeddedExtensionFactory(...) 路径,已由
api.registerAgentToolResultMiddleware(...) 替代,并在 contracts.agentToolResultMiddleware
中显式列出 runtime。OpenClawSchemaType 别名 → OpenClawConfig
OpenClawSchemaType 别名 → OpenClawConfig
openclaw/plugin-sdk 重导出的 OpenClawSchemaType 现在只是 OpenClawConfig 的一行别名。请优先使用标准名称。extensions/ 下捆绑通道/provider 插件内部)会在它们自己的 api.ts 和 runtime-api.ts
总入口中跟踪。它们不影响第三方插件契约,也不会在这里列出。如果你直接消费某个捆绑插件的本地总入口,请先阅读该总入口中的弃用注释再升级。移除时间线
| 时间 | 会发生什么 |
|---|---|
| 现在 | 已弃用的面会发出运行时警告 |
| 下一个大版本 | 已弃用的面将被移除;仍在使用它们的插件会失败 |