已移除的界面
2026 年 7 月清理移除了哪些内容,以及针对已移除表面和后续窗口弃用项的逐 API 替代映射。属于 Plugin SDK 迁移 指南的一部分。
已移除的兼容性表面¶
2026 年 7 月的清理移除了根 SDK 和兼容桶文件、扩展 API 桥接、已过期的 SDK 子路径别名、未使用的 SDK 子路径,以及对仅限打包的 SDK 模块的带类型公共访问。私有本地构建映射仍保留给仓库所有者,生产私有 JavaScript 导出支持官方插件运行时。两者均不提供带类型的第三方 SDK 访问。
通道、配置和基础设施兼容性外观¶
channel-lifecycle、channel-message、channel-reply-pipeline、
config-runtime 和 infra-runtime 已于 2026 年 9 月 30 日经 SDK 所有者批准移除。通道导入迁移到聚焦的出站和入站契约;配置访问使用提供的配置、快照和变更辅助函数;基础设施导入迁移到对应的聚焦运行时或注入 API。系统事件快照检查和消费使用 system-event-runtime。
一些旧版辅助函数和命名类型需要调用方修改,而不是导入路径替换。参见 通道映射 和 配置与基础设施迁移步骤。
命令、Discord 和 Telegram 账户外观¶
command-auth、discord 和 telegram-account 已于 2026 年 10 月 2 日经 SDK 所有者明确批准移除。将发送者授权迁移到
channel-ingress-runtime,将原生命令辅助函数迁移到 command-auth-native,并将帮助构建器迁移到 command-status。Discord 和 Telegram 行为仍由其插件负责;外部插件应使用通用通道契约和注入的运行时辅助函数,仓库消费者应使用所属插件的 api.ts / runtime-api.ts 桶文件。
对于仍导入旧子路径的第三方插件(包括较早发布的 @openclaw/discord 包),这些是破坏性移除。在升级宿主之前,请先升级受影响的插件。并非每个导出都有仅路径替换;参见 逐表面映射。
追溯记录的已发布导出¶
以下导出已在 v2026.9.8 中发布,并在没有兼容性窗口的情况下被移除。它们的移除于 2026 年 10 月 7 日在引入已发布表面守卫时追溯记录;这些导出仍保持移除状态。注册表中的 removeAfter 是移除提交落地前一天的 UTC 日期,而不是提供给插件作者的兼容性窗口。
已移除的导出(openclaw/plugin-sdk/ 前缀) |
落地时间(UTC) | removeAfter |
替代方案 |
|---|---|---|---|
allow-from.mapBasicAllowlistResolutionEntries |
2026-10-05 | 2026-10-04 | 无;在消费插件中投影 BasicAllowlistResolutionEntry 字段。 |
computer-use.compileComputerUseValidator |
2026-10-05 | 2026-10-04 | 使用 typebox/compile 中的 Compile(schema).Check,并采用已导出的 Computer Use 模式。 |
extension-shared.runStoppablePassiveMonitor |
2026-10-05 | 2026-10-04 | 使用 channel-outbound.runPassiveAccountLifecycle,并传入 stop: (monitor) => monitor.stop()。 |
gateway-runtime.resolveAdvertisedLanHost |
2026-10-05 | 2026-10-04 | 无;通告的 LAN 主机发现由宿主负责。 |
json-store.readJsonFileWithFallback |
2026-10-05 | 2026-10-04 | 无;在插件中自行处理 JSON 工件解析、回退和文件存在性处理。 |
provider-auth.normalizeSecretInputModeInput |
2026-10-05 | 2026-10-04 | 无;将插件拥有的输入验证为已导出的 SecretInputMode 值 plaintext 或 ref。 |
persistent-dedupe.PersistentDedupeLegacyJsonMigrationOptions |
2026-10-05 | 2026-10-04 | 无;旧版 JSON 迁移已退役。 |
persistent-dedupe.PersistentDedupeLegacyJsonMigrationResult |
2026-10-05 | 2026-10-04 | 无;旧版 JSON 迁移已退役。 |
persistent-dedupe.listPersistentDedupeLegacyJsonFileEntries |
2026-10-05 | 2026-10-04 | 无;旧版 JSON 迁移已退役。 |
persistent-dedupe.migratePersistentDedupeLegacyJsonFile |
2026-10-05 | 2026-10-04 | 无;旧版 JSON 迁移已退役。运行时去重继续通过基于 SQLite 的 API 进行。 |
provider-auth.CachedCopilotToken |
2026-10-02 | 2026-10-01 | 提供商本地的 GitHub Copilot 认证 API;公共 SDK 中无对应项。 |
provider-auth.DEFAULT_COPILOT_API_BASE_URL |
2026-10-02 | 2026-10-01 | 提供商本地的 GitHub Copilot 认证 API;公共 SDK 中无对应项。 |
provider-auth.deriveCopilotApiBaseUrlFromToken |
2026-10-02 | 2026-10-01 | 提供商本地的 GitHub Copilot 认证 API;公共 SDK 中无对应项。 |
provider-auth.resolveCopilotApiToken |
2026-10-02 | 2026-10-01 | 提供商本地的 GitHub Copilot 认证 API;公共 SDK 中无对应项。 |
前六个导出在
2fec39f57319be5b6e0b20b5305665ed1ff5e685 中被移除。
四个旧版 JSON 迁移导出在
bd64d93ff1ae704d13813f6580c4809ba0e76606 中被移除。
四个 Copilot 导出及其较早的弃用条目在
f2de06b38de710854aacd19218327358445816c8 中被移除;
第三方插件必须自行负责其提供商特定的 Token 交换和缓存。
进程级 API 提供者发布¶
registerApiProvider(...) 和 unregisterApiProviders(...) 已从
openclaw/plugin-sdk/llm 中移除。它们将 API 传输发布到进程级全局状态,
随后由生命周期管理的模型运行时复制到每个已准备的注册表中。
提供者插件应通过 api.registerProvider(...) 注册文本推理提供者。
宿主拥有的代码和测试如果构造 ApiRegistry,应直接在该注册表上注册,
以便提供者所有权和清理保持限定在已准备的运行时范围内。
Deactivate 钩子别名¶
api.on("deactivate", handler) 兼容性别名已移除。请使用 gateway_stop
注册相同的关闭清理:
// Before
api.on("deactivate", async (event, ctx) => {
await stopPluginService(ctx);
});
// After
api.on("gateway_stop", async (event, ctx) => {
await stopPluginService(ctx);
});
Skill Workshop 提案钩子¶
skill_proposal_evaluate 和 skill_proposal_changed 钩子已随
Skill Workshop 提案一起移除。Workshop 现在会立即应用每次更改并保留可恢复的版本,
因此没有待评估的草稿,也没有可观察的提案生命周期。钩子运行器方法
runSkillProposalEvaluate 和 runSkillProposalChanged 已移除,并且
openclaw/plugin-sdk/plugin-entry 不再导出
PluginHookSkillProposalEvaluateEvent、PluginHookSkillProposalEvaluateResult、
PluginHookSkillProposalEvaluationOutcome、PluginHookSkillProposalChangedEvent、
PluginHookSkillProposalKind、PluginHookSkillEvaluationFinding、
PluginHookSkillBundleFile 或 PluginHookSkillBundleSnapshot。
PluginHookSkillChangedEvent 上的可选 proposal 字段也已移除。
若要观察已提交的 Workshop 技能写入,请注册 skill_changed 并按
source: "workshop" 过滤。预应用评估没有替代方案。
注册已移除的钩子名称会记录 unknown typed hook 警告,并且处理程序永远不会运行。
私有测试桶¶
openclaw/plugin-sdk/testing 是仓库本地的,并且被排除在已发布的包产物之外,
因此它在 2026-07-28 的 removeAfter 日期之前被移除。仓库测试使用更聚焦的子路径,
例如 plugin-sdk/plugin-test-runtime、plugin-sdk/channel-test-helpers、
plugin-sdk/channel-target-testing、plugin-sdk/test-env 和
plugin-sdk/test-fixtures。
凭据提示构建器¶
buildCredentialSafetyPrompt 仍可从 openclaw/plugin-sdk/agent-harness-runtime
获取。当传入一个选项对象,且其 controlToolsAvailable 由可调用的 openclaw
和 gateway 工具设置时,它会返回指导:按请求使用或存储用户共享的凭据,
完成任务,并在最终回复中简要确认其使用或存储,而不重复其值。
该确认保持事实性且不引起恐慌。当两个控制工具都不可用时,它还会返回
私有登录码交接指导和终端设置路径。
旧版字符串参数自 2026-09-09 起已弃用,并支持至 2026-11-30。
它会被接受并忽略:由于可用性未知,辅助函数只返回私有交接行。
请将字符串替换为 { controlToolsAvailable };字符串形式自 2026-12-01 起
符合移除条件。辅助函数本身未弃用。
迁移参考¶
这些映射同时涵盖 2026 年 7 月已移除的 API 表面和后续窗口中仍活跃的弃用项。 映射是迁移指导,而不是旧表面仍可用的证据;请查阅兼容性注册表和移除时间线 以了解当前状态。
true
command-status">
旧(openclaw/plugin-sdk/command-auth):buildCommandsMessage、
buildCommandsMessagePaginated、buildHelpMessage。
新(openclaw/plugin-sdk/command-status):签名相同,从更窄的子路径导入。
command-auth 兼容性再导出已移除。
true
resolveInboundMentionDecision">
旧:来自 openclaw/plugin-sdk/channel-inbound 或
openclaw/plugin-sdk/channel-mention-gating 的
resolveMentionGating(params) 和 resolveMentionGatingWithBypass(params)。
新:resolveInboundMentionDecision({ facts, policy })——使用一个决策对象,
而不是两种拆分的调用形式。
已在 Discord、iMessage、Matrix、MS Teams、QQBot、Signal、Telegram、
WhatsApp 和 Zalo 中采用。Slack 自身的 app_mention 事件模型不使用此辅助函数。
通道运行时垫片和通道操作辅助函数
openclaw/plugin-sdk/channel-runtime 已移除。使用
openclaw/plugin-sdk/channel-runtime-context 来注册运行时对象。
openclaw/plugin-sdk/channel-actions 中的原生消息架构辅助函数已随原始
“actions” 通道导出一起移除。请改为通过语义化的 presentation 表面暴露能力——
通道插件声明它们渲染的内容(卡片、按钮、选择器),而不是声明它们接受哪些原始
操作名称。
true
createTool() on the plugin">
旧:来自 openclaw/plugin-sdk/provider-web-search 的 tool() 工厂。
新:直接在提供者插件上实现 createTool(...)。
OpenClaw 不再需要 SDK 辅助函数来注册工具包装器。
true
BodyForAgent">
旧:api.runtime.channel.reply.formatInboundEnvelope(...)(以及入站消息对象上的
channelEnvelope 字段)用于从入站通道消息构建扁平的纯文本提示信封。
新:BodyForAgent 加上结构化的用户上下文块。通道插件将路由元数据
(thread、topic、reply-to、reactions)作为类型化字段附加,而不是将它们拼接成
提示字符串。formatAgentEnvelope(...) 辅助函数仍支持用于合成的面向助手的信封,
但入站纯文本信封正在逐步移除。
受影响区域:inbound_claim、message_received,以及任何对旧信封文本进行后处理的自定义渠道插件。
true
核心线程绑定">
旧:api.on("subagent_spawning", handler) 返回
threadBindingReady 或 deliveryOrigin。
新:让核心通过渠道会话绑定适配器准备 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_spawning 钩子及其事件/结果类型在 2026 年 8 月线程绑定迁移到核心会话绑定路径后被移除。
true
提供程序目录类型"> 四个发现类型别名现在是目录时代类型的薄封装:
| 旧别名 | 新类型 |
|---|---|
ProviderDiscoveryOrder |
ProviderCatalogOrder |
ProviderDiscoveryContext |
ProviderCatalogContext |
ProviderDiscoveryResult |
ProviderCatalogResult |
ProviderPluginDiscovery |
ProviderPluginCatalog |
这些别名和旧版 ProviderCapabilities 静态对象已被移除。提供程序插件
应使用显式提供程序钩子,例如 buildReplayPolicy、
normalizeToolSchemas 和 wrapStreamFn,而不是静态对象。
true
resolveThinkingProfile">
旧(ProviderThinkingPolicy 上的三个独立钩子):
isBinaryThinking(ctx)、supportsXHighThinking(ctx) 和
resolveDefaultThinkingLevel(ctx)。
新:单个 resolveThinkingProfile(ctx),返回
ProviderThinkingProfile,其中包含规范的 id、可选的 label 以及一个
按排名排列的级别列表。OpenClaw 会根据配置资料排名自动降级过时的存储值。
上下文包含 provider、modelId、可选的合并 reasoning,
以及可选的合并模型 compat 事实。提供程序插件可以使用这些
目录事实,仅在已配置请求契约支持时暴露特定模型的配置资料。
实现一个钩子而不是三个。旧版钩子已被移除。
true
contracts.externalAuthProviders"> 旧:实现外部身份验证钩子,但未在插件清单中声明提供程序。
新:在插件清单中声明 contracts.externalAuthProviders,
并实现 resolveExternalAuthProfiles(...)。
true
setup.providers[].envVars">
旧清单字段:providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }。
新:将相同的环境变量查找镜像到清单上的 setup.providers[].envVars。
这会将设置/状态环境变量元数据集中在一处,
避免仅为回答环境变量查找而启动插件运行时。
providerAuthEnvVars 不再被接受。
true
registerMemoryCapability">
旧:三个独立调用 - api.registerMemoryPromptSection(...)、
api.registerMemoryFlushPlan(...)、api.registerMemoryRuntime(...)。
新:内存状态 API 上的一个调用 -
registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })。
相同的插槽,单个注册调用。附加的提示和语料库辅助函数
(registerMemoryPromptSupplement、registerMemoryCorpusSupplement)
不受影响。
内存嵌入提供程序 API
旧:api.registerMemoryEmbeddingProvider(...) 加上
contracts.memoryEmbeddingProviders。
新:api.registerEmbeddingProvider(...) 加上
contracts.embeddingProviders。
通用嵌入提供程序契约可在内存之外复用,并且是每个提供程序的支持路径。特定于内存的注册 API 和清单契约在 2026-08-21 迁移截止日期后被移除。
true
OutboundDeliveryResult">
旧:通过 ChannelSendRawResult 返回 { ok, messageId, error },
并使用 createRawChannelSendResultAdapter(...) 对其进行规范化。
新:返回 OutboundDeliveryResult 字段,并使用
createAttachedChannelResultAdapter(...) 附加渠道。发送失败时应抛出异常,
而不是返回错误字符串。将平台目标放在
target: { kind: "chat" | "channel" | "room" | "conversation", id } 中;
旧的并行 chatId、channelId、roomId 和 conversationId
结果字段不再被接受。原始结果类型将在下一个 plugin-SDK 主要版本发布前保持可用。
子代理会话消息类型已重命名
两个旧类型别名仍从 src/plugins/runtime/types.ts 导出:
| 旧 | 新 |
|---|---|
SubagentReadSessionParams |
SubagentGetSessionMessagesParams |
SubagentReadSessionResult |
SubagentGetSessionMessagesResult |
运行时方法 readSession 已弃用,建议使用
getSessionMessages。签名相同;旧方法会调用到
新方法。
已移除会话和转录文件 API
SQLite 会话/转录切换会移除或弃用面向插件的 API,
这些 API 曾暴露活动的 sessions.json 存储、JSONL 转录路径或
会话文件列表。运行时插件应使用会话标识和 SDK 运行时
辅助函数,而不是解析或修改活动文件。
| 迁移项 | 替代方案 |
|---|---|
已移除 loadSessionStore(...) 和 resolveSessionStoreEntry(...),包括包根目录的 loadSessionStore(...) |
使用 openclaw/plugin-sdk/session-store-runtime 中的 getSessionEntry(...) 获取单个作用域行,或使用 listSessionEntries(...) 进行作用域迭代。 |
已移除 updateSessionStore(...)、包根目录的 saveSessionStore(...) 以及 SDK 文件存储写入 |
使用 openclaw/plugin-sdk/session-store-runtime 中的 patchSessionEntry(...)、upsertSessionEntry(...) 和 deleteSessionEntry(...);仅修改目标行,而不是替换一个脱离的整个存储快照。 |
已移除 LoadSessionStoreOptions 和 UpdateSessionStoreOptions |
作用域行 API 接受的参数;整个存储缓存和回调选项不再适用。 |
已移除 resolveSessionFilePath(...) |
使用 openclaw/plugin-sdk/session-transcript-runtime 的会话标识(agentId、sessionKey 和 sessionId),或操作当前会话的 Gateway 方法。 |
已移除 resolveSessionTranscriptPathInDir(...) 和 resolveAndPersistSessionFile(...) |
会话标识以及操作当前会话的 Gateway 方法。 |
readLatestAssistantTextFromSessionTranscript(...) |
当前运行时上下文暴露的基于标识的转录读取器,或者当插件位于转录所有者路径之外时,使用 Gateway 历史/会话方法。 |
SessionTranscriptUpdate.sessionFile |
带有 agentId、sessionKey 和 sessionId 的 SessionTranscriptUpdate.target。 |
内存同步输入,例如 sessionFiles |
由主机提供的基于标识的转录/会话源;不要为活动会话爬取活动 JSONL 文件。 |
用于活动会话的名为 transcriptPath 或 sessionFile 的运行时选项 |
携带存储中立会话标识的 sessionTarget/运行时目标对象。 |
传统 JSONL 转录文件仍可作为导入、归档、导出和支持工件使用。它们不再是活动会话的稳态运行时契约。
随 `v2026.7.1-beta.5` 发布的官方 `@openclaw/codex` 和 `@openclaw/feishu` 插件导入了已退役的桥接。SDK 所有者于 2026 年 9 月 30 日的批准提前结束了其兼容窗口,取代了原先 10 月 12 日的截止日期。受支持插件的截止日期排除了该版本以及任何仍在导入该桥接的其他包。在升级 OpenClaw 之前,请将受影响的插件升级到使用替代方案的版本。仅版本号更新本身并不能证明已完成迁移。
`openclaw/plugin-sdk/session-store-runtime` 和 `resolveStorePath(...)` 仍受支持。请将选定的 `agentId` 显式传递给作用域行操作;解析路径不再为后续的整个存储调用记录代理选择。此移除不会更改 SQLite 架构或遗留状态导入和 Doctor 迁移。
`openclaw plugins inspect --all --runtime` 会报告其加载错误或诊断信息仍引用这些已移除文件 API 的非捆绑插件。`@openclaw/plugin-inspector` 建议扫描必须使用 `0.3.17` 或更高版本,以便外部包扫描在发布前也能标记整个存储会话辅助函数、会话文件路径辅助函数、遗留转录文件目标和低级转录辅助函数。
true
V2 主机能力契约">
新建或更新的 harness 插件应实现 AgentHarnessV2,并使用
AgentHarnessAttemptParamsV2、EmbeddedRunAttemptParamsV2 或
AgentHarnessSideQuestionParamsV2。V2 参数类型要求
hostCapabilities,与核心在所选 harness 边界处提供的内容相匹配。采用这些 V2 契约的插件必须在其包
清单中声明 openclaw.compat.pluginApi: ">=2026.8.1"(或更高的下限),以便较旧的主机在加载插件前拒绝该插件。
现有插件可以继续实现 AgentHarness,并在 2026-10-12 之前构造不带该字段的遗留
AgentHarnessAttemptParams、EmbeddedRunAttemptParams 或
AgentHarnessSideQuestionParams 类型。这些契约仅为源码兼容性保留该能力的可选性;它们不会创建无能力的运行时路径。通过
更改导入的类型名称,并通过 params.hostCapabilities 绑定工具或原生操作表面来迁移。
Tasks and TaskFlow APIs removed
Tasks 注册表和 TaskFlow 编排 API 已移除,
包括 api.runtime.tasks、registerDetachedTaskRuntime 以及
agent-harness-task-runtime SDK 子路径。不再保留兼容门面。
使用原生子代理启动/等待/历史 API、cron 运行历史以及普通 Lobster runner 来执行相应操作。Harness 完成
路由使用仅完成的 agent-harness-completion 子路径。
此移除不会更改物理数据库架构。现有
task_runs、task_delivery_state 和 flow_runs 表、列和索引
保持不变。Cron 只读取和写入 task_runs 中其 runtime = 'cron' 历史
行;非 Cron Task 和 TaskFlow 行保持不变,且运行时不使用它们。Codex 插件的
Doctor 迁移
在现有父绑定元数据中保留符合条件的、带有所有者标记的原生恢复事实,使源行保持逐字节一致。它不添加运行时 Task
读取器或替代 SDK 表面;当前请求者权限仍控制完成投递。参见版本化契约。
true
agent 工具结果中间件">
已在如何迁移中涵盖。此处包含以求完整:已移除的仅限嵌入式 runner 的
api.registerEmbeddedExtensionFactory(...) 路径由
api.registerAgentToolResultMiddleware(...) 替代,并在 contracts.agentToolResultMiddleware 中带有显式运行时列表。
true
OpenClawConfig">
OpenClawSchemaType 根 SDK 别名已移除。请使用规范的
OpenClawConfig 名称。
Note
扩展级别的弃用项(位于 extensions/ 下的捆绑 channel/provider 插件内部)
在其各自的 api.ts 和 runtime-api.ts barrel 中跟踪。它们不影响第三方插件契约,
也不在此处列出。如果你直接使用某个捆绑插件的本地 barrel,请在升级前阅读该
barrel 中的弃用注释。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw