Plugin SDK geçişi

OpenClaw, geniş bir geriye dönük uyumluluk katmanından odaklı ve belgelenmiş içe aktarmalara sahip modern bir Plugin mimarisine geçti. Plugin'iniz yeni mimariden önce oluşturulduysa, bu kılavuz geçiş yapmanıza yardımcı olur.

Neler değişiyor

Eski Plugin sistemi, Plugin'lerin ihtiyaç duydukları her şeyi tek bir giriş noktasından içe aktarmasına izin veren iki geniş açık yüzey sağlıyordu:

• 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 tanıtıldı.
• 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ı programları karıştıran geniş bir çalışma zamanı yardımcı varili.
• openclaw/plugin-sdk/config-runtime - geçiş penceresi sırasında kullanımdan kaldırılmış doğrudan yükleme/yazma yardımcılarını hâlâ taşıyan geniş bir yapılandırma uyumluluk varili.
• openclaw/extension-api - Plugin'lere gömülü ajan çalıştırıcı gibi ana makine 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ış ve yalnızca gömülü çalıştırıcıya özgü paketli extension hook'u.

Geniş içe aktarma yüzeyleri artık kullanımdan kaldırıldı. Çalışma zamanında hâlâ çalışırlar, ancak yeni Plugin'ler bunları kullanmamalıdır ve mevcut Plugin'ler, bir sonraki major sürüm bunları kaldırmadan önce geçiş yapmalıdır. Yalnızca gömülü çalıştırıcıya özgü extension factory kayıt API'si kaldırıldı; bunun yerine tool-result middleware kullanın.

OpenClaw, bir replacement tanıtan aynı değişiklikte belgelenmiş Plugin davranışını kaldırmaz veya yeniden yorumlamaz. Sözleşmeyi bozan değişiklikler önce bir uyumluluk adapter'ından, tanılamalardan, belgelerden ve bir kullanımdan kaldırma penceresinden geçmelidir. Bu; SDK içe aktarmaları, manifest alanları, kurulum API'leri, hook'lar ve çalışma zamanı kayıt davranışı için geçerlidir.

Bu neden değişti

Eski yaklaşım sorunlara neden oldu:

• Yavaş başlatma - tek 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ırdı
• Belirsiz API yüzeyi - hangi dışa aktarmaların kararlı, hangilerinin dahili olduğunu ayırt etmenin yolu yoktu

Modern Plugin SDK bunu düzeltir: her içe aktarma yolu (openclaw/plugin-sdk/\<subpath\>) net bir amacı ve belgelenmiş sözleşmesi olan küçük, kendi içinde bağımsız bir modüldür.

Paketli kanallar için eski sağlayıcı kolaylık yüzeyleri de kaldırıldı. Kanal markalı yardımcı yüzeyler kararlı Plugin sözleşmeleri değil, özel mono-repo kısayollarıydı. Bunun yerine dar genel SDK alt yollarını kullanın. Paketli Plugin çalışma alanında, sağlayıcıya ait yardımcıları ilgili Plugin'in kendi api.ts veya runtime-api.ts dosyasında tutun.

Güncel paketli sağlayıcı örnekleri:

• Anthropic, Claude'a özgü stream yardımcılarını kendi api.ts / contract-api.ts yüzeyinde tutar
• OpenAI, sağlayıcı oluşturucuları, varsayılan model yardımcılarını ve realtime sağlayıcı oluşturucularını 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 realtime ses geçiş planı

Realtime ses, telefon, toplantı ve tarayıcı Talk kodu, yüzeye yerel turn defteri tutmaktan openclaw/plugin-sdk/realtime-voice tarafından dışa aktarılan paylaşılan bir Talk oturum denetleyicisine taşınıyor. Yeni denetleyici ortak Talk olay zarfını, aktif turn durumunu, yakalama durumunu, çıkış sesi durumunu, yakın olay geçmişini ve bayat turn reddini sahiplenir. Sağlayıcı Plugin'ler satıcıya özgü realtime oturumların sahibi olmaya devam etmelidir; yüzey Plugin'leri yakalama, oynatma, telefon ve toplantı özel durumlarının sahibi olmaya devam etmelidir.

Bu Talk geçişi bilinçli olarak temiz kırılacak şekilde tasarlanmıştır:

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ı relay, managed-room handoff, voice-call realtime, voice-call streaming STT, Google Meet realtime ve native push-to-talk.
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ı duyurun: talk.event.
5. Eski realtime HTTP endpoint'ini ve request-time instruction override yolunu silin.

Yeni kod, düşük seviyeli bir adapter veya test fixture uygulamıyorsa createTalkEventSequencer(...) öğesini doğrudan çağırmamalıdır. Bunun yerine paylaşılan denetleyiciyi tercih edin; böylece turn kapsamlı olaylar turn id olmadan yayımlanamaz, bayat turnEnd / turnCancel çağrıları daha yeni bir aktif turn'ü temizleyemez ve çıkış sesi yaşam döngüsü olayları telefon, toplantılar, tarayıcı relay, managed-room handoff ve native Talk istemcileri genelinde tutarlı kalır.

Hedef genel API şekli şöyledir:

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

Tarayıcıya ait WebRTC/sağlayıcı-websocket oturumları talk.client.create kullanır; çünkü tarayıcı sağlayıcı müzakeresini ve medya taşımasını sahiplenirken Gateway kimlik bilgilerini, talimatları ve araç politikasını sahiplenir. talk.session.*, gateway-relay realtime, gateway-relay transcription ve managed-room native STT/TTS oturumları için ortak Gateway tarafından yönetilen yüzeydir.

Realtime seçicileri talk.provider / talk.providers yanına yerleştiren eski yapılandırmalar openclaw doctor --fix ile onarılmalıdır; çalışma zamanı Talk, konuşma/TTS sağlayıcı yapılandırmasını realtime sağlayıcı yapılandırması olarak yeniden yorumlamaz.

Desteklenen talk.session.create kombinasyonları bilinçli olarak küçüktür:

Kaldırılan yöntem haritası:

Birleşik denetim sözlüğü de kasıtlı olarak dardır:

Bunun çalışması için çekirdeğe sağlayıcıya veya platforma özel durumlar eklemeyin. Talk oturum semantiğinin sahibi çekirdektir. Sağlayıcı Plugin'leri tedarikçi oturum kurulumunun sahibidir. Sesli arama ve Google Meet telefon/meeting adaptörlerinin sahibidir. Tarayıcı ve yerel uygulamalar cihaz yakalama/çalma kullanıcı deneyiminin sahibidir.

Uyumluluk politikası

Harici Plugin'ler için uyumluluk çalışması şu sırayı izler:

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. iki yolu da testlerde kapsayın
5. kullanımdan kaldırma ve geçiş yolunu belgeleyin
6. yalnızca duyurulan geçiş penceresinden sonra, genellikle büyük bir sürümde kaldırın

Bakımcılar mevcut geçiş kuyruğunu pnpm plugins:boundary-report ile denetleyebilir. Kompakt sayımlar için pnpm plugins:boundary-report:summary, tek bir Plugin veya uyumluluk sahibi için --owner <id> ve bir CI kapısının vadesi gelmiş uyumluluk kayıtlarında, sahipler arası ayrılmış SDK içe aktarımlarında veya kullanılmayan ayrılmış SDK alt yollarında başarısız olması gerektiğinde pnpm plugins:boundary-report:ci kullanın. Rapor, kullanımdan kaldırılmış uyumluluk kayıtlarını kaldırma tarihine göre gruplar, yerel kod/belge başvurularını sayar, sahipler arası ayrılmış SDK içe aktarımlarını yüzeye çıkarır ve özel bellek barındırıcısı SDK köprüsünü özetler; böylece uyumluluk temizliği geçici aramalara dayanmak yerine açık kalır. Ayrılmış SDK alt yollarının izlenen sahip kullanımına sahip olması gerekir; kullanılmayan ayrılmış yardımcı dışa aktarımları herkese açık SDK'den kaldırılmalıdır.

Bir manifest alanı hâlâ kabul ediliyorsa, Plugin yazarları belgeler ve tanılamalar aksini söyleyene kadar onu kullanmaya devam edebilir. Yeni kod belgelenmiş yerine geçeni tercih etmelidir, ancak mevcut Plugin'ler olağan küçük sürümler sırasında bozulmamalıdır.

Nasıl geçilir

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/

İçe aktarma yolu referansı

Bu tablo, tam SDK yüzeyi değil, kasıtlı olarak ortak geçiş alt kümesidir. Derleyici giriş noktası envanteri scripts/lib/plugin-sdk-entrypoints.json içinde yer alır; paket dışa aktarımları genel alt kümeden üretilir.

Açıkça belgelenmiş uyumluluk cepheleri, örneğin yayımlanmış @openclaw/discord@2026.3.13 paketi için tutulan, kullanımdan kaldırılmış plugin-sdk/discord ara katmanı dışında, ayrılmış paketlenmiş-Plugin yardımcı arayüzleri genel SDK dışa aktarım haritasından kaldırılmıştır. Sahibe özel yardımcılar, sahip olan Plugin paketinin içinde yaşar; paylaşılan ana makine davranışı plugin-sdk/gateway-runtime, plugin-sdk/security-runtime ve plugin-sdk/plugin-config-runtime gibi genel SDK sözleşmeleri üzerinden taşınmalıdır.

İşe uyan en dar içe aktarımı kullanın. Bir dışa aktarım bulamıyorsanız, src/plugin-sdk/ konumundaki kaynağı kontrol edin veya bakımcılara bunu hangi genel sözleşmenin sahiplenmesi gerektiğini sorun.

Etkin kullanım dışı bırakmalar

Plugin SDK, sağlayıcı sözleşmesi, çalışma zamanı yüzeyi ve manifest genelinde geçerli daha dar kullanım dışı bırakmalar. Her biri bugün hâlâ çalışır, ancak gelecekteki bir majör sürümde kaldırılacaktır. Her öğenin altındaki giriş, eski API'yi kanonik yerine eşler.

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

Kaldırma zaman çizelgesi

Tüm çekirdek Plugin'ler zaten geçirilmiştir. Harici Plugin'ler sonraki ana sürümden önce geçiş yapmalıdır.

Uyarıları geçici olarak bastırma

Geçiş üzerinde çalışırken bu ortam değişkenlerini ayarlayın:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

Bu geçici bir kaçış yoludur, kalıcı bir çözüm değildir.

İ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'ler - sağlayıcı Plugin'ler oluşturma
• Plugin İç Yapısı - mimariye derinlemesine bakış
• Plugin Manifesti - manifest şeması referansı