Ana içeriğe atla

​
Plugin SDK Genel Bakış

Plugin SDK, pluginler ile çekirdek arasındaki türlendirilmiş sözleşmedir. Bu sayfa, neyin içe aktarılacağını ve neleri kaydedebileceğinizi açıklayan başvuru kaynağıdır.
Nasıl yapılır kılavuzu mu arıyorsunuz?

​
İçe aktarma kuralı

Her zaman belirli bir alt yoldan içe aktarın: 
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
Her alt yol küçük, kendi içinde tamamlanmış bir modüldür. Bu, başlangıcı hızlı tutar ve dairesel bağımlılık sorunlarını önler. Channel’a özgü giriş/derleme yardımcıları için openclaw/plugin-sdk/channel-core yolunu tercih edin; openclaw/plugin-sdk/core yolunu ise daha geniş şemsiye yüzeyi ve buildChannelConfigSchema gibi paylaşılan yardımcılar için kullanın. openclaw/plugin-sdk/slack, openclaw/plugin-sdk/discord, openclaw/plugin-sdk/signal, openclaw/plugin-sdk/whatsapp gibi provider adlı kolaylık yüzeylerini veya channel markalı yardımcı yüzeyleri eklemeyin ya da bunlara bağımlı olmayın. Paketle gelen pluginler, genel SDK alt yollarını kendi api.ts veya runtime-api.ts barrel dosyaları içinde birleştirmelidir; çekirdek ise ya bu plugin-yerel barrel dosyalarını kullanmalı ya da ihtiyaç gerçekten kanallar arasıysa dar bir genel SDK sözleşmesi eklemelidir. Oluşturulan dışa aktarma eşlemesi hâlâ plugin-sdk/feishu, plugin-sdk/feishu-setup, plugin-sdk/zalo, plugin-sdk/zalo-setup ve plugin-sdk/matrix* gibi küçük bir paketlenmiş-plugin yardımcı yüzeyi kümesi içerir. Bu alt yollar yalnızca paketlenmiş-plugin bakımı ve uyumluluk için vardır; aşağıdaki ortak tabloda bilinçli olarak yer almazlar ve yeni üçüncü taraf pluginler için önerilen içe aktarma yolu değildir.

​
Alt yol başvurusu

Amaçlarına göre gruplandırılmış, en yaygın kullanılan alt yollar. 200+‘den fazla alt yol içeren tam oluşturulmuş liste scripts/lib/plugin-sdk-entrypoints.json içinde yer alır. Ayrılmış paketlenmiş-plugin yardımcı alt yolları yine de bu oluşturulmuş listede görünür. Bir doküman sayfası bunlardan birini açıkça herkese açık olarak önermedikçe bunları uygulama ayrıntısı/uyumluluk yüzeyleri olarak değerlendirin.

​
Plugin girişi

Alt yolTemel dışa aktarımlar
plugin-sdk/plugin-entrydefinePluginEntry
plugin-sdk/coredefineChannelPluginEntry, createChatChannelPlugin, createChannelPluginBase, defineSetupPluginEntry, buildChannelConfigSchema
plugin-sdk/config-schemaOpenClawSchema
plugin-sdk/provider-entrydefineSingleProviderPluginEntry
Alt yolTemel dışa aktarımlar
plugin-sdk/channel-coredefineChannelPluginEntry, defineSetupPluginEntry, createChatChannelPlugin, createChannelPluginBase
plugin-sdk/config-schemaKök openclaw.json Zod şema dışa aktarımı (OpenClawSchema)
plugin-sdk/channel-setupcreateOptionalChannelSetupSurface, createOptionalChannelSetupAdapter, createOptionalChannelSetupWizard, ayrıca DEFAULT_ACCOUNT_ID, createTopLevelChannelDmPolicy, setSetupChannelEnabled, splitSetupEntries
plugin-sdk/setupPaylaşılan kurulum sihirbazı yardımcıları, allowlist istemleri, kurulum durumu oluşturucuları
plugin-sdk/setup-runtimecreatePatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy
plugin-sdk/setup-adapter-runtimecreateEnvPatchedAccountSetupAdapter
plugin-sdk/setup-toolsformatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR
plugin-sdk/account-coreÇoklu hesap yapılandırma/eylem kapısı yardımcıları, varsayılan hesap geri dönüş yardımcıları
plugin-sdk/account-idDEFAULT_ACCOUNT_ID, hesap kimliği normalleştirme yardımcıları
plugin-sdk/account-resolutionHesap arama + varsayılan geri dönüş yardımcıları
plugin-sdk/account-helpersDar hesap listesi/hesap eylemi yardımcıları
plugin-sdk/channel-pairingcreateChannelPairingController
plugin-sdk/channel-reply-pipelinecreateChannelReplyPipeline
plugin-sdk/channel-config-helperscreateHybridChannelConfigAdapter
plugin-sdk/channel-config-schemaChannel yapılandırma şeması türleri
plugin-sdk/telegram-command-configPaketlenmiş-sözleşme geri dönüşüyle Telegram özel komut normalleştirme/doğrulama yardımcıları
plugin-sdk/channel-policyresolveChannelGroupRequireMention
plugin-sdk/channel-lifecyclecreateAccountStatusSink
plugin-sdk/inbound-envelopePaylaşılan gelen rota + zarf oluşturucu yardımcıları
plugin-sdk/inbound-reply-dispatchPaylaşılan gelen kaydetme-ve-dağıtım yardımcıları
plugin-sdk/messaging-targetsHedef ayrıştırma/eşleştirme yardımcıları
plugin-sdk/outbound-mediaPaylaşılan giden medya yükleme yardımcıları
plugin-sdk/outbound-runtimeGiden kimlik/gönderim temsilci yardımcıları
plugin-sdk/thread-bindings-runtimeİş parçacığı bağlama yaşam döngüsü ve bağdaştırıcı yardımcıları
plugin-sdk/agent-media-payloadEski ajan medya payload oluşturucusu
plugin-sdk/conversation-runtimeKonuşma/iş parçacığı bağlama, eşleştirme ve yapılandırılmış bağlama yardımcıları
plugin-sdk/runtime-config-snapshotRuntime yapılandırma anlık görüntü yardımcısı
plugin-sdk/runtime-group-policyRuntime grup ilkesi çözümleme yardımcıları
plugin-sdk/channel-statusPaylaşılan channel durum anlık görüntüsü/özet yardımcıları
plugin-sdk/channel-config-primitivesDar channel yapılandırma-şeması ilkel öğeleri
plugin-sdk/channel-config-writesChannel yapılandırma-yazma yetkilendirme yardımcıları
plugin-sdk/channel-plugin-commonPaylaşılan channel plugin başlangıç dışa aktarımları
plugin-sdk/allowlist-config-editAllowlist yapılandırma düzenleme/okuma yardımcıları
plugin-sdk/group-accessPaylaşılan grup erişim kararı yardımcıları
plugin-sdk/direct-dmPaylaşılan doğrudan-DM kimlik doğrulama/koruma yardımcıları
plugin-sdk/interactive-runtimeEtkileşimli yanıt payload normalleştirme/indirgeme yardımcıları
plugin-sdk/channel-inboundDebounce, bahsetme eşleştirme, zarf yardımcıları
plugin-sdk/channel-send-resultYanıt sonuç türleri
plugin-sdk/channel-actionscreateMessageToolButtonsSchema, createMessageToolCardSchema
plugin-sdk/channel-targetsHedef ayrıştırma/eşleştirme yardımcıları
plugin-sdk/channel-contractChannel sözleşmesi türleri
plugin-sdk/channel-feedbackGeri bildirim/tepki bağlantıları
Alt yolTemel dışa aktarımlar
plugin-sdk/provider-entrydefineSingleProviderPluginEntry
plugin-sdk/provider-setupDüzenlenmiş yerel/self-hosted provider kurulum yardımcıları
plugin-sdk/self-hosted-provider-setupOdaklanmış OpenAI-uyumlu self-hosted provider kurulum yardımcıları
plugin-sdk/cli-backendCLI backend varsayılanları + watchdog sabitleri
plugin-sdk/provider-auth-runtimeProvider pluginleri için runtime API anahtarı çözümleme yardımcıları
plugin-sdk/provider-auth-api-keyAPI anahtarı onboarding/profil yazma yardımcıları
plugin-sdk/provider-auth-resultStandart OAuth kimlik doğrulama-sonucu oluşturucusu
plugin-sdk/provider-auth-loginProvider pluginleri için paylaşılan etkileşimli giriş yardımcıları
plugin-sdk/provider-env-varsProvider auth ortam değişkeni arama yardımcıları
plugin-sdk/provider-authcreateProviderApiKeyAuthMethod, ensureApiKeyFromOptionEnvOrPrompt, upsertAuthProfile
plugin-sdk/provider-model-sharedProviderReplayFamily, buildProviderReplayFamilyHooks, normalizeModelCompat, paylaşılan replay-policy oluşturucuları, provider-endpoint yardımcıları ve normalizeNativeXaiModelId gibi model-id normalleştirme yardımcıları
plugin-sdk/provider-catalog-sharedfindCatalogTemplate, buildSingleProviderApiKeyCatalog, supportsNativeStreamingUsageCompat, applyProviderNativeStreamingUsageCompat
plugin-sdk/provider-httpGenel provider HTTP/endpoint yetenek yardımcıları
plugin-sdk/provider-web-fetchWeb-fetch provider kayıt/önbellek yardımcıları
plugin-sdk/provider-web-searchWeb-search provider kayıt/önbellek/yapılandırma yardımcıları
plugin-sdk/provider-toolsProviderToolCompatFamily, buildProviderToolCompatFamilyHooks, Gemini şema temizleme + tanılama ve resolveXaiModelCompatPatch / applyXaiModelCompat gibi xAI uyumluluk yardımcıları
plugin-sdk/provider-usagefetchClaudeUsage ve benzerleri
plugin-sdk/provider-streamProviderStreamFamily, buildProviderStreamFamilyHooks, composeProviderStreamWrappers, akış sarmalayıcı türleri ve paylaşılan Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot sarmalayıcı yardımcıları
plugin-sdk/provider-onboardOnboarding yapılandırma yama yardımcıları
plugin-sdk/global-singletonSüreç-yerel singleton/map/cache yardımcıları
Alt yolTemel dışa aktarımlar
plugin-sdk/command-authresolveControlCommandGate, komut kayıt defteri yardımcıları, gönderici yetkilendirme yardımcıları
plugin-sdk/approval-auth-runtimeOnaylayıcı çözümleme ve aynı-sohbet eylem-auth yardımcıları
plugin-sdk/approval-client-runtimeYerel exec onay profili/filtre yardımcıları
plugin-sdk/approval-delivery-runtimeYerel onay yeteneği/teslim bağdaştırıcıları
plugin-sdk/approval-native-runtimeYerel onay hedefi + hesap bağlama yardımcıları
plugin-sdk/approval-reply-runtimeExec/plugin onay yanıt payload yardımcıları
plugin-sdk/command-auth-nativeYerel komut auth + yerel oturum-hedef yardımcıları
plugin-sdk/command-detectionPaylaşılan komut algılama yardımcıları
plugin-sdk/command-surfaceKomut gövdesi normalleştirme ve komut yüzeyi yardımcıları
plugin-sdk/allow-fromformatAllowFromLowercase
plugin-sdk/security-runtimePaylaşılan güven, DM kapılama, harici içerik ve gizli bilgi toplama yardımcıları
plugin-sdk/ssrf-policyAna makine allowlist ve özel ağ SSRF ilkesi yardımcıları
plugin-sdk/ssrf-runtimeSabitlenmiş-dispatcher, SSRF korumalı fetch ve SSRF ilkesi yardımcıları
plugin-sdk/secret-inputGizli girdi ayrıştırma yardımcıları
plugin-sdk/webhook-ingressWebhook istek/hedef yardımcıları
plugin-sdk/webhook-request-guardsİstek gövdesi boyutu/zaman aşımı yardımcıları
Alt yolTemel dışa aktarımlar
plugin-sdk/runtimeGeniş runtime/günlükleme/yedekleme/plugin-kurma yardımcıları
plugin-sdk/runtime-envDar runtime ortamı, logger, zaman aşımı, retry ve backoff yardımcıları
plugin-sdk/runtime-storecreatePluginRuntimeStore
plugin-sdk/plugin-runtimePaylaşılan plugin komutu/hook/http/etkileşimli yardımcıları
plugin-sdk/hook-runtimePaylaşılan webhook/internal hook pipeline yardımcıları
plugin-sdk/lazy-runtimecreateLazyRuntimeModule, createLazyRuntimeMethod ve createLazyRuntimeSurface gibi tembel runtime içe aktarma/bağlama yardımcıları
plugin-sdk/process-runtimeSüreç exec yardımcıları
plugin-sdk/cli-runtimeCLI biçimlendirme, bekleme ve sürüm yardımcıları
plugin-sdk/gateway-runtimeGateway istemcisi ve channel-status yama yardımcıları
plugin-sdk/config-runtimeYapılandırma yükleme/yazma yardımcıları
plugin-sdk/telegram-command-configPaketlenmiş Telegram sözleşme yüzeyi mevcut olmadığında bile Telegram komut adı/açıklama normalleştirme ve yinelenen/çakışma denetimleri
plugin-sdk/approval-runtimeExec/plugin onay yardımcıları, onay-yeteneği oluşturucuları, auth/profil yardımcıları, yerel yönlendirme/runtime yardımcıları
plugin-sdk/reply-runtimePaylaşılan gelen/yanıt runtime yardımcıları, parçalama, dağıtım, heartbeat, yanıt planlayıcı
plugin-sdk/reply-dispatch-runtimeDar yanıt dağıtım/tamamlama yardımcıları
plugin-sdk/reply-historybuildHistoryContext, recordPendingHistoryEntry ve clearHistoryEntriesIfEnabled gibi paylaşılan kısa pencere yanıt geçmişi yardımcıları
plugin-sdk/reply-referencecreateReplyReferencePlanner
plugin-sdk/reply-chunkingDar metin/markdown parçalama yardımcıları
plugin-sdk/session-store-runtimeOturum deposu yolu + updated-at yardımcıları
plugin-sdk/state-pathsDurum/OAuth dizin yolu yardımcıları
plugin-sdk/routingresolveAgentRoute, buildAgentSessionKey ve resolveDefaultAgentBoundAccountId gibi rota/oturum anahtarı/hesap bağlama yardımcıları
plugin-sdk/status-helpersPaylaşılan channel/hesap durum özeti yardımcıları, runtime-state varsayılanları ve sorun meta veri yardımcıları
plugin-sdk/target-resolver-runtimePaylaşılan hedef çözümleyici yardımcıları
plugin-sdk/string-normalization-runtimeSlug/dizgi normalleştirme yardımcıları
plugin-sdk/request-urlFetch/istek benzeri girdilerden dizgi URL’lerini çıkarın
plugin-sdk/run-commandNormalleştirilmiş stdout/stderr sonuçlarıyla zamanlanmış komut çalıştırıcısı
plugin-sdk/param-readersOrtak araç/CLI parametre okuyucuları
plugin-sdk/tool-sendAraç argümanlarından standart gönderim hedef alanlarını çıkarın
plugin-sdk/temp-pathPaylaşılan geçici indirme yolu yardımcıları
plugin-sdk/logging-coreAlt sistem logger ve redaksiyon yardımcıları
plugin-sdk/markdown-table-runtimeMarkdown tablo modu yardımcıları
plugin-sdk/json-storeKüçük JSON durum okuma/yazma yardımcıları
plugin-sdk/file-lockYeniden girişli dosya kilidi yardımcıları
plugin-sdk/persistent-dedupeDisk destekli yinelenen kaldırma önbelleği yardımcıları
plugin-sdk/acp-runtimeACP runtime/oturum yardımcıları
plugin-sdk/agent-config-primitivesDar ajan runtime yapılandırma-şeması ilkel öğeleri
plugin-sdk/boolean-paramGevşek boole parametre okuyucusu
plugin-sdk/dangerous-name-runtimeTehlikeli ad eşleştirme çözümleme yardımcıları
plugin-sdk/device-bootstrapCihaz bootstrap ve eşleştirme token yardımcıları
plugin-sdk/extension-sharedPaylaşılan pasif-channel ve durum yardımcısı ilkel öğeleri
plugin-sdk/models-provider-runtime/models komutu/provider yanıt yardımcıları
plugin-sdk/skill-commands-runtimeSkill komut listeleme yardımcıları
plugin-sdk/native-command-registryYerel komut kayıt defteri/oluşturma/serileştirme yardımcıları
plugin-sdk/provider-zai-endpointZ.AI endpoint algılama yardımcıları
plugin-sdk/infra-runtimeSistem olayı/heartbeat yardımcıları
plugin-sdk/collection-runtimeKüçük sınırlı önbellek yardımcıları
plugin-sdk/diagnostic-runtimeTanılama bayrağı ve olay yardımcıları
plugin-sdk/error-runtimeHata grafiği, biçimlendirme, paylaşılan hata sınıflandırma yardımcıları, isApprovalNotFoundError
plugin-sdk/fetch-runtimeSarmalanmış fetch, proxy ve sabitlenmiş arama yardımcıları
plugin-sdk/host-runtimeAna makine adı ve SCP ana makinesi normalleştirme yardımcıları
plugin-sdk/retry-runtimeRetry yapılandırması ve retry çalıştırıcısı yardımcıları
plugin-sdk/agent-runtimeAjan dizini/kimliği/çalışma alanı yardımcıları
plugin-sdk/directory-runtimeYapılandırma destekli dizin sorgusu/yinelenen kaldırma
plugin-sdk/keyed-async-queueKeyedAsyncQueue
Alt yolTemel dışa aktarımlar
plugin-sdk/media-runtimePaylaşılan medya fetch/dönüştürme/depolama yardımcıları ve medya payload oluşturucuları
plugin-sdk/media-understandingMedya anlama provider türleri ve provider tarafı görüntü/ses yardımcı dışa aktarımları
plugin-sdk/text-runtimeAsistan tarafından görülebilen metin kaldırma, markdown render/parçalama/tablo yardımcıları, redaksiyon yardımcıları, directive-tag yardımcıları ve güvenli metin yardımcıları gibi paylaşılan metin/markdown/günlükleme yardımcıları
plugin-sdk/text-chunkingGiden metin parçalama yardımcısı
plugin-sdk/speechSpeech provider türleri ve provider tarafı directive, kayıt defteri ve doğrulama yardımcıları
plugin-sdk/speech-corePaylaşılan speech provider türleri, kayıt defteri, directive ve normalleştirme yardımcıları
plugin-sdk/realtime-transcriptionGerçek zamanlı transcription provider türleri ve kayıt defteri yardımcıları
plugin-sdk/realtime-voiceGerçek zamanlı ses provider türleri ve kayıt defteri yardımcıları
plugin-sdk/image-generationGörüntü üretimi provider türleri
plugin-sdk/image-generation-corePaylaşılan görüntü üretimi türleri, failover, auth ve kayıt defteri yardımcıları
plugin-sdk/video-generationVideo üretimi provider/istek/sonuç türleri
plugin-sdk/video-generation-corePaylaşılan video üretimi türleri, failover yardımcıları, provider arama ve model-ref ayrıştırma
plugin-sdk/webhook-targetsWebhook hedef kayıt defteri ve rota-kurma yardımcıları
plugin-sdk/webhook-pathWebhook yolu normalleştirme yardımcıları
plugin-sdk/web-mediaPaylaşılan uzak/yerel medya yükleme yardımcıları
plugin-sdk/zodPlugin SDK kullanıcıları için yeniden dışa aktarılan zod
plugin-sdk/testinginstallCommonResolveTargetErrorCases, shouldAckReaction
Alt yolTemel dışa aktarımlar
plugin-sdk/memory-coreYönetici/yapılandırma/dosya/CLI yardımcıları için paketlenmiş memory-core yardım yüzeyi
plugin-sdk/memory-core-engine-runtimeBellek dizinleme/arama runtime cephesi
plugin-sdk/memory-core-host-engine-foundationBellek ana makine foundation engine dışa aktarımları
plugin-sdk/memory-core-host-engine-embeddingsBellek ana makine embedding engine dışa aktarımları
plugin-sdk/memory-core-host-engine-qmdBellek ana makine QMD engine dışa aktarımları
plugin-sdk/memory-core-host-engine-storageBellek ana makine depolama engine dışa aktarımları
plugin-sdk/memory-core-host-multimodalBellek ana makine multimodal yardımcıları
plugin-sdk/memory-core-host-queryBellek ana makine sorgu yardımcıları
plugin-sdk/memory-core-host-secretBellek ana makine gizli bilgi yardımcıları
plugin-sdk/memory-core-host-statusBellek ana makine durum yardımcıları
plugin-sdk/memory-core-host-runtime-cliBellek ana makine CLI runtime yardımcıları
plugin-sdk/memory-core-host-runtime-coreBellek ana makine çekirdek runtime yardımcıları
plugin-sdk/memory-core-host-runtime-filesBellek ana makine dosya/runtime yardımcıları
plugin-sdk/memory-lancedbPaketlenmiş memory-lancedb yardımcı yüzeyi
AileGeçerli alt yollarAmaçlanan kullanım
Browserplugin-sdk/browser-config-support, plugin-sdk/browser-supportPaketlenmiş browser plugin destek yardımcıları
Matrixplugin-sdk/matrix, plugin-sdk/matrix-helper, plugin-sdk/matrix-runtime-heavy, plugin-sdk/matrix-runtime-shared, plugin-sdk/matrix-runtime-surface, plugin-sdk/matrix-surface, plugin-sdk/matrix-thread-bindingsPaketlenmiş Matrix yardımcı/runtime yüzeyi
Lineplugin-sdk/line, plugin-sdk/line-core, plugin-sdk/line-runtime, plugin-sdk/line-surfacePaketlenmiş LINE yardımcı/runtime yüzeyi
IRCplugin-sdk/irc, plugin-sdk/irc-surfacePaketlenmiş IRC yardımcı yüzeyi
Channel’a özgü yardımcılarplugin-sdk/googlechat, plugin-sdk/zalouser, plugin-sdk/bluebubbles, plugin-sdk/bluebubbles-policy, plugin-sdk/mattermost, plugin-sdk/mattermost-policy, plugin-sdk/feishu-conversation, plugin-sdk/msteams, plugin-sdk/nextcloud-talk, plugin-sdk/nostr, plugin-sdk/tlon, plugin-sdk/twitchPaketlenmiş channel uyumluluk/yardımcı yüzeyleri
Auth/plugin’e özgü yardımcılarplugin-sdk/github-copilot-login, plugin-sdk/github-copilot-token, plugin-sdk/diagnostics-otel, plugin-sdk/diffs, plugin-sdk/llm-task, plugin-sdk/thread-ownership, plugin-sdk/voice-callPaketlenmiş özellik/plugin yardımcı yüzeyleri; plugin-sdk/github-copilot-token şu anda DEFAULT_COPILOT_API_BASE_URL, deriveCopilotApiBaseUrlFromToken ve resolveCopilotApiToken dışa aktarımlarını içerir

​
Kayıt API’si

register(api) geri çağrısı, şu yöntemleri içeren bir OpenClawPluginApi nesnesi alır:

​
Yetenek kaydı

YöntemKaydettiği şey
api.registerProvider(...)Metin çıkarımı (LLM)
api.registerCliBackend(...)Yerel CLI çıkarım backend’i
api.registerChannel(...)Mesajlaşma kanalı
api.registerSpeechProvider(...)Metinden sese / STT sentezi
api.registerRealtimeTranscriptionProvider(...)Akışlı gerçek zamanlı transcription
api.registerRealtimeVoiceProvider(...)Çift yönlü gerçek zamanlı ses oturumları
api.registerMediaUnderstandingProvider(...)Görüntü/ses/video analizi
api.registerImageGenerationProvider(...)Görüntü üretimi
api.registerVideoGenerationProvider(...)Video üretimi
api.registerWebFetchProvider(...)Web fetch / scrape provider
api.registerWebSearchProvider(...)Web arama

​
Araçlar ve komutlar

YöntemKaydettiği şey
api.registerTool(tool, opts?)Ajan aracı (zorunlu veya { optional: true })
api.registerCommand(def)Özel komut (LLM’yi atlar)

​
Altyapı

YöntemKaydettiği şey
api.registerHook(events, handler, opts?)Olay hook’u
api.registerHttpRoute(params)Gateway HTTP endpoint’i
api.registerGatewayMethod(name, handler)Gateway RPC yöntemi
api.registerCli(registrar, opts?)CLI alt komutu
api.registerService(service)Arka plan hizmeti
api.registerInteractiveHandler(registration)Etkileşimli işleyici
Ayrılmış çekirdek yönetici ad alanları (config.*, exec.approvals.*, wizard.*, update.*) bir plugin daha dar bir gateway yöntem kapsamı atamaya çalışsa bile her zaman operator.admin olarak kalır. Plugin’in sahip olduğu yöntemler için plugin’e özgü önekleri tercih edin.

​
CLI kayıt meta verisi

api.registerCli(registrar, opts?) iki tür üst seviye meta veri kabul eder:
  • commands: registrar’ın sahip olduğu açık komut kökleri
  • descriptors: kök CLI yardımı, yönlendirme ve tembel plugin CLI kaydı için ayrıştırma zamanında kullanılan komut tanımlayıcıları
Bir plugin komutunun normal kök CLI yolunda tembel yüklenmiş olarak kalmasını istiyorsanız, bu registrar tarafından sunulan her üst seviye 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: "Matrix hesaplarını, doğrulamayı, cihazları ve profil durumunu yönetin",
        hasSubcommands: true,
      },
    ],
  },
);
Yalnızca commands, normal kök CLI kaydı için tembel yükleme gerekmiyorsa kullanılmalıdır. Bu istekli uyumluluk yolu desteklenmeye devam eder, ancak ayrıştırma zamanı tembel yükleme için descriptor destekli yer tutucular kurmaz.

​
CLI backend kaydı

api.registerCliBackend(...), bir pluginin claude-cli veya codex-cli gibi yerel bir AI CLI backend’i için varsayılan yapılandırmaya sahip olmasını sağlar.
  • Backend id, claude-cli/opus gibi model ref’lerinde provider öneki olur.
  • Backend config, agents.defaults.cliBackends.<id> ile aynı şekli kullanır.
  • Kullanıcı yapılandırması yine önceliklidir. OpenClaw, CLI’yi çalıştırmadan önce agents.defaults.cliBackends.<id> değerini plugin varsayılanının üzerine birleştirir.
  • Bir backend, birleştirme sonrası uyumluluk yeniden yazımları gerektiriyorsa (örneğin eski bayrak biçimlerini normalleştirmek için) normalizeConfig kullanın.

