نمای کلی SDK افزونه

قرارداد نوع‌دار میان Pluginها و هسته، SDK مربوط به Plugin است. این صفحه مرجع موارد قابل واردکردن و موارد قابل ثبت است.

قرارداد واردکردن

همیشه از یک زیرمسیر مشخص وارد کنید:

هر زیرمسیر، ماژولی کوچک و خودبسنده است. این کار راه‌اندازی را سریع نگه می‌دارد و از مشکلات وابستگی دوری جلوگیری می‌کند. برای کمک‌تابع‌های ورودی/ساخت ویژهٔ کانال، openclaw/plugin-sdk/channel-core را ترجیح دهید؛ openclaw/plugin-sdk/core را برای سطح جامع‌تر و کمک‌تابع‌های مشترکی مانند buildChannelConfigSchema نگه دارید.

برای پیکربندی کانال، JSON Schema متعلق به کانال را از طریق openclaw.plugin.json#channelConfigs منتشر کنید. زیرمسیر plugin-sdk/channel-config-schema برای اجزای اولیهٔ طرح‌وارهٔ مشترک و سازندهٔ عمومی است. Pluginهای همراه OpenClaw از plugin-sdk/bundled-channel-config-schema برای طرح‌واره‌های حفظ‌شدهٔ کانال‌های همراه استفاده می‌کنند. آن زیرمسیر طرح‌وارهٔ همراه، الگویی برای Pluginهای جدید نیست.

مرجع زیرمسیرها

SDK مربوط به Plugin به‌صورت مجموعه‌ای از زیرمسیرهای محدود، گروه‌بندی‌شده بر اساس حوزه (ورودی Plugin، کانال، ارائه‌دهنده، احراز هویت، زمان اجرا، قابلیت، حافظه و کمک‌تابع‌های رزروشدهٔ Pluginهای همراه) ارائه می‌شود. برای فهرست کاملِ گروه‌بندی‌شده و پیونددار، به زیرمسیرهای SDK مربوط به Plugin مراجعه کنید.

فهرست نقاط ورودی کامپایلر در scripts/lib/plugin-sdk-entrypoints.json قرار دارد؛ خروجی‌های عمومی نوع‌دار، زیرمسیرهای داخلی فهرست‌شده در scripts/lib/plugin-sdk-private-local-only-subpaths.json را مستثنا می‌کنند. ورودی‌های عملیاتی موجود در آن فهرست، خروجی‌های زمان اجرای میزبانِ صرفاً JavaScript را برای Pluginهای رسمیِ جداگانه منتشرشده حفظ می‌کنند، درحالی‌که ورودی‌های صرفاً آزمایشی صادر نمی‌شوند. برای ممیزی تعداد خروجی‌های عمومی، pnpm plugin-sdk:surface را اجرا کنید. زیرمسیرهای عمومی منسوخی که به‌اندازهٔ کافی قدیمی هستند و کد عملیاتی افزونه‌های همراه از آن‌ها استفاده نمی‌کند، در scripts/lib/plugin-sdk-deprecated-public-subpaths.json ردیابی می‌شوند؛ barrelهای گستردهٔ بازصدور منسوخ نیز در scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json ردیابی می‌شوند.

API ثبت

فراخوان برگشتی register(api) یک شیء OpenClawPluginApi با روش‌های زیر دریافت می‌کند:

Pluginهایی که برای یک نشست، سطح گفت‌وگوی تیمی خارجی فراهم می‌کنند می‌توانند ارائه‌دهندهٔ یگانهٔ سراسری فرایند را که از openclaw/plugin-sdk/session-discussion صادر می‌شود ثبت کنند. روش info({ sessionKey }) آن گزارش می‌دهد که آیا یک گفت‌وگو در دسترس نیست، آمادهٔ بازشدن است یا از پیش باز است؛ open({ sessionKey }) گفت‌وگو را ایجاد یا رفع می‌کند و URLهای جاسازی‌شده و خارجی آن را برمی‌گرداند. ثبت ارائه‌دهنده‌ای دیگر، ارائه‌دهندهٔ فعلی را جایگزین می‌کند.

ثبت قابلیت

ارائه‌دهندگان کارگر باید شناسهٔ خود را نیز در contracts.workerProviders اعلام کنند. هسته پیش از provision(profile, operationId) قصد پایدار را ذخیره می‌کند. ارائه‌دهندگان پیش از تخصیص خارجی، تنظیمات را اعتبارسنجی می‌کنند و برای رد دائمی نمایه، WorkerProviderError را پرتاب می‌کنند. هنگامی که شناسهٔ عملیات تکرار می‌شود، provision باید همان اجاره را به‌کار گیرد. هسته تنظیمات نمایهٔ اعتبارسنجی‌شده را همراه اجاره ذخیره می‌کند و آن تصویر لحظه‌ای را به destroy({ leaseId, profile })، که باید هم‌توان باشد، و inspect({ leaseId, profile }) ارائه می‌دهد که active، destroyed یا unknown را برمی‌گرداند. این امر به ارائه‌دهندگان امکان می‌دهد فراخوانی‌های چرخهٔ عمر را پس از راه‌اندازی مجدد Gateway یا حذف نمایهٔ نام‌گذاری‌شده مسیریابی کنند. نقاط پایانی SSH برای keyRef از یک SecretRef استفاده می‌کنند، هرگز از مواد کلید درون‌خطی استفاده نمی‌کنند، و یک hostKey را از خروجی تأمین قابل‌اعتماد، دقیقاً به‌شکل algorithm base64 و بدون نام میزبان یا توضیح، شامل می‌شوند. هسته hostKey را سنجاق می‌کند و هرگز به کلیدی از نخستین اتصال اعتماد نمی‌کند. ارائه‌دهنده‌ای که یک keyRef پویا ایجاد می‌کند می‌تواند resolveSshIdentity({ leaseId, profile, keyRef }) را پیاده‌سازی کند؛ در صورت وجود، آن رفع‌کننده مرجع قطعی است، درحالی‌که ارائه‌دهندگان فاقد آن از رفع‌کنندهٔ عمومی رازِ پیکربندی‌شده استفاده می‌کنند. ارائه‌دهندگان دارای اجاره‌های قابل‌تمدید می‌توانند renew(leaseId) را نیز پیاده‌سازی کنند. inspect باید در شکست‌های گذرا یا نامعین استثنا پرتاب کند؛ فقط برای نبود قطعی، unknown را برگردانید. هسته یک رکورد محلی فعال را یتیم علامت‌گذاری می‌کند، یا پس از یک درخواست تخریب ذخیره‌شده، نبود را به‌عنوان تکمیل برچیدن در نظر می‌گیرد.

