Skip to main content

​
Runbook Gateway

Gunakan halaman ini untuk startup hari pertama dan operasi hari kedua dari layanan Gateway.

Pemecahan Masalah Mendalam

Diagnostik berbasis gejala dengan urutan perintah yang tepat dan tanda tangan log.

Konfigurasi

Panduan pengaturan berbasis tugas + referensi konfigurasi lengkap.

​
Startup lokal 5 menit

1

Mulai Gateway

2

Verifikasi kesehatan layanan

Baseline sehat: Runtime: running dan RPC probe: ok.
3

Validasi kesiapan saluran

Muat ulang konfigurasi Gateway memantau jalur file konfigurasi aktif (diselesaikan dari default profil/state, atau OPENCLAW_CONFIG_PATH jika diatur). Mode default adalah gateway.reload.mode="hybrid".

​
Model runtime

  • Satu proses yang selalu menyala untuk perutean, control plane, dan koneksi saluran.
  • Port tunggal yang multiplexed untuk:
    • Kontrol WebSocket/RPC
    • API HTTP (kompatibel dengan OpenAI, Responses, pemanggilan alat)
    • Control UI dan hook
  • Mode bind default: loopback.
  • Autentikasi diperlukan secara default (gateway.auth.token / gateway.auth.password, atau OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).

​
Prioritas port dan bind

​
Mode hot reload

​
Kumpulan perintah operator

​
Akses jarak jauh (Remote access)

Disukai: Tailscale/VPN. Cadangan: SSH tunnel.
Kemudian hubungkan klien ke ws://127.0.0.1:18789 secara lokal.
Jika autentikasi gateway dikonfigurasi, klien tetap harus mengirimkan autentikasi (token/password) bahkan melalui SSH tunnel.
Lihat: Gateway Jarak Jauh, Autentikasi, Tailscale.

​
Pengawasan dan siklus hidup layanan

Gunakan proses yang diawasi (supervised) untuk keandalan seperti lingkungan produksi.
Label LaunchAgent adalah ai.openclaw.gateway (default) atau ai.openclaw.<profile> (profil bernama). openclaw doctor mengaudit dan memperbaiki penyimpangan konfigurasi layanan.

​
Beberapa gateway pada satu host

Sebagian besar pengaturan seharusnya hanya menjalankan satu Gateway. Gunakan lebih dari satu hanya untuk isolasi ketat/redundansi (misalnya profil penyelamatan). Daftar periksa per instance:
  • gateway.port unik
  • OPENCLAW_CONFIG_PATH unik
  • OPENCLAW_STATE_DIR unik
  • agents.defaults.workspace unik
Contoh:
Lihat: Beberapa gateway.

​
Jalur cepat profil dev

Default mencakup state/konfigurasi yang terisolasi dan port gateway dasar 19001.

​
Referensi cepat protokol (sudut pandang operator)

  • Frame klien pertama harus berupa connect.
  • Gateway mengembalikan snapshot hello-ok (mencakup presence, health, stateVersion, uptimeMs, batas/kebijakan).
  • Permintaan (Request): req(method, params) → res(ok/payload|error).
  • Event umum: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.
Proses agen melalui dua tahap:
  1. Ack diterima segera (status:"accepted")
  2. Respons penyelesaian akhir (status:"ok"|"error"), dengan event agent yang di-stream di antaranya.
Lihat dokumen protokol lengkap: Protokol Gateway.

​
Pemeriksaan operasional

​
Liveness

  • Buka WS dan kirim connect.
  • Harapkan respons hello-ok dengan snapshot.

​
Readiness

​
Pemulihan celah (Gap recovery)

Event tidak diputar ulang. Jika terjadi celah urutan, segarkan status (health, system-presence) sebelum melanjutkan.

​
Tanda-tanda kegagalan umum

Untuk tahapan diagnosis lengkap, gunakan Pemecahan Masalah Gateway.

​
Jaminan keamanan

  • Klien protokol Gateway gagal dengan cepat saat Gateway tidak tersedia (tidak ada fallback saluran langsung yang implisit).
  • Frame pertama yang tidak valid/bukan connect akan ditolak dan ditutup.
  • Shutdown yang anggun (graceful) memancarkan event shutdown sebelum socket ditutup.
Terkait: