Plugin SDK'ya genel bakış

​

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

agentPromptGuidance: [
  "Genel komut ipucu.",
  { text: "Bunu yalnızca ana OpenClaw isteminde göster.", surfaces: ["openclaw_main"] },
];

​

Altyapı

​

Onay sonrası Webhook çalışması

import { runDetachedWebhookWork } from "openclaw/plugin-sdk/webhook-request-guards";

void runDetachedWebhookWork(() => processWebhookEvent(event)).catch((error) => {
  runtime.error?.(`webhook gönderimi başarısız oldu: ${String(error)}`);
});

​

İstek sahibi kapsamlı MCP bağlantıları

api.registerMcpServerConnectionResolver({
  serverName: "user-email",
  resolve: async (ctx) => {
    // ctx.requesterSenderId ana bilgisayar tarafından güvenilirdir; burada asla gönderen kimliği uydurmayın.
    const token = await lookupUserToken(ctx.requesterSenderId);
    if (!token) {
      return null; // mevcut çalıştırma için bu sunucuyu atla
    }
    return {
      url: "https://mcp.example.com/email",
      headers: { Authorization: `Bearer ${token}` },
    };
  },
});

• Çözümleyici bağlamı yalnızca güvenilir ana bilgisayar kimliğini taşır (requesterSenderId, isteğe bağlı agentAccountId / messageChannel). Gelecekteki güvenilir alanlar (örneğin Cron/alt ajan kullanıcı bağlamı) eklemeli olarak eklenebilir.
• Bir sunucu adına tek bir Plugin sahip olur: başka bir Plugin’den aynı serverName için yinelenen bir registerMcpServerConnectionResolver, hata tanılamasıyla reddedilir (ilk kayıt kazanır); böylece bağlantı sahipliği hiçbir zaman Plugin yükleme sırasına bağlı olmaz.
• Araç adları, kısmi çözümlemenin istek sahipleri veya turlar arasında güvenli sunucu adlarını hiçbir zaman değiştirmemesi için bildirilen tam sunucu kümesinden türetilir. Çekirdek, farklı istek sahibi uç noktalarının aynı araç şemalarını sunduğunu doğrulamaz; bir çözümleyici her istek sahibini aynı mantıksal hizmete yönlendirmelidir, aksi takdirde araç şemaları (ve istem önbelleği kararlılığı) istek sahibi başına farklılaşır.
• Güvenilir bir requesterSenderId olmadan yapılan çalıştırmalar (Cron, alt ajan, Heartbeat, genel Gateway) hiçbir zaman istek sahibi kapsamlı sunucuları somutlaştırmaz. Paylaşılan bir geri dönüş bağlantısı yoktur.
• resolve, sunucu başına 10 saniyeyle sınırlıdır; zaman aşımı veya hata fırlatılması, statik MCP’nin başarısız olmasına yol açmadan söz konusu sunucuyu çalıştırmadan çıkarır.
• Çözümlenen bağlantılar istek sahibi başına en fazla 5 dakikada bir yeniden doğrulanır: döndürme, aktarımı yeni kimlik bilgileriyle yeniden oluşturur ve bir null sonucu bunu iptal eder (önbelleğe alınmış çalışma zamanı oturumun ortasında bile imha edilir). Bu nedenle iptal edilmiş veya döndürülmüş bir kimlik bilgisi 5 dakikaya kadar kullanımda kalabilir.
• Çözümlenen headers hiçbir zaman günlüğe kaydedilmez veya kalıcılaştırılmaz; çekirdek, kimlik bilgisi döndürmesini algılamak için yalnızca geçici bir bellek içi anahtarlı özet (işlem yerel HMAC) tutar ve çözümlenen üst bilgi/URL kimlik bilgisi değerlerini günlük/hata ayıklama yakalama redaksiyon kayıt defterine kaydeder.
• İstek sahibi kapsamlı sunucular MCP Uygulaması görünümleri oluşturmaz: bir görünüm, istek sahibinin kimliğinin doğrulandığı çalıştırmadan daha uzun yaşar ve Gateway görünüm sınırında istek sahibi kimliği yoktur; bu nedenle uygulama önizlemeleri bu sunucular için hata durumunda kapalı kalır. Araç sonuçları etkilenmez.
• Çözümleyicisi olmayan statik sunucular mevcut oturum kapsamlı yaşam döngüsünü korur.
• Çalıştırma ortamı teslim kuralı: istek sahibi kapsamlı sunucular hiçbir zaman çalıştırma ortamına özgü MCP istemci yapılandırmasına (Codex iş parçacığı mcp_servers, CLI -c mcp_servers=… veya başka herhangi bir oturum paylaşımlı MCP projeksiyonu) girmez. Bunun yerine çalıştırma ortamları bunları çalıştırma kapsamlı araçlar olarak teslim eder:
  • Gömülü çalıştırıcı: oturum MCP çalışma zamanı + paket araçları (statik + kapsamlı).
  • Codex uygulama sunucusu: materializeRequesterScopedMcpToolsForHarnessRun aracılığıyla dinamik araçlar (yalnızca kapsamlı; statik sunucular Codex’in yerel MCP istemcisinde kalır).
• Kapsamlı araç belirtimleri, söz konusu oturumdaki ilk başarılı çözümlemeden sonra oturum boyunca kararlı kalır; böylece paylaşılan iş parçacıklı çalıştırma ortamları (Codex), gönderenler değiştiğinde iş parçacıklarını döndürmez. Herhangi bir istek sahibi çözümlemeden önce kapsamlı belirtimler duyurulmaz.
• Paylaşılan iş parçacıklı bir çalıştırma ortamındaki kimliği doğrulanmamış istek sahipleri yine de duyurulan kapsamlı araçları görür; bunlardan birini çağırmak, söz konusu istek sahibi için temiz bir bağlı-değil araç hatası döndürür. OpenClaw hiçbir zaman başka bir istek sahibinin kimlik bilgilerine geri dönmez.

​

İş akışı Plugin’leri için ana bilgisayar kancaları

api.session.controls.registerControlUiDescriptor({
  surface: "tab",
  id: "logbook",
  label: "Günlük",
  description: "Ekran anlık görüntülerinden oluşturulan zaman çizelgesi biçimindeki gününüz.",
  icon: "sun",
  group: "control",
  requiredScopes: ["operator.write"],
});

• 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ın, UI tanımlayıcılarının, komutların, araç meta verilerinin, sonraki tur eklemelerinin ve normal kancaların sahibi olabilir.
• Güvenilir araç politikaları sıradan before_tool_call kancalarından önce çalışır ve ana makine tarafından güvenilir kabul edilir. Önce paketlenmiş politikalar çalışır; kurulu Plugin politikaları, açıkça etkinleştirilmelerinin yanı sıra yerel kimliklerinin contracts.trustedToolPolicies içinde bulunmasını gerektirir ve ardından Plugin yükleme sırasına göre çalışır. Politika kimlikleri, kaydeden Plugin ile sınırlıdır.
• Ayrılmış komut sahipliği yalnızca paketlenmiş Plugin’lere özeldir. 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 ve enqueueNextTurnInjection dâhil olmak üzere istemi değiştiren kancaları 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: kaydedenin sahip olduğu açık komut adları
• descriptors: CLI yardımı, yönlendirme ve gecikmeli 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: "Matrix hesaplarını, doğrulamayı, cihazları ve profil durumunu yönetin",
        hasSubcommands: true,
      },
    ],
  },
);

api.registerCli(
  async ({ program }) => {
    const { registerNodesCanvasCommands } = await import("./src/cli.js");
    registerNodesCanvasCommands(program);
  },
  {
    parentPath: ["nodes"],
    descriptors: [
      {
        name: "canvas",
        description: "Eşleştirilmiş bir node'dan tuval içeriği yakalayın veya işleyin",
        hasSubcommands: true,
      },
    ],
  },
);

​

CLI arka ucu kaydı

• Arka ucun id değeri, my-cli/gpt-5 gibi model başvurularında sağlayıcı öneki olur.
• Arka ucun config değeri yetkili komut bağdaştırıcısıdır: argv, ortam, ayrıştırıcı, oturum, görüntü ve güvenilirlik davranışı plugin kodunda bulunur.
• Kullanıcılar arka ucu model başvuruları veya model kapsamlı agentRuntime.id üzerinden seçer; openclaw.json bağdaştırıcıyı yeniden yazmaz.
• Kayıtlı statik alanlar çalışma zamanından haberdar bir normalleştirme geçişine ihtiyaç duyduğunda normalizeConfig kullanın.
• OpenClaw düşünme düzeylerini yerel bir efor bayrağıyla eşlemek gibi CLI lehçesine ait, istek kapsamlı argv yeniden yazımları için resolveExecutionArgs kullanın. Kanca ctx.executionMode alır; geçici /btw çağrılarına arka uca özgü yalıtım bayrakları eklemek için "side-question" kullanın. Bu bayraklar, aksi hâlde her zaman açık olan bir CLI için yerel araçları güvenilir biçimde devre dışı bırakıyorsa sideQuestionToolMode: "disabled" değerini de bildirin.
• Arka ucun sahip olduğu başlatma ortamı veya geçici kimlik doğrulama/yapılandırma köprüleri için prepareExecution kullanın. Bunun ctx.contextTokenBudget değeri, çalıştırma için seçilen etkin token sınırıdır; böylece yerel Compaction arka uçları, sağlayıcıya özgü çekirdek dalları olmadan kendi eşiklerini hizalayabilir. Ayrıca arka uç hazırlama işleminin paketlenmiş MCP ayarlarını genişletmesi gerektiğinde çekirdek tarafından hazırlanmış ctx.env değerini alır.
• Belirli bir çalıştırma için tüm yerel araçları devre dışı bırakabilen arka uçlar nativeToolMode: "selectable" bildirebilir. Kısıtlı çağrılar, tam bir ctx.toolAvailability.native listesiyle birlikte kurallı ctx.toolAvailability.openClaw adlarını geçirir. toolAvailabilityEnforcement: "execution-args" bildirin ve sözleşmeyi son yeni/devam ettirme argv’sinde uygulayın ya da "prepare-execution" bildirin, hazırlanan politikada uygulayın ve toolAvailabilityEnforced: true döndürün. OpenClaw, Cron toolsAllow gibi çalışma zamanı sınırları için yerel araçları devre dışı bırakır ve bildirilen uygulama yolu eksik olduğunda kapalı durumda başarısız olur.

​

Özel yuvalar

​

Kullanımdan kaldırılmış bellek gömme bağdaştırıcıları

• registerMemoryCapability, özel bellek plugin’i API’sidir.
• registerMemoryCapability, ana makine tarafından yönetilen dışa aktarımlar için publicArtifacts.listArtifacts(...) öğesini de sunabilir. Bildirilen bu yapıtları listeleyen yardımcı plugin’ler, odaklanmış bir genel tüketici API’si oluşturulana kadar korunan openclaw/plugin-sdk/memory-host-core cephesindeki listActiveMemoryPublicArtifacts(...) öğesini kullanmaya devam eder; başka bir plugin’in özel düzenine erişmemelidir.
• MemoryFlushPlan.model, etkin geri dönüş zincirini devralmadan temizleme turunu ollama/qwen3:8b gibi tam bir provider/model başvurusuna sabitleyebilir.
• registerMemoryEmbeddingProvider kullanımdan kaldırılmıştır. Yeni gömme sağlayıcıları api.registerEmbeddingProvider(...) ve contracts.embeddingProviders kullanmalıdır.
• Mevcut belleğe özgü sağlayıcılar geçiş dönemi 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ü

​

Kanca 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, geçersiz kılma olarak değil, karar verilmemiş olarak değerlendirilir (block öğesini atlamakla aynıdır).
• 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, geçersiz kılma olarak değil, karar verilmemiş olarak değerlendirilir (block öğesini atlamakla aynıdır).
• reply_dispatch: { handled: true, ... } döndürmek sonlandırıcıdır. Herhangi bir işleyici gönderimi üstlendiğinde daha düşük öncelikli işleyiciler ve varsayılan model gönderim 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, geçersiz kılma olarak değil, karar verilmemiş olarak değerlendirilir (cancel öğesini atlamakla aynıdır).
• message_received: gelen iş parçacığı/konu yönlendirmesine ihtiyaç duyduğunuzda türü belirlenmiş threadId alanını kullanın. Kanala özgü ek bilgiler için metadata öğesini koruyun.
• message_sending: kanala özgü metadata öğesine geri dönmeden önce türü belirlenmiş replyToId / threadId yönlendirme alanlarını kullanın.
• gateway_start: dahili gateway:startup kancalarına güvenmek yerine Gateway’in sahip olduğu başlangıç durumu için ctx.config, ctx.workspaceDir ve ctx.getCron?.() kullanın. Cron bu noktada hâlâ yükleniyor olabilir.
• cron_reconciled: başlangıçtan veya zamanlayıcının yeniden yüklenmesinden sonra tam bir harici Cron projeksiyonunu yeniden oluşturun. ctx.getCron?.() tam olarak uzlaştırılmış zamanlayıcıyı döndürürken bu, reason ve enabled: false dâhil etkin enabled durumunu içerir. Kalıcı projeksiyon çalışmalarına ctx.abortSignal geçirin; ilgili zamanlayıcı anlık görüntüsünün yerini yenisi aldığında veya Gateway kapandığında işlem iptal edilir.
• cron_changed: Gateway’in sahip olduğu Cron yaşam döngüsü değişikliklerini gözlemleyin. scheduled ve removed olayları, sıralı bir fark günlüğü değil, tamamlama sonrası uzlaştırma ipuçlarıdır. Zamanlanmış bir olayın event.nextRunAtMs değeri, işin bir sonraki uyanma zamanı olmadığında bulunmaz; kaldırılmış bir olay ise silinen işin anlık görüntüsünü taşımaya devam eder.

​

API nesnesi alanları

​

Dahili modül kuralı

my-plugin/
  api.ts            # Harici tüketiciler için genel dışa aktarımlar
  runtime-api.ts    # Yalnızca dahili çalışma zamanı dışa aktarımları
  index.ts          # Plugin giriş noktası
  setup-entry.ts    # Yalnızca kurulum için hafif giriş (isteğe bağlı)

• Anthropic: Claude beta-header ve service_tier akış yardımcıları için genel api.ts / contract-api.ts bağlantı noktası.
• @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 ilk katılım/yapılandırma yardımcılarını dışa aktarır.

​

İlgili