Sessions and memory

Compaction

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

نحوهٔ کارکرد

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

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

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

Compaction خودکار

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

خواهید دید:

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

امضاهای سرریز شناسایی‌شده

OpenClaw سرریز زمینه را از الگوهای خطای ارائه‌دهندهٔ زیر تشخیص می‌دهد:

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

Compaction دستی

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

Code

/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 را می‌پذیرد:

json

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

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

json

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

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

حفظ شناسه

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

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

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

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

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

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

اعلان‌های Compaction

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

json5

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

تخلیهٔ حافظه

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

json

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

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

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

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

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

json

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

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

Compaction در برابر هرس

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

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

عیب‌یابی

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

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

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

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

مرتبط

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

Was this useful?