بهداشت رونوشت

OpenClaw پیش از اجرای یک run (ساخت context مدل)، اصلاحات مخصوص ارائه‌دهنده را روی رونوشت‌ها اعمال می‌کند. بیشتر این موارد تنظیمات در حافظه هستند که برای برآورده کردن الزامات سخت‌گیرانه ارائه‌دهنده استفاده می‌شوند. یک مرحله جداگانه ترمیم فایل نشست نیز ممکن است پیش از بارگذاری نشست، JSONL ذخیره‌شده را بازنویسی کند، اما فقط برای خطوط بدشکل یا نوبت‌های ماندگاریافته‌ای که رکوردهای پایدار نامعتبر هستند. پاسخ‌های تحویل‌شده دستیار روی دیسک حفظ می‌شوند؛ حذف assistant-prefill مخصوص ارائه‌دهنده فقط هنگام ساخت payloadهای خروجی انجام می‌شود. وقتی ترمیمی رخ می‌دهد، فایل اصلی پیش از جایگزینی اتمی در یک sibling گذرای *.bak-<pid>-<ts> نوشته می‌شود و پس از موفقیت جایگزینی حذف می‌شود؛ نسخه پشتیبان فقط اگر خود پاک‌سازی شکست بخورد نگه داشته می‌شود (که در آن صورت مسیر گزارش می‌شود).

دامنه شامل این موارد است:

• بیرون نگه داشتن context فقط-زمان‌اجرا از نوبت‌های رونوشت قابل مشاهده برای کاربر
• پاک‌سازی id فراخوانی ابزار
• اعتبارسنجی ورودی فراخوانی ابزار
• ترمیم جفت‌سازی نتیجه ابزار
• اعتبارسنجی / ترتیب‌دهی نوبت
• پاک‌سازی امضای thought
• پاک‌سازی امضای thinking
• پاک‌سازی payload تصویر
• پاک‌سازی بلوک‌های متنی خالی پیش از بازپخش ارائه‌دهنده
• پاک‌سازی نوبت‌های طولی ناقصِ فقط-reasoning پیش از بازپخش ارائه‌دهنده
• برچسب‌گذاری منشأ ورودی کاربر (برای promptهای مسیریابی‌شده بین نشست‌ها)
• ترمیم نوبت خطای خالی دستیار برای بازپخش Bedrock Converse

اگر به جزئیات ذخیره‌سازی رونوشت نیاز دارید، ببینید:

• بررسی عمیق مدیریت نشست

---

قانون سراسری: context زمان‌اجرا رونوشت کاربر نیست

context زمان‌اجرا/سیستم می‌تواند برای یک نوبت به prompt مدل اضافه شود، اما محتوای نوشته‌شده توسط کاربر نهایی نیست. OpenClaw یک بدنه prompt جداگانه و روبه‌رونوشت برای پاسخ‌های Gateway، followupهای صف‌شده، ACP، CLI، و runهای جاسازی‌شده OpenClaw نگه می‌دارد. نوبت‌های قابل مشاهده کاربر که ذخیره می‌شوند به‌جای prompt غنی‌شده با زمان‌اجرا، از همان بدنه رونوشت استفاده می‌کنند.

برای نشست‌های قدیمی که wrapperهای زمان‌اجرا را از قبل ماندگار کرده‌اند، سطح‌های تاریخچه Gateway پیش از بازگرداندن پیام‌ها به کلاینت‌های WebChat، TUI، REST، یا SSE یک projection نمایشی اعمال می‌کنند.

---

این کجا اجرا می‌شود

همه hygiene رونوشت در runner جاسازی‌شده متمرکز شده است:

• انتخاب policy: src/agents/transcript-policy.ts
• اعمال پاک‌سازی/ترمیم: sanitizeSessionHistory در src/agents/embedded-agent-runner/replay-history.ts

این policy از provider، modelApi، و modelId استفاده می‌کند تا تصمیم بگیرد چه چیزی اعمال شود.

جدا از hygiene رونوشت، فایل‌های نشست پیش از بارگذاری (در صورت نیاز) ترمیم می‌شوند:

• repairSessionFileIfNeeded در src/agents/session-file-repair.ts
• فراخوانی‌شده از run/attempt.ts و compact.ts (runner جاسازی‌شده)

---

قانون سراسری: پاک‌سازی تصویر

payloadهای تصویر همیشه پاک‌سازی می‌شوند تا از رد شدن در سمت ارائه‌دهنده به‌دلیل محدودیت‌های اندازه جلوگیری شود (کوچک‌سازی/فشرده‌سازی دوباره تصاویر base64 بیش‌ازحد بزرگ).

این کار همچنین به کنترل فشار token ناشی از تصویر برای مدل‌های دارای قابلیت vision کمک می‌کند. ابعاد حداکثر پایین‌تر معمولا مصرف token را کاهش می‌دهد؛ ابعاد بالاتر جزئیات را حفظ می‌کند.

پیاده‌سازی:

• sanitizeSessionMessagesImages در src/agents/embedded-agent-helpers/images.ts
• sanitizeContentBlocksImages در src/agents/tool-images.ts
• بیشینه ضلع تصویر از طریق agents.defaults.imageMaxDimensionPx قابل تنظیم است (پیش‌فرض: 1200).
• بلوک‌های متنی خالی در حالی حذف می‌شوند که این pass محتوای بازپخش را پیمایش می‌کند. نوبت‌های دستیار که خالی می‌شوند از کپی بازپخش حذف می‌شوند؛ نوبت‌های کاربر و نتیجه ابزار که خالی می‌شوند یک placeholder غیرخالی برای محتوای حذف‌شده دریافت می‌کنند.

---

قانون سراسری: فراخوانی‌های ابزار بدشکل

بلوک‌های فراخوانی ابزارِ دستیار که هم input و هم arguments را ندارند، پیش از ساخته شدن context مدل حذف می‌شوند. این کار از رد شدن توسط ارائه‌دهنده به‌دلیل فراخوانی‌های ابزار نیمه‌ماندگارشده جلوگیری می‌کند (برای مثال، پس از شکست به‌دلیل rate limit).

پیاده‌سازی:

• sanitizeToolCallInputs در src/agents/session-transcript-repair.ts
• اعمال‌شده در sanitizeSessionHistory در src/agents/embedded-agent-runner/replay-history.ts

---

قانون سراسری: نوبت‌های ناقصِ فقط-reasoning

نوبت‌های دستیار که با فقط محتوای thinking یا redacted-thinking به سقف خروجی ارائه‌دهنده می‌خورند، از کپی بازپخش در حافظه حذف می‌شوند. چنین نوبت‌هایی وضعیت ناقص ارائه‌دهنده را در خود دارند و ممکن است حامل یک امضای thinking جزئی باشند.

نوبت‌های طولی خالی، همان‌طور که نوبت‌های طولی دارای متن قابل مشاهده، فراخوانی‌های ابزار، یا بلوک‌های محتوای ناشناخته، بدون تغییر می‌مانند. رونوشت‌های ذخیره‌شده بازنویسی نمی‌شوند.

پیاده‌سازی:

• normalizeAssistantReplayContent در src/agents/embedded-agent-runner/replay-history.ts

---

قانون سراسری: منشأ ورودی بین‌نشستی

وقتی یک agent از طریق sessions_send یک prompt را به نشست دیگری می‌فرستد (از جمله مرحله‌های پاسخ/اعلان agent-to-agent)، OpenClaw نوبت کاربر ایجادشده را با این مقدار ماندگار می‌کند:

• message.provenance.kind = "inter_session"

OpenClaw همچنین یک marker همان‌نوبت [Inter-session message ... isUser=false] را پیش از متن prompt مسیریابی‌شده اضافه می‌کند تا فراخوانی مدل فعال بتواند خروجی نشست خارجی را از دستورهای کاربر نهایی بیرونی تشخیص دهد. این marker در صورت دردسترس بودن شامل نشست منبع، کانال، و ابزار است. رونوشت همچنان برای سازگاری با ارائه‌دهنده از role: "user" استفاده می‌کند، اما هم متن قابل مشاهده و هم metadata منشأ، نوبت را به‌عنوان داده بین‌نشستی مشخص می‌کنند.

هنگام بازسازی context، OpenClaw همین marker را روی نوبت‌های کاربر بین‌نشستی ماندگارشده قدیمی‌تر که فقط metadata منشأ دارند اعمال می‌کند.

---

ماتریس ارائه‌دهنده (رفتار فعلی)

OpenAI / OpenAI Codex

• فقط پاک‌سازی تصویر.
• حذف امضاهای reasoning بی‌سرپرست (آیتم‌های reasoning مستقل بدون بلوک محتوای بعدی) برای رونوشت‌های OpenAI Responses/Codex، و حذف reasoning قابل بازپخش OpenAI پس از تغییر مسیر مدل.
• حفظ payloadهای آیتم reasoning در OpenAI Responses قابل بازپخش، از جمله آیتم‌های encrypted empty-summary، تا بازپخش دستی/WebSocket وضعیت الزامی rs_* را جفت‌شده با آیتم‌های خروجی دستیار نگه دارد.
• Native ChatGPT Codex Responses با بازپخش payloadهای reasoning/message/function قبلی Responses بدون item IDهای قبلی، و در عین حفظ session prompt_cache_key، از برابری wire با Codex پیروی می‌کند.
• بازپخش خانواده OpenAI Responses جفت‌های reasoning همان‌مدل canonical call_*|fc_* را حفظ می‌کند، اما call_id / function-call item idهای بدشکل یا بیش‌ازحد طولانی را پیش از تبدیل payload pi-ai به‌صورت قطعی نرمال‌سازی می‌کند.
• ترمیم جفت‌سازی نتیجه ابزار ممکن است خروجی‌های واقعی match‌شده را جابه‌جا کند و خروجی‌های سبک Codex با وضعیت aborted برای فراخوانی‌های ابزار مفقود بسازد.
• بدون اعتبارسنجی یا ترتیب‌دهی دوباره نوبت.
• خروجی‌های ابزار مفقود خانواده OpenAI Responses به‌صورت aborted ساخته می‌شوند تا با نرمال‌سازی بازپخش Codex سازگار باشند.
• بدون حذف امضای thought.

OpenAI-compatible Chat Completions

• بلوک‌های thinking/reasoning تاریخی دستیار پیش از بازپخش حذف می‌شوند تا سرورهای local و proxy-style سازگار با OpenAI فیلدهای reasoning نوبت‌های قبلی مانند reasoning یا reasoning_content را دریافت نکنند.
• ادامه‌های فراخوانی ابزار در همان نوبت فعلی، بلوک reasoning دستیار را تا زمانی که نتیجه ابزار بازپخش شده باشد، متصل به فراخوانی ابزار نگه می‌دارند.
• ورودی‌های مدل custom/self-hosted با reasoning: true، metadata reasoning بازپخش‌شده را حفظ می‌کنند.
• استثناهای متعلق به ارائه‌دهنده می‌توانند زمانی opt out کنند که wire protocol آن‌ها به metadata reasoning بازپخش‌شده نیاز دارد.

Google (Generative AI / Gemini CLI / Antigravity)

• پاک‌سازی id فراخوانی ابزار: alphanumeric سخت‌گیرانه.
• ترمیم جفت‌سازی نتیجه ابزار و نتایج ابزار ساختگی.
• اعتبارسنجی نوبت (alternation نوبت به سبک Gemini).
• fixup ترتیب نوبت Google (اگر تاریخچه با دستیار شروع شود، یک bootstrap کوچک کاربر را prepend می‌کند).
• Antigravity Claude: نرمال‌سازی امضاهای thinking؛ حذف بلوک‌های thinking بدون امضا.

Anthropic / Minimax (سازگار با Anthropic)

• ترمیم جفت‌سازی نتیجه ابزار و نتایج ابزار ساختگی.
• اعتبارسنجی نوبت (ادغام نوبت‌های پیاپی کاربر برای برآورده کردن alternation سخت‌گیرانه).
• نوبت‌های trailing assistant prefill از payloadهای خروجی Anthropic Messages هنگام فعال بودن thinking حذف می‌شوند، از جمله مسیرهای Cloudflare AI Gateway.
• امضاهای thinking دستیارِ پیش از Compaction پیش از بازپخش ارائه‌دهنده حذف می‌شوند وقتی یک نشست compact شده باشد. امضاهای thinking در زمان تولید از نظر cryptographic به پیشوند مکالمه bound هستند؛ پس از Compaction، پیشوند تغییر می‌کند (محتوای summarized با summaryِ Compaction جایگزین می‌شود)، بنابراین بازپخش امضاهای اصلی باعث می‌شود Anthropic درخواست را با "Invalid signature in thinking block" رد کند. متن thinking به‌عنوان بلوک بدون امضا حفظ می‌شود و سپس توسط قانون زیر مدیریت می‌شود.
• بلوک‌های thinking با امضاهای بازپخش مفقود، خالی، یا blank پیش از تبدیل ارائه‌دهنده حذف می‌شوند. اگر این کار یک نوبت دستیار را خالی کند، OpenClaw شکل نوبت را با متن غیرخالی omitted-reasoning نگه می‌دارد.
• نوبت‌های قدیمی‌تر دستیارِ فقط-thinking که باید حذف شوند با متن غیرخالی omitted-reasoning جایگزین می‌شوند تا adapterهای ارائه‌دهنده نوبت بازپخش را حذف نکنند.

Amazon Bedrock (Converse API)

• نوبت‌های stream-error خالی دستیار پیش از بازپخش به یک بلوک متن fallback غیرخالی ترمیم می‌شوند. Bedrock Converse پیام‌های دستیار با content: [] را رد می‌کند، بنابراین نوبت‌های دستیار ماندگارشده با stopReason: "error" و محتوای خالی نیز پیش از بارگذاری روی دیسک ترمیم می‌شوند.
• نوبت‌های stream-error دستیار که فقط بلوک‌های متنی blank دارند، به‌جای بازپخش یک بلوک blank نامعتبر، از کپی بازپخش در حافظه حذف می‌شوند.
• امضاهای thinking دستیارِ پیش از Compaction پیش از بازپخش Converse وقتی یک نشست compact شده باشد حذف می‌شوند، به همان دلیل Anthropic در بالا.
• بلوک‌های thinking در Claude با امضاهای بازپخش مفقود، خالی، یا blank پیش از بازپخش Converse حذف می‌شوند. اگر این کار یک نوبت دستیار را خالی کند، OpenClaw شکل نوبت را با متن غیرخالی omitted-reasoning نگه می‌دارد.
• نوبت‌های قدیمی‌تر دستیارِ فقط-thinking که باید حذف شوند با متن غیرخالی omitted-reasoning جایگزین می‌شوند تا بازپخش Converse شکل سخت‌گیرانه نوبت را نگه دارد.
• بازپخش، نوبت‌های دستیار delivery-mirror و gateway-injected در OpenClaw را فیلتر می‌کند.
• پاک‌سازی تصویر از طریق قانون سراسری اعمال می‌شود.

Mistral (از جمله تشخیص مبتنی بر model-id)

• پاک‌سازی id فراخوانی ابزار: strict9 (alphanumeric با طول 9).

OpenRouter Gemini

• پاک‌سازی امضای thought: حذف مقادیر غیر-base64 در thought_signature (نگه داشتن base64).

OpenRouter Anthropic

• نوبت‌های trailing assistant prefill از payloadهای مدل Anthropic سازگار با OpenAI و تاییدشده OpenRouter هنگام فعال بودن reasoning حذف می‌شوند، مطابق با رفتار بازپخش مستقیم Anthropic و Cloudflare Anthropic.

هر چیز دیگر

• فقط پاک‌سازی تصویر.

---

رفتار تاریخی (پیش از 2026.1.22)

پیش از انتشار 2026.1.22، OpenClaw چندین لایه hygiene رونوشت اعمال می‌کرد:

• یک transcript-sanitize extension روی هر ساخت context اجرا می‌شد و می‌توانست:
  • جفت‌سازی استفاده/نتیجه ابزار را ترمیم کند.
  • idهای فراخوانی ابزار را پاک‌سازی کند (از جمله یک حالت غیرسخت‌گیرانه که _/- را حفظ می‌کرد).
• runner همچنین پاک‌سازی مخصوص ارائه‌دهنده انجام می‌داد، که کار را تکراری می‌کرد.
• mutationهای اضافی بیرون از policy ارائه‌دهنده رخ می‌داد، از جمله:
  • حذف تگ‌های <final> از متن دستیار پیش از ماندگاری.
  • حذف نوبت‌های خطای خالی دستیار.
  • کوتاه‌سازی محتوای دستیار پس از فراخوانی‌های ابزار.

این پیچیدگی باعث regressionهای بین‌ارائه‌دهنده‌ای شد (به‌ویژه جفت‌سازی call_id|fc_id در openai-responses). پاک‌سازی 2026.1.22 این extension را حذف کرد، منطق را در runner متمرکز کرد، و OpenAI را فراتر از پاک‌سازی تصویر no-touch کرد.

مرتبط

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