Migracja Plugin SDK

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Co się zmienia

• 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.

​

Dlaczego to się zmieniło

• 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

• 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

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.

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

​

Zasady zgodnoś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

​

Jak przeprowadzić migrację

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/

​

Referencja ścieżek importu

​

Aktywne wycofania

// 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 usunięcia

​

Tymczasowe wyciszanie ostrzeżeń

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

​

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