بررسی عمیق مدیریت نشست‌ها

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 حل می‌کند.

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

ماندگاری نشست کنترل‌های نگهداری خودکار (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 بیرون‌رانی‌های احتمالی را گزارش می‌کند اما ذخیره‌گاه/فایل‌ها را تغییر نمی‌دهد.

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

openclaw sessions cleanup --dry-runopenclaw 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 مستند شده‌اند.

شناسه‌های نشست (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 را ببینید.

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، و گونه‌های مشابه با شکل ارائه‌دهنده) → 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 قرار دارند:

{  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 را ببینید.

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

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

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

مرتبط

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