Міграція Plugin SDK

OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури Plugin із цільовими, задокументованими імпортами. Якщо ваш Plugin було створено до нової архітектури, цей посібник допоможе вам мігрувати.

Що змінюється

Стара система Plugin надавала дві широко відкриті поверхні, які давали змогу Plugin імпортувати все потрібне з однієї точки входу:

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

Широкі поверхні імпорту тепер застарілі. Вони досі працюють під час виконання, але нові Plugin не повинні їх використовувати, а наявні Plugin мають мігрувати до того, як наступний major-реліз їх видалить. API реєстрації фабрики розширення лише для embedded-runner було видалено; натомість використовуйте middleware для результатів інструментів.

OpenClaw не видаляє й не переінтерпретовує задокументовану поведінку Plugin у тій самій зміні, яка вводить заміну. Зміни контракту, що порушують сумісність, мають спершу пройти через адаптер сумісності, діагностику, документацію та вікно застарівання. Це стосується імпортів SDK, полів маніфесту, API налаштування, хуків і поведінки реєстрації під час виконання.

Чому це змінилося

Старий підхід створював проблеми:

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

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

Застарілі зручні шви provider для bundled каналів також видалено. Допоміжні шви з брендингом каналу були приватними скороченнями mono-repo, а не стабільними контрактами Plugin. Натомість використовуйте вузькі generic підшляхи SDK. Усередині bundled робочого простору Plugin тримайте допоміжні засоби, що належать provider, у власному api.ts або runtime-api.ts цього Plugin.

Поточні bundled приклади provider:

• Anthropic тримає допоміжні засоби потоків, специфічні для Claude, у власному шві api.ts / contract-api.ts
• OpenAI тримає builders provider, допоміжні засоби default-model і builders realtime provider у власному api.ts
• OpenRouter тримає builder provider і допоміжні засоби onboarding/config у власному api.ts

План міграції Talk і голосу реального часу

Код Talk для голосу реального часу, телефонії, зустрічей і браузера переходить від локального для поверхні обліку ходів до спільного контролера сесії Talk, який експортує openclaw/plugin-sdk/realtime-voice. Новий контролер володіє спільним envelope подій Talk, станом активного ходу, станом захоплення, станом вихідного аудіо, нещодавньою історією подій і відхиленням застарілих ходів. Plugin provider мають і далі володіти realtime-сесіями, специфічними для постачальника; 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. Замініть старі сімейства RPC Talk на фінальний API talk.session.* і talk.client.*.
4. Оголосіть один live-канал подій Talk у Gateway hello-ok.features.events: talk.event.
5. Видаліть старий realtime HTTP endpoint і будь-який шлях перевизначення інструкцій під час запиту.

Новий код не повинен викликати createTalkEventSequencer(...) напряму, якщо тільки він не реалізує низькорівневий adapter або тестову fixture. Віддавайте перевагу спільному контролеру, щоб події в межах ходу не могли бути emitted без id ходу, застарілі виклики turnEnd / turnCancel не могли очистити новіший активний хід, а події життєвого циклу вихідного аудіо лишалися узгодженими в телефонії, зустрічах, browser relay, managed-room handoff і native клієнтах Talk.

Цільова форма публічного 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, бо браузер володіє узгодженням provider і медіатранспортом, тоді як Gateway володіє credentials, інструкціями та політикою інструментів. talk.session.* є спільною керованою Gateway поверхнею для gateway-relay realtime, gateway-relay transcription і managed-room native STT/TTS сесій.

Застарілі конфігурації, які розміщували realtime selectors поруч із talk.provider / talk.providers, слід виправити за допомогою openclaw doctor --fix; runtime Talk не переінтерпретовує конфігурацію speech/TTS provider як конфігурацію realtime provider.

Підтримувані комбінації talk.session.create навмисно невеликі:

Мапа видалених методів:

Уніфікований контрольний словник також навмисно вузький:

Не додавайте в core спеціальні випадки для провайдерів або платформ, щоб це працювало. Core володіє семантикою сеансів Talk. Plugin провайдерів володіють налаштуванням сеансів постачальників. Голосові виклики та Google Meet володіють адаптерами телефонії/зустрічей. Браузерні й нативні застосунки володіють UX захоплення/відтворення пристроїв.

Політика сумісності

Для зовнішніх Plugin робота із сумісністю відбувається в такому порядку:

1. додати новий контракт
2. зберегти стару поведінку, підключену через адаптер сумісності
3. видати діагностику або попередження, що називає старий шлях і заміну
4. покрити обидва шляхи тестами
5. задокументувати застарівання та шлях міграції
6. видаляти лише після оголошеного вікна міграції, зазвичай у major-релізі

Мейнтейнери можуть перевірити поточну чергу міграції за допомогою pnpm plugins:boundary-report. Використовуйте pnpm plugins:boundary-report:summary для компактних підрахунків, --owner <id> для одного Plugin або власника сумісності, і pnpm plugins:boundary-report:ci, коли CI-гейт має падати через прострочені записи сумісності, міжвласницькі зарезервовані імпорти SDK або невикористані зарезервовані підшляхи SDK. Звіт групує застарілі записи сумісності за датою видалення, рахує локальні посилання в коді/документації, показує міжвласницькі зарезервовані імпорти SDK і підсумовує приватний міст SDK memory-host, щоб очищення сумісності залишалося явним, а не покладалося на ситуативні пошуки. Зарезервовані підшляхи SDK повинні мати відстежене використання власником; невикористані зарезервовані експорти helper слід видалити з публічного SDK.

Якщо поле маніфесту все ще приймається, автори Plugin можуть продовжувати його використовувати, доки документація й діагностика не скажуть інакше. Новий код має віддавати перевагу задокументованій заміні, але наявні Plugin не повинні ламатися під час звичайних minor-релізів.

Як мігрувати

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";

// Before (deprecated extension-api bridge)import { runEmbeddedAgent } from "openclaw/extension-api";const result = await runEmbeddedAgent({ sessionId, prompt }); // After (injected runtime)const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm buildpnpm test -- my-plugin/

Довідник шляхів імпорту

Ця таблиця навмисно є спільною підмножиною міграції, а не повною поверхнею SDK. Інвентар точок входу компілятора міститься в scripts/lib/plugin-sdk-entrypoints.json; експорти пакета генеруються з публічної підмножини.

Зарезервовані допоміжні шви bundled-плагінів вилучено з мапи експортів публічного SDK, за винятком явно задокументованих фасадів сумісності, як-от застарілої прокладки plugin-sdk/discord, збереженої для опублікованого пакета @openclaw/discord@2026.3.13. Допоміжні засоби, специфічні для власника, містяться всередині пакета плагіна-власника; спільна поведінка хоста має проходити через загальні контракти SDK, такі як plugin-sdk/gateway-runtime, plugin-sdk/security-runtime і plugin-sdk/plugin-config-runtime.

Використовуйте найвужчий імпорт, який відповідає завданню. Якщо не можете знайти експорт, перевірте джерело в src/plugin-sdk/ або запитайте супровідників, який загальний контракт має ним володіти.

Активні застаріння

Вужчі застаріння, що застосовуються в усьому SDK плагінів, контракті провайдера, 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 - довідник схеми маніфесту