Harici uygulamalar için Gateway entegrasyonları

Harici uygulamalar OpenClaw ile Gateway protokolü üzerinden iletişim kurar: WebSocket aktarımı ve RPC yöntemleri. Bir betik, pano, CI işi, IDE uzantısı veya başka bir işlem; ajan çalıştırmalarını başlatmak, olayları akış halinde almak, sonuçları beklemek, çalışmayı iptal etmek ya da Gateway kaynaklarını incelemek istediğinde bunu kullanın.

Bugün kullanılabilenler

Önerilen yol

1. Bir Gateway çalıştırın veya keşfedin.
2. Gateway protokolü üzerinden bağlanın.
3. Gateway RPC referansında belgelenen RPC yöntemlerini çağırın.
4. Test ettiğiniz OpenClaw sürümünü sabitleyin.
5. OpenClaw'ı yükseltirken RPC referansını yeniden kontrol edin.

Ajan çalıştırmaları için agent RPC'siyle başlayın ve terminal sonucu için bunu agent.wait ile eşleştirin. Kalıcı konuşma durumu için sessions.* yöntemlerini kullanın. Kullanıcı arayüzü entegrasyonlarında Gateway olaylarına abone olun ve yalnızca uygulamanızın anladığı olay ailelerini işleyin.

İş birliğine dayalı ana makine askıya alma

Çalışan bir işlemi donduran veya anlık görüntüsünü alan barındırma denetleyicileri, ana makineden bağımsız askıya alma el sıkışmasını kullanabilir:

1. Ana makinenin denetlediği harici girişlerin kabulünü durdurun.
2. Kararlı ve benzersiz bir requestId ile gateway.suspend.prepare çağrısı yapın.
3. Yanıt busy ise işlemi çalışır durumda tutun ve daha sonra yeniden deneyin.
4. Yanıt ready ise döndürülen suspensionId değerini kaydedin, ardından expiresAtMs öncesinde işlemi dondurun veya anlık görüntüsünü alın.
5. Çözüldükten sonra veya askıya alma işleminden vazgeçilirse mevcut WebSocket ya da Admin HTTP denetim yolu üzerinden bu suspensionId ile gateway.suspend.resume çağrısı yapın.

Hazırlanmış bir Gateway, yeni WebSocket el sıkışmalarını reddeder. Bir WebSocket denetleyicisi, ana makine işlemi boyunca kimliği doğrulanmış bağlantısını açık tutmalıdır. Bu garanti edilemiyorsa hazırlamadan önce Admin HTTP RPC Pluginini etkinleştirin ve kullanın. Denetim yolu kaybolursa yeniden bağlanmadan önce iki dakikalık kiralamanın süresinin dolmasını bekleyin; süre dolduğunda kabul otomatik olarak yeniden açılır.

RPC sözleşmesi şöyledir:

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

Kimliklerin başındaki ve sonundaki boşluklar kaldırılır, en az bir boşluk olmayan karakter içermeleri gerekir ve uzunlukları 128 karakterle sınırlıdır. Meşgul bir hazırlama sonucunda status: "busy", reason, retryAfterMs, activeCount ve blockers bulunur. Hazır bir sonuç şu biçimdedir:

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

Durum, {"status":"running"} veya expiresAtMs içeren hazır bir sonuç döndürür. Devam ettirme {"ok":true,"status":"running","resumed":true} döndürür; başarılı bir devam ettirmeden sonra yinelenmesi resumed: false döndürür.

Çakışan bir istek kimliği veya geçici zamanlayıcı devam ettirme hatası, retryAfterMs içeren yeniden denenebilir UNAVAILABLE döndürür. Zamanlayıcı kurtarması sırasında hazırlama, durum ve devam ettirme işlemlerinin tümü bu hatayı döndürür; Gateway hazır olmayan ve kapalı başarısızlık durumunda kalır, ana makine de onu dondurmamalı veya anlık görüntüsünü almamalıdır. OpenClaw, zamanlayıcıyı otomatik olarak yeniden dener ve kabulü yalnızca kurtarma başarılı olduktan sonra yeniden açar. Eşleşmeyen bir devam ettirme kimliği INVALID_REQUEST döndürür. Hazırlama, Gateway'in dakikada üç denemelik denetim düzlemi yazma bütçesini paylaşır; döndürülen yeniden deneme gecikmesine uyun. WebSocket istemcileri cihaz ve IP'ye göre gruplandırılır. Admin HTTP denetleyicileri çözümlenen istemci IP'sine göre gruplandırılır; dolayısıyla tek bir proxy arkasındaki denetleyiciler bir bütçeyi paylaşabilir.

Hazırlama yalnızca reddetme amaçlıdır: OpenClaw yeni kök/oturum/komut kabulünü kapatır, otomatik Cron döngülerini duraklatır ve çalışmayı eşzamanlı olarak inceler. Etkin bir şey varsa busy döndürmeden önce zamanlayıcıyı devam ettirir ve kabulü yeniden açar; bu çalışmayı kesintiye uğratmaz veya boşaltmaz. Hazır kiralama iki dakika sürer. Aynı requestId ile prepare çağrısının yinelenmesi kiralamayı yeniler; süre dolduğunda kabul yeniden açılmadan önce zamanlayıcı devam ettirilir. Hazır kiralama sırasında zamanı gelen yeniden başlatma yayımı, kiralama devam ettirilene kadar bekler; devam eden bir yeniden başlatma, hazırlamanın busy döndürmesine neden olur.

Hazır durumdayken /healthz çalışmaya devam eder ve /readyz, 503 döndürür. Yerel veya kimliği doğrulanmış hazır olma yanıtları gateway-draining içerir; kimliği doğrulanmamış uzak yoklamalar yalnızca { "ready": false } alır. HTTP sağlık yoklaması, mevcut WebSocket bağlantılarındaki askıya alma yöntemleri ve önceden etkinleştirilmiş Admin HTTP RPC rotası kullanılabilir durumda kalır. Diğer RPC'ler yeniden denenebilir UNAVAILABLE döndürür. OpenAI uyumlu API'ler, araç/oturum işlemleri, Node izlemeleri ve yapılandırılmış kancalar dâhil olmak üzere yerleşik HTTP kullanıcı-çalışma rotaları ve sıradan Plugin HTTP rotaları, error.code: "gateway_unavailable" ile 503 döndürür. Yeni Plugin sahipli WebSocket yükseltmeleri de 503 döndürür; bu, yükseltme sahipliğini kapsar, kurulu bir Plugin soketi üzerinden daha sonra gerçekleştirilen çalışmayı kapsamaz.

Bu el sıkışma gelen mesajları kalıcılaştırmaz, üçüncü taraf kanal aktarımlarını durdurmaz veya barındırma platformunu denetlemez. Ana makine, hazırlamadan önce girişlerini sınırlandırmalı; uyandırma, anlık görüntü/dondurma ve durdurma sorumluluğunu taşımaya devam etmelidir. activeCount toplam izlenen çalışma sayısıdır; blockers ise sıfır olmayan kategori sayılarını ve sınırlandırılmış görev ayrıntılarını içerir. Bu, genel bir işlem durağanlığı engeli değildir. Bir background-exec engelleyicisi yalnızca toplam bilgidir: komut metni, işlem kimlikleri, çıktı ve oturum veya kapsam tanımlayıcıları protokol üzerinden hiçbir zaman aktarılmaz. Kanal sağlığı, bakım, önbellek yenileme, kurulmuş Plugin WebSocket oturumları ve kaydedilmemiş Plugin sahipli arka plan çalışmaları etkin kalabilir. Barındırma platformu, işlem ağacının tamamını ve dosya sistemini tutarlı biçimde dondurmalı veya anlık görüntüsünü almalıdır; bu ilk sözleşme, kaydedilmemiş çalışmanın boşta olduğunu kanıtlayamaz.

Uygulama kodu ve Plugin kodu

Kod OpenClaw dışında bulunuyorsa Gateway RPC kullanın:

• Ajan çalıştırmalarını başlatan veya gözlemleyen Node betikleri
• Bir Gateway çağıran CI işleri
• panolar ve yönetim panelleri
• IDE uzantıları
• kanal Pluginlerine dönüşmesi gerekmeyen harici köprüler
• sahte veya gerçek Gateway aktarımlarıyla entegrasyon testleri

Kod OpenClaw içinde çalışıyorsa Plugin SDK'yı kullanın:

• sağlayıcı Pluginleri
• kanal Pluginleri
• araç veya yaşam döngüsü kancaları
• ajan çalıştırma düzeneği Pluginleri
• güvenilir çalışma zamanı yardımcıları

Harici uygulamalar openclaw/plugin-sdk/* öğesini içe aktarmamalıdır; bu alt yollar OpenClaw tarafından yüklenen Pluginler içindir.

İlgili

• Gateway istemcisi oluşturma
• OpenClaw'ı gömme
• Gateway protokolü
• Gateway RPC referansı
• CLI ajan komutu
• CLI mesaj komutu
• Ajan döngüsü
• Ajan çalışma zamanları
• Oturumlar
• Arka plan görevleri
• ACP ajanları
• Plugin SDK'ya genel bakış