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

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

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

Раньше две чрезмерно широкие поверхности импорта позволяли плагинам получать доступ почти к чему угодно через единую точку входа:

• openclaw/plugin-sdk/compat — повторно экспортировал десятки вспомогательных средств, чтобы старые плагины на основе перехватчиков продолжали работать во время создания новой архитектуры.
• openclaw/plugin-sdk/infra-runtime — широкий сводный модуль, объединявший системные события, состояние Heartbeat, очереди доставки, вспомогательные средства получения данных и прокси, средства работы с файлами, типы подтверждений и не связанные между собой утилиты.
• openclaw/plugin-sdk/config-runtime — широкий сводный модуль конфигурации, который в течение периода миграции всё ещё содержал устаревшие вспомогательные средства прямой загрузки и записи.
• openclaw/extension-api — мост, предоставлявший плагинам прямой доступ к вспомогательным средствам хоста, таким как встроенный механизм запуска агента.
• api.registerEmbeddedExtensionFactory(...) — удалённый перехватчик, предназначенный только для встроенного механизма запуска и отслеживавший его события, например tool_result. Вместо него используйте промежуточное ПО для результатов инструментов агента (см. Перенос расширений результатов инструментов встроенного механизма запуска в промежуточное ПО).

Эти поверхности устарели: они всё ещё работают, но новые плагины не должны их использовать, а существующие плагины следует перенести до следующего основного выпуска, в котором они будут удалены. registerEmbeddedExtensionFactory уже удалён; устаревшие регистрации больше не загружаются.

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

Причины

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

Теперь каждый openclaw/plugin-sdk/<subpath> представляет собой небольшой автономный модуль с документированным контрактом.

Устаревшие вспомогательные интерфейсы провайдеров для встроенных каналов также удалены — вспомогательные сокращения с названиями каналов были внутренним удобством монорепозитория, а не стабильными контрактами плагинов. Вместо них используйте узкие универсальные подпути SDK. Внутри рабочего пространства встроенного плагина храните принадлежащие провайдеру вспомогательные средства в собственном api.ts или runtime-api.ts этого плагина:

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

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

Работа по обеспечению совместимости внешних плагинов выполняется в следующем порядке:

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

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

Проверьте текущую очередь миграции с помощью pnpm plugins:boundary-report:

pnpm plugins:boundary-report:ci запускается со всеми тремя флагами ошибок. Каждая запись совместимости содержит явную дату removeAfter (а не расплывчатое указание «следующий основной выпуск») — отчёт группирует устаревшие записи по этой дате, подсчитывает локальные ссылки в коде и документации, выявляет импорты зарезервированного SDK между владельцами и суммирует сведения о закрытом мосте SDK хоста памяти. Зарезервированные подпути SDK должны иметь отслеживаемое использование владельцем; неиспользуемые зарезервированные экспорты следует удалить из публичного SDK.

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

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

// Динамические инструменты среды выполнения OpenClaw и Codexapi.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 buildpnpm test my-plugin/

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

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

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

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

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

Более узкие устаревания в SDK плагинов, контракте провайдера, поверхности среды выполнения и манифесте. Каждый из этих элементов по-прежнему работает, но будет удалён в одном из будущих мажорных выпусков. Для каждой записи указана каноническая замена старого 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-schema";

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

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

Все встроенные интерфейсы работают на общем контроллере: браузерная ретрансляция, передача управления в управляемую комнату, голосовой вызов в реальном времени, потоковое STT голосового вызова, Google Meet в реальном времени и нативный режим «нажми и говори». Gateway объявляет один активный канал событий Talk в hello-ok.features.events: talk.event.

Новый код не должен вызывать createTalkEventSequencer(...) напрямую, кроме случаев реализации низкоуровневого адаптера или тестовой фикстуры. Используйте общий контроллер, чтобы события, относящиеся к реплике, нельзя было отправлять без идентификатора реплики, устаревшие вызовы turnEnd / turnCancel не могли очистить более новую активную реплику, а события жизненного цикла выходного аудио оставались согласованными для телефонии, совещаний, браузерной ретрансляции, передачи управления в управляемую комнату и нативных клиентов Talk.

Форма публичного API:

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

Сеансы WebRTC/веб-сокетов провайдера под управлением браузера используют talk.client.create, поскольку браузер управляет согласованием с провайдером и транспортом мультимедиа, а Gateway управляет учётными данными, инструкциями и политикой инструментов. talk.session.* — общий интерфейс под управлением Gateway для работы в реальном времени через gateway-relay, транскрибирования через gateway-relay и нативных сеансов STT/TTS в управляемых комнатах.

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

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

Таблица соответствия методов для переходящих со старых семейств talk.realtime.* / talk.transcription.* / talk.handoff.* (все удалены):

Унифицированный набор управляющих операций также намеренно ограничен:

Не добавляйте в ядро особые случаи для провайдеров или платформ, чтобы обеспечить эту работу. Ядро управляет семантикой сеансов Talk. Плагины провайдеров управляют настройкой сеансов поставщиков. Voice-call и Google Meet управляют адаптерами телефонии и совещаний. Браузерные и нативные приложения управляют взаимодействием с пользователем при захвате и воспроизведении на устройстве.

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

Все плагины ядра уже перенесены. Внешние плагины следует перенести до следующего основного выпуска. Запустите pnpm plugins:boundary-report, чтобы узнать, для каких записей совместимости используемых вашим плагином поверхностей API срок наступит раньше всего.

Временное отключение предупреждений

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

Это временный обходной путь, а не постоянное решение.

См. также

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