---
read_when:
    - اشکال‌زدایی وضعیت زنده در صفحه دستگاه‌های رابط کاربری کنترل
    - بررسی ردیف‌های نمونهٔ تکراری یا منقضی‌شده
    - تغییر اتصال WS در Gateway یا بیکن‌های رویداد سیستمی
summary: نحوه تولید، ادغام و نمایش ورودی‌های حضور OpenClaw
title: حضور
x-i18n:
    generated_at: "2026-07-27T15:05:48Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: ac5800eebddb82e69a7d0c06733e6a19addbc57be7776e7361411866af0c60f5
    source_path: concepts/presence.md
    workflow: 16
---

«حضور» در OpenClaw نمایی سبک‌وزن و مبتنی بر بهترین تلاش از موارد زیر است:

- خود **Gateway**، و
- **کلاینت‌های قابل‌مشاهده برای کاربر که به Gateway متصل‌اند** (برنامه Mac، WebChat، نودها و غیره)

حضور، فرادادهٔ زندهٔ اتصال را در صفحهٔ **Devices** در رابط کنترل
(در مسیر **Settings → Devices**) و زبانهٔ **Instances** در برنامهٔ macOS نمایش می‌دهد.

این صفحه فهرست کلاینت‌های Gateway را پوشش می‌دهد. برای تشخیص Mac که اخیراً
از آن استفاده کرده‌اید و هدایت هشدارهای نود به آن، به
[حضور رایانهٔ فعال](/fa/nodes/presence) مراجعه کنید.

## فیلدهای حضور (آنچه نمایش داده می‌شود)

ورودی‌های حضور، اشیایی ساخت‌یافته با فیلدهایی مانند موارد زیر هستند:

- `instanceId` (اختیاری، اما اکیداً توصیه می‌شود): هویت پایدار کلاینت (معمولاً `connect.client.instanceId`)
- `host`: نام میزبان خوانا برای انسان
- `ip`: آدرس IP مبتنی بر بهترین تلاش
- `version`: رشتهٔ نسخهٔ کلاینت
- `deviceFamily` / `modelIdentifier`: اطلاعات راهنمای سخت‌افزار
- `mode`: `ui`، `webchat`، `cli`، `backend`، `node`، `probe`، `test`
- `lastInputSeconds`: تعداد ثانیه‌های سپری‌شده از آخرین ورودی کاربر، در صورت مشخص‌بودن
- `reason`: رشته‌ای با قالب آزاد که کلاینت ارائه می‌کند؛ خود Gateway فقط `self`، `connect` و `disconnect` را منتشر می‌کند
- `deviceId`، `roles`، `scopes`: هویت دستگاه و اطلاعات راهنمای نقش/دامنه از دست‌دهی اتصال
- `ts`: مُهر زمانی آخرین به‌روزرسانی (میلی‌ثانیه از مبدأ زمان)

## تولیدکنندگان (حضور از کجا می‌آید)

ورودی‌های حضور توسط چند منبع تولید و **ادغام** می‌شوند.

### 1) ورودی خود Gateway

Gateway همیشه هنگام راه‌اندازی یک ورودی «خود» ایجاد می‌کند تا رابط‌های کاربری میزبان Gateway را
حتی پیش از اتصال هر کلاینتی نمایش دهند.

### 2) اتصال WebSocket

هر کلاینت WS با یک درخواست `connect` آغاز می‌کند. پس از دست‌دهی موفق،
Gateway یک ورودی حضور را برای آن اتصال درج یا به‌روزرسانی می‌کند.

#### چرا اتصال‌های موقت صفحهٔ کنترل نمایش داده نمی‌شوند

فرمان‌های CLI، کلاینت‌های RPC سمت بک‌اند و کاوشگرها اغلب برای مدت کوتاهی متصل می‌شوند. برای جلوگیری از
نگه‌داشتن این تغییرات سریع در تمام مدت TTL حضور، کلاینت‌های دارای حالت `cli`، `backend`
یا `probe` به ورودی حضور تبدیل **نمی‌شوند**. کلاینت‌های حالت آزمون
همچنان ردیابی می‌شوند، زیرا مجموعه‌آزمون‌ها از آن‌ها به‌عنوان جایگزین کلاینت‌های واقعی استفاده می‌کنند.

### 3) بیکن‌های `system-event`

کلاینت‌ها می‌توانند از طریق متد `system-event` بیکن‌های دوره‌ای غنی‌تری ارسال کنند. برنامهٔ Mac
از این قابلیت برای گزارش نام میزبان، IP، نسخه و فرادادهٔ زنده‌بودن استفاده می‌کند. فعالیت
ورودی فیزیکی بخشی از این بیکن عمومی نیست؛ رویداد بومی نود با هدف مشخص که
در [حضور رایانهٔ فعال](/fa/nodes/presence) شرح داده شده است، مالک آن است. Mac این
بیکن‌ها را با `system-presence-clear-last-input` برچسب‌گذاری می‌کند؛ Gatewayهای فعلی
از این نشانگر سازگار با گذشته استفاده می‌کنند تا هرگونه تازگی ورودی باقی‌مانده از
برنامه‌ای قدیمی را حذف کنند. این بیکن همچنین یک مقدار ثابت 30روزه حمل می‌کند تا Gatewayهای قدیمی که
برچسب را نادیده می‌گیرند، به‌جای نگه‌داشتن تازگی دقیق، آن را بازنویسی کنند. هیچ فعالیت جدیدی
برای این مقدار سازگاری نمونه‌برداری نمی‌شود.

### 4) اتصال نودها (نقش: نود)

وقتی نودی با `role: node` از طریق WebSocket مربوط به Gateway متصل می‌شود، Gateway
یک ورودی حضور برای آن نود درج یا به‌روزرسانی می‌کند (همان جریان سایر کلاینت‌های WS).

## قواعد ادغام و حذف موارد تکراری (چرا `instanceId` اهمیت دارد)

ورودی‌های حضور در یک نگاشت واحد در حافظه ذخیره می‌شوند که کلید آن، بدون حساسیت به بزرگی و کوچکی حروف،
به‌ترتیب نخستین مورد موجود از این موارد است: شناسهٔ دستگاه جفت‌شده، `connect.client.instanceId`
یا در آخرین حالت، شناسهٔ مختص هر اتصال.

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

## TTL و اندازهٔ محدود

حضور عمداً موقتی است:

- **TTL:** ورودی‌های قدیمی‌تر از 5 دقیقه حذف می‌شوند
- **حداکثر ورودی‌ها:** 200 (ابتدا قدیمی‌ترین‌ها حذف می‌شوند)

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

## ملاحظهٔ اتصال دوردست/تونل (IPهای loopback)

وقتی کلاینتی از طریق تونل SSH / هدایت درگاه محلی متصل می‌شود، Gateway
ممکن است آدرس دوردست را به‌صورت `127.0.0.1` ببیند. برای جلوگیری از ثبت آن آدرس تونل
به‌عنوان IP کلاینت، مدیریت اتصال برای کلاینت‌هایی که محلی تشخیص داده می‌شوند (loopback)،
به‌جای نوشتن آدرس loopback در ورودی، `ip` را به‌طور کامل حذف می‌کند.

## مصرف‌کنندگان

### صفحهٔ Devices در رابط کنترل

صفحهٔ **Devices**، `system-presence` را با سوابق پایدار جفت‌سازی و نود
ترکیب می‌کند. این صفحه بیکن خود Gateway را در ابتدا سنجاق می‌کند و برای فرادادهٔ زندهٔ پلتفرم،
نسخه، مدل و تازگی ورودی از شناسه‌های منطبق دستگاه یا نمونه استفاده می‌کند.

### زبانهٔ Instances در macOS

برنامهٔ macOS خروجی `system-presence` را نمایش می‌دهد و بر اساس سن آخرین به‌روزرسانی،
یک نشانگر وضعیت کوچک (فعال/بی‌کار/کهنه) اعمال می‌کند.

## نکات اشکال‌زدایی

- برای دیدن فهرست خام، `system-presence` را در Gateway فراخوانی کنید.
- اگر موارد تکراری مشاهده می‌کنید:
  - تأیید کنید کلاینت‌ها در دست‌دهی یک `client.instanceId` پایدار ارسال می‌کنند
  - تأیید کنید بیکن‌های دوره‌ای از همان `instanceId` استفاده می‌کنند
  - بررسی کنید آیا ورودی مشتق‌شده از اتصال فاقد `instanceId` است (وجود موارد تکراری مورد انتظار است)

## مرتبط

<CardGroup cols={2}>
  <Card title="حضور رایانهٔ فعال" href="/fa/nodes/presence" icon="computer-mouse">
    نحوهٔ انتخاب نود فعال توسط ورودی فیزیکی Mac و هدایت هشدارهای اتصال.
  </Card>
  <Card title="نشانگرهای تایپ" href="/fa/concepts/typing-indicators" icon="ellipsis">
    زمان ارسال نشانگرهای تایپ و نحوهٔ تنظیم آن‌ها.
  </Card>
  <Card title="جریان‌دهی و قطعه‌بندی" href="/fa/concepts/streaming" icon="bars-staggered">
    جریان‌دهی خروجی، قطعه‌بندی و قالب‌بندی مختص هر کانال.
  </Card>
  <Card title="معماری Gateway" href="/fa/concepts/architecture" icon="diagram-project">
    مؤلفه‌های Gateway و پروتکل WebSocket که به‌روزرسانی‌های حضور را هدایت می‌کند.
  </Card>
  <Card title="پروتکل Gateway" href="/fa/gateway/protocol" icon="plug">
    پروتکل روی سیم برای `connect`، `system-event` و `system-presence`.
  </Card>
</CardGroup>
