Migracja Plugin SDK

OpenClaw przeszedł z szerokiej warstwy zgodnoś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 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 runtime, 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 w oknie migracji nadal zawiera przestarzałe bezpośrednie helpery load/write.
• openclaw/extension-api - most, który dawał pluginom bezpośredni dostęp do helperów po stronie hosta, takich jak wbudowany runner agenta.
• api.registerEmbeddedExtensionFactory(...) - usunięty hook wyłącznie dla Pi, dotyczący pakietowanych rozszerzeń, który mógł obserwować zdarzenia wbudowanego 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 fabryki wbudowanych rozszerzeń wyłącznie dla Pi zostało usunięte; zamiast tego użyj middleware wyniku narzędzia.

OpenClaw nie usuwa ani nie reinterpretuje udokumentowanego zachowania pluginów w tej samej zmianie, która wprowadza zamiennik. Zmiany kontraktu powodujące niezgodność muszą najpierw przejść przez adapter zgodności, diagnostykę, dokumentację i okno wycofania. 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:

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

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

Starsze pomocnicze punkty integracji providerów dla pakietowanych kanałów również zniknęły. Helpery oznaczone marką kanału były prywatnymi skrótami mono-repo, a nie stabilnymi kontraktami pluginów. Zamiast nich używaj wąskich, ogólnych podścieżek SDK. W obszarze roboczym pakietowanego pluginu trzymaj helpery należące do providera w jego własnym api.ts lub runtime-api.ts.

Aktualne przykłady pakietowanych providerów:

• Anthropic trzyma helpery strumieni specyficzne dla Claude we własnym punkcie integracji api.ts / contract-api.ts
• OpenAI trzyma buildery providera, helpery modeli domyślnych i buildery providera 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 realtime voice, telefonii, spotkań i przeglądarkowego Talk przechodzi z lokalnego dla powierzchni księgowania tur na współdzielony kontroler sesji Talk eksportowany przez openclaw/plugin-sdk/realtime-voice. Nowy kontroler zarządza wspólną kopertą zdarzeń Talk, stanem aktywnej tury, stanem przechwytywania, stanem wyjściowego audio, historią ostatnich zdarzeń oraz odrzucaniem nieaktualnych tur. Pluginy providerów powinny nadal zarządzać sesjami realtime specyficznymi dla dostawcy; pluginy powierzchni powinny nadal zarządzać przechwytywaniem, odtwarzaniem, telefonią i specyfiką spotkań.

Ta migracja Talk celowo wprowadza czyste przełamanie:

1. Utrzymaj współdzielony kontroler i prymitywy runtime w plugin-sdk/realtime-voice.
2. Przenieś pakietowane powierzchnie na współdzielony kontroler: browser relay, managed-room handoff, voice-call realtime, voice-call streaming STT, Google Meet realtime oraz natywne push-to-talk.
3. Zastąp stare rodziny RPC Talk finalnym API talk.session.* i talk.client.*.
4. Ogłoś 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 o zakresie tury nie mogły być emitowane bez identyfikatora tury, nieaktualne wywołania turnEnd / turnCancel nie mogły wyczyścić nowszej aktywnej tury, a zdarzenia cyklu życia wyjściowego audio pozostawały spójne w telefonii, spotkaniach, browser relay, managed-room handoff 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 });
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 zarządza negocjacją providera i transportem mediów, podczas gdy Gateway zarządza poświadczeniami, instrukcjami i polityką narzędzi. talk.session.* jest wspólną powierzchnią zarządzaną przez Gateway dla gateway-relay realtime, gateway-relay transcription oraz sesji STT/TTS natywnych managed-room.

Starsze konfiguracje, które umieszczały selektory realtime obok talk.provider / talk.providers, należy naprawić 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 ograniczone:

Mapa usuniętych metod:

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

Nie wprowadzaj w core specjalnych przypadków providera ani platformy, aby to zadziałało. Core zarządza semantyką sesji Talk. Pluginy providerów zarządzają konfiguracją sesji dostawców. Voice-call i Google Meet zarządzają adapterami telefonii/spotkań. Aplikacje przeglądarkowe i natywne zarządzają UX przechwytywania/odtwarzania urządzenia.

# Polityka zgodności

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

1. dodaj nowy kontrakt
2. utrzymaj stare zachowanie podłączone przez adapter zgodności
3. emituj diagnostykę lub ostrzeżenie, które nazywa 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 głównym

Maintainerzy mogą audytować bieżącą kolejkę migracji za pomocą pnpm plugins:boundary-report. Użyj pnpm plugins:boundary-report:summary, aby uzyskać kompaktowe zliczenia, --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 dla wymagalnych rekordów zgodności, zarezerwowanych importów SDK między właścicielami albo nieużywanych zarezerwowanych podścieżek SDK. Raport grupuje przestarzałe rekordy zgodności według daty usunięcia, zlicza lokalne odwołania w kodzie i dokumentacji, ujawnia zarezerwowane importy SDK między właścicielami oraz podsumowuje prywatny most SDK hosta pamięci, aby czyszczenie zgodności pozostawało jawne zamiast polegać na doraźnych wyszukiwaniach. Zarezerwowane podścieżki SDK muszą mieć śledzone użycie właściciela; nieużywane zarezerwowane eksporty pomocnicze należy usunąć z publicznego SDK.

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

# Jak migrować

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/

# Odniesienie do ścieżek importu

Ta tabela jest celowo wspólnym podzbiorem migracji, a nie pełną powierzchnią SDK. Pełna lista ponad 200 punktów wejścia znajduje się w scripts/lib/plugin-sdk-entrypoints.json.

Zarezerwowane pomocnicze interfejsy dołączonych 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]. Pomocniki specyficzne dla właściciela znajdują się w pakiecie właścicielskiego Pluginu; 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, który pasuje do zadania. Jeśli nie możesz znaleźć eksportu, sprawdź źródło w src/plugin-sdk/ albo zapytaj opiekunów, który ogólny kontrakt powinien być jego właścicielem.

# Aktywne deprecjacje

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

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

# Harmonogram usuwania

Wszystkie Pluginy core zostały już zmigrowane. Zewnętrzne Pluginy 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 run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

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

# Powiązane

• Pierwsze kroki - zbuduj swój pierwszy Plugin
• Przegląd SDK - pełna referencja importów ścieżek podrzędnych
• Pluginy kanałów - budowanie Pluginów kanałów
• Pluginy dostawców - budowanie Pluginów dostawców
• Wewnętrzne mechanizmy Pluginów - dogłębne omówienie architektury
• Manifest Pluginu - referencja schematu manifestu