ساخت Pluginها

Pluginها OpenClaw را بدون تغییر core گسترش می‌دهند. یک Plugin می‌تواند یک کانال پیام‌رسانی، ارائه‌دهنده مدل، بک‌اند CLI محلی، ابزار agent، hook، ارائه‌دهنده رسانه، یا قابلیت دیگری که مالکیت آن با Plugin است اضافه کند.

لازم نیست یک Plugin خارجی را به مخزن OpenClaw اضافه کنید. package را در ClawHub منتشر کنید و کاربران آن را با این دستور نصب می‌کنند:

openclaw plugins install clawhub:<package-name>

مشخصات package بدون پیشوند همچنان در دوره گذار راه‌اندازی از npm نصب می‌شوند. وقتی می‌خواهید resolve شدن از ClawHub انجام شود، از پیشوند clawhub: استفاده کنید.

نیازمندی‌ها

• از Node 22.19+، Node 23.11+ یا Node 24+ و یک package manager مانند npm یا pnpm استفاده کنید.
• با ماژول‌های TypeScript ESM آشنا باشید.
• برای کار روی Pluginهای bundled داخل مخزن، مخزن را clone کنید و pnpm install را اجرا کنید. توسعه Plugin در source checkout فقط با pnpm انجام می‌شود، چون OpenClaw Pluginهای bundled را از packageهای workspace در extensions/* بارگذاری می‌کند.

شکل Plugin را انتخاب کنید

شروع سریع

با ثبت یک ابزار agent الزامی، یک Plugin ابزار حداقلی بسازید. این کوتاه‌ترین شکل مفید Plugin است و package، manifest، نقطه ورود و اثبات محلی را نشان می‌دهد.

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

ثبت ابزارها

ابزارها می‌توانند الزامی یا اختیاری باشند. ابزارهای الزامی همیشه وقتی Plugin فعال است در دسترس‌اند. ابزارهای اختیاری به opt-in کاربر نیاز دارند.

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(...) ثبت می‌شود باید در manifest Plugin نیز اعلام شود:

{  "contracts": {    "tools": ["workflow_tool"]  },  "toolMetadata": {    "workflow_tool": {      "optional": true    }  }}

کاربران با tools.allow opt in می‌کنند:

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

ابزارهای اختیاری کنترل می‌کنند که آیا یک ابزار در معرض مدل قرار بگیرد یا نه. وقتی یک ابزار یا hook باید پس از انتخاب شدن توسط مدل و پیش از اجرای action درخواست تأیید کند، از درخواست‌های مجوز Plugin استفاده کنید.

از ابزارهای اختیاری برای side effectها، binaryهای غیرمعمول، یا قابلیت‌هایی استفاده کنید که نباید به‌صورت پیش‌فرض در معرض قرار بگیرند. نام ابزارها نباید با ابزارهای core تداخل داشته باشد؛ تداخل‌ها رد می‌شوند و در diagnosticsهای Plugin گزارش می‌شوند. registrationهای malformed، از جمله descriptorهای ابزار بدون parameters، رد می‌شوند و به همان شکل گزارش می‌شوند. ابزارهای ثبت‌شده functionهای typed هستند که مدل می‌تواند پس از عبور policy و allowlist checkها آن‌ها را فراخوانی کند.

factoryهای ابزار یک context object فراهم‌شده توسط runtime دریافت می‌کنند. وقتی یک ابزار باید مدل فعال turn فعلی را log کند، نمایش دهد یا با آن سازگار شود، از ctx.activeModel استفاده کنید. این object می‌تواند شامل provider، modelId و modelRef باشد. آن را metadata اطلاعاتی runtime در نظر بگیرید، نه مرز امنیتی در برابر operator محلی، کد Plugin نصب‌شده، یا runtime تغییر‌یافته OpenClaw. ابزارهای محلی حساس همچنان باید به opt-in صریح Plugin یا operator نیاز داشته باشند و وقتی metadata مدل فعال وجود ندارد یا مناسب نیست fail closed شوند.

manifest مالکیت و discovery را اعلام می‌کند؛ اجرا همچنان implementation ابزار ثبت‌شده live را فراخوانی می‌کند. toolMetadata.<tool>.optional: true را با api.registerTool(..., { optional: true }) هم‌راستا نگه دارید تا OpenClaw بتواند تا زمانی که ابزار صراحتاً allowlist نشده، از بارگذاری runtime آن Plugin اجتناب کند.

قراردادهای import

از subpathهای متمرکز SDK import کنید:

از root barrel منسوخ‌شده import نکنید:

درون package Plugin خود، برای importهای داخلی از فایل‌های barrel محلی مانند api.ts و runtime-api.ts استفاده کنید. Plugin خودتان را از طریق یک مسیر SDK import نکنید. helperهای مخصوص provider باید در package provider بمانند، مگر اینکه مرز واقعاً generic باشد.

methodهای RPC سفارشی Gateway یک نقطه ورود پیشرفته هستند. آن‌ها را روی یک prefix مخصوص Plugin نگه دارید؛ namespaceهای admin core مانند config.*، exec.approvals.*، operator.admin.*، wizard.* و update.* رزرو می‌مانند و به operator.admin resolve می‌شوند. bridge openclaw/plugin-sdk/gateway-method-runtime برای routeهای HTTP Plugin رزرو شده است که contracts.gatewayMethodDispatch: ["authenticated-request"] را اعلام می‌کنند.

برای نقشه کامل import، نمای کلی SDK Plugin را ببینید.

چک‌لیست پیش از ارسال

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json metadata درست openclaw را دارد OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s manifest openclaw.plugin.json وجود دارد و معتبر است OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s نقطه ورود از defineChannelPluginEntry یا definePluginEntry استفاده می‌کند OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s همه importها از مسیرهای متمرکز plugin-sdk/<subpath> استفاده می‌کنند OPENCLAW_DOCS_MARKER:calloutClose: