Compaction

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

# چگونه کار می‌کند

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

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

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

# Compaction خودکار

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

خواهید دید:

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

# Compaction دستی

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

/compact Focus on the API design decisions

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

# پیکربندی

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

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

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

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

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

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

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

# حفظ شناسه‌ها

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

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

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

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

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

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

# اعلان‌های Compaction

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

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

# تخلیهٔ حافظه

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

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

override مدل تخلیهٔ حافظه دقیق است و زنجیرهٔ fallback نشست فعال را به ارث نمی‌برد. برای جزئیات و پیکربندی، حافظه را ببینید.

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

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

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

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

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

# Compaction در برابر هرس

	Compaction	هرس
چه می‌کند	گفت‌وگوی قدیمی‌تر را خلاصه می‌کند	نتایج قدیمی ابزار را کوتاه می‌کند
ذخیره می‌شود؟	بله (در رونوشت نشست)	خیر (فقط در حافظه، برای هر درخواست)
دامنه	کل گفت‌وگو	فقط نتایج ابزار

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

# عیب‌یابی

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

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

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

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

# مرتبط

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