الانتقال إلى المحتوى الرئيسي
يتحكم محرك السياق في كيفية بناء OpenClaw لسياق النموذج لكل تشغيل: أي الرسائل يجب تضمينها، وكيفية تلخيص السجل الأقدم، وكيفية إدارة السياق عبر حدود الوكلاء الفرعيين. يأتي OpenClaw مع محرك legacy مدمج ويستخدمه افتراضيًا - لا يحتاج معظم المستخدمين إلى تغيير ذلك. ثبّت محرك Plugin وحدده فقط عندما تريد سلوكًا مختلفًا للتجميع أو Compaction أو الاستدعاء عبر الجلسات.

البدء السريع

1

Check which engine is active

openclaw doctor
# or inspect config directly:
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'
2

Install a plugin engine

تُثبّت Plugins محرك السياق مثل أي OpenClaw Plugin آخر.
openclaw plugins install @martian-engineering/lossless-claw
3

Enable and select the 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)
      },
    },
  },
}
أعد تشغيل Gateway بعد التثبيت والتهيئة.
4

Switch back to legacy (optional)

اضبط contextEngine على "legacy" (أو أزل المفتاح بالكامل - "legacy" هو الافتراضي).

كيف يعمل

في كل مرة يشغّل فيها OpenClaw مطالبة نموذج، يشارك محرك السياق في أربع نقاط من دورة الحياة:
يُستدعى عند إضافة رسالة جديدة إلى الجلسة. يمكن للمحرك تخزين الرسالة أو فهرستها في مخزن البيانات الخاص به.
يُستدعى قبل كل تشغيل للنموذج. يعيد المحرك مجموعة مرتبة من الرسائل (وsystemPromptAddition اختياريًا) تلائم ميزانية الرموز.
يُستدعى عندما تمتلئ نافذة السياق، أو عندما يشغّل المستخدم /compact. يلخص المحرك السجل الأقدم لتحرير مساحة.
يُستدعى بعد اكتمال التشغيل. يمكن للمحرك حفظ الحالة، أو تشغيل Compaction في الخلفية، أو تحديث الفهارس.
بالنسبة إلى حزمة Codex غير ACP المضمّنة، يطبق OpenClaw دورة الحياة نفسها عبر إسقاط السياق المجمّع في تعليمات مطوّر Codex ومطالبة الدور الحالي. يظل Codex مالكًا لسجل المحادثة الأصلي وCompactor الأصلي الخاص به.

دورة حياة الوكيل الفرعي (اختياري)

يستدعي OpenClaw خطافي دورة حياة اختياريين للوكلاء الفرعيين:
prepareSubagentSpawn
method
حضّر حالة السياق المشتركة قبل بدء تشغيل فرعي. يتلقى الخطاف مفاتيح جلسة الأصل/الفرع، وcontextMode (isolated أو fork)، ومعرّفات/ملفات النص المتاحة، وTTL اختياريًا. إذا أعاد مقبض تراجع، يستدعيه OpenClaw عندما يفشل الإنشاء بعد نجاح التحضير. تتخطى عمليات إنشاء الوكيل الفرعي الأصلية التي تطلب lightContext وتُحل إلى contextMode="isolated" هذا الخطاف عمدًا لكي يبدأ الفرع من سياق تمهيد خفيف الوزن بدون حالة ما قبل الإنشاء المُدارة بواسطة محرك السياق.
onSubagentEnded
method
نظّف الموارد عند اكتمال جلسة وكيل فرعي أو كنسها.

إضافة مطالبة النظام

يمكن لطريقة assemble أن تعيد سلسلة systemPromptAddition. يضيف OpenClaw هذه السلسلة في بداية مطالبة النظام للتشغيل. يتيح ذلك للمحركات حقن إرشادات استدعاء ديناميكية، أو تعليمات استرجاع، أو تلميحات واعية بالسياق دون الحاجة إلى ملفات مساحة عمل ثابتة.

المحرك legacy

يحافظ المحرك legacy المدمج على السلوك الأصلي لـ OpenClaw:
  • الإدخال: بلا إجراء (يتولى مدير الجلسة حفظ الرسائل مباشرة).
  • التجميع: تمرير مباشر (يتولى خط sanitize → validate → limit الحالي في وقت التشغيل تجميع السياق).
  • Compaction: يفوض إلى Compaction التلخيص المدمج، الذي ينشئ ملخصًا واحدًا للرسائل الأقدم ويحافظ على الرسائل الحديثة كما هي.
  • بعد الدور: بلا إجراء.
لا يسجل المحرك legacy أدوات ولا يوفر systemPromptAddition. عندما لا يتم تعيين plugins.slots.contextEngine (أو يكون معينًا إلى "legacy")، يُستخدم هذا المحرك تلقائيًا.

محركات Plugin

يمكن لـ Plugin تسجيل محرك سياق باستخدام واجهة Plugin API:
import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

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 الاختيارية حتى تتمكن Plugins من تهيئة حالة لكل وكيل أو لكل مساحة عمل قبل تشغيل أول خطاف في دورة الحياة. ثم فعّله في الإعدادات:
{
  plugins: {
    slots: {
      contextEngine: "my-engine",
    },
    entries: {
      "my-engine": {
        enabled: true,
      },
    },
  },
}

واجهة ContextEngine

الأعضاء المطلوبة:
العضوالنوعالغرض
infoخاصيةمعرّف المحرك واسمه وإصداره وما إذا كان يملك Compaction
ingest(params)طريقةتخزين رسالة واحدة
assemble(params)طريقةبناء السياق لتشغيل نموذج (يعيد AssembleResult)
compact(params)طريقةتلخيص/تقليل السياق
تعيد assemble قيمة AssembleResult مع:
messages
Message[]
مطلوب
الرسائل المرتبة لإرسالها إلى النموذج.
estimatedTokens
number
مطلوب
تقدير المحرك لإجمالي الرموز في السياق المجمّع. يستخدم OpenClaw ذلك لقرارات عتبة Compaction وإعداد التقارير التشخيصية.
systemPromptAddition
string
تُضاف في بداية مطالبة النظام.
promptAuthority
"assembled" | "preassembly_may_overflow"
يتحكم في تقدير الرموز الذي يستخدمه المشغّل لفحوصات فيضان السياق الاستباقية. الإعداد الافتراضي هو "assembled"، ما يعني أن تقدير المطالبة المجمّعة فقط يُفحص للمحركات التي لا تملك Compaction. تدير المحركات التي تضبط ownsCompaction: true إدخال المطالبة الخاص بها، لذلك يتخطى OpenClaw فحص ما قبل المطالبة العام افتراضيًا. اضبط "preassembly_may_overflow" فقط عندما يمكن أن يخفي العرض المجمّع لديك خطر الفيضان في النص الأساسي؛ عندها يبقي المشغّل الفحص العام نشطًا ويأخذ الحد الأقصى بين التقدير المجمّع وتقدير سجل الجلسة قبل التجميع (غير المحدد بنافذة) عند اتخاذ قرار بتنفيذ Compaction استباقيًا. في كلتا الحالتين، تظل الرسائل التي تعيدها هي ما يراه النموذج - لا يؤثر promptAuthority إلا في الفحص المسبق.
تعيد compact قيمة CompactResult. عندما تدوّر Compaction النص النشط، يحدد result.sessionId وresult.sessionFile الجلسة اللاحقة التي يجب أن تستخدمها إعادة المحاولة أو الدور التالي. الأعضاء الاختيارية:
العضوالنوعالغرض
bootstrap(params)طريقةتهيئة حالة المحرك لجلسة. تُستدعى مرة واحدة عندما يرى المحرك جلسة لأول مرة (مثلًا، استيراد السجل).
ingestBatch(params)طريقةإدخال دور مكتمل كدفعة. تُستدعى بعد اكتمال تشغيل، مع جميع الرسائل من ذلك الدور دفعة واحدة.
afterTurn(params)طريقةعمل دورة حياة ما بعد التشغيل (حفظ الحالة، تشغيل Compaction في الخلفية).
prepareSubagentSpawn(params)طريقةإعداد حالة مشتركة لجلسة فرعية قبل أن تبدأ.
onSubagentEnded(params)طريقةالتنظيف بعد انتهاء وكيل فرعي.
dispose()طريقةتحرير الموارد. تُستدعى أثناء إيقاف Gateway أو إعادة تحميل Plugin - وليس لكل جلسة.

إعدادات وقت التشغيل

تتلقى خطافات دورة الحياة التي تعمل داخل 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 هذه المتطلبات قبل بدء العملية ويفشل مغلقًا مع خطأ وصفي عندما لا يستطيع وقت التشغيل المحدد تلبيتها. لتشغيلات الوكيل، أعلن assemble-before-prompt عندما يجب أن يتحكم المحرك في مطالبة النموذج الفعلية عبر assemble():
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 المحدد عن مسار الرد الأساسي. إذا كان محرك غير قديم مفقودًا، أو فشل في التحقق من العقد، أو رمى خطأ أثناء إنشاء المصنع، أو رمى خطأ من طريقة دورة حياة، يعزل OpenClaw ذلك المحرك لعملية Gateway الحالية ويخفض عمل محرك السياق إلى المحرك المدمج legacy. يُسجَّل الخطأ مع العملية الفاشلة حتى يتمكن المشغّل من إصلاح Plugin أو تحديثه أو تعطيله من دون أن يتوقف الوكيل عن الرد. تختلف حالات فشل متطلبات المضيف: عندما يعلن محرك أن بيئة تشغيل تفتقر إلى قدرة مطلوبة، يفشل OpenClaw بإغلاق آمن قبل بدء التشغيل. وهذا يحمي المحركات التي قد تفسد الحالة إذا عملت في مضيف غير مدعوم.

