---
read_when:
    - باید شناسه‌های نشست، JSONL رونوشت، یا فیلدهای sessions.json را عیب‌یابی کنید
    - شما در حال تغییر رفتار auto-Compaction یا افزودن housekeeping «pre-Compaction» هستید
    - می‌خواهید پاک‌سازی‌های حافظه یا نوبت‌های سیستمی بی‌صدا را پیاده‌سازی کنید
summary: 'بررسی عمیق: ذخیره‌گاه نشست + رونوشت‌ها، چرخهٔ حیات، و سازوکارهای داخلی Compaction (خودکار)'
title: بررسی عمیق مدیریت نشست‌ها
x-i18n:
    generated_at: "2026-05-11T20:43:14Z"
    model: gpt-5.5
    provider: openai
    source_hash: 4ed30f6b1943b2ed5808c5ccdd593e6899e10fb7f75ff5911e6a9623a30ed6be
    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، رابط کنترل وب، TUI) باید فهرست نشست‌ها و شمار توکن‌ها را از Gateway پرس‌وجو کنند.
- در حالت راه‌دور، فایل‌های نشست روی میزبان راه‌دور هستند؛ «بررسی فایل‌های محلی Mac شما» آنچه Gateway استفاده می‌کند را بازتاب نمی‌دهد.

---

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

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

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

2. **رونوشت (`<sessionId>.jsonl`)**
   - رونوشت فقط-افزودنی با ساختار درختی (ورودی‌ها `id` + `parentId` دارند)
   - مکالمهٔ واقعی + فراخوانی‌های ابزار + خلاصه‌های 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`، مصنوعات رونوشت، و فایل‌های جانبی trajectory دارد:

- `mode`: `warn` (پیش‌فرض) یا `enforce`
- `pruneAfter`: آستانهٔ سن ورودی کهنه (پیش‌فرض `30d`)
- `maxEntries`: سقف ورودی‌ها در `sessions.json` (پیش‌فرض `500`)
- `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` همچنان سقف پیکربندی‌شده را فوراً اعمال می‌کند و مصنوعات رونوشت، نقطهٔ بازرسی، و trajectory قدیمیِ بدون ارجاع را حتی زمانی که بودجهٔ دیسک پیکربندی نشده باشد هرس می‌کند.

نگهداری، اشاره‌گرهای بادوام مکالمهٔ بیرونی مانند نشست‌های گروهی
و نشست‌های چت محدود به thread را نگه می‌دارد، اما ورودی‌های مصنوعی زمان اجرا برای Cron، hookها،
Heartbeat، ACP، و زیرعامل‌ها همچنان می‌توانند وقتی از سن، شمار، یا بودجهٔ دیسک
پیکربندی‌شده فراتر می‌روند حذف شوند.

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

جهش‌های رونوشت از قفل نوشتن نشست روی فایل رونوشت استفاده می‌کنند. گرفتن قفل تا
`session.writeLock.acquireTimeoutMs` صبر می‌کند و سپس خطای نشستِ مشغول را نشان می‌دهد؛ پیش‌فرض `60000`
میلی‌ثانیه است. فقط زمانی این مقدار را افزایش دهید که آماده‌سازی، پاک‌سازی، Compaction، یا کار mirror رونوشتِ مشروع روی ماشین‌های کند
برای مدت طولانی‌تری رقابت کند. تشخیص قفل کهنه و هشدارهای حداکثر زمان نگه‌داری، سیاست‌های جداگانه باقی می‌مانند.

ترتیب اعمال برای پاک‌سازی بودجهٔ دیسک (`mode: "enforce"`):

1. ابتدا قدیمی‌ترین مصنوعات آرشیوشده، رونوشت orphan، یا trajectory orphan را حذف کنید.
2. اگر هنوز بالاتر از هدف است، قدیمی‌ترین ورودی‌های نشست و فایل‌های رونوشت/trajectory آن‌ها را بیرون کنید.
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>` را پیش از نوشتن ردیف جدید پاک‌سازی می‌کند. ترجیحات امنی مانند تنظیمات
thinking/fast/verbose، برچسب‌ها، و overrideهای صریحِ انتخاب‌شده توسط کاربر برای مدل/auth را
همراه می‌برد. زمینهٔ محیطی مکالمه مانند مسیریابی کانال/گروه، سیاست ارسال یا صف،
elevation، origin، و اتصال زمان اجرای 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>` (مگر این‌که override شده باشد)

قواعد canonical در [/concepts/session](/fa/concepts/session) مستند شده‌اند.

---

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

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

قواعد کلی:

- **بازنشانی** (`/new`، `/reset`) برای آن `sessionKey` یک `sessionId` جدید ایجاد می‌کند.
- **بازنشانی روزانه** (پیش‌فرض ساعت 4:00 بامداد به وقت محلی روی میزبان gateway) در پیام بعدی پس از مرز بازنشانی یک `sessionId` جدید ایجاد می‌کند.
- **انقضای بی‌کاری** (`session.reset.idleMinutes` یا `session.idleMinutes` قدیمی) وقتی پیامی پس از پنجرهٔ بی‌کاری می‌رسد یک `sessionId` جدید ایجاد می‌کند. وقتی روزانه + بی‌کاری هر دو پیکربندی شده باشند، هرکدام زودتر منقضی شود برنده است.
- **رویدادهای سیستمی** (Heartbeat، بیدارباش‌های Cron، اعلان‌های exec، حسابداری gateway) ممکن است ردیف نشست را تغییر دهند اما تازگی بازنشانی روزانه/بی‌کاری را تمدید نمی‌کنند. rollover بازنشانی، اعلان‌های صف‌شدهٔ رویداد سیستمی برای نشست قبلی را پیش از ساخته‌شدن prompt تازه دور می‌ریزد.
- **سیاست fork والد** هنگام ایجاد یک thread یا fork زیرعامل از شاخهٔ فعال PI استفاده می‌کند. اگر آن شاخه بیش از حد بزرگ باشد، 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`: override اختیاری مسیر صریح رونوشت
- `chatType`: `direct | group | room` (به رابط‌های کاربری و سیاست ارسال کمک می‌کند)
- `provider`، `subject`، `room`، `space`، `displayName`: فراداده برای برچسب‌گذاری گروه/کانال
- تغییر وضعیت‌ها:
  - `thinkingLevel`، `verboseLevel`، `reasoningLevel`، `elevatedLevel`
  - `sendPolicy` (override به‌ازای نشست)
- انتخاب مدل:
  - `providerOverride`، `modelOverride`، `authProfileOverride`
- شمارنده‌های توکن (بهترین تلاش / وابسته به ارائه‌دهنده):
  - `inputTokens`، `outputTokens`، `totalTokens`، `contextTokens`
- `compactionCount`: این‌که auto-compaction چند بار برای این کلید نشست کامل شده است
- `memoryFlushAt`: برچسب زمانی آخرین flush حافظه پیش از Compaction
- `memoryFlushCompactionCount`: شمار Compaction هنگامی که آخرین flush اجرا شد

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

---

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

رونوشت‌ها توسط `SessionManager` متعلق به `@earendil-works/pi-coding-agent` مدیریت می‌شوند.

فایل JSONL است:

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

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

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

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

---

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

دو مفهوم متفاوت اهمیت دارند:

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

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

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

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

---

## Compaction: چیست

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

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

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

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

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

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

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

---

## زمان رخ دادن Compaction خودکار (زمان اجرای Pi)

در عامل 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`، و گونه‌های مشابه با شکل ارائه‌دهنده) → compact → retry.
2. **نگه‌داری آستانه**: پس از یک نوبت موفق، وقتی:

`contextTokens > contextWindow - reserveTokens`

که در آن:

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

این‌ها معناشناسی زمان اجرای Pi هستند (OpenClaw رویدادها را مصرف می‌کند، اما Pi تصمیم می‌گیرد چه زمانی compact کند).

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

برای اجراهای Pi تعبیه‌شده، `agents.defaults.compaction.midTurnPrecheck.enabled: true` یک محافظ چرخه ابزار اختیاری اضافه می‌کند. پس از پیوست شدن نتیجه ابزار و پیش از فراخوانی بعدی مدل، OpenClaw فشار پرامپت را با همان منطق بودجه پیش‌پرواز که در شروع نوبت استفاده می‌شود تخمین می‌زند. اگر زمینه دیگر جا نشود، محافظ درون هوک `transformContext` مربوط به Pi compact نمی‌کند. یک سیگنال ساختاریافته پیش‌بررسی میانه نوبت صادر می‌کند، ارسال پرامپت فعلی را متوقف می‌کند، و به چرخه اجرای بیرونی اجازه می‌دهد از مسیر بازیابی موجود استفاده کند: وقتی کافی باشد نتایج ابزار بیش‌ازحد بزرگ را کوتاه کند، یا حالت Compaction پیکربندی‌شده را فعال و دوباره تلاش کند. این گزینه به‌طور پیش‌فرض غیرفعال است و با هر دو حالت Compaction یعنی `default` و `safeguard` کار می‌کند، از جمله Compaction محافظتی مبتنی بر ارائه‌دهنده.
این مستقل از `maxActiveTranscriptBytes` است: محافظ اندازه برحسب بایت پیش از باز شدن یک نوبت اجرا می‌شود، در حالی که پیش‌بررسی میانه نوبت بعدتر در چرخه ابزار Pi تعبیه‌شده و پس از پیوست شدن نتایج ابزار جدید اجرا می‌شود.

---

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

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

پیاده‌سازی: `ensurePiCompactionReserveTokens()` در `src/agents/pi-settings.ts`
(فراخوانی‌شده از `src/agents/pi-embedded-runner.ts`).

---

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

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

- `provider`: شناسه یک Plugin ارائه‌دهنده Compaction ثبت‌شده. برای خلاصه‌سازی LLM پیش‌فرض تنظیم‌نشده رها کنید.
- تنظیم یک `provider` حالت `mode: "safeguard"` را اجباری می‌کند.
- ارائه‌دهندگان همان دستورالعمل‌های Compaction و سیاست حفظ شناسه را که مسیر داخلی دریافت می‌کند، دریافت می‌کنند.
- محافظ همچنان زمینه پسوند نوبت‌های اخیر و نوبت‌های تقسیم‌شده را پس از خروجی ارائه‌دهنده حفظ می‌کند.
- خلاصه‌سازی محافظتی داخلی خلاصه‌های قبلی را همراه با پیام‌های جدید دوباره تقطیر می‌کند
  به‌جای اینکه کل خلاصه قبلی را عیناً حفظ کند.
- حالت محافظتی ممیزی‌های کیفیت خلاصه را به‌طور پیش‌فرض فعال می‌کند؛ برای رد کردن رفتار تلاش دوباره هنگام خروجی بدشکل، `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`
- لاگ‌های Gateway (`pnpm gateway:watch` یا `openclaw logs --follow`): `embedded run auto-compaction start` + `complete`
- حالت پرجزئیات: `🧹 Auto-compaction complete` + شمار Compaction

---

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

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

قرارداد:

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

از `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`)
- `model` (بازنویسی اختیاری و دقیق ارائه‌دهنده/مدل برای نوبت تخلیه، برای مثال `ollama/qwen3:8b`)
- `softThresholdTokens` (پیش‌فرض: `4000`)
- `prompt` (پیام کاربر برای نوبت تخلیه)
- `systemPrompt` (پرامپت سیستمی اضافی پیوست‌شده برای نوبت تخلیه)

نکته‌ها:

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

Pi همچنین یک هوک `session_before_compact` را در API افزونه ارائه می‌کند، اما منطق تخلیه OpenClaw امروز در سمت Gateway قرار دارد.

---

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

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

## مرتبط

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