موتور زمینه

یک موتور زمینه کنترل می‌کند که 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 در runtime مونتاژ زمینه را مدیریت می‌کند).
• 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 };
    },
  }));
}

factory با نام 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 نشست جانشینی را مشخص می‌کنند که تلاش مجدد یا نوبت بعدی باید از آن استفاده کند.

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

# ownsCompaction

ownsCompaction کنترل می‌کند که آیا Compaction خودکار درون‌تلاش داخلی Pi برای اجرا فعال بماند یا نه:

یعنی دو الگوی معتبر برای 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 استفاده کنید تا تأیید کنید موتور شما درست بارگذاری می‌شود.
• اگر موتور را تغییر دهید، نشست‌های موجود با تاریخچه فعلی خود ادامه می‌دهند. موتور جدید برای اجراهای آینده کنترل را در دست می‌گیرد.
• خطاهای موتور ثبت می‌شوند و در عیب‌یابی نمایش داده می‌شوند. اگر یک موتور Plugin در ثبت شدن شکست بخورد یا شناسه موتور انتخاب‌شده قابل حل نباشد، OpenClaw به‌صورت خودکار به حالت قبلی برنمی‌گردد؛ اجراها تا زمانی که Plugin را اصلاح کنید یا plugins.slots.contextEngine را به "legacy" برگردانید شکست می‌خورند.
• برای توسعه، از openclaw plugins install -l ./my-engine استفاده کنید تا یک پوشه Plugin محلی را بدون کپی کردن پیوند دهید.

# مرتبط

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