Gateway

• Menolak dimulai kecuali gateway.mode=local ditetapkan di ~/.openclaw/openclaw.json. Gunakan --allow-unconfigured untuk proses ad hoc/pengembangan; opsi ini melewati pemeriksaan tanpa menulis atau memperbaiki konfigurasi.
• Saat proses awal menemukan konfigurasi tidak valid yang dapat diperbaiki, terminal interaktif menawarkan untuk menjalankan openclaw doctor --fix dan mencoba memulai kembali satu kali setelah mendapat persetujuan. Proses noninteraktif tidak pernah memperbaiki secara otomatis; proses tersebut menampilkan perintahnya. Jika konfigurasi yang diperbaiki masih tidak valid, proses awal tetap dihentikan.
• openclaw onboard --mode local dan openclaw setup menulis gateway.mode=local. Jika file konfigurasi ada tetapi gateway.mode tidak ditemukan, hal tersebut dianggap sebagai konfigurasi yang rusak/tertindih dan Gateway menolak menebak local untuk Anda — jalankan kembali orientasi awal, tetapkan kunci secara manual, atau berikan --allow-unconfigured.
• Pengikatan di luar loopback tanpa autentikasi diblokir.
• Nilai --bind lan, tailnet, dan custom saat ini di-resolve melalui jalur khusus IPv4; penyiapan host milik sendiri yang hanya menggunakan IPv6 memerlukan sidecar IPv4 atau proksi di depan Gateway.
• SIGUSR1 memicu mulai ulang dalam proses jika diotorisasi. commands.restart (default: diaktifkan) mengendalikan SIGUSR1 yang dikirim secara eksternal; tetapkan ke false untuk memblokir mulai ulang manual melalui sinyal OS. Alat gateway yang tersedia bagi agen bersifat hanya-baca; agen meminta mulai ulang melalui alat delegasi openclaw yang disetujui manusia.
• SIGINT/SIGTERM menghentikan proses tetapi tidak memulihkan status terminal khusus — jika Anda membungkus CLI dalam TUI atau input mode mentah, pulihkan terminal sendiri sebelum keluar.

• Catatan menyimpan metadata operasional: nama peristiwa, jumlah, ukuran byte, pembacaan memori, status antrean/sesi, ID persetujuan, nama saluran/Plugin, dan ringkasan sesi yang disunting. Catatan tidak menyertakan teks percakapan, isi Webhook, keluaran alat, isi mentah permintaan/respons, token, cookie, nilai rahasia, nama host, dan ID sesi mentah. Atur diagnostics.enabled: false untuk menonaktifkan perekam sepenuhnya.
• Penghentian fatal Gateway, batas waktu pematian, dan kegagalan startup saat dimulai ulang menulis snapshot diagnostik yang sama ke ~/.openclaw/logs/stability/openclaw-stability-*.json saat perekam memiliki peristiwa. Periksa bundel terbaru dengan openclaw gateway stability --bundle latest; --limit, --type, dan --since-seq juga berlaku untuk keluaran bundel.

