محرك السياق

A محرك السياق يتحكم في كيفية بناء 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 مسؤولًا عن سجل سلسلة المحادثة الأصلي وأداة Compaction الأصلية الخاصة به.

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

يستدعي OpenClaw خطافي دورة حياة اختياريين للوكلاء الفرعيين:

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

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

المحرك القديم

يحافظ محرك legacy المدمج على سلوك OpenClaw الأصلي:

• الاستيعاب: لا ينفّذ أي إجراء (يتولى مدير الجلسة حفظ الرسائل مباشرةً).
• التجميع: تمرير مباشر (يتولى المسار الحالي للتنقية ← التحقق ← التقييد في بيئة التشغيل تجميع السياق).
• Compaction: يفوّض إلى Compaction التلخيصي المدمج، الذي ينشئ ملخصًا واحدًا للرسائل الأقدم ويُبقي الرسائل الحديثة كما هي.
• بعد الدور: لا ينفّذ أي إجراء.

لا يسجّل المحرك القديم أدوات ولا يوفّر systemPromptAddition.

عندما لا يكون plugins.slots.contextEngine مضبوطًا (أو يكون مضبوطًا على "legacy") يُستخدم هذا المحرك تلقائيًا.

محركات Plugins

يمكن لـ Plugin تسجيل محرك سياق باستخدام واجهة برمجة تطبيقات 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 }) {      // خزّن الرسالة في مخزن بياناتك      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,          agentId: resolveSessionAgentId({ config: ctx.config, sessionKey }),          agentSessionKey: sessionKey,        }),      };    },     async compact({ sessionId, force }) {      // لخّص السياق الأقدم      return { ok: true, compacted: true };    },  }));}

يتضمن المصنع ctx قيمًا اختيارية هي config وagentDir وworkspaceDir بحيث يمكن لـ Plugins تهيئة الحالة لكل وكيل أو لكل مساحة عمل قبل تشغيل أول خطاف لدورة الحياة.

ثم فعّله في الإعدادات:

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

واجهة ContextEngine

الأعضاء المطلوبة:

يعيد assemble كائن AssembleResult يحتوي على:

يعيد compact كائن CompactResult. عندما تغيّر Compaction هوية الجلسة النشطة، يحدّد result.sessionTarget (وهو ContextEngineSessionTarget ذو نوع محدد يحمل هوية الجلسة ونطاق التخزين) الجلسة اللاحقة التي يجب أن تستخدمها إعادة المحاولة أو الدور التالي؛ ويطابق result.sessionId معرّف الجلسة اللاحقة.

الأعضاء الاختيارية:

إعدادات بيئة التشغيل

تتلقى خطافات دورة الحياة التي تعمل داخل OpenClaw كائن runtimeSettings اختياريًا. وهو سطح واجهة برمجة تطبيقات داخلية لمنتج/مستهلك، محدد الإصدار وللقراءة فقط: ينتجه OpenClaw لمحرك السياق المحدد، ويستهلكه محرك السياق داخل خطافات دورة الحياة. ولا يُعرض مباشرةً للمستخدمين ولا ينشئ سطحًا مخصصًا لإعداد التقارير.

• schemaVersion: حاليًا 1
• runtime: مضيف OpenClaw، ووضع وقت التشغيل (normal، أو fallback، أو degraded)، ومعرّفات إطار الاختبار/وقت التشغيل الاختيارية
• contextEngineSelection: معرّف محرك السياق المحدد ومصدر التحديد
• executionHost: معرّف المضيف وتسميته للسطح الذي يستدعي الخطاف
• model: النموذج المطلوب، والنموذج المحسوم، والموفّر، وعائلة النموذج الاختيارية
• limits: ميزانية رموز المطالبة والحد الأقصى لرموز الإخراج عندما يكونان معروفين
• diagnostics: رموز أسباب الرجوع الاحتياطي المغلق والتشغيل المتدهور عندما تكون معروفة

تُمثَّل الحقول التي يمكن أن تكون غير معروفة بالقيمة null؛ أما حقول التمييز مثل وضع وقت التشغيل ومصدر التحديد فتظل غير قابلة للقيمة الخالية. وتظل المحركات الأقدم متوافقة: إذا رفض محرك قديم صارم الخاصية 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:        "استخدم 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 - تسجيل Plugins محرك السياق
• بيان Plugin - حقول بيان Plugin
• Plugins - نظرة عامة على Plugins