ownsCompaction

يتحكم ownsCompaction فيما إذا كان الضغط التلقائي المدمج داخل المحاولة في وقت تشغيل OpenClaw يبقى مفعّلًا للتشغيل:
يمتلك المحرك سلوك الضغط. يعطّل OpenClaw الضغط التلقائي المدمج في وقت تشغيل OpenClaw وفحص ما قبل تجاوز سعة الموجّه العام لذلك التشغيل، ويكون تنفيذ compact() الخاص بالمحرك مسؤولًا عن /compact، وضغط الاسترداد من تجاوز سعة المزوّد، وأي ضغط استباقي يريد تنفيذه في afterTurn(). يظل OpenClaw يشغّل حماية تجاوز سعة ما قبل الموجّه عندما يعيد المحرك promptAuthority: "preassembly_may_overflow" من assemble().
قد يظل الضغط التلقائي المدمج في وقت تشغيل OpenClaw يعمل أثناء تنفيذ الموجّه، لكن طريقة compact() الخاصة بالمحرك النشط تظل تُستدعى من أجل /compact واسترداد تجاوز السعة.
لا يعني ownsCompaction: false أن OpenClaw يعود تلقائيًا إلى مسار الضغط الخاص بالمحرك القديم.
هذا يعني أن هناك نمطين صالحين للـ Plugin:
نفّذ خوارزمية الضغط الخاصة بك واضبط ownsCompaction: true.
يُعد تنفيذ compact() الذي لا يفعل شيئًا غير آمن لمحرك نشط لا يمتلك الضغط، لأنه يعطّل مسار الضغط العادي لـ /compact واسترداد تجاوز السعة في خانة ذلك المحرك.

مرجع الإعداد

{
  plugins: {
    slots: {
      // Select the active context engine. Default: "legacy".
      // Set to a plugin id to use a plugin engine.
      contextEngine: "legacy",
    },
  },
}
الخانة حصرية وقت التشغيل - لا يُحلّ إلا محرك سياق واحد مسجل لتشغيل أو عملية ضغط معينة. لا يزال بإمكان Plugins أخرى مفعّلة من النوع kind: "context-engine" التحميل وتشغيل كود التسجيل الخاص بها؛ يحدد plugins.slots.contextEngine فقط معرّف المحرك المسجل الذي يحلّه OpenClaw عندما يحتاج إلى محرك سياق.
إلغاء تثبيت Plugin: عندما تلغي تثبيت Plugin المحدد حاليًا كـ plugins.slots.contextEngine، يعيد OpenClaw ضبط الخانة إلى القيمة الافتراضية (legacy). ينطبق سلوك إعادة الضبط نفسه على plugins.slots.memory. لا يلزم تعديل الإعداد يدويًا.

العلاقة بالضغط والذاكرة

يُعد Compaction إحدى مسؤوليات محرك السياق. يفوّض المحرك القديم إلى التلخيص المدمج في OpenClaw. يمكن لمحركات Plugin تنفيذ أي استراتيجية ضغط، مثل ملخصات DAG، والاسترجاع المتجهي، وغير ذلك.
تكون Plugins الذاكرة (plugins.slots.memory) منفصلة عن محركات السياق. توفر Plugins الذاكرة البحث/الاسترجاع؛ وتتحكم محركات السياق فيما يراه النموذج. يمكنها العمل معًا - فقد يستخدم محرك سياق بيانات Plugin الذاكرة أثناء التجميع. ينبغي لمحركات Plugin التي تريد مسار موجّه الذاكرة النشط تفضيل buildMemorySystemPromptAddition(...) من openclaw/plugin-sdk/core، الذي يحوّل أقسام موجّه الذاكرة النشطة إلى systemPromptAddition جاهز للإضافة في المقدمة. إذا احتاج محرك إلى تحكم أدنى مستوى، فلا يزال بإمكانه سحب الأسطر الخام من openclaw/plugin-sdk/memory-host-core عبر buildActiveMemoryPromptSection(...).
يظل تقليم نتائج الأدوات القديمة في الذاكرة يعمل بغض النظر عن محرك السياق النشط.

نصائح

  • استخدم openclaw doctor للتحقق من أن محركك يُحمَّل بشكل صحيح.
  • عند تبديل المحركات، تستمر الجلسات الحالية بسجلها الحالي. يتولى المحرك الجديد التشغيلات المستقبلية.
  • تُسجَّل أخطاء المحرك ويُعزل محرك Plugin المحدد لعملية Gateway الحالية. يعود OpenClaw إلى legacy لدورات المستخدم حتى تستمر الردود، لكن ينبغي لك مع ذلك إصلاح Plugin المعطّل أو تحديثه أو تعطيله أو إلغاء تثبيته.
  • للتطوير، استخدم openclaw plugins install -l ./my-engine لربط دليل Plugin محلي من دون نسخه.

ذو صلة