ابزارهای جلسه

OpenClaw به عامل‌ها ابزارهایی می‌دهد تا بین جلسه‌ها کار کنند، وضعیت را بررسی کنند، و زیرعامل‌ها را هماهنگ کنند.

# ابزارهای در دسترس

ابزار	کاری که انجام می‌دهد
sessions_list	فهرست کردن جلسه‌ها با فیلترهای اختیاری (نوع، برچسب، عامل، تازگی، پیش‌نمایش)
sessions_history	خواندن رونوشت یک جلسه مشخص
sessions_send	فرستادن پیام به جلسه‌ای دیگر و در صورت نیاز منتظر ماندن
sessions_spawn	ایجاد یک جلسه زیرعامل جداافتاده برای کار پس‌زمینه
sessions_yield	پایان دادن به نوبت فعلی و منتظر ماندن برای نتایج پیگیری زیرعامل
subagents	فهرست کردن، هدایت کردن، یا کشتن زیرعامل‌های ایجادشده برای این جلسه
session_status	نمایش کارتی به سبک /status و در صورت نیاز تنظیم بازنویسی مدل برای هر جلسه

این ابزارها همچنان تابع نمایه ابزار فعال و سیاست اجازه/رد هستند. tools.profile: "coding" مجموعه کامل هماهنگ‌سازی جلسه را شامل می‌شود، از جمله sessions_spawn، sessions_yield، و subagents. tools.profile: "messaging" ابزارهای پیام‌رسانی بین‌جلسه‌ای را شامل می‌شود (sessions_list، sessions_history، sessions_send، session_status) اما ایجاد زیرعامل را شامل نمی‌شود. برای نگه داشتن نمایه پیام‌رسانی و همچنان اجازه دادن به واگذاری بومی، اضافه کنید:

{
  tools: {
    profile: "messaging",
    alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"],
  },
}

سیاست‌های گروه، ارائه‌دهنده، sandbox، و هر عامل همچنان می‌توانند پس از مرحله نمایه این ابزارها را حذف کنند. از جلسه متاثر، از /tools برای بررسی فهرست موثر ابزارها استفاده کنید.

# فهرست کردن و خواندن جلسه‌ها

sessions_list جلسه‌ها را با کلید، agentId، نوع، کانال، مدل، شمارش توکن‌ها، و مهرهای زمانی آن‌ها برمی‌گرداند. بر اساس نوع (main، group، cron، hook، node)، label دقیق، agentId دقیق، متن جست‌وجو، یا تازگی (activeMinutes) فیلتر کنید. وقتی به تریاژ به سبک صندوق پستی نیاز دارید، این ابزار همچنین می‌تواند برای هر ردیف یک عنوان مشتق‌شده در دامنه دید، یک قطعه پیش‌نمایش از آخرین پیام، یا پیام‌های اخیر محدودشده درخواست کند. عنوان‌ها و پیش‌نمایش‌های مشتق‌شده فقط برای جلسه‌هایی تولید می‌شوند که فراخواننده از قبل طبق سیاست پیکربندی‌شده دید ابزار جلسه می‌تواند ببیند، بنابراین جلسه‌های نامرتبط پنهان می‌مانند.

sessions_history رونوشت گفت‌وگو را برای یک جلسه مشخص دریافت می‌کند. به طور پیش‌فرض، نتایج ابزارها مستثنا می‌شوند؛ برای دیدن آن‌ها includeTools: true را ارسال کنید. نمای برگشتی عمدا محدود و با فیلتر ایمنی است:

• متن دستیار پیش از یادآوری نرمال‌سازی می‌شود:
  • برچسب‌های فکر کردن حذف می‌شوند
  • بلوک‌های داربست <relevant-memories> / <relevant_memories> حذف می‌شوند
  • بلوک‌های payload فراخوانی ابزار XML متن ساده مانند <tool_call>...</tool_call>، <function_call>...</function_call>، <tool_calls>...</tool_calls>، و <function_calls>...</function_calls> حذف می‌شوند، از جمله payloadهای ناقصی که هرگز تمیز بسته نمی‌شوند
  • داربست‌های تنزل‌یافته فراخوانی/نتیجه ابزار مانند [Tool Call: ...]، [Tool Result ...]، و [Historical context ...] حذف می‌شوند
  • توکن‌های کنترل مدل نشت‌کرده مانند <|assistant|>، سایر توکن‌های ASCII به شکل <|...|>، و گونه‌های تمام‌عرض <｜...｜> حذف می‌شوند
  • XML فراخوانی ابزار MiniMax بدشکل مانند <invoke ...> / </minimax:tool_call> حذف می‌شود
• متن‌های شبیه اعتبارنامه/توکن پیش از برگشت داده شدن پوشانده می‌شوند
• بلوک‌های متنی طولانی کوتاه می‌شوند
• تاریخچه‌های بسیار بزرگ می‌توانند ردیف‌های قدیمی‌تر را حذف کنند یا یک ردیف بیش‌ازحد بزرگ را با [sessions_history omitted: message too large] جایگزین کنند
• ابزار پرچم‌های خلاصه‌ای مانند truncated، droppedMessages، contentTruncated، contentRedacted، و bytes را گزارش می‌کند

هر دو ابزار یک کلید جلسه (مانند "main") یا یک شناسه جلسه از فراخوانی فهرست قبلی را می‌پذیرند.

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

# فرستادن پیام‌های بین‌جلسه‌ای

sessions_send پیامی را به جلسه‌ای دیگر تحویل می‌دهد و در صورت نیاز منتظر پاسخ می‌ماند:

• ارسال و فراموشی: timeoutSeconds: 0 را تنظیم کنید تا پیام در صف قرار بگیرد و بلافاصله برگردد.
• انتظار برای پاسخ: یک timeout تنظیم کنید و پاسخ را به صورت درون‌خطی دریافت کنید.

جلسه‌های گفت‌وگوی محدود به رشته، مانند کلیدهای Slack یا Discord که با :thread:<id> تمام می‌شوند، هدف‌های معتبر sessions_send نیستند. برای هماهنگی بین عامل‌ها از کلید جلسه کانال والد استفاده کنید تا پیام‌های مسیریابی‌شده توسط ابزار داخل یک رشته فعال روبه‌روی انسان ظاهر نشوند.

پیام‌ها و پاسخ‌های پیگیری A2A به عنوان داده بین‌جلسه‌ای در prompt گیرنده ([Inter-session message ... isUser=false]) و در منشأ رونوشت علامت‌گذاری می‌شوند. عامل گیرنده باید آن‌ها را داده مسیریابی‌شده توسط ابزار بداند، نه دستور مستقیم نوشته‌شده توسط کاربر نهایی.

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

# کمک‌کننده‌های وضعیت و هماهنگ‌سازی

session_status ابزار سبک‌وزن معادل /status برای جلسه فعلی یا جلسه قابل‌دید دیگر است. این ابزار مصرف، زمان، وضعیت مدل/زمان اجرا، و زمینه کار پس‌زمینه پیوندشده را در صورت وجود گزارش می‌کند. مانند /status، می‌تواند شمارنده‌های کم‌جزئیات توکن/cache را از آخرین ورودی مصرف رونوشت تکمیل کند، و model=default بازنویسی مخصوص هر جلسه را پاک می‌کند. برای جلسه فعلی فراخواننده از sessionKey="current" استفاده کنید؛ برچسب‌های قابل‌دید کلاینت مانند openclaw-tui کلید جلسه نیستند.

sessions_yield عمدا نوبت فعلی را پایان می‌دهد تا پیام بعدی بتواند رویداد پیگیری‌ای باشد که منتظرش هستید. پس از ایجاد زیرعامل‌ها، وقتی می‌خواهید نتایج تکمیل به جای ساختن حلقه‌های polling به عنوان پیام بعدی برسند، از آن استفاده کنید.

subagents کمک‌کننده control-plane برای زیرعامل‌های OpenClaw است که از قبل ایجاد شده‌اند. پشتیبانی می‌کند از:

• action: "list" برای بررسی اجراهای فعال/اخیر
• action: "steer" برای فرستادن راهنمایی پیگیری به فرزند در حال اجرا
• action: "kill" برای متوقف کردن یک فرزند یا all

# ایجاد زیرعامل‌ها

sessions_spawn به طور پیش‌فرض یک جلسه جداافتاده برای کار پس‌زمینه ایجاد می‌کند. این ابزار همیشه غیرمسدودکننده است؛ بلافاصله با یک runId و childSessionKey برمی‌گردد.

گزینه‌های کلیدی:

• runtime: "subagent" (پیش‌فرض) یا "acp" برای عامل‌های harness خارجی.
• بازنویسی‌های model و thinking برای جلسه فرزند.
• thread: true برای اتصال ایجاد به یک رشته گفت‌وگو (Discord، Slack، و غیره).
• sandbox: "require" برای اعمال sandboxing روی فرزند.
• context: "fork" برای زیرعامل‌های بومی وقتی فرزند به رونوشت درخواست‌کننده فعلی نیاز دارد؛ آن را حذف کنید یا از context: "isolated" برای یک فرزند تمیز استفاده کنید. زیرعامل‌های بومی محدود به رشته به طور پیش‌فرض context: "fork" دارند، مگر اینکه threadBindings.defaultSpawnContext چیز دیگری بگوید.

زیرعامل‌های برگ پیش‌فرض ابزارهای جلسه را دریافت نمی‌کنند. وقتی maxSpawnDepth >= 2 باشد، زیرعامل‌های هماهنگ‌کننده عمق ۱ علاوه بر آن sessions_spawn، subagents، sessions_list، و sessions_history را دریافت می‌کنند تا بتوانند فرزندان خودشان را مدیریت کنند. اجراهای برگ همچنان ابزارهای هماهنگ‌سازی بازگشتی دریافت نمی‌کنند.

پس از تکمیل، یک مرحله اعلام، نتیجه را به کانال درخواست‌کننده پست می‌کند. تحویل تکمیل، مسیریابی رشته/موضوع متصل را وقتی موجود باشد حفظ می‌کند، و اگر مبدأ تکمیل فقط یک کانال را شناسایی کند، OpenClaw همچنان می‌تواند از مسیر ذخیره‌شده جلسه درخواست‌کننده (lastChannel / lastTo) برای تحویل مستقیم دوباره استفاده کند.

برای رفتار مخصوص ACP، عامل‌های ACP را ببینید.

# دید

ابزارهای جلسه برای محدود کردن آنچه عامل می‌تواند ببیند دامنه‌بندی می‌شوند:

سطح	دامنه
self	فقط جلسه فعلی
tree	جلسه فعلی + زیرعامل‌های ایجادشده
agent	همه جلسه‌های این عامل
all	همه جلسه‌ها (بین‌عاملی اگر پیکربندی شده باشد)

پیش‌فرض tree است. جلسه‌های sandbox شده، صرف‌نظر از پیکربندی، به tree محدود می‌شوند.

# مطالعه بیشتر

• مدیریت جلسه -- مسیریابی، چرخه عمر، نگهداری
• عامل‌های ACP -- ایجاد harness خارجی
• چندعامله -- معماری چندعامله
• پیکربندی Gateway -- پیچ‌های پیکربندی ابزار جلسه

# مرتبط

• مدیریت جلسه
• هرس جلسه