OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Fundamentals

Arsitektur Gateway

Ikhtisar

  • Satu Gateway berumur panjang mengelola semua sarana perpesanan (WhatsApp melalui Baileys, Telegram melalui grammY, Slack, Discord, Signal, iMessage, WebChat).

  • Klien bidang kontrol (aplikasi macOS, CLI, UI web, otomatisasi) terhubung ke Gateway melalui WebSocket pada host pengikatan yang dikonfigurasi (bawaan 127.0.0.1:18789).

  • Node (macOS/iOS/Android/headless) juga terhubung melalui WebSocket, tetapi mendeklarasikan role: node dengan kapabilitas/perintah eksplisit.

  • Satu Gateway per host; Gateway adalah satu-satunya tempat yang membuka sesi WhatsApp.

  • Host kanvas disajikan oleh server HTTP Gateway pada:

    • /__openclaw__/canvas/ (HTML/CSS/JS yang dapat diedit agen)
    • /__openclaw__/a2ui/ (host A2UI)

    Host ini menggunakan porta yang sama dengan Gateway (bawaan 18789).

Komponen dan alur

Gateway (daemon)

  • Memelihara koneksi penyedia.
  • Menyediakan API WS bertipe (permintaan, respons, peristiwa dorong-server).
  • Memvalidasi bingkai masuk terhadap JSON Schema.
  • Memancarkan peristiwa seperti agent, chat, presence, health, heartbeat, cron.

Klien (aplikasi Mac / CLI / admin web)

  • Satu koneksi WS per klien.
  • Mengirim permintaan (health, status, send, agent, system-presence).
  • Berlangganan peristiwa (tick, agent, presence, shutdown).

Node (macOS / iOS / Android / headless)

  • Terhubung ke server WS yang sama dengan role: node.
  • Menyediakan identitas perangkat dalam connect; pemasangan berbasis perangkat (peran node) dan persetujuan disimpan dalam penyimpanan pemasangan perangkat.
  • Menyediakan perintah seperti canvas.*, camera.*, screen.record, location.get.

Detail protokol: Protokol Gateway

WebChat

  • UI statis yang menggunakan API WS Gateway untuk riwayat percakapan dan pengiriman.
  • Dalam penyiapan jarak jauh, terhubung melalui terowongan SSH/Tailscale yang sama seperti klien lainnya.

Siklus hidup koneksi (klien tunggal)

sequenceDiagram
    participant Client
    participant Gateway

    Client->>Gateway: req:connect
    Gateway-->>Client: res (ok)
    Note right of Gateway: atau kesalahan res + tutup
    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}

Protokol komunikasi (ringkasan)

  • Transpor: WebSocket, bingkai teks dengan muatan JSON.
  • Bingkai pertama harus berupa connect.
  • Setelah jabat tangan:
    • Permintaan: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
    • Peristiwa: {type:"event", event, payload, seq?, stateVersion?}
  • hello-ok.features.methods / events adalah metadata penemuan, bukan hasil pembuatan yang memuat setiap rute pembantu yang dapat dipanggil.
  • Autentikasi rahasia bersama menggunakan connect.params.auth.token atau connect.params.auth.password, bergantung pada mode autentikasi Gateway yang dikonfigurasi.
  • Mode yang membawa identitas seperti Tailscale Serve (gateway.auth.allowTailscale: true) atau gateway.auth.mode: "trusted-proxy" non-loopback memenuhi autentikasi dari header permintaan alih-alih connect.params.auth.*.
  • gateway.auth.mode: "none" untuk akses masuk privat menonaktifkan autentikasi rahasia bersama sepenuhnya; jangan gunakan mode tersebut pada akses masuk publik/tidak tepercaya.
  • Kunci idempotensi diwajibkan untuk metode yang menimbulkan efek samping (send, agent) agar dapat dicoba ulang dengan aman; server menyimpan singgahan deduplikasi berumur pendek.
  • Node harus menyertakan role: "node" beserta kapabilitas/perintah/izin dalam connect.

Pemasangan dan kepercayaan lokal

  • Semua klien WS (operator + Node) menyertakan identitas perangkat saat connect.
  • ID perangkat baru memerlukan persetujuan pemasangan; Gateway menerbitkan token perangkat untuk koneksi berikutnya.
  • Koneksi local loopback langsung dapat disetujui secara otomatis agar pengalaman pengguna pada host yang sama tetap lancar.
  • OpenClaw juga memiliki jalur koneksi mandiri sempit yang bersifat lokal untuk backend/kontainer bagi alur pembantu rahasia bersama tepercaya.
  • Koneksi tailnet dan LAN, termasuk pengikatan tailnet pada host yang sama, tetap memerlukan persetujuan pemasangan eksplisit.
  • Semua koneksi harus menandatangani nonce connect.challenge. Muatan tanda tangan v3 juga mengikat platform dan deviceFamily; Gateway mengunci metadata yang dipasangkan saat koneksi ulang dan mewajibkan pemasangan perbaikan untuk perubahan metadata.
  • Koneksi nonlokal tetap memerlukan persetujuan eksplisit.
  • Autentikasi Gateway (gateway.auth.*) tetap berlaku untuk semua koneksi, baik lokal maupun jarak jauh.

Detail: Protokol Gateway, Pemasangan, Keamanan.

Pengetikan protokol dan pembuatan kode

  • Skema TypeBox mendefinisikan protokol.
  • JSON Schema dihasilkan dari skema tersebut.
  • Model Swift dihasilkan dari JSON Schema.

Akses jarak jauh

  • Disarankan: Tailscale atau VPN.

  • Alternatif: terowongan SSH

    bash
    ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

  • Jabat tangan + token autentikasi yang sama berlaku melalui terowongan.

  • TLS + penyematan opsional dapat diaktifkan untuk WS dalam penyiapan jarak jauh.

Ringkasan operasional

  • Mulai: openclaw gateway (latar depan, log ke stdout).
  • Kesehatan: health melalui WS (juga disertakan dalam hello-ok).
  • Supervisi: launchd/systemd untuk mulai ulang otomatis.

Invarian

  • Tepat satu Gateway mengendalikan satu sesi Baileys per host.
  • Jabat tangan wajib; bingkai pertama yang bukan JSON atau bukan connect akan menyebabkan penutupan paksa.
  • Peristiwa tidak diputar ulang; klien harus menyegarkan ketika terdapat celah.

Terkait

Was this useful?
On this page

On this page