Plugin SDK geçişi

OpenClaw, geniş bir geriye dönük uyumluluk katmanından odaklı, belgelenmiş import'lara 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

• openclaw/plugin-sdk/compat - düzinelerce yardımcıyı yeniden dışa aktaran tek bir import. Yeni plugin mimarisi geliştirilirken eski hook tabanlı plugin'lerin çalışmaya devam etmesini sağlamak için kullanıma sunulmuştu.
• openclaw/plugin-sdk/infra-runtime - sistem olaylarını, Heartbeat durumunu, teslimat 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 runtime yardımcı barrel'ı.
• openclaw/plugin-sdk/config-runtime - geçiş penceresi sırasında hâlâ kullanımdan kaldırılmış doğrudan load/write yardımcılarını taşıyan geniş bir yapılandırma uyumluluğu barrel'ı.
• openclaw/extension-api - plugin'lere gömülü agent runner gibi host tarafı yardımcılara doğrudan erişim veren bir köprü.
• api.registerEmbeddedExtensionFactory(...) - tool_result gibi gömülü-runner olaylarını gözlemleyebilen, kaldırılmış Pi'ye özel paketli extension hook'u.

Geniş import yüzeyleri artık kullanımdan kaldırıldı. Runtime'da hâlâ çalışırlar, ancak yeni plugin'ler bunları kullanmamalıdır ve mevcut plugin'ler bunları kaldıracak sonraki major sürümden önce geçiş yapmalıdır. Pi'ye özel gömülü extension factory kayıt API'si kaldırıldı; bunun yerine tool-result middleware kullanın.

OpenClaw, yerine geçecek bir şeyi 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, diagnostics'ten, dokümantasyondan ve bir kullanımdan kaldırma penceresinden geçmelidir. Bu SDK import'ları, manifest alanları, kurulum API'leri, hook'lar ve runtime kayıt davranışı için geçerlidir.

Bu neden değişti

Eski yaklaşım sorunlara neden oldu:

• Yavaş başlangıç - tek bir yardımcıyı import etmek düzinelerce ilgisiz modülü yüklüyordu
• Döngüsel bağımlılıklar - geniş yeniden dışa aktarımlar import döngüleri oluşturmayı kolaylaştırıyordu
• Belirsiz API yüzeyi - hangi dışa aktarımların kararlı, hangilerinin internal olduğunu anlamanın yolu yoktu

Modern plugin SDK bunu düzeltir: her import yolu (openclaw/plugin-sdk/\<subpath\>) net bir amaca ve belgelenmiş bir sözleşmeye sahip küçük, kendi kendine yeterli bir modüldür.

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

Mevcut paketli sağlayıcı örnekleri:

• Anthropic, Claude'a özgü stream yardımcılarını kendi api.ts / contract-api.ts seam'inde tutar
• OpenAI, sağlayıcı builder'larını, varsayılan-model yardımcılarını ve realtime sağlayıcı builder'larını kendi api.ts dosyasında tutar
• OpenRouter, sağlayıcı builder'ını ve onboarding/config yardımcılarını kendi api.ts dosyasında tutar

Talk ve realtime ses geçiş planı

Realtime ses, telefoni, toplantı ve tarayıcı Talk kodu, yüzey-yerel turn kayıt tutmadan 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, capture durumunu, çıkış-ses durumunu, yakın olay geçmişini ve eski-turn reddini yönetir. Sağlayıcı plugin'ler vendor'a özgü realtime oturumları yönetmeye devam etmelidir; yüzey plugin'leri capture, playback, telefoni ve toplantı özelliklerini yönetmeye devam etmelidir.

Bu Talk geçişi kasıtlı olarak temiz şekilde breaking'dir:

1. Paylaşılan controller/runtime primitive'lerini plugin-sdk/realtime-voice içinde tutun.
2. Paketli yüzeyleri paylaşılan denetleyiciye taşıyın: browser 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ını 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. Paylaşılan denetleyiciyi tercih edin; böylece turn kapsamlı olaylar turn id olmadan yayımlanamaz, eski turnEnd / turnCancel çağrıları daha yeni bir aktif turn'ü temizleyemez ve output-audio yaşam döngüsü olayları telefoni, toplantılar, browser relay, managed-room handoff ve native Talk istemcileri arasında 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 });

