Plugin kurulumu ve yapılandırması

Plugin paketleme (package.json meta verileri), manifestler (openclaw.plugin.json), kurulum girişleri ve config şemaları için referans.

# Paket meta verileri

package.json dosyanızda, Plugin sistemine plugin'inizin ne sağladığını söyleyen bir openclaw alanı gerekir:

{
  "name": "@myorg/openclaw-my-channel",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "channel": {
      "id": "my-channel",
      "label": "My Channel",
      "blurb": "Short description of the channel."
    }
  }
}

{
  "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"
    }
  }
}

# openclaw alanları

# openclaw.channel

openclaw.channel, çalışma zamanı yüklenmeden önce kanal keşfi ve kurulum yüzeyleri için düşük maliyetli paket meta verisidir.

Örnek:

{
  "openclaw": {
    "channel": {
      "id": "my-channel",
      "label": "My Channel",
      "selectionLabel": "My Channel (self-hosted)",
      "detailLabel": "My Channel Bot",
      "docsPath": "/channels/my-channel",
      "docsLabel": "my-channel",
      "blurb": "Webhook-based self-hosted chat integration.",
      "order": 80,
      "aliases": ["mc"],
      "preferOver": ["my-channel-legacy"],
      "selectionDocsPrefix": "Guide:",
      "selectionExtras": ["Markdown"],
      "markdownCapable": true,
      "exposure": {
        "configured": true,
        "setup": true,
        "docs": true
      },
      "quickstartAllowFrom": true
    }
  }
}

exposure şunları destekler:

• configured: kanalı yapılandırılmış/durum tarzı listeleme yüzeylerine dahil eder
• setup: kanalı etkileşimli kurulum/yapılandırma seçicilerine dahil eder
• docs: kanalı dokümanlar/gezinme yüzeylerinde kamuya açık olarak işaretler

# openclaw.install

openclaw.install paket meta verisidir, manifest meta verisi değildir.

{
  "openclaw": {
    "install": {
      "npmSpec": "@wecom/[email protected]",
      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",
      "defaultChoice": "npm"
    }
  }
}

# Ertelenmiş tam yükleme

Channel plugin'leri şu şekilde ertelenmiş yüklemeyi seçebilir:

{
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}

Etkinleştirildiğinde OpenClaw, ön dinleme başlatma aşamasında, halihazırda yapılandırılmış kanallar için bile yalnızca setupEntry değerini yükler. Tam giriş, gateway dinlemeye başladıktan sonra yüklenir.

Kurulum/tam girişiniz gateway RPC yöntemleri kaydediyorsa, bunları plugin'e özgü bir ön ekte tutun. Ayrılmış çekirdek admin ad alanları (config.*, exec.approvals.*, wizard.*, update.*) çekirdeğe ait kalır ve her zaman operator.admin olarak çözülür.

# Plugin manifesti

Her yerel plugin, paket kökünde bir openclaw.plugin.json ile gelmelidir. OpenClaw bunu plugin kodunu çalıştırmadan config doğrulamak için kullanır.

{
  "id": "my-plugin",
  "name": "My Plugin",
  "description": "Adds My Plugin capabilities to OpenClaw",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "webhookSecret": {
        "type": "string",
        "description": "Webhook verification secret"
      }
    }
  }
}

Channel plugin'leri için kind ve channels ekleyin:

{
  "id": "my-channel",
  "kind": "channel",
  "channels": ["my-channel"],
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}

Config'i olmayan plugin'ler bile bir şema ile gelmelidir. Boş bir şema geçerlidir:

{
  "id": "my-plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false
  }
}

Tam şema referansı için Plugin manifesti bölümüne bakın.

# ClawHub yayımlama

Plugin paketleri için pakete özgü ClawHub komutunu kullanın:

clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin

# Kurulum girdisi

setup-entry.ts dosyası, OpenClaw yalnızca kurulum yüzeylerine (onboarding, yapılandırma onarımı, devre dışı kanal denetimi) ihtiyaç duyduğunda yüklediği index.ts için hafif bir alternatiftir.

// setup-entry.ts


export default defineSetupPluginEntry(myChannelPlugin);

Bu, kurulum akışları sırasında ağır runtime kodunun (kripto kitaplıkları, CLI kayıtları, arka plan hizmetleri) yüklenmesini önler.

Kurulum açısından güvenli dışa aktarmaları yan modüllerde tutan paketle birlikte gelen çalışma alanı kanalları, defineSetupPluginEntry(...) yerine openclaw/plugin-sdk/channel-entry-contract içindeki defineBundledChannelSetupEntry(...) öğesini kullanabilir. Bu paketle gelen sözleşme, kurulum zamanındaki runtime bağlantılarının hafif ve açık kalabilmesi için isteğe bağlı bir runtime dışa aktarımını da destekler.

# Dar kurulum yardımcısı içe aktarmaları

Sıcak yalnızca kurulum yolları için, kurulum yüzeyinin yalnızca bir kısmına ihtiyaç duyduğunuzda daha geniş plugin-sdk/setup şemsiyesi yerine dar kurulum yardımcısı bağlantı noktalarını tercih edin:

moveSingleAccountChannelSectionToDefaultAccount(...) gibi yapılandırma yaması yardımcıları dahil olmak üzere paylaşılan kurulum araç takımının tamamını istediğinizde daha geniş plugin-sdk/setup bağlantı noktasını kullanın.

Kurulum yama bağdaştırıcıları içe aktarmada sıcak yol açısından güvenli kalır. Paketle gelen tek hesap yükseltme sözleşme yüzeyi araması tembeldir; bu nedenle plugin-sdk/setup-runtime içe aktarmak, bağdaştırıcı gerçekten kullanılmadan önce paketle gelen sözleşme yüzeyi keşfini hevesle yüklemez.

