Миграция Plugin SDK

OpenClaw перешел от широкого слоя обратной совместимости к современной Plugin архитектуре с узкими, документированными импортами. Если ваш Plugin был создан до новой архитектуры, это руководство поможет выполнить миграцию.

Что меняется

Старая система Plugin предоставляла две широкие поверхности, которые позволяли Plugin импортировать все необходимое из одной точки входа:

• 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.

Широкие поверхности импорта теперь устарели. Они все еще работают во время выполнения, но новые Plugin не должны их использовать, а существующим Plugin следует мигрировать до того, как следующий мажорный релиз удалит их. API регистрации фабрики расширений только для embedded-runner был удален; вместо него используйте middleware результатов инструментов.

OpenClaw не удаляет и не переинтерпретирует документированное поведение Plugin в том же изменении, которое вводит замену. Ломающие изменения контракта сначала должны пройти через адаптер совместимости, диагностику, документацию и окно устаревания. Это относится к импортам SDK, полям манифеста, setup API, хукам и поведению регистрации во время выполнения.

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

Старый подход создавал проблемы:

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

Современный plugin SDK исправляет это: каждый путь импорта (openclaw/plugin-sdk/\<subpath\>) представляет собой небольшой, самодостаточный модуль с понятным назначением и документированным контрактом.

Legacy-поверхности удобства провайдеров для bundled-каналов также удалены. Вспомогательные поверхности с брендингом каналов были приватными ярлыками mono-repo, а не стабильными контрактами Plugin. Используйте вместо них узкие универсальные подпути SDK. Внутри рабочей области bundled Plugin держите вспомогательные средства, принадлежащие провайдеру, в собственном api.ts или runtime-api.ts этого Plugin.

Текущие примеры bundled-провайдеров:

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

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

Код realtime-голоса, телефонии, встреч и браузерного Talk перемещается от локального для поверхности учета ходов к общему контроллеру Talk-сессии, экспортируемому из openclaw/plugin-sdk/realtime-voice. Новый контроллер владеет общей оболочкой событий Talk, состоянием активного хода, состоянием захвата, состоянием output-audio, недавней историей событий и отклонением устаревших ходов. Provider Plugin должны продолжать владеть realtime-сессиями конкретного вендора; surface Plugin должны продолжать владеть особенностями захвата, воспроизведения, телефонии и встреч.

Эта миграция Talk намеренно выполняется как чистое ломающие изменение:

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 и любой путь переопределения инструкций во время запроса.

Новый код не должен вызывать createTalkEventSequencer(...) напрямую, если только он не реализует низкоуровневый adapter или test fixture. Предпочитайте общий контроллер, чтобы события в области хода нельзя было отправить без turn id, устаревшие вызовы turnEnd / turnCancel не могли очистить более новый активный ход, а события жизненного цикла output-audio оставались согласованными в телефонии, встречах, browser relay, managed-room handoff и native Talk client.

Целевая форма публичного API:

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

WebRTC/provider-websocket сессии, которыми владеет браузер, используют talk.client.create, поскольку браузер владеет согласованием с провайдером и медиатранспортом, а Gateway владеет учетными данными, инструкциями и политикой инструментов. talk.session.* - это общая управляемая Gateway поверхность для gateway-relay realtime, gateway-relay transcription и managed-room native STT/TTS сессий.

Legacy-конфигурации, которые размещали realtime-селекторы рядом с talk.provider / talk.providers, следует исправить с помощью openclaw doctor --fix; runtime Talk не переинтерпретирует конфигурацию провайдера speech/TTS как конфигурацию realtime-провайдера.

Поддерживаемые комбинации talk.session.create намеренно ограничены:

Карта удаленных методов:

Единый словарь управления также намеренно узкий:

Не добавляйте в ядро особые случаи для провайдеров или платформ, чтобы это работало. Ядро владеет семантикой сеансов Talk. Provider plugins владеют настройкой сеансов поставщиков. Голосовые вызовы и Google Meet владеют адаптерами телефонии и встреч. Браузерные и нативные приложения владеют UX захвата и воспроизведения на устройстве.

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

Для внешних plugins работа над совместимостью выполняется в таком порядке:

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

Сопровождающие могут проверить текущую очередь миграции с помощью pnpm plugins:boundary-report. Используйте pnpm plugins:boundary-report:summary для компактных счетчиков, --owner <id> для одного Plugin или владельца совместимости и pnpm plugins:boundary-report:ci, когда CI-гейт должен падать из-за просроченных записей совместимости, межвладельческих зарезервированных импортов SDK или неиспользуемых зарезервированных подпутей SDK. Отчет группирует устаревшие записи совместимости по дате удаления, подсчитывает локальные ссылки в коде и документации, показывает межвладельческие зарезервированные импорты SDK и суммирует приватный мост SDK для хоста памяти, чтобы очистка совместимости оставалась явной, а не полагалась на разовые поиски. Зарезервированные подпути SDK должны иметь отслеживаемое использование владельцем; неиспользуемые экспортируемые зарезервированные вспомогательные функции следует удалять из публичного SDK.

Если поле манифеста все еще принимается, авторы plugins могут продолжать его использовать, пока документация и диагностика не скажут иного. Новый код должен предпочитать задокументированную замену, но существующие plugins не должны ломаться во время обычных минорных релизов.

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

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

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

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

// Beforeconst program = applyWindowsSpawnProgramPolicy({ candidate }); // Afterconst 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 buildpnpm test -- my-plugin/

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

Эта таблица намеренно содержит общий миграционный поднабор, а не всю поверхность SDK. Инвентаризация точек входа компилятора находится в scripts/lib/plugin-sdk-entrypoints.json; экспорты пакетов генерируются из публичного поднабора.

Зарезервированные вспомогательные стыки bundled-plugin были удалены из карты экспортов публичного SDK, за исключением явно документированных фасадов совместимости, таких как устаревший shim plugin-sdk/discord, сохраненный для опубликованного пакета @openclaw/discord@2026.3.13. Вспомогательные средства, специфичные для владельца, находятся внутри пакета Plugin-владельца; общее поведение хоста должно проходить через универсальные контракты SDK, такие как plugin-sdk/gateway-runtime, plugin-sdk/security-runtime и plugin-sdk/plugin-config-runtime.

Используйте самый узкий импорт, который соответствует задаче. Если вы не можете найти экспорт, проверьте исходный код в src/plugin-sdk/ или спросите сопровождающих, какому универсальному контракту он должен принадлежать.

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

Более узкие устаревания, которые применяются ко всему SDK Plugin, контракту провайдера, runtime-поверхности и манифесту. Каждое из них сегодня все еще работает, но будет удалено в будущей мажорной версии. Запись под каждым пунктом сопоставляет старый API с его канонической заменой.

// Beforeimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // Afterimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// Beforeapi.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // Afterapi.on("gateway_stop", async (event, ctx) => {  await stopPluginService(ctx);});

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

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

// Beforeconst flow = api.runtime.tasks.flow.fromToolContext(ctx);// Afterconst flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Beforeimport type { OpenClawSchemaType } from "openclaw/plugin-sdk";// Afterimport type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

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

Все основные Plugin уже перенесены. Внешним Plugin следует выполнить миграцию до следующего мажорного релиза.

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

Задайте эти переменные окружения, пока работаете над миграцией:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

Это временная аварийная мера, а не постоянное решение.

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

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