---
read_when:
    - باید شناسه‌های جلسه، JSONL رونوشت یا فیلدهای sessions.json را اشکال‌زدایی کنید
    - شما در حال تغییر رفتار Compaction خودکار یا افزودن خانه‌داری «پیش از Compaction» هستید
    - می‌خواهید تخلیه‌های حافظه یا نوبت‌های سیستمی بی‌صدا را پیاده‌سازی کنید
summary: 'بررسی عمیق: انبار نشست + رونوشت‌ها، چرخهٔ حیات، و سازوکارهای داخلی Compaction (خودکار)'
title: نگاه عمیق به مدیریت نشست
x-i18n:
    generated_at: "2026-06-27T18:50:07Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 7d4b6195c54024a8c0096ec2462ba367dbb6e16a8f6e10f2f912b879848c65af
    source_path: reference/session-management-compaction.md
    workflow: 16
---

OpenClaw نشست‌ها را از ابتدا تا انتها در این بخش‌ها مدیریت می‌کند:

- **مسیریابی نشست** (اینکه پیام‌های ورودی چگونه به یک `sessionKey` نگاشت می‌شوند)
- **ذخیره‌گاه نشست** (`sessions.json`) و چیزهایی که ردیابی می‌کند
- **ماندگاری رونوشت** (`*.jsonl`) و ساختار آن
- **بهداشت رونوشت** (اصلاحات ویژه ارائه‌دهنده پیش از اجراها)
- **محدودیت‌های زمینه** (پنجره زمینه در برابر توکن‌های ردیابی‌شده)
- **Compaction** (Compaction دستی و خودکار) و محل اتصال کارهای پیش از Compaction
- **خانه‌داری بی‌صدا** (نوشتن‌های حافظه که نباید خروجی قابل مشاهده برای کاربر تولید کنند)

اگر ابتدا نمای کلی سطح بالاتری می‌خواهید، از اینجا شروع کنید:

- [مدیریت نشست](/fa/concepts/session)
- [Compaction](/fa/concepts/compaction)
- [نمای کلی حافظه](/fa/concepts/memory)
- [جستجوی حافظه](/fa/concepts/memory-search)
- [هرس نشست](/fa/concepts/session-pruning)
- [بهداشت رونوشت](/fa/reference/transcript-hygiene)

---

## منبع حقیقت: Gateway

OpenClaw پیرامون یک **فرایند Gateway** واحد طراحی شده است که مالک وضعیت نشست است.

- رابط‌های کاربری (برنامه macOS، رابط کاربری وب Control، TUI) باید برای فهرست نشست‌ها و شمارش توکن‌ها از Gateway پرس‌وجو کنند.
- در حالت راه‌دور، فایل‌های نشست روی میزبان راه‌دور هستند؛ «بررسی فایل‌های محلی Mac خودتان» چیزی را که Gateway استفاده می‌کند بازتاب نمی‌دهد.

---

## دو لایه ماندگاری

OpenClaw نشست‌ها را در دو لایه پایدار می‌کند:

1. **ذخیره‌گاه نشست (`sessions.json`)**
   - نگاشت کلید/مقدار: `sessionKey -> SessionEntry`
   - کوچک، قابل تغییر، و ایمن برای ویرایش (یا حذف ورودی‌ها)
   - فراداده نشست را ردیابی می‌کند (شناسه نشست فعلی، آخرین فعالیت، کلیدهای تغییر وضعیت، شمارنده‌های توکن، و غیره)

2. **رونوشت (`<sessionId>.jsonl`)**
   - رونوشت فقط-افزودنی با ساختار درختی (ورودی‌ها `id` + `parentId` دارند)
   - گفت‌وگوی واقعی + فراخوانی‌های ابزار + خلاصه‌های Compaction را ذخیره می‌کند
   - برای بازسازی زمینه مدل در نوبت‌های آینده استفاده می‌شود
   - نقاط وارسی Compaction فراداده‌ای روی رونوشت جانشین فشرده‌شده هستند.
     Compactionهای جدید یک نسخه دوم `.checkpoint.*.jsonl`
     نمی‌نویسند.

خواننده‌های تاریخچه Gateway باید از مادی‌سازی کل رونوشت خودداری کنند مگر اینکه
سطح مربوطه صراحتا به دسترسی دلخواه به تاریخچه نیاز داشته باشد. تاریخچه صفحه اول،
تاریخچه چت جاسازی‌شده، بازیابی پس از راه‌اندازی دوباره، و بررسی‌های توکن/مصرف از خواندن‌های دنباله‌ای محدود استفاده می‌کنند. پویش‌های کامل رونوشت از طریق نمایه ناهمگام رونوشت انجام می‌شوند که
بر اساس مسیر فایل به‌علاوه `mtimeMs`/`size` کش می‌شود و میان خواننده‌های هم‌زمان مشترک است.

---

## مکان‌های روی دیسک

به‌ازای هر عامل، روی میزبان 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`: `enforce` (پیش‌فرض) یا `warn`
- `pruneAfter`: آستانه سن ورودی‌های کهنه (پیش‌فرض `30d`)
- `maxEntries`: سقف ورودی‌ها در `sessions.json` (پیش‌فرض `500`)
- نگهداری کاوش کوتاه‌عمر اجرای مدل Gateway روی `24h` ثابت است، اما با فشار کنترل می‌شود: فقط زمانی ردیف‌های کاوش سخت‌گیرانه کهنه را حذف می‌کند که فشار نگهداری/سقف ورودی نشست رسیده باشد. این فقط برای کلیدهای کاوش صریح سخت‌گیرانه مطابق با `agent:*:explicit:model-run-<uuid>` اعمال می‌شود و هنگام اجرا، پیش از پاک‌سازی/سقف‌گذاری سراسری ورودی‌های کهنه اجرا می‌شود.
- `resetArchiveRetention`: نگهداری برای آرشیوهای رونوشت `*.reset.<timestamp>` (پیش‌فرض: همان `pruneAfter`؛ مقدار `false` پاک‌سازی را غیرفعال می‌کند)
- `maxDiskBytes`: بودجه اختیاری دایرکتوری نشست‌ها
- `highWaterBytes`: هدف اختیاری پس از پاک‌سازی (پیش‌فرض `80%` از `maxDiskBytes`)

نوشتن‌های عادی Gateway از یک نویسنده نشست به‌ازای هر ذخیره‌گاه عبور می‌کنند که جهش‌های درون‌فرایندی را بدون گرفتن قفل فایل زمان اجرا سریالی می‌کند. کمک‌گرهای وصله مسیر داغ، تا وقتی اسلات آن نویسنده را نگه داشته‌اند، کش قابل تغییر اعتبارسنجی‌شده را قرض می‌گیرند، بنابراین فایل‌های بزرگ `sessions.json` برای هر به‌روزرسانی فراداده کپی یا دوباره خوانده نمی‌شوند. کد زمان اجرا باید `updateSessionStore(...)` یا `updateSessionStoreEntry(...)` را ترجیح دهد؛ ذخیره‌های مستقیم کل ذخیره‌گاه ابزارهای سازگاری و نگهداری آفلاین هستند. وقتی یک Gateway در دسترس است، `openclaw sessions cleanup` و `openclaw agents delete` غیر dry-run جهش‌های ذخیره‌گاه را به Gateway واگذار می‌کنند تا پاک‌سازی به همان صف نویسنده بپیوندد؛ `--store <path>` مسیر صریح تعمیر آفلاین برای نگهداری مستقیم فایل است. پاک‌سازی `maxEntries` هنوز برای سقف‌های در اندازه تولید به‌صورت دسته‌ای انجام می‌شود، بنابراین یک ذخیره‌گاه ممکن است برای مدت کوتاهی از سقف پیکربندی‌شده فراتر رود تا پاک‌سازی high-water بعدی آن را دوباره کاهش دهد. خواندن‌های ذخیره‌گاه نشست هنگام راه‌اندازی Gateway ورودی‌ها را هرس یا سقف‌گذاری نمی‌کنند؛ برای پاک‌سازی از نوشتن‌ها یا `openclaw sessions cleanup --enforce` استفاده کنید. `openclaw sessions cleanup --enforce` همچنان سقف پیکربندی‌شده را بی‌درنگ اعمال می‌کند و مصنوعات قدیمی و ارجاع‌نشده رونوشت، نقطه وارسی، و مسیر اجرا را حتی وقتی بودجه دیسک پیکربندی نشده باشد هرس می‌کند.

نگهداری اشاره‌گرهای بادوام گفت‌وگوی خارجی مانند نشست‌های گروهی
و نشست‌های چت محدود به رشته را حفظ می‌کند، اما ورودی‌های مصنوعی زمان اجرا برای Cron، قلاب‌ها،
Heartbeat، ACP، و زیرعامل‌ها همچنان می‌توانند وقتی از سن،
تعداد، یا بودجه دیسک پیکربندی‌شده فراتر می‌روند حذف شوند. نشست‌های کاوش اجرای مدل Gateway فقط وقتی کلیدشان دقیقا با
`agent:*:explicit:model-run-<uuid>` مطابقت داشته باشد از نگهداری جداگانه اجرای مدل `24h` استفاده می‌کنند؛ نشست‌های صریح دیگر بخشی از
آن نگهداری نیستند. پاک‌سازی اجرای مدل فقط تحت فشار سقف ورودی نشست
اعمال می‌شود. اجراهای Cron ایزوله کنترل `cron.sessionRetention` خودشان را نگه می‌دارند،
مستقل از نگهداری کاوش اجرای مدل.

OpenClaw دیگر هنگام نوشتن‌های Gateway پشتیبان‌گیری‌های چرخشی خودکار `sessions.json.bak.*` ایجاد نمی‌کند. کلید قدیمی `session.maintenance.rotateBytes` نادیده گرفته می‌شود و `openclaw doctor --fix` آن را از پیکربندی‌های قدیمی‌تر حذف می‌کند.

جهش‌های رونوشت از قفل نوشتن نشست روی فایل رونوشت استفاده می‌کنند. گرفتن قفل تا
`session.writeLock.acquireTimeoutMs` صبر می‌کند و سپس خطای نشست مشغول را نشان می‌دهد؛ پیش‌فرض `60000`
میلی‌ثانیه است. این مقدار را فقط وقتی افزایش دهید که آماده‌سازی، پاک‌سازی، Compaction، یا کار آینه‌سازی رونوشت مشروع روی ماشین‌های کند
بیشتر رقابت می‌کند. `session.writeLock.staleMs` کنترل می‌کند چه زمانی یک قفل موجود می‌تواند به‌عنوان کهنه
بازپس‌گرفته شود؛ پیش‌فرض `1800000` میلی‌ثانیه است. `session.writeLock.maxHoldMs` آستانه آزادسازی دیده‌بان درون‌فرایندی را کنترل می‌کند؛ پیش‌فرض `300000` میلی‌ثانیه است. بازنویسی‌های اضطراری env عبارت‌اند از
`OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS`، `OPENCLAW_SESSION_WRITE_LOCK_STALE_MS`، و
`OPENCLAW_SESSION_WRITE_LOCK_MAX_HOLD_MS`.

ترتیب اعمال پاک‌سازی بودجه دیسک (`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.keepLines` ردیف‌های نگه‌داشته‌شده تاریخچه اجرای SQLite را به‌ازای هر کار Cron هرس می‌کند (پیش‌فرض: `2000`). `cron.runLog.maxBytes` همچنان برای گزارش‌های اجرای قدیمی‌تر مبتنی بر فایل پذیرفته می‌شود.

وقتی Cron به‌اجبار یک نشست اجرای ایزوله جدید ایجاد می‌کند، ورودی نشست قبلی
`cron:<jobId>` را پیش از نوشتن ردیف جدید پاک‌سازی می‌کند. ترجیحات امن
مانند تنظیمات thinking/fast/verbose، برچسب‌ها، و بازنویسی‌های صریح
مدل/احراز هویت انتخاب‌شده توسط کاربر را حمل می‌کند. زمینه محیطی گفت‌وگو مانند
مسیریابی کانال/گروه، سیاست ارسال یا صف، ارتقا، مبدا، و اتصال زمان اجرای ACP را حذف می‌کند
تا یک اجرای ایزوله تازه نتواند تحویل کهنه یا
اختیار زمان اجرا را از اجرای قدیمی‌تر به ارث ببرد.

---

## کلیدهای نشست (`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](/fa/concepts/session) مستند شده‌اند.

---

## شناسه‌های نشست (`sessionId`)

هر `sessionKey` به یک `sessionId` فعلی اشاره می‌کند (فایل رونوشت که گفت‌وگو را ادامه می‌دهد).

قواعد کلی:

- **بازنشانی** (`/new`، `/reset`) برای آن `sessionKey` یک `sessionId` جدید ایجاد می‌کند.
- **بازنشانی روزانه** (پیش‌فرض ساعت 4:00 صبح به وقت محلی روی میزبان Gateway) در پیام بعدی پس از مرز بازنشانی، یک `sessionId` جدید ایجاد می‌کند.
- **انقضای بیکاری** (`session.reset.idleMinutes` یا `session.idleMinutes` قدیمی) وقتی پیامی پس از پنجره بیکاری برسد یک `sessionId` جدید ایجاد می‌کند. وقتی هر دو مورد روزانه + بیکاری پیکربندی شده باشند، هرکدام زودتر منقضی شود برنده است.
- **ازسرگیری پس از اتصال دوباره Control UI** می‌تواند نشست فعلا قابل مشاهده را برای یک ارسال اتصال دوباره حفظ کند وقتی Gateway، `sessionId` مطابق را از یک کلاینت رابط کاربری اپراتور دریافت کند. ارسال‌های کهنه عادی همچنان یک `sessionId` جدید ایجاد می‌کنند.
- **رویدادهای سیستمی** (Heartbeat، بیدارباش‌های Cron، اعلان‌های exec، دفترگردانی Gateway) ممکن است ردیف نشست را تغییر دهند اما تازگی بازنشانی روزانه/بیکاری را تمدید نمی‌کنند. چرخش بازنشانی، اعلان‌های رویداد سیستمی صف‌شده برای نشست قبلی را پیش از ساخت prompt تازه دور می‌اندازد.
- **سیاست fork والد** هنگام ایجاد یک رشته یا fork زیرعامل از شاخه فعال OpenClaw استفاده می‌کند. اگر آن شاخه بیش از حد بزرگ باشد، OpenClaw فرزند را به‌جای شکست خوردن یا به‌ارث‌بردن تاریخچه غیرقابل استفاده، با زمینه ایزوله آغاز می‌کند. سیاست اندازه‌گذاری خودکار است؛ پیکربندی قدیمی `session.parentForkMaxTokens` توسط `openclaw doctor --fix` حذف می‌شود.

جزئیات پیاده‌سازی: تصمیم در `initSessionState()` در `src/auto-reply/reply/session.ts` انجام می‌شود.

---

## طرح‌واره ذخیره‌گاه نشست (`sessions.json`)

نوع مقدار ذخیره‌گاه `SessionEntry` در `src/config/sessions.ts` است.

فیلدهای کلیدی (غیرجامع):

- `sessionId`: شناسه رونوشت فعلی (نام فایل از این مشتق می‌شود مگر اینکه `sessionFile` تنظیم شده باشد)
- `sessionStartedAt`: مُهرزمان شروع برای `sessionId` فعلی؛ تازگی بازنشانی روزانه
  از این استفاده می‌کند. ردیف‌های قدیمی ممکن است آن را از سرآیند نشست JSONL مشتق کنند.
- `lastInteractionAt`: مُهرزمان آخرین تعامل واقعی کاربر/کانال؛ تازگی بازنشانی بیکاری
  از این استفاده می‌کند تا رویدادهای Heartbeat، Cron، و exec نشست‌ها را
  زنده نگه ندارند. ردیف‌های قدیمی بدون این فیلد برای تازگی بیکاری به زمان شروع نشست بازیابی‌شده
  بازمی‌گردند.
- `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`: مُهرزمان آخرین flush حافظه پیش از Compaction
- `memoryFlushCompactionCount`: شمار Compaction هنگام اجرای آخرین flush

ویرایش ذخیره‌گاه ایمن است، اما Gateway مرجع است: ممکن است هنگام اجرای نشست‌ها ورودی‌ها را دوباره بنویسد یا بازآب‌رسانی کند.

---

## ساختار رونوشت (`*.jsonl`)

رونوشت‌ها توسط `SessionManager` متعلق به `openclaw/plugin-sdk/agent-sessions` مدیریت می‌شوند.

فایل JSONL است:

- خط اول: سرآیند نشست (`type: "session"`، شامل `id`، `cwd`، `timestamp`، `parentSession` اختیاری)
- سپس: ورودی‌های نشست با `id` + `parentId` (درخت)

انواع ورودی قابل توجه:

- `message`: پیام‌های کاربر/دستیار/نتیجهٔ ابزار
- `custom_message`: پیام‌های تزریق‌شده توسط افزونه که وارد بافت مدل _می‌شوند_ (می‌توانند از UI پنهان باشند)
- `custom`: وضعیت افزونه که وارد بافت مدل _نمی‌شود_
- `compaction`: خلاصهٔ Compaction پایدارشده با `firstKeptEntryId` و `tokensBefore`
- `branch_summary`: خلاصهٔ پایدارشده هنگام پیمایش یک شاخهٔ درخت

OpenClaw عمداً transcriptها را «اصلاح» نمی‌کند؛ Gateway از `SessionManager` برای خواندن/نوشتن آن‌ها استفاده می‌کند.

---

## پنجره‌های بافت در برابر توکن‌های ردیابی‌شده

دو مفهوم متفاوت مهم هستند:

1. **پنجرهٔ بافت مدل**: سقف سخت برای هر مدل (توکن‌هایی که برای مدل قابل مشاهده‌اند)
2. **شمارنده‌های ذخیره‌گاه نشست**: آمار چرخشی نوشته‌شده در `sessions.json` (برای /status و داشبوردها استفاده می‌شود)

اگر در حال تنظیم محدودیت‌ها هستید:

- پنجرهٔ بافت از کاتالوگ مدل می‌آید (و می‌تواند از طریق پیکربندی override شود).
- `contextTokens` در ذخیره‌گاه یک مقدار تخمینی/گزارشی زمان اجرا است؛ آن را تضمین سخت‌گیرانه تلقی نکنید.

برای اطلاعات بیشتر، [/token-use](/fa/reference/token-use) را ببینید.

---

## Compaction: چیست

Compaction گفت‌وگوی قدیمی‌تر را در یک ورودی پایدارشدهٔ `compaction` در transcript خلاصه می‌کند و پیام‌های اخیر را دست‌نخورده نگه می‌دارد.

پس از Compaction، نوبت‌های آینده این‌ها را می‌بینند:

- خلاصهٔ Compaction
- پیام‌های پس از `firstKeptEntryId`

تزریق دوبارهٔ بخش AGENTS.md پس از Compaction از طریق
`agents.defaults.compaction.postCompactionSections` اختیاری است؛ وقتی تنظیم نشده یا `[]` باشد،
OpenClaw گزیده‌های AGENTS.md را روی خلاصهٔ Compaction اضافه نمی‌کند.

Compaction **پایدار** است (برخلاف هرس نشست). [/concepts/session-pruning](/fa/concepts/session-pruning) را ببینید.

## مرزهای قطعهٔ Compaction و جفت‌سازی ابزار

وقتی OpenClaw یک transcript طولانی را به قطعه‌های Compaction تقسیم می‌کند، فراخوانی‌های ابزار دستیار را با ورودی‌های `toolResult` متناظرشان جفت نگه می‌دارد.

- اگر تقسیم بر اساس سهم توکن بین یک فراخوانی ابزار و نتیجهٔ آن بیفتد، OpenClaw
  به‌جای جدا کردن جفت، مرز را به پیام فراخوانی ابزار دستیار منتقل می‌کند.
- اگر یک بلوک نتیجهٔ ابزار پایانی در غیر این صورت قطعه را از هدف عبور دهد،
  OpenClaw آن بلوک ابزار معلق را حفظ می‌کند و دُم خلاصه‌نشده را دست‌نخورده نگه می‌دارد.
- بلوک‌های فراخوانی ابزار لغوشده/خطادار یک تقسیم معلق را باز نگه نمی‌دارند.

---

## چه زمانی auto-compaction رخ می‌دهد (زمان اجرای OpenClaw)

در عامل تعبیه‌شدهٔ OpenClaw، auto-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`، و گونه‌های مشابه با شکل ارائه‌دهنده) → فشرده‌سازی → تلاش دوباره.
   وقتی ارائه‌دهنده تعداد توکن تلاش‌شده را گزارش می‌کند، OpenClaw آن شمارش
   مشاهده‌شده را به Compaction بازیابی سرریز ارسال می‌کند. اگر ارائه‌دهنده
   سرریز را تأیید کند اما شمارش قابل parse ارائه ندهد، OpenClaw یک شمارش
   ساختگی حداقلیِ کمی بیش از بودجه را به موتورهای Compaction و diagnostics می‌فرستد.
   اگر بازیابی سرریز همچنان شکست بخورد، OpenClaw راهنمایی صریح را به
   کاربر نمایش می‌دهد و به‌جای چرخاندن بی‌صدای کلید نشست به یک شناسهٔ نشست تازه،
   نگاشت نشست فعلی را حفظ می‌کند. گام بعدی در کنترل operator است:
   پیام را دوباره تلاش کنید، `/compact` را اجرا کنید، یا وقتی نشست تازه ترجیح داده می‌شود `/new` را اجرا کنید.
2. **نگهداری آستانه**: پس از یک نوبت موفق، وقتی:

`contextTokens > contextWindow - reserveTokens`

که در آن:

- `contextWindow` پنجرهٔ بافت مدل است
- `reserveTokens` فضای تنفسی ذخیره‌شده برای promptها + خروجی بعدی مدل است

این‌ها معناشناسی زمان اجرای OpenClaw هستند.

OpenClaw همچنین می‌تواند پیش از باز کردن اجرای بعدی، وقتی `agents.defaults.compaction.maxActiveTranscriptBytes` تنظیم شده و فایل transcript فعال به آن اندازه می‌رسد، یک Compaction محلی preflight فعال کند. این یک محافظ اندازهٔ فایل برای هزینهٔ بازگشایی محلی است، نه آرشیو خام: OpenClaw همچنان Compaction معنایی عادی را اجرا می‌کند، و به `truncateAfterCompaction` نیاز دارد تا خلاصهٔ فشرده‌شده بتواند به یک transcript جانشین تازه تبدیل شود.

برای اجراهای OpenClaw تعبیه‌شده، `agents.defaults.compaction.midTurnPrecheck.enabled: true`
یک محافظ حلقهٔ ابزار اختیاری اضافه می‌کند. پس از append شدن نتیجهٔ ابزار و پیش از
فراخوانی بعدی مدل، OpenClaw فشار prompt را با همان منطق بودجهٔ preflight که در شروع نوبت استفاده می‌شود تخمین می‌زند. اگر بافت دیگر جا نشود، محافظ داخل hook زمان اجرای OpenClaw یعنی `transformContext` فشرده‌سازی نمی‌کند. این محافظ یک سیگنال ساختاریافتهٔ mid-turn precheck بالا می‌آورد، ارسال prompt فعلی را متوقف می‌کند، و می‌گذارد حلقهٔ اجرای بیرونی از مسیر بازیابی موجود استفاده کند: وقتی کافی است نتایج ابزار بیش‌ازحد بزرگ را truncate کند، یا حالت Compaction پیکربندی‌شده را فعال کند و دوباره تلاش کند. این گزینه به‌صورت پیش‌فرض غیرفعال است و با هر دو حالت Compaction یعنی `default` و `safeguard` کار می‌کند، از جمله Compaction safeguard مبتنی بر ارائه‌دهنده.
این مستقل از `maxActiveTranscriptBytes` است: محافظ اندازهٔ بایت پیش از باز شدن یک نوبت اجرا می‌شود، در حالی که mid-turn precheck بعداً در حلقهٔ ابزار OpenClaw تعبیه‌شده و پس از append شدن نتایج ابزار جدید اجرا می‌شود.

---

## تنظیمات Compaction (`reserveTokens`, `keepRecentTokens`)

تنظیمات Compaction زمان اجرای OpenClaw در تنظیمات عامل قرار دارند:

```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` صریح را رعایت می‌کند
  و نقطهٔ برش دُم اخیر زمان اجرای OpenClaw را نگه می‌دارد. بدون بودجهٔ نگهداری صریح،
  Compaction دستی همچنان یک checkpoint سخت است و بافت بازسازی‌شده از
  خلاصهٔ جدید شروع می‌شود.
- برای اجرای precheck اختیاری حلقهٔ ابزار پس از نتایج ابزار جدید و پیش از فراخوانی بعدی مدل،
  `agents.defaults.compaction.midTurnPrecheck.enabled: true` را تنظیم کنید.
  این فقط یک trigger است؛ تولید خلاصه همچنان از مسیر Compaction پیکربندی‌شده استفاده می‌کند.
  این مستقل از `maxActiveTranscriptBytes` است، که یک محافظ اندازهٔ بایت transcript فعال در شروع نوبت است.
- `agents.defaults.compaction.maxActiveTranscriptBytes` را به یک مقدار بایتی یا
  رشته‌ای مانند `"20mb"` تنظیم کنید تا وقتی transcript فعال بزرگ می‌شود، پیش از یک نوبت
  Compaction محلی اجرا شود. این محافظ فقط وقتی فعال است که
  `truncateAfterCompaction` نیز فعال باشد. برای غیرفعال کردن، آن را تنظیم‌نشده بگذارید یا `0` قرار دهید.
- وقتی `agents.defaults.compaction.truncateAfterCompaction` فعال باشد،
  OpenClaw پس از Compaction، transcript فعال را به یک JSONL جانشین فشرده‌شده می‌چرخاند.
  کنش‌های checkpoint شاخه/بازیابی از همان جانشین فشرده‌شده استفاده می‌کنند؛
  فایل‌های checkpoint قدیمی پیش از Compaction تا وقتی ارجاع داده می‌شوند خواندنی می‌مانند.

دلیل: پیش از اجتناب‌ناپذیر شدن Compaction، فضای تنفسی کافی برای «خانه‌داری» چندنوبتی (مانند نوشتن‌های حافظه) باقی بماند.

پیاده‌سازی: `applyAgentCompactionSettingsFromConfig()` در `src/agents/agent-settings.ts`
(از مسیرهای نوبت embedded-runner و راه‌اندازی Compaction فراخوانی می‌شود).

---

## ارائه‌دهندگان Compaction قابل اتصال

Pluginها می‌توانند از طریق `registerCompactionProvider()` روی API افزونه، یک ارائه‌دهندهٔ Compaction ثبت کنند. وقتی `agents.defaults.compaction.provider` روی شناسهٔ یک ارائه‌دهندهٔ ثبت‌شده تنظیم شود، افزونهٔ safeguard خلاصه‌سازی را به‌جای pipeline داخلی `summarizeInStages` به آن ارائه‌دهنده واگذار می‌کند.

- `provider`: شناسهٔ یک Plugin ارائه‌دهندهٔ Compaction ثبت‌شده. برای خلاصه‌سازی LLM پیش‌فرض، تنظیم‌نشده بگذارید.
- تنظیم یک `provider` حالت `mode: "safeguard"` را اجباری می‌کند.
- ارائه‌دهندگان همان دستورالعمل‌های Compaction و سیاست حفظ شناسه را که مسیر داخلی دارد دریافت می‌کنند.
- safeguard همچنان پس از خروجی ارائه‌دهنده، بافت پسوند نوبت‌های اخیر و نوبت تقسیم‌شده را حفظ می‌کند.
- خلاصه‌سازی safeguard داخلی، خلاصه‌های قبلی را همراه با پیام‌های جدید
  دوباره تقطیر می‌کند، به‌جای اینکه کل خلاصهٔ قبلی را عیناً حفظ کند.
- حالت safeguard ممیزی‌های کیفیت خلاصه را به‌صورت پیش‌فرض فعال می‌کند؛ برای رد کردن رفتار تلاش دوباره هنگام خروجی بدشکل،
  `qualityGuard.enabled: false` را تنظیم کنید.
- اگر ارائه‌دهنده شکست بخورد یا نتیجهٔ خالی برگرداند، OpenClaw به‌صورت خودکار به خلاصه‌سازی LLM داخلی fallback می‌کند.
- سیگنال‌های abort/timeout دوباره پرتاب می‌شوند (بلعیده نمی‌شوند) تا لغو caller رعایت شود.

منبع: `src/plugins/compaction-provider.ts`, `src/agents/agent-hooks/compaction-safeguard.ts`.

---

## سطوح قابل مشاهده برای کاربر

می‌توانید Compaction و وضعیت نشست را از طریق این‌ها مشاهده کنید:

- `/status` (در هر نشست چت)
- `openclaw status` (CLI)
- `openclaw sessions` / `sessions --json`
- لاگ‌های Gateway (`pnpm gateway:watch` یا `openclaw logs --follow`): `embedded run auto-compaction start` + `complete`
- حالت verbose: `🧹 Auto-compaction complete` + شمارش Compaction

---

## خانه‌داری بی‌صدا (`NO_REPLY`)

OpenClaw از نوبت‌های «بی‌صدا» برای کارهای پس‌زمینه پشتیبانی می‌کند، جایی که کاربر نباید خروجی میانی را ببیند.

قرارداد:

- دستیار خروجی خود را با توکن بی‌صدای دقیق `NO_REPLY` /
  `no_reply` آغاز می‌کند تا نشان دهد «پاسخی به کاربر تحویل نده».
- OpenClaw این را در لایهٔ تحویل حذف/سرکوب می‌کند.
- سرکوب توکن بی‌صدای دقیق به بزرگی/کوچکی حروف حساس نیست، بنابراین وقتی کل payload فقط توکن بی‌صدا باشد، هم `NO_REPLY` و هم
  `no_reply` حساب می‌شوند.
- این فقط برای نوبت‌های واقعاً پس‌زمینه/بدون تحویل است؛ میان‌بری برای
  درخواست‌های عادی و قابل اقدام کاربر نیست.

از `2026.1.10`، OpenClaw همچنین وقتی یک
chunk جزئی با `NO_REPLY` شروع شود، **streaming پیش‌نویس/در حال تایپ** را سرکوب می‌کند، بنابراین عملیات بی‌صدا خروجی جزئی را در میانهٔ نوبت نشت نمی‌دهند.

---

## «flush حافظه» پیش از Compaction (پیاده‌سازی‌شده)

هدف: پیش از وقوع auto-compaction، یک نوبت عامل‌محور بی‌صدا اجرا شود که وضعیت پایدار را روی دیسک بنویسد (مثلاً `memory/YYYY-MM-DD.md` در workspace عامل) تا Compaction نتواند بافت حیاتی را پاک کند.

OpenClaw از رویکرد **flush پیش‌آستانه‌ای** استفاده می‌کند:

1. مصرف بافت نشست را پایش کنید.
2. وقتی از یک «آستانهٔ نرم» عبور کرد (پایین‌تر از آستانهٔ Compaction زمان اجرای OpenClaw)، یک دستور بی‌صدا
   «اکنون حافظه را بنویس» برای عامل اجرا کنید.
3. از توکن بی‌صدای دقیق `NO_REPLY` / `no_reply` استفاده کنید تا کاربر
   چیزی نبیند.

پیکربندی (`agents.defaults.compaction.memoryFlush`):

- `enabled` (پیش‌فرض: `true`)
- `model` (override اختیاری و دقیق ارائه‌دهنده/مدل برای نوبت flush، برای مثال `ollama/qwen3:8b`)
- `softThresholdTokens` (پیش‌فرض: `4000`)
- `prompt` (پیام کاربر برای نوبت flush)
- `systemPrompt` (prompt سیستمی اضافه که برای نوبت flush append می‌شود)

نکات:

- prompt/سیستم prompt پیش‌فرض شامل یک اشارهٔ `NO_REPLY` برای سرکوب
  تحویل است.
- وقتی `model` تنظیم شده باشد، نوبت flush از همان مدل استفاده می‌کند بدون اینکه زنجیرهٔ fallback نشست فعال را به ارث ببرد، بنابراین خانه‌داری فقط محلی به‌صورت بی‌صدا
  به یک مدل گفت‌وگوی پولی fallback نمی‌کند.
- flush یک بار در هر چرخهٔ Compaction اجرا می‌شود (در `sessions.json` ردیابی می‌شود).
- flush فقط برای نشست‌های OpenClaw تعبیه‌شده اجرا می‌شود (backendهای CLI آن را رد می‌کنند).
- وقتی workspace نشست فقط‌خواندنی باشد (`workspaceAccess: "ro"` یا `"none"`)، flush رد می‌شود.
- برای چیدمان فایل workspace و الگوهای نوشتن، [حافظه](/fa/concepts/memory) را ببینید.

OpenClaw همچنین یک hook به نام `session_before_compact` را در API افزونه exposed می‌کند، اما منطق flush خود OpenClaw امروز در سمت Gateway قرار دارد.

---

## چک‌لیست عیب‌یابی

- کلید نشست اشتباه است؟ با [/concepts/session](/fa/concepts/session) شروع کنید و `sessionKey` را در `/status` تأیید کنید.
- ناسازگاری ذخیره‌گاه و transcript؟ میزبان Gateway و مسیر ذخیره‌گاه را از `openclaw status` تأیید کنید.
- هرزنامهٔ Compaction؟ بررسی کنید:
  - پنجرهٔ بافت مدل (خیلی کوچک)
  - تنظیمات Compaction (`reserveTokens` بیش‌ازحد بالا برای پنجرهٔ مدل می‌تواند باعث Compaction زودتر شود)
  - بزرگ‌شدن نتیجهٔ ابزار: هرس نشست را فعال/تنظیم کنید
- نشت نوبت‌های بی‌صدا؟ تأیید کنید پاسخ با `NO_REPLY` شروع می‌شود (توکن دقیق، غیرحساس به بزرگی/کوچکی حروف) و روی buildی هستید که اصلاح سرکوب streaming را شامل می‌شود.

## مرتبط

- [مدیریت نشست](/fa/concepts/session)
- [هرس نشست](/fa/concepts/session-pruning)
- [موتور بافت](/fa/concepts/context-engine)