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

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

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

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

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

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

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

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

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

Compaction: چیست

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

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

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

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

Compaction پایدار است (برخلاف هرس نشست). /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 در تنظیمات عامل قرار دارند:

{  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 و الگوهای نوشتن، حافظه را ببینید.

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

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

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

مرتبط

• مدیریت نشست
• هرس نشست
• موتور بافت