插件 SDK 迁移

​

变更内容

• openclaw/plugin-sdk 和 openclaw/plugin-sdk/compat - 在构建专用 SDK 的过程中重新导出了数十个辅助函数。现在这两个根入口都已移除；请改为导入 文档化的子路径。
• openclaw/plugin-sdk/infra-runtime - 一个宽泛的聚合模块，混合了系统 事件、心跳状态、投递队列、fetch/proxy 辅助函数、文件辅助函数、 审批类型以及其他无关工具。
• 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. 仅在已公布的迁移窗口结束后移除，通常是在主要版本中。

​

频道状态迁移声明

​

AuthStorage SQLite 迁移

​

已发布频道设置兼容性

​

频道设置输入字段兼容性

​

验证读取方

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 提供者发布

​

deactivate 钩子别名

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

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

​

私有测试 barrel

​

迁移参考

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

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

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

​

移除时间线

​

相关内容

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