Tarayıcıya ait WebRTC/provider-websocket oturumları talk.client.create kullanır, çünkü tarayıcı sağlayıcı negotiation ve media transport'u yönetirken Gateway kimlik bilgilerini, talimatları ve tool politikasını yönetir. 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 koyan legacy config'ler openclaw doctor --fix ile onarılmalıdır; runtime Talk speech/TTS sağlayıcı config'ini realtime sağlayıcı config'i olarak yeniden yorumlamaz.

Desteklenen talk.session.create kombinasyonları kasıtlı olarak azdır:

Kaldırılan method haritası:

Birleşik kontrol söz varlığı da bilinçli olarak dardır:

Bunu çalıştırmak için core içine provider veya platforma özel durumlar eklemeyin. Core, Talk oturumu semantiğinin sahibidir. Provider Plugin'leri, satıcı oturumu kurulumunun sahibidir. Sesli arama ve Google Meet, telefon/Toplantı bağdaştırıcılarının sahibidir. Tarayıcı ve yerel uygulamalar, cihaz yakalama/oynatma UX'inin sahibidir.

Uyumluluk ilkesi

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

1. yeni sözleşmeyi ekleyin
2. eski davranışı bir uyumluluk bağdaştırıcısı üzerinden bağlı tutun
3. eski yolu ve yerine kullanılacak seçeneği adlandıran bir tanılama veya uyarı yayınlayın
4. testlerde her iki yolu da kapsayın
5. kullanımdan kaldırmayı ve geçiş yolunu belgeleyin
6. yalnızca duyurulan geçiş penceresinden sonra kaldırın; bu genellikle büyük bir sürümdedir

Maintainer'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>, bir CI kapısının zamanı gelmiş uyumluluk kayıtları, sahipler arası ayrılmış SDK içe aktarımları veya kullanılmayan ayrılmış SDK alt yolları nedeniyle 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 referanslarını sayar, sahipler arası ayrılmış SDK içe aktarımlarını ortaya çıkarır ve özel memory-host 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ında takip edilen sahip kullanımı bulunmalıdır; kullanılmayan ayrılmış yardımcı dışa aktarımları public SDK'dan 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, belgelenen yerine kullanılacak seçeneği tercih etmelidir; ancak mevcut Plugin'ler olağan minor sürümler sırasında bozulmamalıdır.

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

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

// Pi and Codex runtime dynamic toolsapi.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["pi", "codex"],});

{  "contracts": {    "agentToolResultMiddleware": ["pi", "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 { runEmbeddedPiAgent } from "openclaw/extension-api";const result = await runEmbeddedPiAgent({ sessionId, prompt }); // After (injected runtime)const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });

pnpm buildpnpm test -- my-plugin/

İçe aktarma yolu başvurusu

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

Açıkça belgelenmiş uyumluluk cepheleri, örneğin yayımlanmış @openclaw/[email protected] paketi için korunan kullanım dışı plugin-sdk/discord shim’i dışında, ayrılmış yerleşik Plugin yardımcı birleşim noktaları herkese açık SDK dışa aktarım haritasından emekliye ayrıldı. Sahibe özgü yardımcılar, sahibi olan Plugin paketinin içinde yaşar; paylaşılan host davranışı plugin-sdk/gateway-runtime, plugin-sdk/security-runtime ve plugin-sdk/plugin-config-runtime gibi genel SDK sözleşmeleri üzerinden ilerlemelidir.

İşe uyan en dar import’u kullanın. Bir dışa aktarım bulamıyorsanız src/plugin-sdk/ içindeki kaynağı kontrol edin veya sürdürücülere hangi genel sözleşmenin buna sahip olması gerektiğini sorun.

Aktif kullanım dışı bırakmalar

Plugin SDK, sağlayıcı sözleşmesi, runtime yüzeyi ve manifest genelinde geçerli olan daha dar kullanım dışı bırakmalar. Her biri bugün hâlâ çalışır, ancak gelecekteki bir major 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";

{  "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 core Plugin’ler zaten geçirildi. Harici Plugin’ler sonraki major 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çış kapağıdır, kalıcı bir çözüm değildir.

İlgili

• Başlarken - ilk Plugin’inizi oluşturun
• SDK Genel Bakış - tam alt yol import başvurusu
• 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 Manifest’i - manifest şeması başvurusu