Araç pluginleri

defineToolPlugin, yalnızca ajan tarafından çağrılabilen araçlar ekleyen bir Plugin oluşturur: kanal, model sağlayıcısı, hook, hizmet veya kurulum arka ucu eklemez. OpenClaw’ın Plugin çalışma zamanı kodunu yüklemeden araçları keşfetmek için ihtiyaç duyduğu manifest meta verilerini üretir.

Sağlayıcı, kanal, hook, hizmet veya karma yetenekli Plugin’ler için bunun yerine Plugin oluşturma, Kanal Plugin’leri veya Sağlayıcı Plugin’leri ile başlayın.

Gereksinimler

• Node 22.19+, Node 23.11+ veya Node 24+.
• TypeScript ESM paket çıktısı.
• dependencies içinde typebox (yalnızca devDependencies içinde değil; oluşturulan Plugin bunu çalışma zamanında içe aktarır).
• openclaw/plugin-sdk/tool-plugin dışa aktarımını sunan ilk sürüm olan openclaw >=2026.5.17.
• dist/, openclaw.plugin.json ve package.json dosyalarını dağıtan bir paket kökü.

Hızlı başlangıç

openclaw plugins init stock-quotes --name "Stock Quotes"cd stock-quotesnpm installnpm run plugin:buildnpm run plugin:validatenpm test

plugins init şunların iskeletini oluşturur:

npm run plugin:build, npm run build (tsc) komutunu ve ardından openclaw plugins build --entry ./dist/index.js komutunu çalıştırır. npm run plugin:validate, yeniden derler ve openclaw plugins validate --entry ./dist/index.js komutunu çalıştırır. Başarılı doğrulama şu çıktıyı verir:

Plugin stock-quotes is valid.

openclaw plugins init <id> seçenekleri:

Araç yazma

defineToolPlugin, Plugin kimliğini, isteğe bağlı bir yapılandırma şemasını ve statik bir araç listesini alır. Parametre ve yapılandırma türleri TypeBox şemalarından çıkarılır.

  export default defineToolPlugin({  id: "stock-quotes",  name: "Stock Quotes",  description: "Fetch stock quote snapshots.",  configSchema: Type.Object({    apiKey: Type.Optional(Type.String({ description: "Quote API key." })),    baseUrl: Type.Optional(Type.String({ description: "Quote API base URL." })),  }),  tools: (tool) => [    tool({      name: "stock_quote",      label: "Stock Quote",      description: "Fetch a stock quote snapshot.",      parameters: Type.Object({        symbol: Type.String({ description: "Ticker symbol, for example OPEN." }),      }),      async execute({ symbol }, config, context) {        context.signal?.throwIfAborted();        return {          symbol: symbol.toUpperCase(),          configured: Boolean(config.apiKey),          baseUrl: config.baseUrl ?? "https://api.example.com",        };      },    }),  ],});

Araç adları kararlı API’dir. Benzersiz, küçük harfli ve çekirdek araçlarla veya diğer Plugin’lerle çakışmayı önleyecek kadar belirgin adlar seçin.

İsteğe bağlı araçlar ve fabrika araçları

Kullanıcıların aracı bir modele gönderilmeden önce açıkça izin listesine eklemesi gerekiyorsa optional: true ayarlayın. openclaw plugins build, eşleşen toolMetadata.<tool>.optional manifest girdisini yazar; böylece OpenClaw, Plugin çalışma zamanı kodunu yüklemeden aracın isteğe bağlı olduğunu görebilir.

tool({  name: "workflow_run",  description: "Run an external workflow.",  parameters: Type.Object({ goal: Type.String() }),  optional: true,  execute: ({ goal }) => ({ queued: true, goal }),});

Bir aracın oluşturulmadan önce çalışma zamanı araç bağlamına ihtiyacı olduğunda factory kullanın: belirli bir çalıştırmadan vazgeçmek, korumalı alan durumunu incelemek veya çalışma zamanı yardımcılarını bağlamak için. Somut araç çalışma zamanında oluşturulsa bile meta veriler statik kalır.

tool({  name: "local_workflow",  description: "Run a local workflow outside sandboxed sessions.",  parameters: Type.Object({ goal: Type.String() }),  optional: true,  factory({ api, toolContext }) {    if (toolContext.sandboxed) {      return null;    }    return createLocalWorkflowTool(api);  },});

Fabrikalar yine de sabit bir araç adını önceden bildirir. Plugin araç adlarını dinamik olarak hesaplıyorsa veya araçları hook’lar, hizmetler, sağlayıcılar ya da komutlarla birleştiriyorsa doğrudan definePluginEntry kullanın.

Dönüş değerleri

defineToolPlugin, düz dönüş değerlerini OpenClaw araç sonucu biçimine sarar:

• Modelin tam olarak bu metni görmesi gerektiğinde bir dize döndürün.
• Modelin biçimlendirilmiş JSON görmesini ve OpenClaw’ın özgün değeri details içinde tutmasını istediğinizde JSON ile uyumlu bir değer döndürün.

tool({  name: "echo_text",  description: "Echo input text.",  parameters: Type.Object({    input: Type.String(),  }),  execute: ({ input }) => input,});

tool({  name: "echo_json",  description: "Echo input as structured JSON.",  parameters: Type.Object({    input: Type.String(),  }),  execute: ({ input }) => ({ input, length: input.length }),});

Özel bir AgentToolResult gerektiğinde veya mevcut bir api.registerTool uygulamasını yeniden kullanmak istediğinizde fabrika aracı kullanın.

Yapılandırma

configSchema isteğe bağlıdır. Bunu atlarsanız OpenClaw katı bir boş nesne şeması uygular; oluşturulan manifest yine de configSchema içerir.

export default defineToolPlugin({  id: "no-config-tools",  name: "No Config Tools",  description: "Adds tools that do not need configuration.",  tools: () => [],});

Bir configSchema kullanıldığında ikinci execute bağımsız değişkeninin türü bu şemadan belirlenir:

const configSchema = Type.Object({  apiKey: Type.String(),}); export default defineToolPlugin({  id: "configured-tools",  name: "Configured Tools",  description: "Adds configured tools.",  configSchema,  tools: (tool) => [    tool({      name: "configured_ping",      description: "Check whether configuration is available.",      parameters: Type.Object({}),      execute: (_params, config) => ({ hasKey: config.apiKey.length > 0 }),    }),  ],});

OpenClaw, Plugin yapılandırmasını Gateway yapılandırmasındaki Plugin girdisinden okur. Kaynak kodda veya dokümantasyon örneklerinde gizli bilgileri sabit kodlamayın; Plugin’in güvenlik modeline göre yapılandırma, ortam değişkenleri veya SecretRef’ler kullanın.

Oluşturulan meta veriler

OpenClaw, Plugin çalışma zamanı kodunu içe aktarmadan önce Plugin manifestini okumalıdır. defineToolPlugin bunun için statik meta veriler sunar ve openclaw plugins build bunları pakete yazar. Plugin kimliği, adı, açıklaması, yapılandırma şeması, etkinleştirme ayarları veya araç adları değiştirildikten sonra oluşturucuyu yeniden çalıştırın:

npm run buildopenclaw plugins build --entry ./dist/index.js

Tek araçlı bir Plugin için oluşturulan manifest:

{  "id": "stock-quotes",  "name": "Stock Quotes",  "description": "Fetch stock quote snapshots.",  "version": "0.1.0",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  },  "activation": {    "onStartup": true  },  "contracts": {    "tools": ["stock_quote"]  }}

contracts.tools önemli keşif sözleşmesidir: kurulu tüm Plugin’lerin çalışma zamanını yüklemeden her aracın hangi Plugin’e ait olduğunu OpenClaw’a bildirir. Güncelliğini yitirmiş bir manifest, bir aracın keşifte görünmemesine veya bir kayıt hatasının yanlış Plugin’e yüklenmesine neden olabilir.

Paket meta verileri

openclaw plugins build, package.json dosyasını da seçilen çalışma zamanı giriş noktasıyla hizalar:

{  "type": "module",  "files": ["dist", "openclaw.plugin.json", "README.md"],  "dependencies": {    "typebox": "^1.1.38"  },  "peerDependencies": {    "openclaw": ">=2026.5.17"  },  "openclaw": {    "extensions": ["./dist/index.js"]  }}

TypeScript kaynak giriş noktasını değil, derlenmiş JavaScript’i (./dist/index.js) dağıtın. Kaynak giriş noktaları yalnızca çalışma alanına özgü yerel geliştirmede çalışır.

CI’da doğrulama

Oluşturulan meta veriler güncel olmadığında plugins build --check, dosyaları yeniden yazmadan başarısız olur:

npm run buildopenclaw plugins build --entry ./dist/index.js --checkopenclaw plugins validate --entry ./dist/index.jsnpm test

plugins validate şunları denetler:

• openclaw.plugin.json dosyasının var olması ve normal manifest yükleyiciden geçmesi.
• Geçerli giriş noktasının defineToolPlugin meta verilerini dışa aktarması.
• Oluşturulan manifest alanlarının giriş noktası meta verileriyle eşleşmesi.
• contracts.tools değerinin bildirilen araç adlarıyla eşleşmesi.
• package.json içindeki openclaw.extensions değerinin seçilen çalışma zamanı giriş noktasını göstermesi.

Yerel olarak kurma ve inceleme

Ayrı bir OpenClaw çalışma kopyasından veya kurulu CLI’dan paket yolunu kurun:

openclaw plugins install ./stock-quotesopenclaw plugins inspect stock-quotes --runtime

Paketlenmiş bir duman testi için önce paketi oluşturun ve tarball dosyasını kurun:

npm packopenclaw plugins install npm-pack:./openclaw-plugin-stock-quotes-0.1.0.tgzopenclaw plugins inspect stock-quotes --runtime --json

Kurulumdan sonra Gateway’i yeniden başlatın veya yeniden yükleyin ve ajandan aracı kullanmasını isteyin. Araç görünmüyorsa kodu değiştirmeden önce Plugin çalışma zamanını ve geçerli araç kataloğunu inceleyin (bkz. Sorun giderme).

Yayımlama

Paket hazır olduğunda ClawHub üzerinden yayımlayın. clawhub package publish bir kaynak kabul eder: yerel klasör, GitHub deposu (owner/repo[@ref]) veya tarball URL’si.

clawhub package publish ./stock-quotes --dry-runclawhub package publish ./stock-quotes

Açık bir ClawHub konum belirleyicisiyle kurun:

openclaw plugins install clawhub:your-org/stock-quotes

Çıplak npm paket tanımları, geçiş dönemi boyunca npm’den kurulmaya devam eder; ancak OpenClaw Plugin’leri için tercih edilen keşif ve dağıtım yüzeyi ClawHub’dır. Sahip kapsamı ve sürüm incelemesi için ClawHub’da yayımlama bölümüne bakın.

Sorun giderme

plugin entry not found: ./dist/index.js

Seçilen giriş dosyası mevcut değil. npm run build komutunu çalıştırın, ardından openclaw plugins build --entry ./dist/index.js veya openclaw plugins validate --entry ./dist/index.js komutunu yeniden çalıştırın.

plugin entry does not expose defineToolPlugin metadata

Giriş noktası, defineToolPlugin tarafından oluşturulan bir değeri dışa aktarmadı. Modülün varsayılan dışa aktarımının defineToolPlugin(...) sonucu olduğunu doğrulayın veya --entry ile doğru giriş noktasını belirtin.

openclaw.plugin.json generated metadata is stale

Manifest artık giriş noktası meta verileriyle eşleşmiyor. Şunları çalıştırın:

npm run buildopenclaw plugins build --entry ./dist/index.js

Hem openclaw.plugin.json hem de package.json değişikliklerini kaydedin.

package.json openclaw.extensions must include ./dist/index.js

Paket meta verileri farklı bir çalışma zamanı giriş noktasını gösteriyor. Oluşturucunun paket meta verilerini dağıtmayı amaçladığınız giriş noktasıyla hizalaması için openclaw plugins build --entry ./dist/index.js komutunu çalıştırın.

Cannot find package 'typebox'

Derlenmiş Plugin, çalışma zamanında typebox paketini içe aktarır. Paketi dependencies içinde tutun; bağımlılıkları yeniden kurun, yeniden derleyin ve doğrulamayı yeniden çalıştırın.

Araç kurulumdan sonra görünmüyor

Şunları sırayla denetleyin:

1. openclaw plugins inspect <plugin-id> --runtime
2. openclaw plugins validate --root <plugin-root> --entry ./dist/index.js
3. openclaw.plugin.json, beklenen araç adlarını içeren contracts.tools alanına sahiptir.
4. package.json, openclaw.extensions: ["./dist/index.js"] alanına sahiptir.
5. Plugin yüklendikten sonra Gateway yeniden başlatıldı veya yeniden yüklendi.

Ayrıca bakınız

• Plugin oluşturma
• Plugin giriş noktaları
• Plugin SDK alt yolları
• Plugin manifesti
• Plugin CLI'si
• ClawHub'da yayımlama