موتور زمینه

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

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

شروع سریع

openclaw doctor# or inspect config directly: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", // must match the plugin's registered engine id    },    entries: {      "lossless-claw": {        enabled: true,        // Plugin-specific config goes here (see the plugin's docs)      },    },  },}

نحوهٔ کارکرد

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

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

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

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

افزودن اعلان سیستم

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

موتور legacy

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

• دریافت: بدون عملیات (مدیر نشست پایداری پیام را مستقیماً مدیریت می‌کند).
• مونتاژ: عبور مستقیم (خط لولهٔ موجود sanitize → validate → limit در زمان اجرا مونتاژ زمینه را مدیریت می‌کند).
• Compact: به Compaction خلاصه‌سازی داخلی واگذار می‌کند، که یک خلاصهٔ واحد از پیام‌های قدیمی‌تر می‌سازد و پیام‌های اخیر را دست‌نخورده نگه می‌دارد.
• پس از نوبت: بدون عملیات.

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

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

موتورهای Plugin

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

 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 }) {      // Store the message in your data store      return { ingested: true };    },     async assemble({ sessionId, messages, tokenBudget, availableTools, citationsMode }) {      // Return messages that fit the budget      return {        messages: buildContext(messages, tokenBudget),        estimatedTokens: countTokens(messages),        systemPromptAddition: buildMemorySystemPromptAddition({          availableTools: availableTools ?? new Set(),          citationsMode,        }),      };    },     async compact({ sessionId, force }) {      // Summarize older context      return { ok: true, compacted: true };    },  }));}

کارخانهٔ ctx شامل مقادیر اختیاری config، agentDir، و workspaceDir است تا Pluginها بتوانند پیش از اجرای نخستین هوک چرخهٔ عمر، وضعیت هر عامل یا هر فضای کاری را مقداردهی اولیه کنند.

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

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

رابط ContextEngine

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

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

compact یک CompactResult برمی‌گرداند. وقتی Compaction رونوشت فعال را می‌چرخاند، result.sessionId و result.sessionFile نشست جانشین را شناسایی می‌کنند که تلاش دوباره یا نوبت بعدی باید از آن استفاده کند.

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

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

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

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

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

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

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

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

info: {  id: "my-context-engine",  name: "My Context Engine",  hostRequirements: {    "agent-run": {      requiredCapabilities: ["assemble-before-prompt"],      unsupportedMessage:        "Use the native Codex or OpenClaw embedded runtime, or select the legacy context engine.",    },  },}

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

جداسازی شکست

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

خطاهای مربوط به الزامات میزبان متفاوت‌اند: وقتی یک موتور اعلام می‌کند که یک runtime فاقد قابلیت لازم است، OpenClaw پیش از شروع اجرا به‌صورت fail-closed متوقف می‌شود. این از موتورهایی محافظت می‌کند که اگر در میزبان پشتیبانی‌نشده اجرا شوند، وضعیت را خراب می‌کنند.

ownsCompaction

ownsCompaction کنترل می‌کند که آیا auto-compaction داخلی runtime OpenClaw درون attempt برای اجرا فعال بماند یا نه:

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

یک compact() بدون عملیات برای یک موتور فعال غیرمالک ناامن است، چون مسیر عادی Compaction مربوط به /compact و بازیابی سرریز را برای آن slot موتور غیرفعال می‌کند.

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

{  plugins: {    slots: {      // Select the active context engine. Default: "legacy".      // Set to a plugin id to use a plugin engine.      contextEngine: "legacy",    },  },}

رابطه با Compaction و حافظه

نکته‌ها

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

مرتبط

• Compaction - خلاصه‌سازی گفتگوهای طولانی
• Context - context چگونه برای turnهای agent ساخته می‌شود
• معماری Plugin - ثبت Pluginهای موتور context
• manifest Plugin - فیلدهای manifest مربوط به Plugin
• Pluginها - نمای کلی Plugin