Gateway

• Secara default, Gateway menolak untuk memulai kecuali gateway.mode=local ditetapkan di ~/.openclaw/openclaw.json. Gunakan --allow-unconfigured untuk eksekusi ad-hoc/dev.
• 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, bukan mengasumsikan mode lokal secara implisit.
• Jika file ada dan gateway.mode tidak ada, Gateway memperlakukannya sebagai kerusakan konfigurasi yang mencurigakan dan menolak untuk "menebak lokal" untuk Anda.
• Binding di luar loopback tanpa auth diblokir (pagar pengaman keselamatan).
• lan, tailnet, dan custom saat ini di-resolve melalui jalur BYOH khusus IPv4.
• BYOH khusus IPv6 belum didukung secara native pada jalur ini saat ini. Gunakan sidecar IPv4 atau proxy jika host itu sendiri hanya IPv6.
• SIGUSR1 memicu restart dalam proses saat diotorisasi (commands.restart diaktifkan secara default; tetapkan commands.restart: false untuk memblokir restart manual, sementara penerapan/pembaruan alat/konfigurasi Gateway tetap diizinkan).
• Handler SIGINT/SIGTERM menghentikan proses Gateway, tetapi tidak memulihkan state terminal kustom apa pun. Jika Anda membungkus CLI dengan TUI atau input raw-mode, pulihkan terminal sebelum keluar.

• Catatan menyimpan metadata operasional: nama event, hitungan, ukuran byte, pembacaan memori, state antrean/sesi, id persetujuan, nama saluran/Plugin, dan ringkasan sesi yang disunting. Catatan tidak menyimpan teks chat, body webhook, output alat, body request atau respons mentah, token, cookie, nilai rahasia, hostname, atau id sesi mentah. Tetapkan diagnostics.enabled: false untuk menonaktifkan perekam sepenuhnya.
• Pada exit fatal Gateway, timeout shutdown, dan kegagalan startup restart, OpenClaw menulis snapshot diagnostik yang sama ke ~/.openclaw/logs/stability/openclaw-stability-*.json ketika 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 kemampuan autentikasi yang terlihat saat handshake. Ini tidak membuktikan operasi baca/tulis/admin.
• Pemeriksaan diagnostik tidak memutasi autentikasi perangkat pertama kali: pemeriksaan ini menggunakan ulang token perangkat cache yang sudah ada jika tersedia, tetapi tidak membuat identitas perangkat CLI baru atau catatan pemasangan perangkat baca-saja hanya untuk memeriksa status.
• gateway status menyelesaikan SecretRefs autentikasi yang dikonfigurasi untuk autentikasi pemeriksaan jika memungkinkan.
• Jika SecretRef autentikasi yang diperlukan tidak terselesaikan di jalur perintah ini, gateway status --json melaporkan rpc.authWarning ketika konektivitas/autentikasi pemeriksaan gagal; teruskan --token/--password secara eksplisit atau selesaikan sumber rahasia terlebih dahulu.
• Jika pemeriksaan berhasil, peringatan auth-ref yang tidak terselesaikan ditekan untuk menghindari positif palsu.
• Ketika pemeriksaan diaktifkan, keluaran JSON menyertakan gateway.version saat Gateway yang berjalan melaporkannya; --require-rpc dapat kembali ke payload RPC status.runtimeVersion jika pemeriksaan handshake lanjutan tidak dapat menyediakan metadata versi.
• Gunakan --require-rpc dalam skrip dan otomatisasi ketika layanan yang mendengarkan saja tidak cukup dan Anda juga membutuhkan panggilan RPC cakupan baca dalam keadaan sehat.
• --deep menambahkan pemindaian upaya terbaik untuk instalasi launchd/systemd/schtasks tambahan. Ketika beberapa layanan mirip gateway terdeteksi, keluaran manusia mencetak petunjuk pembersihan dan memperingatkan bahwa sebagian besar pengaturan 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 kanal yang hilang) sehingga pemeriksaan smoke instalasi dan pembaruan menangkapnya. gateway status default mempertahankan jalur baca-saja cepat yang melewati validasi plugin.
• Keluaran manusia menyertakan jalur log file yang terselesaikan plus snapshot jalur/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, jalur 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 resolusi 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 pemeriksaan 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, pemeriksaan menggunakan ulang autentikasi perangkat cache yang sudah ada tetapi tidak membuat identitas perangkat pertama kali atau status pemasangan.
• Kode keluar non-nol hanya ketika tidak ada target yang diperiksa dapat dijangkau.

Tingkat atas:

• ok: setidaknya satu target dapat dijangkau.
• degraded: setidaknya satu target menerima koneksi tetapi tidak menyelesaikan diagnostik RPC detail penuh.
• capability: kemampuan 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 upaya terbaik 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 pass pemeriksaan ini.

Per target (targets[].connect):

• ok: keterjangkauan setelah koneksi + klasifikasi 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 kemampuan autentikasi yang ditampilkan untuk target tersebut.

• ssh_tunnel_failed: penyiapan tunnel SSH gagal; perintah kembali ke pemeriksaan langsung.
• multiple_gateways: identitas gateway yang berbeda dapat dijangkau, atau OpenClaw tidak dapat membuktikan target yang dapat dijangkau adalah gateway yang sama. Tunnel SSH, URL proxy, atau URL remote yang dikonfigurasi ke gateway yang sama tidak memicu peringatan ini.
• auth_secretref_unresolved: SecretRef autentikasi yang dikonfigurasi tidak dapat diselesaikan untuk target yang gagal.
• probe_scope_limited: koneksi WebSocket berhasil, tetapi pemeriksaan 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 secara persisten — pemulihan otomatis KeepAlive tetap aktif untuk crash mendatang dan gateway start mengaktifkan ulang dengan bersih tanpa launchctl enable manual. Berikan --disable untuk menekan KeepAlive dan RunAtLoad secara persisten agar gateway tidak muncul ulang sampai gateway start eksplisit berikutnya; gunakan ini ketika penghentian manual harus bertahan melewati reboot atau mulai ulang sistem.
• gateway restart --safe meminta Gateway yang sedang berjalan untuk memeriksa awal pekerjaan aktif dan menjadwalkan satu mulai ulang tergabung setelah pekerjaan aktif selesai. Mulai ulang aman default menunggu pekerjaan aktif hingga gateway.reload.deferralTimeoutMs yang dikonfigurasi (default 5 menit); ketika batas waktu itu habis, mulai ulang dipaksa. Atur gateway.reload.deferralTimeoutMs ke 0 untuk penantian aman tanpa batas yang tidak pernah memaksa. --safe tidak dapat digabungkan dengan --force atau --wait.
• gateway restart --wait 30s menimpa batas waktu drain mulai ulang yang dikonfigurasi untuk mulai ulang tersebut. Angka tanpa satuan adalah milidetik; satuan 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 penangguhan sehingga Gateway langsung memancarkan mulai ulang meskipun pemblokir dilaporkan. Jalan keluar operator untuk penangguhan task-run yang macet; memerlukan --safe.
• 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.

• Ketika auth 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 auth token memerlukan token dan SecretRef token yang dikonfigurasi tidak terselesaikan, pemasangan gagal tertutup alih-alih menyimpan plaintext fallback.
• Untuk auth kata sandi pada gateway run, pilih OPENCLAW_GATEWAY_PASSWORD, --password-file, atau gateway.auth.password yang didukung SecretRef daripada --password inline.
• Dalam mode auth yang diinferensikan, OPENCLAW_GATEWAY_PASSWORD yang hanya ada di shell tidak melonggarkan persyaratan token pemasangan; gunakan konfigurasi tahan lama (gateway.auth.password atau config env) saat memasang layanan terkelola.
• Jika gateway.auth.token dan gateway.auth.password sama-sama dikonfigurasi dan gateway.auth.mode belum diatur, pemasangan diblokir sampai mode diatur secara eksplisit.