Plugin SDK geçişi

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Neler değişiyor

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

​

Bu neden değişti

• 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

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

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.

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

​

Uyumluluk ilkesi

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

​

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

​

Aktif kullanım dışı bırakmalar

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

​

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