بررسی عمیق مدیریت جلسه

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

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

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

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

منبع حقیقت: Gateway

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

• UIها (برنامهٔ macOS، Control UI وب، 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 همچنان برای سقف‌های هم‌اندازهٔ تولید به‌صورت دسته‌ای انجام می‌شود، بنابراین یک ذخیره‌گاه ممکن است کوتاه‌مدت از سقف پیکربندی‌شده فراتر برود تا پاک‌سازی بعدیِ سطح بالا آن را دوباره پایین بیاورد. خواندن‌های ذخیره‌گاه نشست هنگام راه‌اندازی Gateway ورودی‌ها را هرس یا سقف‌گذاری نمی‌کنند؛ برای پاک‌سازی از نوشتن‌ها یا openclaw sessions cleanup --enforce استفاده کنید. openclaw sessions cleanup --enforce همچنان سقف پیکربندی‌شده را بلافاصله اعمال می‌کند و مصنوعات رونوشت، چک‌پوینت، و مسیر اجرای قدیمیِ بدون ارجاع را حتی وقتی هیچ بودجهٔ دیسکی پیکربندی نشده باشد هرس می‌کند.

نگهداری اشاره‌گرهای بادوام گفت‌وگوی خارجی مانند نشست‌های گروهی و نشست‌های گفت‌وگوی محدود به نخ را نگه می‌دارد، اما ورودی‌های مصنوعی زمان اجرا برای cron، hookها، Heartbeat، ACP، و زیرعامل‌ها همچنان می‌توانند وقتی از سن، شمار، یا بودجهٔ دیسک پیکربندی‌شده فراتر بروند حذف شوند. نشست‌های پروب اجرای مدل Gateway فقط زمانی از نگهداری جداگانهٔ اجرای مدل 24h استفاده می‌کنند که کلیدشان دقیقاً با agent:*:explicit:model-run-<uuid> مطابقت داشته باشد؛ نشست‌های صریح دیگر بخشی از آن نگهداری نیستند. پاک‌سازی اجرای مدل فقط زیر فشار سقف ورودی نشست اعمال می‌شود. اجراهای 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> قبلی را پاک‌سازی می‌کند. ترجیح‌های ایمن مانند تنظیمات تفکر/سریع/پرحرف، برچسب‌ها، و بازنویسی‌های صریح مدل/احراز هویت انتخاب‌شده توسط کاربر را حمل می‌کند. زمینهٔ گفت‌وگوی محیطی مانند مسیریابی کانال/گروه، سیاست ارسال یا صف، ارتقا، مبدأ، و اتصال زمان اجرای 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 مطابق را از یک کلاینت UI اپراتور دریافت کند. ارسال‌های کهنهٔ عادی همچنان یک sessionId جدید ایجاد می‌کنند.
• رویدادهای سامانه (Heartbeat، بیدارسازی‌های cron، اعلان‌های exec، دفترداری gateway) ممکن است ردیف نشست را جهش دهند اما تازگی بازنشانی روزانه/بی‌کاری را تمدید نمی‌کنند. چرخش بازنشانی پیش از ساخته‌شدن پرامپت تازه، اعلان‌های رویداد سامانهٔ صف‌شده برای نشست قبلی را دور می‌اندازد.
• سیاست انشعاب والد هنگام ایجاد نخ یا انشعاب زیرعامل از شاخهٔ فعال 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: زمان‌برچسب آخرین جهش ردیفِ ذخیره‌گاه، که برای فهرست‌کردن، هرس‌کردن، و امور دفترداری استفاده می‌شود. این مرجع تازگیِ بازنشانی روزانه/بیکاری نیست.
• archivedAt: زمان‌برچسب اختیاری بایگانی. نشست‌های بایگانی‌شده با رونوشت دست‌نخوردهٔ خود در ذخیره‌گاه می‌مانند و از فهرست‌های فعال عادی کنار گذاشته می‌شوند.
• pinnedAt: زمان‌برچسب اختیاری سنجاق. نشست‌های سنجاق‌شدهٔ فعال جلوتر از نشست‌های سنجاق‌نشده مرتب می‌شوند؛ بایگانی‌کردن یک نشست، سنجاق آن را پاک می‌کند.
• هم‌کنش‌پذیری رشتهٔ Codex: هر دو فیلد از شکل مدیریت رشتهٔ Codex پیروی می‌کنند — بولی‌های archived/pinned روی سیم همیشه از زمان‌برچسب مشتق می‌شوند و در سمت سرور مهر می‌خورند، همسو با معناشناسی Codex threads.archived_at و سری‌سازی camelCase. زمان‌برچسب‌های OpenClaw بر حسب میلی‌ثانیهٔ epoch هستند، در حالی که Codex از ثانیهٔ epoch استفاده می‌کند، بنابراین پل‌ها در مرز Plugin کدکس تبدیل را انجام می‌دهند. Codex هنوز API سنجاق ندارد (فقط thread/archive/thread/unarchive)؛ وضعیت سنجاق تا زمانی که چنین API وجود داشته باشد در سمت OpenClaw می‌ماند، و در آن زمان شکل منطبق اجازه می‌دهد نشست‌های مقید، وضعیت سنجاق را به‌صورت مکانیکی رفت‌وبرگشت کنند.
• sessionFile: بازنویسی اختیاری و صریح مسیر رونوشت
• chatType: direct | group | room (به UIها و سیاست ارسال کمک می‌کند)
• provider، subject، room، space، displayName: فراداده برای برچسب‌گذاری گروه/کانال
• کلیدهای تغییر:
  • thinkingLevel، verboseLevel، reasoningLevel، elevatedLevel
  • sendPolicy (بازنویسی برای هر نشست)
• انتخاب مدل:
  • providerOverride، modelOverride، authProfileOverride
• شمارنده‌های توکن (با بهترین تلاش / وابسته به ارائه‌دهنده):
  • inputTokens، outputTokens، totalTokens، contextTokens
• compactionCount: تعداد دفعاتی که Compaction خودکار برای این کلید نشست کامل شده است
• memoryFlushAt: زمان‌برچسب آخرین تخلیهٔ حافظه پیش از Compaction
• memoryFlushCompactionCount: شمار Compaction هنگام اجرای آخرین تخلیه

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

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

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

فایل JSONL است:

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

انواع مدخل قابل توجه:

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

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

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

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

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

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

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

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

Compaction: چیست

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

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

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

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

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

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

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

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

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

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

contextTokens > contextWindow - reserveTokens

که در آن:

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

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

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

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

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

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

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

ارائه‌دهندگان 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/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
• حالت پرجزئیات: 🧹 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 زمان اجرای OpenClaw)، یک دستور خاموش «همین حالا حافظه را بنویس» برای عامل اجرا کنید.
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 ردیابی می‌شود).
• تخلیه فقط برای نشست‌های تعبیه‌شدهٔ OpenClaw اجرا می‌شود (بک‌اندهای CLI از آن عبور می‌کنند).
• وقتی فضای کاری نشست فقط‌خواندنی باشد (workspaceAccess: "ro" یا "none")، تخلیه رد می‌شود.
• برای چیدمان فایل‌های فضای کاری و الگوهای نوشتن، حافظه را ببینید.

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

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

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

مرتبط

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