Plugin oluşturma

Plugin'ler OpenClaw'a yeni yetenekler ekler: kanallar, model sağlayıcıları, konuşma, gerçek zamanlı transkripsiyon, gerçek zamanlı ses, medya anlama, görüntü üretimi, video üretimi, web getirme, web arama, ajan araçları veya bunların herhangi bir kombinasyonu.

Plugin'inizi OpenClaw deposuna eklemeniz gerekmez. ClawHub'da yayımlayın; kullanıcılar openclaw plugins install clawhub:<package-name> ile yükler. Yalın paket belirtimleri, lansman geçişi sırasında hâlâ npm'den yüklenir.

Önkoşullar

• Node >= 22 ve bir paket yöneticisi (npm veya pnpm)
• TypeScript (ESM) bilgisi
• Depo içi Plugin'ler için: depo klonlanmış ve pnpm install yapılmış olmalıdır. Kaynak checkout'unda Plugin geliştirme yalnızca pnpm ile yapılır, çünkü OpenClaw paketlenmiş Plugin'leri extensions/* çalışma alanı paketlerinden yükler.

Ne tür bir Plugin?

İlk kurulum/kurulum çalıştığında yüklü olduğu garanti edilmeyen bir kanal Plugin'i için 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 yazmalarında güvenli biçimde başarısız olan bir kurulum adaptörü + sihirbaz çifti üretir.

Hızlı başlangıç: araç Plugin'i

Bu adım adım kılavuz, bir ajan aracı kaydeden minimal bir Plugin oluşturur. Kanal ve sağlayıcı Plugin'leri için yukarıda bağlantısı verilen özel kılavuzlar vardır.

{"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"  }}}

{"id": "my-plugin","name": "My Plugin","description": "Adds a custom tool to OpenClaw","contracts": {  "tools": ["my_tool"]},"activation": {  "onStartup": true},"configSchema": {  "type": "object",  "additionalProperties": false}}

// index.tsimport { 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}` }] };      },    });  },});

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

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

Plugin yetenekleri

Tek bir Plugin, api nesnesi üzerinden herhangi sayıda yetenek kaydedebilir:

Tam kayıt API'si için SDK Genel Bakışı bölümüne bakın.

Paketlenmiş Plugin'ler, model çıktıyı görmeden önce eşzamansız araç sonucu yeniden yazmaya ihtiyaç duyduklarında api.registerAgentToolResultMiddleware(...) kullanabilir. Hedeflenen çalışma zamanlarını contracts.agentToolResultMiddleware içinde beyan edin; örneğin ["pi", "codex"]. Bu, güvenilen bir paketlenmiş Plugin entegrasyon noktasıdır; harici Plugin'ler, OpenClaw bu yetenek için açık bir güven ilkesi geliştirmedikçe normal OpenClaw Plugin kancalarını tercih etmelidir.

Plugin'iniz özel Gateway RPC yöntemleri kaydediyorsa, bunları Plugin'e özgü bir önek altında tutun. Çekirdek yönetim 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ümlenir.

Aklınızda tutmanız gereken kanca koruması semantikleri:

• before_tool_call: { block: true } sonlandırıcıdır ve daha düşük öncelikli işleyicileri durdurur.
• before_tool_call: { block: false } karar yok olarak ele alınır.
• before_tool_call: { requireApproval: true } ajan 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 } sonlandırıcıdır ve daha düşük öncelikli işleyicileri durdurur.
• before_install: { block: false } karar yok olarak ele alınır.
• message_sending: { cancel: true } sonlandırıcıdır ve daha düşük öncelikli işleyicileri durdurur.
• message_sending: { cancel: false } karar yok olarak ele alınır.
• message_received: gelen iş parçacığı/konu yönlendirmesine ihtiyaç duyduğunuzda tiplendirilmiş threadId alanını tercih edin. Kanala özgü ekler için metadata değerini kullanın.
• message_sending: kanala özgü metadata anahtarları yerine tiplendirilmiş replyToId / threadId yönlendirme alanlarını tercih edin.

/approve komutu hem exec hem de Plugin onaylarını sınırlı fallback ile işler: bir exec onayı kimliği bulunmadığında OpenClaw aynı kimliği Plugin onayları üzerinden yeniden dener. Plugin onayı yönlendirmesi, yapılandırmada approvals.plugin üzerinden bağımsız olarak yapılandırılabilir.

Özel onay akışının aynı sınırlı fallback durumunu algılaması gerekiyorsa, onay sona erme dizelerini elle eşleştirmek yerine openclaw/plugin-sdk/error-runtime içinden isApprovalNotFoundError kullanmayı tercih edin.

Örnekler ve kanca referansı için Plugin kancaları bölümüne bakın.

Ajan araçlarını kaydetme

Araçlar, LLM'nin çağırabileceği tiplendirilmiş fonksiyonlardır. Zorunlu (her zaman kullanılabilir) veya isteğe bağlı (kullanıcı katılımıyla) 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 },  );}

Araç fabrikaları, çalışma zamanı tarafından sağlanan bir bağlam nesnesi alır. Bir aracın geçerli turdaki etkin modeli günlüğe kaydetmesi, görüntülemesi veya ona uyum sağlaması gerektiğinde ctx.activeModel kullanın. Nesne provider, modelId ve modelRef içerebilir. Bunu yerel operatöre, kurulu Plugin koduna veya değiştirilmiş bir OpenClaw çalışma zamanına karşı bir güvenlik sınırı olarak değil, bilgilendirici çalışma zamanı meta verisi olarak ele alın. Hassas yerel araçlar için açık bir Plugin veya operatör katılım onayı bulundurun ve etkin model meta verisi eksik ya da uygun değilse kapalı şekilde başarısız olun.

api.registerTool(...) ile kaydedilen her araç, Plugin manifestinde de bildirilmelidir:

{  "contracts": {    "tools": ["my_tool", "workflow_tool"]  },  "toolMetadata": {    "workflow_tool": {      "optional": true    }  }}

OpenClaw, kayıtlı araçtan doğrulanmış tanımlayıcıyı yakalar ve önbelleğe alır; bu nedenle Plugin'ler manifestte description veya şema verilerini yinelemez. Manifest sözleşmesi yalnızca sahipliği ve keşfi bildirir; yürütme hâlâ canlı kayıtlı araç uygulamasını çağırır. api.registerTool(..., { optional: true }) ile kaydedilen araçlar için toolMetadata.<tool>.optional: true ayarlayın; böylece OpenClaw, araç açıkça izin listesine alınana kadar o Plugin çalışma zamanını yüklemekten kaçınabilir.

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

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

• Araç adları çekirdek araçlarla çakışmamalıdır (çakışmalar atlanır)
• Eksik parameters dahil olmak üzere hatalı biçimlendirilmiş kayıt nesnelerine sahip araçlar atlanır ve ajan çalıştırmalarını bozmak yerine Plugin tanılamalarında raporlanır
• Yan etkileri veya ek ikili gereksinimleri olan araçlar için optional: true kullanın
• Kullanıcılar, Plugin kimliğini tools.allow öğesine ekleyerek bir Plugin'deki tüm araçları etkinleştirebilir

CLI komutlarını kaydetme

Plugin'ler api.registerCli ile kök openclaw komut grupları ekleyebilir. OpenClaw'ın her Plugin çalışma zamanını hevesle yüklemeden komutu gösterebilmesi ve yönlendirebilmesi için her üst düzey komut kökü için descriptors sağlayın.

register(api) {  api.registerCli(    ({ program }) => {      const demo = program        .command("demo-plugin")        .description("Run demo plugin commands");       demo        .command("ping")        .description("Check that the plugin CLI is executable")        .action(() => {          console.log("demo-plugin:pong");        });    },    {      descriptors: [        {          name: "demo-plugin",          description: "Run demo plugin commands",          hasSubcommands: true,        },      ],    },  );}

Kurulumdan sonra çalışma zamanı kaydını doğrulayın ve komutu yürütün:

openclaw plugins inspect demo-plugin --runtime --jsonopenclaw demo-plugin ping

İçe aktarma kuralları

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

  // Wrong: monolithic root (deprecated, will be removed) 

Tam alt yol başvurusu için bkz. SDK Genel Bakış.

Plugin'inizin içinde, dahili içe aktarmalar için yerel barrel dosyalarını (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, bağlantı noktası gerçekten genel değilse sağlayıcıya özgü yardımcıları bu paket kökü barrel'larında tutun. Geçerli paketli ö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şturucu ve ilk kurulum/yapılandırma yardımcıları

Bir yardımcı yalnızca tek bir paketli sağlayıcı paketi içinde kullanışlıysa, onu openclaw/plugin-sdk/* içine yükseltmek yerine o paket kökü bağlantı noktasında tutun.

Paketli Plugin bakımı için, sahip kullanımını izledikleri durumlarda bazı oluşturulmuş openclaw/plugin-sdk/<bundled-id> yardımcı bağlantı noktaları hâlâ mevcuttur. 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

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json doğru openclaw meta verilerine sahip OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s openclaw.plugin.json manifesti mevcut ve geçerli OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Giriş noktası defineChannelPluginEntry veya definePluginEntry kullanıyor OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Tüm içe aktarmalar odaklanmış plugin-sdk/<subpath> yollarını kullanıyor OPENCLAW_DOCS_MARKER:calloutClose: