Plugin SDK genel bakışı

Plugin SDK, Plugin'ler ile çekirdek arasındaki türlendirilmiş sözleşmedir. Bu sayfa, neyi içe aktaracağınız ve neyi kaydedebileceğiniz için başvuru kaynağıdır.

İçe aktarma kuralı

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

Her alt yol küçük, kendi içinde bağımsız bir modüldür. Bu, başlatmayı hızlı tutar ve döngüsel bağımlılık sorunlarını önler. Kanala özgü giriş/oluşturma 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 ilkelleri ve genel oluşturucu içindir. OpenClaw'ın paketli Plugin'leri, korunmuş paketli kanal şemaları için plugin-sdk/bundled-channel-config-schema kullanır. Kullanımdan kaldırılmış uyumluluk dışa aktarımları plugin-sdk/channel-config-schema-legacy üzerinde kalır; paketli şema alt yollarının hiçbiri yeni Plugin'ler için bir kalıp değildir.

Alt yol başvurusu

Plugin SDK; Plugin girişi, kanal, sağlayıcı, auth, çalışma zamanı, yetenek, bellek ve ayrılmış paketli Plugin yardımcılarına göre gruplanmış dar alt yollar kümesi olarak sunulur. Gruplanmış ve bağlantılanmış tam katalog için Plugin SDK alt yolları bölümüne bakın.

Derleyici giriş noktası envanteri scripts/lib/plugin-sdk-entrypoints.json içinde bulunur; paket dışa aktarımları, scripts/lib/plugin-sdk-private-local-only-subpaths.json içinde listelenen repo-yerel test/dahili alt yollar çıkarıldıktan sonra herkese açık alt kümeden oluşturulur. Herkese açık dışa aktarım 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ış herkese açık 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:

Yetenek kaydı

Araçlar ve komutlar

Plugin komutları, aracının kısa ve komuta ait bir yönlendirme ipucuna ihtiyaç duyduğu durumlarda agentPromptGuidance ayarlayabilir. Bu metni komutun kendisi hakkında tutun; çekirdek prompt oluşturuculara sağlayıcıya veya Plugin'e özgü politika eklemeyin.

Altyapı

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

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

Yeni Plugin kodu için gruplanmış namespace'leri 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 alias'ları 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ık katmanıdır. Cron zamanlamayı sahiplenir ve turn çalıştığında arka plan görev kaydını oluşturur; Plugin SDK yalnızca hedef oturumu, Plugin’e ait adlandırmayı ve temizlemeyi sınırlar. İşin kendisi dayanıklı çok adımlı Task Flow durumu gerektirdiğinde, zamanlanmış turn içinde api.runtime.tasks.managedFlows kullanın.

Sözleşmeler yetkiyi bilinçli olarak ayırır:

• Harici Plugin’ler oturum uzantılarını, UI tanımlayıcılarını, komutları, araç meta verilerini, sonraki turn enjeksiyonlarını ve normal hook’ları sahiplenebilir.
• Güvenilir araç ilkeleri sıradan before_tool_call hook’larından önce çalışır ve ana makine güvenlik ilkesine katıldıkları için yalnızca paketlenmiş olanlara özeldir.
• Ayrılmış komut sahipliği yalnızca paketlenmiş olanlara özeldir. Harici Plugin’ler kendi komut adlarını veya diğer adlarını kullanmalıdır.
• allowPromptInjection=false, agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, eski before_agent_start içindeki prompt alanları ve enqueueNextTurnInjection dahil olmak üzere prompt’u 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 aktarımı üzerinde duyurmasını sağlar. OpenClaw, yerel keşif etkin olduğunda Gateway başlatılırken servisi çağırır, geçerli Gateway portlarını ve gizli olmayan TXT ipucu verilerini iletir ve Gateway kapatılırken 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 sır veya kimlik doğrulama olarak ele almamalıdır. Keşif bir yönlendirme ipucudur; Gateway kimlik doğrulaması ve TLS pinleme hâlâ güveni sahiplenir.

CLI kayıt meta verisi

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

• commands: registrar tarafından sahiplenilen 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: ["nodes"] gibi iç içe komut grupları için isteğe bağlı üst komut yolu

Eşlenmiş node ö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 node özellikleri yapar.

Bir Plugin komutunun normal kök CLI yolunda tembel yüklemeli kalmasını istiyorsanız, o registrar’ın 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 ihtiyacınız yoksa 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 codex-cli gibi yerel bir AI CLI arka ucu için varsayılan yapılandırmayı sahiplenmesini sağlar.

• Arka uç id değeri, codex-cli/gpt-5 gibi model referanslarında provider öneki olur.
• Arka uç config değeri agents.defaults.cliBackends.<id> ile aynı şekli kullanır.
• Kullanıcı yapılandırması hâlâ önceliklidir. OpenClaw, CLI’ı çalıştırmadan önce agents.defaults.cliBackends.<id> değerini Plugin varsayılanının üzerine birleştirir.
• Bir arka uç birleştirme sonrasında uyumluluk yeniden yazımları gerektiriyorsa normalizeConfig kullanın (örneğin eski flag şekillerini normalleştirmek için).
• OpenClaw düşünme düzeylerini yerel effort flag’ine eşlemek gibi CLI lehçesine ait istek kapsamlı argv yeniden yazımları için resolveExecutionArgs kullanın.

Uçtan uca yazma kılavuzu için CLI arka uç Plugin’leri bölümüne bakın.

Özel slotlar

Bellek embedding adapter’ları

• registerMemoryCapability, tercih edilen özel bellek Plugin API’sidir.
• registerMemoryCapability, eşlik eden Plugin’lerin belirli bir bellek Plugin’inin özel düzenine erişmek yerine dışa aktarılan bellek artifact’lerini openclaw/plugin-sdk/memory-host-core üzerinden tüketebilmesi için publicArtifacts.listArtifacts(...) de açığa çıkarabilir.
• registerMemoryPromptSection, registerMemoryFlushPlan ve registerMemoryRuntime eskiyle uyumlu özel bellek Plugin API’leridir.
• MemoryFlushPlan.model, flush turn’ünü etkin fallback zincirini devralmadan ollama/qwen3:8b gibi tam bir provider/model referansına sabitleyebilir.
• registerMemoryEmbeddingProvider, etkin bellek Plugin’inin bir veya daha fazla embedding adapter kimliği kaydetmesini sağlar (örneğin openai, gemini veya özel Plugin tanımlı bir kimlik).
• agents.defaults.memorySearch.provider ve agents.defaults.memorySearch.fallback gibi kullanıcı yapılandırması, bu kayıtlı adapter kimliklerine göre çözümlenir.

Olaylar ve yaşam döngüsü

Örnekler, yaygın hook adları ve guard semantiği için Plugin hook’ları bölümüne bakın.

Hook karar semantiği

• before_tool_call: { block: true } döndürmek sonlandırıcıdır. Herhangi bir işleyici bunu ayarladığında, daha düşük öncelikli işleyiciler atlanır.
• before_tool_call: { block: false } döndürmek karar yok olarak ele alınır (block değerini atlamakla aynıdır), override olarak değil.
• before_install: { block: true } döndürmek sonlandırıcıdır. Herhangi bir işleyici bunu ayarladığında, daha düşük öncelikli işleyiciler atlanır.
• before_install: { block: false } döndürmek karar yok olarak ele alınır (block değerini atlamakla aynıdır), override olarak değil.
• reply_dispatch: { handled: true, ... } döndürmek sonlandırıcıdır. Herhangi bir işleyici dispatch’i üstlendiğinde, daha düşük öncelikli işleyiciler ve varsayılan model dispatch yolu atlanır.
• message_sending: { cancel: true } döndürmek sonlandırıcıdır. Herhangi bir işleyici bunu ayarladığında, daha düşük öncelikli işleyiciler atlanır.
• message_sending: { cancel: false } döndürmek karar yok olarak ele alınır (cancel değerini atlamakla aynıdır), override olarak değil.
• message_received: gelen thread/konu yönlendirmesine ihtiyacınız olduğunda türlü threadId alanını kullanın. metadata alanını kanala özgü ekler için saklayın.
• message_sending: kanala özgü metadata değerine dönmeden önce türlü replyToId / threadId yönlendirme alanlarını kullanın.
• gateway_start: iç gateway:startup hook’larına güvenmek 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; süresi gelen denetimleri ve yürütme için OpenClaw’ı doğruluk kaynağı olarak tutun.

API nesnesi alanları

Dahili modül kuralı

Plugin’inizin içinde, dahili içe aktarmalar için yerel barrel dosyalarını 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 paketlenmiş Plugin genel yüzeyleri (api.ts, runtime-api.ts, index.ts, setup-entry.ts ve benzer genel giriş dosyaları), OpenClaw zaten çalışıyorken 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, diskte çözümlenen yapılandırma dosyasına geri dönerler. Paketlenmiş Plugin facade’ları OpenClaw’ın Plugin facade yükleyicileri üzerinden yüklenmelidir; dist/extensions/... üzerinden doğrudan içe aktarmalar, paketli kurulumların Plugin’e ait kod için kullandığı manifest ve çalışma zamanı sidecar denetimlerini atlar.

Sağlayıcı Plugin’leri, bir yardımcı kasıtlı olarak sağlayıcıya özgüyse ve henüz genel bir SDK alt yoluna ait değilse, dar bir Plugin yerel sözleşme barrel’ı sunabilir. Paketlenmiş örnekler:

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

İlgili