---
read_when:
    - اشکال‌زدایی زبانه نمونه‌ها
    - بررسی ردیف‌های نمونهٔ تکراری یا قدیمی
    - تغییر اتصال WS در Gateway یا بیکن‌های system-event
summary: نحوه تولید، ادغام و نمایش ورودی‌های حضور OpenClaw
title: حضور
x-i18n:
    generated_at: "2026-04-29T22:45:06Z"
    model: gpt-5.5
    provider: openai
    source_hash: 2f33a7d4a3d5e5555c68a7503b3a4f75c12db94d260e5546cfc26ca8a12de0f9
    source_path: concepts/presence.md
    workflow: 16
---

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

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

حضور عمدتا برای نمایش زبانه **Instances** در برنامه macOS و فراهم کردن
دید سریع برای اپراتور استفاده می‌شود.

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

ورودی‌های حضور آبجکت‌های ساختاریافته‌ای با فیلدهایی مانند این‌ها هستند:

- `instanceId` (اختیاری اما قویا توصیه می‌شود): هویت پایدار کلاینت (معمولا `connect.client.instanceId`)
- `host`: نام میزبان خوانا برای انسان
- `ip`: نشانی IP با رویکرد بهترین تلاش
- `version`: رشته نسخه کلاینت
- `deviceFamily` / `modelIdentifier`: راهنماهای سخت‌افزاری
- `mode`: `ui`, `webchat`, `cli`, `backend`, `probe`, `test`, `node`, ...
- `lastInputSeconds`: «ثانیه از آخرین ورودی کاربر» (اگر معلوم باشد)
- `reason`: `self`, `connect`, `node-connected`, `periodic`, ...
- `ts`: مهر زمانی آخرین به‌روزرسانی (میلی‌ثانیه از epoch)

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

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

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

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

### 2) اتصال WebSocket

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

#### چرا فرمان‌های یک‌باره CLI نمایش داده نمی‌شوند

CLI اغلب برای فرمان‌های کوتاه و یک‌باره متصل می‌شود. برای جلوگیری از شلوغ کردن
فهرست Instances، `client.mode === "cli"` به ورودی حضور تبدیل **نمی‌شود**.

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

کلاینت‌ها می‌توانند بیکن‌های دوره‌ای غنی‌تری را از طریق متد `system-event` ارسال کنند. برنامه mac
از این برای گزارش نام میزبان، IP و `lastInputSeconds` استفاده می‌کند.

### 4) اتصال Nodeها (نقش: node)

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

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

ورودی‌های حضور در یک map واحد درون حافظه ذخیره می‌شوند:

- ورودی‌ها با یک **کلید حضور** کلیدگذاری می‌شوند.
- بهترین کلید یک `instanceId` پایدار است (از `connect.client.instanceId`) که از راه‌اندازی‌های مجدد جان سالم به در می‌برد.
- کلیدها به بزرگی و کوچکی حروف حساس نیستند.

اگر یک کلاینت بدون `instanceId` پایدار دوباره متصل شود، ممکن است به‌صورت یک ردیف
**تکراری** نمایش داده شود.

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

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

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

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

## نکته اتصال راه‌دور/تونل (IPهای loopback)

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

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

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

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

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

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

## مرتبط

- [نشانگرهای تایپ](/fa/concepts/typing-indicators)
- [استریم و قطعه‌بندی](/fa/concepts/streaming)
