Compaction

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

نحوهٔ کار

1. نوبت‌های قدیمی‌تر گفت‌وگو در یک ورودی فشرده خلاصه می‌شوند.
2. خلاصه در رونوشت نشست ذخیره می‌شود.
3. پیام‌های اخیر بدون تغییر نگه داشته می‌شوند.

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

تاریخچهٔ کامل گفت‌وگو روی دیسک باقی می‌ماند. Compaction فقط چیزی را تغییر می‌دهد که مدل در نوبت بعدی می‌بیند.

Compaction خودکار

Compaction خودکار به‌صورت پیش‌فرض فعال است. وقتی نشست به حد زمینه نزدیک می‌شود، یا وقتی مدل خطای سرریز زمینه برمی‌گرداند اجرا می‌شود؛ در این حالت OpenClaw Compaction را انجام می‌دهد و دوباره تلاش می‌کند.

خواهید دید:

• embedded run auto-compaction start / complete در لاگ‌های عادی Gateway.
• 🧹 Auto-compaction complete در حالت پرجزئیات.
• /status که 🧹 Compactions: <count> را نشان می‌دهد.

Compaction دستی

در هر چت، /compact را تایپ کنید تا Compaction اجباری انجام شود. برای هدایت خلاصه، دستورالعمل اضافه کنید:

/compact Focus on the API design decisions

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

پیکربندی

Compaction را در agents.defaults.compaction داخل openclaw.json پیکربندی کنید. رایج‌ترین تنظیم‌ها در زیر فهرست شده‌اند؛ برای مرجع کامل، بررسی عمیق مدیریت نشست را ببینید.

استفاده از یک مدل متفاوت

به‌صورت پیش‌فرض، Compaction از مدل اصلی عامل استفاده می‌کند. agents.defaults.compaction.model را تنظیم کنید تا خلاصه‌سازی را به یک مدل توانمندتر یا تخصصی‌تر واگذار کنید. این بازنویسی یک رشتهٔ provider/model-id یا یک نام مستعار ساده را که زیر agents.defaults.models پیکربندی شده می‌پذیرد:

{  "agents": {    "defaults": {      "compaction": {        "model": "openrouter/anthropic/claude-sonnet-4-6"      }    }  }}

نام‌های مستعار سادهٔ پیکربندی‌شده پیش از شروع Compaction به ارائه‌دهنده و مدل متعارف خود حل می‌شوند. اگر یک مقدار ساده هم با یک نام مستعار و هم با یک شناسهٔ مدل literal پیکربندی‌شده مطابقت داشته باشد، شناسهٔ مدل literal برنده می‌شود. مقدار سادهٔ نامطابق، روی ارائه‌دهندهٔ فعال به‌عنوان شناسهٔ مدل باقی می‌ماند.

این با مدل‌های محلی هم کار می‌کند، برای مثال یک مدل دوم Ollama که به خلاصه‌سازی اختصاص دارد:

{  "agents": {    "defaults": {      "compaction": {        "model": "ollama/llama3.1:8b"      }    }  }}

وقتی تنظیم نشده باشد، Compaction با مدل فعال نشست شروع می‌شود. اگر خلاصه‌سازی با یک خطای ارائه‌دهندهٔ واجد شرایط fallback مدل شکست بخورد، OpenClaw آن تلاش Compaction را از طریق زنجیرهٔ fallback مدل موجود نشست دوباره امتحان می‌کند. انتخاب fallback موقتی است و دوباره در وضعیت نشست نوشته نمی‌شود. بازنویسی صریح agents.defaults.compaction.model دقیق باقی می‌ماند و زنجیرهٔ fallback نشست را به ارث نمی‌برد.

حفظ شناسه

خلاصه‌سازی Compaction به‌صورت پیش‌فرض شناسه‌های مات را حفظ می‌کند (identifierPolicy: "strict"). برای غیرفعال‌کردن، با identifierPolicy: "off" بازنویسی کنید، یا برای راهنمایی سفارشی از identifierPolicy: "custom" همراه با identifierInstructions استفاده کنید.

محافظ بایت رونوشت فعال

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

رونوشت‌های جانشین

وقتی agents.defaults.compaction.truncateAfterCompaction فعال باشد، OpenClaw رونوشت موجود را درجا بازنویسی نمی‌کند. یک رونوشت جانشین فعال جدید از خلاصهٔ Compaction، وضعیت حفظ‌شده، و دنبالهٔ خلاصه‌نشده ایجاد می‌کند، سپس فرادادهٔ نقطهٔ بازرسی را ثبت می‌کند که جریان‌های branch/restore را به آن جانشین فشرده‌شده هدایت می‌کند. رونوشت‌های جانشین همچنین نوبت‌های طولانی کاربر را که عیناً تکراری هستند و داخل یک پنجرهٔ کوتاه تلاش مجدد می‌رسند حذف می‌کنند، تا طوفان‌های تلاش مجدد کانال به رونوشت فعال بعدی پس از Compaction منتقل نشوند.

OpenClaw دیگر برای Compactionهای جدید نسخه‌های جداگانهٔ .checkpoint.*.jsonl نمی‌نویسد. فایل‌های قدیمی نقطهٔ بازرسی موجود تا زمانی که ارجاع داده می‌شوند همچنان قابل استفاده‌اند و با پاک‌سازی عادی نشست حذف می‌شوند.

اعلان‌های Compaction

به‌صورت پیش‌فرض، Compaction بی‌صدا اجرا می‌شود. notifyUser را تنظیم کنید تا هنگام شروع و تکمیل Compaction پیام‌های وضعیت کوتاه نشان داده شود:

{  agents: {    defaults: {      compaction: {        notifyUser: true,      },    },  },}

تخلیهٔ حافظه

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

{  "agents": {    "defaults": {      "compaction": {        "memoryFlush": {          "model": "ollama/qwen3:8b"        }      }    }  }}

بازنویسی مدل memory-flush دقیق است و زنجیرهٔ fallback نشست فعال را به ارث نمی‌برد. برای جزئیات و پیکربندی، Memory را ببینید.

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

Pluginها می‌توانند از طریق registerCompactionProvider() در API پلاگین، یک ارائه‌دهندهٔ سفارشی Compaction ثبت کنند. وقتی یک ارائه‌دهنده ثبت و پیکربندی شده باشد، OpenClaw خلاصه‌سازی را به‌جای خط لولهٔ LLM داخلی به آن واگذار می‌کند.

برای استفاده از یک ارائه‌دهندهٔ ثبت‌شده، شناسهٔ آن را در پیکربندی خود تنظیم کنید:

{  "agents": {    "defaults": {      "compaction": {        "provider": "my-provider"      }    }  }}

تنظیم یک provider به‌طور خودکار mode: "safeguard" را اجباری می‌کند. ارائه‌دهندگان همان دستورالعمل‌های Compaction و سیاست حفظ شناسه را مانند مسیر داخلی دریافت می‌کنند، و OpenClaw همچنان زمینهٔ پسوند نوبت‌های اخیر و نوبت‌های تقسیم‌شده را پس از خروجی ارائه‌دهنده حفظ می‌کند.

Compaction در برابر هرس

هرس نشست مکملی سبک‌تر است که خروجی ابزار را بدون خلاصه‌سازی کوتاه می‌کند.

عیب‌یابی

Compaction بیش از حد انجام می‌شود؟ ممکن است پنجرهٔ زمینهٔ مدل کوچک باشد، یا خروجی‌های ابزار بزرگ باشند. فعال‌کردن هرس نشست را امتحان کنید.

پس از Compaction، زمینه کهنه به نظر می‌رسد؟ از /compact Focus on <topic> برای هدایت خلاصه استفاده کنید، یا تخلیهٔ حافظه را فعال کنید تا یادداشت‌ها باقی بمانند.

به یک شروع تمیز نیاز دارید؟ /new یک نشست تازه را بدون Compaction شروع می‌کند.

برای پیکربندی پیشرفته (توکن‌های ذخیره، حفظ شناسه، موتورهای زمینهٔ سفارشی، Compaction سمت سرور OpenAI)، بررسی عمیق مدیریت نشست را ببینید.

مرتبط

• نشست: مدیریت نشست و چرخهٔ عمر.
• هرس نشست: کوتاه‌کردن نتایج ابزار.
• زمینه: نحوهٔ ساخته‌شدن زمینه برای نوبت‌های عامل.
• Hooks: hookهای چرخهٔ عمر Compaction (before_compaction, after_compaction).