ارائه‌دهندگان تعبیه که با api.registerEmbeddingProvider(...) ثبت می‌شوند باید در contracts.embeddingProviders در مانیفست Plugin نیز فهرست شوند. این سطح عمومی تعبیه برای تولید بردار قابل‌استفادهٔ مجدد است. جست‌وجوی حافظه می‌تواند این سطح عمومی ارائه‌دهنده را مصرف کند. رابط قدیمی‌تر api.registerMemoryEmbeddingProvider(...) و contracts.memoryEmbeddingProviders در دورهٔ مهاجرت ارائه‌دهندگان موجودِ ویژهٔ حافظه، به‌عنوان سازگاری منسوخ باقی می‌ماند.

ارائه‌دهندگان ویژهٔ حافظه که همچنان یک batchEmbed(...) زمان اجرا ارائه می‌کنند، بر قرارداد دسته‌بندی موجود به‌ازای هر فایل باقی می‌مانند، مگر اینکه زمان اجرای آن‌ها صراحتاً sourceWideBatchEmbed: true را تنظیم کند. این انتخاب به میزبان حافظه امکان می‌دهد قطعه‌های چندین فایل حافظهٔ تغییرکرده و منبع فعال را، تا سقف محدودیت‌های دستهٔ میزبان، در یک فراخوانی batchEmbed(...) ارسال کند. سازگارکننده‌های دسته‌ای که فایل‌های درخواست JSONL بارگذاری می‌کنند باید کارهای ارائه‌دهنده را هم پیش از سقف اندازهٔ بارگذاری و هم پیش از سقف تعداد درخواست آن‌ها تقسیم کنند. ارائه‌دهنده باید برای هر قطعهٔ ورودی، یک تعبیه را با همان ترتیب batch.chunks برگرداند؛ هنگامی که ارائه‌دهنده انتظار دسته‌های محلی فایل را دارد یا نمی‌تواند ترتیب ورودی را در یک کار بزرگ‌ترِ سراسری منبع حفظ کند، این پرچم را حذف کنید.

ابزارها و فرمان‌ها

برای Pluginهای سادهٔ صرفاً ابزاری با نام ابزارهای ثابت، از defineToolPlugin استفاده کنید. برای Pluginهای ترکیبی یا ثبت کاملاً پویا‌ی ابزار، مستقیماً از api.registerTool(...) استفاده کنید.

هنگامی که عامل به یک راهنمای کوتاه مسیریابی متعلق به فرمان نیاز دارد، فرمان‌های Plugin می‌توانند agentPromptGuidance را تنظیم کنند. آن متن را دربارهٔ خود فرمان نگه دارید؛ سیاست ویژهٔ ارائه‌دهنده یا Plugin را به سازنده‌های اعلان هسته اضافه نکنید.

ورودی‌های راهنما می‌توانند رشته‌های قدیمی باشند که بر همهٔ سطوح اعلان اعمال می‌شوند، یا ورودی‌های ساخت‌یافته:

agentPromptGuidance: [  "راهنمای سراسری فرمان.",  { text: "این را فقط در اعلان اصلی OpenClaw نمایش دهید.", surfaces: ["openclaw_main"] },];

surfaces ساختاریافته ممکن است شامل openclaw_main، codex_app_server، cli_backend، acp_backend یا subagent باشد. pi_main همچنان نام مستعار منسوخ‌شده‌ای برای openclaw_main است. برای راهنمایی عمدی همهٔ سطوح، surfaces را حذف کنید. یک آرایهٔ خالی surfaces ارسال نکنید؛ این آرایه رد می‌شود تا از تبدیل‌شدن ازدست‌رفتن تصادفی دامنه به متن سراسری پرامپت جلوگیری شود.

دستورالعمل‌های توسعه‌دهندهٔ بومی app-server در Codex از سایر سطوح پرامپت سخت‌گیرانه‌ترند: فقط راهنمایی‌ای که صراحتاً به codex_app_server محدود شده باشد، به آن مسیر با اولویت بالاتر ارتقا می‌یابد. راهنمایی رشته‌ای قدیمی و راهنمایی ساختاریافتهٔ بدون دامنه برای سازگاری همچنان در دسترس سطوح پرامپت غیر Codex باقی می‌مانند.

فرمان‌های میزبان Node روی میزبان Node متصل اجرا می‌شوند، نه داخل فرایند Gateway. اگر agentTool وجود داشته باشد، Node پس از اتصال موفق به Gateway یک توصیفگر منتشر می‌کند؛ Gateway آن را فقط تا زمانی که آن Node متصل است و فقط در صورتی در اختیار اجراهای عامل قرار می‌دهد که command توصیفگر در سطح فرمان‌های تأییدشدهٔ Node باشد. برای افزودن یک فرمان غیرخطرناک به فهرست مجاز پیش‌فرض فرمان‌های Node، agentTool.defaultPlatforms را تنظیم کنید؛ در غیر این صورت، gateway.nodes.commands.allow صریح یا یک سیاست فراخوانی Node لازم است. agentTool.name باید برای ارائه‌دهنده ایمن باشد: با یک حرف شروع شود، فقط از حروف، ارقام، زیرخط یا خط تیره استفاده کند و حداکثر 64 نویسه داشته باشد. ابزارهای Node مبتنی بر MCP می‌توانند فرادادهٔ agentTool.mcp را تنظیم کنند تا سطوح کاتالوگ و جست‌وجوی ابزار بتوانند هویت سرور/ابزار MCP راه‌دور را نمایش دهند، اما اجرا همچنان از طریق فرمان اعلام‌شدهٔ Node انجام می‌شود.

زیرساخت

کار Webhook پس از تأیید

مسیرهای Webhook که پیش از پایان پردازش یک درخواست را تأیید می‌کنند، باید آن کار جداشده را به ریشهٔ پذیرش رهگیری‌شدهٔ مستقل خودش منتقل کنند:

 void runDetachedWebhookWork(() => processWebhookEvent(event)).catch((error) => {  runtime.error?.(`ارسال webhook ناموفق بود: ${String(error)}`);});

runDetachedWebhookWork(...) را هنگامی که درخواست HTTP هنوز پذیرفته شده است، به‌صورت همگام فراخوانی کنید. این تابع کمکی بلافاصله یک ریشهٔ مستقل رزرو می‌کند، سپس فراخوان بازگشتی را در ریزوظیفهٔ بعدی آغاز می‌کند تا رسیدگی‌کنندهٔ درخواست بتواند ابتدا تأیید خود را بنویسد. promise بازگشتی نتیجهٔ فراخوان بازگشتی را می‌پذیرد؛ رسیدگی به ردشدن همچنان بر عهدهٔ فراخواننده است. این کار باعث می‌شود کار صف پس از تأیید پذیرفته بماند و تخلیه‌های راه‌اندازی مجدد یا تعلیق منتظر آن بمانند. رسیدگی‌کننده‌هایی که پیش از بازگشت منتظر تکمیل تمام پردازش می‌مانند، به این تابع کمکی نیاز ندارند.

اتصال‌های MCP محدود به درخواست‌کننده

هویت سرور MCP (نام، فیلتر ابزار) را در mcp.servers، فیلد مانیفست mcpServers یک Plugin بومی یا یک مانیفست بسته، ایستا نگه دارید. در صورت تمایل، یک حل‌کنندهٔ اتصال ثبت کنید تا هر درخواست‌کنندهٔ مورداعتماد پیام، انتقال اختصاصی خود را دریافت کند:

