Skip to main content

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 已经从一个广泛的向后兼容层迁移到了现代插件架构,采用了聚焦且有文档说明的导入方式。如果你的插件是在新架构之前构建的,本指南将帮助你完成迁移。

正在发生的变化

旧的插件系统提供了两个开放面,让插件可以从单一入口导入所需的任何内容:
  • 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
这些广泛的导入面现在都已弃用。它们在运行时仍然可用,但新插件不得使用它们,现有插件应在下一个大版本移除它们之前完成迁移。仅 Pi 的嵌入式扩展工厂注册 API 已经被移除;请改用 tool-result 中间件。 OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释已文档化的插件行为。任何破坏性契约变更都必须先经过兼容适配器、诊断、文档和弃用窗口。这适用于 SDK 导入、清单字段、设置 API、hook 以及运行时注册行为。
这层向后兼容机制将在未来的大版本中移除。仍然从这些面导入的插件在那时会失效。 仅 Pi 的嵌入式扩展工厂注册现在已经不会再加载。

为什么会这样改

旧方案带来了这些问题:
  • 启动慢 — 导入一个辅助工具会加载几十个无关模块
  • 循环依赖 — 广泛的重导出让创建导入循环变得很容易
  • API 面不清晰 — 无法判断哪些导出是稳定的,哪些是内部的
现代插件 SDK 解决了这些问题:每个导入路径(openclaw/plugin-sdk/\<subpath\>)都是一个小型、自包含的模块,具有明确用途和文档化契约。 捆绑通道的旧 provider 便利接缝也已经移除。带通道品牌的辅助接缝是私有的单仓库快捷方式,不是稳定的插件契约。请改用更窄的通用 SDK 子路径。在捆绑插件工作区内部,将 provider 自有的辅助工具保留在该插件自己的 api.tsruntime-api.ts 中。 当前的捆绑 provider 示例:
  • Anthropic 将 Claude 专用流式辅助工具保留在自己的 api.ts / contract-api.ts 接缝中
  • OpenAI 将 provider 构建器、默认模型辅助工具以及实时 provider 构建器保留在自己的 api.ts
  • OpenRouter 将 provider 构建器以及 onboarding/config 辅助工具保留在自己的 api.ts

兼容性政策

对于外部插件,兼容性工作遵循以下顺序:
  1. 添加新的契约
  2. 通过兼容适配器继续保持旧行为
  3. 发出诊断或警告,说明旧路径和替代路径
  4. 在测试中覆盖两条路径
  5. 记录弃用和迁移路径
  6. 仅在公布的迁移窗口之后才移除,通常是在某个大版本中
维护者可以使用 pnpm plugins:boundary-report 审核当前迁移队列。使用 pnpm plugins:boundary-report:summary 获取简要计数,使用 --owner <id> 查看单个插件或兼容性负责人,使用 pnpm plugins:boundary-report:ci 让 CI 在存在待处理兼容记录、跨负责人保留的 SDK 导入或未使用的保留 SDK 子路径时失败。该报告会按移除日期分组已弃用的兼容记录,统计本地代码/文档引用,展示跨负责人保留的 SDK 导入,并汇总私有内存主机 SDK 桥接,以便兼容性清理保持明确,而不是依赖临时搜索。保留的 SDK 子路径必须具有已追踪的负责人使用情况;未使用的保留辅助导出应从公共 SDK 中移除。 如果某个清单字段仍被接受,插件作者可以继续使用它,直到文档和诊断另有说明。新代码应优先使用文档化的替代方案,但现有插件在常规次版本发布期间不应被破坏。

如何迁移

1

迁移运行时配置的加载/写入辅助工具

捆绑插件应停止直接调用 api.runtime.config.loadConfig()api.runtime.config.writeConfigFile(...)。优先使用已经传入当前调用路径的配置。 需要当前进程快照的长生命周期处理器可以使用 api.runtime.config.current()。 长生命周期 agent 工具应在 execute 中使用工具上下文的 ctx.getRuntimeConfig(), 这样即使某个工具是在配置写入之前创建的,也仍能看到刷新后的运行时配置。配置写入必须通过事务型辅助工具,并选择写后策略:
await api.runtime.config.mutateConfigFile({
  afterWrite: { mode: "auto" },
  mutate(draft) {
    draft.plugins ??= {};
  },
});
当调用方知道该变更需要一次干净的 gateway 重启时,请使用 afterWrite: { mode: "restart", reason: "..." };只有当调用方负责后续步骤并且明确想抑制重载规划器时,才使用 afterWrite: { mode: "none", reason: "..." }。 变更结果会包含一个用于测试和日志的类型化 followUp 摘要;gateway 仍负责应用或安排重启。 在迁移窗口期间,loadConfigwriteConfigFile 仍作为面向外部插件的已弃用兼容辅助工具存在,并会通过 runtime-config-load-write 兼容代码仅警告一次。捆绑插件和仓库运行时代码受扫描防护约束, 分别由 pnpm check:deprecated-internal-config-apipnpm 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
捆绑插件及其测试受扫描防护限制,不允许使用这个宽泛的总入口,因此导入和 mock 都保持在所需行为的本地范围内。这个宽泛总入口仍为外部兼容性而存在,但新代码不应依赖它。
2

