Gateway

• Secara default, Gateway menolak untuk dimulai kecuali gateway.mode=local diatur di ~/.openclaw/openclaw.json. Gunakan --allow-unconfigured untuk eksekusi ad-hoc/pengembangan.
• openclaw onboard --mode local dan openclaw setup diharapkan menulis gateway.mode=local. Jika file ada tetapi gateway.mode tidak ada, perlakukan itu sebagai konfigurasi yang rusak atau tertimpa dan perbaiki, alih-alih mengasumsikan mode lokal secara implisit.
• Jika file ada dan gateway.mode tidak ada, Gateway memperlakukan itu sebagai kerusakan konfigurasi yang mencurigakan dan menolak untuk "menebak lokal" untuk Anda.
• Binding di luar loopback tanpa autentikasi diblokir (batas pengaman keselamatan).
• SIGUSR1 memicu mulai ulang dalam proses saat diotorisasi (commands.restart diaktifkan secara default; atur commands.restart: false untuk memblokir mulai ulang manual, sementara penerapan/pembaruan alat/konfigurasi Gateway tetap diizinkan).
• Handler SIGINT/SIGTERM menghentikan proses Gateway, tetapi tidak memulihkan status terminal khusus apa pun. Jika Anda membungkus CLI dengan TUI atau input raw-mode, pulihkan terminal sebelum keluar.

• Rekaman menyimpan metadata operasional: nama event, jumlah, ukuran byte, pembacaan memori, status antrean/sesi, nama saluran/plugin, dan ringkasan sesi yang disunting. Rekaman tidak menyimpan teks chat, body webhook, output alat, body request atau respons mentah, token, cookie, nilai rahasia, hostname, atau id sesi mentah. Atur diagnostics.enabled: false untuk menonaktifkan perekam sepenuhnya.
• Pada keluarnya Gateway yang fatal, timeout shutdown, dan kegagalan startup restart, OpenClaw menulis snapshot diagnostik yang sama ke ~/.openclaw/logs/stability/openclaw-stability-*.json saat perekam memiliki event. Periksa bundle terbaru dengan openclaw gateway stability --bundle latest; --limit, --type, dan --since-seq juga berlaku untuk output bundle.

• gateway status tetap tersedia untuk diagnostik bahkan ketika konfigurasi CLI lokal hilang atau tidak valid.
• gateway status default membuktikan status layanan, koneksi WebSocket, dan kapabilitas autentikasi yang terlihat pada waktu handshake. Ini tidak membuktikan operasi baca/tulis/admin.
• Probe diagnostik tidak melakukan mutasi untuk autentikasi perangkat pertama kali: probe menggunakan ulang token perangkat yang sudah ada di cache jika tersedia, tetapi tidak membuat identitas perangkat CLI baru atau catatan pemasangan perangkat read-only hanya untuk memeriksa status.
• gateway status menyelesaikan SecretRefs autentikasi yang dikonfigurasi untuk autentikasi probe jika memungkinkan.
• Jika SecretRef autentikasi wajib tidak terselesaikan dalam jalur perintah ini, gateway status --json melaporkan rpc.authWarning ketika konektivitas/autentikasi probe gagal; teruskan --token/--password secara eksplisit atau selesaikan sumber secret terlebih dahulu.
• Jika probe berhasil, peringatan auth-ref yang tidak terselesaikan disembunyikan untuk menghindari positif palsu.
• Gunakan --require-rpc dalam skrip dan otomatisasi ketika layanan yang mendengarkan saja tidak cukup dan Anda juga memerlukan panggilan RPC cakupan-baca yang sehat.
• --deep menambahkan pemindaian best-effort untuk instalasi launchd/systemd/schtasks tambahan. Ketika beberapa layanan mirip gateway terdeteksi, keluaran manusia mencetak petunjuk pembersihan dan memperingatkan bahwa sebagian besar penyiapan sebaiknya menjalankan satu Gateway per mesin.
• --deep juga melaporkan handoff restart supervisor Gateway terbaru ketika proses layanan keluar dengan bersih untuk restart supervisor eksternal.
• --deep menjalankan validasi konfigurasi dalam mode sadar-plugin (pluginValidation: "full") dan menampilkan peringatan manifes plugin yang dikonfigurasi (misalnya metadata konfigurasi channel yang hilang) sehingga pemeriksaan smoke instalasi dan pembaruan menangkapnya. gateway status default mempertahankan jalur read-only cepat yang melewati validasi plugin.
• Keluaran manusia menyertakan path log file yang terselesaikan plus snapshot path/validitas konfigurasi CLI-vs-layanan untuk membantu mendiagnosis drift profil atau state-dir.

• Pada instalasi systemd Linux, pemeriksaan drift autentikasi layanan membaca nilai Environment= dan EnvironmentFile= dari unit (termasuk %h, path yang dikutip, beberapa file, dan file opsional -).
• Pemeriksaan drift menyelesaikan SecretRefs gateway.auth.token menggunakan env runtime gabungan (env perintah layanan terlebih dahulu, lalu fallback env proses).
• Jika autentikasi token tidak aktif secara efektif (gateway.auth.mode eksplisit berupa password/none/trusted-proxy, atau mode tidak disetel saat kata sandi dapat menang dan tidak ada kandidat token yang dapat menang), pemeriksaan token-drift melewati penyelesaian token konfigurasi.

• Reachable: yes berarti setidaknya satu target menerima koneksi WebSocket.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only melaporkan apa yang dapat dibuktikan probe tentang autentikasi. Ini terpisah dari keterjangkauan.
• Read probe: ok berarti panggilan RPC detail cakupan-baca (health/status/system-presence/config.get) juga berhasil.
• Read probe: limited - missing scope: operator.read berarti koneksi berhasil tetapi RPC cakupan-baca terbatas. Ini dilaporkan sebagai keterjangkauan terdegradasi, bukan kegagalan penuh.
• Read probe: failed setelah Connect: ok berarti Gateway menerima koneksi WebSocket, tetapi diagnostik baca lanjutan kehabisan waktu atau gagal. Ini juga merupakan keterjangkauan terdegradasi, bukan Gateway yang tidak dapat dijangkau.
• Seperti gateway status, probe menggunakan ulang autentikasi perangkat yang sudah ada di cache tetapi tidak membuat identitas perangkat pertama kali atau status pemasangan.
• Exit code bernilai non-zero hanya ketika tidak ada target yang diprobe yang dapat dijangkau.

Tingkat atas:

• ok: setidaknya satu target dapat dijangkau.
• degraded: setidaknya satu target menerima koneksi tetapi tidak menyelesaikan diagnostik RPC detail penuh.
• capability: kapabilitas terbaik yang terlihat di seluruh target yang dapat dijangkau (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope, atau unknown).
• primaryTargetId: target terbaik untuk diperlakukan sebagai pemenang aktif dalam urutan ini: URL eksplisit, tunnel SSH, remote yang dikonfigurasi, lalu local loopback.
• warnings[]: catatan peringatan best-effort dengan code, message, dan targetIds opsional.
• network: petunjuk URL local loopback/tailnet yang diturunkan dari konfigurasi saat ini dan jaringan host.
• discovery.timeoutMs dan discovery.count: anggaran/jumlah hasil discovery aktual yang digunakan untuk lintasan probe ini.

Per target (targets[].connect):

• ok: keterjangkauan setelah koneksi + klasifikasi terdegradasi.
• rpcOk: keberhasilan RPC detail penuh.
• scopeLimited: RPC detail gagal karena cakupan operator yang hilang.

Per target (targets[].auth):

• role: peran autentikasi yang dilaporkan dalam hello-ok jika tersedia.
• scopes: cakupan yang diberikan yang dilaporkan dalam hello-ok jika tersedia.
• capability: klasifikasi kapabilitas autentikasi yang ditampilkan untuk target tersebut.

• ssh_tunnel_failed: penyiapan tunnel SSH gagal; perintah beralih kembali ke probe langsung.
• multiple_gateways: lebih dari satu target dapat dijangkau; ini tidak biasa kecuali Anda sengaja menjalankan profil terisolasi, seperti bot penyelamat.
• auth_secretref_unresolved: SecretRef autentikasi yang dikonfigurasi tidak dapat diselesaikan untuk target yang gagal.
• probe_scope_limited: koneksi WebSocket berhasil, tetapi probe baca dibatasi oleh operator.read yang hilang.

• gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
• gateway install: --port, --runtime <node|bun>, --token, --wrapper <path>, --force, --json
• gateway restart: --safe, --skip-deferral, --force, --wait <duration>, --json
• gateway uninstall|start: --json
• gateway stop: --disable, --json

• Gunakan gateway restart untuk memulai ulang layanan terkelola. Jangan merangkai gateway stop dan gateway start sebagai pengganti mulai ulang.
• Di macOS, gateway stop menggunakan launchctl bootout secara default, yang menghapus LaunchAgent dari sesi boot saat ini tanpa menyimpan penonaktifan — pemulihan otomatis KeepAlive tetap aktif untuk crash berikutnya dan gateway start mengaktifkan ulang dengan bersih tanpa launchctl enable manual. Berikan --disable untuk menekan KeepAlive dan RunAtLoad secara persisten agar gateway tidak muncul kembali sampai gateway start eksplisit berikutnya; gunakan ini saat penghentian manual harus bertahan melewati reboot atau mulai ulang sistem.
• gateway restart --safe meminta Gateway yang berjalan untuk melakukan preflight pekerjaan OpenClaw aktif dan menunda mulai ulang sampai pengiriman balasan, run tertanam, dan run tugas selesai dikosongkan. --safe tidak dapat digabungkan dengan --force atau --wait.
• gateway restart --wait 30s menimpa anggaran drain mulai ulang yang dikonfigurasi untuk mulai ulang tersebut. Angka polos adalah milidetik; unit seperti s, m, dan h diterima. --wait 0 menunggu tanpa batas.
• gateway restart --safe --skip-deferral menjalankan mulai ulang aman yang sadar OpenClaw tetapi melewati gerbang penundaan sehingga Gateway memancarkan mulai ulang segera meskipun pemblokir dilaporkan. Pintu keluar operator untuk penundaan run tugas yang macet; memerlukan --safe.
• gateway restart --force melewati drain pekerjaan aktif dan memulai ulang segera. Gunakan saat operator sudah memeriksa pemblokir tugas yang tercantum dan ingin gateway kembali sekarang.
• Perintah siklus hidup menerima --json untuk scripting.

• Saat autentikasi token memerlukan token dan gateway.auth.token dikelola SecretRef, gateway install memvalidasi bahwa SecretRef dapat di-resolve tetapi tidak menyimpan token yang di-resolve ke metadata lingkungan layanan.
• Jika autentikasi token memerlukan token dan SecretRef token yang dikonfigurasi tidak ter-resolve, instalasi gagal tertutup alih-alih menyimpan plaintext fallback.
• Untuk autentikasi kata sandi pada gateway run, pilih OPENCLAW_GATEWAY_PASSWORD, --password-file, atau gateway.auth.password yang didukung SecretRef daripada --password inline.
• Dalam mode autentikasi tersimpul, OPENCLAW_GATEWAY_PASSWORD yang hanya ada di shell tidak melonggarkan persyaratan token instalasi; gunakan konfigurasi tahan lama (gateway.auth.password atau config env) saat menginstal layanan terkelola.
• Jika gateway.auth.token dan gateway.auth.password sama-sama dikonfigurasi dan gateway.auth.mode belum diatur, instalasi diblokir sampai mode diatur secara eksplisit.