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.

# Değişenler

Eski Plugin sistemi, Plugin'lerin tek bir giriş noktasından ihtiyaç duydukları her şeyi import etmesine olanak tanıyan iki çok geniş yüzey sağlıyordu:

• openclaw/plugin-sdk/compat - onlarca yardımcıyı yeniden dışa aktaran tek bir import. Yeni Plugin mimarisi inşa edilirken eski hook tabanlı Plugin'lerin çalışmaya devam etmesi için sunulmuştu.
• 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 runtime yardımcı barrel'i.
• openclaw/plugin-sdk/config-runtime - geçiş aralığı sırasında artık kullanımdan kaldırılmış doğrudan yükleme/yazma yardımcılarını hâlâ taşıyan geniş bir config uyumluluk barrel'i.
• openclaw/extension-api - Plugin'lere gömülü agent ç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 Pi'ye özgü paketli extension hook'u.

Geniş import yüzeyleri artık kullanımdan kaldırılmıştır. Runtime sırasında hâlâ çalışırlar, ancak yeni Plugin'ler bunları kullanmamalıdır ve mevcut Plugin'ler, bir sonraki major release bunları kaldırmadan önce geçiş yapmalıdır. Yalnızca Pi'ye özgü gömülü extension factory kayıt API'si kaldırılmıştır; bunun yerine araç sonucu middleware'i kullanın.

OpenClaw, yerine geçecek bir seçenek sunan değişiklikle aynı anda belgelenmiş Plugin davranışını kaldırmaz veya yeniden yorumlamaz. Kırıcı contract değişiklikleri önce bir uyumluluk adapter'ından, tanılardan, dokümanlardan ve bir kullanımdan kaldırma aralığından 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 onlarca 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 export'ları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 amacı ve belgelenmiş contract'ı olan küçük, kendi içinde bağımsız bir modüldür.

Paketli kanallar için eski provider kolaylık seam'leri de kaldırıldı. Kanal markalı yardımcı seam'ler kararlı Plugin contract'ları değil, özel mono-repo kısayollarıydı. Bunun yerine dar ve genel SDK subpath'leri kullanın. Paketli Plugin çalışma alanında, provider'a ait yardımcıları o Plugin'in kendi api.ts veya runtime-api.ts dosyasında tutun.

Mevcut paketli provider örnekleri:

• Anthropic, Claude'a özgü stream yardımcılarını kendi api.ts / contract-api.ts seam'inde tutar
• OpenAI, provider builder'ları, varsayılan model yardımcılarını ve realtime provider builder'larını kendi api.ts dosyasında tutar
• OpenRouter, provider builder'ını ve onboarding/config 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 kayıt tutmadan openclaw/plugin-sdk/realtime-voice tarafından dışa aktarılan paylaşılan bir Talk oturum controller'ına taşınıyor. Yeni controller ortak Talk olay envelope'unu, aktif turn durumunu, capture durumunu, output-audio durumunu, yakın olay geçmişini ve eski turn reddini yönetir. Provider Plugin'leri tedarikçiye özgü realtime oturumları yönetmeye devam etmelidir; yüzey Plugin'leri capture, playback, telefon ve toplantı ayrıntılarını yönetmeye devam etmelidir.

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

1. Paylaşılan controller/runtime primitives'lerini plugin-sdk/realtime-voice içinde tutun.
2. Paketli yüzeyleri paylaşılan controller'a 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ı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 uygulamadığı sürece createTalkEventSequencer(...) öğesini doğrudan çağırmamalıdır. Turn kapsamlı olayların turn id olmadan yayımlanamaması, eski turnEnd / turnCancel çağrılarının daha yeni bir aktif turn'ü temizleyememesi ve output-audio lifecycle olaylarının telefon, toplantılar, tarayıcı relay'i, managed-room handoff ve native Talk istemcileri genelinde tutarlı kalması için paylaşılan controller'ı tercih edin.

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 });
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ı provider negotiation'ı ve media transport'u yönetirken Gateway kimlik bilgilerini, talimatları ve araç policy'sini yönetir. talk.session.*, gateway-relay realtime, gateway-relay transcription ve managed-room native STT/TTS oturumları için ortak Gateway yönetimli yüzeydir.

Realtime selector'ları talk.provider / talk.providers yanına yerleştiren eski config'ler openclaw doctor --fix ile onarılmalıdır; runtime Talk, speech/TTS provider config'ini realtime provider config'i olarak yeniden yorumlamaz.

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

Kaldırılan method haritası:

Birleşik kontrol sözlüğü de bilinçli olarak dardır:

Bunu çalıştırmak için core içinde provider veya platform özel durumları sunmayın. Core, Talk session semantiğine sahiptir. Provider Plugin'leri vendor session kurulumuna sahiptir. Voice-call ve Google Meet telefon/toplantı adapter'larına sahiptir. Tarayıcı ve native uygulamalar cihaz capture/playback UX'ine sahiptir.

# Uyumluluk policy'si

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

1. yeni contract'ı ekleyin
2. eski davranışı bir uyumluluk adapter'ı üzerinden bağlı tutun
3. eski yolu ve yerine geçeni adlandıran bir tanı 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ş aralığından sonra, genellikle bir major release'te kaldırın

Bakımcılar mevcut geçiş kuyruğunu pnpm plugins:boundary-report ile denetleyebilir. Kısa 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 gelmiş uyumluluk kayıtlarında, sahipler arası ayrılmış SDK içe aktarmaları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 referanslarını sayar, sahipler arası ayrılmış SDK içe aktarmalarını görünür kılar ve özel bellek sunucusu 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ı olmalıdır; kullanılmayan ayrılmış yardımcı dışa aktarımları genel SDK'dan kaldırılmalıdır.

Bir manifest alanı hâlâ kabul ediliyorsa, plugin yazarları belgeler ve tanılar aksini söyleyene kadar onu kullanmaya devam edebilir. Yeni kod belgelenmiş değişimi tercih etmelidir, ancak mevcut pluginler 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 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/

# İçe aktarma yolu başvurusu

Bu tablo, tam SDK yüzeyi değil, bilerek ortak geçiş alt kümesidir. 200+ giriş noktasının tam listesi scripts/lib/plugin-sdk-entrypoints.json içinde bulunur.

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ış paketli Plugin yardımcı seams’leri genel SDK export map’inden kaldırılmıştır. Sahibe özgü yardımcılar, sahip 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 export bulamıyorsanız, src/plugin-sdk/ içindeki kaynağı kontrol edin veya bunun hangi genel sözleşmeye ait olması gerektiğini bakımcılara sorun.

# Etkin kullanımdan kaldırmalar

Plugin SDK, provider sözleşmesi, runtime yüzeyi ve manifest genelinde geçerli 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 yedeğiyle eşler.

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

# Kaldırma zaman çizelgesi

Tüm core Plugin’ler zaten taşındı. Harici Plugin’ler bir sonraki major sürümden önce geçiş yapmalıdır.

# Uyarıları geçici olarak susturma

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

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_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 referansı
• Channel Plugin’leri - channel Plugin’leri oluşturma
• Provider Plugin’leri - provider Plugin’leri oluşturma
• Plugin İç Yapıları - mimariye derinlemesine bakış
• Plugin Manifest’i - manifest şeması referansı