بسته‌های مسیر

ضبط مسیر، ضبط‌کنندهٔ پرواز هر نشست در OpenClaw است. این قابلیت یک خط زمانی ساخت‌یافته برای هر اجرای عامل ثبت می‌کند، سپس /export-trajectory نشست فعلی را در یک بستهٔ پشتیبانی ویرایش‌شده بسته‌بندی می‌کند.

وقتی نیاز دارید به پرسش‌هایی مانند این‌ها پاسخ دهید از آن استفاده کنید:

• چه پرامپت، پرامپت سیستمی، و ابزارهایی به مدل ارسال شدند؟
• کدام پیام‌های رونوشت و فراخوانی‌های ابزار به این پاسخ منجر شدند؟
• آیا اجرا مهلتش تمام شد، لغو شد، Compaction شد، یا با خطای ارائه‌دهنده روبه‌رو شد؟
• کدام مدل، Pluginها، Skills، و تنظیمات زمان اجرا فعال بودند؟
• ارائه‌دهنده چه فراداده‌ای دربارهٔ مصرف و کش پرامپت برگرداند؟

اگر در حال ثبت یک گزارش پشتیبانی گسترده برای یک مشکل زندهٔ Gateway هستید، با /diagnostics شروع کنید. عیب‌یابی، بستهٔ پاک‌سازی‌شدهٔ Gateway را جمع‌آوری می‌کند و برای نشست‌های OpenAI Codex harness، پس از تأیید می‌تواند بازخورد Codex را نیز به سرورهای OpenAI ارسال کند. وقتی به‌طور مشخص به خط زمانی دقیق پرامپت، ابزار، و رونوشت در سطح نشست نیاز دارید از /export-trajectory استفاده کنید.

# شروع سریع

این را در نشست فعال ارسال کنید:

/export-trajectory

نام مستعار:

/trajectory

OpenClaw بسته را زیر فضای کاری می‌نویسد:

.openclaw/trajectory-exports/openclaw-trajectory-<session>-<timestamp>/

می‌توانید یک نام مسیر خروجی نسبی انتخاب کنید:

/export-trajectory bug-1234

مسیر سفارشی داخل .openclaw/trajectory-exports/ resolve می‌شود. مسیرهای مطلق و مسیرهای ~ رد می‌شوند.

بسته‌های مسیر می‌توانند شامل پرامپت‌ها، پیام‌های مدل، schemaهای ابزار، نتایج ابزار، رویدادهای زمان اجرا، و مسیرهای محلی باشند. بنابراین فرمان اسلش چت هر بار از مسیر تأیید exec عبور می‌کند. وقتی قصد دارید بسته را ایجاد کنید، یک بار خروجی را تأیید کنید؛ از allow-all استفاده نکنید. در چت‌های گروهی، OpenClaw پرامپت تأیید و نتیجهٔ خروجی را به‌صورت خصوصی برای مالک می‌فرستد، به‌جای اینکه جزئیات مسیر را به اتاق مشترک برگرداند.

برای بررسی محلی یا جریان‌های کاری پشتیبانی، می‌توانید مسیر فرمان تأییدشده را مستقیماً نیز اجرا کنید:

openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .

# دسترسی

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

# چه چیزهایی ضبط می‌شود

ضبط مسیر به‌صورت پیش‌فرض برای اجرای عامل‌های OpenClaw فعال است.

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

• session.started
• trace.metadata
• context.compiled
• prompt.submitted
• model.fallback_step، شامل مدل مبدأ، مدل بعدی، دلیل/جزئیات خرابی، جایگاه در زنجیره، و اینکه fallback پیش رفته، موفق شده، یا زنجیره را تمام کرده است
• model.completed
• trace.artifacts
• session.ended

رویدادهای رونوشت نیز از شاخهٔ نشست فعال بازسازی می‌شوند:

• پیام‌های کاربر
• پیام‌های دستیار
• فراخوانی‌های ابزار
• نتایج ابزار
• Compactionها
• تغییرات مدل
• برچسب‌ها و ورودی‌های سفارشی نشست

رویدادها به‌صورت JSON Lines با این نشانگر schema نوشته می‌شوند:

{
  "traceSchema": "openclaw-trajectory",
  "schemaVersion": 1
}

# فایل‌های بسته

یک بستهٔ خروجی‌گرفته‌شده می‌تواند شامل این موارد باشد:

فایل	محتوا
manifest.json	schema بسته، فایل‌های مبدأ، شمار رویدادها، و فهرست فایل‌های تولیدشده
events.jsonl	خط زمانی مرتب‌شدهٔ زمان اجرا و رونوشت
session-branch.json	شاخهٔ رونوشت فعال ویرایش‌شده و سربرگ نشست
metadata.json	نسخهٔ OpenClaw، سیستم‌عامل/زمان اجرا، مدل، snapshot پیکربندی، Pluginها، Skills، و فرادادهٔ پرامپت
artifacts.json	وضعیت نهایی، خطاها، مصرف، کش پرامپت، شمار Compaction، متن دستیار، و فرادادهٔ ابزار
prompts.json	پرامپت‌های ارسال‌شده و جزئیات منتخب ساخت پرامپت
system-prompt.txt	آخرین پرامپت سیستمی کامپایل‌شده، در صورت ضبط شدن
tools.json	تعریف‌های ابزار ارسال‌شده به مدل، در صورت ضبط شدن

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

# محل ضبط

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

<session>.trajectory.jsonl

OpenClaw همچنین یک فایل اشاره‌گر best-effort کنار نشست می‌نویسد:

<session>.trajectory-path.json

OPENCLAW_TRAJECTORY_DIR را تنظیم کنید تا sidecarهای مسیر زمان اجرا در یک دایرکتوری اختصاصی ذخیره شوند:

export OPENCLAW_TRAJECTORY_DIR=/var/lib/openclaw/trajectories

وقتی این متغیر تنظیم شده باشد، OpenClaw برای هر شناسهٔ نشست یک فایل JSONL در آن دایرکتوری می‌نویسد.

نگهداشت نشست، sidecarهای مسیر را وقتی ورودی نشست مالک آن‌ها prune، capped، یا به‌دلیل بودجهٔ دیسک نشست‌ها evicted شود حذف می‌کند. فایل‌های زمان اجرا خارج از دایرکتوری نشست‌ها فقط وقتی حذف می‌شوند که هدف اشاره‌گر همچنان ثابت کند به آن نشست تعلق دارد.

# غیرفعال کردن ضبط

پیش از شروع OpenClaw، OPENCLAW_TRAJECTORY=0 را تنظیم کنید:

export OPENCLAW_TRAJECTORY=0

این کار ضبط مسیر زمان اجرا را غیرفعال می‌کند. /export-trajectory همچنان می‌تواند شاخهٔ رونوشت را خروجی بگیرد، اما فایل‌های فقط زمان اجرا مانند زمینهٔ کامپایل‌شده، artifactهای ارائه‌دهنده، و فرادادهٔ پرامپت ممکن است موجود نباشند.

# حریم خصوصی و محدودیت‌ها

بسته‌های مسیر برای پشتیبانی و اشکال‌زدایی طراحی شده‌اند، نه انتشار عمومی. OpenClaw پیش از نوشتن فایل‌های خروجی، مقدارهای حساس را ویرایش می‌کند:

• credentials و فیلدهای payload شناخته‌شده‌ای که شبیه secret هستند
• دادهٔ تصویر
• مسیرهای وضعیت محلی
• مسیرهای فضای کاری، که با $WORKSPACE_DIR جایگزین می‌شوند
• مسیرهای دایرکتوری خانه، در صورت تشخیص

خروجی‌گیر همچنین اندازهٔ ورودی را محدود می‌کند:

• فایل‌های sidecar زمان اجرا: ضبط زنده در 10 MiB متوقف می‌شود و وقتی فضا باقی بماند یک رویداد truncation ثبت می‌کند؛ خروجی‌گیری، sidecarهای زمان اجرای موجود را تا 50 MiB می‌پذیرد
• فایل‌های نشست: 50 MiB
• رویدادهای زمان اجرا: 200,000
• کل رویدادهای خروجی‌گرفته‌شده: 250,000
• خطوط منفرد رویداد زمان اجرا بالاتر از 256 KiB کوتاه می‌شوند

پیش از اشتراک‌گذاری بسته‌ها خارج از تیم خود، آن‌ها را بازبینی کنید. ویرایش best-effort است و نمی‌تواند هر secret اختصاصی برنامه را بشناسد.

# عیب‌یابی

اگر خروجی هیچ رویداد زمان اجرایی ندارد:

• تأیید کنید OpenClaw بدون OPENCLAW_TRAJECTORY=0 شروع شده است
• بررسی کنید آیا OPENCLAW_TRAJECTORY_DIR به یک دایرکتوری قابل نوشتن اشاره می‌کند
• پیام دیگری را در نشست اجرا کنید، سپس دوباره خروجی بگیرید
• manifest.json را برای runtimeEventCount بررسی کنید

اگر فرمان مسیر خروجی را رد می‌کند:

• از یک نام نسبی مانند bug-1234 استفاده کنید
• /tmp/... یا ~/... را پاس ندهید
• خروجی را داخل .openclaw/trajectory-exports/ نگه دارید

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

# مرتبط

• Diffها
• مدیریت نشست
• ابزار exec