Migracja Plugin SDK

OpenClaw przeszedł z szerokiej warstwy zgodności wstecznej na nowoczesną architekturę pluginów ze skoncentrowanymi, 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 bardzo szerokie powierzchnie, które pozwalały pluginom importować wszystko, czego potrzebowały, z jednego punktu wejścia:

• openclaw/plugin-sdk/compat - pojedynczy import, który ponownie eksportował dziesiątki helperów. Został wprowadzony, aby starsze pluginy oparte na hookach nadal działały, gdy budowano nową architekturę pluginów.
• openclaw/plugin-sdk/infra-runtime - szeroki barrel helperów uruchomieniowych, który mieszał zdarzenia systemowe, stan heartbeat, kolejki dostarczania, helpery fetch/proxy, helpery plików, typy zatwierdzeń i niepowiązane narzędzia.
• openclaw/plugin-sdk/config-runtime - szeroki barrel zgodności konfiguracji, który wciąż przenosi przestarzałe bezpośrednie helpery ładowania/zapisu w okresie migracji.
• openclaw/extension-api - most, który dawał pluginom bezpośredni dostęp do helperów po stronie hosta, takich jak osadzony runner agenta.
• api.registerEmbeddedExtensionFactory(...) - usunięty hook bundled extension tylko dla osadzonego runnera, który mógł obserwować zdarzenia osadzonego 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 factory rozszerzeń wyłącznie dla osadzonego runnera zostało usunięte; zamiast tego użyj middleware wyników narzędzi.

OpenClaw nie usuwa ani nie interpretuje ponownie udokumentowanego zachowania pluginów w tej samej zmianie, która wprowadza zamiennik. Zmiany łamiące kontrakt muszą najpierw przejść przez adapter zgodności, diagnostykę, dokumentację i okres wycofywania. Dotyczy to importów SDK, pól manifestu, API setup, hooków i zachowania rejestracji runtime.

Dlaczego to się zmieniło

Stare podejście powodowało problemy:

• Powolny startup - import jednego helpera ładował dziesiątki niepowiązanych modułów
• Zależności cykliczne - szerokie ponowne eksporty ułatwiały tworzenie cykli importu
• Niejasna powierzchnia API - nie było sposobu, aby stwierdzić, które eksporty były stabilne, a które wewnętrzne

Nowoczesny plugin SDK rozwiązuje ten problem: każda ścieżka importu (openclaw/plugin-sdk/\<subpath\>) jest małym, samodzielnym modułem o jasnym przeznaczeniu i udokumentowanym kontrakcie.

Starsze wygodne seamy providerów dla bundled kanałów również zniknęły. Helper seamy oznaczone marką kanału były prywatnymi skrótami mono-repo, a nie stabilnymi kontraktami pluginów. Zamiast tego używaj wąskich, ogólnych podścieżek SDK. Wewnątrz bundled przestrzeni roboczej pluginów trzymaj helpery należące do providera we własnym api.ts lub runtime-api.ts tego pluginu.

Aktualne przykłady bundled providerów:

• Anthropic trzyma helpery strumieni specyficzne dla Claude we własnym seamie api.ts / contract-api.ts
• OpenAI trzyma buildery providerów, helpery modeli domyślnych i buildery providerów realtime we własnym api.ts
• OpenRouter trzyma builder providera oraz helpery onboardingu/konfiguracji we własnym api.ts

Plan migracji Talk i głosu realtime

Kod głosu realtime, telefonii, spotkań i przeglądarkowego Talk jest przenoszony z lokalnego dla powierzchni księgowania tur do współdzielonego kontrolera sesji Talk eksportowanego przez openclaw/plugin-sdk/realtime-voice. Nowy kontroler odpowiada za wspólną kopertę zdarzeń Talk, stan aktywnej tury, stan przechwytywania, stan dźwięku wyjściowego, ostatnią historię zdarzeń i odrzucanie przestarzałych tur. Pluginy providerów powinny nadal odpowiadać za sesje realtime specyficzne dla dostawcy; pluginy powierzchni powinny nadal odpowiadać za przechwytywanie, odtwarzanie, telefonię i osobliwości spotkań.

Ta migracja Talk jest celowo czysto łamiąca:

1. Utrzymaj współdzielony kontroler/prymitywy runtime w plugin-sdk/realtime-voice.
2. Przenieś bundled powierzchnie na współdzielony kontroler: przekaźnik przeglądarkowy, przekazanie managed-room, realtime połączeń głosowych, strumieniowe STT połączeń głosowych, realtime Google Meet oraz natywne push-to-talk.
3. Zastąp stare rodziny RPC Talk docelowym API talk.session.* i talk.client.*.
4. Ogłaszaj jeden aktywny kanał zdarzeń Talk w Gateway hello-ok.features.events: talk.event.
5. Usuń stary endpoint HTTP realtime i 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 testowy. Preferuj współdzielony kontroler, aby zdarzenia ograniczone do tury nie mogły być emitowane bez id tury, przestarzałe wywołania turnEnd / turnCancel nie mogły wyczyścić nowszej aktywnej tury, a zdarzenia cyklu życia dźwięku wyjściowego pozostawały spójne w telefonii, spotkaniach, przekaźniku przeglądarkowym, przekazaniu 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 });await gateway.request("talk.client.steer", { sessionKey, text, mode: "steer" });

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

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

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

Mapa usuniętych metod:

Ujednolicony słownik sterowania jest również celowo wąski:

Nie wprowadzaj w rdzeniu specjalnych przypadków dostawcy ani platformy, aby to działało. Rdzeń odpowiada za semantykę sesji Talk. Pluginy dostawców odpowiadają za konfigurację sesji dostawcy. Voice-call i Google Meet odpowiadają za adaptery telefonii/spotkań. Przeglądarka i aplikacje natywne odpowiadają za UX przechwytywania/odtwarzania urządzenia.

Zasady zgodności

Dla 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. emituj diagnostykę lub ostrzeżenie, które wskazuje starą ścieżkę i zamiennik
4. pokryj obie ścieżki testami
5. udokumentuj wycofanie i ścieżkę migracji
6. usuń dopiero po ogłoszonym oknie migracji, zwykle w wydaniu major

Maintainerzy mogą audytować bieżącą kolejkę migracji za pomocą pnpm plugins:boundary-report. Użyj pnpm plugins:boundary-report:summary dla zwartych zliczeń, --owner <id> dla jednego pluginu lub właściciela zgodności oraz pnpm plugins:boundary-report:ci, gdy bramka CI ma kończyć się niepowodzeniem przy zaległych rekordach zgodności, zastrzeżonych importach SDK między właścicielami albo nieużywanych zastrzeżonych podścieżkach SDK. Raport grupuje przestarzałe rekordy zgodności według daty usunięcia, zlicza lokalne odwołania w kodzie/dokumentacji, ujawnia zastrzeżone importy SDK między właścicielami i podsumowuje prywatny most SDK memory-host, aby sprzątanie zgodności pozostawało jawne zamiast polegać na doraźnych wyszukiwaniach. Zastrzeżone podścieżki SDK muszą mieć śledzone użycie przez właścicieli; nieużywane zastrzeżone eksporty pomocnicze należy usunąć z publicznego SDK.

Jeśli pole manifestu jest nadal akceptowane, autorzy pluginów mogą go dalej 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ń minor.

Jak migrować

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/

Odwołanie do ścieżek importu

Ta tabela jest celowo wspólnym podzbiorem migracji, a nie pełną 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 styki dla dołączonych plugins 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/discord@2026.3.13. Pomocniki specyficzne dla właściciela znajdują się w pakiecie właścicielskiego plugin; wspólne 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żyj 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 mają zastosowanie w całym SDK plugin, kontrakcie providera, powierzchni runtime i manifeście. Każde z nich nadal działa dzisiaj, ale zostanie usunięte w przyszłej wersji major. 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";

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

Harmonogram usuwania

Wszystkie pluginy rdzeniowe zostały już zmigrowane. Zewnętrzne pluginy powinny przeprowadzić migrację 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 awaryjna, nie trwałe rozwiązanie.

Powiązane

• Pierwsze kroki - zbuduj swój pierwszy plugin
• Omówienie SDK - pełna referencja importów podścieżek
• Pluginy kanałów - budowanie pluginów kanałów
• Pluginy dostawców - budowanie pluginów dostawców
• Wnętrze pluginów - szczegółowe omówienie architektury
• Manifest pluginu - referencja schematu manifestu