---
read_when:
    - می‌خواهید بدانید عامل چه ابزارهای نشستی در اختیار دارد
    - می‌خواهید دسترسی بین‌نشستی یا ایجاد زیرعامل را پیکربندی کنید
    - می‌خواهید وضعیت را بررسی کنید یا زیرعامل‌های ایجادشده را کنترل کنید
summary: ابزارهای عامل برای وضعیت میان‌نشستی، بازیابی، پیام‌رسانی و هماهنگ‌سازی زیرعامل‌ها
title: ابزارهای نشست
x-i18n:
    generated_at: "2026-05-11T20:31:39Z"
    model: gpt-5.5
    provider: openai
    source_hash: e91f1f956ff882cabf7df51bd8c08836398decfb185c56c42db4052f24b3f716
    source_path: concepts/session-tool.md
    workflow: 16
---

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`) اما
ایجاد زیرعامل را شامل نمی‌شود. برای حفظ نمایه پیام‌رسانی و در عین حال
مجاز کردن واگذاری بومی، اضافه کنید:

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

سیاست‌های گروه، ارائه‌دهنده، سندباکس و هر عامل همچنان می‌توانند پس از مرحله
نمایه آن ابزارها را حذف کنند. از `/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` را تنظیم کنید تا پیام در صف قرار گیرد و
  بلافاصله برگردد.
- **انتظار برای پاسخ:** یک مهلت تنظیم کنید و پاسخ را درجا دریافت کنید.

نشست‌های گفت‌وگوی محدود به 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` کلید نشست نیستند.

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

`subagents` راهنمای صفحه کنترل برای زیرعامل‌های OpenClaw است که از قبل ایجاد
شده‌اند. پشتیبانی می‌کند از:

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

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

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

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

- `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 بسته‌شده را حفظ می‌کند، و اگر
مبدأ تکمیل فقط یک کانال را شناسایی کند، OpenClaw همچنان می‌تواند از مسیر ذخیره‌شده
نشست درخواست‌کننده (`lastChannel` / `lastTo`) برای تحویل مستقیم دوباره استفاده کند.

برای رفتار ویژه ACP، [عامل‌های ACP](/fa/tools/acp-agents) را ببینید.

## دید

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

| سطح   | دامنه                                    |
| ------- | ---------------------------------------- |
| `self`  | فقط نشست فعلی                 |
| `tree`  | نشست فعلی + زیرعامل‌های ایجادشده     |
| `agent` | همه نشست‌های این عامل              |
| `all`   | همه نشست‌ها (در صورت پیکربندی، بین عامل‌ها) |

پیش‌فرض `tree` است. نشست‌های سندباکس‌شده بدون توجه به پیکربندی به `tree` محدود
می‌شوند.

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

- [مدیریت نشست](/fa/concepts/session) -- مسیریابی، چرخه عمر، نگهداری
- [عامل‌های ACP](/fa/tools/acp-agents) -- ایجاد harness خارجی
- [چندعاملی](/fa/concepts/multi-agent) -- معماری چندعاملی
- [پیکربندی Gateway](/fa/gateway/configuration) -- گزینه‌های پیکربندی ابزار نشست

## مرتبط

- [مدیریت نشست](/fa/concepts/session)
- [هرس نشست](/fa/concepts/session-pruning)