Menyematkan OpenClaw

Host penyemat harus mengawasi executable openclaw yang terinstal, menggunakan protokol WebSocket Gateway sebagai bidang kontrolnya, dan memperlakukan proses anak sebagai runtime yang dapat diganti. Pendekatan ini membuat kepemilikan proses, kesiapan, pemulihan kegagalan, dan peningkatan tetap eksplisit tanpa bergantung pada tata letak status privat OpenClaw.

Untuk autentikasi klien dan status penyambungan ulang, baca Membangun klien Gateway.

Mulai proses anak dengan preset penyematan

Gunakan instalasi node_modules yang sebenarnya dan jalankan executable paket. Baseline yang berguna untuk host yang memiliki siklus hidup penemuan, mulai ulang, dan saluran adalah:

   // Berikan jalur absolut ke runtime Node sebenarnya yang dikelola oleh aplikasi host.declare const hostNodeExecutable: string; const packageEntry = fileURLToPath(import.meta.resolve("openclaw"));const openclawEntry = resolve(dirname(packageEntry), "..", "openclaw.mjs");const gateway = spawn(hostNodeExecutable, [openclawEntry, "gateway", "--allow-unconfigured"], {  env: {    ...process.env,    OPENCLAW_DISABLE_BONJOUR: "1",    OPENCLAW_EXEC_SHELL_SNAPSHOT: "0",    OPENCLAW_NO_RESPAWN: "1",    OPENCLAW_SKIP_CHANNELS: "1",  },  stdio: ["ignore", "inherit", "inherit"],});

Resolusikan OpenClaw melalui paket yang terinstal seperti yang ditunjukkan; jangan berasumsi bahwa biner openclaw lokal proyek tersedia di PATH proses host. Contoh ini mewarisi keluaran agar proses anak tidak terblokir akibat pipa stdout atau stderr yang penuh. Jika host mengambil alih aliran tersebut, pasang konsumen segera setelah proses dijalankan.

--allow-unconfigured hanya melewati pelindung pemulaian gateway.mode=local. Opsi ini tidak menulis konfigurasi atau memperbaiki berkas yang tidak valid. Hilangkan opsi ini saat aplikasi penyemat menyediakan konfigurasi lokal normal melalui orientasi awal, CLI konfigurasi, atau RPC Gateway.

Peringatan snapshot shell Electron

Pengambilan snapshot shell menjalankan process.execPath -e <script> dari shell login. Dalam proses Node normal, process.execPath adalah executable Node. Di bawah Electron, nilai tersebut adalah biner Electron, yang dapat menafsirkan pemanggilan itu sebagai peluncuran aplikasi dan menampilkan popup "Unable to find Electron app". Atur OPENCLAW_EXEC_SHELL_SNAPSHOT=0 di lingkungan proses anak Gateway, bukan hanya di proses perender. Karena alasan yang sama, hostNodeExecutable harus menunjuk ke runtime Node sebenarnya, bukan process.execPath milik Electron.

Tangani konfigurasi tidak valid berdasarkan kode keluar

Pemulaian Gateway menggunakan kode keluar 78 (EX_CONFIG) untuk kegagalan pemulaian kelas konfigurasi, termasuk konfigurasi yang tidak valid. Buat percabangan berdasarkan kode keluar, bukan dengan mengurai stderr yang dapat dibaca manusia:

1. Jalankan openclaw doctor --fix --yes --non-interactive terhadap lingkungan konfigurasi dan status yang sama dengan proses anak Gateway.
2. Coba mulai Gateway sekali lagi setelah doctor berhasil selesai.
3. Jika proses anak kembali keluar dengan 78, hentikan perulangan perbaikan dan tampilkan kegagalan konfigurasi kepada pengguna.

Pertahankan stderr untuk diagnostik, tetapi jangan membuat keputusan siklus hidup berdasarkan susunan katanya.

Setelah pemulaian berhasil, pengeditan langsung konfigurasi yang tidak valid tidak terlalu merusak. Pengawas konfigurasi mencatat bahwa pemuatan ulang dilewati dan terus melayani konfigurasi dalam memori terakhir yang diterima. Perbaiki berkas, lalu biarkan pengawas menerima snapshot valid berikutnya.

Tunggu kesiapan protokol

Gunakan sinyal WebSocket, bukan substring log:

1. Buka WebSocket Gateway.
2. Tunggu peristiwa connect.challenge. Peristiwa ini membuktikan bahwa listener menerima WebSocket dan handshake tantangan dapat dimulai.
3. Kirim connect dengan tanda tangan perangkat yang terikat pada tantangan.
4. Perlakukan hello-ok sebagai kesiapan aplikasi untuk RPC terautentikasi.

Tantangan sengaja dikirim lebih awal daripada inisialisasi penuh. Jika sidecar pemulaian masih tertunda, connect mengembalikan galat UNAVAILABLE yang dapat dicoba ulang dengan details.reason: "startup-sidecars", retryAfterMs yang dibatasi, lalu menutup dengan kode 1013 dan alasan gateway starting. Gunakan resolveGatewayStartupRetryAfterMs dari @openclaw/gateway-protocol/startup-unavailable atau kebijakan bawaan klien referensi, lalu sambungkan kembali.

Tafsirkan mulai ulang dan penghentian

Sebelum penutupan teratur, Gateway menyiarkan peristiwa shutdown dengan reason dan restartExpectedMs. Nilai restartExpectedMs yang bukan null berarti mulai ulang dalam proses atau terawasi diharapkan; null berarti penghentian terminal.

Kode penutupan WebSocket berikutnya adalah 1012 untuk kedua kasus. Alasan penutupan klien biasa juga service restart dalam kedua kasus, sehingga baik kode penutupan maupun alasannya tidak membedakan mulai ulang dari penghentian. Pertahankan payload shutdown sebelumnya saat payload tersebut tiba, dan gabungkan dengan maksud penghentian host sendiri serta status keluar proses anak. Jika koneksi terputus tanpa peristiwa tersebut, gunakan kebijakan penyambungan ulang terbatas dan pengawasan proses anak seperti biasa.

Gunakan RPC, bukan berkas status

Pertahankan Gateway sebagai satu-satunya pemilik status OpenClaw. Operasi penyematan umum sudah memiliki metode RPC:

config.get menyunting nilai sensitif dan pengidentifikasi SecretRef sebelum mengembalikan snapshot. Metode tulis juga mengembalikan konfigurasi yang telah disunting. Klien harus memperlakukan sentinel penyuntingan sebagai buram dan menggunakan kontrak penulisan konfigurasi yang terdokumentasi; klien tidak boleh mengharapkan Gateway mengembalikan rahasia dalam teks biasa.

Jangan membaca atau mengubah berkas, tabel SQLite, berkas transkrip, atau direktori cache di bawah ~/.openclaw untuk mengimplementasikan fitur aplikasi. Tata letak tersebut adalah detail implementasi runtime privat dan dapat dipindahkan atau diubah tanpa kompatibilitas protokol.

Instal; jangan ratakan

Paket root openclaw bukan target vendorisasi berkas tunggal. Berkas runtime yang dibundel di bawah dist/extensions mempertahankan impor mandiri tanpa prefiks seperti openclaw/plugin-sdk/*, sementara paket npm sengaja mengecualikan pohon node_modules per ekstensi.

Instal OpenClaw melalui npm, pnpm, atau instalasi paket Node normal lainnya agar Node dapat meresolusikan ekspor paket dan pohon dependensi root. Jalankan executable openclaw yang terinstal. Jangan hanya menyalin dist, meratakan paket ke dalam bundel aplikasi, atau mem-vendor berkas ekstensi tertentu.

Terkait

• Membangun klien Gateway
• Protokol Gateway
• CLI Gateway
• Integrasi Gateway untuk aplikasi eksternal