Plugin oluşturma

Pluginler, çekirdeği değiştirmeden OpenClaw'ı genişletir. Bir plugin; mesajlaşma kanalı, model sağlayıcısı, yerel CLI arka ucu, aracı aracı, kanca, medya sağlayıcısı veya plugin tarafından yönetilen başka bir yetenek ekleyebilir.

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

openclaw plugins install clawhub:<package-name>

Yalın paket tanımları, kullanıma geçiş sürecinde npm'den 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. Kaynak kopyasında plugin geliştirme yalnızca pnpm ile yapılır; çünkü OpenClaw, paketlenmiş pluginleri extensions/* çalışma alanı paketlerinden keşfeder.

Plugin yapısını seçme

Hızlı başlangıç

Zorunlu bir aracı aracını 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. Zorunlu araçlar, plugin etkinleştirildiğinde her zaman kullanılabilir. İsteğe bağlı araçlarda OpenClaw'ın sahip plugin çalışma zamanını yüklemesinden önce kullanıcının açıkça etkinleştirmesi gerekir.

Araç fabrikaları; deliveryContext, kullanılabilir olduğunda etkin platform görüşmesi için nativeChannelId ve requesterSenderId dâhil olmak üzere güvenilir ç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"] }, // or ["my-plugin"] for every tool from one plugin}

İsteğe bağlı araçlar, bir aracın modele sunulup sunulmayacağını denetler. Bir araç veya kancanın, model onu seçtikten sonra ve eylem çalışmadan önce onay istemesi gerekiyorsa plugin izin isteklerini kullanın.

İsteğe bağlı araçları yan etkiler, alışılmadık 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ılamasında bildirilir. Hatalı kayıtlar da aynı şekilde atlanıp bildirilir: eksik veya boş bir name, işlev olmayan bir execute ya da parameters nesnesi bulunmayan bir araç tanımlayıcısı.

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; bu nesne 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 ele alın. Hassas yerel araçlar yine de açık bir plugin veya operatör onayı gerektirmeli ve etkin model meta verileri eksik ya da uygunsuz olduğunda kapalı biçimde başarısız olmalıdır.

Manifest sahipliği ve keşfi bildirir; yürütme ise canlı olarak kaydedilmiş araç uygulamasını çağırmaya devam eder. OpenClaw'ın araç açıkça izin verilenler listesine eklenene kadar ilgili plugin çalışma zamanını yüklememesini sağlamak 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:

Kullanımdan kaldırılan 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, 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ı 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 sonucuna çözümlenir. openclaw/plugin-sdk/gateway-method-runtime köprüsü, contracts.gatewayMethodDispatch: ["authenticated-request"] bildiren plugin HTTP yolları için ayrılmıştır.

İçe aktarma haritasının tamamı için Plugin SDK genel bakışı sayfasına bakı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 aktarımlar odaklanmış plugin-sdk/<subpath> yollarını kullanıyor OPENCLAW_DOCS_MARKER:calloutClose: