Building Plugins

Plugins, OpenClaw’ı yeni yeteneklerle genişletir: kanallar, model sağlayıcıları, konuşma, gerçek zamanlı transkripsiyon, gerçek zamanlı ses, medya anlama, görsel oluşturma, video oluşturma, web getirme, web arama, agent araçları veya bunların herhangi bir kombinasyonu. Plugin’inizi OpenClaw deposuna eklemeniz gerekmez. Şuraya yayımlayın: ClawHub veya npm, ardından kullanıcılar openclaw plugins install <package-name> ile yükler. OpenClaw önce ClawHub’ı dener ve ardından otomatik olarak npm’e geri döner.

Önkoşullar

Node >= 22 ve bir paket yöneticisi (npm veya pnpm)
TypeScript (ESM) bilgisi
Depo içi plugin’ler için: depo klonlanmış olmalı ve pnpm install çalıştırılmış olmalı

Ne tür bir plugin?

Kanal plugin'i

OpenClaw’ı bir mesajlaşma platformuna bağlayın (Discord, IRC vb.)

Sağlayıcı plugin'i

Bir model sağlayıcısı ekleyin (LLM, proxy veya özel uç nokta)

Araç / hook plugin'i

Agent araçları, olay hook’ları veya hizmetleri kaydedin — aşağıdan devam edin

Bir kanal plugin’i isteğe bağlıysa ve onboarding/kurulum çalıştığında yüklü olmayabilirse, openclaw/plugin-sdk/channel-setup içinden createOptionalChannelSetupSurface(...) kullanın. Bu, yükleme gereksinimini duyuran ve plugin yüklenene kadar gerçek yapılandırma yazımlarında güvenli şekilde başarısız olan bir kurulum bağdaştırıcısı + sihirbaz çifti üretir.

Hızlı başlangıç: araç plugin’i

Bu rehber, bir agent aracı kaydeden minimal bir plugin oluşturur. Kanal ve sağlayıcı plugin’leri için yukarıda bağlantısı verilen özel rehberler vardır.

Paketi ve manifest'i oluşturun

{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "compat": {
      "pluginApi": ">=2026.3.24-beta.2",
      "minGatewayVersion": "2026.3.24-beta.2"
    },
    "build": {
      "openclawVersion": "2026.3.24-beta.2",
      "pluginSdkVersion": "2026.3.24-beta.2"
    }
  }
}

Her plugin’in bir manifest’e ihtiyacı vardır; yapılandırma olmasa bile. Tam şema için Manifest sayfasına bakın. Kanonik ClawHub yayımlama parçacıkları docs/snippets/plugin-publish/ içinde bulunur.

Giriş noktasını yazın

// index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { Type } from "@sinclair/typebox";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Adds a custom tool to OpenClaw",
  register(api) {
    api.registerTool({
      name: "my_tool",
      description: "Do a thing",
      parameters: Type.Object({ input: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: `Got: ${params.input}` }] };
      },
    });
  },
});

definePluginEntry, kanal olmayan plugin’ler içindir. Kanallar için defineChannelPluginEntry kullanın — bkz. Channel Plugins. Tam giriş noktası seçenekleri için bkz. Entry Points.

Test edin ve yayımlayın

Harici plugin’ler: ClawHub ile doğrulayın ve yayımlayın, sonra yükleyin:

clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
openclaw plugins install clawhub:@myorg/openclaw-my-plugin

OpenClaw, @myorg/openclaw-my-plugin gibi yalın paket belirtimleri için npm’den önce ClawHub’ı da kontrol eder.Depo içi plugin’ler: paketlenmiş plugin çalışma alanı ağacının altına yerleştirin — otomatik olarak keşfedilir.

pnpm test -- <bundled-plugin-root>/my-plugin/

Plugin yetenekleri

Tek bir plugin, api nesnesi üzerinden istediği sayıda yetenek kaydedebilir:

Yetenek	Kayıt yöntemi	Ayrıntılı rehber
Metin çıkarımı (LLM)	`api.registerProvider(...)`	Provider Plugins
CLI çıkarım arka ucu	`api.registerCliBackend(...)`	CLI Backends
Kanal / mesajlaşma	`api.registerChannel(...)`	Channel Plugins
Konuşma (TTS/STT)	`api.registerSpeechProvider(...)`	Provider Plugins
Gerçek zamanlı transkripsiyon	`api.registerRealtimeTranscriptionProvider(...)`	Provider Plugins
Gerçek zamanlı ses	`api.registerRealtimeVoiceProvider(...)`	Provider Plugins
Medya anlama	`api.registerMediaUnderstandingProvider(...)`	Provider Plugins
Görsel oluşturma	`api.registerImageGenerationProvider(...)`	Provider Plugins
Video oluşturma	`api.registerVideoGenerationProvider(...)`	Provider Plugins
Web getirme	`api.registerWebFetchProvider(...)`	Provider Plugins
Web arama	`api.registerWebSearchProvider(...)`	Provider Plugins
Agent araçları	`api.registerTool(...)`	Aşağıda
Özel komutlar	`api.registerCommand(...)`	Entry Points
Olay hook’ları	`api.registerHook(...)`	Entry Points
HTTP rotaları	`api.registerHttpRoute(...)`	Internals
CLI alt komutları	`api.registerCli(...)`	Entry Points

Tam kayıt API’si için bkz. SDK Overview. Plugin’iniz özel gateway RPC yöntemleri kaydediyorsa, bunları plugin’e özgü bir önek altında tutun. Çekirdek yönetici ad alanları (config.*, exec.approvals.*, wizard.*, update.*) ayrılmış kalır ve bir plugin daha dar bir kapsam istese bile her zaman operator.admin olarak çözülür. Aklınızda bulundurmanız gereken hook guard semantiği:

before_tool_call: { block: true } nihaidir ve daha düşük öncelikli işleyicileri durdurur.
before_tool_call: { block: false } karar verilmemiş gibi değerlendirilir.
before_tool_call: { requireApproval: true } agent yürütmesini duraklatır ve exec onay katmanı, Telegram düğmeleri, Discord etkileşimleri veya herhangi bir kanaldaki /approve komutu üzerinden kullanıcıdan onay ister.
before_install: { block: true } nihaidir ve daha düşük öncelikli işleyicileri durdurur.
before_install: { block: false } karar verilmemiş gibi değerlendirilir.
message_sending: { cancel: true } nihaidir ve daha düşük öncelikli işleyicileri durdurur.
message_sending: { cancel: false } karar verilmemiş gibi değerlendirilir.

/approve komutu hem exec hem de plugin onaylarını sınırlı geri dönüşle işler: bir exec onay kimliği bulunamadığında OpenClaw aynı kimliği plugin onayları üzerinden yeniden dener. Plugin onay yönlendirmesi, yapılandırmadaki approvals.plugin üzerinden bağımsız olarak yapılandırılabilir. Özel onay akışının aynı sınırlı geri dönüş durumunu algılaması gerekiyorsa, onay süresi dolma dizgelerini elle eşleştirmek yerine openclaw/plugin-sdk/error-runtime içinden isApprovalNotFoundError kullanmayı tercih edin. Ayrıntılar için bkz. SDK Overview hook decision semantics.

Agent araçlarını kaydetme

Araçlar, LLM’nin çağırabildiği türlendirilmiş işlevlerdir. Zorunlu (her zaman kullanılabilir) veya isteğe bağlı (kullanıcının açıkça etkinleştirmesi gerekir) olabilirler:

register(api) {
  // Required tool — always available
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({ input: Type.String() }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });

  // Optional tool — user must add to allowlist
  api.registerTool(
    {
      name: "workflow_tool",
      description: "Run a workflow",
      parameters: Type.Object({ pipeline: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: params.pipeline }] };
      },
    },
    { optional: true },
  );
}

Kullanıcılar isteğe bağlı araçları yapılandırmada etkinleştirir:

{
  tools: { allow: ["workflow_tool"] },
}

Araç adları çekirdek araçlarla çakışmamalıdır (çakışmalar atlanır)
Yan etkileri veya ek ikili gereksinimleri olan araçlar için optional: true kullanın
Kullanıcılar tools.allow içine plugin kimliğini ekleyerek bir plugin’deki tüm araçları etkinleştirebilir

İçe aktarma kuralları

Her zaman odaklı openclaw/plugin-sdk/<subpath> yollarından içe aktarın:

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";

// Wrong: monolithic root (deprecated, will be removed)
import { ... } from "openclaw/plugin-sdk";

Tam alt yol başvurusu için bkz. SDK Overview. Plugin’inizin içinde, dahili içe aktarmalar için yerel barrel dosyaları (api.ts, runtime-api.ts) kullanın — kendi plugin’inizi asla SDK yolu üzerinden içe aktarmayın. Sağlayıcı plugin’leri için, sağlayıcıya özgü yardımcıları gerçekten genel bir ayrım yüzeyi olmadıkça bu paket kökü barrel dosyalarında tutun. Güncel paketlenmiş örnekler:

Anthropic: Claude akış sarmalayıcıları ve service_tier / beta yardımcıları
OpenAI: sağlayıcı oluşturucuları, varsayılan model yardımcıları, gerçek zamanlı sağlayıcılar
OpenRouter: sağlayıcı oluşturucusu ile onboarding/yapılandırma yardımcıları

Bir yardımcı yalnızca bir paketlenmiş sağlayıcı paketi içinde faydalıysa, onu openclaw/plugin-sdk/* içine taşımak yerine ilgili paket kökü ayrım yüzeyinde tutun. Bazı oluşturulmuş openclaw/plugin-sdk/<bundled-id> yardımcı ayrım yüzeyleri, örneğin plugin-sdk/feishu-setup veya plugin-sdk/zalo-setup, paketlenmiş plugin bakımı ve uyumluluğu için hâlâ vardır. Bunları, yeni üçüncü taraf plugin’ler için varsayılan desen olarak değil, ayrılmış yüzeyler olarak ele alın.

Gönderim öncesi kontrol listesi

package.json doğru openclaw meta verilerine sahip

openclaw.plugin.json manifest’i mevcut ve geçerli

Giriş noktası defineChannelPluginEntry veya definePluginEntry kullanıyor

Tüm içe aktarmalar odaklı plugin-sdk/<subpath> yollarını kullanıyor

Dahili içe aktarmalar SDK öz-içe aktarmaları değil, yerel modülleri kullanıyor

Testler geçiyor (pnpm test -- <bundled-plugin-root>/my-plugin/)

pnpm check geçiyor (depo içi plugin’ler)

Beta Sürüm Testi

openclaw/openclaw üzerindeki GitHub sürüm etiketlerini izleyin ve Watch > Releases ile abone olun. Beta etiketleri v2026.3.N-beta.1 gibi görünür. Sürüm duyuruları için resmi OpenClaw X hesabı @openclaw bildirimlerini de açabilirsiniz.
Etiket görünür görünmez plugin’inizi beta etiketiyle test edin. Kararlı sürüm öncesindeki pencere genellikle yalnızca birkaç saattir.
Testten sonra plugin-forum Discord kanalında plugin’inizin başlığında all good veya neyin bozulduğunu yazın. Henüz bir başlığınız yoksa oluşturun.
Bir şey bozulursa, Beta blocker: <plugin-name> - <summary> başlıklı bir issue açın veya mevcut olanı güncelleyin ve beta-blocker etiketini uygulayın. Issue bağlantısını başlığınıza ekleyin.
main için fix(<plugin-id>): beta blocker - <summary> başlıklı bir PR açın ve issue’yu hem PR’da hem de Discord başlığınızda bağlayın. Katkıcılar PR’leri etiketleyemez, bu yüzden başlık, bakımcılar ve otomasyon için PR tarafındaki sinyaldir. PR’si olan engelleyiciler birleştirilir; olmayanlar yine de yayımlanabilir. Bakımcılar beta testi sırasında bu başlıkları izler.
Sessizlik yeşil anlamına gelir. Pencereyi kaçırırsanız, düzeltmeniz büyük olasılıkla bir sonraki döngüye kalır.

Sonraki adımlar

Channel Plugins

Bir mesajlaşma kanal plugin’i oluşturun

Provider Plugins

Bir model sağlayıcı plugin’i oluşturun

SDK Overview

İçe aktarma haritası ve kayıt API başvurusu

Runtime Helpers

api.runtime üzerinden TTS, arama, alt agent

Testing

Test yardımcıları ve desenleri

Plugin Manifest

Tam manifest şeması başvurusu

İlgili

Plugin Architecture — dahili mimari derinlemesine incelemesi
SDK Overview — Plugin SDK başvurusu
Manifest — plugin manifest biçimi
Channel Plugins — kanal plugin’leri oluşturma
Provider Plugins — sağlayıcı plugin’leri oluşturma

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

Building Plugins

Building Plugins

Önkoşullar

Ne tür bir plugin?

Kanal plugin'i

Sağlayıcı plugin'i

Araç / hook plugin'i

Hızlı başlangıç: araç plugin’i

Plugin yetenekleri

Agent araçlarını kaydetme

İçe aktarma kuralları

Gönderim öncesi kontrol listesi

Beta Sürüm Testi

Sonraki adımlar

Channel Plugins

Provider Plugins

SDK Overview

Runtime Helpers

Testing

Plugin Manifest

İlgili

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

​Building Plugins

​Önkoşullar

​Ne tür bir plugin?

Kanal plugin'i

Sağlayıcı plugin'i

Araç / hook plugin'i

​Hızlı başlangıç: araç plugin’i

​Plugin yetenekleri

​Agent araçlarını kaydetme

​İçe aktarma kuralları

​Gönderim öncesi kontrol listesi

​Beta Sürüm Testi

​Sonraki adımlar

Channel Plugins

Provider Plugins

SDK Overview

Runtime Helpers

Testing

Plugin Manifest

​İlgili

Building Plugins

Önkoşullar

Ne tür bir plugin?

Hızlı başlangıç: araç plugin’i

Plugin yetenekleri

Agent araçlarını kaydetme

İçe aktarma kuralları

Gönderim öncesi kontrol listesi

Beta Sürüm Testi

Sonraki adımlar

İlgili