Integrasi Gateway untuk aplikasi eksternal

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

Yang tersedia saat ini

Jalur yang disarankan

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

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

Penangguhan host kooperatif

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

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

Gateway yang telah disiapkan menolak jabat tangan WebSocket baru. Pengontrol WebSocket harus menjaga 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 menghubungkan kembali; berakhirnya sewa secara otomatis membuka kembali penerimaan.

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" }

ID dipangkas, harus memuat 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 pelanjutan penjadwal mengembalikan UNAVAILABLE yang dapat dicoba ulang dengan retryAfterMs. Selama pemulihan penjadwal, persiapan, status, dan pelanjutan semuanya mengembalikan galat tersebut, Gateway tetap tidak siap dan tertutup saat gagal, 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 upaya per menit; patuhi waktu tunda percobaan ulang yang dikembalikan. Klien WebSocket dikelompokkan berdasarkan perangkat dan IP. Pengontrol Admin HTTP dikelompokkan berdasarkan IP klien yang diresolusikan, sehingga pengontrol di belakang satu proksi dapat berbagi anggaran.

Persiapan hanya bersifat menolak: 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 memperbaruinya; berakhirnya sewa melanjutkan penjadwal sebelum membuka kembali penerimaan. Emisi mulai ulang yang jatuh tempo selama sewa siap menunggu hingga sewa dilanjutkan; mulai ulang yang sedang berlangsung menyebabkan persiapan mengembalikan busy.

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

Jabat tangan ini tidak mempertahankan pesan masuk, menghentikan transportasi saluran pihak ketiga, atau mengendalikan platform hosting. Host harus membatasi ingress-nya sebelum persiapan dan tetap bertanggung jawab atas membangunkan, snapshot/pembekuan, dan penghentian. activeCount adalah jumlah agregat pekerjaan yang dilacak, sedangkan blockers memuat jumlah kategori bukan 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 tersambung, 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; kontrak pertama ini tidak dapat membuktikan bahwa pekerjaan yang tidak terdaftar sedang menganggur.

Kode aplikasi vs kode Plugin

Gunakan RPC Gateway ketika 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 ketika 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

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