---
read_when:
    - تحتاج إلى تصحيح معرّفات الجلسات، أو ملف JSONL الخاص بالنصوص المفرغة، أو حقول `sessions.json`
    - أنت تغيّر سلوك Compaction التلقائي أو تضيف أعمال ترتيب تمهيدية «قبل Compaction»
    - تريد تنفيذ عمليات تفريغ الذاكرة أو دورات نظام صامتة
summary: 'نظرة متعمقة: مخزن الجلسات + النصوص المفرغة، ودورة الحياة، والجوانب الداخلية لـ Compaction (اليدوية والتلقائية)'
title: نظرة متعمقة على إدارة الجلسات
x-i18n:
    generated_at: "2026-04-26T11:40:01Z"
    model: gpt-5.4
    provider: openai
    source_hash: f41f1c403f978c22cc2a929629e1811414d1399fa7f9e28c481fcb594d30196f
    source_path: reference/session-management-compaction.md
    workflow: 15
---

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

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

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

- [إدارة الجلسات](/ar/concepts/session)
- [Compaction](/ar/concepts/compaction)
- [نظرة عامة على الذاكرة](/ar/concepts/memory)
- [البحث في الذاكرة](/ar/concepts/memory-search)
- [تشذيب الجلسات](/ar/concepts/session-pruning)
- [نظافة النصوص المفرغة](/ar/reference/transcript-hygiene)

---

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

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

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

---

## طبقتا الاستدامة

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

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

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

---

## المواقع على القرص

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

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

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

---

## صيانة المخزن وعناصر التحكم في القرص

تحتوي استدامة الجلسات على عناصر تحكم تلقائية للصيانة (`session.maintenance`) تخص `sessions.json` وعناصر النصوص المفرغة:

- `mode`: إما `warn` (الافتراضي) أو `enforce`
- `pruneAfter`: حد عمر الإدخالات القديمة (الافتراضي `30d`)
- `maxEntries`: حد أقصى للإدخالات في `sessions.json` (الافتراضي `500`)
- `rotateBytes`: تدوير `sessions.json` عند تجاوزه الحجم المسموح (الافتراضي `10mb`)
- `resetArchiveRetention`: مدة الاحتفاظ بأرشيفات النصوص المفرغة `*.reset.<timestamp>` (الافتراضي: نفس `pruneAfter`؛ و`false` يعطّل التنظيف)
- `maxDiskBytes`: ميزانية اختيارية لدليل الجلسات
- `highWaterBytes`: هدف اختياري بعد التنظيف (الافتراضي `80%` من `maxDiskBytes`)

ترتيب التنفيذ لتنظيف ميزانية القرص (`mode: "enforce"`):

1. إزالة أقدم عناصر أرشيف النصوص المفرغة أو العناصر اليتيمة أولًا.
2. إذا بقي الاستخدام فوق الهدف، تُزال أقدم إدخالات الجلسات وملفات نصوصها المفرغة.
3. يستمر ذلك حتى يصبح الاستخدام عند `highWaterBytes` أو دونه.

في وضع `mode: "warn"`، يبلّغ OpenClaw عن عمليات الإزالة المحتملة لكنه لا يغيّر المخزن أو الملفات.

شغّل الصيانة عند الطلب:

```bash
openclaw sessions cleanup --dry-run
openclaw sessions cleanup --enforce
```

---

## جلسات Cron وسجلات التشغيل

تنشئ تشغيلات Cron المعزولة أيضًا إدخالات/نصوصًا مفرغة للجلسات، ولها عناصر تحكم مخصصة للاحتفاظ:

- `cron.sessionRetention` (الافتراضي `24h`) يزيل جلسات تشغيل Cron المعزولة القديمة من مخزن الجلسات (`false` يعطّل ذلك).
- `cron.runLog.maxBytes` + `cron.runLog.keepLines` يشذّبان ملفات `~/.openclaw/cron/runs/<jobId>.jsonl` (الافتراضيات: `2_000_000` بايت و`2000` سطر).

