插件 SDK 迁移

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

新版（openclaw/plugin-sdk/command-status）：签名和 导出均保持不变，只需从范围更精确的子路径导入。command-auth 将它们重新导出为兼容性存根。

// 之前import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // 之后import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLmj5Dlj4rpl6jmjqfovoXliqnlt6XlhbcgLQ resolveInboundMentionDecision"> 旧版：来自 openclaw/plugin-sdk/channel-inbound 或 openclaw/plugin-sdk/channel-mention-gating 的 resolveMentionGating(params) 和 resolveMentionGatingWithBypass(params)。

新版：resolveInboundMentionDecision({ facts, policy })——使用单个决策 对象，而非两个分离的调用形式。

Discord、iMessage、Matrix、MS Teams、QQ Bot、Signal、 Telegram、WhatsApp 和 Zalo 均已采用。Slack 自身的 app_mention 事件模型 不使用此辅助工具。

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

新版：直接在提供商插件上实现 createTool(...)。 OpenClaw 不再需要通过 SDK 辅助工具注册工具包装器。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLnuq_mlofmnKzmuKDpgZPkv6HlsIEgLQ BodyForAgent"> 旧版：使用 api.runtime.channel.reply.formatInboundEnvelope(...)（以及入站消息对象上的 channelEnvelope 字段）从入站渠道消息构建扁平的 纯文本提示词信封。

新版：使用 BodyForAgent 加结构化用户上下文块。渠道 插件将路由元数据（线程、主题、回复目标、表情回应）附加为 类型化字段，而非将它们拼接到提示词字符串中。formatAgentEnvelope(...) 辅助工具仍支持用于合成面向助手的信封，但入站纯文本信封正在逐步 淘汰。

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

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

新版：api.on("gateway_stop", handler)。关闭清理 契约不变；仅钩子名称发生变化。

// 之前api.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // 之后api.on("gateway_stop", async (event, ctx) => {  await stopPluginService(ctx);});

deactivate 在 2026-08-16 之后移除之前，仍作为已弃用的兼容性别名接入。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJzdWJhZ2VudF9zcGF3bmluZyDpkqnlrZAgLQ 核心线程绑定"> 旧版：api.on("subagent_spawning", handler) 返回 threadBindingReady 或 deliveryOrigin。

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

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

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

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

新版：使用单个 resolveThinkingProfile(ctx)，它返回 ProviderThinkingProfile，其中包含规范的 id、可选的 label 和一个 按优先级排列的级别列表。OpenClaw 会根据配置文件优先级自动 降级过期的已存储值。

上下文包含 provider、modelId、可选的合并 reasoning 以及可选的合并模型 compat 事实。仅当已配置的 请求契约支持时，提供商插件才能使用这些目录事实公开特定于模型的配置文件。

请实现一个钩子，而非三个。旧版钩子在 弃用期内仍然有效，但不会与配置文件结果组合。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLlpJbpg6jouqvku73pqozor4Hmj5DkvpvllYYgLQ contracts.externalAuthProviders"> 旧版：实现外部身份验证钩子，但未在插件清单中声明提供商。

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

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

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

新版：将相同的环境变量查找镜像到清单的 setup.providers[].envVars 中。这会将设置/状态环境元数据整合到一个位置， 并避免仅为响应环境变量查找而启动插件运行时。

在弃用期结束之前，providerAuthEnvVars 仍通过兼容性适配器 获得支持。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLorrDlv4bmj5Lku7bms6jlhowgLQ registerMemoryCapability"> 旧版：三个独立调用——api.registerMemoryPromptSection(...)、 api.registerMemoryFlushPlan(...)、api.registerMemoryRuntime(...)。

新版：在记忆状态 API 上执行一次调用—— registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })。

插槽相同，只需一次注册调用。增量提示词和语料库辅助工具 （registerMemoryPromptSupplement、registerMemoryCorpusSupplement）不受影响。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLljp_lp4vmuKDpgZPlj5HpgIHnu5PmnpwgLQ OutboundDeliveryResult"> 旧版：通过 ChannelSendRawResult 返回 { ok, messageId, error }， 并使用 createRawChannelSendResultAdapter(...) 将其规范化。

新版：返回 OutboundDeliveryResult 字段，并通过 createAttachedChannelResultAdapter(...) 附加渠道。发送失败时应抛出异常， 而非返回错误字符串。原始结果类型将在下一个插件 SDK 主要版本发布前 保持可用。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJydW50aW1lLnRhc2tzLmZsb3cgLQ runtime.tasks.managedFlows"> 旧版：runtime.tasks.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);

将于 2026-07-26 后移除。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLltYzlhaXlvI_mianlsZXlt6XljoIgLQ 智能体工具结果中间件"> 上文的如何迁移中已介绍。此处列出是为了 保持完整：已移除的仅限嵌入式运行器的 api.registerEmbeddedExtensionFactory(...) 路径，现由 api.registerAgentToolResultMiddleware(...) 替代，并在 contracts.agentToolResultMiddleware 中显式指定运行时列表。

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

// 之前import type { OpenClawSchemaType } from "openclaw/plugin-sdk";// 之后import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";