Integrasi Gateway untuk aplikasi eksternal

Aplikasi eksternal berkomunikasi dengan OpenClaw melalui protokol Gateway: transportasi WebSocket serta metode RPC. Gunakan protokol ini saat skrip, dasbor, tugas CI, ekstensi IDE, atau proses lain ingin memulai eksekusi agen, melakukan streaming peristiwa, menunggu hasil, membatalkan pekerjaan, atau memeriksa sumber daya Gateway.

Yang tersedia saat ini

Paket pustaka klien mendatang sedang dikembangkan secara internal, tetapi belum menjadi antarmuka instalasi publik. Perlakukan paket tersebut sebagai detail implementasi pratinjau hingga rilis mengumumkan paket yang dipublikasikan dan memiliki versi.

Jalur yang direkomendasikan

1. Jalankan atau temukan Gateway.
2. Hubungkan melalui protokol Gateway.
3. Panggil metode RPC yang terdokumentasi dari referensi RPC Gateway.
4. Sematkan versi OpenClaw yang menjadi target pengujian Anda.
5. Periksa kembali referensi RPC saat meningkatkan OpenClaw.

Untuk eksekusi agen, mulai dengan RPC agent dan pasangkan dengan agent.wait untuk mendapatkan hasil terminal. Untuk status percakapan yang persisten, gunakan metode sessions.*. Untuk integrasi UI, berlangganan peristiwa Gateway dan render hanya kelompok peristiwa yang dipahami aplikasi Anda.

Penangguhan host secara kooperatif

Pengontrol hosting yang membekukan atau membuat snapshot proses yang sedang berjalan dapat menggunakan jabat tangan penangguhan yang netral terhadap host:

1. Hentikan penerimaan trafik masuk eksternal yang dikendalikan oleh host.
2. Panggil gateway.suspend.prepare dengan requestId yang stabil dan unik.
3. Jika responsnya busy, biarkan proses tetap berjalan dan coba lagi nanti.
4. Jika responsnya ready, simpan suspensionId yang dikembalikan, lalu bekukan atau buat snapshot proses sebelum expiresAtMs.
5. Setelah proses dicairkan, atau jika penangguhan dibatalkan, panggil gateway.suspend.resume dengan suspensionId tersebut melalui WebSocket yang sudah ada atau jalur kontrol Admin HTTP.

Gateway yang telah disiapkan menolak jabat tangan WebSocket baru. Pengontrol WebSocket harus mempertahankan koneksi terautentikasinya tetap terbuka selama operasi host. Jika hal itu tidak dapat dijamin, aktifkan dan gunakan Plugin RPC Admin HTTP sebelum melakukan persiapan. Jika jalur kontrol terputus, tunggu hingga sewa dua menit berakhir sebelum menyambungkan kembali; berakhirnya masa sewa akan membuka kembali penerimaan secara otomatis.

Kontrak RPC-nya adalah:

• gateway.suspend.prepare — operator.admin; parameter { "requestId": "stable-host-operation-id" }
• gateway.suspend.status — operator.read; parameter { "suspensionId": "id-from-prepare" }
• gateway.suspend.resume — operator.admin; parameter { "suspensionId": "id-from-prepare" }

Spasi di awal dan akhir ID dihapus, ID harus mengandung karakter selain spasi, dan dibatasi hingga 128 karakter. Hasil persiapan sibuk memiliki status: "busy", reason, retryAfterMs, activeCount, dan blockers. Hasil siap memiliki bentuk berikut:

{  "status": "ready",  "suspensionId": "2c3f...",  "expiresAtMs": 1770000000000,  "activeCount": 0,  "blockers": []}

Status mengembalikan {"status":"running"} atau hasil siap dengan expiresAtMs. Pelanjutan mengembalikan {"ok":true,"status":"running","resumed":true}; mengulanginya setelah pelanjutan berhasil akan mengembalikan resumed: false.

ID permintaan yang bersaing atau kegagalan sementara dalam melanjutkan penjadwal akan mengembalikan UNAVAILABLE yang dapat dicoba ulang beserta retryAfterMs. Selama pemulihan penjadwal, persiapan, status, dan pelanjutan semuanya mengembalikan galat tersebut, Gateway tetap tidak siap dan gagal secara tertutup, serta host tidak boleh membekukan atau membuat snapshot-nya. OpenClaw mencoba kembali penjadwal secara otomatis dan hanya membuka kembali penerimaan setelah pemulihan berhasil. ID pelanjutan yang tidak cocok mengembalikan INVALID_REQUEST. Persiapan berbagi anggaran penulisan bidang kontrol Gateway sebanyak tiga percobaan per menit; patuhi penundaan percobaan ulang yang dikembalikan. Klien WebSocket dikelompokkan berdasarkan perangkat dan IP. Pengontrol Admin HTTP dikelompokkan berdasarkan IP klien yang telah diurai, sehingga pengontrol di balik satu proksi dapat berbagi anggaran.

Persiapan hanya melakukan penolakan: OpenClaw menutup penerimaan root/sesi/perintah baru, menjeda tick cron otomatis, dan memeriksa pekerjaan secara sinkron. Jika ada sesuatu yang aktif, OpenClaw melanjutkan penjadwal dan membuka kembali penerimaan sebelum mengembalikan busy; OpenClaw tidak menginterupsi atau menguras pekerjaan tersebut. Sewa siap berlangsung selama dua menit. Mengulangi prepare dengan requestId yang sama akan memperbaruinya; berakhirnya masa sewa akan melanjutkan penjadwal sebelum membuka kembali penerimaan. Emisi mulai ulang yang jatuh tempo selama sewa siap akan menunggu hingga sewa dilanjutkan; mulai ulang yang sedang berlangsung menyebabkan persiapan mengembalikan busy.

Saat siap, /healthz tetap aktif dan /readyz mengembalikan 503. Respons kesiapan lokal atau terautentikasi menyertakan gateway-draining; pemeriksaan jarak jauh tanpa autentikasi hanya menerima { "ready": false }. Pemeriksaan kesehatan HTTP, metode penangguhan pada koneksi WebSocket yang sudah ada, dan rute RPC Admin HTTP yang telah diaktifkan tetap tersedia. RPC lainnya mengembalikan UNAVAILABLE yang dapat dicoba ulang. Rute HTTP pekerjaan pengguna bawaan dan rute HTTP Plugin biasa, termasuk API yang kompatibel dengan OpenAI, operasi alat/sesi, pemantauan Node, dan hook yang dikonfigurasi, mengembalikan 503 dengan error.code: "gateway_unavailable". Peningkatan WebSocket baru yang dimiliki Plugin juga mengembalikan 503; ini mencakup kepemilikan peningkatan, bukan pekerjaan yang kemudian dilakukan melalui soket Plugin yang telah terbentuk.

Jabat tangan ini tidak mempersistenkan pesan masuk, menghentikan transportasi saluran pihak ketiga, atau mengendalikan platform hosting. Host harus membatasi trafik masuknya sebelum persiapan dan tetap bertanggung jawab atas pengaktifan, snapshot/pembekuan, dan penghentian. activeCount adalah jumlah agregat pekerjaan terlacak, sedangkan blockers berisi jumlah kategori yang tidak nol dan detail tugas yang dibatasi. Ini bukan penghalang ketenangan proses umum. Pemblokir background-exec hanya bersifat agregat: teks perintah, ID proses, keluaran, serta pengidentifikasi sesi atau cakupan tidak pernah melintasi protokol. Kesehatan saluran, pemeliharaan, penyegaran cache, sesi WebSocket Plugin yang telah terbentuk, dan pekerjaan latar belakang milik Plugin yang tidak terdaftar dapat tetap aktif. Platform hosting harus membekukan atau membuat snapshot seluruh pohon proses dan sistem berkasnya secara konsisten; pekerjaan yang tidak terdaftar tidak dapat dibuktikan sedang menganggur oleh kontrak pertama ini.

Kode aplikasi vs kode Plugin

Gunakan RPC Gateway saat kode berada di luar OpenClaw:

• Skrip Node yang memulai atau mengamati eksekusi agen
• Tugas CI yang memanggil Gateway
• dasbor dan panel admin
• ekstensi IDE
• jembatan eksternal yang tidak perlu menjadi Plugin saluran
• pengujian integrasi dengan transportasi Gateway palsu atau nyata

Gunakan SDK Plugin saat kode berjalan di dalam OpenClaw:

• Plugin penyedia
• Plugin saluran
• hook alat atau siklus hidup
• Plugin harness agen
• pembantu runtime tepercaya

Aplikasi eksternal tidak boleh mengimpor openclaw/plugin-sdk/*; subjalur tersebut ditujukan untuk Plugin yang dimuat oleh OpenClaw.

Terkait

• Protokol Gateway
• Referensi RPC Gateway
• Perintah agen CLI
• Perintah pesan CLI
• Loop agen
• Runtime agen
• Sesi
• Tugas latar belakang
• Agen ACP
• Ikhtisar SDK Plugin