---
read_when:
    - می‌خواهید عامل‌ها متوجه شوند که انسان‌ها یا عامل‌های دیگر، بدون اطلاع آن‌ها، یک نشست را تغییر می‌دهند
    - در حال اشکال‌زدایی اعلان‌های تغییر وضعیت، مکان‌نماهای پایش یا `changesSince` در `session_status` هستید
    - می‌خواهید بدانید عامل‌های والد چگونه با نشست‌های فرزند همگام می‌مانند
sidebarTitle: Session state awareness
summary: 'گزارش پایدار سیگنال‌های وضعیت نشست: نسخه‌های وضعیت، ناظرها، اعلان‌های وضعیت منسوخ و همگام‌سازی'
title: آگاهی از وضعیت نشست
x-i18n:
    generated_at: "2026-07-16T16:06:27Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: bb4126a0802e1ca4418f225c792490493a78886089b81c3b4567f72090ce34f4
    source_path: concepts/session-state.md
    workflow: 16
---

وقتی چند نشست روی یک مسئله کار می‌کنند — مدیری که کار را به فرزندان واگذار می‌کند، انسانی که مستقیماً وارد نشست یک عامل اجرایی می‌شود، یا دو عامل که از طریق [`sessions_send`](/fa/concepts/session-tool) هماهنگ می‌شوند — هر نشست درباره دیگران فرض‌هایی می‌سازد. به‌محض دخالت بازیگری دیگر، آن فرض‌ها منسوخ می‌شوند. آگاهی از وضعیت نشست سازوکاری است که این دخالت را تشخیص می‌دهد، یک‌بار نشست متأثر را مطلع می‌کند و راهی کم‌هزینه در اختیارش می‌گذارد تا پیش از اقدام، خود را به‌روز کند.

سه بخش با هم کار می‌کنند:

1. یک **گزارش پایدار سیگنال‌ها** تغییرات وضعیت منتخب را برای هر نشست ثبت می‌کند.
2. **ناظران** مکان‌نماهای مختص هر هدف را نگه می‌دارند و یک اعلان تجمیع‌شده درباره وضعیت منسوخ دریافت می‌کنند.
3. **همگام‌سازی مجدد** اختلاف دقیق را از طریق `session_status` با `changesSince` دریافت می‌کند.

## گزارش سیگنال‌ها

وقتی یک نشست تحت نظارت به‌طور معناداری تغییر می‌کند، OpenClaw یک رویداد نوع‌دار را به پایگاه داده وضعیت مشترک (`session_state_events`) می‌افزاید. رویدادها حاوی فراداده و خلاصه‌ای یک‌خطی هستند — هرگز محتوای پیام را شامل نمی‌شوند.

| نوع                   | زمان ثبت                                            | اطلاع‌رسانی به ناظران |
| ---------------------- | -------------------------------------------------------- | ----------------- |
| `human_direct_message` | یک انسان مستقیماً نوبتی را به نشست تحت نظارت ارسال می‌کند       | بله               |
| `upstream_missing`     | منبع بالادستی یک نشست پذیرفته‌شده ناپدید می‌شود          | بله               |
| `goal_changed`         | وضعیت هدف نشست ایجاد، به‌روزرسانی یا پاک می‌شود | بله               |
| `child_spawned`        | نشست فرزندِ یک زیرعامل یا ACP ایجاد می‌شود              | خیر (مکان‌نما مقداردهی اولیه می‌شود) |
| `run_completed`        | اجرای فرزند با موفقیت پایان می‌یابد                            | خیر (فقط ثبت در گزارش)     |
| `run_failed`           | اجرای فرزند شکست می‌خورد، مهلتش تمام می‌شود یا لغو می‌شود            | خیر (فقط ثبت در گزارش)     |
| `compacted`            | تاریخچه نشست Compaction می‌شود                       | خیر (فقط ثبت در گزارش)     |
| `adopted`              | یک نشست فهرست در OpenClaw پذیرفته می‌شود               | خیر (فقط ثبت در گزارش)     |

هر رویداد بازیگر خود را (`human`، `agent` یا `system`) مشخص می‌کند. اجراهای فرزند لغوشده و زمان‌تمام‌شده به‌عنوان شکست ثبت می‌شوند و نتیجه دقیق (`cancelled`، `timeout` یا `error`) در داده رویداد حفظ می‌شود.

**نسخه وضعیت** یک نشست صرفاً بالاترین شماره توالی در گزارش آن است که در یک سرآیند پایدار مختص نشست ردیابی می‌شود و پس از هرس نیز باقی می‌ماند. ردیف‌های `sessions_list`، وقتی نشستی تغییرات ثبت‌شده داشته باشد، شامل `stateVersion` هستند؛ `session_status` همیشه آن را گزارش می‌کند.

نوع‌های فقط‌گزارشی برای تاریخچه همگام‌سازی مجدد وجود دارند، نه اطلاع‌رسانی: تحویل عادی تکمیل اجرای فرزند همچنان در اختیار [اعلان‌های زیرعامل](/fa/tools/subagents) است و گزارش سیگنال‌ها هرگز آن را تکرار نمی‌کند.

## ناظران

ناظر نشستی است که یک مکان‌نما (`session_watch_cursors`) روی هدف نگه می‌دارد. مکان‌نماها از دو محل ایجاد می‌شوند:

- **ضمنی (یال‌های ایجاد).** وقتی یک نشست زیرعامل یا فرزند ACP ایجاد می‌کند، مکان‌نمای والد به‌طور خودکار روی نسخه زمان ایجاد فرزند مقداردهی اولیه می‌شود. والدها هرگز به‌صورت دستی مشترک نمی‌شوند.
- **صریح (`sessions_send watch: true`).** هر هماهنگ‌کننده‌ای می‌تواند هدفی را که خود ایجاد نکرده است نظارت کند: در `sessions_send` مقدار `watch: true` را ارسال کنید؛ پس از ارسال موفق پیام، فرستنده به‌عنوان ناظر نشستی ثبت می‌شود که واقعاً پیام را دریافت کرده است. ثبت از نسخه وضعیت فعلی هدف آغاز می‌شود — تاریخچه پیشین هرگز اعلان ایجاد نمی‌کند. وقتی پارامتر تنظیم شده باشد، نتیجه ابزار `watched: true|false` را گزارش می‌کند.

هویت ناظر باید یک کلید نشست واجد شناسه عامل باشد. در `session.scope="global"`، کلید مشترک `global` میان عامل‌ها مبهم است؛ بنابراین چنین نشست‌هایی گزارش پایدار و `changesSince` را دریافت می‌کنند، اما اعلان پیش‌دستانه‌ای نمی‌گیرند.

نظارت‌ها خودکار پاک‌سازی می‌شوند: ردیف‌های مکان‌نما هم‌زمان با دوره نگهداری گزارش سیگنال منقضی می‌شوند، هنگام بازنشانی نشست ناظر حذف می‌شوند و با حذف هر یک از دو نشست نیز پاک می‌شوند. در v1 فعلی برای لغو نظارت وجود ندارد.

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

اگر منبع بالادستی یک نشست پذیرفته‌شده به‌صورت خارجی حذف شود، سه بررسی ناموفق متوالی (حدود سه تیک پایش) یک سیگنال `upstream_missing` برای ناظران آن ایجاد می‌کند و پیوند بالادستی را حذف می‌کند. ادامه دوباره نشست فهرست، پیوند تازه‌ای ایجاد می‌کند.

## اعلان‌ها: یکی، نه چندتا

وقتی رویدادی واجد شرایط اطلاع‌رسانی ثبت شود و مکان‌نمای ناظر عقب‌تر باشد، ناظر در نوبت بعدی خود یک اعلان سیستمی دریافت می‌کند:

```
نشست "agent:main:subagent:child" تغییر کرد (بازیگر دیگر). پیش از اقدام همگام‌سازی مجدد کنید: session_status sessionKey "agent:main:subagent:child" changesSince 12.
```

ناظران نشست اصلی نیز بلافاصله با یک بیدارباش Heartbeat فعال می‌شوند؛ ناظران زیرعامل تو‌در‌تو اعلان را در نوبت بعدی خود دریافت می‌کنند.

پروتکل عمداً ضد هرزآگهی است:

- **یک اعلان در انتظار برای هر جفت ناظر/هدف.** متن اعلان تا زمانی که در انتظار است از نظر بایتی ثابت می‌ماند و صف رویداد سیستمی آن را تکرارزدایی می‌کند؛ بنابراین حتی بیست تغییر سریع در یک هدف نیز فقط یک خط در اعلان ناظر ایجاد می‌کند.
- **نقطه اوج ثابت.** وقتی اعلان در صف قرار می‌گیرد، مکان‌نما موقعیت اطلاع‌داده‌شده خود را ثابت نگه می‌دارد. رویدادهای معنادار بعدی فقط نقطه اوج معنادار را جلو می‌برند؛ آن‌ها دوباره اعلان نمی‌کنند.
- **تأیید هنگام تخلیه، بازگشایی فقط برای کارهای میان‌لایه‌ای.** وقتی نوبت ناظر اعلان را مصرف می‌کند، مکان‌نما جلو می‌رود. اگر میان صف‌شدن و تخلیه، رویدادهای معنادار بیشتری رسیده باشند، دقیقاً یک اعلان تازه برای باقی‌مانده باز می‌شود.
- **سرکوب خودی.** ناظر هرگز درباره رویدادهایی که خودش ایجاد کرده است مطلع نمی‌شود.
- **بازیابی پس از راه‌اندازی مجدد.** اعلان‌های در انتظار در یک صف درون‌حافظه‌ای قرار دارند؛ پس از راه‌اندازی مجدد Gateway، یک پیمایش آغازین آن‌ها را از مکان‌نماهای پایدار دوباره ایجاد می‌کند.

## همگام‌سازی مجدد

اعلان دقیقاً به ناظر می‌گوید چه کاری انجام دهد. `session_status` با `changesSince: <version>` رویدادهای نوع‌دار پس از آن نسخه را (حداکثر 200 مورد) بدون جلو بردن هیچ مکان‌نمایی برمی‌گرداند:

```json
{
  "stateVersion": 19,
  "stateChanges": {
    "events": [
      {
        "sequence": 14,
        "kind": "human_direct_message",
        "actorType": "human",
        "summary": "پیام انسانی از طریق telegram"
      },
      { "sequence": 19, "kind": "goal_changed", "actorType": "human", "summary": "هدف به‌روزرسانی شد" }
    ],
    "historyGap": false
  }
}
```

`historyGap: true` یعنی نسخه درخواستی قدیمی‌تر از تاریخچه نگهداری‌شده است — به‌جای درنظرگرفتن پاسخ به‌عنوان اختلاف دقیق، کل وضعیت نشست (`sessions_history`، `session_status`) را تازه‌سازی کنید. سیگنال شکاف دقیق است: این سیگنال از یک نقطه اوج هرس‌شده مختص نشست می‌آید و از محاسبات توالی استنتاج نمی‌شود.

## ذخیره‌سازی و محدودیت‌ها

تاریخچه در پایگاه داده وضعیت مشترک نگهداری می‌شود و به 30 روز و 50,000 ردیف محدود است؛ سرآیندهای مختص نشست پس از هرس نیز یکنواخت صعودی باقی می‌مانند. ثبت به‌صورت بهترین‌تلاش انجام می‌شود — افزودن ناموفق ثبت می‌شود و هرگز نوبت مبدأ را با شکست مواجه نمی‌کند — بنابراین `stateVersion` یک سرآیند گزارش سیگنال است، نه نسخه ثبت تغییرات داده‌ای تراکنشی.

محدودیت‌های فعلی:

- تحویل اعلان فرض می‌کند یک فرایند Gateway مالک پایگاه داده وضعیت مشترک است. چند Gateway گزارش پایدار و `changesSince` را به اشتراک می‌گذارند، اما v1 اعلان‌ها را میان فرایندها ارسال نمی‌کند.
- رویدادهای Compaction مالکان Compaction زمان‌اجرای توکار را پوشش می‌دهند؛ Compaction مختص مهار بومی به‌طور کامل ثبت نمی‌شود.
- جزئیات داده نتیجه لغوشده در حال حاضر توسط اجراهای فرزند ACP تولید می‌شود؛ لغوهای زیرعامل بومی به‌صورت شکست‌های عمومی نمایش داده می‌شوند.
- تشخیص بازتاب خودی بالادستی، متن عادی‌سازی‌شده کاربر را مقایسه می‌کند. پرامپت خارجی که با یکی از 10 پیام اخیر کاربر در سمت OpenClaw نشست مطابقت داشته باشد، بازتاب خودی در نظر گرفته می‌شود.
- یک ردیف محلی Claude JSONL بزرگ‌تر از سقف پیمایش 1 MiB در هر تناوب، مکان‌نمای آن نشست را در v1 مسدود می‌کند؛ بایت‌های طبقه‌بندی‌نشده هرگز نادیده گرفته نمی‌شوند.
- بررسی‌های Claude در Node جفت‌شده، آخرین 50 مورد رونوشت را در هر تناوب طبقه‌بندی می‌کنند. جهش‌های بزرگ‌تر ممکن است خارج از پنجره پیمایش v1 قرار بگیرند.
- خواندن تاریخچه Claude در Node جفت‌شده نتیجه قطعی برای پیدانشدن رشته گفتگو ارائه نمی‌کند؛ بنابراین حذف‌های راه‌دور Claude در v1 به‌عنوان `upstream_missing` طبقه‌بندی نمی‌شوند.
- نشست‌های فهرستی که پذیرفته نشده‌اند، در v1 خارج از لایه آگاهی باقی می‌مانند.
- نشست‌هایی که پیش از این قابلیت پذیرفته شده‌اند، هیچ پیوند بالادستی ندارند؛ یک‌بار آن‌ها را از فهرست ادامه دهید تا پایش بالادستی آغاز شود.
- پیوندهای بالادستی فرض می‌کنند هر کلید نشست پذیرفته‌شده به یک عامل مالک نگاشت می‌شود (پذیرش از عامل پیش‌فرض مخزن استفاده می‌کند). پذیرش چندعاملی یک رشته خارجی یکسان در v1 پایش نمی‌شود.

## مرتبط

- [ابزارهای نشست](/fa/concepts/session-tool) — `sessions_send`، `session_status`، `sessions_list`
- [زیرعامل‌ها](/fa/tools/subagents) — یال‌های ایجاد و اعلان‌های تکمیل
- [Heartbeat](/fa/gateway/heartbeat) — نحوه بیدارکردن نشست‌های اصلی توسط اعلان‌های صف‌شده
- [مدیریت نشست](/fa/concepts/session) — کلیدها، دامنه‌ها و چرخه عمر نشست