• Tetap tersedia untuk diagnostik meskipun konfigurasi CLI lokal tidak ada atau tidak valid.
• Keluaran default membuktikan status layanan, koneksi WebSocket, dan kemampuan autentikasi yang terlihat saat handshake — bukan operasi baca/tulis/admin.
• Probe tidak melakukan perubahan untuk autentikasi perangkat pertama kali: probe menggunakan kembali token perangkat tersimpan yang sudah ada, tetapi tidak pernah membuat identitas perangkat CLI baru atau catatan pairing hanya-baca hanya untuk memeriksa status.
• Menyelesaikan SecretRef autentikasi yang dikonfigurasi untuk autentikasi probe jika memungkinkan. Jika SecretRef yang diperlukan tidak dapat diselesaikan, --json melaporkan rpc.authWarning saat konektivitas/autentikasi probe gagal; teruskan --token/--password secara eksplisit atau perbaiki sumber rahasia. Peringatan autentikasi yang belum terselesaikan disembunyikan setelah probe berhasil.
• Keluaran JSON menyertakan gateway.version saat Gateway yang berjalan melaporkannya; --require-rpc dapat kembali menggunakan payload RPC status.runtimeVersion jika probe handshake tidak dapat menyediakan metadata versi.
• Gunakan --require-rpc dalam skrip/otomatisasi saat layanan yang sedang mendengarkan belum memadai dan RPC cakupan-baca juga harus sehat.
• --deep memindai instalasi launchd/systemd/schtasks tambahan; saat ditemukan beberapa layanan mirip Gateway, keluaran yang dapat dibaca manusia mencetak petunjuk pembersihan (biasanya jalankan satu Gateway per mesin) dan melaporkan serah-terima mulai ulang supervisor terbaru jika relevan.
• --deep juga menjalankan validasi konfigurasi dalam mode yang mengetahui Plugin (pluginValidation: "full") dan menampilkan peringatan manifes Plugin (misalnya metadata konfigurasi saluran yang tidak ada). gateway status default mempertahankan jalur hanya-baca cepat yang melewati validasi Plugin.
• Keluaran yang dapat dibaca manusia menyertakan jalur log berkas yang telah diselesaikan beserta jalur/validitas konfigurasi CLI dibandingkan layanan untuk membantu mendiagnosis penyimpangan profil atau direktori status.
• Keluaran yang dapat dibaca manusia menyertakan Gateway heap: dengan batas yang diterapkan dan derivasi adaptifnya. Keluaran JSON menyajikan laporan yang sama sebagai service.gatewayHeap.

• Pemeriksaan penyimpangan autentikasi layanan membaca Environment= dan EnvironmentFile= dari unit (termasuk %h, jalur yang dikutip, beberapa berkas, dan berkas - opsional).
• Menyelesaikan SecretRef gateway.auth.token menggunakan lingkungan runtime gabungan (lingkungan perintah layanan terlebih dahulu, lalu lingkungan proses sebagai fallback).
• Pemeriksaan penyimpangan token melewati penyelesaian token konfigurasi saat autentikasi token tidak aktif secara efektif (gateway.auth.mode secara eksplisit password/none/trusted-proxy, atau mode tidak ditetapkan ketika kata sandi dapat diprioritaskan dan tidak ada kandidat token yang dapat diprioritaskan).

• Reachable: yes berarti setidaknya satu target menerima koneksi WebSocket.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only melaporkan hal yang dapat dibuktikan probe tentang autentikasi, secara 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. Dilaporkan sebagai keterjangkauan yang menurun, bukan kegagalan total.
• Read probe: failed setelah Connect: ok berarti WebSocket terhubung, tetapi diagnostik baca lanjutan kehabisan waktu atau gagal — juga menurun, bukan tidak dapat dijangkau.
• Seperti gateway status, probe menggunakan kembali autentikasi perangkat tersimpan yang sudah ada, tetapi tidak membuat identitas perangkat atau status pairing untuk pertama kalinya.
• Kode keluar hanya bukan nol jika 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: 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, dengan urutan: URL eksplisit, terowongan SSH, remote yang dikonfigurasi, loopback lokal.
• warnings[]: catatan peringatan upaya terbaik dengan code, message, dan targetIds opsional.
• network: petunjuk URL loopback lokal/tailnet yang diturunkan dari konfigurasi saat ini dan jaringan host.
• discovery.timeoutMs / discovery.count: anggaran penemuan/jumlah hasil aktual yang digunakan untuk tahap pemeriksaan ini.

Per target (targets[].connect): ok (keterjangkauan + klasifikasi terdegradasi), rpcOk (keberhasilan RPC detail penuh), scopeLimited (RPC detail gagal karena cakupan operator tidak tersedia).

Per target (targets[].auth): role dan scopes dilaporkan dalam hello-ok jika tersedia, beserta klasifikasi capability yang ditampilkan.

• ssh_tunnel_failed: penyiapan terowongan SSH gagal; perintah beralih kembali ke pemeriksaan langsung.
• multiple_gateways: identitas Gateway yang berbeda dapat dijangkau, atau OpenClaw tidak dapat membuktikan bahwa target yang dapat dijangkau merupakan Gateway yang sama. Terowongan SSH, URL proksi, atau URL remote yang dikonfigurasi ke Gateway yang sama tidak memicu hal ini.
• auth_secretref_unresolved: SecretRef autentikasi yang dikonfigurasi tidak dapat diurai untuk target yang gagal.
• probe_scope_limited: koneksi WebSocket berhasil, tetapi pemeriksaan baca dibatasi karena operator.read tidak tersedia.
• local_tls_runtime_unavailable: TLS Gateway lokal diaktifkan, tetapi OpenClaw tidak dapat memuat sidik jari sertifikat lokal.

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

• gateway start bersifat idempoten: ketika layanan terkelola sudah berjalan, perintah ini melaporkan proses yang berjalan dan membiarkannya tanpa perubahan. Layanan yang telah dimuat tetapi berhenti akan dimulai seperti sebelumnya.
• Gunakan gateway restart untuk memulai ulang layanan terkelola. Jangan merangkai gateway stop dan gateway start sebagai pengganti mulai ulang.
• Dalam shell noninteraktif, gateway stop memerlukan --force. Terminal interaktif mempertahankan perilaku tanpa prompt yang ada. Untuk otomatisasi dan pengujian, utamakan gateway run --dev atau --profile yang terisolasi dengan port kosong.
• Di macOS, gateway stop menggunakan launchctl bootout secara bawaan, yang menghapus LaunchAgent dari sesi boot saat ini tanpa mempertahankan penonaktifan — pemulihan otomatis KeepAlive tetap aktif untuk kegagalan mendatang dan gateway start mengaktifkannya kembali dengan bersih tanpa launchctl enable manual. Teruskan --disable untuk menekan KeepAlive dan RunAtLoad secara persisten agar gateway tidak muncul kembali hingga gateway start eksplisit berikutnya; gunakan ini ketika penghentian manual harus tetap berlaku setelah boot ulang.
• Mutasi siklus hidup Gateway menambahkan catatan audit pasangan kunci-nilai berbasis upaya terbaik ke <state-dir>/logs/gateway-restart.log, termasuk operasi mulai, berhenti, dan mulai ulang CLI, permintaan mulai ulang aman, mulai ulang supervisor, serta serah terima terpisah.
• Perintah siklus hidup menerima --json untuk pembuatan skrip.

• gateway install menulis nilai NODE_OPTIONS khusus heap untuk layanan Gateway terkelola. Nilai ini menargetkan 50% dari memori yang dibatasi ketika Node melaporkan batas kontainer atau layanan, atau 50% dari memori fisik jika tidak.
• Rentang target nominal adalah 2048–8192 MiB, dengan batas ruang tambahan native sebesar 75%. Pada host kecil, batas ruang tambahan tersebut dapat membuat batas yang diterapkan berada di bawah nilai minimum nominal 2048 MiB.
• Nilai eksplisit --max-old-space-size yang valid dan sudah tersimpan dalam layanan terinstal dipertahankan selama instalasi ulang paksa dan perbaikan doctor. Flag NODE_OPTIONS lainnya tidak diteruskan ke layanan terkelola.
• NODE_OPTIONS dari shell sekitar tidak menggantikan kebijakan ini. Gunakan gateway status atau doctor untuk memeriksa nilai yang terinstal; jalankan openclaw gateway install --force untuk membuat ulang metadata layanan lama yang tidak memiliki pengaturan heap terkelola.
• Kebijakan ini hanya berlaku untuk layanan Gateway terkelola. gateway run di latar depan, layanan node, dan unit supervisor yang ditulis manual mempertahankan konfigurasi runtime masing-masing.

• Ketika autentikasi token memerlukan token dan gateway.auth.token dikelola oleh SecretRef, gateway install memvalidasi bahwa SecretRef dapat diresolusi, tetapi tidak menyimpan token yang telah diresolusi ke dalam metadata lingkungan layanan.
• Jika autentikasi token memerlukan token dan SecretRef token yang dikonfigurasi tidak dapat diresolusi, instalasi gagal secara tertutup alih-alih menyimpan teks biasa cadangan.
• Untuk autentikasi kata sandi pada gateway run, utamakan OPENCLAW_GATEWAY_PASSWORD, --password-file, atau gateway.auth.password yang didukung SecretRef daripada --password sebaris.
• Dalam mode autentikasi tersimpulkan, OPENCLAW_GATEWAY_PASSWORD yang hanya tersedia di shell tidak melonggarkan persyaratan token instalasi; gunakan konfigurasi 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 tidak ditetapkan, instalasi diblokir hingga mode ditetapkan secara eksplisit.