​
Ayrılmış yuvalar

YöntemKaydettiği şey
api.registerContextEngine(id, factory)Bağlam motoru (aynı anda bir etkin)
api.registerMemoryPromptSection(builder)Bellek istem bölümü oluşturucusu
api.registerMemoryFlushPlan(resolver)Bellek flush planı çözümleyicisi
api.registerMemoryRuntime(runtime)Bellek runtime bağdaştırıcısı

​
Bellek embedding bağdaştırıcıları

YöntemKaydettiği şey
api.registerMemoryEmbeddingProvider(adapter)Etkin plugin için bellek embedding bağdaştırıcısı
  • registerMemoryPromptSection, registerMemoryFlushPlan ve registerMemoryRuntime, bellek pluginlerine özeldir.
  • registerMemoryEmbeddingProvider, etkin bellek plugininin bir veya daha fazla embedding bağdaştırıcı kimliği (openai, gemini veya plugin tarafından tanımlanmış özel bir kimlik gibi) kaydetmesini sağlar.
  • agents.defaults.memorySearch.provider ve agents.defaults.memorySearch.fallback gibi kullanıcı yapılandırmaları, bu kayıtlı bağdaştırıcı kimliklerine göre çözülür.

​
Olaylar ve yaşam döngüsü

YöntemNe yapar
api.on(hookName, handler, opts?)Türlendirilmiş yaşam döngüsü hook’u
api.onConversationBindingResolved(handler)Konuşma bağlama geri çağrısı

​
Hook karar semantiği

  • before_tool_call: { block: true } döndürmek nihaidir. Herhangi bir işleyici bunu ayarladığında, daha düşük öncelikli işleyiciler atlanır.
  • before_tool_call: { block: false } döndürmek bir karar verilmemiş olarak değerlendirilir (block alanını hiç vermemekle aynıdır), geçersiz kılma olarak değil.
  • before_install: { block: true } döndürmek nihaidir. Herhangi bir işleyici bunu ayarladığında, daha düşük öncelikli işleyiciler atlanır.
  • before_install: { block: false } döndürmek bir karar verilmemiş olarak değerlendirilir (block alanını hiç vermemekle aynıdır), geçersiz kılma olarak değil.
  • message_sending: { cancel: true } döndürmek nihaidir. Herhangi bir işleyici bunu ayarladığında, daha düşük öncelikli işleyiciler atlanır.
  • message_sending: { cancel: false } döndürmek bir karar verilmemiş olarak değerlendirilir (cancel alanını hiç vermemekle aynıdır), geçersiz kılma olarak değil.

​
API nesnesi alanları

AlanTürAçıklama
api.idstringPlugin kimliği
api.namestringGörünen ad
api.versionstring?Plugin sürümü (isteğe bağlı)
api.descriptionstring?Plugin açıklaması (isteğe bağlı)
api.sourcestringPlugin kaynak yolu
api.rootDirstring?Plugin kök dizini (isteğe bağlı)
api.configOpenClawConfigGeçerli yapılandırma anlık görüntüsü (varsa etkin bellek içi runtime anlık görüntüsü)
api.pluginConfigRecord<string, unknown>plugins.entries.<id>.config içinden plugin’e özgü yapılandırma
api.runtimePluginRuntimeRuntime yardımcıları
api.loggerPluginLoggerKapsamlı logger (debug, info, warn, error)
api.registrationModePluginRegistrationModeGeçerli yükleme modu; "setup-runtime" hafif tam-giriş-öncesi başlangıç/kurulum penceresidir
api.resolvePath(input)(string) => stringPlugin köküne göre yolu çözümle

​
Dahili modül kuralı

Plugininiz içinde dahili içe aktarmalar için yerel barrel dosyaları kullanın: 
my-plugin/
  api.ts            # Harici kullanıcılar için herkese açık dışa aktarımlar
  runtime-api.ts    # Yalnızca dahili runtime dışa aktarımları
  index.ts          # Plugin giriş noktası
  setup-entry.ts    # Yalnızca kurulum için hafif giriş (isteğe bağlı)
Üretim kodunda kendi plugininizi asla openclaw/plugin-sdk/<your-plugin> üzerinden içe aktarmayın. Dahili içe aktarmaları ./api.ts veya ./runtime-api.ts üzerinden yönlendirin. SDK yolu yalnızca harici sözleşmedir.
Cephe yüklü paketlenmiş plugin herkese açık yüzeyleri (api.ts, runtime-api.ts, index.ts, setup-entry.ts ve benzer herkese açık giriş dosyaları), OpenClaw zaten çalışıyorsa artık etkin runtime yapılandırma anlık görüntüsünü tercih eder. Henüz runtime anlık görüntüsü yoksa, diskteki çözümlenmiş yapılandırma dosyasına geri dönerler. Provider pluginleri ayrıca, bir yardımcı bilinçli olarak provider’a özgüyse ve henüz genel bir SDK alt yoluna ait değilse dar bir plugin-yerel sözleşme barrel dosyası da sunabilir. Mevcut paketlenmiş örnek: Anthropic provider, Claude akış yardımcılarını, Anthropic beta-header ve service_tier mantığını genel bir plugin-sdk/* sözleşmesine yükseltmek yerine kendi herkese açık api.ts / contract-api.ts yüzeyinde tutar. Diğer güncel paketlenmiş örnekler:
  • @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
Extension üretim kodu da openclaw/plugin-sdk/<other-plugin> içe aktarmalarından kaçınmalıdır. Bir yardımcı gerçekten paylaşılıyorsa, iki plugini birbirine bağlamak yerine onu openclaw/plugin-sdk/speech, .../provider-model-shared veya başka bir yetenek odaklı yüzey gibi tarafsız bir SDK alt yoluna yükseltin.

​
İlgili