插件 SDK 迁移

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJjb21tYW5kLWF1dGggaGVscCBidWlsZGVycyAt command-status"> 旧（openclaw/plugin-sdk/command-auth）：buildCommandsMessage、 buildCommandsMessagePaginated、buildHelpMessage。

新（openclaw/plugin-sdk/command-status）：相同签名、相同 exports - 只是从更窄的子路径导入。command-auth 将它们作为兼容 stub 重新导出。

// Beforeimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // Afterimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLmj5Dlj4rpl6jmjqcgaGVscGVyIC0 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 事件模型 不使用此 helper。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJXZWIg5pCc57Si5o-Q5L6b5ZWGIHRvb2woKSBoZWxwZXIgLQ 插件上的 createTool()"> 旧：来自 openclaw/plugin-sdk/provider-web-search 的 tool() factory。

新：直接在提供商插件上实现 createTool(...)。 OpenClaw 不再需要 SDK helper 来注册工具 wrapper。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLnuq_mlofmnKzmuKDpgZMgZW52ZWxvcGUgLQ BodyForAgent"> 旧：使用 api.runtime.channel.reply.formatInboundEnvelope(...)（以及入口消息对象上的 channelEnvelope 字段）从入口渠道消息构建扁平的纯文本 prompt envelope。

新：BodyForAgent 加结构化用户上下文 block。渠道插件将路由元数据 （thread、topic、reply-to、reaction）作为类型化字段附加，而不是把它们拼接进 prompt 字符串。formatAgentEnvelope(...) helper 仍支持用于合成面向 assistant 的 envelope，但入口纯文本 envelope 正在退出。

受影响区域：inbound_claim、message_received，以及任何对旧 envelope 文本做后处理的自定义渠道插件。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJkZWFjdGl2YXRlIGhvb2sgLQ gateway_stop"> 旧：api.on("deactivate", handler)。

新：api.on("gateway_stop", handler)。相同的关闭清理 contract；只有 hook 名称改变。

// Beforeapi.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // Afterapi.on("gateway_stop", async (event, ctx) => {  await stopPluginService(ctx);});

deactivate 会继续作为已弃用的兼容性 alias 接线，直到 2026-08-16 之后移除。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJzdWJhZ2VudF9zcGF3bmluZyBob29rIC0 core thread binding"> 旧：api.on("subagent_spawning", handler) 返回 threadBindingReady 或 deliveryOrigin。

新：让 core 通过渠道会话绑定 adapter 准备 thread: true 子智能体绑定。 仅将 api.on("subagent_spawned", handler) 用于启动后的观察。

// Beforeapi.on("subagent_spawning", async () => ({  status: "ok",  threadBindingReady: true,  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },})); // Afterapi.on("subagent_spawned", async (event) => {  await observeSubagentLaunch(event);});

subagent_spawning、PluginHookSubagentSpawningEvent、 PluginHookSubagentSpawningResult 和 SubagentLifecycleHookRunner.runSubagentSpawning(...) 仅作为已弃用的兼容性表面保留， 供外部插件迁移，并会在 2026-08-30 之后移除。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJUaGlua2luZyBwb2xpY3kgaG9vayAt resolveThinkingProfile"> 旧（ProviderThinkingPolicy 上的三个独立 hook）： isBinaryThinking(ctx)、supportsXHighThinking(ctx) 和 resolveDefaultThinkingLevel(ctx)。

新：单个 resolveThinkingProfile(ctx)，返回一个 ProviderThinkingProfile，其中包含规范 id、可选 label 和排序后的 level 列表。 OpenClaw 会按 profile 排名自动降级过期的已存储值。

上下文包含 provider、modelId、可选合并后的 reasoning， 以及可选合并后的模型 compat facts。提供商插件可以使用这些 catalog facts，仅在配置的请求 contract 支持时暴露特定于模型的 profile。

实现一个 hook，而不是三个。旧版 hook 在弃用窗口期内会继续工作， 但不会与 profile 结果组合。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLlpJbpg6ggYXV0aCDmj5DkvpvllYYgLQ contracts.externalAuthProviders"> 旧：实现外部 auth hook，但未在插件清单中声明提供商。

新：在插件清单中声明 contracts.externalAuthProviders 并且实现 resolveExternalAuthProfiles(...)。

{  "contracts": {    "externalAuthProviders": ["anthropic", "openai"]  }}

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLmj5DkvpvllYYgZW52LXZhciDmn6Xmib4gLQ setup.providers[].envVars"> 旧清单字段：providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }。

新：将相同的 env-var 查找镜像到清单上的 setup.providers[].envVars。 这会把 setup/status 环境变量元数据整合到一处，并避免仅为回答 env-var 查找而启动插件运行时。

providerAuthEnvVars 会通过兼容性 adapter 继续支持， 直到弃用窗口关闭。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJNZW1vcnkg5o-S5Lu25rOo5YaMIC0 registerMemoryCapability"> 旧：三个独立调用 - api.registerMemoryPromptSection(...)、 api.registerMemoryFlushPlan(...)、api.registerMemoryRuntime(...)。

新：memory-state API 上的一个调用 - registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })。

相同 slot，单个注册调用。增量 prompt 和 corpus helper （registerMemoryPromptSupplement、registerMemoryCorpusSupplement） 不受影响。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJydW50aW1lLnRhc2tzLmZsb3cgLQ runtime.tasks.managedFlows"> 旧：runtime.tasks.flow（单数）返回 live task-flow accessor。

新：runtime.tasks.managedFlows 为从 flow 创建、更新、取消或运行子任务的插件保留受管理的 TaskFlow mutation 运行时。当插件只需要基于 DTO 的读取时，请使用 runtime.tasks.flows。

// Beforeconst flow = api.runtime.tasks.flow.fromToolContext(ctx);// Afterconst flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

2026-07-26 之后移除。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLltYzlhaXlvI8gZXh0ZW5zaW9uIGZhY3RvcnkgLQ agent tool-result middleware"> 已在上方的 如何迁移 中说明。为完整性在此列出： 已移除的仅限 embedded-runner 的 api.registerEmbeddedExtensionFactory(...) 路径由 api.registerAgentToolResultMiddleware(...) 替代，并在 contracts.agentToolResultMiddleware 中使用明确的运行时列表。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJPcGVuQ2xhd1NjaGVtYVR5cGUgYWxpYXMgLQ OpenClawConfig"> 从 openclaw/plugin-sdk 重新导出的 OpenClawSchemaType 现在是 OpenClawConfig 的单行 alias。请优先使用规范名称。

// Beforeimport type { OpenClawSchemaType } from "openclaw/plugin-sdk";// Afterimport type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";