> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Presence

# Presence

OpenClaw “presence”, aşağıdakilerin hafif ve en iyi çaba esaslı bir görünümüdür:

* **Gateway**’in kendisi ve
* **Gateway’e bağlı istemciler** (mac uygulaması, WebChat, CLI vb.)

Presence, öncelikle macOS uygulamasındaki **Instances** sekmesini oluşturmak ve
operatörlere hızlı görünürlük sağlamak için kullanılır.

## Presence alanları (görünenler)

Presence girdileri, aşağıdaki gibi alanlara sahip yapılandırılmış nesnelerdir:

* `instanceId` (isteğe bağlı ancak güçlü biçimde önerilir): kararlı istemci kimliği (genellikle `connect.client.instanceId`)
* `host`: insan tarafından okunabilir ana makine adı
* `ip`: en iyi çaba esaslı IP adresi
* `version`: istemci sürüm dizesi
* `deviceFamily` / `modelIdentifier`: donanım ipuçları
* `mode`: `ui`, `webchat`, `cli`, `backend`, `probe`, `test`, `node`, ...
* `lastInputSeconds`: “son kullanıcı girdisinden bu yana geçen saniye” (biliniyorsa)
* `reason`: `self`, `connect`, `node-connected`, `periodic`, ...
* `ts`: son güncelleme zaman damgası (epoch’tan beri ms)

## Üreticiler (presence nereden gelir)

Presence girdileri birden fazla kaynak tarafından üretilir ve **birleştirilir**.

### 1. Gateway öz girdisi

Gateway, başlatma sırasında her zaman bir “öz” girdisi ekler; böylece herhangi bir
istemci bağlanmadan önce bile arayüzlerde gateway ana makinesi görünür.

### 2. WebSocket bağlantısı

Her WS istemcisi bir `connect` isteğiyle başlar. Başarılı el sıkışma sonrasında
Gateway, bu bağlantı için bir presence girdisini ekler veya günceller.

#### Neden tek seferlik CLI komutları görünmez

CLI, kısa süreli tek seferlik komutlar için sıkça bağlanır. Instances listesini
spam’lememek için `client.mode === "cli"` bir presence girdisine **dönüştürülmez**.

### 3. `system-event` beacon’ları

İstemciler, `system-event` yöntemi aracılığıyla daha zengin periyodik beacon’lar
gönderebilir. mac uygulaması, ana makine adı, IP ve `lastInputSeconds` bildirmek için bunu kullanır.

### 4. Node bağlantıları (rol: node)

Bir node, Gateway WebSocket’i üzerinden `role: node` ile bağlandığında Gateway,
o node için bir presence girdisini ekler veya günceller (diğer WS istemcileriyle aynı akış).

## Birleştirme + yinelenenleri giderme (neden `instanceId` önemlidir)

Presence girdileri tek bir bellek içi haritada saklanır:

* Girdiler bir **presence anahtarı** ile anahtarlanır.
* En iyi anahtar, yeniden başlatmalardan sonra da kalıcı olan kararlı bir `instanceId`’dur (`connect.client.instanceId`’dan).
* Anahtarlar büyük/küçük harfe duyarsızdır.

Bir istemci kararlı bir `instanceId` olmadan yeniden bağlanırsa,
**yinelenen** bir satır olarak görünebilir.

## TTL ve sınırlı boyut

Presence bilerek geçicidir:

* **TTL:** 5 dakikadan eski girdiler budanır
* **Maks. girdi sayısı:** 200 (en eskiler önce düşürülür)

Bu, listenin taze kalmasını sağlar ve sınırsız bellek büyümesini önler.

## Uzak/tünel uyarısı (loopback IP’ler)

Bir istemci SSH tüneli / yerel port yönlendirme üzerinden bağlandığında, Gateway
uzak adresi `127.0.0.1` olarak görebilir. İstemci tarafından bildirilen iyi bir
IP’nin üzerine yazmamak için loopback uzak adresler yok sayılır.

## Tüketiciler

### macOS Instances sekmesi

macOS uygulaması, `system-presence` çıktısını oluşturur ve son güncellemenin yaşına göre
küçük bir durum göstergesi (Active/Idle/Stale) uygular.

## Hata ayıklama ipuçları

* Ham listeyi görmek için Gateway’e karşı `system-presence` çağrısını yapın.
* Yinelenenler görüyorsanız:
  * istemcilerin el sıkışmada kararlı bir `client.instanceId` gönderdiğini doğrulayın
  * periyodik beacon’ların aynı `instanceId`’yı kullandığını doğrulayın
  * bağlantıdan türetilen girdide `instanceId`’nin eksik olup olmadığını kontrol edin (bu durumda yinelenenler beklenir)