---
read_when:
    - شما یک Plugin مربوط به OpenClaw را نگهداری می‌کنید
    - یک هشدار سازگاری Plugin می‌بینید
    - در حال برنامه‌ریزی برای مهاجرت SDK یا مانیفست Plugin هستید
summary: قراردادهای سازگاری Plugin، فراداده‌های منسوخ‌سازی، و انتظارات مهاجرت
title: سازگاری Plugin
x-i18n:
    generated_at: "2026-05-11T20:39:23Z"
    model: gpt-5.5
    provider: openai
    source_hash: 1afd37697f55721ca8419256a6e8187c398d4b20fb11a65776b755050dd5368b
    source_path: plugins/compatibility.md
    workflow: 16
---

OpenClaw قراردادهای قدیمی‌تر Plugin را پیش از حذف، از طریق آداپتورهای سازگاریِ نام‌دار متصل نگه می‌دارد. این کار از Pluginهای بسته‌بندی‌شده و خارجی موجود محافظت می‌کند، در حالی که قراردادهای SDK، مانیفست، راه‌اندازی، پیکربندی و زمان اجرای عامل تکامل می‌یابند.

## رجیستری سازگاری

قراردادهای سازگاری Plugin در رجیستری هسته در
`src/plugins/compat/registry.ts` پیگیری می‌شوند.

هر رکورد شامل این موارد است:

- یک کد سازگاری پایدار
- وضعیت: `active`، `deprecated`، `removal-pending` یا `removed`
- مالک: SDK، پیکربندی، راه‌اندازی، کانال، ارائه‌دهنده، اجرای Plugin، زمان اجرای عامل،
  یا هسته
- تاریخ‌های معرفی و منسوخ‌سازی در صورت کاربرد
- راهنمای جایگزینی
- مستندات، عیب‌یابی‌ها و آزمون‌هایی که رفتار قدیمی و جدید را پوشش می‌دهند

این رجیستری منبع برنامه‌ریزی نگه‌دارندگان و بررسی‌های آینده بازرس Plugin است. اگر رفتاری رو به Plugin تغییر کند، رکورد سازگاری را در همان تغییری که آداپتور را اضافه می‌کند، اضافه یا به‌روزرسانی کنید.

سازگاری تعمیر و مهاجرت Doctor به‌صورت جداگانه در
`src/commands/doctor/shared/deprecation-compat.ts` پیگیری می‌شود. آن رکوردها شکل‌های قدیمی پیکربندی، چیدمان‌های دفتر نصب، و شیم‌های تعمیر را پوشش می‌دهند که ممکن است پس از حذف مسیر سازگاری زمان اجرا همچنان لازم باشد در دسترس بمانند.

بازبینی‌های انتشار باید هر دو رجیستری را بررسی کنند. صرفا به این دلیل که رکورد سازگاری زمان اجرا یا پیکربندی متناظر منقضی شده است، یک مهاجرت Doctor را حذف نکنید؛ ابتدا تأیید کنید مسیر ارتقای پشتیبانی‌شده‌ای که هنوز به آن تعمیر نیاز دارد وجود ندارد. همچنین در طول برنامه‌ریزی انتشار، هر یادداشت جایگزینی را دوباره اعتبارسنجی کنید، چون مالکیت Plugin و footprint پیکربندی می‌تواند با خروج ارائه‌دهندگان و کانال‌ها از هسته تغییر کند.

## بسته بازرس Plugin

بازرس Plugin باید بیرون از مخزن هسته OpenClaw، به‌صورت یک بسته/مخزن جداگانه که بر قراردادهای نسخه‌دار سازگاری و مانیفست تکیه دارد، قرار بگیرد.

CLI روز نخست باید این باشد:

```sh
openclaw-plugin-inspector ./my-plugin
```

باید این موارد را منتشر کند:

- اعتبارسنجی مانیفست/اسکیما
- نسخه سازگاری قراردادی که بررسی می‌شود
- بررسی‌های فراداده نصب/منبع
- بررسی‌های import مسیر سرد
- هشدارهای منسوخ‌سازی و سازگاری

برای خروجی پایدار و قابل‌خواندن توسط ماشین در annotationهای CI از `--json` استفاده کنید. هسته OpenClaw باید قراردادها و fixtureهایی را در معرض استفاده بازرس قرار دهد، اما نباید باینری بازرس را از بسته اصلی `openclaw` منتشر کند.

### مسیر پذیرش نگه‌دارنده

هنگام اعتبارسنجی بازرس خارجی در برابر بسته‌های Plugin OpenClaw، برای مسیر پذیرش بسته قابل‌نصب از Blacksmith Testbox مبتنی بر Crabbox استفاده کنید. پس از ساخت بسته، آن را از یک checkout تمیز OpenClaw اجرا کنید:

```sh
pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "pnpm install && pnpm build && npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/telegram --json"
pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/discord --json"
pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- <clawhub-plugin-dir> --json"
```

این مسیر را برای نگه‌دارندگان opt-in نگه دارید، چون یک بسته npm خارجی نصب می‌کند و ممکن است بسته‌های Plugin را که بیرون از مخزن clone شده‌اند بررسی کند. نگهبان‌های مخزن محلی نقشه export مربوط به SDK، فراداده رجیستری سازگاری، کاهش importهای SDK منسوخ، و مرزهای import افزونه‌های بسته‌بندی‌شده را پوشش می‌دهند؛ اثبات بازرس Testbox، بسته را همان‌گونه که نویسندگان Plugin خارجی مصرف می‌کنند پوشش می‌دهد.

## سیاست منسوخ‌سازی

OpenClaw نباید یک قرارداد مستند Plugin را در همان انتشاری حذف کند که جایگزین آن را معرفی می‌کند.

توالی مهاجرت این است:

1. قرارداد جدید را اضافه کنید.
2. رفتار قدیمی را از طریق یک آداپتور سازگاری نام‌دار متصل نگه دارید.
3. وقتی نویسندگان Plugin می‌توانند اقدام کنند، عیب‌یابی یا هشدار منتشر کنید.
4. جایگزین و زمان‌بندی را مستند کنید.
5. هر دو مسیر قدیمی و جدید را آزمایش کنید.
6. تا پایان پنجره مهاجرت اعلام‌شده صبر کنید.
7. فقط با تأیید صریح انتشار breaking حذف کنید.

رکوردهای منسوخ باید شامل تاریخ شروع هشدار، جایگزین، پیوند مستندات، و تاریخ حذف نهایی حداکثر سه ماه پس از شروع هشدار باشند. مسیر سازگاری منسوخ با پنجره حذف بی‌انتها اضافه نکنید، مگر اینکه نگه‌دارندگان صریحا تصمیم بگیرند این سازگاری دائمی است و به‌جای آن وضعیتش را `active` علامت بزنند.

## حوزه‌های سازگاری فعلی

رکوردهای سازگاری فعلی شامل این موارد هستند:

- importهای گسترده قدیمی SDK مانند `openclaw/plugin-sdk/compat`
- شکل‌های قدیمی Plugin فقط مبتنی بر hook و `before_agent_start`
- entrypointهای قدیمی Plugin با `activate(api)` تا زمانی که Pluginها به
  `register(api)` مهاجرت کنند
- aliasهای قدیمی SDK مانند `openclaw/extension-api`،
  `openclaw/plugin-sdk/channel-runtime`، سازنده‌های وضعیت `openclaw/plugin-sdk/command-auth`،
  `openclaw/plugin-sdk/test-utils` (جایگزین‌شده با زیربخش‌های آزمون متمرکز
  `openclaw/plugin-sdk/*`) و aliasهای نوع `ClawdbotConfig` /
  `OpenClawSchemaType`
- رفتار allowlist و فعال‌سازی Pluginهای بسته‌بندی‌شده
- فراداده قدیمی مانیفست env-var ارائه‌دهنده/کانال
- hookها و aliasهای نوع قدیمی Plugin ارائه‌دهنده، تا زمانی که ارائه‌دهندگان به
  hookهای صریح کاتالوگ، احراز هویت، thinking، replay و انتقال مهاجرت کنند
- aliasهای قدیمی زمان اجرا مانند `api.runtime.taskFlow`،
  `api.runtime.subagent.getSession`، `api.runtime.stt` و
  `api.runtime.config.loadConfig()` / `api.runtime.config.writeConfigFile(...)` منسوخ
- ثبت split قدیمی Plugin حافظه، تا زمانی که Pluginهای حافظه به
  `registerMemoryCapability` مهاجرت کنند
- helperهای قدیمی SDK کانال برای اسکیماهای پیام native، کنترل mention،
  قالب‌بندی envelope ورودی، و تو در تویی قابلیت تأیید
- aliasهای قدیمی کلید مسیر کانال و helper هدف قابل‌مقایسه، تا زمانی که Pluginها
  به `openclaw/plugin-sdk/channel-route` مهاجرت کنند
- hintهای فعال‌سازی که با مالکیت contribution در مانیفست جایگزین می‌شوند
- fallback زمان اجرای `setup-api`، تا زمانی که descriptorهای راه‌اندازی به فراداده سرد
  `setup.requiresRuntime: false` منتقل شوند
- hookهای `discovery` ارائه‌دهنده، تا زمانی که hookهای کاتالوگ ارائه‌دهنده به
  `catalog.run(...)` منتقل شوند
- فراداده `showConfigured` / `showInSetup` کانال، تا زمانی که بسته‌های کانال به
  `openclaw.channel.exposure` منتقل شوند
- کلیدهای پیکربندی قدیمی runtime-policy، تا زمانی که Doctor اپراتورها را به
  `agentRuntime` مهاجرت دهد
- fallback فراداده تولیدشده پیکربندی کانال‌های بسته‌بندی‌شده، تا زمانی که فراداده registry-first
  `channelConfigs` اضافه شود
- پرچم‌های env برای غیرفعال‌سازی رجیستری Plugin پایدارشده و مهاجرت نصب، تا زمانی که جریان‌های تعمیر
  اپراتورها را به `openclaw plugins registry --refresh` و
  `openclaw doctor --fix` مهاجرت دهند
- مسیرهای پیکربندی قدیمی جست‌وجوی وب، دریافت وب، و x_search متعلق به Plugin، تا زمانی که
  Doctor آن‌ها را به `plugins.entries.<plugin>.config` مهاجرت دهد
- پیکربندی authored قدیمی `plugins.installs` و aliasهای مسیر بارگذاری Plugin بسته‌بندی‌شده،
  تا زمانی که فراداده نصب به دفتر Plugin مدیریت‌شده توسط state منتقل شود

کد جدید Plugin باید جایگزین فهرست‌شده در رجیستری و در راهنمای مهاجرت مشخص را ترجیح دهد. Pluginهای موجود می‌توانند تا زمانی که مستندات، عیب‌یابی‌ها و یادداشت‌های انتشار پنجره حذف را اعلام کنند، به استفاده از مسیر سازگاری ادامه دهند.

## یادداشت‌های انتشار

یادداشت‌های انتشار باید منسوخ‌سازی‌های آینده Plugin را همراه با تاریخ‌های هدف و پیوند به مستندات مهاجرت شامل شوند. این هشدار باید پیش از آن رخ دهد که مسیر سازگاری به `removal-pending` یا `removed` منتقل شود.