Plugin SDK genel bakışı

Plugin SDK, Plugin'ler ile core arasındaki tipli sözleşmedir. Bu sayfa, neyi içe aktaracağınız ve neyi kaydedebileceğiniz için referanstır.

İçe aktarma kuralı

Her zaman belirli bir alt yoldan içe aktarın:

Her alt yol küçük, kendi kendine yeterli bir modüldür. Bu, başlangıcı hızlı tutar ve döngüsel bağımlılık sorunlarını önler. Kanala özgü entry/build yardımcıları için openclaw/plugin-sdk/channel-core tercih edin; daha geniş şemsiye yüzey ve buildChannelConfigSchema gibi paylaşılan yardımcılar için openclaw/plugin-sdk/core kullanın.

Kanal yapılandırması için, kanalın sahip olduğu JSON Schema'yı openclaw.plugin.json#channelConfigs üzerinden yayımlayın. plugin-sdk/channel-config-schema alt yolu, paylaşılan şema ilkel öğeleri ve genel builder içindir. OpenClaw'ın paketli Plugin'leri, korunan paketli kanal şemaları için plugin-sdk/bundled-channel-config-schema kullanır. Kullanımdan kaldırılmış uyumluluk dışa aktarmaları plugin-sdk/channel-config-schema-legacy üzerinde kalır; paketli şema alt yollarından hiçbiri yeni Plugin'ler için bir model değildir.

Alt yol referansı

Plugin SDK, alana göre gruplanmış dar alt yollar kümesi olarak sunulur (Plugin entry, kanal, sağlayıcı, kimlik doğrulama, runtime, capability, bellek ve ayrılmış paketli Plugin yardımcıları). Gruplanmış ve bağlantılı tam katalog için Plugin SDK alt yolları sayfasına bakın.

Derleyici entrypoint envanteri scripts/lib/plugin-sdk-entrypoints.json içinde bulunur; paket dışa aktarmaları, scripts/lib/plugin-sdk-private-local-only-subpaths.json içinde listelenen repo yerel test/dahili alt yolları çıkarıldıktan sonra genel alt kümeden üretilir. Genel dışa aktarma sayısını denetlemek için pnpm plugin-sdk:surface çalıştırın. Yeterince eski olan ve paketli uzantı üretim kodu tarafından kullanılmayan kullanımdan kaldırılmış genel alt yollar scripts/lib/plugin-sdk-deprecated-public-subpaths.json içinde izlenir; geniş kullanımdan kaldırılmış yeniden dışa aktarma barrel'ları scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json içinde izlenir.

Kayıt API'si

register(api) callback'i, şu yöntemlere sahip bir OpenClawPluginApi nesnesi alır:

Capability kaydı

api.registerEmbeddingProvider(...) ile kaydedilen embedding sağlayıcıları, Plugin manifestindeki contracts.embeddingProviders içinde de listelenmelidir. Bu, yeniden kullanılabilir vektör üretimi için genel embedding yüzeyidir. Bellek araması bu genel sağlayıcı yüzeyini tüketebilir. Eski api.registerMemoryEmbeddingProvider(...) ve contracts.memoryEmbeddingProviders dikişi, mevcut belleğe özgü sağlayıcılar taşınırken kullanımdan kaldırılmış uyumluluktur.

Hâlâ runtime batchEmbed(...) sunan belleğe özgü sağlayıcılar, runtime'ları açıkça sourceWideBatchEmbed: true ayarlamadıkça mevcut dosya başına batch sözleşmesinde kalır. Bu opt-in, bellek host'unun birden çok kirli bellek dosyasından ve etkin kaynaktan gelen parçaları host batch sınırlarına kadar tek bir batchEmbed(...) çağrısında göndermesine izin verir. JSONL istek dosyaları yükleyen batch adapter'ları, sağlayıcı işlerini istek sayısı sınırlarının yanı sıra yükleme boyutu sınırlarından önce de bölmelidir. Sağlayıcı, her input parçası için batch.chunks ile aynı sırada bir embedding döndürmelidir; sağlayıcı dosya yerel batch'ler bekliyorsa veya daha büyük kaynak geneli bir işte input sıralamasını koruyamıyorsa flag'i atlayın.

Araçlar ve komutlar

Sabit araç adlarına sahip basit, yalnızca araç içeren Plugin'ler için defineToolPlugin kullanın. Karma Plugin'ler veya tamamen dinamik araç kaydı için doğrudan api.registerTool(...) kullanın.

Plugin komutları, agent kısa, komuta ait bir yönlendirme ipucuna ihtiyaç duyduğunda agentPromptGuidance ayarlayabilir. Bu metni komutun kendisiyle ilgili tutun; core prompt builder'larına sağlayıcıya veya Plugin'e özgü policy eklemeyin.

Guidance girdileri, her prompt yüzeyine uygulanan legacy string'ler veya yapılandırılmış girdiler olabilir:

agentPromptGuidance: [  "Global command hint.",  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },];

Yapılandırılmış surfaces; openclaw_main, codex_app_server, cli_backend, acp_backend veya subagent içerebilir. pi_main, openclaw_main için kullanımdan kaldırılmış bir alias olarak kalır. Bilinçli olarak tüm yüzeylere yönelik guidance için surfaces atlayın. Boş bir surfaces dizisi geçirmeyin; kazara kapsam kaybının global prompt metnine dönüşmemesi için reddedilir.

Yerel Codex app-server developer instructions, diğer prompt yüzeylerinden daha katıdır: yalnızca açıkça codex_app_server kapsamına alınmış guidance bu daha yüksek öncelikli şeride yükseltilir. Legacy string guidance ve kapsamsız yapılandırılmış guidance, uyumluluk için Codex dışı prompt yüzeylerinde kullanılabilir kalır.

Altyapı

İş akışı Plugin'leri için host hook'ları

Host hook'ları, yalnızca bir sağlayıcı, kanal veya araç eklemek yerine host yaşam döngüsüne katılması gereken Plugin'ler için SDK dikişleridir. Bunlar genel sözleşmelerdir; Plan Mode bunları kullanabilir, ancak onay iş akışları, çalışma alanı policy gate'leri, arka plan izleyicileri, kurulum sihirbazları ve UI yardımcı Plugin'leri de kullanabilir.

Yeni Plugin kodu için gruplanmış ad alanlarını kullanın:

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

Eşdeğer düz yöntemler, mevcut Plugin'ler için kullanımdan kaldırılmış uyumluluk takma adları olarak kullanılabilir kalır. Doğrudan api.registerSessionExtension, api.enqueueNextTurnInjection, api.registerControlUiDescriptor, api.registerRuntimeLifecycle, api.registerAgentEventSubscription, api.emitAgentEvent, api.setRunContext, api.getRunContext, api.clearRunContext, api.registerSessionSchedulerJob, api.registerSessionAction, api.sendSessionAttachment, api.scheduleSessionTurn veya api.unscheduleSessionTurnsByTag çağıran yeni Plugin kodu eklemeyin.

scheduleSessionTurn(...), Gateway Cron zamanlayıcısı üzerinde oturum kapsamlı bir kolaylıktır. Cron zamanlamaya sahiptir ve tur çalıştığında arka plan görev kaydını oluşturur; Plugin SDK yalnızca hedef oturumu, Plugin'e ait adlandırmayı ve temizliği sınırlar. İşin kendisi kalıcı çok adımlı Task Flow durumu gerektirdiğinde zamanlanmış tur içinde api.runtime.tasks.managedFlows kullanın.

Sözleşmeler yetkiyi kasıtlı olarak böler:

• Harici Plugin'ler oturum uzantılarına, UI tanımlayıcılarına, komutlara, araç meta verilerine, sonraki tur enjeksiyonlarına ve normal hook'lara sahip olabilir.
• Güvenilir araç politikaları sıradan before_tool_call hook'larından önce çalışır ve ana bilgisayar tarafından güvenilirdir. Paketli politikalar önce çalışır; kurulu Plugin politikaları açık etkinleştirme ve contracts.trustedToolPolicies içinde yerel kimliklerini gerektirir ve ardından Plugin yükleme sırasına göre çalışır. Politika kimlikleri, kaydeden Plugin'e göre kapsamlandırılır.
• Ayrılmış komut sahipliği yalnızca paketlidir. Harici Plugin'ler kendi komut adlarını veya takma adlarını kullanmalıdır.
• allowPromptInjection=false, agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, eski before_agent_start içindeki istem alanları ve enqueueNextTurnInjection dahil istemi değiştiren hook'ları devre dışı bırakır.

Plan dışı tüketici örnekleri:

Gateway keşif kaydı

api.registerGatewayDiscoveryService(...), bir Plugin'in etkin Gateway'i mDNS/Bonjour gibi yerel bir keşif taşıması üzerinde duyurmasına izin verir. OpenClaw, yerel keşif etkinleştirildiğinde Gateway başlatması sırasında hizmeti çağırır, geçerli Gateway bağlantı noktalarını ve gizli olmayan TXT ipucu verilerini geçirir ve Gateway kapanışı sırasında döndürülen stop işleyicisini çağırır.

api.registerGatewayDiscoveryService({  id: "my-discovery",  async advertise(ctx) {    const handle = await startMyAdvertiser({      gatewayPort: ctx.gatewayPort,      tls: ctx.gatewayTlsEnabled,      displayName: ctx.machineDisplayName,    });    return { stop: () => handle.stop() };  },});

Gateway keşif Plugin'leri duyurulan TXT değerlerini gizli bilgi veya kimlik doğrulama olarak ele almamalıdır. Keşif bir yönlendirme ipucudur; Gateway kimlik doğrulaması ve TLS sabitlemesi hâlâ güvene sahiptir.

CLI kayıt meta verileri

api.registerCli(registrar, opts?) iki tür komut meta verisi kabul eder:

• commands: kaydedicinin sahip olduğu açık komut adları
• descriptors: CLI yardımı, yönlendirme ve tembel Plugin CLI kaydı için kullanılan ayrıştırma zamanı komut tanımlayıcıları
• parentPath: iç içe komut grupları için isteğe bağlı üst komut yolu, örneğin ["nodes"]

Eşleştirilmiş düğüm özellikleri için api.registerNodeCliFeature(registrar, opts?) tercih edin. Bu, api.registerCli(..., { parentPath: ["nodes"] }) etrafında küçük bir sarmalayıcıdır ve openclaw nodes canvas gibi komutları açıkça Plugin'e ait düğüm özellikleri haline getirir.

Bir Plugin komutunun normal kök CLI yolunda tembel yüklenmiş kalmasını istiyorsanız, o kaydedicinin açığa çıkardığı her üst düzey komut kökünü kapsayan descriptors sağlayın.

api.registerCli(  async ({ program }) => {    const { registerMatrixCli } = await import("./src/cli.js");    registerMatrixCli({ program });  },  {    descriptors: [      {        name: "matrix",        description: "Manage Matrix accounts, verification, devices, and profile state",        hasSubcommands: true,      },    ],  },);

İç içe komutlar çözümlenmiş üst komutu program olarak alır:

api.registerCli(  async ({ program }) => {    const { registerNodesCanvasCommands } = await import("./src/cli.js");    registerNodesCanvasCommands(program);  },  {    parentPath: ["nodes"],    descriptors: [      {        name: "canvas",        description: "Capture or render canvas content from a paired node",        hasSubcommands: true,      },    ],  },);

commands değerini tek başına yalnızca tembel kök CLI kaydına ihtiyaç duymadığınızda kullanın. Bu istekli uyumluluk yolu desteklenmeye devam eder, ancak ayrıştırma zamanı tembel yükleme için tanımlayıcı destekli yer tutucular kurmaz.

CLI arka uç kaydı

api.registerCliBackend(...), bir Plugin'in claude-cli veya my-cli gibi yerel bir AI CLI arka ucu için varsayılan yapılandırmaya sahip olmasına izin verir.

• Backend id değeri, my-cli/gpt-5 gibi model referanslarında provider öneki olur.
• Backend config, agents.defaults.cliBackends.<id> ile aynı şekli kullanır.
• Kullanıcı yapılandırması yine önceliklidir. OpenClaw, CLI'ı çalıştırmadan önce agents.defaults.cliBackends.<id> değerini Plugin varsayılanının üzerine birleştirir.
• Bir backend, birleştirmeden sonra uyumluluk yeniden yazımlarına ihtiyaç duyduğunda normalizeConfig kullanın (örneğin eski bayrak şekillerini normalize etmek için).
• CLI lehçesine ait istek kapsamlı argv yeniden yazımları için resolveExecutionArgs kullanın; örneğin OpenClaw düşünme düzeylerini yerel bir çaba bayrağına eşlemek için. Hook ctx.executionMode alır; geçici /btw çağrıları için backend'e özgü yerel izolasyon bayrakları eklemek üzere "side-question" kullanın. Bu bayraklar aksi halde her zaman açık olan bir CLI için yerel araçları güvenilir biçimde devre dışı bırakıyorsa, ayrıca sideQuestionToolMode: "disabled" bildirin.

Uçtan uca yazarlık kılavuzu için bkz. CLI backend Plugin'leri.

Özel yuvalar

Kullanımdan kaldırılmış bellek embedding adaptörleri

• registerMemoryCapability, tercih edilen özel bellek-Plugin API'sidir.
• registerMemoryCapability ayrıca publicArtifacts.listArtifacts(...) sunabilir; böylece eşlik eden Plugin'ler, belirli bir bellek Plugin'inin özel düzenine erişmek yerine dışa aktarılan bellek yapıtlarını openclaw/plugin-sdk/memory-host-core üzerinden tüketebilir.
• registerMemoryPromptSection, registerMemoryFlushPlan ve registerMemoryRuntime, eskiyle uyumlu özel bellek-Plugin API'leridir.
• MemoryFlushPlan.model, boşaltma turunu etkin fallback zincirini devralmadan ollama/qwen3:8b gibi kesin bir provider/model referansına sabitleyebilir.
• registerMemoryEmbeddingProvider kullanımdan kaldırılmıştır. Yeni embedding provider'ları api.registerEmbeddingProvider(...) ve contracts.embeddingProviders kullanmalıdır.
• Mevcut belleğe özgü provider'lar geçiş penceresi boyunca çalışmaya devam eder, ancak Plugin incelemesi bunu paketlenmemiş Plugin'ler için uyumluluk borcu olarak bildirir.

