插件 SDK 迁移

​

变更内容

• openclaw/plugin-sdk 和 openclaw/plugin-sdk/compat - 在构建聚焦式 SDK 期间重新导出了数十个辅助程序。现在这两个根入口均已移除；请改为导入有文档说明的子路径。
• openclaw/plugin-sdk/infra-runtime - 一个宽泛的桶式导出，混合了系统 事件、Heartbeat 状态、投递队列、fetch/代理辅助程序、文件辅助程序、 审批类型和不相关的实用程序。
• openclaw/plugin-sdk/config-runtime - 一个宽泛的配置桶式导出，仅为其 后续兼容窗口而保留；直接运行时加载/写入辅助程序已移除。
• openclaw/extension-api - 一个已移除的桥接层，曾允许插件直接 访问主机端辅助程序，例如嵌入式智能体运行器。
• api.registerEmbeddedExtensionFactory(...) - 一个已移除的、仅供嵌入式运行器使用的 钩子，曾观察 tool_result 等嵌入式运行器事件。请改用智能体 工具结果中间件（参阅将嵌入式工具结果扩展迁移到 中间件）。

​

原因

• 启动缓慢 - 导入一个辅助程序会加载数十个不相关的模块。
• 循环依赖 - 宽泛的重新导出很容易产生导入循环。
• API 表面不明确 - 无法区分稳定导出与内部导出。

• Anthropic 将 Claude 专用的流式辅助程序保留在自身的 api.ts / contract-api.ts 接口中。
• OpenAI 将提供商构建器、默认模型辅助程序和实时提供商 构建器保留在自身的 api.ts 中。
• OpenRouter 将提供商构建器及新手引导/配置辅助程序保留在自身的 api.ts 中。

​

兼容策略

1. 添加新契约。
2. 通过兼容适配器继续接入旧行为。
3. 发出诊断或警告，指出旧路径和替代路径。
4. 在测试中覆盖两条路径。
5. 记录弃用和迁移路径。
6. 仅在公布的迁移窗口结束后移除，通常是在一个主 版本中。

​

已发布渠道设置兼容性

​

渠道设置输入字段兼容性

​

验证读取方

1. 使用每个 nextCursor 对 https://clawhub.ai/api/v1/packages?family=code-plugin&limit=100 进行分页查询，并保留其 categories 包含 channels 的软件包。
2. 添加来自 npm search --json --searchlimit=1000 "openclaw channel plugin" 的 npm 候选项。通过在 GitHub 中搜索 openclaw/plugin-sdk/channel-setup、openclaw/plugin-sdk/setup 和 openclaw/plugin-sdk/core 的代码，添加仅有源代码的候选项。
3. 解析每个候选项的最新已发布版本。运行 npm pack <package>@<version> --json --pack-destination <temp-dir>，将其解包，并检查已发布的 dist JavaScript 和声明中是否存在直接或解构字段读取。如果软件包没有 npm 版本，请下载 ClawHub 工件。
4. 记录软件包、版本、字段或提升键以及匹配文件。只有在没有任何已发布插件工件读取某个字段或键时，才能删除它。确保保留字段和键列表旁代码注释中的读取方名称与扫描结果保持同步。

​

旧版媒体投影

import { toInboundMediaFacts } from "openclaw/plugin-sdk/channel-inbound";

const media = toInboundMediaFacts([
  { path: saved.path, url: nativeUrl, contentType: saved.contentType, messageId },
]);

const ctx = finalizeInboundContext({ Body: caption, media });

​

如何迁移

await api.runtime.config.mutateConfigFile({
  afterWrite: { mode: "auto" },
  mutate(draft) {
    draft.plugins ??= {};
  },
});

// OpenClaw 运行时工具和 Codex 运行时动态工具（结果可能会被
// 转换）。Codex 原生工具结果也会被转发以供观察，
// 但其转换后的输出绝不会传递给模型：Codex
// PostToolUse 钩子契约无法替换原生工具响应。
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["openclaw", "codex"],
});

{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "codex"]
  }
}

// 之前
const program = applyWindowsSpawnProgramPolicy({ candidate });

// 之后
const program = applyWindowsSpawnProgramPolicy({
  candidate,
  // 仅为有意接受经由 shell 回退的可信兼容性调用方
  // 设置此项。
  allowShellFallback: true,
});

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/

// 之前（已弃用的向后兼容层）
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 { runEmbeddedAgent } from "openclaw/extension-api";
const result = await runEmbeddedAgent({ sessionId, prompt });

// 之后（注入的运行时）
const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm build
pnpm test my-plugin/

​

导入路径参考

​

已移除的兼容性接口

​

进程全局 API 提供商发布

​

私有测试聚合入口

​

迁移参考

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

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

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

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

// 之前
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);
});

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

// 之前
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// 之后
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

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

​

Talk 和实时语音迁移

// Gateway 网关负责的 Talk 会话 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 });

// 客户端负责的提供商会话 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" });

​

移除时间线

​

暂时禁止显示警告

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

​

相关内容

• 入门指南 - 构建你的第一个插件
• SDK 概览 - 完整的子路径导入参考
• 渠道插件 - 构建渠道插件
• 提供商插件 - 构建提供商插件
• 插件内部机制 - 深入解析架构
• Plugin Manifest - 清单架构参考