# Kanalın sahip olduğu tek hesap yükseltme

Bir kanal tek hesaplı üst düzey yapılandırmadan channels.<id>.accounts.* yapısına yükseltildiğinde, varsayılan paylaşılan davranış yükseltilen hesap kapsamlı değerleri accounts.default içine taşımaktır.

Paketle gelen kanallar, kurulum sözleşme yüzeyleri aracılığıyla bu yükseltmeyi daraltabilir veya geçersiz kılabilir:

• singleAccountKeysToMove: yükseltilen hesaba taşınması gereken ek üst düzey anahtarlar
• namedAccountPromotionKeys: adlandırılmış hesaplar zaten mevcut olduğunda, yalnızca bu anahtarlar yükseltilen hesaba taşınır; paylaşılan ilke/teslim anahtarları kanal kökünde kalır
• resolveSingleAccountPromotionTarget(...): yükseltilen değerleri hangi mevcut hesabın alacağını seçer

# Yapılandırma şeması

Plugin yapılandırması, manifestinizdeki JSON Schema ile doğrulanır. Kullanıcılar Plugin'leri şu şekilde yapılandırır:

{
  plugins: {
    entries: {
      "my-plugin": {
        config: {
          webhookSecret: "abc123",
        },
      },
    },
  },
}

Plugin'iniz bu yapılandırmayı kayıt sırasında api.pluginConfig olarak alır.

Kanala özgü yapılandırma için bunun yerine kanal yapılandırma bölümünü kullanın:

{
  channels: {
    "my-channel": {
      token: "bot-token",
      allowFrom: ["user1", "user2"],
    },
  },
}

# Kanal yapılandırma şemaları oluşturma

Bir Zod şemasını Plugin'e ait yapılandırma artefaktları tarafından kullanılan ChannelConfigSchema sarmalayıcısına dönüştürmek için buildChannelConfigSchema kullanın:

const accountSchema = z.object({
  token: z.string().optional(),
  allowFrom: z.array(z.string()).optional(),
  accounts: z.object({}).catchall(z.any()).optional(),
  defaultAccount: z.string().optional(),
});

const configSchema = buildChannelConfigSchema(accountSchema);

Sözleşmeyi zaten JSON Schema veya TypeBox olarak yazıyorsanız, OpenClaw'ın meta veri yollarında Zod'dan JSON Schema'ya dönüştürmeyi atlayabilmesi için doğrudan yardımcıyı kullanın:

const configSchema = buildJsonChannelConfigSchema(
  Type.Object({
    token: Type.Optional(Type.String()),
    allowFrom: Type.Optional(Type.Array(Type.String())),
  }),
);

Üçüncü taraf Plugin'ler için soğuk yol sözleşmesi hâlâ Plugin manifestidir: oluşturulan JSON Schema'yı openclaw.plugin.json#channelConfigs içine yansıtın; böylece yapılandırma şeması, kurulum ve UI yüzeyleri runtime kodunu yüklemeden channels.<id> öğesini inceleyebilir.

# Kurulum sihirbazları

Kanal Plugin'leri openclaw onboard için etkileşimli kurulum sihirbazları sağlayabilir. Sihirbaz, ChannelPlugin üzerindeki bir ChannelSetupWizard nesnesidir:

const setupWizard: ChannelSetupWizard = {
  channel: "my-channel",
  status: {
    configuredLabel: "Connected",
    unconfiguredLabel: "Not configured",
    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),
  },
  credentials: [
    {
      inputKey: "token",
      providerHint: "my-channel",
      credentialLabel: "Bot token",
      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",
      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",
      keepPrompt: "Keep current token?",
      inputPrompt: "Enter your bot token:",
      inspect: ({ cfg, accountId }) => {
        const token = (cfg.channels as any)?.["my-channel"]?.token;
        return {
          accountConfigured: Boolean(token),
          hasConfiguredValue: Boolean(token),
        };
      },
    },
  ],
};

ChannelSetupWizard türü credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize ve daha fazlasını destekler. Tam örnekler için paketle gelen Plugin paketlerine (örneğin Discord Plugin'i src/channel.setup.ts) bakın.

import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup";

const setupSurface = createOptionalChannelSetupSurface({
  channel: "my-channel",
  label: "My Channel",
  npmSpec: "@myorg/openclaw-my-channel",
  docsPath: "/channels/my-channel",
});
// Returns { setupAdapter, setupWizard }

# Yayınlama ve yükleme

Harici Plugin'ler: ClawHub üzerinde yayınlayın, ardından yükleyin:

openclaw plugins install @myorg/openclaw-my-plugin

openclaw plugins install clawhub:@myorg/openclaw-my-plugin

openclaw plugins install npm:@myorg/openclaw-my-plugin

Repo içi Plugin'ler: birlikte gelen Plugin çalışma alanı ağacının altına yerleştirin; derleme sırasında otomatik olarak keşfedilirler.

Kullanıcılar şunu yükleyebilir:

openclaw plugins install <package-name>

Birlikte gelen paket meta verileri açıktır; Gateway başlatılırken derlenmiş JavaScript'ten çıkarılmaz. Çalışma zamanı bağımlılıkları, onlara sahip olan Plugin paketinde yer alır; paketlenmiş OpenClaw başlatması Plugin bağımlılıklarını hiçbir zaman onarmaz veya yansıtmaz.

# İlgili

• Plugin oluşturma — adım adım başlangıç kılavuzu
• Plugin bildirimi — tam bildirim şeması başvurusu
• SDK giriş noktaları — definePluginEntry ve defineChannelPluginEntry