Plugin SDK genel bakışı

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.

​

İçe aktarma kuralı

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

​

Alt yol başvurusu

​

Kayıt API’si

​

Yetenek kaydı

​

Araçlar ve komutlar

​

Altyapı

​

İş akışı Plugin’leri için ana makine 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ı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.

​

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 verisi

• 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

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ı

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

​

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

​

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ı

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