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)

قاعدهٔ سراسری: جفت‌سازی نتیجهٔ ابزار

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

پیاده‌سازی: sanitizeToolUseResultPairing در src/agents/session-transcript-repair.ts

قاعدهٔ سراسری: نوبت‌های ناقص یا بی‌صدای صرفاً استدلالی

نوبت‌های دستیار زمانی از نسخهٔ بازپخش درون‌حافظه‌ای حذف می‌شوند که پس از هر یک از رویدادهای زیر، فقط محتوای تفکر یا تفکر ویرایش‌شده داشته باشند:

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

پاک‌سازی پاسخ بی‌صدا مانع ادغام استدلال پنهان با نوبت بعدی استفاده از ابزار توسط دستیار می‌شود، هنگامی که ارائه‌دهندگان سخت‌گیر مکالمه را دوباره می‌سازند.

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

پیاده‌سازی: 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_* را در کنار موارد خروجی دستیار نگه دارد.
Native ChatGPT Codex Responses با بازپخش محموله‌های پیشین استدلال/پیام/تابع Responses بدون شناسهٔ موارد قبلی و با حفظ prompt_cache_key نشست، از هم‌ارزی سیمی Codex پیروی می‌کند.
بازپخش خانوادهٔ OpenAI Responses جفت‌های متعارف استدلال همان‌مدل call_*|fc_* را حفظ می‌کند، اما شناسه‌های معیوب یا بیش‌ازحد طولانی موارد call_id/فراخوانی تابع را پیش از تبدیل محمولهٔ pi-ai به‌صورت قطعی نرمال‌سازی می‌کند.
تعمیر جفت‌سازی نتیجهٔ ابزار ممکن است خروجی‌های واقعی منطبق را جابه‌جا و برای فراخوانی‌های ابزار فاقد نتیجه، خروجی‌های aborted به سبک Codex تولید کند.
بدون اعتبارسنجی یا ترتیب‌دهی مجدد نوبت؛ بدون حذف امضای اندیشه.

Chat Completions سازگار با OpenAI

بلوک‌های تاریخی تفکر/استدلال دستیار پیش از بازپخش حذف می‌شوند تا سرورهای محلی و پروکسی‌مانند سازگار با 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 (حروف و اعداد، طول 9).

OpenRouter Gemini

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

OpenRouter Anthropic

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

سایر موارد

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

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

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

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

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

مرتبط

Was this useful?