Plugin oluşturma

Plugin'ler OpenClaw'a yeni yetenekler ekler: kanallar, model sağlayıcıları, konuşma, gerçek zamanlı transkripsiyon, gerçek zamanlı ses, medya anlama, görüntü üretimi, video üretimi, web getirme, web arama, aracı araçları veya bunların herhangi bir kombinasyonu.

Plugin'inizi OpenClaw deposuna eklemeniz gerekmez. ClawHub üzerinde yayımlayın; kullanıcılar openclaw plugins install clawhub:<package-name> ile kurar. Çıplak paket belirtimleri, lansman geçişi sırasında hâlâ npm'den kurulur.

# Önkoşullar

• Node >= 22 ve bir paket yöneticisi (npm veya pnpm)
• TypeScript (ESM) bilgisi
• Depo içi Plugin'ler için: depo klonlanmış ve pnpm install tamamlanmış olmalıdır. Kaynak checkout Plugin geliştirme yalnızca pnpm ile yapılır, çünkü OpenClaw paketlenmiş Plugin'leri extensions/* çalışma alanı paketlerinden yükler.

# Ne tür bir Plugin?

Onboarding/kurulum çalıştığında kurulu olduğu garanti edilmeyen bir kanal Plugin'i için openclaw/plugin-sdk/channel-setup içindeki createOptionalChannelSetupSurface(...) öğesini kullanın. Bu, kurulum gereksinimini duyuran ve Plugin kurulana kadar gerçek yapılandırma yazmalarında kapalı başarısız olan bir kurulum bağdaştırıcısı + sihirbaz çifti üretir.

# Hızlı başlangıç: araç Plugin'i

Bu izlenecek yol, bir aracı aracı kaydeden minimal bir Plugin oluşturur. Kanal ve sağlayıcı Plugin'leri için yukarıda bağlantısı verilen özel kılavuzlar vardır.

{
"name": "@myorg/openclaw-my-plugin",
"version": "1.0.0",
"type": "module",
"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
}
}

// index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { Type } from "@sinclair/typebox";

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

clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
openclaw plugins install clawhub:@myorg/openclaw-my-plugin

pnpm test -- <bundled-plugin-root>/my-plugin/

# Plugin yetenekleri

Tek bir Plugin, api nesnesi aracılığıyla herhangi sayıda yetenek kaydedebilir:

Tam kayıt API'si için SDK Genel Bakış bölümüne bakın.

Paketlenmiş Plugin'ler, model çıktıyı görmeden önce zaman uyumsuz araç sonucu yeniden yazımı gerektiğinde api.registerAgentToolResultMiddleware(...) kullanabilir. Hedeflenen çalışma zamanlarını contracts.agentToolResultMiddleware içinde bildirin; örneğin ["pi", "codex"]. Bu, güvenilir bir paketlenmiş-Plugin dikişidir; harici Plugin'ler, OpenClaw bu yetenek için açık bir güven politikası geliştirene kadar normal OpenClaw Plugin hook'larını tercih etmelidir.

Plugin'iniz özel Gateway RPC yöntemleri kaydediyorsa bunları Plugin'e özgü bir ön ekte tutun. Çekirdek yönetici ad alanları (config.*, exec.approvals.*, wizard.*, update.*) ayrılmış kalır ve bir Plugin daha dar bir kapsam istese bile her zaman operator.admin olarak çözümlenir.

Akılda tutulması gereken hook koruma semantiği:

• before_tool_call: { block: true } sonlandırıcıdır ve daha düşük öncelikli işleyicileri durdurur.
• before_tool_call: { block: false } karar yok olarak değerlendirilir.
• before_tool_call: { requireApproval: true } aracı yürütmesini duraklatır ve exec onay kaplaması, Telegram düğmeleri, Discord etkileşimleri veya herhangi bir kanaldaki /approve komutu üzerinden kullanıcıdan onay ister.
• before_install: { block: true } sonlandırıcıdır ve daha düşük öncelikli işleyicileri durdurur.
• before_install: { block: false } karar yok olarak değerlendirilir.
• message_sending: { cancel: true } sonlandırıcıdır ve daha düşük öncelikli işleyicileri durdurur.
• message_sending: { cancel: false } karar yok olarak değerlendirilir.
• message_received: gelen thread/konu yönlendirmesine ihtiyacınız olduğunda türlenmiş threadId alanını tercih edin. metadata alanını kanala özgü ek bilgiler için kullanın.
• message_sending: kanala özgü metadata anahtarları yerine türlenmiş replyToId / threadId yönlendirme alanlarını tercih edin.

/approve komutu, sınırlı yedeklemeyle hem exec hem de Plugin onaylarını işler: bir exec onay kimliği bulunamadığında OpenClaw aynı kimliği Plugin onayları üzerinden yeniden dener. Plugin onay iletimi yapılandırmada approvals.plugin üzerinden bağımsız olarak yapılandırılabilir.

Özel onay tesisatının aynı sınırlı yedekleme durumunu algılaması gerekiyorsa, onay-süresi dolumu dizgelerini elle eşleştirmek yerine openclaw/plugin-sdk/error-runtime içindeki isApprovalNotFoundError öğesini tercih edin.

Örnekler ve hook referansı için Plugin hook'ları bölümüne bakın.

# Aracı araçlarını kaydetme

Araçlar, LLM'in çağırabileceği türlenmiş işlevlerdir. Zorunlu (her zaman kullanılabilir) veya isteğe bağlı (kullanıcı seçimine bağlı) olabilirler:

register(api) {
  // Required tool - always available
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({ input: Type.String() }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });

  // Optional tool - user must add to allowlist
  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": ["my_tool", "workflow_tool"]
  },
  "toolMetadata": {
    "workflow_tool": {
      "optional": true
    }
  }
}

OpenClaw, kayıtlı araçtan doğrulanmış tanımlayıcıyı yakalar ve önbelleğe alır, böylece pluginler manifestte description veya şema verilerini yinelemez. Manifest sözleşmesi yalnızca sahipliği ve keşfi bildirir; yürütme yine de canlı kayıtlı araç uygulamasını çağırır. api.registerTool(..., { optional: true }) ile kaydedilen araçlar için toolMetadata.<tool>.optional: true ayarını yapın; böylece OpenClaw, araç açıkça izin listesine alınana kadar o plugin çalışma zamanını yüklemekten kaçınabilir.

Kullanıcılar isteğe bağlı araçları yapılandırmada etkinleştirir:

{
  tools: { allow: ["workflow_tool"] },
}

• Araç adları çekirdek araçlarla çakışmamalıdır (çakışmalar atlanır)
• Eksik parameters dahil hatalı biçimlendirilmiş kayıt nesnelerine sahip araçlar, ajan çalıştırmalarını bozmak yerine atlanır ve plugin tanılamalarında bildirilir
• Yan etkileri veya ek ikili dosya gereksinimleri olan araçlar için optional: true kullanın
• Kullanıcılar, plugin kimliğini tools.allow içine ekleyerek bir plugindeki tüm araçları etkinleştirebilir

# CLI komutlarını kaydetme

Pluginler, api.registerCli ile kök openclaw komut grupları ekleyebilir. OpenClaw'ın her plugin çalışma zamanını istekli biçimde yüklemeden komutu gösterebilmesi ve yönlendirebilmesi için her üst düzey komut kökü için descriptors sağlayın.

register(api) {
  api.registerCli(
    ({ program }) => {
      const demo = program
        .command("demo-plugin")
        .description("Run demo plugin commands");

      demo
        .command("ping")
        .description("Check that the plugin CLI is executable")
        .action(() => {
          console.log("demo-plugin:pong");
        });
    },
    {
      descriptors: [
        {
          name: "demo-plugin",
          description: "Run demo plugin commands",
          hasSubcommands: true,
        },
      ],
    },
  );
}

Kurulumdan sonra çalışma zamanı kaydını doğrulayın ve komutu yürütün:

openclaw plugins inspect demo-plugin --runtime --json
openclaw demo-plugin ping

# İçe aktarma kuralları

Her zaman odaklanmış openclaw/plugin-sdk/<subpath> yollarından içe aktarın:

// Wrong: monolithic root (deprecated, will be removed)

Tam alt yol başvurusu için bkz. SDK Genel Bakışı.

Plugininizin içinde, dahili içe aktarmalar için yerel barrel dosyaları (api.ts, runtime-api.ts) kullanın - kendi plugininizi hiçbir zaman SDK yolu üzerinden içe aktarmayın.

Sağlayıcı pluginleri için, dikiş gerçekten genel değilse sağlayıcıya özgü yardımcıları paket kökü barrel'larında tutun. Mevcut paketlenmiş örnekler:

• Anthropic: Claude akış sarmalayıcıları ve service_tier / beta yardımcıları
• OpenAI: sağlayıcı oluşturucular, varsayılan model yardımcıları, gerçek zamanlı sağlayıcılar
• OpenRouter: sağlayıcı oluşturucu ile onboarding/yapılandırma yardımcıları

Bir yardımcı yalnızca tek bir paketlenmiş sağlayıcı paketi içinde yararlıysa, onu openclaw/plugin-sdk/* içine yükseltmek yerine o paket kökü dikişinde tutun.

Bazı oluşturulmuş openclaw/plugin-sdk/<bundled-id> yardımcı dikişleri, izlenen sahip kullanımları olduğunda paketlenmiş plugin bakımı için hâlâ vardır. Bunları yeni üçüncü taraf pluginler için varsayılan kalıp olarak değil, ayrılmış yüzeyler olarak değerlendirin.

# 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: