Plugin oluşturma

Pluginler, çekirdeği değiştirmeden OpenClaw'u genişletir. Bir plugin; mesajlaşma kanalı, model sağlayıcısı, yerel CLI arka ucu, ajan aracı, hook, medya sağlayıcısı veya pluginin sahip olduğu başka bir yetenek ekleyebilir.

Harici bir plugini OpenClaw deposuna eklemeniz gerekmez. Paketi ClawHub üzerinde yayımlayın; kullanıcılar paketi şu komutla yükler:

openclaw plugins install clawhub:<package-name>

Başlatma geçişi sırasında öneksiz paket belirtimleri npm'den yüklenmeye devam eder. ClawHub çözümlemesini istediğinizde clawhub: önekini kullanın.

Gereksinimler

• Node 22.19+, Node 23.11+ veya Node 24+ ile npm ya da pnpm.
• TypeScript ESM modülleri.
• Depoda paketlenmiş plugin çalışmaları için depoyu klonlayın ve pnpm install komutunu çalıştırın. OpenClaw, paketlenmiş pluginleri extensions/* çalışma alanı paketlerinden keşfettiği için kaynak kod çıkışında plugin geliştirme yalnızca pnpm ile yapılabilir.

Plugin yapısını seçme

Hızlı başlangıç

Bir zorunlu ajan aracı kaydederek asgari bir araç plugini oluşturun. Bu, kullanışlı en kısa plugin yapısıdır ve paketi, manifesti, giriş noktasını ve yerel doğrulamayı kapsar.

{"name": "@myorg/openclaw-my-plugin","version": "1.0.0","type": "module","dependencies": {"typebox": "1.1.39"},"peerDependencies": {"openclaw": ">=2026.3.24-beta.2"},"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}}

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

openclaw plugins inspect my-plugin --runtime --json

pnpm test extensions/my-plugin/pnpm check

npm pack --pack-destination /tmpopenclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --forceopenclaw plugins inspect my-plugin --runtime --json

clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

openclaw plugins install clawhub:your-org/your-plugin

Araçları kaydetme

Araçlar zorunlu veya isteğe bağlı olabilir. Plugin etkinleştirildiğinde zorunlu araçlar her zaman kullanılabilir. İsteğe bağlı araçlarda OpenClaw'un sahip plugin çalışma zamanını yüklemesinden önce kullanıcının açıkça onay vermesi gerekir.

Araç fabrikaları; deliveryContext, mevcut olduğunda etkin platform konuşmasının nativeChannelId değeri ve requesterSenderId dâhil olmak üzere güvenilen çalışma zamanı bağlamını alır.

register(api) {  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 },  );}

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

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

Kullanıcılar tools.allow ile etkinleştirir:

{  tools: { allow: ["workflow_tool"] }, // veya bir plugindeki tüm araçlar için ["my-plugin"]}

İsteğe bağlı araçlar, bir aracın modele sunulup sunulmayacağını denetler. Bir araç veya hook, model tarafından seçildikten sonra ve eylem çalıştırılmadan önce onay istemeliyse plugin izin isteklerini kullanın.

Yan etkiler, alışılmadık ikili dosyalar veya varsayılan olarak sunulmaması gereken yetenekler için isteğe bağlı araçlar kullanın. Araç adları çekirdek araç adlarıyla çakışmamalıdır; çakışmalar atlanır ve plugin tanılamalarında bildirilir. Hatalı kayıtlar da aynı şekilde atlanır ve bildirilir: boş olmayan bir name değerinin eksik olması, execute değerinin işlev olmaması veya araç tanımlayıcısında bir parameters nesnesinin bulunmaması.

Araç fabrikaları, çalışma zamanı tarafından sağlanan bir bağlam nesnesi alır. Bir aracın mevcut turdaki etkin modeli günlüğe kaydetmesi, göstermesi veya ona uyum sağlaması gerektiğinde ctx.activeModel kullanın; bu değer provider, modelId ve modelRef içerebilir. Bunu yerel operatöre, yüklü plugin koduna veya değiştirilmiş bir OpenClaw çalışma zamanına karşı güvenlik sınırı olarak değil, bilgilendirici çalışma zamanı meta verisi olarak değerlendirin. Hassas yerel araçlar yine de açık bir plugin veya operatör etkinleştirmesi gerektirmeli ve etkin model meta verileri eksik veya uygunsuz olduğunda güvenli biçimde başarısız olmalıdır.

Manifest, sahipliği ve keşfi bildirir; yürütme yine canlı olarak kaydedilmiş araç uygulamasını çağırır. OpenClaw'un araç açıkça izin listesine alınana kadar ilgili plugin çalışma zamanını yüklemekten kaçınabilmesi için toolMetadata.<tool>.optional: true ile api.registerTool(..., { optional: true }) değerlerini uyumlu tutun.

İçe aktarma kuralları

Odaklanmış SDK alt yollarından içe aktarın:

Kullanımdan kaldırılmış kök barrel dosyasından içe aktarmayın:

Plugin paketiniz içinde dahili içe aktarımlar için api.ts ve runtime-api.ts gibi yerel barrel dosyalarını kullanın. Kendi plugininizi bir SDK yolu üzerinden içe aktarmayın. Sağlayıcıya özgü yardımcılar, ilgili sınır gerçekten genel olmadığı sürece sağlayıcı paketinde kalmalıdır.

Özel Gateway RPC yöntemleri gelişmiş bir giriş noktasıdır. Bunları plugine özgü bir önek altında tutun; config.*, exec.approvals.*, operator.admin.*, wizard.* ve update.* gibi çekirdek yönetim ad alanları ayrılmış olarak kalır ve operator.admin olarak çözümlenir. openclaw/plugin-sdk/gateway-method-runtime köprüsü, contracts.gatewayMethodDispatch: ["authenticated-request"] bildiren plugin HTTP rotalarına ayrılmıştır.

İçe aktarma haritasının tamamı için Plugin SDK'ya genel bakış sayfasına bakın.

Gönderim öncesi denetim 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 aktarımlar odaklanmış plugin-sdk/<subpath> yollarını kullanıyor OPENCLAW_DOCS_MARKER:calloutClose: