ابزارهای نشست

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

ابزارهای موجود

این ابزارها همچنان تابع نمایه ابزار فعال و سیاست اجازه/رد هستند. 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"],  },}

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

فهرست‌کردن و خواندن نشست‌ها

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

sessions_history رونوشت گفت‌وگو را برای یک نشست مشخص دریافت می‌کند. به‌طور پیش‌فرض، نتایج ابزار حذف می‌شوند -- برای دیدن آن‌ها includeTools: true را ارسال کنید. برای جدیدترین دنباله محدودشده از limit استفاده کنید. وقتی به فراداده صفحه‌بندی نیاز دارید offset: 0 را ارسال کنید، سپس مقدارهای nextOffset برگشتی را ارسال کنید تا بدون خواندن فایل‌های خام رونوشت، در پنجره‌های قدیمی‌تر رونوشت OpenClaw به عقب صفحه‌بندی کنید. صفحه‌های دارای offset صریح، واردسازی‌های جایگزین CLI خارجی را ادغام نمی‌کنند؛ وقتی به آن تاریخچه نمایش ادغام‌شده نیاز دارید از نمای پیش‌فرض جدیدترین دنباله استفاده کنید. نمای برگشتی عمدا محدود و با فیلتر ایمنی است:

• متن دستیار پیش از یادآوری نرمال‌سازی می‌شود:
  • برچسب‌های تفکر حذف می‌شوند
  • بلوک‌های داربست <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 تنظیم کنید و پاسخ را درجا دریافت کنید.

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

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

پس از پاسخ‌دادن هدف، OpenClaw می‌تواند یک حلقه پاسخ‌برگشتی اجرا کند که در آن عامل‌ها به‌نوبت پیام ردوبدل می‌کنند (تا session.agentToAgent.maxPingPongTurns، بازه 0-20، پیش‌فرض 5). عامل هدف می‌تواند برای توقف زودهنگام REPLY_SKIP پاسخ دهد.

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

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

وقتی فراداده مسیر موجود باشد، session_status یک بلوک JSON قابل‌مشاهده Route context و فیلدهای ساخت‌یافته details متناظر را نیز شامل می‌شود. این فیلدها کلید نشست را از مسیری که اکنون اجرای زنده را مدیریت می‌کند متمایز می‌کنند:

• origin جایی است که نشست در آن ایجاد شده است، یا ارائه‌دهنده‌ای است که از پیشوند کلید نشست قابل‌تحویل استنباط شده، وقتی وضعیت قدیمی‌تر فراداده origin ذخیره‌شده ندارد.
• active مسیر اجرای زنده فعلی است. فقط برای نشست زنده یا فعلی که اکنون مدیریت می‌شود گزارش می‌شود.
• deliveryContext مسیر تحویل پایدارشده ذخیره‌شده روی نشست است که OpenClaw می‌تواند بعدا حتی وقتی سطح فعال متفاوت است برای تحویل دوباره استفاده کند.

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

subagents کمک‌کننده دیدپذیری برای زیرعامل‌های OpenClaw است که از پیش ایجاد شده‌اند. از action: "list" برای بررسی اجراهای فعال/اخیر پشتیبانی می‌کند.

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

sessions_spawn به‌طور پیش‌فرض یک نشست ایزوله برای یک کار پس‌زمینه ایجاد می‌کند. همیشه غیرمسدودکننده است -- بلافاصله با یک runId و childSessionKey برمی‌گردد. اجراهای زیرعامل بومی، کار واگذارشده را در نخستین پیام قابل‌مشاهده [Subagent Task] نشست فرزند دریافت می‌کنند، در حالی که prompt سیستم فقط قواعد زمان اجرای زیرعامل و زمینه مسیریابی را حمل می‌کند.

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

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

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

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

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

دیدپذیری

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

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

مطالعه بیشتر

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

مرتبط

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