Міграція Plugin SDK

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

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

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

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

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

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

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

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

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

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

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

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

• Anthropic тримає Claude-specific stream helpers у власному api.ts / contract-api.ts seam
• OpenAI тримає provider builders, default-model helpers і realtime provider builders у власному api.ts
• OpenRouter тримає provider builder і onboarding/config helpers у власному api.ts

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

Код Realtime voice, telephony, meeting і browser Talk переходить від surface-local turn bookkeeping до спільного контролера Talk sessions, який експортується з openclaw/plugin-sdk/realtime-voice. Новий контролер володіє спільним Talk event envelope, active turn state, capture state, output-audio state, recent event history і stale-turn rejection. Provider plugins мають і надалі володіти vendor-specific realtime sessions; surface plugins мають і надалі володіти capture, playback, telephony і meeting quirks.

Ця міграція 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 path.

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

Цільова форма public 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 });
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 surface для gateway-relay realtime, gateway-relay transcription і managed-room native STT/TTS sessions.

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

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

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

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

Не вводьте provider або platform special cases у core, щоб це запрацювало. Core володіє Talk session semantics. Provider plugins володіють vendor session setup. Voice-call і Google Meet володіють telephony/meeting adapters. Browser і native apps володіють device capture/playback UX.

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

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

1. додати новий контракт
2. зберегти стару поведінку, підключену через compatibility adapter
3. вивести diagnostic або warning, що називає старий шлях і заміну
4. покрити обидва шляхи в tests
5. задокументувати deprecation і migration path
6. видалити лише після оголошеного migration window, зазвичай у major release

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

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

# Як мігрувати

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

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

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

// Before
const program = applyWindowsSpawnProgramPolicy({ candidate });

// After
const 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 build
pnpm test -- my-plugin/

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

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

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

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

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

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

// Before
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// After
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

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

// Before
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// After
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Before
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// After
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

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

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

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

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

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

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

# Пов'язане

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