عندما ينشئ Cron بالقوة جلسة تشغيل معزولة جديدة، فإنه ينقّي إدخال
الجلسة السابق `cron:<jobId>` قبل كتابة الصف الجديد. ويحمل التفضيلات
الآمنة مثل إعدادات التفكير/السريع/المفصل، والتسميات، وتجاوزات
النموذج/المصادقة الصريحة التي اختارها المستخدم. ويسقط سياق المحادثة المحيط مثل
توجيه القناة/المجموعة، أو سياسة الإرسال أو الانتظار، أو التصعيد، أو الأصل، أو ربط Runtime الخاص بـ ACP حتى لا ترث عملية تشغيل جديدة معزولة
صلاحيات تسليم أو Runtime قديمة من تشغيل أقدم.

---

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

يحدد `sessionKey` _حاوية المحادثة التي أنت فيها_ (التوجيه + العزل).

الأنماط الشائعة:

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

القواعد الأساسية موثقة في [/concepts/session](/ar/concepts/session).

---

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

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

قواعد عامة:

- **إعادة التعيين** (`/new`، `/reset`) تنشئ `sessionId` جديدًا لذلك `sessionKey`.
- **إعادة التعيين اليومية** (افتراضيًا 4:00 صباحًا بالتوقيت المحلي على مضيف Gateway) تنشئ `sessionId` جديدًا عند الرسالة التالية بعد حد إعادة التعيين.
- **انتهاء المهلة بسبب الخمول** (`session.reset.idleMinutes` أو القديمة `session.idleMinutes`) تنشئ `sessionId` جديدًا عندما تصل رسالة بعد نافذة الخمول. وعند ضبط الإعادة اليومية والخمول معًا، يفوز أيهما ينتهي أولًا.
- **أحداث النظام** (Heartbeat، وتنبيهات Cron، وإشعارات التنفيذ، وأعمال Gateway التنظيمية) قد تغيّر صف الجلسة لكنها لا تمدد حداثة إعادة التعيين اليومية/بسبب الخمول. ويؤدي تدوير إعادة التعيين إلى إسقاط إشعارات أحداث النظام الموضوعة في الطابور للجلسة السابقة قبل بناء الموجه الجديد.
- **حارس تشعب الأصل في الخيط** (`session.parentForkMaxTokens`، الافتراضي `100000`) يتجاوز تشعيب النص المفرغ الأصل عندما تكون الجلسة الأصلية كبيرة جدًا بالفعل؛ وتبدأ الجلسة الجديدة من جديد. اضبطه إلى `0` لتعطيله.

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

---

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

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

حقول أساسية (ليست شاملة):

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

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

---

## بنية النص المفرغ (`*.jsonl`)

تُدار النصوص المفرغة بواسطة `SessionManager` من `@mariozechner/pi-coding-agent`.

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

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

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

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

يتعمد OpenClaw **ألا** «يصلح» النصوص المفرغة؛ إذ تستخدم Gateway `SessionManager` لقراءتها وكتابتها.

---

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

توجد هنا فكرتان مختلفتان مهمتان:

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

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

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

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

---

## Compaction: ما هي

تلخّص Compaction المحادثة الأقدم في إدخال `compaction` محفوظ داخل النص المفرغ، وتُبقي الرسائل الحديثة كما هي.

بعد Compaction، سترى الدورات المستقبلية:

- ملخص Compaction
- الرسائل بعد `firstKeptEntryId`

تُعد Compaction **مستمرة** (على عكس تشذيب الجلسات). راجع [/concepts/session-pruning](/ar/concepts/session-pruning).

## حدود مقاطع Compaction واقتران الأدوات

عندما يقسم OpenClaw نصًا مفرغًا طويلًا إلى مقاطع Compaction، فإنه يُبقي
استدعاءات أدوات المساعد مقترنة بإدخالات `toolResult` المطابقة لها.

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

---

## متى تحدث Compaction التلقائية (Pi runtime)

في وكيل Pi المضمّن، يتم تشغيل Compaction التلقائية في حالتين:

1. **التعافي من الفائض**: يعيد النموذج خطأ فائض في السياق
   (`request_too_large`، أو `context length exceeded`، أو `input exceeds the maximum
number of tokens`، أو `input token count exceeds the maximum number of input
tokens`، أو `input is too long for the model`، أو `ollama error: context length
exceeded`، وأشكالًا مماثلة بحسب المزوّد) ← تنفيذ Compaction ← إعادة المحاولة.
2. **صيانة العتبة**: بعد دورة ناجحة، عندما:

`contextTokens > contextWindow - reserveTokens`

حيث:

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

هذه دلالات Pi runtime (يستهلك OpenClaw الأحداث، لكن Pi هو من يقرر متى ينفذ Compaction).

---

## إعدادات Compaction (`reserveTokens`، `keepRecentTokens`)

توجد إعدادات Compaction في Pi ضمن إعدادات Pi:

```json5
{
  compaction: {
    enabled: true,
    reserveTokens: 16384,
    keepRecentTokens: 20000,
  },
}
```

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

- إذا كانت `compaction.reserveTokens < reserveTokensFloor`، فإن OpenClaw يرفعها.
- الحد الأدنى الافتراضي هو `20000` رمز.
- اضبط `agents.defaults.compaction.reserveTokensFloor: 0` لتعطيل الحد الأدنى.
- إذا كانت أعلى بالفعل، فإن OpenClaw يتركها كما هي.
- يأخذ `/compact` اليدوي في الحسبان قيمة `agents.defaults.compaction.keepRecentTokens`
  الصريحة، ويُبقي نقطة قطع الذيل الحديث الخاصة بـ Pi. ومن دون ميزانية احتفاظ صريحة،
  تبقى Compaction اليدوية نقطة تحقق صارمة ويبدأ السياق المعاد بناؤه من
  الملخص الجديد.

السبب: ترك مساحة كافية لأعمال «ترتيب» متعددة الدورات (مثل كتابات الذاكرة) قبل أن تصبح Compaction حتمية.

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

---

## مزوّدو Compaction القابلون للتوصيل

يمكن لـ Plugins تسجيل مزوّد Compaction عبر `registerCompactionProvider()` على واجهة API الخاصة بـ Plugin. وعندما يتم ضبط `agents.defaults.compaction.provider` على معرّف مزوّد مسجّل، يفوّض امتداد safeguard التلخيص إلى ذلك المزوّد بدلًا من مسار `summarizeInStages` المضمّن.

- `provider`: معرّف مزوّد Compaction مسجّل من Plugin. اتركه غير مضبوط لاستخدام تلخيص LLM الافتراضي.
- يؤدي ضبط `provider` إلى فرض `mode: "safeguard"`.
- تتلقى المزوّدات تعليمات Compaction نفسها وسياسة الحفاظ على المعرّفات نفسها كما في المسار المضمّن.
- لا يزال safeguard يحتفظ بسياق لاحقة الدورات الحديثة والدورات المقسّمة بعد خرج المزوّد.
- يعيد تلخيص safeguard المضمّن تقطير الملخصات السابقة مع الرسائل الجديدة
  بدلًا من الحفاظ على الملخص السابق الكامل كما هو حرفيًا.
- يفعّل وضع safeguard تدقيقات جودة الملخص افتراضيًا؛ اضبط
  `qualityGuard.enabled: false` لتخطي سلوك إعادة المحاولة عند المخرجات غير السليمة.
- إذا فشل المزوّد أو أعاد نتيجة فارغة، فإن OpenClaw يرجع تلقائيًا إلى تلخيص LLM المضمّن.
- تُعاد إشارات الإجهاض/المهلة الزمنية على هيئة أخطاء كما هي (ولا يتم ابتلاعها) احترامًا لإلغاء المستدعي.

المصدر: `src/plugins/compaction-provider.ts`، `src/agents/pi-hooks/compaction-safeguard.ts`.

---

## الأسطح المرئية للمستخدم

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

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

---

## أعمال الترتيب الصامتة (`NO_REPLY`)

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

الاصطلاح:

- يبدأ المساعد خرجه برمز الصمت الدقيق `NO_REPLY` /
  `no_reply` للدلالة على «لا تُسلّم ردًا إلى المستخدم».
- يزيل OpenClaw هذا في طبقة التسليم أو يكبته.
- إن كبت رمز الصمت الدقيق غير حساس لحالة الأحرف، لذا يُحتسب كل من `NO_REPLY` و
  `no_reply` عندما تكون الحمولة كلها هي رمز الصمت فقط.
- هذا مخصّص للدورات الخلفية الحقيقية/من دون تسليم فقط؛ وليس اختصارًا
  لطلبات المستخدم العادية القابلة للتنفيذ.

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

---

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

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

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

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

الإعدادات (`agents.defaults.compaction.memoryFlush`):

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

ملاحظات:

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

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

---

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

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

## ذو صلة

- [إدارة الجلسات](/ar/concepts/session)
- [تشذيب الجلسات](/ar/concepts/session-pruning)
- [محرك السياق](/ar/concepts/context-engine)
