Plugin SDK geçişi

​

Neler değişti

• openclaw/plugin-sdk ve openclaw/plugin-sdk/compat - odaklı SDK oluşturulurken düzinelerce yardımcıyı yeniden dışa aktarıyordu. Her iki kök de artık kaldırıldı; bunun yerine belgelenmiş bir alt yolu içe aktarın.
• 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ı programları bir araya getiren geniş kapsamlı bir barrel.
• openclaw/plugin-sdk/config-runtime - yalnızca sonraki uyumluluk dönemi için tutulan geniş kapsamlı bir yapılandırma barrel’ı; doğrudan çalışma zamanı yükleme/yazma yardımcıları kaldırıldı.
• openclaw/extension-api - plugin’lere gömülü agent çalıştırıcısı gibi ana makine tarafındaki yardımcılara doğrudan erişim sağlayan, kaldırılmış bir köprü.
• api.registerEmbeddedExtensionFactory(...) - tool_result gibi gömülü çalıştırıcı olaylarını gözlemleyen, yalnızca gömülü çalıştırıcıya yönelik kaldırılmış bir hook. Bunun yerine agent araç sonucu ara yazılımını kullanın (bkz. Gömülü araç sonucu uzantılarını ara yazılıma taşıma).

​

Nedenleri

• Yavaş başlangıç - tek bir yardımcının içe aktarılması, ilgisiz düzinelerce modülü yüklüyordu.
• Döngüsel bağımlılıklar - geniş kapsamlı yeniden dışa aktarımlar, içe aktarım döngülerinin oluşturulmasını kolaylaştırıyordu.
• Belirsiz API yüzeyi - kararlı dışa aktarımları dahili olanlardan ayırt etmenin bir yolu yoktu.

• Anthropic, Claude’a özgü akış yardımcılarını kendi api.ts / contract-api.ts katmanında tutar.
• OpenAI, sağlayıcı oluşturucularını, varsayılan model yardımcılarını ve gerçek zamanlı sağlayıcı oluşturucularını kendi api.ts konumunda tutar.
• OpenRouter, sağlayıcı oluşturucusunu ve ilk katılım/yapılandırma yardımcılarını kendi api.ts konumunda tutar.

​

Uyumluluk politikası

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 alternatifini belirten bir tanılama veya uyarı yayınlayın.
4. Testlerde her iki yolu da kapsayın.
5. Kullanımdan kaldırma ve geçiş yolunu belgeleyin.
6. Yalnızca duyurulan geçiş döneminden sonra, genellikle büyük bir sürümde kaldırın.

​

Yayımlanmış kanal kurulumu uyumluluğu

​

Kanal kurulumu giriş alanı uyumluluğu

​

Okuyucuları doğrulama

1. Her nextCursor ile https://clawhub.ai/api/v1/packages?family=code-plugin&limit=100 içinde sayfalar arasında ilerleyin ve categories alanında channels bulunan paketleri tutun.
2. npm search --json --searchlimit=1000 "openclaw channel plugin" içindeki npm adaylarını ekleyin. openclaw/plugin-sdk/channel-setup, openclaw/plugin-sdk/setup ve openclaw/plugin-sdk/core için GitHub kod aramalarından yalnızca kaynak kodu bulunan adayları ekleyin.
3. Her adayın yayımlanmış en son sürümünü çözümleyin. npm pack <package>@<version> --json --pack-destination <temp-dir> komutunu çalıştırın, paketi açın ve doğrudan veya yapı çözümlemeli alan okumaları için gönderilmiş dist JavaScript kodunu ve bildirimlerini inceleyin. Bir paketin npm sürümü yoksa ClawHub yapıtını indirin.
4. Paketi, sürümü, alanı veya yükseltme anahtarını ve eşleşen dosyayı kaydedin. Bir alan veya anahtar yalnızca hiçbir yayımlanmış plugin yapıtı onu okumadığında silinebilir. Tutulan alan ve anahtar listelerinin yanındaki kod açıklamalarında bulunan okuyucu adlarını taramayla eşitlenmiş halde tutun.

​

Eski medya projeksiyonu

import { toInboundMediaFacts } from "openclaw/plugin-sdk/channel-inbound";

const media = toInboundMediaFacts([
  { path: saved.path, url: nativeUrl, contentType: saved.contentType, messageId },
]);

const ctx = finalizeInboundContext({ Body: caption, media });

​

Geçiş yapma

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

// OpenClaw çalışma zamanı araçları ve Codex çalışma zamanı dinamik araçları (sonuç
// dönüştürülebilir). Codex'e özgü araç sonuçları da gözlem amacıyla aktarılır,
// ancak dönüştürülmüş çıktıları modele hiçbir zaman ulaşmaz: Codex
// PostToolUse kancası sözleşmesi yerel bir araç yanıtının yerini alamaz.
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["openclaw", "codex"],
});

{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "codex"]
  }
}

// Önce
const program = applyWindowsSpawnProgramPolicy({ candidate });

// Sonra
const program = applyWindowsSpawnProgramPolicy({
  candidate,
  // Bunu yalnızca kabuk aracılı geri dönüşü kasıtlı olarak kabul eden
  // güvenilir uyumluluk çağıranları için ayarlayın.
  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/

// Önce (kullanımdan kaldırılmış geriye dönük uyumluluk katmanı)
import {
  createChannelReplyPipeline,
  createPluginRuntimeStore,
  resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";

// Sonra (modern odaklı içe aktarmalar)
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";

// Önce (kullanımdan kaldırılmış extension-api köprüsü)
import { runEmbeddedAgent } from "openclaw/extension-api";
const result = await runEmbeddedAgent({ sessionId, prompt });

// Sonra (eklenen çalışma zamanı)
const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm build
pnpm test my-plugin/

​

İçe aktarma yolu başvurusu

​

Kaldırılan uyumluluk yüzeyleri

​

İşlem geneli API sağlayıcısı yayımlama

​

Özel test toplu dışa aktarımı

​

Geçiş başvurusu

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

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

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

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

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

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

{
  "contracts": {
    "externalAuthProviders": ["anthropic", "openai"]
  }
}

// Önce
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// Sonra
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Önce
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// Sonra
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";

​

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

// Gateway'in sahip olduğu Talk oturumu API'si.
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 });

// İstemcinin sahip olduğu sağlayıcı oturumu API'si.
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" });

​

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 plugininizi oluşturun
• SDK’ya Genel Bakış - tam alt yol içe aktarma referansı
• Kanal Pluginleri - kanal pluginleri oluşturma
• Sağlayıcı Pluginleri - sağlayıcı pluginleri oluşturma
• Plugin İç Yapısı - ayrıntılı mimari incelemesi
• Plugin Manifesti - manifest şeması referansı