Technical reference

نظافة السجل النصي

يُطبّق OpenClaw إصلاحات خاصة بكل مزوّد على النصوص المنسوخة قبل التشغيل (عند بناء سياق النموذج). ومعظم هذه الإصلاحات تعديلات تُجرى في الذاكرة لاستيفاء متطلبات المزوّد الصارمة. وقد تعيد مرحلة منفصلة لإصلاح ملف الجلسة كتابة بيانات JSONL المخزّنة قبل تحميل الجلسة، ولكن فقط للأسطر المشوّهة أو الأدوار المحفوظة التي لا تصلح كسجلات دائمة. تُحفَظ ردود المساعد التي جرى تسليمها على القرص؛ ولا تحدث إزالة التمهيد المسبق الخاص بالمزوّد من ردود المساعد إلا عند إنشاء الحمولات الصادرة.

عند إجراء إصلاح، يُكتب الملف الأصلي في ملف شقيق مؤقت باسم *.bak-<pid>-<ts> قبل الاستبدال الذري، ثم يُحذف بعد نجاح الاستبدال. ولا تُحتفظ النسخة الاحتياطية إلا إذا فشلت عملية التنظيف نفسها، وفي هذه الحالة يُبلَّغ عن المسار.

يشمل النطاق ما يلي:

منع سياق المطالبة الخاص بوقت التشغيل من الظهور ضمن أدوار النص المنسوخ المرئية للمستخدم
تنقية معرّفات استدعاءات الأدوات
التحقق من صحة مدخلات استدعاءات الأدوات
إصلاح إقران نتائج الأدوات
التحقق من صحة الأدوار وترتيبها
تنظيف توقيعات الأفكار
تنظيف توقيعات التفكير
تنقية حمولات الصور
تنظيف كتل النص الفارغة قبل إعادة التشغيل لدى المزوّد
تنظيف أدوار الطول غير المكتملة التي لا تحتوي إلا على الاستدلال قبل إعادة التشغيل لدى المزوّد
وسم مصدر مدخلات المستخدم (للمطالبات الموجّهة بين الجلسات)
إصلاح أدوار أخطاء المساعد الفارغة لإعادة التشغيل عبر Bedrock Converse

إذا كنت تحتاج إلى تفاصيل تخزين النصوص المنسوخة، فراجع التعمق في إدارة الجلسات.

القاعدة العامة: سياق وقت التشغيل ليس نص المستخدم المنسوخ

يمكن إضافة سياق وقت التشغيل/النظام إلى مطالبة النموذج لأحد الأدوار، لكنه ليس محتوى أنشأه المستخدم النهائي. يحتفظ OpenClaw بنص منفصل للمطالبة الموجّهة إلى النص المنسوخ لردود Gateway، والمتابعات الموضوعة في قائمة الانتظار، وACP، وCLI، وعمليات تشغيل OpenClaw المضمّنة. تستخدم أدوار المستخدم المرئية المخزّنة نصَّ النص المنسوخ هذا بدلًا من المطالبة المعززة بسياق وقت التشغيل.

بالنسبة إلى الجلسات القديمة التي حفظت بالفعل أغلفة وقت التشغيل، تطبّق واجهات سجل Gateway إسقاطًا للعرض قبل إعادة الرسائل إلى عملاء WebChat أو TUI أو REST أو SSE.

موضع التنفيذ

تتركز جميع عمليات ضبط النصوص المنسوخة في المشغّل المضمّن:

اختيار السياسة: src/agents/transcript-policy.ts (resolveTranscriptPolicy، استنادًا إلى provider وmodelApi وmodelId)
تطبيق التنقية/الإصلاح: sanitizeSessionHistory في src/agents/embedded-agent-runner/replay-history.ts

بمعزل عن ضبط النصوص المنسوخة، تُصلح ملفات الجلسات (عند الحاجة) قبل التحميل:

repairSessionFileIfNeeded في src/agents/session-file-repair.ts
يُستدعى من src/agents/embedded-agent-runner/run/attempt.ts و src/agents/embedded-agent-runner/compact.ts

القاعدة العامة: تنقية الصور

تُنقّى حمولات الصور دائمًا لمنع رفضها من جانب المزوّد بسبب حدود الحجم (تصغير الصور الكبيرة بترميز base64 أو إعادة ضغطها). ويساعد ذلك أيضًا على التحكم في ضغط الرموز الناتج عن الصور في النماذج القادرة على الرؤية: تقلّل الأبعاد القصوى الأصغر استخدام الرموز، بينما تحافظ الأبعاد الأكبر على التفاصيل.

التنفيذ:

sanitizeSessionMessagesImages في src/agents/embedded-agent-helpers/images.ts
sanitizeContentBlocksImages في src/agents/tool-images.ts
يمكن ضبط الحد الأقصى لضلع الصورة عبر agents.defaults.imageMaxDimensionPx (القيمة الافتراضية: 1200)
تُزال كتل النص الفارغة أثناء مرور هذه المرحلة على محتوى إعادة التشغيل. وتُحذف أدوار المساعد التي تصبح فارغة من نسخة إعادة التشغيل؛ أما أدوار المستخدم ونتائج الأدوات التي تصبح فارغة، فتتلقى عنصرًا نائبًا غير فارغ للمحتوى المحذوف.

القاعدة العامة: استدعاءات الأدوات المشوّهة

تُحذف كتل استدعاءات أدوات المساعد التي تفتقد كلًا من input وarguments قبل بناء سياق النموذج. يمنع ذلك رفض المزوّد لاستدعاءات الأدوات المحفوظة جزئيًا (على سبيل المثال، بعد إخفاق بسبب حد المعدّل).

التنفيذ:

sanitizeToolCallInputs في src/agents/session-transcript-repair.ts
يُطبّق في sanitizeSessionHistory (src/agents/embedded-agent-runner/replay-history.ts)

القاعدة العامة: الأدوار غير المكتملة التي لا تحتوي إلا على الاستدلال

تُستبعد من نسخة إعادة التشغيل في الذاكرة أدوار المساعد التي بلغت حد مخرجات المزوّد ولم تحتوِ إلا على محتوى تفكير أو تفكير منقّح. تحتوي هذه الأدوار على حالة مزوّد غير مكتملة، وقد تحمل توقيع تفكير جزئيًا.

تظل أدوار الطول الفارغة دون تغيير، وكذلك أدوار الطول التي تحتوي على نص مرئي أو استدعاءات أدوات أو كتل محتوى غير معروفة. ولا يُعاد كتابة النصوص المنسوخة المخزّنة.

التنفيذ: normalizeAssistantReplayContent في src/agents/embedded-agent-runner/replay-history.ts

القاعدة العامة: مصدر المدخلات بين الجلسات

عندما يرسل وكيل مطالبة إلى جلسة أخرى عبر sessions_send (بما في ذلك خطوات الرد/الإعلان من وكيل إلى وكيل)، يحفظ OpenClaw دور المستخدم المنشأ مع message.provenance.kind = "inter_session".

ويضيف OpenClaw أيضًا في بداية الدور نفسه علامة [Inter-session message] ... isUser=false قبل نص المطالبة الموجّهة، حتى يتمكن استدعاء النموذج النشط من تمييز مخرجات الجلسة الأجنبية عن تعليمات المستخدم النهائي الخارجي. تتضمن هذه العلامة الجلسة المصدر والقناة والأداة عند توفرها. يظل النص المنسوخ يستخدم role: "user" للتوافق مع المزوّد، لكن كلًا من النص المرئي وبيانات المصدر الوصفية يميّز الدور على أنه بيانات بين الجلسات.

أثناء إعادة بناء السياق، يطبّق OpenClaw العلامة نفسها على أدوار المستخدم القديمة المحفوظة بين الجلسات التي لا تحتوي إلا على بيانات المصدر الوصفية.

مصفوفة المزوّدين (السلوك الحالي)

OpenAI / OpenAI Codex

تنقية الصور فقط.
حذف توقيعات الاستدلال اليتيمة (عناصر الاستدلال المستقلة التي لا تتبعها كتلة محتوى) من نصوص OpenAI Responses/Codex المنسوخة، وحذف استدلال OpenAI القابل لإعادة التشغيل بعد تبديل مسار النموذج.
الحفاظ على حمولات عناصر استدلال OpenAI Responses القابلة لإعادة التشغيل، بما في ذلك العناصر المشفّرة ذات الملخص الفارغ، حتى تبقي إعادة التشغيل اليدوية/عبر WebSocket حالة rs_* المطلوبة مقترنة بعناصر مخرجات المساعد.
تتبع واجهة Native ChatGPT Codex Responses التكافؤ السلكي مع Codex من خلال إعادة تشغيل حمولات الاستدلال/الرسائل/الدوال السابقة لـ Responses دون معرّفات العناصر السابقة، مع الحفاظ على prompt_cache_key الخاص بالجلسة.
تحافظ إعادة التشغيل لعائلة OpenAI Responses على أزواج الاستدلال القياسية call_*|fc_* للنموذج نفسه، لكنها تطبّع بصورة حتمية معرّفات call_id أو معرّفات عناصر استدعاء الدوال المشوّهة أو المفرطة الطول قبل تحويل الحمولة في pi-ai.
قد ينقل إصلاح إقران نتائج الأدوات المخرجات الحقيقية المطابقة، وينشئ مخرجات aborted بأسلوب Codex لاستدعاءات الأدوات المفقودة.
لا يوجد تحقق من صحة الأدوار أو إعادة ترتيبها؛ ولا إزالة لتوقيعات الأفكار.

إكمالات الدردشة المتوافقة مع OpenAI

تُزال كتل التفكير/الاستدلال التاريخية للمساعد قبل إعادة التشغيل، حتى لا تتلقى الخوادم المحلية والخوادم الوكيلة المتوافقة مع OpenAI حقول استدلال من الأدوار السابقة مثل reasoning أو reasoning_content.
تحتفظ استمراريات استدعاءات الأدوات ضمن الدور الحالي بكتلة استدلال المساعد مرفقة باستدعاء الأداة حتى إعادة تشغيل نتيجة الأداة.
تحتفظ إدخالات النماذج المخصّصة/المستضافة ذاتيًا التي تتضمن reasoning: true ببيانات الاستدلال الوصفية المعاد تشغيلها.
يمكن للاستثناءات التي يملكها المزوّد تعطيل ذلك عندما يتطلب بروتوكولها السلكي إعادة تشغيل بيانات الاستدلال الوصفية.

Google (Generative AI / Gemini CLI / Antigravity)

تنقية معرّفات استدعاءات الأدوات: أبجدية رقمية صارمة.
إصلاح إقران نتائج الأدوات وإنشاء نتائج أدوات اصطناعية.
التحقق من صحة الأدوار (التناوب بين الأدوار بأسلوب Gemini).
إصلاح ترتيب أدوار Google (إضافة تمهيد صغير للمستخدم في البداية إذا بدأ السجل بالمساعد).
Antigravity Claude: تطبيع توقيعات التفكير؛ وحذف كتل التفكير غير الموقّعة.

Anthropic / Minimax (متوافق مع Anthropic)

إصلاح إقران نتائج الأدوات وإنشاء نتائج أدوات اصطناعية.
التحقق من صحة الأدوار (دمج أدوار المستخدم المتتالية لاستيفاء التناوب الصارم).
تُزال أدوار التمهيد المسبق الأخيرة للمساعد من حمولات Anthropic Messages الصادرة عند تمكين التفكير، بما في ذلك المسارات عبر Cloudflare AI Gateway.
تُزال توقيعات تفكير المساعد السابقة لـ Compaction قبل إعادة التشغيل لدى المزوّد عندما تكون الجلسة قد خضعت لـ Compaction. ترتبط توقيعات التفكير تشفيريًا ببداية المحادثة وقت إنشائها؛ وبعد Compaction تتغير البداية (إذ يحل المحتوى الملخص محل المحتوى الأصلي)، ولذلك تؤدي إعادة تشغيل التوقيعات الأصلية إلى رفض Anthropic للطلب برسالة «توقيع غير صالح في كتلة التفكير». يُحفَظ نص التفكير ككتلة غير موقّعة، ثم تتعامل معه القاعدة التالية.
تُزال كتل التفكير ذات توقيعات إعادة التشغيل المفقودة أو الفارغة أو الخالية من المحتوى قبل التحويل الخاص بالمزوّد. وإذا أدى ذلك إلى إفراغ دور المساعد، يحافظ OpenClaw على بنية الدور باستخدام نص غير فارغ يشير إلى حذف الاستدلال.
تُستبدل أدوار المساعد القديمة التي لا تحتوي إلا على التفكير ويجب حذفها بنص غير فارغ يشير إلى حذف الاستدلال، حتى لا تُسقط محوّلات المزوّد دور إعادة التشغيل.

Amazon Bedrock (واجهة Converse API)

تُصلح أدوار أخطاء تدفق المساعد الفارغة إلى كتلة نص احتياطية غير فارغة قبل إعادة التشغيل. يرفض Bedrock Converse رسائل المساعد التي تحتوي على content: []، ولذلك تُصلح أيضًا على القرص قبل التحميل أدوار المساعد المحفوظة التي تحتوي على stopReason: "error" ومحتوى فارغ.
تُحذف أدوار أخطاء تدفق المساعد التي لا تحتوي إلا على كتل نص فارغة من نسخة إعادة التشغيل في الذاكرة بدلًا من إعادة تشغيل كتلة فارغة غير صالحة.
تُزال توقيعات تفكير المساعد السابقة لـ Compaction قبل إعادة التشغيل عبر Converse عندما تكون الجلسة قد خضعت لـ Compaction، للسبب نفسه المذكور أعلاه بشأن Anthropic.
تُزال كتل تفكير Claude ذات توقيعات إعادة التشغيل المفقودة أو الفارغة أو الخالية من المحتوى قبل إعادة التشغيل عبر Converse. وإذا أدى ذلك إلى إفراغ دور المساعد، يحافظ OpenClaw على بنية الدور باستخدام نص غير فارغ يشير إلى حذف الاستدلال.
تُستبدل أدوار المساعد القديمة التي لا تحتوي إلا على التفكير ويجب حذفها بنص غير فارغ يشير إلى حذف الاستدلال، حتى تحافظ إعادة التشغيل عبر Converse على بنية الأدوار الصارمة.
ترشّح إعادة التشغيل أدوار المساعد المنسوخة لأغراض التسليم والمحقونة عبر Gateway في OpenClaw.
تُطبّق تنقية الصور من خلال القاعدة العامة.

Mistral (بما في ذلك الاكتشاف المستند إلى معرّف النموذج)

تنقية معرّفات استدعاءات الأدوات: strict9 (أبجدية رقمية بطول 9).

OpenRouter Gemini

تنظيف توقيعات الأفكار: إزالة قيم thought_signature التي ليست بترميز base64 (والاحتفاظ بالقيم ذات ترميز base64).

OpenRouter Anthropic

تُزال أدوار التمهيد المسبق الأخيرة للمساعد من حمولات نماذج Anthropic المتوافقة مع OpenAI والمتحقق منها في OpenRouter عند تمكين الاستدلال، بما يتطابق مع سلوك إعادة التشغيل المباشر لدى Anthropic وعبر Cloudflare Anthropic.

كل ما عدا ذلك

تنقية الصور فقط.

السلوك التاريخي (قبل 2026.1.22)

قبل إصدار 2026.1.22، كان OpenClaw يطبّق طبقات متعددة من ضبط النصوص المنسوخة:

كان امتداد تنقية النصوص المنسوخة يعمل عند كل بناء للسياق، وكان بإمكانه:
- إصلاح إقران استخدام الأدوات بنتائجها.
- تنقية معرّفات استدعاءات الأدوات (بما في ذلك وضع غير صارم يحتفظ بـ _/-).
كان المشغّل ينفّذ أيضًا تنقية خاصة بكل مزوّد، ما أدى إلى تكرار العمل.
حدثت تعديلات إضافية خارج سياسة المزوّد، بما في ذلك إزالة وسوم <final> من نص المساعد قبل الحفظ، وحذف أدوار أخطاء المساعد الفارغة، واقتطاع محتوى المساعد بعد استدعاءات الأدوات.

تسبب هذا التعقيد في تراجعات في السلوك عبر المزوّدين (وخاصة في إقران call_id|fc_id ضمن openai-responses). أزالت عملية التنظيف في 2026.1.22 الامتداد، وركّزت المنطق في المشغّل، وجعلت OpenAI دون تعديل باستثناء تنقية الصور.

ذو صلة

Was this useful?