Plugin SDK genel bakışı

​

İçe aktarma kuralı

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

​

Alt yol referansı

​

Kayıt API’si

​

Capability kaydı

​

Araçlar ve komutlar

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

​

Altyapı

​

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

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

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

​

Gateway keşif kaydı

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() };
  },
});

​

CLI kayıt meta verileri

• 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"]

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,
      },
    ],
  },
);

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,
      },
    ],
  },
);

​

CLI arka uç kaydı

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

​

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

​

Hook karar semantiği

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

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)

• 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