Миграция Plugin SDK

​

Что меняется

• openclaw/plugin-sdk/compat - единый импорт, который повторно экспортировал десятки вспомогательных функций. Он был введен, чтобы старые Plugin на основе хуков продолжали работать, пока создавалась новая Plugin архитектура.
• openclaw/plugin-sdk/infra-runtime - широкий runtime-barrel вспомогательных средств, который смешивал системные события, состояние Heartbeat, очереди доставки, вспомогательные средства fetch/proxy, файловые вспомогательные средства, типы утверждений и несвязанные утилиты.
• openclaw/plugin-sdk/config-runtime - широкий barrel совместимости конфигурации, который в период миграции все еще содержит устаревшие прямые вспомогательные средства загрузки/записи.
• openclaw/extension-api - мост, который давал Plugin прямой доступ к вспомогательным средствам на стороне хоста, например встроенному запускателю агента.
• api.registerEmbeddedExtensionFactory(...) - удаленный bundled-хук расширений только для embedded-runner, который мог наблюдать события embedded-runner, такие как tool_result.

​

Почему это изменилось

• Медленный запуск - импорт одной вспомогательной функции загружал десятки несвязанных модулей
• Циклические зависимости - широкие повторные экспорты упрощали создание циклов импортов
• Неясная поверхность API - нельзя было понять, какие экспорты стабильны, а какие внутренние

• Anthropic держит потоковые вспомогательные средства, специфичные для Claude, в собственной поверхности api.ts / contract-api.ts
• OpenAI держит builder-функции провайдера, вспомогательные средства моделей по умолчанию и builder-функции realtime-провайдера в собственном api.ts
• OpenRouter держит builder-функцию провайдера и вспомогательные средства onboarding/config в собственном api.ts

​

План миграции Talk и realtime-голоса

1. Держите общий контроллер/runtime-примитивы в plugin-sdk/realtime-voice.
2. Переведите bundled-поверхности на общий контроллер: browser relay, managed-room handoff, voice-call realtime, voice-call streaming STT, Google Meet realtime и native push-to-talk.
3. Замените старые семейства Talk RPC финальными API talk.session.* и talk.client.*.
4. Объявите один live-канал событий Talk в Gateway hello-ok.features.events: talk.event.
5. Удалите старый realtime HTTP endpoint и любой путь переопределения инструкций во время запроса.

// Gateway-owned Talk session 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 });

// Client-owned provider session 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" });

​

Политика совместимости

1. добавить новый контракт
2. сохранить старое поведение, подключенное через адаптер совместимости
3. вывести диагностическое сообщение или предупреждение, называющее старый путь и замену
4. покрыть оба пути тестами
5. задокументировать устаревание и путь миграции
6. удалить только после объявленного окна миграции, обычно в мажорном выпуске

​

Как выполнить миграцию

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

// OpenClaw and Codex runtime dynamic tools
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["openclaw", "codex"],
});

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

// Before
const program = applyWindowsSpawnProgramPolicy({ candidate });

// After
const program = applyWindowsSpawnProgramPolicy({
  candidate,
  // Only set this for trusted compatibility callers that intentionally
  // accept shell-mediated fallback.
  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/

// Before (deprecated backwards-compatibility layer)
import {
  createChannelReplyPipeline,
  createPluginRuntimeStore,
  resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";

// After (modern focused imports)
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/

​

Справочник путей импорта

​

Активные устаревания

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

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

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

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

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

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

// Before
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// After
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Before
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// After
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

​

График удаления

​

Временное подавление предупреждений

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

​

Связанные материалы

• Начало работы - создайте свой первый Plugin
• Обзор SDK - полный справочник импортов по подпутям
• Канальные Plugin - создание канальных Plugin
• Провайдерские Plugin - создание провайдерских Plugin
• Внутреннее устройство Plugin - подробный разбор архитектуры
• Манифест Plugin - справочник схемы манифеста