---
doc-schema-version: 1
read_when:
    - نصب یا پیکربندی Pluginها
    - درک قواعد کشف و بارگذاری Plugin
    - کار با بسته‌های Plugin سازگار با Codex/Claude
sidebarTitle: Getting Started
summary: نصب، پیکربندی و مدیریت Pluginهای OpenClaw
title: Pluginها
x-i18n:
    generated_at: "2026-07-16T17:50:17Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: cd6b19616c14fbbfcec47beca02f206d7a8ca9500c530d06958a30a9e5488bde
    source_path: tools/plugin.md
    workflow: 16
---

Pluginها قابلیت‌های OpenClaw را با کانال‌ها، ارائه‌دهندگان مدل، چارچوب‌های عامل، ابزارها،
Skills، گفتار، رونویسی بلادرنگ، صدا، درک رسانه، تولید،
واکشی وب، جست‌وجوی وب و دیگر قابلیت‌های زمان اجرا گسترش می‌دهند.

از این صفحه برای نصب یک Plugin، راه‌اندازی مجدد Gateway، تأیید بارگذاری آن در زمان اجرا
و رفع خطاهای رایج راه‌اندازی استفاده کنید. برای نمونه‌های صرفاً دستوری، به
[مدیریت Pluginها](/fa/plugins/manage-plugins) مراجعه کنید. برای فهرست موجودی تولیدشده از
Pluginهای همراه، رسمیِ خارجی و صرفاً منبع، به
[موجودی Pluginها](/fa/plugins/plugin-inventory) مراجعه کنید.

## الزامات

- یک checkout یا نصب OpenClaw که CLI ‏`openclaw` در آن در دسترس باشد
- دسترسی شبکه به منبع انتخاب‌شده (ClawHub، npm یا یک میزبان git)
- هرگونه اعتبارنامه، کلید پیکربندی یا ابزار سیستم‌عامل مختص Plugin که در
  مستندات راه‌اندازی آن Plugin ذکر شده است
- مجوز بارگذاری مجدد یا راه‌اندازی مجدد برای Gateway ارائه‌دهنده کانال‌های شما

## شروع سریع

<Steps>
  <Step title="یافتن Plugin">
    برای یافتن بسته‌های عمومی Plugin در [ClawHub](/clawhub) جست‌وجو کنید:

    ```bash
    openclaw plugins search "calendar"
    ```

    ClawHub سطح اصلی کشف Pluginهای جامعه است. در طول گذار
    راه‌اندازی، مشخصه‌های معمولی و بدون پیشوند بسته همچنان از npm نصب می‌شوند، مگر اینکه
    با شناسه یک Plugin رسمی مطابقت داشته باشند. مشخصه‌های خام `@openclaw/*` که با یک
    Plugin همراه مطابقت دارند، به همان نسخه همراه ارجاع داده می‌شوند. هنگامی که مشخصاً
    به یک منبع نیاز دارید، از پیشوند صریح منبع استفاده کنید.

  </Step>

  <Step title="نصب Plugin">
    ```bash
    # از ClawHub.
    openclaw plugins install clawhub:<package>

    # از npm.
    openclaw plugins install npm:<package>

    # از git.
    openclaw plugins install git:github.com/<owner>/<repo>@<ref>

    # از یک checkout توسعه محلی.
    openclaw plugins install ./my-plugin
    openclaw plugins install --link ./my-plugin
    ```

    با نصب Pluginها مانند اجرای کد برخورد کنید. برای نصب‌های قابل‌بازتولید
    در محیط عملیاتی، نسخه‌های ثابت‌شده را ترجیح دهید. بسته‌های ClawHub و کاتالوگ
    همراه/رسمی OpenClaw منابع مورداعتماد هستند. منابع جدید و دلخواه npm،‏ git،
    مسیر/بایگانی محلی، `npm-pack:` یا marketplace در نصب‌های غیرتعاملی، پس از
    بررسی و اعتماد به منبع، به `--force` نیاز دارند.

  </Step>

  <Step title="پیکربندی و فعال‌سازی آن">
    تنظیمات مختص Plugin را در `plugins.entries.<id>.config` پیکربندی کنید.
    اگر Plugin از قبل فعال نیست، آن را فعال کنید:

    ```bash
    openclaw plugins enable <plugin-id>
    ```

    اگر `plugins.allow` تنظیم شده باشد، شناسه Plugin نصب‌شده باید پیش از بارگذاری
    Plugin در آن فهرست باشد. `openclaw plugins install` شناسه نصب‌شده را به فهرست موجود
    `plugins.allow` می‌افزاید و همان شناسه را از `plugins.deny` حذف می‌کند
    تا نصب صریح پس از راه‌اندازی مجدد بارگذاری شود.

  </Step>

  <Step title="اجازه بارگذاری مجدد به Gateway">
    نصب، به‌روزرسانی یا حذف کد Plugin به راه‌اندازی مجدد Gateway
    نیاز دارد. یک Gateway مدیریت‌شده که بارگذاری مجدد پیکربندی در آن فعال است، رکورد
    تغییرکرده نصب Plugin را تشخیص می‌دهد و به‌طور خودکار راه‌اندازی مجدد می‌شود. در غیر این صورت، خودتان
    آن را راه‌اندازی مجدد کنید:

    ```bash
    openclaw gateway restart
    ```

    فعال‌سازی/غیرفعال‌سازی، پیکربندی و رجیستری سرد را به‌روزرسانی می‌کند. بررسی زمان اجرا
    همچنان روشن‌ترین اثبات برای سطوح زنده زمان اجرا است.

  </Step>

  <Step title="تأیید ثبت در زمان اجرا">
    ```bash
    openclaw plugins inspect <plugin-id> --runtime --json
    ```

    برای اثبات ثبت ابزارها، hookها، سرویس‌ها، متدهای Gateway
    یا دستورهای CLI متعلق به Plugin، از `--runtime` استفاده کنید. `inspect` ساده فقط
    بررسی سرد manifest و رجیستری است.

  </Step>