将 Pi 的 tool-result 扩展迁移到中间件

捆绑插件必须用运行时中立的中间件替换仅 Pi 可用的 api.registerEmbeddedExtensionFactory(...) tool-result 处理器。
// Pi 和 Codex 运行时动态工具
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["pi", "codex"],
});
同时更新插件清单:
{
  "contracts": {
    "agentToolResultMiddleware": ["pi", "codex"]
  }
}
外部插件不能注册 tool-result 中间件,因为它可以在模型看到之前重写高信任度的工具输出。
3

将基于审批的处理器迁移到能力事实

具备审批能力的通道插件现在通过 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 获取当前审批能力布局。
4

审计 Windows wrapper 回退行为

如果你的插件使用 openclaw/plugin-sdk/windows-spawn,那么未解析的 Windows .cmd/.bat wrapper 现在会默认失败关闭,除非你显式传入 allowShellFallback: true
// 之前
const program = applyWindowsSpawnProgramPolicy({ candidate });

// 之后
const program = applyWindowsSpawnProgramPolicy({
  candidate,
  // 仅当可信的兼容性调用方明确接受经由 shell 的回退时才设置此项。
  allowShellFallback: true,
});
如果你的调用方并不刻意依赖 shell 回退,不要设置 allowShellFallback,而应改为处理抛出的错误。
5

查找已弃用导入

在你的插件中搜索来自任一已弃用面导入:
grep -r "plugin-sdk/compat" my-plugin/
grep -r "plugin-sdk/infra-runtime" my-plugin/
grep -r "plugin-sdk/config-runtime" my-plugin/
grep -r "openclaw/extension-api" my-plugin/
6

替换为聚焦导入

旧面中的每个导出都对应一个具体的现代导入路径:
// 之前(已弃用的向后兼容层)
import {
  createChannelReplyPipeline,
  createPluginRuntimeStore,
  resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";

// 之后(现代的聚焦导入)
import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
对于宿主侧辅助工具,请使用注入的插件运行时,而不是直接导入:
// 之前(已弃用的 extension-api 桥接)
import { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });

// 之后(注入的运行时)
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
同样的模式也适用于其他旧的桥接辅助工具:
旧导入现代等价项
resolveAgentDirapi.runtime.agent.resolveAgentDir
resolveAgentWorkspaceDirapi.runtime.agent.resolveAgentWorkspaceDir
resolveAgentIdentityapi.runtime.agent.resolveAgentIdentity
resolveThinkingDefaultapi.runtime.agent.resolveThinkingDefault
resolveAgentTimeoutMsapi.runtime.agent.resolveAgentTimeoutMs
ensureAgentWorkspaceapi.runtime.agent.ensureAgentWorkspace
会话存储辅助工具api.runtime.agent.session.*
7

替换宽泛的 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
感知调度器的 fetchopenclaw/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 扫描防护限制,因此仓库代码不能退回到这个宽泛总入口。
8

迁移通道 route 辅助工具

新的通道路由代码应使用 openclaw/plugin-sdk/channel-route。 较旧的 route-key 和可比较目标名称在迁移窗口期间仍保留为兼容别名,但新插件应使用能直接描述行为的 route 名称:
旧辅助工具现代辅助工具
channelRouteIdentityKey(...)channelRouteDedupeKey(...)
channelRouteKey(...)channelRouteCompactKey(...)
ComparableChannelTargetChannelRouteParsedTarget
resolveComparableTargetForChannel(...)resolveRouteTargetForChannel(...)
resolveComparableTargetForLoadedChannel(...)resolveRouteTargetForLoadedChannel(...)
comparableChannelTargetsMatch(...)channelRouteTargetsMatchExact(...)
comparableChannelTargetsShareRoute(...)channelRouteTargetsShareConversation(...)
现代 route 辅助工具会在原生审批、回复抑制、入站去重、cron 投递和会话路由中一致地规范化 { channel, to, accountId, threadId }。如果你的插件拥有自定义 target 语法,请使用 resolveChannelRouteTargetWithParser(...) 将该解析器适配到相同的 route target 契约中。
9

构建并测试

pnpm build
pnpm test -- my-plugin/

导入路径参考

导入路径用途关键导出
plugin-sdk/plugin-entry规范的插件入口辅助工具definePluginEntry
plugin-sdk/core通道入口定义/构建器的旧式总导出defineChannelPluginEntry, createChatChannelPlugin
plugin-sdk/config-schema根配置 schema 导出OpenClawSchema
plugin-sdk/provider-entry单 provider 入口辅助工具defineSingleProviderPluginEntry
plugin-sdk/channel-core聚焦的通道入口定义和构建器defineChannelPluginEntry, defineSetupPluginEntry, createChatChannelPlugin, createChannelPluginBase
plugin-sdk/setup共享的设置向导辅助工具Allowlist 提示、设置状态构建器
plugin-sdk/setup-runtime设置期运行时辅助工具导入安全的 setup patch 适配器、lookup-note 辅助工具、promptResolvedAllowFromsplitSetupEntries、委派 setup 代理
plugin-sdk/setup-adapter-runtime设置适配器辅助工具createEnvPatchedAccountSetupAdapter
plugin-sdk/setup-tools设置工具辅助工具formatCliCommanddetectBinaryextractArchiveresolveBrewExecutableformatDocsLinkCONFIG_DIR
plugin-sdk/account-core多账号辅助工具账号列表/配置/动作门控辅助工具
plugin-sdk/account-id账号 ID 辅助工具DEFAULT_ACCOUNT_ID、账号 ID 规范化
plugin-sdk/account-resolution账号查找辅助工具账号查找 + 默认回退辅助工具
plugin-sdk/account-helpers窄账号辅助工具账号列表/账号动作辅助工具
plugin-sdk/channel-setup设置向导适配器createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter, createOptionalChannelSetupWizard, 以及 DEFAULT_ACCOUNT_ID, createTopLevelChannelDmPolicy, setSetupChannelEnabled, splitSetupEntries
plugin-sdk/channel-pairingDM 配对原语createChannelPairingController
plugin-sdk/channel-reply-pipeline回复前缀、打字状态和源投递接线createChannelReplyPipeline, resolveChannelSourceReplyDeliveryMode
plugin-sdk/channel-config-helpers配置适配器工厂和 DM 访问辅助工具createHybridChannelConfigAdapter, resolveChannelDmAccess, resolveChannelDmAllowFrom, resolveChannelDmPolicy, normalizeChannelDmPolicy, normalizeLegacyDmAliases
plugin-sdk/channel-config-schema配置 schema 构建器共享的通道配置 schema 原语和通用构建器
plugin-sdk/bundled-channel-config-schema捆绑配置 schema仅限 OpenClaw 维护的捆绑插件;新插件必须定义插件本地 schema
plugin-sdk/channel-config-schema-legacy已弃用的捆绑配置 schema仅兼容别名;受维护的捆绑插件请使用 plugin-sdk/bundled-channel-config-schema
plugin-sdk/telegram-command-configTelegram 命令配置辅助工具命令名规范化、描述裁剪、重复/冲突校验
plugin-sdk/channel-policy群组/DM 策略解析resolveChannelGroupRequireMention
plugin-sdk/channel-lifecycle账号状态和草稿流生命周期辅助工具createAccountStatusSink、草稿预览收尾辅助工具
plugin-sdk/inbound-envelope入站信封辅助工具共享 route + 信封构建器辅助工具
plugin-sdk/inbound-reply-dispatch入站回复辅助工具共享记录和派发辅助工具
plugin-sdk/messaging-targets消息目标解析目标解析/匹配辅助工具
plugin-sdk/outbound-media出站媒体辅助工具共享出站媒体加载
plugin-sdk/outbound-send-deps出站发送依赖辅助工具无需导入完整出站运行时的轻量 resolveOutboundSendDep 查找
plugin-sdk/outbound-runtime出站运行时辅助工具出站投递、身份/发送委托、会话、格式化和载荷规划辅助工具
plugin-sdk/thread-bindings-runtime线程绑定辅助工具线程绑定生命周期和适配器辅助工具
plugin-sdk/agent-media-payload旧媒体载荷辅助工具面向旧字段布局的 agent 媒体载荷构建器
plugin-sdk/channel-runtime已弃用的兼容 shim仅旧通道运行时工具
plugin-sdk/channel-send-result发送结果类型回复结果类型
plugin-sdk/runtime-store持久化插件存储createPluginRuntimeStore
plugin-sdk/runtime广泛的运行时辅助工具运行时/日志/备份/插件安装辅助工具
plugin-sdk/runtime-env窄运行时 env 辅助工具logger/runtime env、超时、重试和退避辅助工具
plugin-sdk/plugin-runtime共享插件运行时辅助工具插件命令/hook/http/交互式辅助工具
plugin-sdk/hook-runtimehook 管道辅助工具共享 webhook/内部 hook 管道辅助工具
plugin-sdk/lazy-runtime懒加载运行时辅助工具createLazyRuntimeModule, createLazyRuntimeMethod, createLazyRuntimeMethodBinder, createLazyRuntimeNamedExport, createLazyRuntimeSurface
plugin-sdk/process-runtime进程辅助工具共享 exec 辅助工具
plugin-sdk/cli-runtimeCLI 运行时辅助工具命令格式化、等待、版本辅助工具
plugin-sdk/gateway-runtimegateway 辅助工具gateway 客户端、事件循环就绪启动辅助工具,以及通道状态 patch 辅助工具
plugin-sdk/config-runtime已弃用的配置兼容 shim优先使用 config-typesplugin-config-runtimeruntime-config-snapshotconfig-mutation
plugin-sdk/telegram-command-configTelegram 命令辅助工具当捆绑的 Telegram 契约面不可用时,提供稳定回退的 Telegram 命令校验辅助工具
plugin-sdk/approval-runtime审批提示辅助工具exec/plugin 审批载荷、审批能力/配置文件辅助工具、原生审批路由/运行时辅助工具,以及结构化审批显示路径格式化
plugin-sdk/approval-auth-runtime审批认证辅助工具审批人解析、同聊天动作认证
plugin-sdk/approval-client-runtime审批客户端辅助工具原生 exec 审批配置文件/过滤器辅助工具
plugin-sdk/approval-delivery-runtime审批投递辅助工具原生审批能力/投递适配器
plugin-sdk/approval-gateway-runtime审批 gateway 辅助工具共享审批 gateway 解析辅助工具
plugin-sdk/approval-handler-adapter-runtime审批适配器辅助工具面向热通道入口点的轻量原生审批适配器加载辅助工具
plugin-sdk/approval-handler-runtime审批处理器辅助工具更广泛的审批处理器运行时辅助工具;当足够用时,优先使用更窄的适配器/gateway 接缝
plugin-sdk/approval-native-runtime审批目标辅助工具原生审批目标/账号绑定辅助工具
plugin-sdk/approval-reply-runtime审批回复辅助工具exec/plugin 审批回复载荷辅助工具
plugin-sdk/channel-runtime-context通道运行时上下文辅助工具通用通道运行时上下文注册/获取/监听辅助工具
plugin-sdk/security-runtime安全辅助工具共享信任、DM 门控、外部内容和秘密收集辅助工具
plugin-sdk/ssrf-policySSRF 策略辅助工具主机 allowlist 和私有网络策略辅助工具
plugin-sdk/ssrf-runtimeSSRF 运行时辅助工具固定调度器、受控 fetch、SSRF 策略辅助工具
plugin-sdk/system-event-runtime系统事件辅助工具enqueueSystemEvent, peekSystemEventEntries
plugin-sdk/heartbeat-runtime心跳辅助工具心跳事件和可见性辅助工具
plugin-sdk/delivery-queue-runtime投递队列辅助工具drainPendingDeliveries
plugin-sdk/channel-activity-runtime通道活动辅助工具recordChannelActivity
plugin-sdk/dedupe-runtime去重辅助工具内存中的去重缓存
plugin-sdk/file-access-runtime文件访问辅助工具安全的本地文件/媒体路径辅助工具
plugin-sdk/transport-ready-runtime传输就绪辅助工具waitForTransportReady
plugin-sdk/collection-runtime有界缓存辅助工具pruneMapToMaxSize
plugin-sdk/diagnostic-runtime诊断门控辅助工具isDiagnosticFlagEnabled, isDiagnosticsEnabled
plugin-sdk/error-runtime错误格式化辅助工具formatUncaughtError, isApprovalNotFoundError, error graph 辅助工具
plugin-sdk/fetch-runtime包装的 fetch/proxy 辅助工具resolveFetch、proxy 辅助工具、EnvHttpProxyAgent 选项辅助工具
plugin-sdk/host-runtime主机规范化辅助工具normalizeHostname, normalizeScpRemoteHost
plugin-sdk/retry-runtime重试辅助工具RetryConfig, retryAsync, 策略运行器
plugin-sdk/allow-fromallowlist 格式化formatAllowFromLowercase
plugin-sdk/allowlist-resolutionallowlist 输入映射mapAllowlistResolutionInputs
plugin-sdk/command-auth命令门控和命令面辅助工具resolveControlCommandGate、发送者授权辅助工具、命令注册表辅助工具,包括动态参数菜单格式化
plugin-sdk/command-status命令状态/帮助渲染器buildCommandsMessage, buildCommandsMessagePaginated, buildHelpMessage
plugin-sdk/secret-input秘密输入解析秘密输入辅助工具
plugin-sdk/webhook-ingressWebhook 请求辅助工具Webhook 目标工具
plugin-sdk/webhook-request-guardsWebhook 正文防护辅助工具请求正文读取/限制辅助工具
plugin-sdk/reply-runtime共享回复运行时入站派发、心跳、回复规划器、分块
plugin-sdk/reply-dispatch-runtime窄回复派发辅助工具收尾、provider 派发和会话标签辅助工具
plugin-sdk/reply-history回复历史辅助工具buildHistoryContext, buildPendingHistoryContextFromMap, recordPendingHistoryEntry, clearHistoryEntriesIfEnabled
plugin-sdk/reply-reference回复引用规划createReplyReferencePlanner
plugin-sdk/reply-chunking回复分块辅助工具文本/markdown 分块辅助工具
plugin-sdk/session-store-runtime会话存储辅助工具存储路径 + updated-at 辅助工具
plugin-sdk/state-paths状态路径辅助工具状态和 OAuth 目录辅助工具
plugin-sdk/routing路由/会话键辅助工具resolveAgentRoute, buildAgentSessionKey, resolveDefaultAgentBoundAccountId, 会话键规范化辅助工具
plugin-sdk/status-helpers通道状态辅助工具通道/账号状态摘要构建器、运行时状态默认值、问题元数据辅助工具
plugin-sdk/target-resolver-runtime目标解析器辅助工具共享目标解析器辅助工具
plugin-sdk/string-normalization-runtime字符串规范化辅助工具slug/字符串规范化辅助工具
plugin-sdk/request-url请求 URL 辅助工具从类请求输入中提取字符串 URL
plugin-sdk/run-command定时命令辅助工具具有规范化 stdout/stderr 的定时命令运行器
plugin-sdk/param-readers参数读取器常见工具/CLI 参数读取器
plugin-sdk/tool-payload工具载荷提取从工具结果对象中提取规范化载荷
plugin-sdk/tool-send工具发送提取从工具参数中提取规范的发送目标字段
plugin-sdk/temp-path临时路径辅助工具共享临时下载路径辅助工具
plugin-sdk/logging-core日志辅助工具子系统 logger 和脱敏辅助工具
plugin-sdk/markdown-table-runtimemarkdown 表格辅助工具markdown 表格模式辅助工具
plugin-sdk/reply-payload消息回复类型回复载荷类型
plugin-sdk/provider-setup经过筛选的本地/自托管 provider 设置辅助工具自托管 provider 发现/配置辅助工具
plugin-sdk/self-hosted-provider-setup聚焦的 OpenAI 兼容自托管 provider 设置辅助工具相同的自托管 provider 发现/配置辅助工具
plugin-sdk/provider-auth-runtimeprovider 运行时认证辅助工具运行时 API key 解析辅助工具
plugin-sdk/provider-auth-api-keyprovider API key 设置辅助工具API key onboarding/配置写入辅助工具
plugin-sdk/provider-auth-resultprovider 认证结果辅助工具标准 OAuth 认证结果构建器
plugin-sdk/provider-auth-loginprovider 交互式登录辅助工具共享交互式登录辅助工具
plugin-sdk/provider-selection-runtimeprovider 选择辅助工具配置或自动 provider 选择和原始 provider 配置合并
plugin-sdk/provider-env-varsprovider 环境变量辅助工具provider 认证环境变量查找辅助工具
plugin-sdk/provider-model-shared共享 provider 模型/回放辅助工具ProviderReplayFamily, buildProviderReplayFamilyHooks, normalizeModelCompat, 共享回放策略构建器、provider 端点辅助工具,以及模型 ID 规范化辅助工具
plugin-sdk/provider-catalog-shared共享 provider 目录辅助工具findCatalogTemplate, buildSingleProviderApiKeyCatalog, buildManifestModelProviderConfig, supportsNativeStreamingUsageCompat, applyProviderNativeStreamingUsageCompat
plugin-sdk/provider-onboardprovider onboarding patchonboarding 配置辅助工具
plugin-sdk/provider-httpprovider HTTP 辅助工具通用 provider HTTP/端点能力辅助工具,包括音频转写 multipart form 辅助工具
plugin-sdk/provider-web-fetchprovider web-fetch 辅助工具web-fetch provider 注册/缓存辅助工具
plugin-sdk/provider-web-search-config-contractprovider web-search 配置辅助工具对于不需要插件启用接线的 provider,提供窄 web-search 配置/凭据辅助工具
plugin-sdk/provider-web-search-contractprovider web-search 契约辅助工具窄 web-search 配置/凭据契约辅助工具,例如 createWebSearchProviderContractFields, enablePluginInConfig, resolveProviderWebSearchPluginConfig, 以及作用域凭据 setter/getter
plugin-sdk/provider-web-searchprovider web-search 辅助工具web-search provider 注册/缓存/运行时辅助工具
plugin-sdk/provider-toolsprovider 工具/schema 兼容辅助工具ProviderToolCompatFamily, buildProviderToolCompatFamilyHooks, Gemini schema 清理 + 诊断,以及 xAI 兼容辅助工具,例如 resolveXaiModelCompatPatch / applyXaiModelCompat
plugin-sdk/provider-usageprovider 使用量辅助工具fetchClaudeUsage, fetchGeminiUsage, fetchGithubCopilotUsage,以及其他 provider 使用量辅助工具
plugin-sdk/provider-streamprovider 流包装器辅助工具ProviderStreamFamily, buildProviderStreamFamilyHooks, composeProviderStreamWrappers, 流包装器类型,以及共享 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具
plugin-sdk/provider-transport-runtimeprovider 传输辅助工具原生 provider 传输辅助工具,例如受控 fetch、传输消息转换,以及可写传输事件流
plugin-sdk/keyed-async-queue有序异步队列KeyedAsyncQueue
plugin-sdk/media-runtime共享媒体辅助工具媒体 fetch/transform/store 辅助工具、基于 ffprobe 的视频尺寸探测,以及媒体载荷构建器
plugin-sdk/media-generation-runtime共享媒体生成辅助工具共享故障转移辅助工具、候选选择,以及图像/视频/音乐生成的缺失模型消息
plugin-sdk/media-understanding媒体理解辅助工具媒体理解 provider 类型,以及面向 provider 的图像/音频辅助导出
plugin-sdk/text-runtime共享文本辅助工具assistant 可见文本剥离、markdown 渲染/分块/表格辅助工具、脱敏辅助工具、指令标签辅助工具、安全文本工具,以及相关文本/日志辅助工具
plugin-sdk/text-chunking文本分块辅助工具出站文本分块辅助工具
plugin-sdk/speech语音辅助工具语音 provider 类型,以及面向 provider 的指令、注册表、校验辅助工具和 OpenAI 兼容 TTS 构建器
plugin-sdk/speech-core共享语音核心语音 provider 类型、注册表、指令、规范化
plugin-sdk/realtime-transcription实时转写辅助工具provider 类型、注册表辅助工具和共享 WebSocket 会话辅助工具
plugin-sdk/realtime-voice实时语音辅助工具provider 类型、注册表/解析辅助工具和桥接会话辅助工具
plugin-sdk/image-generation图像生成辅助工具图像生成 provider 类型,以及图像资源/data URL 辅助工具和 OpenAI 兼容图像 provider 构建器
plugin-sdk/image-generation-core共享图像生成核心图像生成类型、故障转移、认证和注册表辅助工具
plugin-sdk/music-generation音乐生成辅助工具音乐生成 provider/请求/结果类型
plugin-sdk/music-generation-core共享音乐生成核心音乐生成类型、故障转移辅助工具、provider 查找和 model-ref 解析
plugin-sdk/video-generation视频生成辅助工具视频生成 provider/请求/结果类型
plugin-sdk/video-generation-core共享视频生成核心视频生成类型、故障转移辅助工具、provider 查找和 model-ref 解析
plugin-sdk/interactive-runtime交互式回复辅助工具交互式回复载荷规范化/归约
plugin-sdk/channel-config-primitives通道配置原语窄通道配置-schema 原语
plugin-sdk/channel-config-writes通道配置写入辅助工具通道配置写入授权辅助工具
plugin-sdk/channel-plugin-common共享通道前导共享通道插件前导导出
plugin-sdk/channel-status通道状态辅助工具共享通道状态快照/摘要辅助工具
plugin-sdk/allowlist-config-editAllowlist 配置辅助工具Allowlist 配置编辑/读取辅助工具
plugin-sdk/group-access群组访问辅助工具共享群组访问决策辅助工具
plugin-sdk/direct-dm直接 DM 辅助工具共享直接 DM 认证/门控辅助工具
plugin-sdk/extension-shared共享扩展辅助工具被动通道/状态和环境代理辅助原语
plugin-sdk/webhook-targetsWebhook 目标辅助工具Webhook 目标注册表和 route 安装辅助工具
plugin-sdk/webhook-pathWebhook 路径辅助工具Webhook 路径规范化辅助工具
plugin-sdk/web-media共享 web 媒体辅助工具远程/本地媒体加载辅助工具
plugin-sdk/zodZod 重导出为 plugin SDK 消费者重导出的 zod
plugin-sdk/memory-core捆绑 memory-core 辅助工具memory 管理器/配置/文件/CLI 辅助工具面
plugin-sdk/memory-core-engine-runtimememory 引擎运行时外观memory 索引/搜索运行时外观
plugin-sdk/memory-core-host-engine-foundationmemory 宿主基础引擎memory 宿主基础引擎导出
plugin-sdk/memory-core-host-engine-embeddingsmemory 宿主 embedding 引擎memory embedding 契约、注册表访问、本地 provider,以及通用 batch/remote 辅助工具;具体远程 provider 位于各自所属插件中
plugin-sdk/memory-core-host-engine-qmdmemory 宿主 QMD 引擎memory 宿主 QMD 引擎导出
plugin-sdk/memory-core-host-engine-storagememory 宿主存储引擎memory 宿主存储引擎导出
plugin-sdk/memory-core-host-multimodalmemory 宿主多模态辅助工具memory 宿主多模态辅助工具
plugin-sdk/memory-core-host-querymemory 宿主查询辅助工具memory 宿主查询辅助工具
plugin-sdk/memory-core-host-secretmemory 宿主秘密辅助工具memory 宿主秘密辅助工具
plugin-sdk/memory-core-host-eventsmemory 宿主事件日志辅助工具memory 宿主事件日志辅助工具
plugin-sdk/memory-core-host-statusmemory 宿主状态辅助工具memory 宿主状态辅助工具
plugin-sdk/memory-core-host-runtime-climemory 宿主 CLI 运行时memory 宿主 CLI 运行时辅助工具
plugin-sdk/memory-core-host-runtime-corememory 宿主核心运行时memory 宿主核心运行时辅助工具
plugin-sdk/memory-core-host-runtime-filesmemory 宿主文件/运行时辅助工具memory 宿主文件/运行时辅助工具
plugin-sdk/memory-host-corememory 宿主核心运行时别名memory 宿主核心运行时辅助工具的供应商无关别名
plugin-sdk/memory-host-eventsmemory 宿主事件日志别名memory 宿主事件日志辅助工具的供应商无关别名
plugin-sdk/memory-host-filesmemory 宿主文件/运行时别名memory 宿主文件/运行时辅助工具的供应商无关别名
plugin-sdk/memory-host-markdown托管 markdown 辅助工具与 memory 相邻插件共享的托管 markdown 辅助工具
plugin-sdk/memory-host-search活动 memory 搜索外观懒加载活动 memory 搜索管理器运行时外观
plugin-sdk/memory-host-statusmemory 宿主状态别名memory 宿主状态辅助工具的供应商无关别名
plugin-sdk/testing测试工具旧式广泛兼容总导出;优先使用更聚焦的测试子路径,例如 plugin-sdk/plugin-test-runtimeplugin-sdk/channel-test-helpersplugin-sdk/channel-target-testingplugin-sdk/test-envplugin-sdk/test-fixtures
此表有意只包含常见迁移子集,而不是完整的 SDK 面。完整的 200+ 个入口点列表位于 scripts/lib/plugin-sdk-entrypoints.json 已保留的捆绑插件辅助接缝已从公共 SDK 导出映射中移除,除了明确文档化的兼容外观,例如为已发布的 @openclaw/discord@2026.3.13 包保留的已弃用 plugin-sdk/discord shim。特定 owner 的辅助工具保留在所属插件包内部;共享宿主行为应通过通用 SDK 契约迁移,例如 plugin-sdk/gateway-runtimeplugin-sdk/security-runtimeplugin-sdk/plugin-config-runtime 请使用最符合任务的最窄导入。如果找不到某个导出,请检查 src/plugin-sdk/ 下的源代码,或者询问维护者它应该归属哪个通用契约。

当前弃用项

下面这些更窄的弃用项适用于整个 plugin SDK、provider 契约、运行时面和清单。它们现在仍然可用,但会在未来的大版本中移除。每一项下面的条目都会把旧 API 映射到其标准替代项。
旧(openclaw/plugin-sdk/command-authbuildCommandsMessagebuildCommandsMessagePaginatedbuildHelpMessage新(openclaw/plugin-sdk/command-status:签名相同,导出相同——只是从更窄的子路径导入。command-auth 通过兼容 stub 重新导出它们。
// 之前
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// 之后
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";
:来自 openclaw/plugin-sdk/channel-inboundopenclaw/plugin-sdk/channel-mention-gatingresolveInboundMentionRequirement({ facts, policy })shouldDropInboundForMention(...)resolveInboundMentionDecision({ facts, policy }) —— 返回一个单独的决策对象,而不是两个拆分调用。下游通道插件(Slack、Discord、Matrix、MS Teams)已经切换完成。
openclaw/plugin-sdk/channel-runtime 是为旧通道插件提供的兼容 shim。不要在新代码中导入它;请使用 openclaw/plugin-sdk/channel-runtime-context 来注册运行时对象。openclaw/plugin-sdk/channel-actions 中的 channelActions* 辅助工具与原始的 “actions” 通道导出一起已弃用。 请改为通过语义化的 presentation 面暴露能力——通道插件声明它们渲染什么(cards、buttons、selects),而不是它们接受哪些原始 action 名称。
:来自 openclaw/plugin-sdk/provider-web-searchtool() 工厂。:直接在 provider 插件上实现 createTool(...)。 OpenClaw 不再需要 SDK 辅助工具来注册工具包装器。
formatInboundEnvelope(...)(以及 ChannelMessageForAgent.channelEnvelope),用于从入站通道消息构建扁平的纯文本 prompt 信封。BodyForAgent 加上结构化的用户上下文块。通道插件将路由元数据(线程、主题、回复对象、反应)作为带类型的字段附加,而不是把它们拼接进 prompt 字符串。formatAgentEnvelope(...) 辅助工具仍支持为生成的面向 assistant 的信封使用,但入站纯文本信封正在退出。受影响的区域:inbound_claimmessage_received,以及任何对 channelEnvelope 文本进行后处理的自定义通道插件。
下面四个发现类型别名现在都是 catalog 时代类型的薄包装:
旧别名新类型
ProviderDiscoveryOrderProviderCatalogOrder
ProviderDiscoveryContextProviderCatalogContext
ProviderDiscoveryResultProviderCatalogResult
ProviderPluginDiscoveryProviderPluginCatalog
另外还有旧的 ProviderCapabilities 静态集合——provider 插件应使用显式的 provider hooks,例如 buildReplayPolicynormalizeToolSchemaswrapStreamFn,而不是静态对象。
ProviderThinkingPolicy 上的三个独立 hook): isBinaryThinking(ctx)supportsXHighThinking(ctx)resolveDefaultThinkingLevel(ctx):单个 resolveThinkingProfile(ctx),返回一个带有标准 id、可选 label 和分级 level 列表的 ProviderThinkingProfile。OpenClaw 会根据 profile 等级自动降级陈旧的存储值。请实现一个 hook,而不是三个。旧 hook 在弃用窗口期间仍可工作,但不会与 profile 结果组合。
:在没有在插件清单中声明该 provider 的情况下实现 resolveExternalOAuthProfiles(...):在插件清单中声明 contracts.externalAuthProviders 并且实现 resolveExternalAuthProfiles(...)。旧的“auth 回退”路径会在运行时发出警告,并将在以后移除。
{
  "contracts": {
    "externalAuthProviders": ["anthropic", "openai"]
  }
}
清单字段:providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }:将同样的环境变量查找映射到清单中的 setup.providers[].envVars。 这样可以将 setup/status 的环境元数据集中在一个地方,并避免仅为回答环境变量查找而启动插件运行时。在弃用窗口结束之前,providerAuthEnvVars 仍通过兼容适配器受支持。
:三个单独调用—— api.registerMemoryPromptSection(...)api.registerMemoryFlushPlan(...)api.registerMemoryRuntime(...):在 memory-state API 上一次调用—— registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })位置相同,注册调用变为单次。增量 memory 辅助工具 (registerMemoryPromptSupplementregisterMemoryCorpusSupplementregisterMemoryEmbeddingProvider) 不受影响。
src/plugins/runtime/types.ts 仍导出两个旧类型别名:
SubagentReadSessionParamsSubagentGetSessionMessagesParams
SubagentReadSessionResultSubagentGetSessionMessagesResult
运行时方法 readSession 已弃用,建议改用 getSessionMessages。签名相同;旧方法会转调新方法。
runtime.tasks.flow(单数)返回一个活动 task-flow 访问器。runtime.tasks.managedFlows 为创建、更新、取消或运行子任务的插件保留受管理的 TaskFlow 变更运行时。仅当插件只需要基于 DTO 的读取时,请使用 runtime.tasks.flows
// 之前
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// 之后
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);
见上文“如何迁移 → 将 Pi 的 tool-result 扩展迁移到中间件”。此处仅为完整性重复说明: 已移除的仅 Pi 可用的 api.registerEmbeddedExtensionFactory(...) 路径,已由 api.registerAgentToolResultMiddleware(...) 替代,并在 contracts.agentToolResultMiddleware 中显式列出 runtime。
openclaw/plugin-sdk 重导出的 OpenClawSchemaType 现在只是 OpenClawConfig 的一行别名。请优先使用标准名称。
// 之前
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// 之后
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";
扩展级弃用项(位于 extensions/ 下捆绑通道/provider 插件内部)会在它们自己的 api.tsruntime-api.ts 总入口中跟踪。它们不影响第三方插件契约,也不会在这里列出。如果你直接消费某个捆绑插件的本地总入口,请先阅读该总入口中的弃用注释再升级。

移除时间线

时间会发生什么
现在已弃用的面会发出运行时警告
下一个大版本已弃用的面将被移除;仍在使用它们的插件会失败
所有核心插件都已经迁移完成。外部插件应在下一个大版本之前完成迁移。

临时抑制警告

在迁移期间设置以下环境变量:
OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
这只是临时逃生通道,不是永久解决方案。

相关