Миграция SDK плагина

​

Что изменилось

• openclaw/plugin-sdk/compat — повторно экспортировал десятки вспомогательных средств, чтобы старые плагины на основе перехватчиков продолжали работать во время создания новой архитектуры.
• openclaw/plugin-sdk/infra-runtime — широкий сводный модуль, объединявший системные события, состояние Heartbeat, очереди доставки, вспомогательные средства получения данных и прокси, средства работы с файлами, типы подтверждений и не связанные между собой утилиты.
• 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. Удалить только после завершения объявленного периода миграции, обычно в основном выпуске.

​

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

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

// Динамические инструменты среды выполнения OpenClaw и Codex
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["openclaw", "codex"],
});

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

// До
const program = applyWindowsSpawnProgramPolicy({ candidate });

// После
const program = applyWindowsSpawnProgramPolicy({
  candidate,
  // Устанавливайте только для доверенных вызывающих сторон совместимости, которые намеренно
  // допускают резервный вариант через командную оболочку.
  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/

​

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

​

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

// До
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-schema";

​

Миграция Talk и голосовой связи в реальном времени

// API сеанса Talk под управлением Gateway.
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 — полный справочник по импорту из подпутей
• Плагины каналов — создание плагинов каналов
• Плагины провайдеров — создание плагинов провайдеров
• Внутреннее устройство плагинов — подробный обзор архитектуры
• Манифест плагина — справочник по схеме манифеста