</Steps>

## پیکربندی

### انتخاب منبع نصب

| منبع        | زمان استفاده                                                                  | نمونه                                                          |
| ----------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| ClawHub     | وقتی کشف بومی OpenClaw، اسکن‌ها، فراداده نسخه و راهنمای نصب را می‌خواهید       | `openclaw plugins install clawhub:<package>`                   |
| npm         | وقتی به جریان‌های مستقیم رجیستری npm یا dist-tag نیاز دارید                    | `openclaw plugins install npm:<package>`                       |
| git         | وقتی به یک شاخه، برچسب یا commit از یک مخزن نیاز دارید                         | `openclaw plugins install git:github.com/<owner>/<repo>@<ref>` |
| مسیر محلی   | وقتی یک Plugin را روی همان دستگاه توسعه یا آزمایش می‌کنید                      | `openclaw plugins install --link ./my-plugin`                  |
| marketplace | وقتی یک Plugin سازگار با Claude را از marketplace نصب می‌کنید                  | `openclaw plugins install <plugin> --marketplace <source>`     |

مشخصه‌های بدون پیشوند بسته رفتار سازگاری ویژه‌ای دارند: نام بدون پیشوندی که
با شناسه یک Plugin همراه مطابقت داشته باشد از همان منبع همراه استفاده می‌کند؛ نام بدون پیشوندی که با
شناسه یک Plugin رسمی خارجی مطابقت داشته باشد از کاتالوگ بسته رسمی استفاده می‌کند؛ و هر
مشخصه بدون پیشوند دیگری در طول گذار راه‌اندازی از طریق npm نصب می‌شود. مشخصه‌های خام `@openclaw/*`
که با Pluginهای همراه مطابقت دارند نیز پیش از fallback به npm به نسخه همراه
ارجاع داده می‌شوند. برای نصب عمدی بسته خارجی npm به‌جای نسخه همراه، از
`npm:@openclaw/<plugin>@<version>` استفاده کنید. برای انتخاب قطعی منبع، از `clawhub:`، `npm:`،
`git:` یا `npm-pack:` استفاده کنید. برای قرارداد کامل دستور به
[`openclaw plugins`](/fa/cli/plugins#install) مراجعه کنید.

برای نصب‌های npm، مشخصه‌های بدون نسخه ثابت و `@latest` جدیدترین
بسته پایدارِ اعلام‌کننده سازگاری با این build از OpenClaw را انتخاب می‌کنند. اگر
نسخه latest فعلی npm مقدار جدیدتری برای `openclaw.compat.pluginApi` یا
`openclaw.install.minHostVersion` نسبت به مقدار پشتیبانی‌شده این build اعلام کند، OpenClaw
نسخه‌های پایدار قدیمی‌تر را بررسی می‌کند و جدیدترین نسخه سازگار را نصب می‌کند. نسخه‌های دقیق
و برچسب‌های صریح کانال مانند `@beta` روی بسته انتخاب‌شده ثابت می‌مانند
و در صورت ناسازگاری ناموفق می‌شوند.

### سیاست نصب اپراتور

`security.installPolicy` را پیکربندی کنید تا پیش از ادامه نصب یا به‌روزرسانی یک Plugin،
یک دستور سیاست محلی مورداعتماد اجرا شود. سیاست، فراداده به‌همراه
مسیر منبع staging‌شده را دریافت می‌کند و می‌تواند نصب را مجاز یا مسدود کند. این سیاست هم مسیرهای نصب/به‌روزرسانی CLI
و هم مسیرهای مبتنی بر Gateway را پوشش می‌دهد. hookهای `before_install` مربوط به Plugin
بعداً و فقط در فرایندهای OpenClaw که hookهای Plugin در آن‌ها بارگذاری شده‌اند اجرا می‌شوند؛ بنابراین برای
تصمیم‌های نصب متعلق به اپراتور، به‌جای آن از `security.installPolicy` استفاده کنید. فلگ منسوخ
`--dangerously-force-unsafe-install` برای سازگاری پذیرفته می‌شود،
اما هیچ اثری ندارد: سیاست نصب یا denylist داخلی وابستگی‌های Plugin در OpenClaw را دور نمی‌زند.

برای schema مشترک اجرای `security.installPolicy` که هم Skills و هم
Pluginها از آن استفاده می‌کنند، به [پیکربندی Skills](/fa/tools/skills-config#operator-install-policy-securityinstallpolicy)
مراجعه کنید.

### پیکربندی سیاست Plugin

شکل رایج پیکربندی Plugin چنین است:

```json5
{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-plugin"] },
    slots: { memory: "memory-core" },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}
```

قواعد اصلی سیاست:

- `plugins.enabled: false` همه Pluginها را غیرفعال می‌کند و از کار
  کشف/بارگذاری صرف‌نظر می‌کند. ارجاع‌های قدیمی Plugin تا زمانی که این گزینه فعال است بی‌اثر می‌مانند؛ اگر می‌خواهید
  شناسه‌های قدیمی حذف شوند، پیش از اجرای پاک‌سازی doctor، Pluginها را دوباره فعال کنید.
- `plugins.deny` بر allow و فعال‌سازی هر Plugin اولویت دارد.
- `plugins.allow` یک allowlist انحصاری است. ابزارهای متعلق به Plugin خارج از
  allowlist حتی وقتی `tools.allow` شامل `"*"` باشد، در دسترس نمی‌مانند.
- `plugins.entries.<id>.enabled: false` یک Plugin را ضمن حفظ
  پیکربندی آن غیرفعال می‌کند.
- `plugins.load.paths` فایل‌ها یا دایرکتوری‌های صریح Plugin محلی را اضافه می‌کند.
  مسیرهای محلی مدیریت‌شده `plugins install` باید دایرکتوری یا
  بایگانی Plugin باشند؛ برای فایل‌های مستقل Plugin از `plugins.load.paths` استفاده کنید.
- Pluginهای منشأگرفته از workspace به‌طور پیش‌فرض غیرفعال‌اند؛ پیش از استفاده از
  کد workspace محلی، آن‌ها را صریحاً فعال یا به allowlist اضافه کنید.
- Pluginهای همراه بر اساس فراداده داخلی پیش‌فرض فعال/غیرفعال خود عمل می‌کنند،
  مگر اینکه پیکربندی صریحاً آن را بازنویسی کند.
- `plugins.slots.<slot>` (`memory` یا `contextEngine`) یک Plugin را برای یک
  دسته انحصاری انتخاب می‌کند. انتخاب slot به‌عنوان فعال‌سازی صریح محسوب می‌شود و
  Plugin انتخاب‌شده را برای آن slot به‌اجبار فعال می‌کند، حتی اگر در حالت عادی
  نیازمند فعال‌سازی اختیاری باشد. `plugins.deny` و `plugins.entries.<id>.enabled: false` همچنان
  آن را مسدود می‌کنند.
- Pluginهای همراهِ نیازمند فعال‌سازی اختیاری می‌توانند وقتی پیکربندی یکی از سطوح
  متعلق به آن‌ها را نام می‌برد، مانند ارجاع ارائه‌دهنده/مدل، پیکربندی کانال، backend ‏CLI
  یا زمان اجرای چارچوب عامل، به‌طور خودکار فعال شوند.
- مسیریابی Codex در خانواده OpenAI مرزهای Plugin ارائه‌دهنده و زمان اجرا را
  جدا نگه می‌دارد: ارجاع‌های قدیمی مدل Codex پیکربندی قدیمی‌ای هستند که doctor آن‌ها را اصلاح می‌کند،
  در حالی که Plugin همراه `codex` مالک زمان اجرای app-server مربوط به Codex برای
  ارجاع‌های استاندارد عامل `openai/*`، مقدار صریح `agentRuntime.id: "codex"` و
  ارجاع‌های قدیمی `codex/*` است.

وقتی `plugins.allow` تنظیم نشده باشد و Pluginهای غیرهمراه به‌طور خودکار از
workspace یا ریشه‌های سراسری Plugin کشف شوند، گزارش‌های راه‌اندازی
`plugins.allow is empty; discovered non-bundled plugins may auto-load: ...`
را همراه با شناسه‌های Plugin کشف‌شده و، برای فهرست‌های کوتاه، قطعه حداقلی `plugins.allow`
ثبت می‌کنند. پیش از کپی‌کردن Pluginهای مورداعتماد در `openclaw.json`، روی شناسه Plugin
فهرست‌شده [`openclaw plugins list --enabled --verbose`](/fa/cli/plugins#list)
یا [`openclaw plugins inspect <id>`](/fa/cli/plugins#inspect) را اجرا کنید. همین
ثابت‌سازی اعتماد هنگامی اعمال می‌شود که عیب‌یابی اعلام کند یک Plugin با
`without install/load-path provenance` بارگذاری شده است: آن شناسه Plugin را بررسی کنید، سپس آن را در
`plugins.allow` ثابت کنید یا از یک منبع مورداعتماد دوباره نصب کنید تا OpenClaw منشأ نصب را
ثبت کند.

وقتی اعتبارسنجی پیکربندی شناسه‌های قدیمی Plugin، عدم تطابق allowlist/ابزار
یا مسیرهای قدیمی Plugin همراه را گزارش می‌کند، `openclaw doctor` یا `openclaw doctor --fix` را اجرا کنید.

## آشنایی با قالب‌های Plugin

OpenClaw دو قالب Plugin را تشخیص می‌دهد:

| قالب                   | نحوه بارگذاری                                                                | زمان استفاده                                                            |
| ---------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Plugin بومی OpenClaw   | `openclaw.plugin.json` به‌همراه یک ماژول زمان اجرا که درون فرایند بارگذاری می‌شود | وقتی قابلیت‌های زمان اجرای مختص OpenClaw را نصب یا ایجاد می‌کنید        |
| بسته سازگار            | چیدمان Plugin مربوط به Codex،‏ Claude یا Cursor که به موجودی Pluginهای OpenClaw نگاشت می‌شود | وقتی Skills، دستورها، hookها یا فراداده بسته سازگار را دوباره استفاده می‌کنید |

هر دو قالب در `openclaw plugins list`، `openclaw plugins inspect`،
`openclaw plugins enable` و `openclaw plugins disable` ظاهر می‌شوند. برای مرز سازگاری بسته به
[بسته‌های Plugin](/fa/plugins/bundles) و برای ساخت Plugin بومی به
[ساخت Pluginها](/fa/plugins/building-plugins) مراجعه کنید.

## hookهای Plugin

Pluginها می‌توانند در زمان اجرا از طریق دو API متفاوت hook ثبت کنند:

- hookهای نوع‌دار `api.on(...)` برای رویدادهای چرخه‌عمر زمان اجرا. این
  سطح ترجیحی برای middleware، سیاست، بازنویسی پیام، شکل‌دهی prompt
  و کنترل ابزار است.
- `api.registerHook(...)` برای سیستم hook داخلی که در
  [Hookها](/fa/automation/hooks) توضیح داده شده است. این مورد عمدتاً برای اثرات جانبی کلی
  دستور/چرخه‌عمر و سازگاری با خودکارسازی موجود به سبک HOOK است.

قاعده سریع: اگر handler به اولویت، معناشناسی ادغام یا
رفتار مسدودسازی/لغو نیاز دارد، از hookهای نوع‌دار استفاده کنید. اگر فقط به `command:new`،
`command:reset`، `message:sent` یا رویدادهای کلی مشابه واکنش نشان می‌دهد، `api.registerHook`
مناسب است.

hookهای داخلی مدیریت‌شده توسط Plugin در `openclaw hooks list` با
`plugin:<id>` نمایش داده می‌شوند. نمی‌توانید آن‌ها را از طریق `openclaw hooks`
فعال یا غیرفعال کنید؛ در عوض خود Plugin را فعال یا غیرفعال کنید.

## تأیید Gateway فعال

`openclaw plugins list` و `openclaw plugins inspect` ساده، پیکربندی سرد،
مانیفست و وضعیت رجیستری را می‌خوانند. آن‌ها اثبات نمی‌کنند که یک
Gateway از قبل در حال اجرا، همان کد Plugin را وارد کرده است.

وقتی به نظر می‌رسد یک Plugin نصب شده، اما ترافیک زندهٔ گفت‌وگو از آن استفاده نمی‌کند:

```bash
openclaw gateway status --deep --require-rpc
openclaw plugins inspect <plugin-id> --runtime --json
openclaw gateway restart
```

Gatewayهای مدیریت‌شده پس از تغییرات نصب، به‌روزرسانی و حذف Plugin که
منبع Plugin را تغییر می‌دهند، به‌طور خودکار راه‌اندازی مجدد می‌شوند. در نصب‌های VPS یا کانتینری، مطمئن شوید
هر راه‌اندازی مجدد دستی، فرزند واقعی `openclaw gateway run` را که
کانال‌های شما را سرویس‌دهی می‌کند هدف قرار می‌دهد، نه فقط یک پوشش یا ناظر را.

## عیب‌یابی

| نشانه                                                        | بررسی                                                                                                                                      | راه‌حل                                                                                                     |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| Plugin در `plugins list` ظاهر می‌شود، اما هوک‌های زمان اجرا اجرا نمی‌شوند  | از `openclaw plugins inspect <id> --runtime --json` استفاده کنید و Gateway فعال را با `gateway status --deep --require-rpc` تأیید کنید             | پس از تغییرات نصب، به‌روزرسانی، پیکربندی یا منبع، Gateway زنده را راه‌اندازی مجدد کنید                               |
| عیب‌یابی‌های تکراری مالکیت کانال یا ابزار ظاهر می‌شوند         | `openclaw plugins list --enabled --verbose` را اجرا کنید، هر Plugin مشکوک را با `--runtime --json` بررسی کنید و مالکیت کانال/ابزار را مقایسه کنید | یکی از مالکان را غیرفعال کنید، نصب‌های منسوخ را حذف کنید یا برای جایگزینی عمدی از `preferOver` مانیفست استفاده کنید      |
| پیکربندی می‌گوید یک Plugin وجود ندارد                                | [فهرست موجودی Plugin](/fa/plugins/plugin-inventory) را بررسی کنید تا مشخص شود همراه، خارجی رسمی یا فقط منبع است                           | بستهٔ خارجی را نصب کنید، Plugin همراه را فعال کنید یا پیکربندی منسوخ را حذف کنید                         |
| پیکربندی هنگام نصب نامعتبر است                               | پیام اعتبارسنجی را بخوانید و اگر به وضعیت منسوخ Plugin اشاره دارد، `openclaw doctor --fix` را اجرا کنید                                             | Doctor می‌تواند با غیرفعال‌کردن ورودی و حذف محتوای نامعتبر، پیکربندی نامعتبر Plugin را قرنطینه کند     |
| مسیر Plugin به‌دلیل مالکیت یا مجوزهای مشکوک مسدود شده است | عیب‌یابی پیش از خطای پیکربندی را بررسی کنید                                                                                             | مالکیت/مجوزهای سیستم فایل را اصلاح کنید، سپس `openclaw plugins registry --refresh` را اجرا کنید                    |
| `OPENCLAW_NIX_MODE=1` فرمان‌های چرخهٔ عمر را مسدود می‌کند                | تأیید کنید که نصب توسط Nix مدیریت می‌شود                                                                                                      | به‌جای استفاده از فرمان‌های تغییردهندهٔ Plugin، انتخاب Plugin را در منبع Nix تغییر دهید                      |
| واردکردن وابستگی در زمان اجرا شکست می‌خورد                             | بررسی کنید که آیا Plugin از طریق npm/git/ClawHub نصب شده یا از یک مسیر محلی بارگذاری شده است                                                 | `openclaw plugins update <id>` را اجرا کنید، منبع را دوباره نصب کنید یا وابستگی‌های Plugin محلی را خودتان نصب کنید |

وقتی پیکربندی منسوخ Plugin همچنان یک Plugin کانال غیرقابل‌کشف را نام می‌برد،
اعتبارسنجی پیکربندی، کلید آن کانال را به‌جای شکست سخت به یک هشدار تنزل می‌دهد،
تا راه‌اندازی Gateway همچنان بتواند همهٔ کانال‌های دیگر را سرویس‌دهی کند.
برای حذف ورودی‌های منسوخ Plugin و کانال، `openclaw doctor --fix` را اجرا کنید. کلیدهای
ناشناختهٔ کانال بدون شواهد Plugin منسوخ همچنان در اعتبارسنجی شکست می‌خورند تا خطاهای تایپی
قابل‌مشاهده باقی بمانند.

برای جایگزینی عمدی کانال، Plugin ترجیحی باید
`channelConfigs.<channel-id>.preferOver` را با شناسهٔ Plugin قدیمی یا دارای اولویت پایین‌تر
اعلام کند. اگر هر دو Plugin به‌صراحت فعال باشند، OpenClaw آن درخواست را حفظ می‌کند
و به‌جای انتخاب بی‌سروصدای یک مالک، عیب‌یابی‌های تکراری کانال/ابزار را گزارش می‌دهد.

اگر یک بستهٔ نصب‌شده گزارش دهد که `requires compiled runtime output for
TypeScript entry ...`، آن بسته بدون فایل‌های JavaScript موردنیاز
OpenClaw در زمان اجرا منتشر شده است. پس از آنکه ناشر JavaScript
کامپایل‌شده را عرضه کرد، آن را به‌روزرسانی یا دوباره نصب کنید؛ یا تا آن زمان Plugin را غیرفعال/حذف کنید.

### مالکیت مسدودشدهٔ مسیر Plugin

اگر عیب‌یابی‌ها می‌گویند
`blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)`
و اعتبارسنجی با `plugin present but blocked` ادامه می‌یابد، OpenClaw
فایل‌های Plugin را یافته است که متعلق به یک کاربر Unix متفاوت از فرایند بارگذار آن‌ها هستند.
پیکربندی Plugin را در جای خود نگه دارید؛ مالکیت سیستم فایل را اصلاح کنید یا OpenClaw را
با همان کاربری اجرا کنید که مالک پوشهٔ وضعیت است.

برای نصب‌های Docker، تصویر رسمی با `node` (uid `1000`) اجرا می‌شود، بنابراین
پوشه‌های پیکربندی و فضای کاری OpenClaw که از میزبان bind mount شده‌اند، معمولاً باید
متعلق به uid `1000` باشند:

```bash
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
```

اگر عمداً OpenClaw را به‌عنوان root اجرا می‌کنید، در عوض مالکیت ریشهٔ Plugin مدیریت‌شده را
به root اصلاح کنید:

```bash
sudo chown -R root:root /path/to/openclaw-config/npm
```

پس از اصلاح مالکیت، `openclaw doctor --fix` یا
`openclaw plugins registry --refresh` را دوباره اجرا کنید تا رجیستری پایدار Plugin
با فایل‌های اصلاح‌شده مطابقت داشته باشد.

### راه‌اندازی کند ابزار Plugin

اگر به نظر می‌رسد نوبت‌های عامل هنگام آماده‌سازی ابزارها متوقف می‌شوند، ثبت رخداد سطح trace را فعال کنید
و خطوط زمان‌بندی کارخانهٔ ابزار Plugin را بررسی کنید:

```bash
openclaw config set logging.level trace
openclaw logs --follow
```

به‌دنبال این مورد بگردید:

```text
[trace:plugin-tools] زمان‌بندی‌های کارخانه ...
```

خلاصه، زمان کل کارخانه و کندترین کارخانه‌های ابزار Plugin را فهرست می‌کند،
از جمله شناسهٔ Plugin، نام‌های ابزار اعلام‌شده، شکل نتیجه و اختیاری‌بودن یا نبودن ابزار.
وقتی یک کارخانه دست‌کم 1s زمان ببرد یا آماده‌سازی کل کارخانهٔ ابزار Plugin دست‌کم 5s طول بکشد،
خطوط کند به هشدار ارتقا می‌یابند.

OpenClaw نتایج موفق کارخانهٔ ابزار Plugin را برای تفکیک‌های تکراری
با همان زمینهٔ مؤثر درخواست کش می‌کند. کلید کش شامل
پیکربندی مؤثر زمان اجرا، فضای کاری و شناسهٔ عامل، سیاست sandbox، تنظیمات مرورگر،
زمینهٔ تحویل، هویت درخواست‌کننده و وضعیت مالکیت است؛ بنابراین
کارخانه‌هایی که به این فیلدهای مورداعتماد وابسته‌اند، با تغییر زمینه
دوباره اجرا می‌شوند. اگر زمان‌بندی‌ها همچنان بالا بمانند، ممکن است Plugin پیش از
بازگرداندن تعریف‌های ابزار خود، کار پرهزینه‌ای انجام دهد.

اگر یک Plugin بر زمان‌بندی غالب است، ثبت‌های زمان اجرای آن را بررسی کنید:

```bash
openclaw plugins inspect <plugin-id> --runtime --json
```

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

برای ریشه‌های وابستگی، اعتبارسنجی فرادادهٔ بسته، رکوردهای رجیستری، رفتار
بارگذاری مجدد هنگام راه‌اندازی و پاک‌سازی قدیمی، به
[تفکیک وابستگی Plugin](/fa/plugins/dependency-resolution) مراجعه کنید.

## مرتبط

- [مدیریت Pluginها](/fa/plugins/manage-plugins) - نمونه‌فرمان‌های فهرست‌کردن، نصب، به‌روزرسانی، حذف و انتشار
- [`openclaw plugins`](/fa/cli/plugins) - مرجع کامل CLI
- [فهرست موجودی Plugin](/fa/plugins/plugin-inventory) - فهرست تولیدشدهٔ Pluginهای همراه و خارجی
- [مرجع Plugin](/fa/plugins/reference) - صفحات مرجع تولیدشده برای هر Plugin
- [Pluginهای جامعه](/fa/plugins/community) - سیاست کشف ClawHub و PR مستندات
- [تفکیک وابستگی Plugin](/fa/plugins/dependency-resolution) - ریشه‌های نصب، رکوردهای رجیستری و مرزهای زمان اجرا
- [ساخت Pluginها](/fa/plugins/building-plugins) - راهنمای توسعهٔ Plugin بومی
- [نمای کلی SDKِ Plugin](/fa/plugins/sdk-overview) - ثبت زمان اجرا، هوک‌ها و فیلدهای API
- [مانیفست Plugin](/fa/plugins/manifest) - مانیفست و فرادادهٔ بسته