> ## 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.

# Gateway Mimarisi

# Gateway mimarisi

Son güncelleme: 2026-01-22

## Genel bakış

* Tek ve uzun ömürlü bir **Gateway**, tüm mesajlaşma yüzeylerinin sahibidir (Baileys üzerinden WhatsApp,
  grammY üzerinden Telegram, Slack, Discord, Signal, iMessage, WebChat).
* Kontrol düzlemi istemcileri (macOS uygulaması, CLI, web UI, otomasyonlar),
  yapılandırılmış bağlama ana makinesinde (varsayılan
  `127.0.0.1:18789`) **WebSocket** üzerinden Gateway’e bağlanır.
* **Node**’lar (macOS/iOS/Android/headless) da **WebSocket** üzerinden bağlanır, ancak
  açık yetenekler/komutlar ile `role: node` bildirir.
* Ana makine başına bir Gateway; WhatsApp oturumunu açan tek yerdir.
* **canvas host**, Gateway HTTP sunucusu tarafından şu yol altında sunulur:
  * `/__openclaw__/canvas/` (ajan tarafından düzenlenebilir HTML/CSS/JS)
  * `/__openclaw__/a2ui/` (A2UI host)
    Gateway ile aynı portu kullanır (varsayılan `18789`).

## Bileşenler ve akışlar

### Gateway (daemon)

* Sağlayıcı bağlantılarını sürdürür.
* Tipli bir WS API’si sunar (istekler, yanıtlar, sunucu-itmeli olaylar).
* Gelen çerçeveleri JSON Schema’ya göre doğrular.
* `agent`, `chat`, `presence`, `health`, `heartbeat`, `cron` gibi olaylar yayar.

### İstemciler (mac uygulaması / CLI / web yönetimi)

* İstemci başına bir WS bağlantısı.
* İstekler gönderir (`health`, `status`, `send`, `agent`, `system-presence`).
* Olaylara abone olur (`tick`, `agent`, `presence`, `shutdown`).

### Node’lar (macOS / iOS / Android / headless)

* `role: node` ile **aynı WS sunucusuna** bağlanır.
* `connect` içinde bir cihaz kimliği sağlar; eşleştirme **cihaz tabanlıdır** (rol `node`) ve
  onay cihaz eşleştirme deposunda tutulur.
* `canvas.*`, `camera.*`, `screen.record`, `location.get` gibi komutları sunar.

Protokol ayrıntıları:

* [Gateway protokolü](/gateway/protocol)

### WebChat

* Sohbet geçmişi ve gönderimler için Gateway WS API’sini kullanan statik bir UI.
* Uzak kurulumlarda, diğer istemcilerle aynı SSH/Tailscale tüneli üzerinden bağlanır.

## Bağlantı yaşam döngüsü (tek istemci)

```mermaid theme={"theme":{"light":"min-light","dark":"min-dark"}}
sequenceDiagram
    participant Client
    participant Gateway

    Client->>Gateway: req:connect
    Gateway-->>Client: res (ok)
    Note right of Gateway: veya res error + close
    Note left of Client: payload=hello-ok<br>snapshot: presence + health

    Gateway-->>Client: event:presence
    Gateway-->>Client: event:tick

    Client->>Gateway: req:agent
    Gateway-->>Client: res:agent<br>ack {runId, status:"accepted"}
    Gateway-->>Client: event:agent<br>(streaming)
    Gateway-->>Client: res:agent<br>final {runId, status, summary}
```

## Wire protokolü (özet)

* Taşıma: WebSocket, JSON yükleri içeren metin çerçeveleri.
* İlk çerçeve **zorunlu olarak** `connect` olmalıdır.
* El sıkışmadan sonra:
  * İstekler: `{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
  * Olaylar: `{type:"event", event, payload, seq?, stateVersion?}`
* `OPENCLAW_GATEWAY_TOKEN` (veya `--token`) ayarlanmışsa, `connect.params.auth.token`
  eşleşmelidir; aksi halde soket kapanır.
* Yan etki oluşturan yöntemler (`send`, `agent`) için güvenli yeniden deneme amacıyla
  idempotency anahtarları zorunludur; sunucu kısa ömürlü bir tekilleştirme önbelleği tutar.
* Node’lar `role: "node"` ile birlikte yetenekler/komutlar/izinleri `connect` içinde göndermelidir.

## Eşleştirme + yerel güven

* Tüm WS istemcileri (operatörler + node’lar) `connect` üzerinde bir **cihaz kimliği** içerir.
* Yeni cihaz kimlikleri eşleştirme onayı gerektirir; Gateway, sonraki bağlantılar için bir **cihaz belirteci**
  verir.
* **Yerel** bağlantılar (loopback veya gateway ana makinesinin kendi tailnet adresi)
  aynı ana makinede UX’i akıcı tutmak için otomatik onaylanabilir.
* **Yerel olmayan** bağlantılar `connect.challenge` nonce’unu imzalamalıdır ve
  açık onay gerektirir.
* Gateway kimlik doğrulaması (`gateway.auth.*`) yerel veya uzak **tüm** bağlantılar için
  geçerlidir.

Ayrıntılar: [Gateway protokolü](/gateway/protocol), [Eşleştirme](/channels/pairing),
[Güvenlik](/gateway/security).

## Protokol tiplemesi ve kod üretimi

* TypeBox şemaları protokolü tanımlar.
* JSON Schema bu şemalardan üretilir.
* Swift modelleri JSON Schema’dan üretilir.

## Uzak erişim

* Tercih edilen: Tailscale veya VPN.

* Alternatif: SSH tüneli

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  ssh -N -L 18789:127.0.0.1:18789 user@host
  ```

* Tünel üzerinden de aynı el sıkışma + kimlik doğrulama belirteci uygulanır.

* Uzak kurulumlarda WS için TLS + isteğe bağlı pinning etkinleştirilebilir.

## Operasyonlar özeti

* Başlatma: `openclaw gateway` (ön planda, günlükler stdout’a).
* Sağlık: WS üzerinden `health` (ayrıca `hello-ok` içinde yer alır).
* Gözetim: otomatik yeniden başlatma için launchd/systemd.

## Invariants

* Her ana makinede tek bir Gateway, tek bir Baileys oturumunu kontrol eder.
* El sıkışma zorunludur; JSON olmayan veya ilk çerçevesi connect olmayan her şey sert kapatma ile sonuçlanır.
* Olaylar tekrar oynatılmaz; boşluklarda istemciler yenileme yapmalıdır.