راه‌اندازی و پیکربندی Plugin

مرجع بسته‌بندی Plugin (فراداده package.json)، manifestها (openclaw.plugin.json)، ورودی‌های راه‌اندازی، و شِماهای پیکربندی.

# فراداده بسته

package.json شما به یک فیلد openclaw نیاز دارد که به سیستم Plugin بگوید Plugin شما چه چیزی ارائه می‌کند:

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

# openclaw.channel

openclaw.channel فراداده سبک بسته برای کشف کانال و سطوح راه‌اندازی، پیش از بارگذاری زمان اجرا است.

مثال:

{
  "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 پشتیبانی می‌کند از:

• configured: گنجاندن کانال در سطوح فهرست‌سازی پیکربندی‌شده/سبک وضعیت
• setup: گنجاندن کانال در انتخابگرهای تعاملی راه‌اندازی/پیکربندی
• docs: علامت‌گذاری کانال به‌عنوان عمومی در سطوح مستندات/ناوبری

# openclaw.install

openclaw.install فراداده بسته است، نه فراداده manifest.

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

# بارگذاری کامل تعویق‌افتاده

Pluginهای کانال می‌توانند با این مورد، بارگذاری تعویق‌افتاده را فعال کنند:

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

وقتی فعال باشد، OpenClaw در مرحله راه‌اندازی پیش از گوش‌دادن، حتی برای کانال‌هایی که از قبل پیکربندی شده‌اند، فقط setupEntry را بارگذاری می‌کند. ورودی کامل پس از آن‌که gateway شروع به گوش‌دادن کرد بارگذاری می‌شود.

اگر ورودی setup/full شما متدهای RPC gateway را ثبت می‌کند، آن‌ها را روی یک پیشوند اختصاصی Plugin نگه دارید. فضای نام‌های رزروشده مدیریت هسته (config.*، exec.approvals.*، wizard.*، update.*) متعلق به هسته می‌مانند و همیشه به operator.admin resolve می‌شوند.

# manifest Plugin

هر Plugin بومی باید یک openclaw.plugin.json در ریشه بسته ارائه کند. OpenClaw از این برای اعتبارسنجی پیکربندی بدون اجرای کد Plugin استفاده می‌کند.

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

برای Pluginهای کانال، kind و channels را اضافه کنید:

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

حتی Pluginهایی که هیچ پیکربندی ندارند باید یک شِما ارائه کنند. یک شِمای خالی معتبر است:

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

برای مرجع کامل شِما، manifest Plugin را ببینید.

# انتشار در ClawHub

برای بسته‌های Plugin، از فرمان اختصاصی بسته ClawHub استفاده کنید:

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

# ورودی راه‌اندازی

فایل setup-entry.ts جایگزینی سبک برای index.ts است که OpenClaw زمانی آن را بارگذاری می‌کند که فقط به سطح‌های راه‌اندازی نیاز داشته باشد (onboarding، تعمیر پیکربندی، بازرسی کانال غیرفعال).

// setup-entry.ts


export default defineSetupPluginEntry(myChannelPlugin);

این کار از بارگذاری کد سنگین زمان اجرا (کتابخانه‌های رمزنگاری، ثبت‌های CLI، سرویس‌های پس‌زمینه) در جریان‌های راه‌اندازی جلوگیری می‌کند.

کانال‌های workspace همراه که exportهای ایمن برای راه‌اندازی را در ماژول‌های sidecar نگه می‌دارند، می‌توانند به‌جای defineSetupPluginEntry(...) از defineBundledChannelSetupEntry(...) از openclaw/plugin-sdk/channel-entry-contract استفاده کنند. آن قرارداد همراه همچنین از export اختیاری runtime پشتیبانی می‌کند تا اتصال‌های زمان اجرای زمان راه‌اندازی سبک و صریح بمانند.

# importهای محدود helper راه‌اندازی

برای مسیرهای داغِ فقط راه‌اندازی، وقتی فقط به بخشی از سطح راه‌اندازی نیاز دارید، helper seamهای محدود راه‌اندازی را به umbrella گسترده‌تر plugin-sdk/setup ترجیح دهید:

وقتی کل جعبه‌ابزار مشترک راه‌اندازی را می‌خواهید، از جمله helperهای config-patch مانند moveSingleAccountChannelSectionToDefaultAccount(...)، از seam گسترده‌تر plugin-sdk/setup استفاده کنید.

adapterهای patch راه‌اندازی هنگام import برای hot path ایمن می‌مانند. lookup سطح قرارداد promotion تک-account همراه آن‌ها lazy است، بنابراین import کردن plugin-sdk/setup-runtime پیش از استفاده واقعی از adapter، discovery سطح قرارداد همراه را مشتاقانه بارگذاری نمی‌کند.

# promotion تک-account متعلق به کانال

وقتی یک کانال از پیکربندی top-level تک-account به channels.<id>.accounts.* ارتقا پیدا می‌کند، رفتار مشترک پیش‌فرض این است که مقدارهای account-scoped ارتقایافته را به accounts.default منتقل کند.

کانال‌های همراه می‌توانند آن promotion را از طریق سطح قرارداد راه‌اندازی خود محدود یا override کنند:

• singleAccountKeysToMove: کلیدهای top-level اضافی که باید به account ارتقایافته منتقل شوند
• namedAccountPromotionKeys: وقتی accountهای نام‌دار از قبل وجود دارند، فقط این کلیدها به account ارتقایافته منتقل می‌شوند؛ کلیدهای shared policy/delivery در root کانال می‌مانند
• resolveSingleAccountPromotionTarget(...): انتخاب می‌کند کدام account موجود مقدارهای ارتقایافته را دریافت کند

# schema پیکربندی

پیکربندی Plugin بر اساس JSON Schema موجود در manifest شما اعتبارسنجی می‌شود. کاربران Pluginها را از این طریق پیکربندی می‌کنند:

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

Plugin شما این پیکربندی را هنگام registration به‌صورت api.pluginConfig دریافت می‌کند.

برای پیکربندی مخصوص کانال، به‌جای آن از بخش پیکربندی کانال استفاده کنید:

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

# ساخت schemaهای پیکربندی کانال

از buildChannelConfigSchema برای تبدیل یک schema‏ Zod به wrapper‏ ChannelConfigSchema استفاده کنید که artifactهای پیکربندی متعلق به Plugin از آن استفاده می‌کنند:

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);

