Migracja Plugin SDK

OpenClaw przeszedł z szerokiej warstwy kompatybilności wstecznej na nowoczesną architekturę Pluginów z ukierunkowanymi, udokumentowanymi importami. Jeśli Twój Plugin został zbudowany przed nową architekturą, ten przewodnik pomoże Ci przeprowadzić migrację.

Co się zmienia

Stary system Pluginów udostępniał dwie szeroko otwarte powierzchnie, które pozwalały Pluginom importować wszystko, czego potrzebowały, z jednego punktu wejścia:

• openclaw/plugin-sdk/compat - pojedynczy import, który reeksportował dziesiątki pomocników. Został wprowadzony, aby utrzymać działanie starszych Pluginów opartych na hookach podczas budowania nowej architektury Pluginów.
• openclaw/plugin-sdk/infra-runtime - szeroki barrel pomocników runtime, który mieszał zdarzenia systemowe, stan heartbeat, kolejki dostarczania, pomocniki fetch/proxy, pomocniki plikowe, typy zatwierdzeń i niepowiązane narzędzia.
• openclaw/plugin-sdk/config-runtime - szeroki barrel kompatybilności konfiguracji, który nadal przenosi przestarzałe bezpośrednie pomocniki odczytu/zapisu w oknie migracji.
• openclaw/extension-api - most, który dawał Pluginom bezpośredni dostęp do pomocników po stronie hosta, takich jak wbudowany runner agenta.
• api.registerEmbeddedExtensionFactory(...) - usunięty hook bundled extension tylko dla Pi, który mógł obserwować zdarzenia embedded-runnera, takie jak tool_result.

Szerokie powierzchnie importu są teraz przestarzałe. Nadal działają w runtime, ale nowe Pluginy nie mogą ich używać, a istniejące Pluginy powinny przeprowadzić migrację, zanim następne wydanie główne je usunie. API rejestracji embedded extension factory tylko dla Pi zostało usunięte; zamiast tego użyj middleware wyników narzędzi.

OpenClaw nie usuwa ani nie reinterpretuje udokumentowanego zachowania Pluginów w tej samej zmianie, która wprowadza zamiennik. Zmiany łamiące kontrakt muszą najpierw przejść przez adapter kompatybilności, diagnostykę, dokumentację i okno deprecjacji. Dotyczy to importów SDK, pól manifestu, API konfiguracji, hooków i zachowania rejestracji runtime.

Dlaczego to się zmieniło

Stare podejście powodowało problemy:

• Wolny start - zaimportowanie jednego pomocnika ładowało dziesiątki niepowiązanych modułów
• Zależności cykliczne - szerokie reeksporty ułatwiały tworzenie cykli importów
• Niejasna powierzchnia API - nie było sposobu, aby określić, które eksporty były stabilne, a które wewnętrzne

Nowoczesny SDK Pluginów to naprawia: każda ścieżka importu (openclaw/plugin-sdk/\<subpath\>) jest małym, samodzielnym modułem z jasnym celem i udokumentowanym kontraktem.

Starsze wygodne seam'y providerów dla bundled channels również zniknęły. Seam'y pomocnicze oznaczone marką kanału były prywatnymi skrótami mono-repo, a nie stabilnymi kontraktami Pluginów. Zamiast tego używaj wąskich, generycznych subścieżek SDK. W przestrzeni roboczej bundled Pluginu trzymaj pomocniki należące do providera w jego własnym api.ts lub runtime-api.ts.

Aktualne przykłady bundled providerów:

• Anthropic trzyma pomocniki strumieniowania specyficzne dla Claude we własnym seam'ie api.ts / contract-api.ts
• OpenAI trzyma buildery providera, pomocniki modeli domyślnych i buildery providera realtime we własnym api.ts
• OpenRouter trzyma builder providera oraz pomocniki onboardingu/konfiguracji we własnym api.ts

Plan migracji Talk i głosu realtime

Kod Talk dla głosu realtime, telefonii, spotkań i przeglądarki przechodzi z lokalnego dla powierzchni księgowania tur na wspólny kontroler sesji Talk eksportowany przez openclaw/plugin-sdk/realtime-voice. Nowy kontroler posiada wspólną kopertę zdarzeń Talk, stan aktywnej tury, stan przechwytywania, stan wyjściowego audio, historię ostatnich zdarzeń oraz odrzucanie nieaktualnych tur. Pluginy providerów powinny nadal posiadać sesje realtime specyficzne dla dostawcy; Pluginy powierzchni powinny nadal posiadać przechwytywanie, odtwarzanie, telefonię i osobliwości spotkań.

Ta migracja Talk celowo zrywa zgodność w czysty sposób:

1. Trzymaj współdzielony kontroler i prymitywy runtime w plugin-sdk/realtime-voice.
2. Przenieś bundled powierzchnie na wspólny kontroler: relay przeglądarkowy, handoff managed-room, realtime rozmów głosowych, streaming STT rozmów głosowych, Google Meet realtime oraz natywny push-to-talk.
3. Zastąp stare rodziny RPC Talk finalnym API talk.session.* i talk.client.*.
4. Ogłaszaj jeden żywy kanał zdarzeń Talk w Gateway hello-ok.features.events: talk.event.
5. Usuń stary endpoint HTTP realtime oraz każdą ścieżkę nadpisywania instrukcji w czasie żądania.

Nowy kod nie powinien wywoływać createTalkEventSequencer(...) bezpośrednio, chyba że implementuje niskopoziomowy adapter lub fixture testową. Preferuj wspólny kontroler, aby zdarzenia ograniczone do tury nie mogły być emitowane bez identyfikatora tury, nieaktualne wywołania turnEnd / turnCancel nie mogły czyścić nowszej aktywnej tury, a zdarzenia cyklu życia wyjściowego audio pozostawały spójne w telefonii, spotkaniach, relayu przeglądarkowym, handoffie managed-room i natywnych klientach Talk.

Docelowy kształt publicznego API to:

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

Sesje WebRTC/provider-websocket należące do przeglądarki używają talk.client.create, ponieważ przeglądarka posiada negocjację providera i transport mediów, podczas gdy Gateway posiada poświadczenia, instrukcje i politykę narzędzi. talk.session.* jest wspólną powierzchnią zarządzaną przez Gateway dla sesji realtime gateway-relay, transkrypcji gateway-relay oraz natywnych sesji STT/TTS managed-room.

Starsze konfiguracje, które umieszczały selektory realtime obok talk.provider / talk.providers, powinny zostać naprawione za pomocą openclaw doctor --fix; runtime Talk nie reinterpretuje konfiguracji providera speech/TTS jako konfiguracji providera realtime.

Obsługiwane kombinacje talk.session.create są celowo niewielkie:

Mapa usuniętych metod:

Ujednolicone słownictwo kontroli jest również celowo wąskie:

Nie wprowadzaj w rdzeniu wyjątków specyficznych dla dostawcy lub platformy, aby to zadziałało. Rdzeń odpowiada za semantykę sesji Talk. Pluginy dostawców odpowiadają za konfigurację sesji dostawcy. Połączenia głosowe i Google Meet odpowiadają za adaptery telefonii/spotkań. Przeglądarka i natywne aplikacje odpowiadają za UX przechwytywania/odtwarzania z urządzeń.

Zasady zgodności

W przypadku zewnętrznych pluginów prace nad zgodnością przebiegają w tej kolejności:

1. dodaj nowy kontrakt
2. zachowaj stare zachowanie podłączone przez adapter zgodności
3. wyemituj diagnostykę lub ostrzeżenie, które wskazuje starą ścieżkę i zamiennik
4. pokryj obie ścieżki testami
5. udokumentuj wycofanie oraz ścieżkę migracji
6. usuń dopiero po ogłoszonym oknie migracji, zwykle w wydaniu głównym

Maintainerzy mogą przeprowadzić audyt bieżącej kolejki migracji za pomocą pnpm plugins:boundary-report. Użyj pnpm plugins:boundary-report:summary dla zwięzłych liczników, --owner <id> dla jednego pluginu lub właściciela zgodności oraz pnpm plugins:boundary-report:ci, gdy bramka CI powinna kończyć się niepowodzeniem przy zaległych rekordach zgodności, importach z zastrzeżonego SDK między właścicielami lub nieużywanych zastrzeżonych podścieżkach SDK. Raport grupuje przestarzałe rekordy zgodności według daty usunięcia, liczy lokalne odwołania w kodzie/dokumentacji, ujawnia importy z zastrzeżonego SDK między właścicielami i podsumowuje prywatny most SDK hosta pamięci, aby porządkowanie zgodności pozostawało jawne zamiast opierać się na doraźnych wyszukiwaniach. Zastrzeżone podścieżki SDK muszą mieć śledzone użycie przez właścicieli; nieużywane eksporty zastrzeżonych helperów należy usunąć z publicznego SDK.

Jeśli pole manifestu jest nadal akceptowane, autorzy pluginów mogą dalej go używać, dopóki dokumentacja i diagnostyka nie powiedzą inaczej. Nowy kod powinien preferować udokumentowany zamiennik, ale istniejące pluginy nie powinny psuć się podczas zwykłych wydań pomniejszych.

Jak przeprowadzić migrację

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/

Referencja ścieżek importu

Ta tabela celowo obejmuje wspólny podzbiór migracyjny, a nie całą powierzchnię SDK. Inwentarz punktów wejścia kompilatora znajduje się w scripts/lib/plugin-sdk-entrypoints.json; eksporty pakietu są generowane z publicznego podzbioru.

Zarezerwowane pomocnicze punkty integracji wbudowanych Pluginów zostały wycofane z publicznej mapy eksportów SDK z wyjątkiem jawnie udokumentowanych fasad zgodności, takich jak przestarzały shim plugin-sdk/discord, zachowany dla opublikowanego pakietu @openclaw/[email protected]. Pomocnicy specyficzni dla właściciela znajdują się wewnątrz pakietu Pluginu właściciela; współdzielone zachowanie hosta powinno przechodzić przez ogólne kontrakty SDK, takie jak plugin-sdk/gateway-runtime, plugin-sdk/security-runtime i plugin-sdk/plugin-config-runtime.

Używaj najwęższego importu pasującego do zadania. Jeśli nie możesz znaleźć eksportu, sprawdź źródło w src/plugin-sdk/ albo zapytaj maintainerów, który ogólny kontrakt powinien go posiadać.

Aktywne wycofania

Węższe wycofania, które dotyczą całego SDK Pluginów, kontraktu providera, powierzchni runtime i manifestu. Każde z nich nadal dziś działa, ale zostanie usunięte w przyszłym wydaniu głównym. Wpis pod każdym elementem mapuje stare API na jego kanoniczny zamiennik.

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

Harmonogram usunięcia

Wszystkie podstawowe Pluginy zostały już zmigrowane. Pluginy zewnętrzne powinny zmigrować przed następnym wydaniem głównym.

Tymczasowe wyciszanie ostrzeżeń

Ustaw te zmienne środowiskowe podczas pracy nad migracją:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

To tymczasowa furtka, a nie trwałe rozwiązanie.

Powiązane

• Pierwsze kroki - zbuduj swój pierwszy Plugin
• Przegląd SDK - pełna referencja importów podścieżek
• Pluginy kanałów - budowanie Pluginów kanałów
• Pluginy providerów - budowanie Pluginów providerów
• Wewnętrzna architektura Pluginów - szczegółowe omówienie architektury
• Manifest Pluginu - referencja schematu manifestu