Varlık¶

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)