api.registerMcpServerConnectionResolver({  serverName: "user-email",  resolve: async (ctx) => {    // ctx.requesterSenderId is host-trusted; never invent sender identity here.    const token = await lookupUserToken(ctx.requesterSenderId);    if (!token) {      return null; // omit this server for the current run    }    return {      url: "https://mcp.example.com/email",      headers: { Authorization: `Bearer ${token}` },    };  },});

یادداشت‌های قرارداد:

• زمینهٔ حل‌کننده فقط هویت مورداعتماد میزبان را حمل می‌کند (requesterSenderId، و agentAccountId / messageChannel اختیاری). فیلدهای مورداعتماد آینده (برای نمونه، زمینهٔ کاربر cron/زیرعامل) را می‌توان به‌صورت افزایشی اضافه کرد.
• هر Plugin مالک یک نام سرور است: registerMcpServerConnectionResolver تکراری برای همان serverName از یک Plugin دیگر با یک پیام تشخیصی خطا رد می‌شود (اولین ثبت برنده است)، بنابراین مالکیت اتصال هرگز به ترتیب بارگیری Plugin وابسته نیست.
• نام ابزارها از مجموعهٔ کامل سرورهای اعلام‌شده مشتق می‌شوند تا حل جزئی هرگز نام‌های امن سرور را میان درخواست‌کنندگان یا نوبت‌ها تغییر ندهد. هسته تأیید نمی‌کند که نقاط پایانی درخواست‌کنندگان مختلف طرح‌واره‌های ابزار یکسانی ارائه می‌دهند؛ حل‌کننده باید هر درخواست‌کننده را به همان سرویس منطقی هدایت کند، وگرنه طرح‌واره‌های ابزار (و پایداری کش پرامپت) به‌ازای هر درخواست‌کننده واگرا می‌شوند.
• اجراهای بدون requesterSenderId مورداعتماد (cron، زیرعامل، heartbeat، Gateway عمومی) هرگز سرورهای محدود به درخواست‌کننده را ایجاد نمی‌کنند. هیچ اتصال جایگزین مشترکی وجود ندارد.
• resolve برای هر سرور به 10 ثانیه محدود است؛ پایان مهلت یا پرتاب خطا، آن سرور را بدون شکست‌دادن MCP ایستا از اجرا حذف می‌کند.
• اتصال‌های حل‌شده حداکثر هر 5 دقیقه یک‌بار به‌ازای هر درخواست‌کننده دوباره اعتبارسنجی می‌شوند: چرخش، انتقال را با اعتبارنامه‌های تازه بازسازی می‌کند و نتیجهٔ null آن را لغو می‌کند (زمان اجرای کش‌شده حتی در میانهٔ نشست نیز کنار گذاشته می‌شود). بنابراین یک اعتبارنامهٔ لغوشده یا چرخیده می‌تواند تا 5 دقیقه همچنان در حال استفاده بماند.
• headers حل‌شده هرگز ثبت یا ماندگار نمی‌شوند؛ هسته برای تشخیص چرخش اعتبارنامه فقط یک چکیدهٔ کلیددار زودگذر در حافظه (HMAC محلی فرایند) نگه می‌دارد و مقادیر اعتبارنامهٔ URL/سرآیند حل‌شده را در رجیستری پوشانندگی ثبت وقایع/ثبت اشکال‌زدایی ثبت می‌کند.
• سرورهای محدود به درخواست‌کننده نماهای MCP App ایجاد نمی‌کنند: یک نما بیش از اجرای احراز هویت‌شدهٔ درخواست‌کننده عمر می‌کند و مرز نمای Gateway هیچ هویت درخواست‌کننده‌ای ندارد، بنابراین پیش‌نمایش‌های برنامه برای این سرورها به‌صورت بسته و امن باقی می‌مانند. نتایج ابزار تحت‌تأثیر نیستند.
• سرورهای ایستای بدون حل‌کننده، چرخهٔ عمر محدود به نشست موجود را حفظ می‌کنند.
• قاعدهٔ تحویل هارنس: سرورهای محدود به درخواست‌کننده هرگز وارد پیکربندی بومی کلاینت MCP هارنس نمی‌شوند (رشتهٔ Codex mcp_servers، CLI -c mcp_servers=… یا هر فرافکنی MCP مشترک دیگر در نشست). در عوض، هارنس‌ها آن‌ها را به‌صورت ابزارهای محدود به اجرا تحویل می‌دهند:
  • اجراکنندهٔ توکار: زمان اجرای MCP نشست + ابزارهای بسته (ایستا + محدود).
  • app-server در Codex: ابزارهای پویا از طریق materializeRequesterScopedMcpToolsForHarnessRun (فقط محدود؛ سرورهای ایستا روی کلاینت بومی MCP در Codex باقی می‌مانند).
• مشخصات ابزار محدود پس از نخستین حل موفق در آن نشست، در سطح نشست پایدار می‌مانند؛ بنابراین هارنس‌های دارای رشتهٔ مشترک (Codex) هنگام تغییر فرستنده رشته‌ها را نمی‌چرخانند. پیش از حل‌شدن برای هر درخواست‌کننده، هیچ مشخصات محدودی اعلام نمی‌شود.
• درخواست‌کنندگان احراز هویت‌نشده در یک هارنس دارای رشتهٔ مشترک همچنان ابزارهای محدود اعلام‌شده را می‌بینند؛ فراخوانی هرکدام برای آن درخواست‌کننده یک خطای ابزار تمیزِ متصل‌نبودن برمی‌گرداند. OpenClaw هرگز به اعتبارنامه‌های درخواست‌کننده‌ای دیگر متوسل نمی‌شود.

سازندگان مکمل پرامپت حافظه، زمینهٔ اختیاری agentId، agentSessionKey و sandboxed را دریافت می‌کنند. فراخوانی‌های search و get مکمل پیکرهٔ حافظه، زمینهٔ اختیاری agentId و sandboxed را دریافت می‌کنند. Pluginهای دارای ذخیره‌سازی تحت مالکیت عامل باید به‌جای ثبت یک مسیر سراسری هنگام ثبت، آن ذخیره‌سازی را برای هر فراخوانی حل کنند. اگر شناسهٔ عامل لازم باشد اما در عملیاتی چندعاملی وجود نداشته باشد، به‌جای انتخاب عاملی دلخواه، به‌صورت بسته و امن شکست بخورید.

هنگامی که متن پرامپت به وضعیت ناهمگام Plugin وابسته است، از registerMemoryPromptPreparation(...) استفاده کنید. فراخوان بازگشتی پیش از هر پرامپت کامل عامل یک‌بار اجرا می‌شود و همان زمینهٔ ابزار، عامل، نشست و sandbox سازندگان همگام پرامپت حافظه را دریافت می‌کند. پیش از بارگیری وضعیت ماندگار، نمونهٔ فعلی مالک ذخیره‌سازی را اعتبارسنجی کنید، سپس فقط خطوط مربوط به همان اجرا را برگردانید. OpenClaw آن خطوط را ثابت می‌کند و نتیجهٔ تغییرناپذیر را به مونتاژ همگام پرامپت تحویل می‌دهد. ماندگاری، جایگزینی اتمی و حذف هنگام برداشتن مالک را درون Plugin مالک نگه دارید؛ از سازندهٔ پرامپت فایل‌ها را نظرسنجی یا خوانده نکنید.

رسیدگی‌کننده‌های تعاملی Telegram می‌توانند { submitText } را برگردانند تا پس از موفقیت رسیدگی‌کننده، متن از مسیر عادی ورودی عامل در Telegram عبور کند. وقتی سیاست ورودی متن را رد می‌کند یا پردازش شکست می‌خورد، OpenClaw دکمهٔ فراخوان بازگشتی را نگه می‌دارد تا کاربر پس از تغییر وضعیت مسدودکننده بتواند دوباره تلاش کند. این فیلد نتیجه مختص Telegram است؛ کانال‌های دیگر قراردادهای نتیجهٔ تعاملی خود را حفظ می‌کنند.

هوک‌های میزبان برای Pluginهای گردش کار

هوک‌های میزبان، درگاه‌های SDK برای Pluginهایی هستند که باید به‌جای صرفاً افزودن یک ارائه‌دهنده، کانال یا ابزار، در چرخهٔ عمر میزبان مشارکت کنند. آن‌ها قراردادهایی عمومی‌اند؛ Plan Mode می‌تواند از آن‌ها استفاده کند، اما گردش‌کارهای تأیید، دروازه‌های سیاست فضای کاری، پایشگرهای پس‌زمینه، جادوگرهای راه‌اندازی و Pluginهای همراه UI نیز می‌توانند از آن‌ها بهره ببرند.

یک توصیفگر surface: "tab" زبانه‌ای را به نوار کناری رابط کاربری کنترل اضافه می‌کند. توصیفگرهای زبانهٔ Pluginهای فعال در پیام خوشامد Gateway (controlUiTabs) به کلاینت‌های داشبورد اعلام می‌شوند؛ بنابراین زبانه فقط تا زمانی نمایش داده می‌شود که Plugin فعال باشد. Pluginهای همراه می‌توانند برای زبانهٔ خود یک نمای داشبورد درجه‌یک ارائه کنند؛ سایر Pluginها می‌توانند path را روی یک مسیر HTTP متعلق به Plugin تنظیم کنند (نگاه کنید به api.registerHttpRoute(...)) تا داشبورد آن را در یک قاب سندباکس‌شده نمایش دهد. icon راهنمای نام آیکون داشبورد است، group بخش نوار کناری را انتخاب می‌کند (control یا agent)، order ترتیب میان زبانه‌های Plugin را تعیین می‌کند و requiredScopes زبانه را از اتصال‌هایی که آن دامنه‌های دسترسی اپراتور را ندارند پنهان می‌کند:

برای یک زبانهٔ خارجیِ محافظت‌شده با Gateway، توصیفگر path را زیر یک مسیر HTTP هم‌Plugin با auth: "gateway" ثبت کنید. پس از راه‌اندازی اولیهٔ احرازشده، مرورگر یک مجوز کوتاه‌عمر و HttpOnly دریافت می‌کند که به همان Plugin و ریشهٔ مسیر محدود است تا قاب سندباکس‌شده بتواند بدون کپی‌کردن توکن حامل Gateway در URL یا JavaScript خود بارگذاری شود. والد احرازشده، در مدت فعال‌بودن زبانهٔ خارجی و پیش از سوارکردن آن پس از پیمایش یا ازسرگیری مرورگر، مجوز را تمدید می‌کند. همچنین پیش از سوارکردن، مجوز را از همان سندباکس مات بررسی می‌کند تا حالت‌های حریم خصوصی مرورگر که کوکی را مسدود می‌کنند، به‌صورت بسته شکست بخورند و پنلی دردسترس‌نبودنی نمایش داده شود. مجوز قاب فقط GET و HEAD را می‌پذیرد و همیشه operator.read را حمل می‌کند؛ requiredScopes نمایان‌بودن زبانه را کنترل می‌کند، اما هرگز دامنهٔ مجوز کوکی را گسترش نمی‌دهد. تغییرات همچنان روی سطوح والد یا حاملِ دارای احراز هویت صریح Gateway باقی می‌مانند. زبانه‌های خارجی به HTTPS/Tailscale Serve یا یک مبدأ loopback مورداعتماد مرورگر نیاز دارند؛ HTTP ساده روی یک میزبان LAN به‌جای سوارکردن پنلی که نمی‌تواند احراز هویت شود، خطای زمینهٔ امن را نمایش می‌دهد. مسدودسازی کامل کوکی‌های شخص ثالث نیز زبانه‌های محافظت‌شده با Gateway را دردسترس‌ناپذیر می‌کند. همانند همهٔ سطوح بومی Plugin، قاب درون مرز اعتماد Plugin نصب‌شده باقی می‌ماند؛ OpenClaw، Pluginهای نصب‌شده را به‌عنوان هویت‌های امنیتی مرورگر که متقابلاً از یکدیگر جدا هستند در نظر نمی‌گیرد. مجوزهای کوکی از مرز نام میزبان مرورگر استفاده می‌کنند، نه مرز پورت آن. حتی روی پورت‌های دیگر نیز سرویس‌هایی را که متقابلاً به یکدیگر اعتماد ندارند روی نام میزبان Gateway هم‌میزبانی نکنید. زبانه‌هایی که احراز هویتشان توسط Plugin مدیریت می‌شود، رفتار مستقیم iframe خود را حفظ می‌کنند و این مجوز Gateway را درخواست یا الزامی نمی‌کنند.

api.session.controls.registerControlUiDescriptor({  surface: "tab",  id: "logbook",  label: "Logbook",  description: "Your day as a timeline, built from screen snapshots.",  icon: "sun",  group: "control",  requiredScopes: ["operator.write"],});

برای کد جدید Plugin از فضاهای نام گروه‌بندی‌شده استفاده کنید:

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

متدهای تخت معادل، همچنان به‌عنوان نام‌های مستعار سازگاری منسوخ‌شده برای Pluginهای موجود دردسترس‌اند. کد جدید Plugin را به‌گونه‌ای اضافه نکنید که مستقیماً api.registerSessionExtension، api.enqueueNextTurnInjection، api.registerControlUiDescriptor، api.registerRuntimeLifecycle، api.registerAgentEventSubscription، api.emitAgentEvent، api.setRunContext، api.getRunContext، api.clearRunContext، api.registerSessionSchedulerJob، api.registerSessionAction، api.sendSessionAttachment، api.scheduleSessionTurn یا api.unscheduleSessionTurnsByTag را فراخوانی کند.

scheduleSessionTurn(...) یک تسهیل‌گر محدود به نشست روی زمان‌بند Cron در Gateway است. Cron مالک زمان‌بندی است و هنگام اجرای نوبت، رکورد وظیفهٔ پس‌زمینه را ایجاد می‌کند؛ SDK مربوط به Plugin فقط نشست مقصد، نام‌گذاری تحت مالکیت Plugin و پاک‌سازی را محدود می‌کند. هنگامی که خود کار به وضعیت پایدار چندمرحله‌ای Task Flow نیاز دارد، درون نوبت زمان‌بندی‌شده از api.runtime.tasks.managedFlows استفاده کنید.

قراردادها عمداً اختیار را تفکیک می‌کنند:

• Pluginهای خارجی می‌توانند مالک افزونه‌های نشست، توصیفگرهای رابط کاربری، فرمان‌ها، فرادادهٔ ابزار، تزریق‌های نوبت بعدی و قلاب‌های عادی باشند.
• سیاست‌های مورداعتماد ابزار پیش از قلاب‌های عادی before_tool_call اجرا می‌شوند و مورداعتماد میزبان هستند. سیاست‌های همراه ابتدا اجرا می‌شوند؛ سیاست‌های Pluginهای نصب‌شده به فعال‌سازی صریح به‌همراه شناسه‌های محلی‌شان در contracts.trustedToolPolicies نیاز دارند و سپس به‌ترتیب بارگذاری Plugin اجرا می‌شوند. شناسه‌های سیاست به Plugin ثبت‌کننده محدود هستند.
• مالکیت فرمان‌های رزروشده فقط برای Pluginهای همراه است. Pluginهای خارجی باید از نام‌ها یا نام‌های مستعار فرمان خود استفاده کنند.
• allowPromptInjection=false قلاب‌های تغییردهندهٔ پرامپت، از جمله agent_turn_prepare، before_prompt_build، heartbeat_prompt_contribution و enqueueNextTurnInjection را غیرفعال می‌کند.

نمونه‌هایی از مصرف‌کنندگان غیر Plan:

ثبت کشف Gateway

api.registerGatewayDiscoveryService(...) به یک Plugin اجازه می‌دهد Gateway فعال را در یک انتقال کشف محلی مانند mDNS/Bonjour اعلام کند. هنگامی که کشف محلی فعال باشد، OpenClaw سرویس را هنگام راه‌اندازی Gateway فراخوانی می‌کند، پورت‌های فعلی Gateway و داده‌های راهنمای غیرمحرمانهٔ TXT را به آن می‌دهد و هنگام خاموش‌شدن Gateway، کنترل‌کنندهٔ stop بازگردانده‌شده را فراخوانی می‌کند.

api.registerGatewayDiscoveryService({  id: "my-discovery",  async advertise(ctx) {    const handle = await startMyAdvertiser({      gatewayPort: ctx.gatewayPort,      tls: ctx.gatewayTlsEnabled,      displayName: ctx.machineDisplayName,    });    return { stop: () => handle.stop() };  },});

Pluginهای کشف Gateway نباید مقادیر TXT اعلام‌شده را محرمانه یا ابزار احراز هویت در نظر بگیرند. کشف فقط یک راهنمای مسیریابی است؛ احراز هویت Gateway و پین‌کردن TLS همچنان مالک اعتماد هستند.

فرادادهٔ ثبت CLI

api.registerCli(registrar, opts?) دو نوع فرادادهٔ فرمان را می‌پذیرد:

• commands: نام‌های صریح فرمان که تحت مالکیت ثبت‌کننده هستند
• descriptors: توصیفگرهای فرمان در زمان تجزیه که برای راهنمای CLI، مسیریابی و ثبت تنبل CLI مربوط به Plugin استفاده می‌شوند
• parentPath: مسیر اختیاری فرمان والد برای گروه‌های فرمان تودرتو، مانند ["nodes"]

برای قابلیت‌های Node جفت‌شده، api.registerNodeCliFeature(registrar, opts?) را ترجیح دهید. این یک پوشش کوچک پیرامون api.registerCli(..., { parentPath: ["nodes"] }) است و فرمان‌هایی مانند openclaw nodes canvas را به‌صورت قابلیت‌های Node که صریحاً تحت مالکیت Plugin هستند تعریف می‌کند.

اگر می‌خواهید یک فرمان Plugin در مسیر عادی CLI ریشه به‌صورت تنبل بارگذاری شود، descriptors را ارائه دهید که همهٔ ریشه‌های فرمان سطح‌بالای ارائه‌شده توسط آن ثبت‌کننده را پوشش دهد.

api.registerCli(  async ({ program }) => {    const { registerMatrixCli } = await import("./src/cli.js");    registerMatrixCli({ program });  },  {    descriptors: [      {        name: "matrix",        description: "مدیریت حساب‌ها، تأیید، دستگاه‌ها و وضعیت نمایه Matrix",        hasSubcommands: true,      },    ],  },);

فرمان‌های تودرتو فرمان والدِ تفکیک‌شده را به‌صورت program دریافت می‌کنند:

api.registerCli(  async ({ program }) => {    const { registerNodesCanvasCommands } = await import("./src/cli.js");    registerNodesCanvasCommands(program);  },  {    parentPath: ["nodes"],    descriptors: [      {        name: "canvas",        description: "ثبت یا رندر محتوای بوم از یک Node جفت‌شده",        hasSubcommands: true,      },    ],  },);

تنها زمانی از commands به‌تنهایی استفاده کنید که به ثبت تنبل CLI ریشه نیازی ندارید. آن مسیر سازگاریِ eager همچنان پشتیبانی می‌شود، اما برای بارگذاری تنبل در زمان تجزیه، جای‌نگهدارهای مبتنی بر توصیف‌گر را نصب نمی‌کند.

ثبت بک‌اند CLI

api.registerCliBackend(...) به یک Plugin اجازه می‌دهد مالک پیکربندی پیش‌فرض یک بک‌اند محلی CLI هوش مصنوعی مانند claude-cli یا my-cli باشد.

• id بک‌اند به پیشوند ارائه‌دهنده در ارجاع‌های مدل مانند my-cli/gpt-5 تبدیل می‌شود.
• config بک‌اند، آداپتور فرمانِ مرجع است: رفتار argv، محیط، تجزیه‌گر، نشست، تصویر و قابلیت اطمینان در کد Plugin قرار دارد.
• کاربران بک‌اند را از طریق ارجاع‌های مدل یا agentRuntime.id محدود به مدل انتخاب می‌کنند؛ openclaw.json آداپتور را بازنویسی نمی‌کند.
• هنگامی که فیلدهای ایستای ثبت‌شده به یک گذر نرمال‌سازی آگاه از زمان اجرا نیاز دارند، از normalizeConfig استفاده کنید.
• برای بازنویسی‌های argv محدود به درخواست که به گویش CLI تعلق دارند، از resolveExecutionArgs استفاده کنید؛ مانند نگاشت سطوح تفکر OpenClaw به یک پرچم effort بومی. هوک، ctx.executionMode را دریافت می‌کند؛ برای افزودن پرچم‌های جداسازی بومی بک‌اند به فراخوانی‌های موقتی /btw، از "side-question" استفاده کنید. اگر این پرچم‌ها ابزارهای بومی را برای یک CLI که در غیر این صورت همیشه فعال است به‌طور قابل‌اعتماد غیرفعال می‌کنند، sideQuestionToolMode: "disabled" را نیز اعلان کنید.
• برای محیط اجرای تحت مالکیت بک‌اند یا پل‌های موقت احراز هویت/پیکربندی، از prepareExecution استفاده کنید. ctx.contextTokenBudget آن، محدودیت مؤثر توکنِ انتخاب‌شده برای اجرا است؛ بنابراین بک‌اندهای دارای Compaction بومی می‌توانند آستانه خود را بدون شاخه‌های هسته مختص ارائه‌دهنده هم‌تراز کنند. همچنین هنگامی که آماده‌سازی بک‌اند باید تنظیمات همراه MCP را گسترش دهد، ctx.env آماده‌شده توسط هسته را دریافت می‌کند.
• بک‌اندهایی که می‌توانند همه ابزارهای بومی را برای یک اجرای مشخص غیرفعال کنند، می‌توانند nativeToolMode: "selectable" را اعلان کنند. فراخوانی‌های محدودشده یک فهرست دقیق ctx.toolAvailability.native به‌همراه نام‌های متعارف ctx.toolAvailability.openClaw ارسال می‌کنند. toolAvailabilityEnforcement: "execution-args" را اعلان و قرارداد را در argv نهاییِ تازه/ازسرگرفته‌شده اعمال کنید، یا "prepare-execution" را اعلان کنید، آن را در سیاست آماده‌شده اعمال کنید و toolAvailabilityEnforced: true را برگردانید. OpenClaw ابزارهای بومی را برای سقف‌های زمان اجرا مانند toolsAllow مربوط به Cron غیرفعال می‌کند و هنگامی که مسیر اعمال اعلان‌شده ناقص باشد، با حالت بسته شکست می‌خورد.

برای راهنمای نگارش سرتاسری، به Pluginهای بک‌اند CLI مراجعه کنید.

جایگاه‌های انحصاری

آداپتورهای منسوخ‌شده تعبیه حافظه

• registerMemoryCapability، API انحصاری Plugin حافظه است.
• registerMemoryCapability همچنین ممکن است publicArtifacts.listArtifacts(...) را برای خروجی‌های مدیریت‌شده توسط میزبان ارائه کند. Pluginهای همراه که آن مصنوعات اعلان‌شده را فهرست می‌کنند، تا زمانی که یک API عمومی و متمرکز برای مصرف‌کننده وجود داشته باشد، همچنان از listActiveMemoryPublicArtifacts(...) نمای حفظ‌شده openclaw/plugin-sdk/memory-host-core استفاده می‌کنند؛ آن‌ها نباید به چیدمان خصوصی Plugin دیگری دسترسی پیدا کنند.
• MemoryFlushPlan.model می‌تواند نوبت تخلیه را به یک ارجاع دقیق provider/model، مانند ollama/qwen3:8b، سنجاق کند، بدون اینکه زنجیره fallback فعال را به ارث ببرد.
• registerMemoryEmbeddingProvider منسوخ شده است. ارائه‌دهندگان جدید تعبیه باید از api.registerEmbeddingProvider(...) و contracts.embeddingProviders استفاده کنند.
• ارائه‌دهندگان موجودِ مختص حافظه در طول بازه مهاجرت به کار خود ادامه می‌دهند، اما بازرسی Plugin این مورد را برای Pluginهای غیرهمراه به‌عنوان بدهی سازگاری گزارش می‌کند.

رویدادها و چرخه حیات

برای نمونه‌ها، نام‌های رایج هوک و معناشناسی محافظ، به هوک‌های Plugin مراجعه کنید.

معناشناسی تصمیم هوک

before_install یک هوک چرخه حیات زمان اجرای Plugin است، نه سطح سیاست نصب اپراتور. هنگامی که تصمیم مجازسازی/مسدودسازی باید مسیرهای نصب یا به‌روزرسانی مبتنی بر CLI و Gateway را پوشش دهد، از security.installPolicy استفاده کنید.

• before_tool_call: برگرداندن { block: true } نهایی است. به‌محض اینکه هر handler آن را تنظیم کند، handlerهای با اولویت پایین‌تر نادیده گرفته می‌شوند.
• before_tool_call: برگرداندن { block: false } به‌معنای نبود تصمیم تلقی می‌شود (همانند حذف block)، نه به‌عنوان override.
• before_install: برگرداندن { block: true } نهایی است. به‌محض اینکه هر handler آن را تنظیم کند، handlerهای با اولویت پایین‌تر نادیده گرفته می‌شوند.
• before_install: برگرداندن { block: false } به‌معنای نبود تصمیم تلقی می‌شود (همانند حذف block)، نه به‌عنوان override.
• reply_dispatch: برگرداندن { handled: true, ... } نهایی است. به‌محض اینکه هر handler ارسال را بر عهده بگیرد، handlerهای با اولویت پایین‌تر و مسیر پیش‌فرض ارسال مدل نادیده گرفته می‌شوند.
• message_sending: برگرداندن { cancel: true } نهایی است. به‌محض اینکه هر handler آن را تنظیم کند، handlerهای با اولویت پایین‌تر نادیده گرفته می‌شوند.
• message_sending: برگرداندن { cancel: false } به‌معنای نبود تصمیم تلقی می‌شود (همانند حذف cancel)، نه به‌عنوان override.
• message_received: هنگامی که به مسیریابی ورودی رشته/موضوع نیاز دارید، از فیلد نوع‌دار threadId استفاده کنید. metadata را برای موارد اضافی مختص کانال نگه دارید.
• message_sending: پیش از fallback به metadata مختص کانال، از فیلدهای مسیریابی نوع‌دار replyToId / threadId استفاده کنید.
• gateway_start: برای وضعیت راه‌اندازی تحت مالکیت Gateway، به‌جای تکیه بر هوک‌های داخلی gateway:startup، از ctx.config، ctx.workspaceDir و ctx.getCron?.() استفاده کنید. ممکن است Cron در این نقطه هنوز در حال بارگذاری باشد.
• cron_reconciled: پس از راه‌اندازی یا بارگذاری مجدد زمان‌بند، یک تصویر کامل خارجی از Cron را بازسازی کنید. این تصویر شامل reason و وضعیت مؤثر enabled، از جمله enabled: false است، درحالی‌که ctx.getCron?.() زمان‌بند دقیقِ تطبیق‌یافته را برمی‌گرداند. ctx.abortSignal را به کار ماندگار تصویرسازی ارسال کنید؛ هنگامی که snapshot آن زمان‌بند جایگزین شود یا Gateway بسته شود، عملیات را لغو می‌کند.
• cron_changed: تغییرات چرخه حیات Cron تحت مالکیت Gateway را مشاهده کنید. رویدادهای scheduled و removed راهنمای تطبیق پس از commit هستند، نه یک گزارش مرتب‌شده تغییرات. event.nextRunAtMs یک رویداد زمان‌بندی‌شده هنگامی وجود ندارد که کار بیدارباش بعدی نداشته باشد؛ یک رویداد حذف‌شده همچنان snapshot کار حذف‌شده را حمل می‌کند.

زمان‌بندهای خارجی بیدارباش باید رویدادهای cron_changed را debounce یا ادغام کنند، سپس نمای کامل و ماندگار را از زمان‌بندی که آخرین بار توسط cron_reconciled ثبت شده است، دوباره بخوانند. زمان‌بند را از زمینه cron_changed نپذیرید: یک راهنمای جداشده از زمان‌بندی قدیمی‌تر می‌تواند با بارگذاری مجدد بعدی هم‌پوشانی داشته باشد.

از cron_reconciled به‌عنوان محرک snapshot کامل برای وضعیت ماندگاری استفاده کنید که هنگام راه‌اندازی Gateway یا جایگزینی زمان‌بند بارگذاری شده است. این مورد برای بارگذاری مجدد داغِ صرفاً Plugin بازپخش نمی‌شود. handlerهای مشاهده به‌طور موازی اجرا می‌شوند و ارسال‌های fire-and-forget می‌توانند هم‌پوشانی داشته باشند؛ بنابراین مصرف‌کنندگان نباید به ترتیب تکمیل رویداد وابسته باشند. OpenClaw را منبع حقیقت برای بررسی موعدها و اجرا نگه دارید.

برای یک آداپتور تک‌اجرایی با جایگزینی ماندگار، تلاش مجدد/backoff و خاموش‌شدن پاک، به تصویرسازی امن خارجی Cron مراجعه کنید.

فیلدهای شیء API

قرارداد ماژول داخلی

درون Plugin خود، برای importهای داخلی از فایل‌های barrel محلی استفاده کنید:

my-plugin/  api.ts            # خروجی‌های عمومی برای مصرف‌کنندگان خارجی  runtime-api.ts    # خروجی‌های زمان اجرا فقط برای استفاده داخلی  index.ts          # نقطه ورود Plugin  setup-entry.ts    # ورودی سبک فقط برای راه‌اندازی (اختیاری)

سطوح عمومی Pluginهای همراه که با facade بارگذاری می‌شوند (api.ts، runtime-api.ts، index.ts، setup-entry.ts و فایل‌های ورودی عمومی مشابه)، هنگامی که OpenClaw از قبل در حال اجراست، snapshot فعال پیکربندی runtime را ترجیح می‌دهند. اگر هنوز snapshotی از runtime وجود نداشته باشد، به فایل پیکربندی resolveشده روی دیسک بازمی‌گردند. facadeهای Pluginهای همراه بسته‌بندی‌شده باید از طریق بارگذارهای facade مربوط به Plugin در OpenClaw بارگذاری شوند؛ import مستقیم از dist/extensions/... بررسی‌های manifest و sidecar مربوط به runtime را که نصب‌های بسته‌بندی‌شده برای کد تحت مالکیت Plugin استفاده می‌کنند، دور می‌زند.

Pluginهای ارائه‌دهنده می‌توانند یک barrel قرارداد محدود و محلی برای Plugin ارائه کنند، مشروط بر اینکه helper عمداً مختص ارائه‌دهنده باشد و هنوز به یک زیرمسیر عمومی SDK تعلق نداشته باشد. نمونه‌های همراه:

• Anthropic: مرز عمومی api.ts / contract-api.ts برای helperهای beta-header مربوط به Claude و جریان service_tier.
• @openclaw/openai-provider: api.ts سازنده‌های ارائه‌دهنده، helperهای مدل پیش‌فرض و سازنده‌های ارائه‌دهنده بلادرنگ را export می‌کند.
• @openclaw/openrouter-provider: api.ts سازنده ارائه‌دهنده را همراه با helperهای راه‌اندازی اولیه/پیکربندی export می‌کند.

مرتبط