اگر از قبل قرارداد را به‌صورت JSON Schema یا TypeBox می‌نویسید، از helper مستقیم استفاده کنید تا OpenClaw بتواند در مسیرهای metadata تبدیل Zod-to-JSON-Schema را skip کند:

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

برای Pluginهای third-party، قرارداد cold-path همچنان manifest Plugin است: JSON Schema تولیدشده را در openclaw.plugin.json#channelConfigs mirror کنید تا schema پیکربندی، راه‌اندازی و سطح‌های UI بتوانند channels.<id> را بدون بارگذاری کد runtime بازرسی کنند.

# wizardهای راه‌اندازی

Pluginهای کانال می‌توانند برای openclaw onboard wizardهای راه‌اندازی تعاملی ارائه کنند. wizard یک شیء ChannelSetupWizard روی ChannelPlugin است:

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 از credentials، textInputs، dmPolicy، allowFrom، groupAccess، prepare، finalize و موارد بیشتر پشتیبانی می‌کند. برای نمونه‌های کامل، بسته‌های Plugin همراه را ببینید (برای مثال Plugin مربوط به Discord در src/channel.setup.ts).

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 }

# انتشار و نصب

Pluginهای خارجی: در ClawHub منتشر کنید، سپس نصب کنید:

openclaw plugins install @myorg/openclaw-my-plugin

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

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

Pluginهای درون مخزن: آن‌ها را زیر درخت workspace مربوط به Pluginهای همراه قرار دهید تا هنگام build به‌طور خودکار شناسایی شوند.

کاربران می‌توانند نصب کنند:

openclaw plugins install <package-name>

فرادادهٔ بسته‌های همراه صریح است و هنگام راه‌اندازی gateway از JavaScript ساخته‌شده استنتاج نمی‌شود. وابستگی‌های runtime به بستهٔ Pluginای تعلق دارند که مالک آن‌هاست؛ راه‌اندازی OpenClaw بسته‌بندی‌شده هرگز وابستگی‌های Plugin را تعمیر یا آینه‌سازی نمی‌کند.

# مرتبط

• ساخت Pluginها — راهنمای شروع گام‌به‌گام
• manifest مربوط به Plugin — مرجع کامل طرح‌وارهٔ manifest
• نقطه‌های ورود SDK — definePluginEntry و defineChannelPluginEntry