Plugin oluşturma

Plugin'ler, ç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ı, kanca, medya sağlayıcısı veya plugin'in sahip olduğu başka bir yetenek ekleyebilir.

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

openclaw plugins install clawhub:<package-name>

Çıplak paket belirtimleri, kullanıma geçiş sürecinde npm üzerinden yüklenmeye devam eder. ClawHub çözümlemesi istediğinizde clawhub: önekini kullanın.

Gereksinimler

• Node 22.22.3+, Node 24.15+ veya Node 25.9+ ve npm ya da pnpm.
• TypeScript ESM modülleri.
• Depo içindeki paketlenmiş plugin çalışmaları için depoyu klonlayın ve pnpm install komutunu çalıştırın. OpenClaw, paketlenmiş plugin'leri extensions/* çalışma alanı paketlerinden keşfettiği için kaynak kod kullanıma alma üzerinden plugin geliştirme yalnızca pnpm ile yapılır.

Plugin biçimini seçme

Hızlı başlangıç

Gerekli bir ajan aracını kaydederek asgari bir araç plugin'i oluşturun. Bu, kullanışlı en kısa plugin biçimidir 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() }),      outputSchema: Type.Object(        { input: Type.String() },        { additionalProperties: false },      ),      async execute(_id, params) {        const details = { input: params.input };        return {          content: [{ type: "text", text: `Got: ${params.input}` }],          details,        };      },    });  },});

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 gerekli veya isteğe bağlı olabilir. Gerekli araçlar, plugin etkin olduğunda her zaman kullanılabilir. İsteğe bağlı araçların, OpenClaw sahip plugin çalışma zamanını yüklemeden önce kullanıcının açıkça kabul etmesini gerektirir.

Araç fabrikaları; deliveryContext, mevcut olduğunda etkin platform görüşmesi için nativeChannelId ve requesterSenderId dahil 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() }),      outputSchema: Type.Object(        { pipeline: Type.String() },        { additionalProperties: false },      ),      async execute(_id, params) {        return {          content: [{ type: "text", text: params.pipeline }],          details: { pipeline: params.pipeline },        };      },    },    { optional: true },  );}

outputSchema isteğe bağlıdır. Kod Modu ve Araç Arama tarafından kullanılan yapılandırılmış details değerini açıklar. Katalog çağrıları, yürütmeden önce geçersiz şemaları reddeder ve araç kancalarından sonra nihai değeri doğrular. Kararlı bir JSON sonucu olmayan araçlarda bunu kullanmayın. Sözleşmenin tamamı için Araç plugin'leri bölümüne bakın.

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 katılım sağlar:

{  tools: { allow: ["workflow_tool"] }, // veya bir plugin'in 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 kancanın model tarafından seçilmesinden sonra ve eylem çalışmadan önce onay istemesi gerekiyorsa plugin izin isteklerini kullanın.

İsteğe bağlı araçları yan etkiler, sıra dışı ikili dosyalar veya varsayılan olarak sunulmaması gereken yetenekler için 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 öğesinin eksik olması, execute öğesinin işlev olmaması veya parameters nesnesi bulunmayan bir araç tanımlayıcısı.

Araç fabrikaları, çalışma zamanının sağladığı bir bağlam nesnesi alır. Bir aracın geçerli dönüşte etkin modeli günlüğe kaydetmesi, görüntülemesi veya modele uyarlanması gerektiğinde ctx.activeModel kullanın; bu, 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 katılımı gerektirmeli ve etkin model meta verisi eksik ya da uygun değilse kapalı şekilde başarısız olmalıdır.

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

İçe aktarma kuralları

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

Plugin paketinizde, dahili içe aktarımlar için api.ts ve runtime-api.ts gibi yerel barrel dosyalarını kullanın. Kendi plugin'inizi bir SDK yolu üzerinden içe aktarmayın. Sağlayıcıya özgü yardımcılar, bağlantı 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ı plugin'e özgü bir önekte tutun; config.*, exec.approvals.*, operator.admin.*, wizard.* ve update.* gibi çekirdek yönetici 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ı için ayrılmıştır.

İçe aktarma haritasının tamamı için Plugin SDK'ya genel bakış bölümüne bakın.

OpenClaw SDK uyumluluk alanları, düzenleyicilerin geçiş uyarıları olarak gösterdiği TypeScript @deprecated ek açıklamalarını taşır. Bunları derleme sırasında zorunlu kılmak için @typescript-eslint/no-deprecated gibi tür bilgisine duyarlı bir kuralı etkinleştirin. Oxlint tür bilgisine duyarlı olmadığından bu ek açıklamaları zorunlu kılamaz.

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: