Міграція Plugin SDK

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

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

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

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

Широкі поверхні імпорту тепер застарілі. Вони досі працюють у runtime, але нові plugin не повинні їх використовувати, а наявні plugin мають виконати міграцію до того, як наступний major release їх видалить. API реєстрації embedded extension factory лише для Pi було видалено; натомість використовуйте middleware для tool-result.

OpenClaw не видаляє і не переінтерпретовує задокументовану поведінку plugin у тій самій зміні, яка запроваджує заміну. Зміни контракту, що порушують сумісність, спочатку мають пройти через адаптер сумісності, діагностику, документацію та вікно застарівання. Це стосується імпортів SDK, полів manifest, setup API, hooks і runtime-поведінки реєстрації.

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

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

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

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

Застарілі provider convenience seams для bundled channels також видалено. Channel-branded helper seams були приватними скороченнями mono-repo, а не стабільними контрактами plugin. Натомість використовуйте вузькі generic SDK subpaths. Усередині bundled plugin workspace тримайте provider-owned допоміжні функції у власному api.ts або runtime-api.ts цього plugin.

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

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

План міграції Talk і realtime voice

Код realtime voice, телефонії, зустрічей і browser Talk переходить від surface-local обліку turn до спільного Talk session controller, що експортується з openclaw/plugin-sdk/realtime-voice. Новий controller володіє спільним конвертом подій Talk, станом active turn, станом capture, станом output-audio, нещодавньою історією подій і відхиленням stale-turn. Provider plugins мають і надалі володіти vendor-specific realtime sessions; surface plugins мають і надалі володіти capture, playback, особливостями телефонії та зустрічей.

Ця міграція Talk навмисно є breaking-clean:

1. Залишити спільні controller/runtime primitives у plugin-sdk/realtime-voice.
2. Перевести bundled surfaces на спільний controller: 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 event channel у Gateway hello-ok.features.events: talk.event.
5. Видалити старий realtime HTTP endpoint і будь-який шлях request-time instruction override.

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

Цільова форма публічного 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 });

Browser-owned WebRTC/provider-websocket sessions використовують talk.client.create, бо browser володіє provider negotiation і media transport, тоді як Gateway володіє credentials, instructions і tool policy. talk.session.* є спільною Gateway-managed поверхнею для gateway-relay realtime, gateway-relay transcription і managed-room native STT/TTS sessions.

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

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

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

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

Не додавайте спеціальні випадки для провайдерів або платформ у core, щоб це запрацювало. Core відповідає за семантику сесії Talk. Plugin провайдерів відповідають за налаштування сесій постачальників. Voice-call і Google Meet відповідають за адаптери телефонії/зустрічей. Browser і native apps відповідають за 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.

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

Як мігрувати

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

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

{  "contracts": {    "agentToolResultMiddleware": ["pi", "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 { runEmbeddedPiAgent } from "openclaw/extension-api";const result = await runEmbeddedPiAgent({ sessionId, prompt }); // After (injected runtime)const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });

pnpm buildpnpm test -- my-plugin/

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

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

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

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

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

Вужчі застаріння, що застосовуються в SDK plugin, контракті provider, runtime-поверхні та manifest. Кожне з них досі працює сьогодні, але буде видалене в майбутньому major-релізі. Запис під кожним пунктом зіставляє старий API з його канонічною заміною.

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

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

Графік видалення

Усі core plugins уже мігровано. Зовнішні plugins мають мігрувати до наступного major-релізу.

Тимчасове приглушення попереджень

Встановіть ці змінні середовища, поки працюєте над міграцією:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

Це тимчасовий аварійний вихід, а не постійне рішення.

Пов'язане

• Початок роботи - створіть свій перший plugin
• Огляд SDK - повний довідник імпорту підшляхів
• Channel Plugins - створення channel plugins
• Provider Plugins - створення provider plugins
• Внутрішня архітектура plugin - поглиблений огляд архітектури
• Manifest plugin - довідник схеми manifest