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

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

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

این ابزارها همچنان تابع پروفایل ابزار فعال و سیاست مجاز/غیرمجاز هستند. tools.profile: "coding" شامل مجموعهٔ کامل هماهنگ‌سازی نشست است. tools.profile: "messaging" شامل خودخدمتی نشست، کشف، بازیابی، پیام‌رسانی میان‌نشستی، ابزارهای مکالمهٔ خارجی و چرخهٔ عمر کامل ایجاد زیرعامل (sessions_spawn، sessions_yield و subagents) است. ابزارهای پیشنهاد وظیفهٔ مختص رابط کاربری، یعنی spawn_task و dismiss_task، همچنان ابزارهای پروفایل کدنویسی باقی می‌مانند.

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

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

sessions_list ردیف‌های متمرکز کشف را بازمی‌گرداند: کلید نشست، عامل، نوع، کانال، فیلدهای برچسب/عنوان/پیش‌نمایش، روابط والد و فرزند، آخرین به‌روزرسانی، وضعیت بایگانی/سنجاق، نسخهٔ وضعیت، مدل، تعداد توکن‌های زمینه/کل، وضعیت اجرا و اینکه آیا آخرین اجرا متوقف شده است. بر اساس kinds (آرایه؛ مقادیر پذیرفته‌شده: main، group، cron، hook، node، other)، مقدار دقیق label، مقدار دقیق agentId، متن search یا تازگی (activeMinutes) فیلتر کنید. به‌طور پیش‌فرض نشست‌های فعال بازگردانده می‌شوند؛ برای بررسی نشست‌های بایگانی‌شده، به‌جای آن archived: true را ارسال کنید. هنگامی که به اولویت‌بندی به سبک صندوق ورودی نیاز دارید، includeDerivedTitles، includeLastMessage یا messageLimit (با سقف 20) را تنظیم کنید: عنوان مشتق‌شده با دامنهٔ دید، قطعهٔ پیش‌نمایش آخرین پیام یا پیام‌های اخیر محدودشده در هر ردیف. مسیریابی تحویل، شناسه‌های داخلی نشست، زمان‌بندی‌ها/تنظیمات هر اجرا، برآورد هزینه و مسیرهای رونوشت عمداً حذف شده‌اند؛ برای این جزئیات مختص مالک از session_status، ابزارهای مکالمه و sessions_history استفاده کنید. عنوان‌ها و پیش‌نمایش‌های مشتق‌شده فقط برای نشست‌هایی تولید می‌شوند که فراخواننده از قبل طبق سیاست پیکربندی‌شدهٔ مشاهده‌پذیری ابزار نشست قادر به دیدن آن‌هاست؛ بنابراین نشست‌های نامرتبط پنهان می‌مانند. وقتی مشاهده‌پذیری محدود است، sessions_list فرادادهٔ اختیاری visibility را بازمی‌گرداند که حالت مؤثر و هشداری دربارهٔ احتمال محدودبودن دامنهٔ نتایج را نشان می‌دهد.

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

نمای بازگردانده‌شده عمداً محدود و با فیلترهای ایمنی پالایش شده است:

• متن دستیار پیش از بازیابی عادی‌سازی می‌شود:
  • برچسب‌های تفکر حذف می‌شوند
  • بلوک‌های داربستی <relevant-memories> / <relevant_memories> حذف می‌شوند
  • بلوک‌های بار XML فراخوانی ابزار به‌صورت متن ساده، مانند <tool_call>...</tool_call>، <function_call>...</function_call>، <tool_calls>...</tool_calls> و <function_calls>...</function_calls>، از جمله بارهای ناقصی که هرگز به‌درستی بسته نمی‌شوند، حذف می‌شوند
  • داربست‌های تنزل‌یافتهٔ فراخوانی/نتیجهٔ ابزار، مانند [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، sessions_send و session_status استفاده کنید. این ابزارهای مقصد همچنین می‌توانند شناسهٔ شناخته‌شدهٔ نشست را حل کنند، اما sessions_list شناسه‌های داخلی را افشا نمی‌کند.

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

برای بازیابی دقیق متن کامل در متن رونوشت‌های قابل‌مشاهدهٔ کاربر و دستیار، از sessions_search استفاده کنید. نتایج آن یک sessionKey برای فراخوانی بعدی sessions_history دارند؛ فیلتر مشاهده‌پذیری، ویرایش قطعه‌ها و محدودیت‌های خروجی با مرز تاریخچه مطابقت دارند.

مدیریت تنظیمات و گروه‌های نشست

ابزار sessions که به مالک محدود شده است، دو سطح خودخدمتی محدود را ارائه می‌کند:

• action: "patch" به‌طور پیش‌فرض نشست جاری یا نشست قابل‌مشاهدهٔ دیگری را که با sessionKey انتخاب شده است تغییر می‌دهد. این ابزار می‌تواند برچسب، نماد نوار کناری، وضعیت سنجاق/بایگانی، مدل و سطح تفکر را تنظیم کند. کنش‌های بازنشانی، حذف یا فشرده‌سازی را ارائه نمی‌کند.
• group_list، group_set، group_rename و group_delete کاتالوگ مرتب سراسری گروه‌های نشست را مدیریت می‌کنند. group_set به‌جای وصله‌کردن یک ورودی، فهرست مرتب نام‌ها را جایگزین می‌کند.

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

نشست‌ها در برابر مکالمات

یک نشست زمینهٔ محلی مدل است. یک مکالمه نشانی خارجی دقیقی مانند یک همتا، کانال یا رشته است. این دو به هم پیوند دارند، اما قابل‌جایگزینی نیستند: پیام‌های مستقیم می‌توانند یک نشست main مشترک داشته باشند، درحالی‌که نشانی‌های مکالمهٔ جداگانهٔ خود را حفظ می‌کنند.

conversations_list مقادیر مبهم conversationRef را برای عامل فعال بازمی‌گرداند. با یک channel صریح، Gateway نشانی‌ها را از فهرست محلی آن کانال، مانند همتایان تأییدشدهٔ Reef، نیز تازه‌سازی می‌کند؛ برای یافتن همتایی مشخص فراتر از صفحهٔ فعلی نتایج از query استفاده کنید. کشف، نشانی را بدون ایجاد نشست زمینهٔ مدل در کاتالوگ ثبت می‌کند؛ نشست پشتیبان فقط زمانی ایجاد می‌شود که تحویل یا زمینهٔ ورودی به آن نیاز داشته باشد. کشف و تحویل مکالمه فقط برای مالک مجاز است، زیرا از اعتبارنامه‌های کانال Gateway استفاده می‌کند. برای تحویل بدون انتظار پاسخ از conversations_send استفاده کنید. هنگامی که پاسخ راه‌دور متعلق به نوبت فعلی مدل است، از conversations_turn استفاده کنید: Gateway یک شناسهٔ پیام انتقال را رزرو می‌کند، پیش از ورودی/خروجی انتقال یک عملیات تحویل و قصد صف را پایدار می‌کند و به‌جای آغاز نوبت دوم عامل محلی، پاسخ هم‌بسته را از ابزار بازمی‌گرداند. عملیات تحویل خارج از رونوشت‌های مدل قرار دارند؛ پاسخ ثبت‌شده تنها به‌عنوان یک مصنوع جانبی نگه‌داری می‌شود، درحالی‌که نتیجهٔ ابزار مالک زمینهٔ مدل است. اگر Gateway پس از صف‌گذاری دوباره راه‌اندازی شود، تحویل قابل‌بازیابی است، اما پاسخ بعدی از مسیر عادی توزیع ورودی پیروی می‌کند، زیرا منتظر محلی فرایند از بین رفته است. پیام‌های ورودی ناخواسته همیشه از مسیر عادی توزیع کانال ادامه می‌یابند.

هنگامی که از قبل مقصد خام و صریح کانال را دارید یا به کنشی مختص کانال نیاز دارید، از ابزار مشترک message استفاده کنید. ارجاع‌های مکالمه به عامل فعال محدود هستند و باید از طریق conversations_list به‌دست آیند، نه اینکه از کلیدهای نشست ساخته شوند.

در حالت کد، ابزارهای مکالمه دقیقاً از قراردادهای خروجی Gateway خود استفاده می‌کنند. یک سلول exec می‌تواند نشانی‌ها را فهرست کند، یک conversationRef بازگردانده‌شده را انتخاب کند و conversations_send یا conversations_turn را فراخوانی کند؛ سیاست عادی ابزار و تأییدها همچنان بر فراخوانی‌های تو‌در‌تو اعمال می‌شوند.

ارسال پیام‌های میان‌نشستی

sessions_send نشست دیگری را روی همان Gateway اجرا می‌کند و به‌صورت اختیاری منتظر پاسخ می‌ماند. sessionKey، label یا agentId آن زمینهٔ محلی مدل را انتخاب می‌کند، نه مقصدی خارجی را. پاسخ حاصل همچنان می‌تواند از طریق زمینهٔ تحویل تثبیت‌شدهٔ درخواست‌کننده یا مقصد اعلام شود؛ این رفتار موجود بدون تغییر باقی می‌ماند. برای تحویل خارجی دقیق، از یک ابزار مکالمه یا message همراه با کانال و مقصد صریح استفاده کنید.

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

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

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

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

برای ثبت فرستنده به‌عنوان ناظر تغییر وضعیت مقصد نیز watch: true را ارسال کنید: وقتی کنشگر دیگری بعداً یک پیام مستقیم انسانی برای مقصد می‌فرستد یا هدف آن را تغییر می‌دهد، فرستنده یک اعلان سیستمی دریافت می‌کند که به session_status changesSince اشاره دارد. ثبت پس از ارسال موفق انجام می‌شود، نشست واقعی دریافت‌کنندهٔ پیام را هدف می‌گیرد و از نسخهٔ وضعیت فعلی آن آغاز می‌شود؛ بنابراین فقط تغییرات بعدی اعلان ایجاد می‌کنند. نتیجه هنگام موفقیت ثبت، watched: true را گزارش می‌کند. آگاهی از وضعیت نشست را ببینید.

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

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

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

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

تغییرات وضعیت نشست

OpenClaw یک گزارش پایدار از سیگنال‌های تغییرات مهم وضعیت نشست نگه می‌دارد (پیام‌های مستقیم انسانی به نشست‌های تحت نظارت، نتایج اجرای فرزند، تغییرات هدف، Compaction). ردیف‌های sessions_list و session_status مقدار stateVersion نشست را ارائه می‌کنند، و session_status مقدار changesSince: <version> را می‌پذیرد تا رویدادهای نوع‌دار پس از آن نسخه را بازگرداند؛ اگر نسخهٔ درخواستی مربوط به پیش از تاریخچهٔ نگه‌داری‌شده باشد، این موضوع با historyGap به‌طور دقیق اعلام می‌شود. ناظران — والدهای ایجادکننده به‌صورت خودکار و sessions_send watch: true به‌صورت صریح — هنگامی که کنشگر دیگری یک نشست تحت نظارت را تغییر دهد، یک اعلان تجمیع‌شدهٔ وضعیت منقضی دریافت می‌کنند.

رویدادهای تغییر وضعیت، شناسه‌های تکراری نشست/عامل را حذف می‌کنند و فقط فیلدهای محمولهٔ مفید برای مدل (outcome، channel یا turns) را ارائه می‌دهند. خلاصهٔ رویداد و شناسه‌های کنشگر/اجرا برای تطبیق همچنان در دسترس می‌مانند.

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

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

subagents نمای درخت نشست بر اجراهای بومی زیرعامل و دفتر مشترک وظایف پس‌زمینه است. action: "list" زیرعامل‌های فعال/اخیر را همراه با وظایف محدوده‌بندی‌شدهٔ ACP، CLI/رسانه و Cron گزارش می‌کند. action: "cancel" یک taskId بازگردانده‌شده را می‌پذیرد و فقط می‌تواند کارهای درون درخت نشست تحت کنترل فراخواننده را متوقف کند؛ زیرعامل‌های برگ نمی‌توانند وظیفهٔ نشست دیگری را لغو کنند.

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

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

گزینه‌های اصلی:

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

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

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

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

قابلیت مشاهده

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

پیش‌فرض tree است. نشست‌های سندباکس‌شده، بدون توجه به پیکربندی، به tree محدود می‌شوند. با session.dmScope: "main" پیش‌فرض، فعالیت گروه باعث می‌شود نشست‌های گروهی تحت نظارت همان عامل از نشست اصلی قابل‌خواندن باشند.

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

• مدیریت نشست: مسیریابی، چرخهٔ عمر، نگه‌داری
• زیرعامل‌ها: چرخهٔ عمر نشست فرزند و تحویل
• عامل‌های ACP: ایجاد مهار خارجی
• چندعاملی: معماری چندعاملی
• پیکربندی Gateway: گزینه‌های پیکربندی ابزار نشست

مرتبط

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