Technical reference

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

OpenClaw پیش از اجرای هر نوبت (هنگام ساخت زمینهٔ مدل)، اصلاحات ویژهٔ ارائه‌دهنده را روی رونوشت‌ها اعمال می‌کند. بیشتر این اصلاحات، تنظیماتی درون‌حافظه‌ای هستند که برای برآورده‌کردن الزامات سخت‌گیرانهٔ ارائه‌دهنده استفاده می‌شوند. یک مرحلهٔ جداگانهٔ ترمیم فایل نشست نیز ممکن است پیش از بارگذاری نشست، فایل JSONL ذخیره‌شده را بازنویسی کند؛ اما فقط برای خطوط بدشکل یا نوبت‌های ماندگاریافته‌ای که رکوردهای پایدار معتبری نیستند. پاسخ‌های تحویل‌شدهٔ دستیار روی دیسک حفظ می‌شوند؛ حذف پیش‌پرکردن دستیارِ ویژهٔ ارائه‌دهنده فقط هنگام ساخت محموله‌های خروجی انجام می‌شود.

هنگامی که ترمیمی رخ می‌دهد، پیش از جایگزینی اتمی، فایل اصلی در یک فایل هم‌سطح موقت با الگوی *.bak-<pid>-<ts> نوشته می‌شود و پس از موفقیت جایگزینی حذف می‌گردد. نسخهٔ پشتیبان فقط در صورتی نگه داشته می‌شود که خود پاک‌سازی ناموفق باشد؛ در این صورت مسیر آن گزارش می‌شود.

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

جلوگیری از ورود زمینهٔ اعلانِ صرفاً زمان‌اجرا به نوبت‌های رونوشت قابل‌مشاهده برای کاربر
پاک‌سازی شناسهٔ فراخوانی ابزار
اعتبارسنجی ورودی فراخوانی ابزار
ترمیم جفت‌سازی نتیجهٔ ابزار
اعتبارسنجی / ترتیب‌دهی نوبت‌ها
پاک‌سازی امضای اندیشه
پاک‌سازی امضای تفکر
پاک‌سازی محمولهٔ تصویر
پاک‌سازی بلوک‌های متنی خالی پیش از بازپخش برای ارائه‌دهنده
پاک‌سازی نوبت‌های ناقصِ محدودشده به استدلال پیش از بازپخش برای ارائه‌دهنده
برچسب‌گذاری منشأ ورودی کاربر (برای اعلان‌های مسیریابی‌شده میان نشست‌ها)
ترمیم نوبت خطای خالی دستیار برای بازپخش Bedrock Converse

اگر به جزئیات ذخیره‌سازی رونوشت نیاز دارید، به بررسی عمیق مدیریت نشست مراجعه کنید.

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

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

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

محل اجرا

تمام بهداشت رونوشت در اجراکنندهٔ توکار متمرکز شده است:

انتخاب خط‌مشی: src/agents/transcript-policy.ts (resolveTranscriptPolicy، با کلیدهای provider، modelApi و modelId)
اعمال پاک‌سازی/ترمیم: sanitizeSessionHistory در src/agents/embedded-agent-runner/replay-history.ts

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

repairSessionFileIfNeeded در src/agents/session-file-repair.ts
فراخوانی‌شده از src/agents/embedded-agent-runner/run/attempt.ts و src/agents/embedded-agent-runner/compact.ts

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

محموله‌های تصویر همیشه پاک‌سازی می‌شوند تا از ردشدن آن‌ها در سمت ارائه‌دهنده به‌دلیل محدودیت اندازه جلوگیری شود (کوچک‌سازی/فشرده‌سازی مجدد تصاویر بزرگ base64). این کار همچنین به کنترل فشار توکن ناشی از تصویر برای مدل‌های دارای قابلیت بینایی کمک می‌کند: حداکثر ابعاد کمتر، مصرف توکن را کاهش می‌دهد و ابعاد بیشتر، جزئیات را حفظ می‌کند.

پیاده‌سازی:

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

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

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

پیاده‌سازی:

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

قانون سراسری: نوبت‌های ناقصِ محدودشده به استدلال

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

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

پیاده‌سازی: normalizeAssistantReplayContent در src/agents/embedded-agent-runner/replay-history.ts

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

هنگامی که یک عامل از طریق sessions_send اعلانی را به نشست دیگری می‌فرستد (از جمله مراحل پاسخ/اعلان عامل به عامل)، OpenClaw نوبت کاربر ایجادشده را با message.provenance.kind = "inter_session" ماندگار می‌کند.

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

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

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

OpenAI / OpenAI Codex

فقط پاک‌سازی تصویر.
حذف امضاهای استدلال یتیم (موارد مستقل استدلال بدون بلوک محتوایی پس از آن‌ها) برای رونوشت‌های OpenAI Responses/Codex و حذف استدلال قابل‌بازپخش OpenAI پس از تغییر مسیر مدل.
حفظ محموله‌های موارد استدلال قابل‌بازپخش OpenAI Responses، از جمله موارد رمزگذاری‌شده با خلاصهٔ خالی، تا بازپخش دستی/WebSocket وضعیت الزامی rs_* را با موارد خروجی دستیار جفت نگه دارد.
ChatGPT Codex Responses بومی با بازپخش محموله‌های پیشین استدلال/پیام/تابع Responses بدون شناسهٔ موارد قبلی و با حفظ prompt_cache_key نشست، هم‌ارزی پروتکل Codex را رعایت می‌کند.
بازپخش خانوادهٔ OpenAI Responses جفت‌های متعارف call_*|fc_* مربوط به استدلال همان مدل را حفظ می‌کند، اما پیش از تبدیل محمولهٔ pi-ai، شناسه‌های بدشکل یا بیش‌ازحد طولانی call_id/موارد فراخوانی تابع را به‌صورت قطعی نرمال‌سازی می‌کند.
ترمیم جفت‌سازی نتیجهٔ ابزار ممکن است خروجی‌های واقعی تطبیق‌یافته را جابه‌جا کند و برای فراخوانی‌های ابزار فاقد نتیجه، خروجی‌های aborted به سبک Codex بسازد.
بدون اعتبارسنجی یا ترتیب‌دهی مجدد نوبت‌ها؛ بدون حذف امضای اندیشه.

OpenAI-compatible Chat Completions

بلوک‌های تاریخی تفکر/استدلال دستیار پیش از بازپخش حذف می‌شوند تا سرورهای محلی و پراکسی‌مانند سازگار با OpenAI، فیلدهای استدلال نوبت‌های قبلی مانند reasoning یا reasoning_content را دریافت نکنند.
ادامه‌های فراخوانی ابزار در همان نوبت جاری، بلوک استدلال دستیار را تا زمان بازپخش نتیجهٔ ابزار به فراخوانی ابزار متصل نگه می‌دارند.
ورودی‌های مدل سفارشی/خودمیزبان با reasoning: true فرادادهٔ استدلال بازپخش‌شده را حفظ می‌کنند.
استثناهای متعلق به ارائه‌دهنده می‌توانند در صورت نیاز پروتکل ارتباطی آن‌ها به فرادادهٔ استدلال بازپخش‌شده، از این رفتار انصراف دهند.

Google (Generative AI / Gemini CLI / Antigravity)

پاک‌سازی شناسهٔ فراخوانی ابزار: صرفاً حروف و ارقام.
ترمیم جفت‌سازی نتیجهٔ ابزار و نتایج ابزار مصنوعی.
اعتبارسنجی نوبت‌ها (تناوب نوبت به سبک Gemini).
اصلاح ترتیب نوبت‌های Google (اگر تاریخچه با دستیار آغاز شود، یک راه‌انداز کوچک کاربر به ابتدا افزوده می‌شود).
Antigravity Claude: نرمال‌سازی امضاهای تفکر؛ حذف بلوک‌های تفکر بدون امضا.

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

ترمیم جفت‌سازی نتیجهٔ ابزار و نتایج ابزار مصنوعی.
اعتبارسنجی نوبت‌ها (ادغام نوبت‌های متوالی کاربر برای رعایت تناوب سخت‌گیرانه).
هنگامی که تفکر فعال است، نوبت‌های پایانی پیش‌پرکردن دستیار از محموله‌های خروجی Anthropic Messages حذف می‌شوند؛ این شامل مسیرهای Cloudflare AI Gateway نیز می‌شود.
اگر نشستی Compaction شده باشد، امضاهای تفکر دستیار مربوط به پیش از Compaction پیش از بازپخش برای ارائه‌دهنده حذف می‌شوند. امضاهای تفکر در زمان تولید به‌صورت رمزنگاری‌شده به پیشوند مکالمه متصل می‌شوند؛ پس از Compaction، پیشوند تغییر می‌کند (محتوای خلاصه‌شده جایگزین محتوای اصلی می‌شود)، بنابراین بازپخش امضاهای اصلی باعث می‌شود Anthropic درخواست را با پیام "Invalid signature in thinking block" رد کند. متن تفکر به‌صورت یک بلوک بدون امضا حفظ می‌شود و سپس مطابق قانون زیر پردازش می‌گردد.
بلوک‌های تفکر با امضای بازپخش مفقود، خالی یا سفید پیش از تبدیل برای ارائه‌دهنده حذف می‌شوند. اگر این کار نوبت دستیار را خالی کند، OpenClaw شکل نوبت را با متن غیرخالیِ حذف استدلال حفظ می‌کند.
نوبت‌های قدیمی دستیار که فقط شامل تفکر هستند و باید حذف شوند، با متن غیرخالیِ حذف استدلال جایگزین می‌شوند تا آداپتورهای ارائه‌دهنده نوبت بازپخش را کنار نگذارند.

Amazon Bedrock (Converse API)

نوبت‌های خالیِ خطای جریان دستیار پیش از بازپخش به یک بلوک متنی جایگزین غیرخالی ترمیم می‌شوند. Bedrock Converse پیام‌های دستیار با content: [] را رد می‌کند؛ بنابراین نوبت‌های ماندگاریافتهٔ دستیار با stopReason: "error" و محتوای خالی نیز پیش از بارگذاری روی دیسک ترمیم می‌شوند.
نوبت‌های خطای جریان دستیار که فقط بلوک‌های متنی سفید دارند، به‌جای بازپخش یک بلوک سفید نامعتبر، از نسخهٔ بازپخش درون‌حافظه‌ای کنار گذاشته می‌شوند.
اگر نشستی Compaction شده باشد، امضاهای تفکر دستیار مربوط به پیش از Compaction پیش از بازپخش Converse حذف می‌شوند؛ به همان دلیل بیان‌شده برای Anthropic در بالا.
بلوک‌های تفکر Claude با امضای بازپخش مفقود، خالی یا سفید پیش از بازپخش Converse حذف می‌شوند. اگر این کار نوبت دستیار را خالی کند، OpenClaw شکل نوبت را با متن غیرخالیِ حذف استدلال حفظ می‌کند.
نوبت‌های قدیمی دستیار که فقط شامل تفکر هستند و باید حذف شوند، با متن غیرخالیِ حذف استدلال جایگزین می‌شوند تا بازپخش Converse شکل سخت‌گیرانهٔ نوبت را حفظ کند.
بازپخش، نوبت‌های دستیارِ آینهٔ تحویل OpenClaw و تزریق‌شده توسط Gateway را فیلتر می‌کند.
پاک‌سازی تصویر مطابق قانون سراسری اعمال می‌شود.

Mistral (از جمله تشخیص مبتنی بر شناسهٔ مدل)

پاک‌سازی شناسهٔ فراخوانی ابزار: strict9 (حروف و ارقام، با طول ۹).

OpenRouter Gemini

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

OpenRouter Anthropic

هنگامی که استدلال فعال است، نوبت‌های پایانی پیش‌پرکردن دستیار از محموله‌های مدل Anthropic سازگار با OpenAI و تأییدشدهٔ OpenRouter حذف می‌شوند؛ مطابق با رفتار بازپخش مستقیم Anthropic و Cloudflare Anthropic.

سایر موارد

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

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

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

یک افزونهٔ پاک‌سازی رونوشت در هر بار ساخت زمینه اجرا می‌شد و می‌توانست:
- جفت‌سازی استفاده/نتیجهٔ ابزار را ترمیم کند.
- شناسه‌های فراخوانی ابزار را پاک‌سازی کند (از جمله حالت غیرسخت‌گیرانه‌ای که _/- را حفظ می‌کرد).
اجراکننده نیز پاک‌سازی ویژهٔ ارائه‌دهنده را انجام می‌داد که باعث تکرار کار می‌شد.
تغییرات دیگری خارج از خط‌مشی ارائه‌دهنده رخ می‌دادند؛ از جمله حذف برچسب‌های <final> از متن دستیار پیش از ماندگارسازی، کنارگذاشتن نوبت‌های خالیِ خطای دستیار و کوتاه‌کردن محتوای دستیار پس از فراخوانی‌های ابزار.

این پیچیدگی موجب پس‌رفت‌های میان‌ارائه‌دهنده‌ای شد (به‌ویژه در جفت‌سازی call_id|fc_id برای openai-responses). پاک‌سازی نسخهٔ 2026.1.22 افزونه را حذف کرد، منطق را در اجراکننده متمرکز ساخت و OpenAI را به‌جز پاک‌سازی تصویر بدون تغییر نگه داشت.

مرتبط

Was this useful?