Olaylar ve yaşam döngüsü

Örnekler, yaygın hook adları ve guard semantiği için bkz. Plugin hook'ları.

Hook karar semantiği

before_install, operatör kurulum ilkesi yüzeyi değil, bir Plugin çalışma zamanı yaşam döngüsü hook'udur. Bir izin verme/engelleme kararının CLI ve Gateway destekli kurulum ya da güncelleme yollarını kapsaması gerektiğinde security.installPolicy kullanın.

• before_tool_call: { block: true } döndürmek terminaldir. Herhangi bir handler bunu ayarladığında daha düşük öncelikli handler'lar atlanır.
• before_tool_call: { block: false } döndürmek karar yok olarak değerlendirilir (block değerini atlamakla aynı), override olarak değil.
• before_install: { block: true } döndürmek terminaldir. Herhangi bir handler bunu ayarladığında daha düşük öncelikli handler'lar atlanır.
• before_install: { block: false } döndürmek karar yok olarak değerlendirilir (block değerini atlamakla aynı), override olarak değil.
• reply_dispatch: { handled: true, ... } döndürmek terminaldir. Herhangi bir handler gönderimi üstlendiğinde daha düşük öncelikli handler'lar ve varsayılan model gönderim yolu atlanır.
• message_sending: { cancel: true } döndürmek terminaldir. Herhangi bir handler bunu ayarladığında daha düşük öncelikli handler'lar atlanır.
• message_sending: { cancel: false } döndürmek karar yok olarak değerlendirilir (cancel değerini atlamakla aynı), override olarak değil.
• message_received: gelen thread/konu yönlendirmesine ihtiyaç duyduğunuzda tiplendirilmiş threadId alanını kullanın. metadata alanını kanala özgü ekler için saklayın.
• message_sending: kanala özgü metadata değerine düşmeden önce tiplendirilmiş replyToId / threadId yönlendirme alanlarını kullanın.
• gateway_start: dahili gateway:startup hook'larına dayanmak yerine Gateway'e ait başlatma durumu için ctx.config, ctx.workspaceDir ve ctx.getCron?.() kullanın.
• cron_changed: Gateway'e ait Cron yaşam döngüsü değişikliklerini gözlemleyin. Harici uyandırma zamanlayıcılarını eşitlerken event.job?.state?.nextRunAtMs ve ctx.getCron?.() kullanın; vade denetimleri ve yürütme için doğruluk kaynağı olarak OpenClaw'u koruyun.

API nesne alanları

Dahili modül kuralı

Plugin'iniz içinde dahili import'lar için yerel barrel dosyaları kullanın:

my-plugin/  api.ts            # Public exports for external consumers  runtime-api.ts    # Internal-only runtime exports  index.ts          # Plugin entry point  setup-entry.ts    # Lightweight setup-only entry (optional)

Facade ile yüklenen paketli Plugin genel yüzeyleri (api.ts, runtime-api.ts, index.ts, setup-entry.ts ve benzeri genel giriş dosyaları), OpenClaw zaten çalışıyorsa etkin çalışma zamanı yapılandırma anlık görüntüsünü tercih eder. Henüz çalışma zamanı anlık görüntüsü yoksa, diskteki çözümlenmiş yapılandırma dosyasına fallback yaparlar. Paketlenmiş paketli Plugin facade'ları OpenClaw'un Plugin facade yükleyicileri üzerinden yüklenmelidir; dist/extensions/... konumundan doğrudan import'lar, paketlenmiş kurulumların Plugin'e ait kod için kullandığı manifest ve çalışma zamanı sidecar denetimlerini atlar.

Provider Plugin'leri, bir yardımcı özellikle provider'a özgü olduğunda ve henüz genel bir SDK alt yoluna ait olmadığında dar bir Plugin yerel sözleşme barrel'ı sunabilir. Paketli örnekler:

• Anthropic: Claude beta-header ve service_tier stream yardımcıları için genel api.ts / contract-api.ts yüzeyi.
• @openclaw/openai-provider: api.ts, provider oluşturucularını, varsayılan-model yardımcılarını ve gerçek zamanlı provider oluşturucularını dışa aktarır.
• @openclaw/openrouter-provider: api.ts, provider oluşturucusunu ve onboarding/yapılandırma yardımcılarını dışa aktarır.

İlgili