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

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

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

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

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

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

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

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

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

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

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

CLI روز اول باید چنین باشد:

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

باید این موارد را خروجی دهد:

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

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

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

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

```sh
blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90
blacksmith testbox run --id <tbx_id> "pnpm install && pnpm build && npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/telegram --json"
blacksmith testbox run --id <tbx_id> "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/discord --json"
blacksmith testbox run --id <tbx_id> "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- <clawhub-plugin-dir> --json"
blacksmith testbox stop <tbx_id>
```

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

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

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

دنباله مهاجرت چنین است:

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

رکوردهای منسوخ باید شامل تاریخ شروع هشدار، جایگزین، لینک مستندات، و تاریخ حذف نهایی باشند که بیش از سه ماه پس از شروع هشدار نباشد. مسیر سازگاری منسوخ با بازه حذف باز و بدون پایان اضافه نکنید، مگر اینکه نگه‌دارندگان صریحا تصمیم بگیرند سازگاری دائمی است و به‌جای آن آن را `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های بسته‌بندی‌شده
- فراداده manifest قدیمی env-var برای ارائه‌دهنده/کانال
- hookها و aliasهای نوع قدیمی Plugin ارائه‌دهنده، تا زمانی که ارائه‌دهنده‌ها به
  hookهای صریح catalog، auth، thinking، replay، و transport منتقل شوند
- aliasهای قدیمی runtime مانند `api.runtime.taskFlow`،
  `api.runtime.subagent.getSession`، `api.runtime.stt`، و
  `api.runtime.config.loadConfig()` / `api.runtime.config.writeConfigFile(...)` منسوخ
- ثبت تفکیک‌شده قدیمی memory-plugin تا زمانی که Pluginهای حافظه به
  `registerMemoryCapability` منتقل شوند
- helperهای قدیمی SDK کانال برای schemaهای پیام بومی، gating اشاره، قالب‌بندی پاکت ورودی، و nesting قابلیت تایید
- کلید route قدیمی کانال و aliasهای helper هدف قابل مقایسه، تا زمانی که Pluginها به `openclaw/plugin-sdk/channel-route` منتقل شوند
- hintهای فعال‌سازی که با مالکیت مشارکت manifest جایگزین می‌شوند
- fallback runtime در `setup-api` تا زمانی که descriptorهای راه‌اندازی به فراداده سرد
  `setup.requiresRuntime: false` منتقل شوند
- hookهای `discovery` ارائه‌دهنده، تا زمانی که hookهای catalog ارائه‌دهنده به
  `catalog.run(...)` منتقل شوند
- فراداده `showConfigured` / `showInSetup` کانال، تا زمانی که بسته‌های کانال به
  `openclaw.channel.exposure` منتقل شوند
- کلیدهای پیکربندی قدیمی runtime-policy، تا زمانی که Doctor اپراتورها را به
  `agentRuntime` مهاجرت دهد
- fallback فراداده پیکربندی کانال بسته‌بندی‌شده تولیدشده، تا زمانی که فراداده رجیستری‌محور
  `channelConfigs` اضافه شود
- فلگ‌های env برای غیرفعال‌سازی رجیستری Plugin پایدارشده و مهاجرت نصب، تا زمانی که جریان‌های تعمیر اپراتورها را به `openclaw plugins registry --refresh` و
  `openclaw doctor --fix` مهاجرت دهند
- مسیرهای پیکربندی قدیمی جست‌وجوی وب، دریافت وب، و x_search متعلق به Plugin، تا زمانی که Doctor آن‌ها را به `plugins.entries.<plugin>.config` مهاجرت دهد
- پیکربندی نوشته‌شده قدیمی `plugins.installs` و aliasهای مسیر بارگذاری Plugin بسته‌بندی‌شده، تا زمانی که فراداده نصب به دفتر Plugin مدیریت‌شده توسط state منتقل شود

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

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

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