Plugin SDK geçişi

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

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 ana sürüm bunları kaldırmadan önce geçiş yapmalıdır. Yalnızca gömülü çalıştırıcıya yönelik uzantı fabrikası kayıt API’si kaldırıldı; bunun yerine araç sonucu ara katmanını kullanın.

OpenClaw, belgelenmiş Plugin davranışını bir ikame getiren aynı değişiklikte kaldırmaz veya yeniden yorumlamaz. Sözleşmeyi bozan değişiklikler önce bir uyumluluk adaptöründen, 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 - 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

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 kendine yeterli bir modüldür.

Paketli kanallar için eski sağlayıcı kolaylık dikişleri de kaldırıldı. Kanal markalı yardımcı dikişleri 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ı içinde, sağlayıcıya ait yardımcıları o Plugin’in kendi api.ts veya runtime-api.ts dosyasında tutun.

Geçerli paketli sağlayıcı örnekleri:

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

Gerçek zamanlı ses, telefon, toplantı ve tarayıcı Talk kodu, yüzey yerel tur defter tutmasından 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ı, etkin tur durumunu, yakalama durumunu, çıkış sesi durumunu, yakın olay geçmişini ve eski tur reddini sahiplenir. Sağlayıcı Plugin’leri tedarikçiye özgü gerçek zamanlı oturumları sahiplenmeye devam etmelidir; yüzey Plugin’leri ise yakalama, oynatma, telefon ve toplantı özel durumlarını sahiplenmeye 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ı 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.

Yeni kod, düşük seviyeli bir adaptör veya test fikstürü uygulamadığı sürece createTalkEventSequencer(...) öğesini doğrudan çağırmamalıdır. Paylaşılan denetleyiciyi tercih edin; böylece tur kapsamlı olaylar tur kimliği olmadan yayılamaz, eski turnEnd / turnCancel çağrıları daha yeni bir etkin turu temizleyemez ve çıkış sesi yaşam döngüsü olayları telefon, toplantılar, tarayıcı aktarma, yönetilen oda devri ve yerel 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ı uzlaşmasını ve medya taşımasını sahiplenirken Gateway kimlik bilgilerini, talimatları ve araç politikasını sahiplenir. talk.session.*, gateway-relay gerçek zamanlı, gateway-relay transkripsiyon ve yönetilen oda yerel STT/TTS oturumları için ortak Gateway tarafından yönetilen yüzeydir.

Gerçek zamanlı 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ı gerçek zamanlı 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öz varlığı da bilinçli olarak dardır:

Bunu çalıştırmak için core içine sağlayıcı veya platform özel durumları eklemeyin. Talk oturum semantiği core’a aittir. Sağlayıcı Plugin’leri satıcı oturumu kurulumuna sahiptir. Sesli arama ve Google Meet telefon/meeting adaptörlerine sahiptir. Tarayıcı ve native uygulamalar cihaz yakalama/oynatma UX’ine sahiptir.

Uyumluluk ilkesi

Harici Plugin’ler için uyumluluk işi ş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. 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

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 süresi gelen uyumluluk kayıtları, sahipler arası ayrılmış SDK import’ları 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/docs referanslarını sayar, sahipler arası ayrılmış SDK import’larını ortaya çıkarır ve özel memory-host SDK köprüsünü özetler; böylece uyumluluk temizliği ad hoc aramalara dayanmak yerine açık kalır. Ayrılmış SDK alt yollarında izlenen sahip kullanımı olmalıdır; kullanılmayan ayrılmış yardımcı export’ları genel SDK’dan kaldırılmalıdır.

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

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

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 bilerek tam SDK yüzeyi değil, ortak geçiş alt kümesidir. Derleyici giriş noktası envanteri scripts/lib/plugin-sdk-entrypoints.json içinde yaşar; paket dışa aktarımları herkese açık alt kümeden üretilir.

Ayrılmış yerleşik Plugin yardımcı birleşim noktaları, yayımlanmış @openclaw/discord@2026.3.13 paketi için tutulan, kullanımdan kaldırılmış plugin-sdk/discord shim'i gibi açıkça belgelenmiş uyumluluk facadeleri dışında herkese açık SDK dışa aktarma haritasından kaldırılmıştır. 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 taşınmalıdır.

İş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 bakımcılara bunun hangi genel sözleşmeye ait olması gerektiğini sorun.

Etkin kullanımdan kaldırmalar

Plugin SDK, sağlayıcı sözleşmesi, çalışma zamanı yüzeyi ve manifest genelinde geçerli olan daha dar kullanımdan kaldırmalar. 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 karşılığına 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 taşındı. Harici Plugin'ler sonraki ana sürümden önce taşınmalıdır.

Uyarıları geçici olarak bastırma

Taşıma üzerinde çalışırken şu 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'leri - sağlayıcı Plugin'leri oluşturma
• Plugin İç Yapısı - mimariye derinlemesine bakış
• Plugin Manifesti - manifest şeması referansı