Plugin oluşturma

Plugin'ler, çekirdeği değiştirmeden OpenClaw'ı genişletir. Bir Plugin bir mesajlaşma kanalı, model sağlayıcısı, yerel CLI arka ucu, agent aracı, hook, medya sağlayıcısı veya Plugin'e ait başka bir yetenek ekleyebilir.

OpenClaw deposuna harici bir Plugin eklemeniz gerekmez. Paketi ClawHub üzerinde yayımlayın; kullanıcılar şu komutla kurar:

openclaw plugins install clawhub:<package-name>

Çıplak paket belirtimleri, lansman geçişi sırasında hâlâ npm üzerinden kurulur. ClawHub çözümlemesi istediğinizde clawhub: önekini kullanın.

Gereksinimler

• Node 22.19+, Node 23.11+ veya Node 24+ ve npm ya da pnpm gibi bir paket yöneticisi kullanın.
• TypeScript ESM modüllerine aşina olun.
• Depo içi paketlenmiş Plugin çalışması için depoyu klonlayın ve pnpm install çalıştırın. Kaynak checkout Plugin geliştirmesi yalnızca pnpm kullanır, çünkü OpenClaw paketlenmiş Plugin'leri extensions/* workspace paketlerinden yükler.

Plugin biçimini seçin

Hızlı başlangıç

Gerekli tek bir agent aracı kaydederek en küçük araç Plugin'ini oluşturun. Bu, en kısa kullanışlı Plugin biçimidir ve paketi, manifesti, giriş noktasını ve yerel kanıtı gösterir.

{"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 gerekli veya isteğe bağlı olabilir. Gerekli araçlar, Plugin etkinken her zaman kullanılabilir. İsteğe bağlı araçlar kullanıcı opt-in'i gerektirir.

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 opt-in yapar:

{  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for all tools from one plugin}

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

Varsayılan olarak sunulmaması gereken yan etkiler, alışılmadık ikili dosyalar veya yetenekler için isteğe bağlı araçları kullanın. Araç adları çekirdek araçlarla çakışmamalıdır; çakışmalar atlanır ve Plugin tanılamalarında raporlanır. parameters içermeyen araç tanımlayıcıları dahil hatalı biçimlendirilmiş kayıtlar da aynı şekilde atlanır ve raporlanır. Kayıtlı araçlar, policy ve izin listesi kontrolleri geçtikten sonra modelin çağırabileceği tipli fonksiyonlardır.

Araç factory'leri runtime tarafından sağlanan bir context nesnesi alır. Bir aracın geçerli turdaki etkin modeli günlüğe yazması, göstermesi 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ş OpenClaw runtime'ına karşı bir güvenlik sınırı olarak değil, bilgilendirici runtime metadata'sı olarak ele alın. Hassas yerel araçlar hâlâ açık bir Plugin veya operatör opt-in'i gerektirmeli ve etkin model metadata'sı eksik ya da uygunsuz olduğunda kapalı başarısız olmalıdır.

Manifest sahipliği ve keşfi bildirir; yürütme yine canlı kayıtlı araç uygulamasını çağırır. toolMetadata.<tool>.optional: true değerini api.registerTool(..., { optional: true }) ile hizalı tutun; böylece OpenClaw, araç açıkça izin listesine alınana kadar o Plugin runtime'ını yüklemekten kaçınabilir.

Import kuralları

Odaklı SDK alt yollarından import edin:

Kullanımdan kaldırılmış kök barrel'dan import etmeyin:

Plugin paketiniz içinde, dahili import'lar için api.ts ve runtime-api.ts gibi yerel barrel dosyaları kullanın. Kendi Plugin'inizi bir SDK yolu üzerinden import etmeyin. Sağlayıcıya özgü yardımcılar, arayüz gerçekten genel olmadıkça sağlayıcı paketinde kalmalıdır.

Özel Gateway RPC yöntemleri ileri düzey bir giriş noktasıdır. Bunları Plugin'e özgü bir önekte tutun; config.*, exec.approvals.*, operator.admin.*, wizard.* ve update.* gibi çekirdek yönetici namespace'leri ayrılmış 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.

Tam import haritası için Plugin SDK genel bakışı bölümüne bakın.

Gönderim öncesi kontrol listesi

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json doğru openclaw metadata'sına 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 import'lar odaklı plugin-sdk/<subpath> yollarını kullanıyor OPENCLAW_DOCS_MARKER:calloutClose: