Skip to main content
OpenClaw 用由小型、聚焦导入构建的现代插件架构,替换了宽泛的向后兼容层。如果你的插件早于这次变更,本指南会帮助它迁移到当前契约。

变更内容

过去,两个完全开放的导入表面允许插件从单个入口点访问几乎所有内容:
  • openclaw/plugin-sdk/compat - 重新导出了数十个辅助函数,以便在构建新架构期间让较旧的基于钩子的插件继续工作。
  • openclaw/plugin-sdk/infra-runtime - 一个宽泛的 barrel,混合了系统事件、心跳状态、投递队列、fetch/proxy 辅助函数、文件辅助函数、审批类型和无关工具。
  • openclaw/plugin-sdk/config-runtime - 一个宽泛的配置 barrel,在迁移窗口期间仍携带已弃用的直接加载/写入辅助函数。
  • openclaw/extension-api - 一个桥接层,让插件可以直接访问主机侧辅助函数,例如嵌入式智能体运行器。
  • api.registerEmbeddedExtensionFactory(...) - 一个已移除的仅限嵌入式运行器的钩子,用于观察嵌入式运行器事件,例如 tool_result。请改用智能体工具结果中间件(参见将嵌入式工具结果扩展迁移到中间件)。
这些表面已弃用:它们仍然可用,但新插件不得使用,现有插件也应在下一个主版本移除它们之前完成迁移。registerEmbeddedExtensionFactory 已经移除;旧版注册不再加载。
向后兼容层将在未来的主版本中移除。届时仍从这些表面导入的插件将会中断。
OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释已记录的插件行为。破坏性契约变更会先经过兼容适配器、诊断、文档和弃用窗口。这适用于 SDK 导入、清单字段、设置 API、钩子以及运行时注册行为。

原因

  • 启动缓慢 - 导入一个辅助函数会加载数十个无关模块。
  • 循环依赖 - 宽泛的重新导出很容易形成导入循环。
  • API 表面不清晰 - 无法区分稳定导出和内部导出。
现在,每个 openclaw/plugin-sdk/<subpath> 都是一个小型、自包含的模块,并带有明确记录的契约。 内置渠道的旧版提供商便捷接缝也已移除 - 带渠道品牌的辅助快捷方式只是私有单仓库便捷功能,不是稳定插件契约。请改用窄范围的通用 SDK 子路径。在内置插件工作区内,将提供商拥有的辅助函数保留在该插件自己的 api.tsruntime-api.ts 中:
  • Anthropic 将 Claude 专用流式传输辅助函数保留在自己的 api.ts / contract-api.ts 接缝中。
  • OpenAI 将提供商构建器、默认模型辅助函数和实时提供商构建器保留在自己的 api.ts 中。
  • OpenRouter 将提供商构建器和新手引导/配置辅助函数保留在自己的 api.ts 中。

兼容性策略

外部插件兼容性工作遵循以下顺序:
  1. 添加新契约。
  2. 通过兼容适配器继续接线旧行为。
  3. 发出诊断或警告,点明旧路径和替代方案。
  4. 在测试中覆盖两条路径。
  5. 记录弃用和迁移路径。
  6. 仅在宣布的迁移窗口结束后移除,通常是在主版本中。
如果某个清单字段仍被接受,请继续使用它,直到文档和诊断另有说明。新代码应优先使用已记录的替代方案;现有插件不应在普通次版本发布期间中断。 使用 pnpm plugins:boundary-report 审计当前迁移队列:
标志作用
--summary(或 pnpm plugins:boundary-report:summary使用紧凑计数而不是完整详情。
--json机器可读报告。
--owner <id>筛选到一个插件或兼容性所有者。
--fail-on-cross-owner遇到跨所有者的保留 SDK 导入时以非零状态退出。
--fail-on-eligible-compat当已弃用兼容性记录的 removeAfter 日期已过时以非零状态退出。
--fail-on-unclassified-unused-reserved遇到未使用且未分类的保留 SDK shim 时以非零状态退出。
pnpm plugins:boundary-report:ci 会启用全部三个失败标志。每条兼容性记录都有明确的 removeAfter 日期(不是模糊的“下一个主版本”)- 报告会按该日期分组已弃用记录,统计本地代码/文档引用,展示跨所有者保留 SDK 导入,并汇总私有 memory-host SDK 桥接。保留 SDK 子路径必须有被跟踪的所有者使用情况;未使用的保留导出应从公共 SDK 中移除。

如何迁移

1

迁移运行时配置加载/写入辅助函数

内置插件应停止直接调用 api.runtime.config.loadConfig()api.runtime.config.writeConfigFile(...)。优先使用已传入当前调用路径的配置。需要当前进程快照的长期存活处理器可以使用 api.runtime.config.current()。长期存活的智能体工具应在 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-api-usagepnpm check:no-runtime-action-load-config 保护:新的生产插件用法会直接失败,直接配置写入会失败,Gateway 网关服务器方法必须使用请求运行时快照,运行时渠道发送/action/client 辅助函数必须从其边界接收配置,长期存活的运行时模块不允许任何环境级 loadConfig() 调用。新插件代码应避免使用宽泛的 openclaw/plugin-sdk/config-runtime barrel。请为具体任务使用窄范围子路径:
需求导入
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
内置插件及其测试会通过扫描器防护,避免使用宽泛 barrel,从而让导入和 mock 保持在所需行为本地。该 barrel 仍为外部兼容性存在,但新代码不应依赖它。
2

将嵌入式工具结果扩展迁移到中间件

内置插件必须用运行时中立的中间件替换仅限嵌入式运行器的 api.registerEmbeddedExtensionFactory(...) 工具结果处理器:
// OpenClaw and Codex runtime dynamic tools
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["openclaw", "codex"],
});
同时更新插件清单:
{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "codex"]
  }
}
已安装插件也可以在显式启用且每个目标运行时都在 contracts.agentToolResultMiddleware 中声明时注册工具结果中间件。未声明的已安装中间件注册会被拒绝。
3

将审批原生处理器迁移到能力事实

支持审批的渠道插件通过 approvalCapability.nativeRuntime 加共享运行时上下文注册表暴露原生审批行为:
  • approvalCapability.handler.loadRuntime(...) 替换为 approvalCapability.nativeRuntime
  • 将审批专用的认证/投递从旧版 plugin.auth / plugin.approvals 接线迁移到 approvalCapability
  • ChannelPlugin.approvals 已从公共渠道插件契约中移除;请将投递/native/render 字段迁移到 approvalCapability
  • plugin.auth 仅保留用于渠道登录/登出流程;核心不再从那里读取审批认证钩子。
  • 通过 openclaw/plugin-sdk/channel-runtime-context 注册渠道拥有的运行时对象(客户端、令牌、Bolt 应用)。
  • 不要从原生审批处理器发送插件拥有的重路由通知;核心根据实际投递结果拥有已路由到其他位置的通知。
  • channelRuntime 传入 createChannelManager(...) 时,请提供真实的 createPluginRuntime().channel 表面 - 部分 stub 会被拒绝。
参见渠道插件,了解当前审批能力布局。
4

审计 Windows 包装器回退行为

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

// After
const program = applyWindowsSpawnProgramPolicy({
  candidate,
  // Only set this for trusted compatibility callers that intentionally
  // accept shell-mediated fallback.
  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

替换为聚焦导入

旧表面的每个导出都会映射到特定的现代导入路径:
// Before (deprecated backwards-compatibility layer)
import {
  createChannelReplyPipeline,
  createPluginRuntimeStore,
  resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";

// After (modern focused imports)
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";
对于主机侧辅助函数,请使用注入的插件运行时,而不是直接导入:
// Before (deprecated extension-api bridge)
import { runEmbeddedAgent } from "openclaw/extension-api";
const result = await runEmbeddedAgent({ sessionId, prompt });

// After (injected runtime)
const result = await api.runtime.agent.runEmbeddedAgent({ 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

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
感知调度器的 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

Migrate channel route helpers

新的渠道路由代码使用 openclaw/plugin-sdk/channel-route。旧的路由键和可比较目标名称仍作为兼容性别名保留:
旧辅助函数现代辅助函数
channelRouteIdentityKey(...)channelRouteDedupeKey(...)
channelRouteKey(...)channelRouteCompactKey(...)
ComparableChannelTargetChannelRouteParsedTarget
comparableChannelTargetsMatch(...)channelRouteTargetsMatchExact(...)
comparableChannelTargetsShareRoute(...)channelRouteTargetsShareConversation(...)
现代路由辅助函数会在原生审批、回复抑制、入站去重、cron 投递和会话路由中一致地规范化 { channel, to, accountId, threadId }不要新增对 ChannelMessagingAdapter.parseExplicitTarget、基于解析器的已加载路由辅助函数(parseExplicitTargetForLoadedChannelresolveRouteTargetForLoadedChannel)或来自 plugin-sdk/channel-routeresolveChannelRouteTargetWithParser(...) 的使用 - 这些都已弃用,仅为旧插件保留。新的渠道插件应使用 messaging.targetResolver.resolveTarget(...) 进行目标 ID 规范化和目录未命中回退;当核心需要早期对端类型时使用 messaging.inferTargetChatType(...);并使用 messaging.resolveOutboundSessionRoute(...) 处理提供商原生的会话和线程身份。
9

Build and test

pnpm build
pnpm test my-plugin/

导入路径参考

导入路径用途关键导出
plugin-sdk/plugin-entry规范插件入口辅助工具definePluginEntry
plugin-sdk/core渠道入口定义/构建器的旧版总括式重新导出defineChannelPluginEntry, createChatChannelPlugin
plugin-sdk/config-schema根配置架构导出OpenClawSchema
plugin-sdk/provider-entry单提供商入口辅助工具defineSingleProviderPluginEntry
plugin-sdk/channel-core聚焦的渠道入口定义和构建器defineChannelPluginEntry, defineSetupPluginEntry, createChatChannelPlugin, createChannelPluginBase
plugin-sdk/setup共享设置向导辅助工具设置翻译器、允许列表提示、设置状态构建器
plugin-sdk/setup-runtime设置时运行时辅助工具createSetupTranslator, 可安全导入的设置补丁适配器、查找说明辅助工具、promptResolvedAllowFrom, splitSetupEntries, 委派设置代理
plugin-sdk/setup-adapter-runtime已弃用的设置适配器别名使用 plugin-sdk/setup-runtime
plugin-sdk/setup-tools设置工具辅助工具formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_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-pairing私信配对基元createChannelPairingController
plugin-sdk/channel-reply-pipeline回复前缀、输入状态和来源投递接线createChannelReplyPipeline, resolveChannelSourceReplyDeliveryMode
plugin-sdk/channel-config-helpers配置适配器工厂和私信访问辅助工具createHybridChannelConfigAdapter, resolveChannelDmAccess, resolveChannelDmAllowFrom, resolveChannelDmPolicy, normalizeChannelDmPolicy, normalizeLegacyDmAliases
plugin-sdk/channel-config-schema配置架构构建器共享渠道配置架构基元和通用构建器
plugin-sdk/bundled-channel-config-schema内置配置架构仅限 OpenClaw 维护的内置插件;新插件必须定义插件本地架构
plugin-sdk/channel-config-schema-legacy已弃用的内置配置架构仅兼容性别名;对维护中的内置插件使用 plugin-sdk/bundled-channel-config-schema
plugin-sdk/telegram-command-configTelegram 命令配置辅助工具命令名称规范化、描述裁剪、重复/冲突验证
plugin-sdk/channel-policy群组/私信策略解析resolveChannelGroupRequireMention
plugin-sdk/channel-lifecycle已弃用的兼容性门面使用 plugin-sdk/channel-outbound
plugin-sdk/inbound-envelope入站信封辅助工具共享路由 + 信封构建器辅助工具
plugin-sdk/channel-inbound入站接收辅助工具上下文构建、格式化、根、运行器、预备回复分发和分发谓词
plugin-sdk/messaging-targets已弃用的目标解析导入路径使用 plugin-sdk/channel-targets 作为通用目标解析辅助工具,使用 plugin-sdk/channel-route 进行路由比较,并使用插件拥有的 messaging.targetResolver / messaging.resolveOutboundSessionRoute 进行提供商特定目标解析
plugin-sdk/outbound-media出站媒体辅助工具共享出站媒体加载
plugin-sdk/outbound-send-deps已弃用的兼容性门面使用 plugin-sdk/channel-outbound
plugin-sdk/channel-outbound出站消息生命周期辅助工具消息适配器、回执、持久发送辅助工具、实时预览/流式传输辅助工具、回复选项、生命周期辅助工具、出站身份和载荷规划
plugin-sdk/channel-streaming已弃用的兼容性门面使用 plugin-sdk/channel-outbound
plugin-sdk/outbound-runtime已弃用的兼容性门面使用 plugin-sdk/channel-outbound
plugin-sdk/thread-bindings-runtime线程绑定辅助工具线程绑定生命周期和适配器辅助工具
plugin-sdk/agent-media-payload旧版媒体载荷辅助工具旧版字段布局的 Agent 媒体载荷构建器
plugin-sdk/channel-runtime已弃用的兼容性垫片仅旧版渠道运行时工具
plugin-sdk/channel-send-result发送结果类型回复结果类型
plugin-sdk/runtime-store持久化插件存储createPluginRuntimeStore
plugin-sdk/runtime宽范围运行时辅助工具运行时/日志/备份/插件安装辅助工具
plugin-sdk/runtime-env窄范围运行时环境辅助工具日志记录器/运行时环境、超时、重试和退避辅助工具
plugin-sdk/plugin-runtime共享插件运行时辅助工具插件命令/钩子/http/交互式辅助工具
plugin-sdk/hook-runtime钩子流水线辅助工具共享 webhook/内部钩子流水线辅助工具
plugin-sdk/lazy-runtime惰性运行时辅助工具createLazyRuntimeModule, createLazyRuntimeMethod, createLazyRuntimeMethodBinder, createLazyRuntimeNamedExport, createLazyRuntimeSurface
plugin-sdk/process-runtime进程辅助工具共享 exec 辅助工具
plugin-sdk/cli-runtimeCLI 运行时辅助工具命令格式化、等待、版本辅助工具
plugin-sdk/gateway-runtimeGateway 网关辅助工具Gateway 网关客户端、事件循环就绪启动辅助工具、公布的 LAN 主机解析和渠道状态补丁辅助工具
plugin-sdk/config-runtime已弃用的配置兼容性垫片优先使用 config-contracts, plugin-config-runtime, runtime-config-snapshotconfig-mutation
plugin-sdk/telegram-command-configTelegram 命令辅助工具内置 Telegram 合同表面不可用时保持回退稳定的 Telegram 命令验证辅助工具
plugin-sdk/approval-runtime审批提示辅助工具Exec/插件审批载荷、审批能力/配置文件辅助工具、原生审批路由/运行时辅助工具,以及结构化审批显示路径格式化
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-sdk/channel-runtime-context渠道运行时上下文辅助工具通用渠道运行时上下文注册/get/watch 辅助工具
plugin-sdk/security-runtime安全辅助工具共享信任、私信门控、根边界文件/路径辅助工具、外部内容和密钥收集辅助工具
plugin-sdk/ssrf-policySSRF 策略辅助工具主机允许列表和私有网络策略辅助工具
plugin-sdk/ssrf-runtimeSSRF 运行时辅助工具固定分发器、受保护的 fetch、SSRF 策略辅助工具
plugin-sdk/system-event-runtime系统事件辅助工具enqueueSystemEvent, peekSystemEventEntries
plugin-sdk/heartbeat-runtimeHeartbeat 辅助工具Heartbeat 唤醒、事件和可见性辅助工具
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/exec-approvals-runtimeExec 审批策略辅助工具loadExecApprovals, resolveExecApprovalsFromFile, ExecApprovalsFile
plugin-sdk/collection-runtime有界缓存辅助工具pruneMapToMaxSize
plugin-sdk/diagnostic-runtime诊断门控辅助工具isDiagnosticFlagEnabled, isDiagnosticsEnabled
plugin-sdk/error-runtime错误格式化辅助工具formatUncaughtError, isApprovalNotFoundError, 错误图辅助工具
plugin-sdk/fetch-runtime包装 fetch/代理辅助工具resolveFetch, 代理辅助工具、EnvHttpProxyAgent 选项辅助工具
plugin-sdk/host-runtime主机规范化辅助工具normalizeHostname, normalizeScpRemoteHost
plugin-sdk/retry-runtime重试辅助工具RetryConfig, retryAsync, 策略运行器
plugin-sdk/allow-from允许列表格式化和输入映射formatAllowFromLowercase, 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共享回复运行时入站分发、Heartbeat、回复规划器、分块
plugin-sdk/reply-dispatch-runtime窄范围回复分发辅助工具完成、提供商分发和会话标签辅助工具
plugin-sdk/reply-history回复历史辅助工具createChannelHistoryWindow; 已弃用的 map-helper 兼容性导出,例如 buildPendingHistoryContextFromMap, recordPendingHistoryEntryclearHistoryEntriesIfEnabled
plugin-sdk/reply-reference回复引用规划createReplyReferencePlanner
plugin-sdk/reply-chunking回复分块辅助工具文本/markdown 分块辅助工具
plugin-sdk/session-store-runtime会话存储辅助工具存储路径 + 更新时间辅助工具
plugin-sdk/state-paths状态路径辅助工具状态和 OAuth 目录辅助工具
plugin-sdk/routing路由/会话键辅助函数resolveAgentRoutebuildAgentSessionKeyresolveDefaultAgentBoundAccountId、会话键规范化辅助函数
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日志辅助函数子系统日志记录器和脱敏辅助函数
plugin-sdk/markdown-table-runtimeMarkdown 表格辅助函数Markdown 表格模式辅助函数
plugin-sdk/reply-payload消息回复类型回复载荷类型
plugin-sdk/provider-setup精选本地/自托管提供商设置辅助函数自托管提供商发现/配置辅助函数
plugin-sdk/self-hosted-provider-setup聚焦 OpenAI 兼容自托管提供商设置辅助函数相同的自托管提供商发现/配置辅助函数
plugin-sdk/provider-auth-runtime提供商运行时认证辅助函数运行时 API key 解析辅助函数
plugin-sdk/provider-auth-api-key提供商 API key 设置辅助函数API key 新手引导/配置文件写入辅助函数
plugin-sdk/provider-auth-result提供商认证结果辅助函数标准 OAuth 认证结果构建器
plugin-sdk/provider-selection-runtime提供商选择辅助函数已配置或自动提供商选择,以及原始提供商配置合并
plugin-sdk/provider-env-vars提供商环境变量辅助函数提供商认证环境变量查找辅助函数
plugin-sdk/provider-model-shared共享提供商模型/重放辅助函数ProviderReplayFamilybuildProviderReplayFamilyHooksnormalizeModelCompat、共享重放策略构建器、提供商端点辅助函数,以及模型 ID 规范化辅助函数
plugin-sdk/provider-catalog-shared共享提供商目录辅助函数findCatalogTemplatebuildSingleProviderApiKeyCatalogbuildManifestModelProviderConfigsupportsNativeStreamingUsageCompatapplyProviderNativeStreamingUsageCompat
plugin-sdk/provider-onboard提供商新手引导补丁新手引导配置辅助函数
plugin-sdk/provider-http提供商 HTTP 辅助函数通用提供商 HTTP/端点能力辅助函数,包括音频转录 multipart 表单辅助函数
plugin-sdk/provider-web-fetch提供商 web-fetch 辅助函数Web-fetch 提供商注册/缓存辅助函数
plugin-sdk/provider-web-search-config-contract提供商 Web 搜索配置辅助函数面向不需要插件启用接线的提供商的窄 Web 搜索配置/凭据辅助函数
plugin-sdk/provider-web-search-contract提供商 Web 搜索契约辅助函数窄 Web 搜索配置/凭据契约辅助函数,例如 createWebSearchProviderContractFieldsenablePluginInConfigresolveProviderWebSearchPluginConfig,以及限定作用域的凭据设置器/获取器
plugin-sdk/provider-web-search提供商 Web 搜索辅助函数Web 搜索提供商注册/缓存/运行时辅助函数
plugin-sdk/provider-tools提供商工具/架构兼容辅助函数ProviderToolCompatFamilybuildProviderToolCompatFamilyHooks,以及 DeepSeek/Gemini/OpenAI 架构清理 + 诊断
plugin-sdk/provider-usage提供商用量辅助函数fetchClaudeUsagefetchGeminiUsagefetchGithubCopilotUsage,以及其他提供商用量辅助函数
plugin-sdk/provider-stream提供商流包装器辅助函数ProviderStreamFamilybuildProviderStreamFamilyHookscomposeProviderStreamWrappers、流包装器类型,以及共享 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助函数
plugin-sdk/provider-transport-runtime提供商传输辅助函数原生提供商传输辅助函数,例如受保护 fetch、工具结果文本提取、传输消息转换,以及可写传输事件流
plugin-sdk/keyed-async-queue有序异步队列KeyedAsyncQueue
plugin-sdk/media-runtime共享媒体辅助函数媒体获取/转换/存储辅助函数、基于 ffprobe 的视频尺寸探测,以及媒体载荷构建器
plugin-sdk/media-generation-runtime共享媒体生成辅助函数用于图像/视频/音乐生成的共享故障转移辅助函数、候选选择,以及缺失模型消息
plugin-sdk/media-understanding媒体理解辅助函数媒体理解提供商类型,以及面向提供商的图像/音频辅助函数导出
plugin-sdk/text-runtime已弃用的宽泛文本兼容性导出使用 string-coerce-runtimetext-chunkingtext-utility-runtimelogging-core
plugin-sdk/text-chunking文本分块辅助函数出站文本分块辅助函数
plugin-sdk/speech语音辅助函数语音提供商类型,以及面向提供商的指令、注册表、验证辅助函数和 OpenAI 兼容 TTS 构建器
plugin-sdk/speech-core共享语音核心语音提供商类型、注册表、指令、规范化
plugin-sdk/realtime-transcription实时转录辅助函数提供商类型、注册表辅助函数,以及共享 WebSocket 会话辅助函数
plugin-sdk/realtime-voice实时语音辅助函数提供商类型、注册表/解析辅助函数、桥接会话辅助函数、共享 Agent 回话队列、活动运行语音控制、转录稿/事件健康、回声抑制、咨询问题匹配、强制咨询协调、轮次上下文跟踪、输出活动跟踪,以及快速上下文咨询辅助函数
plugin-sdk/image-generation图像生成辅助函数图像生成提供商类型,以及图像资产/数据 URL 辅助函数和 OpenAI 兼容图像提供商构建器
plugin-sdk/image-generation-core共享图像生成核心图像生成类型、故障转移、认证和注册表辅助函数
plugin-sdk/music-generation音乐生成辅助函数音乐生成提供商/请求/结果类型
plugin-sdk/music-generation-core共享音乐生成核心音乐生成类型、故障转移辅助函数、提供商查找,以及模型引用解析
plugin-sdk/video-generation视频生成辅助函数视频生成提供商/请求/结果类型
plugin-sdk/video-generation-core共享视频生成核心视频生成类型、故障转移辅助函数、提供商查找,以及模型引用解析
plugin-sdk/interactive-runtime交互式回复辅助函数交互式回复载荷规范化/归约
plugin-sdk/channel-config-primitives渠道配置基元窄渠道配置架构基元
plugin-sdk/channel-config-writes渠道配置写入辅助函数渠道配置写入授权辅助函数
plugin-sdk/channel-plugin-common共享渠道前导共享渠道插件前导导出
plugin-sdk/channel-status渠道状态辅助函数共享渠道状态快照/摘要辅助函数
plugin-sdk/allowlist-config-edit允许列表配置辅助函数允许列表配置编辑/读取辅助函数
plugin-sdk/group-access群组访问辅助函数共享群组访问决策辅助函数
plugin-sdk/direct-dmplugin-sdk/direct-dm-access已弃用的兼容性门面使用 plugin-sdk/channel-inbound
plugin-sdk/direct-dm-guard-policyDirect-DM 保护辅助函数窄前加密保护策略辅助函数
plugin-sdk/extension-shared共享扩展辅助函数被动渠道/状态和环境代理辅助基元
plugin-sdk/webhook-targetsWebhook 目标辅助函数Webhook 目标注册表和路由安装辅助函数
plugin-sdk/webhook-path已弃用的 Webhook 路径别名使用 plugin-sdk/webhook-ingress
plugin-sdk/web-media共享 Web 媒体辅助函数远程/本地媒体加载辅助函数
plugin-sdk/zod已弃用的 Zod 兼容性再导出直接从 zod 导入 zod
plugin-sdk/memory-core内置 memory-core 辅助函数记忆管理器/配置/文件/CLI 辅助表面
plugin-sdk/memory-core-engine-runtime记忆引擎运行时门面记忆索引/搜索运行时门面
plugin-sdk/memory-core-host-embedding-registry记忆嵌入注册表轻量级记忆嵌入提供商注册表辅助函数
plugin-sdk/memory-core-host-engine-foundation记忆主机基础引擎记忆主机基础引擎导出
plugin-sdk/memory-core-host-engine-embeddings记忆主机嵌入引擎记忆嵌入契约、注册表访问、本地提供商,以及通用批处理/远程辅助函数;具体远程提供商位于其所属插件中
plugin-sdk/memory-core-host-engine-qmd记忆主机 QMD 引擎记忆主机 QMD 引擎导出
plugin-sdk/memory-core-host-engine-storage记忆主机存储引擎记忆主机存储引擎导出
plugin-sdk/memory-core-host-multimodal记忆主机多模态辅助函数记忆主机多模态辅助函数
plugin-sdk/memory-core-host-query记忆主机查询辅助函数记忆主机查询辅助函数
plugin-sdk/memory-core-host-secret记忆主机密钥辅助函数记忆主机密钥辅助函数
plugin-sdk/memory-core-host-events已弃用的记忆事件别名使用 plugin-sdk/memory-host-events
plugin-sdk/memory-core-host-status记忆主机状态辅助函数记忆主机状态辅助函数
plugin-sdk/memory-core-host-runtime-cli记忆主机 CLI 运行时记忆主机 CLI 运行时辅助函数
plugin-sdk/memory-core-host-runtime-core记忆主机核心运行时记忆主机核心运行时辅助函数
plugin-sdk/memory-core-host-runtime-files记忆主机文件/运行时辅助函数记忆主机文件/运行时辅助函数
plugin-sdk/memory-host-core记忆主机核心运行时别名面向厂商中立的记忆主机核心运行时辅助函数别名
plugin-sdk/memory-host-events记忆主机事件日志别名面向厂商中立的记忆主机事件日志辅助函数别名
plugin-sdk/memory-host-files已弃用的记忆文件/运行时别名使用 plugin-sdk/memory-core-host-runtime-files
plugin-sdk/memory-host-markdown托管 Markdown 辅助函数用于记忆相关插件的共享托管 Markdown 辅助函数
plugin-sdk/memory-host-search主动记忆搜索门面懒加载主动记忆搜索管理器运行时门面
plugin-sdk/memory-host-status已弃用的记忆主机状态别名使用 plugin-sdk/memory-core-host-status
plugin-sdk/testing测试实用工具仓库本地已弃用的兼容性桶形导出;使用聚焦的仓库本地测试子路径,例如 plugin-sdk/plugin-test-runtimeplugin-sdk/channel-test-helpersplugin-sdk/channel-target-testingplugin-sdk/test-envplugin-sdk/test-fixtures
此表是常见迁移子集,不是完整 SDK 表面。编译器入口点清单位于 scripts/lib/plugin-sdk-entrypoints.json;package exports 从公开子集生成。 预留的内置插件 helper seam 已从公共 SDK export map 中退役,但明确记录的兼容性 facade 除外,例如已弃用的 plugin-sdk/discord shim,它保留给仍直接导入已发布 @openclaw/discord 包的外部插件。所有者特定的 helper 位于所属插件包内;共享的宿主行为通过通用 SDK contract 移动,例如 plugin-sdk/gateway-runtimeplugin-sdk/security-runtimeplugin-sdk/plugin-config-runtime 使用与任务匹配的最窄 import。如果找不到某个 export,请查看 src/plugin-sdk/ 中的源码,或询问维护者应由哪个通用 contract 拥有它。

活跃弃用项

插件 SDK、提供商 contract、运行时表面和清单中的更窄弃用项。每项现在仍可工作,但会在未来的 major release 中移除。每个条目都会把旧 API 映射到它的规范替代项。
旧(openclaw/plugin-sdk/command-authbuildCommandsMessagebuildCommandsMessagePaginatedbuildHelpMessage新(openclaw/plugin-sdk/command-status:相同签名、相同 exports - 只是从更窄的子路径导入。command-auth 将它们作为兼容 stub 重新导出。
// Before
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// After
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";
:来自 openclaw/plugin-sdk/channel-inboundopenclaw/plugin-sdk/channel-mention-gatingresolveMentionGating(params)resolveMentionGatingWithBypass(params)resolveInboundMentionDecision({ facts, policy }) - 使用一个决策对象, 而不是两个拆分的调用形态。已在 Discord、iMessage、Matrix、MS Teams、QQBot、Signal、 Telegram、WhatsApp 和 Zalo 中采用。Slack 自己的 app_mention 事件模型 不使用此 helper。
openclaw/plugin-sdk/channel-runtime 是用于较旧渠道插件的兼容性 shim。 新代码不要导入它;请使用 openclaw/plugin-sdk/channel-runtime-context 注册运行时对象。openclaw/plugin-sdk/channel-actions 中的 channelActions* helper 与原始 “actions” 渠道 export 一起弃用。请改为通过语义化的 presentation 表面暴露能力 - 渠道插件声明它们渲染什么(card、button、select), 而不是声明它们接受哪些原始 action 名称。
:来自 openclaw/plugin-sdk/provider-web-searchtool() factory。:直接在提供商插件上实现 createTool(...)。 OpenClaw 不再需要 SDK helper 来注册工具 wrapper。
:使用 api.runtime.channel.reply.formatInboundEnvelope(...)(以及入口消息对象上的 channelEnvelope 字段)从入口渠道消息构建扁平的纯文本 prompt envelope。BodyForAgent 加结构化用户上下文 block。渠道插件将路由元数据 (thread、topic、reply-to、reaction)作为类型化字段附加,而不是把它们拼接进 prompt 字符串。formatAgentEnvelope(...) helper 仍支持用于合成面向 assistant 的 envelope,但入口纯文本 envelope 正在退出。受影响区域:inbound_claimmessage_received,以及任何对旧 envelope 文本做后处理的自定义渠道插件。
api.on("deactivate", handler)api.on("gateway_stop", handler)。相同的关闭清理 contract;只有 hook 名称改变。
// Before
api.on("deactivate", async (event, ctx) => {
  await stopPluginService(ctx);
});

// After
api.on("gateway_stop", async (event, ctx) => {
  await stopPluginService(ctx);
});
deactivate 会继续作为已弃用的兼容性 alias 接线,直到 2026-08-16 之后移除。
api.on("subagent_spawning", handler) 返回 threadBindingReadydeliveryOrigin:让 core 通过渠道会话绑定 adapter 准备 thread: true 子智能体绑定。 仅将 api.on("subagent_spawned", handler) 用于启动后的观察。
// Before
api.on("subagent_spawning", async () => ({
  status: "ok",
  threadBindingReady: true,
  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },
}));

// After
api.on("subagent_spawned", async (event) => {
  await observeSubagentLaunch(event);
});
subagent_spawningPluginHookSubagentSpawningEventPluginHookSubagentSpawningResultSubagentLifecycleHookRunner.runSubagentSpawning(...) 仅作为已弃用的兼容性表面保留, 供外部插件迁移,并会在 2026-08-30 之后移除。
四个 discovery type alias 现在是 catalog 时代类型的薄 wrapper:
旧 alias新类型
ProviderDiscoveryOrderProviderCatalogOrder
ProviderDiscoveryContextProviderCatalogContext
ProviderDiscoveryResultProviderCatalogResult
ProviderPluginDiscoveryProviderPluginCatalog
另外还有旧版 ProviderCapabilities 静态 bag - 提供商插件应使用明确的提供商 hook, 例如 buildReplayPolicynormalizeToolSchemaswrapStreamFn, 而不是静态对象。
ProviderThinkingPolicy 上的三个独立 hook): isBinaryThinking(ctx)supportsXHighThinking(ctx)resolveDefaultThinkingLevel(ctx):单个 resolveThinkingProfile(ctx),返回一个 ProviderThinkingProfile,其中包含规范 id、可选 label 和排序后的 level 列表。 OpenClaw 会按 profile 排名自动降级过期的已存储值。上下文包含 providermodelId、可选合并后的 reasoning, 以及可选合并后的模型 compat facts。提供商插件可以使用这些 catalog facts,仅在配置的请求 contract 支持时暴露特定于模型的 profile。实现一个 hook,而不是三个。旧版 hook 在弃用窗口期内会继续工作, 但不会与 profile 结果组合。
:实现外部 auth hook,但未在插件清单中声明提供商。:在插件清单中声明 contracts.externalAuthProviders 并且实现 resolveExternalAuthProfiles(...)
{
  "contracts": {
    "externalAuthProviders": ["anthropic", "openai"]
  }
}
清单字段:providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }:将相同的 env-var 查找镜像到清单上的 setup.providers[].envVars。 这会把 setup/status 环境变量元数据整合到一处,并避免仅为回答 env-var 查找而启动插件运行时。providerAuthEnvVars 会通过兼容性 adapter 继续支持, 直到弃用窗口关闭。
:三个独立调用 - api.registerMemoryPromptSection(...)api.registerMemoryFlushPlan(...)api.registerMemoryRuntime(...):memory-state API 上的一个调用 - registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })相同 slot,单个注册调用。增量 prompt 和 corpus helper (registerMemoryPromptSupplementregisterMemoryCorpusSupplement) 不受影响。
api.registerMemoryEmbeddingProvider(...)contracts.memoryEmbeddingProvidersapi.registerEmbeddingProvider(...)contracts.embeddingProviders通用 embedding 提供商 contract 可在 memory 之外复用, 是新提供商的受支持路径。memory 专用注册 API 仍作为已弃用的兼容性接线, 供现有提供商迁移。插件检查会将非内置用法报告为兼容性债务。
仍从 src/plugins/runtime/types.ts 导出的两个旧版 type alias:
SubagentReadSessionParamsSubagentGetSessionMessagesParams
SubagentReadSessionResultSubagentGetSessionMessagesResult
运行时方法 readSession 已弃用,请改用 getSessionMessages。相同签名;旧方法会调用新方法。
runtime.tasks.flow(单数)返回 live task-flow accessor。runtime.tasks.managedFlows 为从 flow 创建、更新、取消或运行子任务的插件保留受管理的 TaskFlow mutation 运行时。当插件只需要基于 DTO 的读取时,请使用 runtime.tasks.flows
// Before
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// After
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);
2026-07-26 之后移除。
已在上方的 如何迁移 中说明。为完整性在此列出: 已移除的仅限 embedded-runner 的 api.registerEmbeddedExtensionFactory(...) 路径由 api.registerAgentToolResultMiddleware(...) 替代,并在 contracts.agentToolResultMiddleware 中使用明确的运行时列表。
openclaw/plugin-sdk 重新导出的 OpenClawSchemaType 现在是 OpenClawConfig 的单行 alias。请优先使用规范名称。
// Before
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// After
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";
扩展级弃用项(位于 extensions/ 下的内置渠道/提供商插件内部)会在它们自己的 api.tsruntime-api.ts barrel 中跟踪。它们不会影响第三方插件契约,也不会在此列出。如果你直接使用内置插件的本地 barrel,请在升级前阅读该 barrel 中的弃用注释。

Talk 和实时语音迁移

实时语音、电话、会议和浏览器 Talk 代码共享一个由 openclaw/plugin-sdk/realtime-voice 导出的 Talk 会话控制器。该控制器负责通用 Talk 事件信封、活动轮次状态、采集状态、输出音频状态、近期事件历史,以及过期轮次拒绝。提供商插件负责特定厂商的实时会话;界面插件负责采集、播放、电话和会议相关的特殊处理。 所有内置界面都运行在共享控制器上:浏览器中继、托管房间移交、语音通话实时、语音通话流式 STT、Google Meet 实时,以及原生按住说话。Gateway 网关会在 hello-ok.features.events 中公布一个实时 Talk 事件渠道:talk.event 新代码不应直接调用 createTalkEventSequencer(...),除非是在实现低层适配器或测试夹具。请使用共享控制器,这样没有轮次 id 就无法发出轮次作用域事件,过期的 turnEnd / turnCancel 调用不会清除更新的活动轮次,并且输出音频生命周期事件能在电话、会议、浏览器中继、托管房间移交和原生 Talk 客户端之间保持一致。 公共 API 形状:
// Gateway-owned Talk session API.
await gateway.request("talk.session.create", {
  mode: "realtime",
  transport: "gateway-relay",
  brain: "agent-consult",
  sessionKey: "main",
});
await gateway.request("talk.session.appendAudio", { sessionId, audioBase64 });
await gateway.request("talk.session.cancelOutput", { sessionId, reason: "barge-in" });
await gateway.request("talk.session.submitToolResult", {
  sessionId,
  callId,
  result: { status: "working" },
  options: { willContinue: true },
});
await gateway.request("talk.session.submitToolResult", {
  sessionId,
  callId,
  result: { status: "already_delivered" },
  options: { suppressResponse: true },
});
await gateway.request("talk.session.submitToolResult", { sessionId, callId, result });
await gateway.request("talk.session.close", { sessionId });

// Client-owned provider session API.
await gateway.request("talk.client.create", {
  mode: "realtime",
  transport: "webrtc",
  brain: "agent-consult",
  sessionKey: "main",
});
await gateway.request("talk.client.toolCall", { sessionKey, callId, name, args });
await gateway.request("talk.client.steer", { sessionKey, text, mode: "steer" });
浏览器拥有的 WebRTC/提供商 websocket 会话使用 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 组合有意保持较少:
模式传输Brain所有者说明
realtimegateway-relayagent-consultGateway 网关通过 Gateway 网关桥接全双工提供商音频;工具调用通过 agent-consult 工具路由。
transcriptiongateway-relaynoneGateway 网关仅流式 STT;调用方发送输入音频并接收转录事件。
stt-ttsmanaged-roomagent-consult原生/客户端房间按住说话和对讲机式房间,其中客户端负责采集/播放,Gateway 网关负责轮次状态。
stt-ttsmanaged-roomdirect-tools原生/客户端房间面向受信任第一方界面的仅管理员房间模式,可直接执行 Gateway 网关工具操作。
供从较旧的 talk.realtime.* / talk.transcription.* / talk.handoff.* 系列迁移的读者使用的方法映射(这些系列均已移除):
talk.realtime.sessiontalk.client.create
talk.realtime.toolCalltalk.client.toolCall
talk.realtime.relayAudiotalk.session.appendAudio
talk.realtime.relayCanceltalk.session.cancelOutputtalk.session.cancelTurn
talk.realtime.relayToolResulttalk.session.submitToolResult
talk.realtime.relayStoptalk.session.close
talk.transcription.sessiontalk.session.create({ mode: "transcription" })
talk.transcription.relayAudiotalk.session.appendAudio
talk.transcription.relayCanceltalk.session.cancelTurn
talk.transcription.relayStoptalk.session.close
talk.handoff.createtalk.session.create({ transport: "managed-room" })
talk.handoff.jointalk.session.join
talk.handoff.revoketalk.session.close
统一控制词汇也刻意保持精简:
方法适用于契约
talk.session.appendAudiorealtime/gateway-relay, transcription/gateway-relay向同一个 Gateway 网关连接拥有的提供商会话追加一个 base64 PCM 音频块。
talk.session.startTurnstt-tts/managed-room启动一个托管房间用户轮次。
talk.session.endTurnstt-tts/managed-room在过期轮次校验后结束活动轮次。
talk.session.cancelTurn所有 Gateway 网关拥有的会话取消某个轮次的活动采集/提供商/智能体/TTS 工作。
talk.session.cancelOutputrealtime/gateway-relay停止助手音频输出,而不一定结束用户轮次。
talk.session.submitToolResultrealtime/gateway-relay完成中继发出的提供商工具调用;传入 options.willContinue 表示中间输出,或传入 options.suppressResponse 在不产生另一条助手响应的情况下满足该调用。
talk.session.steer由智能体支持的 Talk 会话向从 Talk 会话解析出的活动嵌入式运行发送口语化的 statussteercancelfollowup 控制。
talk.session.close所有统一会话停止中继会话或撤销托管房间状态,然后遗忘统一会话 id。
不要为了实现此功能而在核心中引入提供商或平台特殊情况。核心负责 Talk 会话语义。提供商插件负责厂商会话设置。语音通话和 Google Meet 负责电话/会议适配器。浏览器和原生应用负责设备采集/播放用户体验。

移除时间线

时间会发生什么
现在已弃用界面会发出运行时警告。
每条兼容记录的 removeAfter 日期该特定界面符合移除条件;日期过后,pnpm plugins:boundary-report --fail-on-eligible-compat 会让 CI 失败。
下一个主版本发布仍未迁移的任何界面都会被移除;仍在使用它们的插件将失败。
所有核心插件都已完成迁移。外部插件应在下一个主版本发布前迁移。运行 pnpm plugins:boundary-report,查看你的插件使用的界面中哪些兼容记录最早到期。

暂时抑制警告

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
这是临时逃生口,不是永久解决方案。

相关