Gateway

• Secara default, Gateway menolak memulai kecuali gateway.mode=local ditetapkan di ~/.openclaw/openclaw.json. Gunakan --allow-unconfigured untuk proses ad-hoc/dev.
• openclaw onboard --mode local dan openclaw setup diharapkan menulis gateway.mode=local. Jika file ada tetapi gateway.mode hilang, perlakukan itu sebagai konfigurasi rusak atau tertimpa dan perbaiki, bukan mengasumsikan mode lokal secara implisit.
• Jika file ada dan gateway.mode hilang, Gateway memperlakukan itu sebagai kerusakan konfigurasi yang mencurigakan dan menolak untuk "menebak lokal" untuk Anda.
• Binding di luar loopback tanpa auth diblokir (pagar pengaman).
• SIGUSR1 memicu restart dalam proses saat diotorisasi (commands.restart diaktifkan secara default; tetapkan commands.restart: false untuk memblokir restart manual, sementara alat gateway/konfigurasi apply/update tetap diizinkan).
• Handler SIGINT/SIGTERM menghentikan proses gateway, tetapi tidak memulihkan status terminal kustom apa pun. Jika Anda membungkus CLI dengan TUI atau input mode mentah, pulihkan terminal sebelum keluar.

• Rekaman menyimpan metadata operasional: nama event, jumlah, ukuran byte, pembacaan memori, status antrean/sesi, nama channel/Plugin, dan ringkasan sesi yang disamarkan. Rekaman tidak menyimpan teks chat, body Webhook, output alat, body permintaan atau respons mentah, token, cookie, nilai rahasia, hostname, atau id sesi mentah. Tetapkan diagnostics.enabled: false untuk menonaktifkan perekam sepenuhnya.
• Pada keluar fatal Gateway, 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 meskipun konfigurasi CLI lokal hilang atau tidak valid.
• gateway status default membuktikan status layanan, koneksi WebSocket, dan kapabilitas autentikasi yang terlihat saat 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 di-cache ketika ada, tetapi tidak membuat identitas perangkat CLI baru atau catatan pairing perangkat read-only hanya untuk memeriksa status.
• gateway status menyelesaikan SecretRefs autentikasi yang dikonfigurasi untuk autentikasi probe jika memungkinkan.
• Jika SecretRef autentikasi yang diperlukan tidak terselesaikan di jalur perintah ini, gateway status --json melaporkan rpc.authWarning saat 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 dalam keadaan sehat.
• --deep menambahkan pemindaian best-effort untuk instalasi launchd/systemd/schtasks tambahan. Ketika beberapa layanan mirip Gateway terdeteksi, output 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.
• Output manusia menyertakan path log file yang terselesaikan beserta snapshot path/validitas konfigurasi CLI-vs-service 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 bernilai password/none/trusted-proxy, atau mode tidak disetel ketika 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 mengalami timeout atau gagal. Ini juga merupakan keterjangkauan terdegradasi, bukan Gateway yang tidak dapat dijangkau.
• Seperti gateway status, probe menggunakan ulang autentikasi perangkat yang sudah di-cache tetapi tidak membuat identitas perangkat pertama kali atau status pairing.
• Kode keluar 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 discovery/jumlah hasil aktual yang digunakan untuk lintasan probe ini.

Per target (targets[].connect):

• ok: keterjangkauan setelah klasifikasi koneksi + terdegradasi.
• rpcOk: keberhasilan RPC detail penuh.
• scopeLimited: RPC detail gagal karena cakupan operator 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 umum 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, --force, --wait <duration>, --json
• gateway uninstall|start|stop: --json

• Gunakan gateway restart untuk memulai ulang layanan terkelola. Jangan merangkai gateway stop dan gateway start sebagai pengganti restart; di macOS, gateway stop sengaja menonaktifkan LaunchAgent sebelum menghentikannya.
• gateway restart --safe meminta Gateway yang sedang berjalan untuk melakukan preflight pekerjaan OpenClaw aktif dan menunda restart hingga pengiriman balasan, run tertanam, dan run tugas selesai terkuras. --safe tidak dapat digabungkan dengan --force atau --wait.
• gateway restart --wait 30s menimpa anggaran drain restart yang dikonfigurasi untuk restart tersebut. Angka tanpa satuan adalah milidetik; satuan seperti s, m, dan h diterima. --wait 0 menunggu tanpa batas.
• gateway restart --force melewati drain pekerjaan aktif dan langsung memulai ulang. Gunakan ini ketika 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 dalam metadata lingkungan layanan.
• Jika autentikasi token memerlukan token dan SecretRef token yang dikonfigurasi belum 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 berbasis SecretRef daripada --password inline.
• Dalam mode autentikasi terinferensi, OPENCLAW_GATEWAY_PASSWORD yang hanya ada di shell tidak melonggarkan persyaratan token instalasi; gunakan konfigurasi yang tahan lama (gateway.auth.password atau konfigurasi env) saat menginstal layanan terkelola.
• Jika gateway.auth.token dan gateway.auth.password sama-sama dikonfigurasi dan gateway.auth.mode belum disetel, instalasi diblokir hingga mode disetel secara eksplisit.