بررسی عمیق مدیریت نشست

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

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

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

• مدیریت نشست
• Compaction
• نمای کلی حافظه
• جست‌وجوی حافظه
• هرس نشست
• بهداشت رونوشت

---

# منبع حقیقت: 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 حل می‌کند.

---

# نگهداشت ذخیره‌گاه و کنترل‌های دیسک

ماندگاری نشست برای sessions.json، مصنوعات رونوشت، و فایل‌های جانبی trajectory کنترل‌های نگهداشت خودکار (session.maintenance) دارد:

• 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 غیرخشک، جهش‌های ذخیره‌گاه را به Gateway واگذار می‌کنند تا پاک‌سازی به همان صف نویسنده بپیوندد؛ --store <path> مسیر صریح تعمیر آفلاین برای نگهداشت مستقیم فایل است. پاک‌سازی maxEntries همچنان برای سقف‌های هم‌اندازهٔ تولید دسته‌بندی می‌شود، بنابراین یک ذخیره‌گاه ممکن است پیش از پاک‌سازی high-water بعدی که آن را دوباره پایین می‌آورد، کوتاه‌مدت از سقف پیکربندی‌شده عبور کند. خواندن‌های ذخیره‌گاه نشست هنگام راه‌اندازی Gateway ورودی‌ها را هرس یا محدود نمی‌کنند؛ برای پاک‌سازی از نوشتن‌ها یا openclaw sessions cleanup --enforce استفاده کنید. openclaw sessions cleanup --enforce همچنان سقف پیکربندی‌شده را فوری اعمال می‌کند و رونوشت‌های ارجاع‌نشدهٔ قدیمی، ایست‌های بازرسی، و مصنوعات trajectory را حتی وقتی هیچ بودجهٔ دیسکی پیکربندی نشده باشد هرس می‌کند.

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

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

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

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

1. ابتدا قدیمی‌ترین مصنوعات بایگانی‌شده، رونوشت یتیم، یا trajectory یتیم را حذف کنید.
2. اگر همچنان بالاتر از هدف است، قدیمی‌ترین ورودی‌های نشست و فایل‌های رونوشت/trajectory آن‌ها را بیرون بیندازید.
3. ادامه دهید تا مصرف در highWaterBytes یا پایین‌تر از آن باشد.

در mode: "warn"، OpenClaw اخراج‌های احتمالی را گزارش می‌کند اما ذخیره‌گاه/فایل‌ها را تغییر نمی‌دهد.

نگهداشت را در صورت نیاز اجرا کنید:

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های صریح انتخاب‌شده توسط کاربر برای مدل/احراز هویت را حمل می‌کند. زمینهٔ پیرامونی مکالمه مانند مسیریابی کانال/گروه، سیاست ارسال یا صف، ارتقا، خاستگاه، و اتصال زمان اجرای 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 شده باشد)

قواعد مرجع در /concepts/session مستند شده‌اند.

---

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

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

قواعد کلی:

• بازنشانی (/new، /reset) برای آن sessionKey یک sessionId جدید ایجاد می‌کند.
• بازنشانی روزانه (پیش‌فرض 4:00 صبح به وقت محلی روی میزبان Gateway) در پیام بعدی پس از مرز بازنشانی، یک sessionId جدید ایجاد می‌کند.
• انقضای بیکاری (session.reset.idleMinutes یا session.idleMinutes قدیمی) وقتی پیامی پس از پنجرهٔ بیکاری برسد، یک sessionId جدید ایجاد می‌کند. وقتی هر دو بازنشانی روزانه + بیکاری پیکربندی شده باشند، هرکدام زودتر منقضی شود برنده است.
• رویدادهای سیستمی (Heartbeat، بیدارباش‌های Cron، اعلان‌های exec، دفترداری Gateway) ممکن است ردیف نشست را تغییر دهند اما تازگی بازنشانی روزانه/بیکاری را تمدید نمی‌کنند. چرخش بازنشانی، پیش از ساخته‌شدن prompt تازه، اعلان‌های رویداد سیستمی صف‌شده برای نشست قبلی را دور می‌اندازد.
• سیاست انشعاب والد هنگام ایجاد یک رشته یا انشعاب زیرعامل از شاخهٔ فعال 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: مهرزمان آخرین تخلیهٔ حافظهٔ پیش از 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 و داشبوردها)

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

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

برای اطلاعات بیشتر، /token-use را ببینید.

---

# Compaction: چیست

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

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

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

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

contextTokens > contextWindow - reserveTokens

که در آن:

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

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

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

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

---

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

تنظیمات Compaction در Pi داخل تنظیمات Pi قرار دارند:

{
  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 است، که یک محافظ اندازه بایتی رونوشت فعال در آغاز نوبت است.
• agents.defaults.compaction.maxActiveTranscriptBytes را به یک مقدار بایتی یا رشته‌ای مانند "20mb" تنظیم کنید تا وقتی رونوشت فعال بزرگ می‌شود، پیش از یک نوبت Compaction محلی اجرا شود. این محافظ فقط وقتی فعال است که truncateAfterCompaction نیز فعال باشد. برای غیرفعال کردن، آن را تنظیم‌نشده رها کنید یا روی 0 بگذارید.
• وقتی agents.defaults.compaction.truncateAfterCompaction فعال باشد، OpenClaw پس از Compaction، رونوشت فعال را به یک JSONL جانشین فشرده‌شده می‌چرخاند. رونوشت کامل قدیمی به‌جای بازنویسی درجا، بایگانی می‌ماند و از نقطه بازرسی 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 ثبت‌شده. برای خلاصه‌سازی پیش‌فرض با مدل زبانی بزرگ، تنظیم‌نشده رها کنید.
• تنظیم یک provider حالت mode: "safeguard" را اجباری می‌کند.
• ارائه‌دهندگان همان دستورالعمل‌های Compaction و سیاست حفظ شناسه را که مسیر داخلی دریافت می‌کند، دریافت می‌کنند.
• محافظ همچنان پس از خروجی ارائه‌دهنده، زمینه پسوند نوبت‌های اخیر و نوبت تقسیم‌شده را حفظ می‌کند.
• خلاصه‌سازی محافظ داخلی، خلاصه‌های پیشین را با پیام‌های جدید دوباره تقطیر می‌کند به‌جای اینکه خلاصه قبلی کامل را کلمه‌به‌کلمه حفظ کند.
• حالت محافظ، ممیزی‌های کیفیت خلاصه را به‌طور پیش‌فرض فعال می‌کند؛ برای رد کردن رفتار تلاش دوباره هنگام خروجی بدشکل، qualityGuard.enabled: false را تنظیم کنید.
• اگر ارائه‌دهنده شکست بخورد یا نتیجه‌ای خالی برگرداند، OpenClaw خودکار به خلاصه‌سازی داخلی با مدل زبانی بزرگ بازمی‌گردد.
• سیگنال‌های لغو/مهلت زمانی دوباره پرتاب می‌شوند (بلعیده نمی‌شوند) تا لغو از سوی فراخواننده رعایت شود.

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

نکته‌ها:

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

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

---

# چک‌فهرست عیب‌یابی

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

# مرتبط

• مدیریت نشست
• هرس نشست
• موتور زمینه