موتور زمینه

یک موتور زمینه کنترل می‌کند که OpenClaw چگونه زمینهٔ مدل را برای هر اجرا می‌سازد: کدام پیام‌ها گنجانده شوند، تاریخچهٔ قدیمی‌تر چگونه خلاصه شود و زمینه در مرزهای زیرعامل چگونه مدیریت شود.

OpenClaw با یک موتور داخلی legacy عرضه می‌شود و به‌طور پیش‌فرض از آن استفاده می‌کند. تنها زمانی یک موتور Plugin را نصب و انتخاب کنید که به رفتار متفاوتی برای گردآوری، Compaction یا یادآوری میان‌نشستی نیاز دارید.

شروع سریع

openclaw doctor# یا پیکربندی را مستقیماً بررسی کنید:cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'

openclaw plugins install @martian-engineering/lossless-claw

openclaw plugins install -l ./my-context-engine

// openclaw.json{  plugins: {    slots: {      contextEngine: "lossless-claw", // باید با شناسهٔ موتور ثبت‌شدهٔ Plugin مطابقت داشته باشد    },    entries: {      "lossless-claw": {        enabled: true,        // پیکربندی مختص Plugin در اینجا قرار می‌گیرد (به مستندات Plugin مراجعه کنید)      },    },  },}

نحوهٔ کار

هر بار که OpenClaw یک پرامپت مدل را اجرا می‌کند، موتور زمینه در چهار نقطه از چرخهٔ عمر مشارکت دارد:

موتورها همچنین می‌توانند یک متد اختیاری maintain() برای نگه‌داری رونوشت (بازنویسی‌های ایمن از طریق runtimeContext.rewriteTranscriptEntries()) پس از راه‌اندازی اولیه، یک نوبت موفق یا Compaction پیاده‌سازی کنند. برای اجرای آن به‌عنوان کار معوق به‌جای مسدودکردن پاسخ، info.turnMaintenanceMode: "background" را تنظیم کنید.

برای مهار Codex غیر ACP همراه، OpenClaw همین چرخهٔ عمر را با نگاشت زمینهٔ گردآوری‌شده به دستورالعمل‌های توسعه‌دهندهٔ Codex و پرامپت نوبت جاری اعمال می‌کند. Codex همچنان مالک تاریخچهٔ بومی رشته و فشرده‌ساز بومی خود است.

چرخهٔ عمر زیرعامل (اختیاری)

OpenClaw دو هوک اختیاری چرخهٔ عمر زیرعامل را فراخوانی می‌کند:

افزودهٔ پرامپت سیستم

متد assemble می‌تواند یک رشتهٔ systemPromptAddition برگرداند. OpenClaw آن را به ابتدای پرامپت سیستم اجرا اضافه می‌کند. این قابلیت به موتورها امکان می‌دهد بدون نیاز به فایل‌های ایستای فضای کاری، راهنمای یادآوری پویا، دستورالعمل‌های بازیابی یا نکته‌های آگاه از زمینه را تزریق کنند.

موتور قدیمی

موتور داخلی legacy رفتار اصلی OpenClaw را حفظ می‌کند:

• دریافت: بدون عملیات (مدیر نشست ماندگاری پیام را مستقیماً مدیریت می‌کند).
• گردآوری: عبور مستقیم (پایپ‌لاین موجود پاک‌سازی ← اعتبارسنجی ← محدودسازی در زمان اجرا، گردآوری زمینه را مدیریت می‌کند).
• فشرده‌سازی: به Compaction خلاصه‌سازی داخلی واگذار می‌شود که یک خلاصهٔ واحد از پیام‌های قدیمی‌تر ایجاد می‌کند و پیام‌های اخیر را دست‌نخورده نگه می‌دارد.
• پس از نوبت: بدون عملیات.

موتور قدیمی ابزارها را ثبت نمی‌کند و systemPromptAddition ارائه نمی‌دهد.

هنگامی که هیچ plugins.slots.contextEngine تنظیم نشده باشد (یا روی "legacy" تنظیم شده باشد)، این موتور به‌طور خودکار استفاده می‌شود.

موتورهای Plugin

یک Plugin می‌تواند با استفاده از API افزونه، یک موتور زمینه ثبت کند:

 export default function register(api) {  api.registerContextEngine("my-engine", (ctx) => ({    info: {      id: "my-engine",      name: "My Context Engine",      ownsCompaction: true,    },     async ingest({ sessionId, message, isHeartbeat }) {      // پیام را در مخزن دادهٔ خود ذخیره کنید      return { ingested: true };    },     async assemble({      sessionId,      sessionKey,      messages,      tokenBudget,      availableTools,      citationsMode,    }) {      // پیام‌هایی را برگردانید که در بودجه جا می‌گیرند      return {        messages: buildContext(messages, tokenBudget),        estimatedTokens: countTokens(messages),        systemPromptAddition: buildMemorySystemPromptAddition({          availableTools: availableTools ?? new Set(),          citationsMode,          agentSessionKey: sessionKey,        }),      };    },     async compact({ sessionId, force }) {      // زمینهٔ قدیمی‌تر را خلاصه کنید      return { ok: true, compacted: true };    },  }));}

کارخانهٔ ctx شامل مقادیر اختیاری config، agentDir و workspaceDir است تا Pluginها بتوانند پیش از نخستین فراخوانی چرخهٔ عمر، وضعیت مختص عامل یا فضای کاری را مقداردهی اولیه کنند. پیش از یک فراخوانی غیرقدیمی assemble()، میزبان آماده‌سازی ثبت‌شدهٔ ناهمگام پرامپت حافظه را تکمیل می‌کند. تابع کمکی همگام buildMemorySystemPromptAddition(...) آن تصویر لحظه‌ای تغییرناپذیر اجرا را می‌خواند؛ زمینهٔ ابزار، استناد، عامل و نشست ارائه‌شده را بدون تغییر عبور دهید.

سپس آن را در پیکربندی فعال کنید:

{  plugins: {    slots: {      contextEngine: "my-engine",    },    entries: {      "my-engine": {        enabled: true,      },    },  },}

رابط ContextEngine

اعضای الزامی:

assemble یک AssembleResult با موارد زیر برمی‌گرداند:

compact یک CompactResult برمی‌گرداند. هنگامی که Compaction هویت نشست فعال را تغییر می‌دهد، result.sessionTarget (یک ContextEngineSessionTarget نوع‌دار که هویت نشست و دامنهٔ مخزن را حمل می‌کند) نشست جانشینی را مشخص می‌کند که تلاش مجدد یا نوبت بعدی باید از آن استفاده کند؛ result.sessionId شناسهٔ جانشین را بازتاب می‌دهد.

اعضای اختیاری:

تنظیمات زمان اجرا

هوک‌های چرخهٔ عمر که درون OpenClaw اجرا می‌شوند، یک شیء اختیاری runtimeSettings دریافت می‌کنند. این یک سطح API داخلی نسخه‌بندی‌شده و فقط‌خواندنی برای تولیدکننده/مصرف‌کننده است: OpenClaw آن را برای موتور زمینهٔ انتخاب‌شده تولید می‌کند و موتور زمینه آن را درون هوک‌های چرخهٔ عمر مصرف می‌کند. این شیء مستقیماً به کاربران نمایش داده نمی‌شود و سطح گزارش‌دهی اختصاصی ایجاد نمی‌کند.

• schemaVersion: در حال حاضر 1
• runtime: میزبان OpenClaw، حالت زمان اجرا (normal، fallback، یا degraded) و شناسه‌های اختیاری چارچوب آزمون/زمان اجرا
• contextEngineSelection: شناسه موتور زمینه انتخاب‌شده و منبع انتخاب
• executionHost: شناسه و برچسب میزبان برای سطحی که هوک را فراخوانی می‌کند
• model: مدل درخواست‌شده، مدل نهایی، ارائه‌دهنده و خانواده اختیاری مدل
• limits: بودجه توکن پرامپت و حداکثر توکن‌های خروجی، در صورت مشخص‌بودن
• diagnostics: کدهای دلیلِ بازگشت جایگزین بسته و تنزل عملکرد، در صورت مشخص‌بودن

فیلدهایی که ممکن است نامشخص باشند به‌صورت null نمایش داده می‌شوند؛ فیلدهای تمایزدهنده‌ای مانند حالت زمان اجرا و منبع انتخاب همچنان غیرقابل‌تهی باقی می‌مانند. موتورهای قدیمی‌تر همچنان سازگارند: اگر یک موتور قدیمی سخت‌گیر runtimeSettings را به‌عنوان یک ویژگی ناشناخته رد کند، OpenClaw به‌جای قرنطینه‌کردن موتور، فراخوانی چرخه حیات را بدون آن دوباره امتحان می‌کند.

الزامات میزبان

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

برای اجرای عامل، وقتی موتور باید پرامپت واقعی مدل را از طریق assemble() کنترل کند، assemble-before-prompt را اعلام کنید:

info: {  id: "my-context-engine",  name: "My Context Engine",  hostRequirements: {    "agent-run": {      requiredCapabilities: ["assemble-before-prompt"],      unsupportedMessage:        "از زمان اجرای بومی Codex یا زمان اجرای تعبیه‌شده OpenClaw استفاده کنید، یا موتور زمینه قدیمی را انتخاب کنید.",    },  },}

اجرای عامل در Codex بومی و OpenClaw تعبیه‌شده، assemble-before-prompt را برآورده می‌کند. بک‌اندهای عمومی CLI چنین قابلیتی ندارند؛ بنابراین موتورهایی که به آن نیاز دارند، پیش از آغاز فرایند CLI رد می‌شوند.

جداسازی خرابی

OpenClaw موتور Plugin انتخاب‌شده را از مسیر اصلی پاسخ جدا می‌کند. اگر یک موتور غیرقدیمی وجود نداشته باشد، در اعتبارسنجی قرارداد ناموفق شود، هنگام ایجاد کارخانه استثنا پرتاب کند، یا از یک متد چرخه حیات استثنا پرتاب کند، OpenClaw آن موتور را برای فرایند فعلی Gateway قرنطینه می‌کند و کارهای موتور زمینه را به موتور داخلی legacy تنزل می‌دهد. خطا همراه با عملیات ناموفق ثبت می‌شود تا اپراتور بتواند بدون ساکت‌شدن عامل، Plugin را تعمیر، به‌روزرسانی یا غیرفعال کند.

خرابی الزامات میزبان متفاوت است: وقتی موتوری اعلام کند که یک زمان اجرا قابلیت لازم را ندارد، OpenClaw پیش از آغاز اجرا به‌شکل بسته متوقف می‌شود. این کار از موتورهایی محافظت می‌کند که اجرای آن‌ها در میزبانی پشتیبانی‌نشده موجب خرابی وضعیت می‌شود.

ownsCompaction

ownsCompaction تعیین می‌کند که آیا فشرده‌سازی خودکار داخلیِ حین تلاش در زمان اجرای OpenClaw برای آن اجرا فعال بماند:

یعنی دو الگوی معتبر برای Plugin وجود دارد:

یک compact() بدون عملیات برای یک موتور فعالِ غیرمالک ناامن است، زیرا مسیر عادی فشرده‌سازی /compact و بازیابی سرریز را برای جایگاه آن موتور غیرفعال می‌کند.

مرجع پیکربندی

{  plugins: {    slots: {      // موتور زمینه فعال را انتخاب کنید. پیش‌فرض: "legacy".      // برای استفاده از موتور Plugin، آن را روی شناسه Plugin تنظیم کنید.      contextEngine: "legacy",    },  },}

ارتباط با فشرده‌سازی و حافظه

نکته‌ها

• برای اطمینان از بارگذاری صحیح موتور خود، از openclaw doctor استفاده کنید.
• هنگام تعویض موتور، نشست‌های موجود با تاریخچه فعلی خود ادامه می‌یابند. موتور جدید اجرای دفعات بعدی را بر عهده می‌گیرد.
• خطاهای موتور ثبت می‌شوند و موتور Plugin انتخاب‌شده برای فرایند فعلی Gateway قرنطینه می‌شود. OpenClaw برای نوبت‌های کاربر به legacy بازمی‌گردد تا پاسخ‌ها بتوانند ادامه یابند، اما همچنان باید Plugin خراب را تعمیر، به‌روزرسانی، غیرفعال یا حذف نصب کنید.
• برای توسعه، از openclaw plugins install -l ./my-engine استفاده کنید تا بدون کپی‌کردن، یک پوشه Plugin محلی را پیوند دهید.

مرتبط

• Compaction - خلاصه‌سازی گفت‌وگوهای طولانی
• زمینه - نحوه ساخت زمینه برای نوبت‌های عامل
• معماری Plugin - ثبت Pluginهای موتور زمینه
• مانیفست Plugin - فیلدهای مانیفست Plugin
• Pluginها - نمای کلی Pluginها