Plugin SDK geçişi

​

Neler değişiyor

• openclaw/plugin-sdk/compat - onlarca yardımcıyı yeniden dışa aktaran tek bir içe aktarma. Yeni Plugin mimarisi oluşturulurken eski hook tabanlı Plugin’lerin çalışmasını sürdürmek için kullanıma sunuldu.
• openclaw/plugin-sdk/infra-runtime - sistem olaylarını, Heartbeat durumunu, teslim kuyruklarını, fetch/proxy yardımcılarını, dosya yardımcılarını, onay türlerini ve ilgisiz yardımcıları karıştıran geniş bir çalışma zamanı yardımcı barrel’ı.
• openclaw/plugin-sdk/config-runtime - geçiş penceresi sırasında hâlâ kullanımdan kaldırılmış doğrudan yükleme/yazma yardımcılarını taşıyan geniş bir yapılandırma uyumluluk barrel’ı.
• openclaw/extension-api - Plugin’lere gömülü ajan çalıştırıcısı gibi host tarafı yardımcılara doğrudan erişim veren bir köprü.
• api.registerEmbeddedExtensionFactory(...) - tool_result gibi gömülü çalıştırıcı olaylarını gözlemleyebilen, kaldırılmış, yalnızca gömülü çalıştırıcıya yönelik paketli uzantı hook’u.

​

Bu neden değişti

• Yavaş başlatma - bir yardımcıyı içe aktarmak onlarca ilgisiz modülü yüklüyordu
• Döngüsel bağımlılıklar - geniş yeniden dışa aktarmalar içe aktarma döngüleri oluşturmayı kolaylaştırıyordu
• Belirsiz API yüzeyi - hangi dışa aktarmaların kararlı, hangilerinin dahili olduğunu anlamanın yolu yoktu

• Anthropic, Claude’a özgü akış yardımcılarını kendi api.ts / contract-api.ts dikişinde tutar
• OpenAI, sağlayıcı oluşturucuları, varsayılan model yardımcılarını ve gerçek zamanlı sağlayıcı oluşturucuları kendi api.ts dosyasında tutar
• OpenRouter, sağlayıcı oluşturucuyu ve onboarding/yapılandırma yardımcılarını kendi api.ts dosyasında tutar

​

Talk ve gerçek zamanlı ses geçiş planı

1. Paylaşılan denetleyici/çalışma zamanı primitiflerini plugin-sdk/realtime-voice içinde tutun.
2. Paketli yüzeyleri paylaşılan denetleyiciye taşıyın: tarayıcı aktarma, yönetilen oda devri, sesli arama gerçek zamanlı, sesli arama akış STT, Google Meet gerçek zamanlı ve yerel bas-konuş.
3. Eski Talk RPC ailelerini nihai talk.session.* ve talk.client.* API’siyle değiştirin.
4. Gateway hello-ok.features.events içinde tek bir canlı Talk olay kanalını duyurun: talk.event.
5. Eski gerçek zamanlı HTTP uç noktasını ve istek zamanında talimat geçersiz kılma yollarını silin.

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

​

Uyumluluk ilkesi

1. yeni sözleşmeyi ekleyin
2. eski davranışı bir uyumluluk adaptörü üzerinden bağlı tutun
3. eski yolu ve yerine geçeni adlandıran bir tanılama veya uyarı yayımlayın
4. testlerde iki yolu da kapsayın
5. kullanımdan kaldırmayı ve geçiş yolunu belgeleyin
6. yalnızca duyurulan geçiş penceresinden sonra, genellikle büyük bir sürümde kaldırın

​

Nasıl geçiş yapılır

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

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

{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "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 { runEmbeddedAgent } from "openclaw/extension-api";
const result = await runEmbeddedAgent({ sessionId, prompt });

// After (injected runtime)
const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm build
pnpm test -- my-plugin/

​

İçe aktarma yolu referansı

​

Etkin kullanımdan kaldırmalar

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

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

// Before
api.on("deactivate", async (event, ctx) => {
  await stopPluginService(ctx);
});

// After
api.on("gateway_stop", async (event, ctx) => {
  await stopPluginService(ctx);
});

// Before
api.on("subagent_spawning", async () => ({
  status: "ok",
  threadBindingReady: true,
  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },
}));

// After
api.on("subagent_spawned", async (event) => {
  await observeSubagentLaunch(event);
});

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

​

Kaldırma zaman çizelgesi

​

Uyarıları geçici olarak bastırma

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

​

İlgili

• Başlarken - ilk Plugin’inizi oluşturun
• SDK Genel Bakışı - tam alt yol içe aktarma referansı
• Kanal Plugin’leri - kanal Plugin’leri oluşturma
• Sağlayıcı Plugin’leri - sağlayıcı Plugin’leri oluşturma
• Plugin İç Yapısı - mimariye derinlemesine bakış
• Plugin Manifesti - manifest şeması referansı