> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# تعمّق في إدارة الجلسات

# إدارة الجلسات والضغط (تعمّق تقني)

تشرح هذه الوثيقة كيف يدير OpenClaw الجلسات من البداية إلى النهاية:

* **توجيه الجلسة** (كيف تُطابِق الرسائل الواردة `sessionKey`)
* **مخزن الجلسة** (`sessions.json`) وما الذي يتتبّعه
* **استمرارية السجل النصي** (`*.jsonl`) وبنيته
* **نظافة السجل النصي** (تصحيحات خاصة بالموفّر قبل التشغيل)
* **حدود السياق** (نافذة السياق مقابل الرموز المتتبَّعة)
* **الضغط** (اليدوي + التلقائي) وأين يمكن ربط أعمال ما قبل الضغط
* **الصيانة الصامتة** (مثل كتابات الذاكرة التي لا ينبغي أن تُنتِج مخرجات مرئية للمستخدم)

إذا أردت نظرة عامة أعلى مستوى أولًا، ابدأ بـ:

* [/concepts/session](/concepts/session)
* [/concepts/compaction](/concepts/compaction)
* [/concepts/session-pruning](/concepts/session-pruning)
* [/reference/transcript-hygiene](/reference/transcript-hygiene)

***

## مصدر الحقيقة: الـ Gateway

صُمّم OpenClaw حول **عملية Gateway واحدة** تمتلك حالة الجلسة.

* ينبغي لواجهات المستخدم (تطبيق macOS، واجهة التحكم على الويب، TUI) الاستعلام من الـ Gateway عن قوائم الجلسات وعدّادات الرموز.
* في الوضع البعيد، تكون ملفات الجلسة على المضيف البعيد؛ «فحص ملفات Mac المحلية» لن يعكس ما يستخدمه الـ Gateway.

***

## طبقتان ثابتتان

يحفظ OpenClaw الجلسات في طبقتين:

1. **مخزن الجلسة (`sessions.json`)**
   * خريطة مفتاح/قيمة: `sessionKey -> SessionEntry`
   * صغير، قابل للتغيير، وآمن للتحرير (أو حذف الإدخالات)
   * يتتبّع بيانات وصفية للجلسة (معرّف الجلسة الحالي، آخر نشاط، مفاتيح التبديل، عدّادات الرموز، إلخ)

2. **السجل النصي (`<sessionId>.jsonl`)**
   * سجل إلحاقي فقط ببنية شجرية (للإدخالات `id` + `parentId`)
   * يخزّن المحادثة الفعلية + استدعاءات الأدوات + ملخّصات الضغط
   * يُستخدم لإعادة بناء سياق النموذج للأدوار اللاحقة

***

## مواقع التخزين على القرص

لكل وكيل، على مضيف الـ Gateway:

* المخزن: `~/.openclaw/agents/<agentId>/sessions/sessions.json`
* السجلات النصية: `~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl`
  * جلسات مواضيع Telegram: `.../<sessionId>-topic-<threadId>.jsonl`

يحلّ OpenClaw هذه المسارات عبر `src/config/sessions.ts`.

***

## مفاتيح الجلسة (`sessionKey`)

يُحدِّد `sessionKey` «أي دلو محادثة» أنت فيه (توجيه + عزل).

أنماط شائعة:

* الدردشة الرئيسية/المباشرة (لكل وكيل): `agent:<agentId>:<mainKey>` (الافتراضي `main`)
* مجموعة: `agent:<agentId>:<channel>:group:<id>`
* غرفة/قناة (Discord/Slack): `agent:<agentId>:<channel>:channel:<id>` أو `...:room:<id>`
* كرون: `cron:<job.id>`
* Webhook: `hook:<uuid>` (ما لم يتم التجاوز)

القواعد المعتمدة موثّقة في [/concepts/session](/concepts/session).

***

## معرّفات الجلسات (`sessionId`)

يشير كل `sessionKey` إلى `sessionId` الحالي (ملف السجل النصي الذي يواصل المحادثة).

قواعد عامة:

* **إعادة الضبط** (`/new`، `/reset`) تُنشئ `sessionId` جديدًا لذلك `sessionKey`.
* **إعادة الضبط اليومية** (الافتراضي 4:00 صباحًا بالتوقيت المحلي على مضيف الـ Gateway) تُنشئ `sessionId` جديدًا عند الرسالة التالية بعد حدّ إعادة الضبط.
* **انتهاء الخمول** (`session.reset.idleMinutes` أو القديم `session.idleMinutes`) يُنشئ `sessionId` جديدًا عند وصول رسالة بعد نافذة الخمول. عند تفعيل اليومي + الخمول معًا، يفوز أيّهما ينتهي أولًا.

تفصيل تنفيذي: يحدث القرار في `initSessionState()` ضمن `src/auto-reply/reply/session.ts`.

***

## مخطط مخزن الجلسة (`sessions.json`)

نوع قيمة المخزن هو `SessionEntry` في `src/config/sessions.ts`.

الحقول الرئيسية (غير حصرية):

* `sessionId`: معرّف السجل النصي الحالي (يُشتق اسم الملف منه ما لم يتم تعيين `sessionFile`)
* `updatedAt`: طابع زمني لآخر نشاط
* `sessionFile`: تجاوز اختياري لمسار السجل النصي
* `chatType`: `direct | group | room` (يساعد واجهات المستخدم وسياسة الإرسال)
* `provider`، `subject`، `room`، `space`، `displayName`: بيانات وصفية لتوسيم المجموعة/القناة
* مفاتيح التبديل:
  * `thinkingLevel`، `verboseLevel`، `reasoningLevel`، `elevatedLevel`
  * `sendPolicy` (تجاوز لكل جلسة)
* اختيار النموذج:
  * `providerOverride`، `modelOverride`، `authProfileOverride`
* عدّادات الرموز (أفضل جهد/تعتمد على الموفّر):
  * `inputTokens`، `outputTokens`، `totalTokens`، `contextTokens`
* `compactionCount`: عدد مرات اكتمال الضغط التلقائي لهذا مفتاح الجلسة
* `memoryFlushAt`: الطابع الزمني لآخر تفريغ ذاكرة قبل الضغط
* `memoryFlushCompactionCount`: عدد الضغط عند تشغيل آخر تفريغ

المخزن آمن للتحرير، لكن الـ Gateway هو المرجع: قد يعيد كتابة الإدخالات أو إعادة إحيائها أثناء تشغيل الجلسات.

***

## بنية السجل النصي (`*.jsonl`)

تُدار السجلات النصية بواسطة `@mariozechner/pi-coding-agent` الخاص بـ `SessionManager`.

الملف بصيغة JSONL:

* السطر الأول: رأس الجلسة (`type: "session"`، يتضمن `id`، `cwd`، `timestamp`، و `parentSession` الاختياري)
* ثم: إدخالات الجلسة مع `id` + `parentId` (شجرة)

أنواع إدخالات ملحوظة:

* `message`: رسائل المستخدم/المساعد/نتيجة الأداة
* `custom_message`: رسائل محقونة بواسطة الامتداد تدخل سياق النموذج (يمكن إخفاؤها عن واجهة المستخدم)
* `custom`: حالة الامتداد التي لا تدخل سياق النموذج
* `compaction`: ملخّص ضغط محفوظ مع `firstKeptEntryId` و `tokensBefore`
* `branch_summary`: ملخّص محفوظ عند التنقّل في فرع شجري

يتعمّد OpenClaw **عدم** «تصحيح» السجلات النصية؛ يستخدم الـ Gateway `SessionManager` لقراءتها وكتابتها.

***

## نوافذ السياق مقابل الرموز المتتبَّعة

مفهومان مختلفان مهمّان:

1. **نافذة سياق النموذج**: حدّ صارم لكل نموذج (الرموز المرئية للنموذج)
2. **عدّادات مخزن الجلسة**: إحصاءات متحرّكة تُكتب في `sessions.json` (تُستخدم لأوامر /status ولوحات المتابعة)

إذا كنت تضبط الحدود:

* تأتي نافذة السياق من كتالوج النماذج (ويمكن تجاوزها عبر التهيئة).
* `contextTokens` في المخزن هو قيمة تقدير/إبلاغ وقت التشغيل؛ لا تتعامل معه كضمان صارم.

للمزيد، راجع [/token-use](/reference/token-use).

***

## الضغط: ما هو

يلخّص الضغط المحادثات الأقدم في إدخال `compaction` محفوظ في السجل النصي، مع إبقاء الرسائل الحديثة سليمة.

بعد الضغط، ترى الأدوار اللاحقة:

* ملخص الدمج
* الرسائل بعد `firstKeptEntryId`

الضغط **مستمر** (على عكس تقليم الجلسة). انظر [/concepts/session-pruning](/concepts/session-pruning).

***

## متى يحدث الضغط التلقائي (تشغيل Pi)

في وكيل Pi المضمّن، يُفعَّل الضغط التلقائي في حالتين:

1. **استعادة من فيضان**: يُرجع النموذج خطأ فيضان السياق → ضغط → إعادة المحاولة.
2. **صيانة العتبة**: بعد دور ناجح، عندما:

`contextTokens > contextWindow - reserveTokens`

حيث:

* `contextWindow` هي نافذة سياق النموذج
* `reserveTokens` هو الهامش المحجوز للمطالبات + مخرج النموذج التالي

هذه دلالات تشغيل Pi (يستهلك OpenClaw الأحداث، لكن Pi هو من يقرّر متى يضغط).

***

## إعدادات الضغط (`reserveTokens`، `keepRecentTokens`)

توجد إعدادات الضغط الخاصة بـ Pi ضمن إعدادات Pi:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  compaction: {
    enabled: true,
    reserveTokens: 16384,
    keepRecentTokens: 20000,
  },
}
```

يفرض OpenClaw أيضًا حدّ أمان أدنى للتشغيلات المضمّنة:

* إذا كان `compaction.reserveTokens < reserveTokensFloor` أقل، يرفعه OpenClaw.
* الحدّ الافتراضي الأدنى هو `20000` رمزًا.
* اضبط `agents.defaults.compaction.reserveTokensFloor: 0` لتعطيل الحدّ الأدنى.
* إذا كان أعلى بالفعل، يتركه OpenClaw كما هو.

السبب: ترك هامش كافٍ لأعمال «الصيانة» متعددة الأدوار (مثل كتابات الذاكرة) قبل أن يصبح الضغط حتميًا.

التنفيذ: `ensurePiCompactionReserveTokens()` في `src/agents/pi-settings.ts`
(يُستدعى من `src/agents/pi-embedded-runner.ts`).

***

## الواجهات المرئية للمستخدم

يمكنك ملاحظة الضغط وحالة الجلسة عبر:

* `/status` (في أي جلسة دردشة)
* `openclaw status` (CLI)
* `openclaw sessions` / `sessions --json`
* الوضع المفصّل: `🧹 Auto-compaction complete` + عدد مرات الضغط

***

## الصيانة الصامتة (`NO_REPLY`)

يدعم OpenClaw أدوارًا «صامتة» للمهام الخلفية حيث لا ينبغي للمستخدم رؤية مخرجات وسيطة.

الاتفاقية:

* يبدأ المساعد مخرجه بـ `NO_REPLY` للإشارة إلى «عدم تسليم ردّ للمستخدم».
* يقوم OpenClaw بإزالة/كبت ذلك في طبقة التسليم.

اعتبارًا من `2026.1.10`، يقوم OpenClaw أيضًا بكبت **بثّ المسودات/الكتابة** عندما تبدأ قطعة جزئية بـ `NO_REPLY`، حتى لا تتسرّب مخرجات جزئية أثناء الدور.

***

## «تفريغ الذاكرة» قبل الضغط (مُنفَّذ)

الهدف: قبل حدوث الضغط التلقائي، تشغيل دور وكيل صامت يكتب حالة دائمة إلى القرص
(مثل `memory/YYYY-MM-DD.md` في مساحة عمل الوكيل) بحيث لا يستطيع الضغط
محو السياق الحرج.

يستخدم OpenClaw نهج **التفريغ قبل العتبة**:

1. مراقبة استخدام سياق الجلسة.
2. عند تجاوز «عتبة لينة» (أدنى من عتبة الضغط في Pi)، تشغيل توجيه صامت
   «اكتب الذاكرة الآن» إلى الوكيل.
3. استخدام `NO_REPLY` بحيث لا يرى المستخدم شيئًا.

التهيئة (`agents.defaults.compaction.memoryFlush`):

* `enabled` (الافتراضي: `true`)
* `softThresholdTokens` (الافتراضي: `4000`)
* `prompt` (رسالة المستخدم لدور التفريغ)
* `systemPrompt` (موجّه نظام إضافي يُلحق بدور التفريغ)

ملاحظات:

* تتضمن المطالبة/موجّه النظام الافتراضيان تلميح `NO_REPLY` لكبت التسليم.
* يعمل التفريغ مرة واحدة لكل دورة ضغط (يُتتبَّع في `sessions.json`).
* يعمل التفريغ فقط لجلسات Pi المضمّنة (تتجاوز الخلفيات عبر CLI ذلك).
* يُتجاوز التفريغ عندما تكون مساحة عمل الجلسة للقراءة فقط (`workspaceAccess: "ro"` أو `"none"`).
* راجع [Memory](/concepts/memory) لتخطيط ملفات مساحة العمل وأنماط الكتابة.

يُتيح Pi أيضًا خطّاف `session_before_compact` في واجهة برمجة الامتداد، لكن منطق التفريغ في OpenClaw
يعيش اليوم على جانب الـ Gateway.

***

## قائمة التحقق لاستكشاف الأخطاء وإصلاحها

* خطأ في مفتاح الجلسة؟ خطأ في مفتاح الجلسة؟ مفتاح الجلسة خاطئ؟ ابدأ بـ [/concepts/session](/concepts/session) وأكّد `sessionKey` في `/status`.
* تخزين ضد عدم تطابق النص ؟ تخزين ضد عدم تطابق النص ؟ عدم تطابق المخزن مع السجل النصي؟ أكّد مضيف الـ Gateway ومسار المخزن من `openclaw status`.
* البريد المزعج؟ تحقّق من: تحقّق من:
  * نافذة سياق النموذج (صغيرة جدًا)
  * إعدادات الضغط (`reserveTokens` المرتفع جدًا مقارنة بنافذة النموذج قد يسبّب ضغطًا أبكر)
  * تضخّم نتائج الأدوات: فعّل/اضبط تقليم الجلسة
* الدوران الصامت للتسرب؟ تسرّب الأدوار الصامتة؟ أكّد أن الرد يبدأ بـ `NO_REPLY` (الرمز الدقيق) وأنك على إصدار يتضمن إصلاح كبت البثّ.