Gateway-integraties voor externe apps

Externe apps communiceren met OpenClaw via het Gateway-protocol: WebSocket- transport plus RPC-methoden. Gebruik dit wanneer een script, dashboard, CI-taak, IDE- extensie of ander proces agentruns wil starten, gebeurtenissen wil streamen, op resultaten wil wachten, werk wil annuleren of Gateway-resources wil inspecteren.

Wat vandaag beschikbaar is

Aanbevolen werkwijze

1. Voer een Gateway uit of detecteer er een.
2. Maak verbinding via het Gateway-protocol.
3. Roep gedocumenteerde RPC-methoden aan uit de Gateway RPC-referentie.
4. Zet de OpenClaw-versie waartegen je test vast.
5. Controleer de RPC-referentie opnieuw wanneer je OpenClaw bijwerkt.

Begin voor agentruns met de RPC agent en combineer deze met agent.wait voor een eindresultaat. Gebruik de sessions.*-methoden voor duurzame gespreksstatus. Abonneer je voor UI-integraties op Gateway-gebeurtenissen en geef alleen de gebeurtenisfamilies weer die jouw app begrijpt.

Coöperatieve opschorting door de host

Hostingcontrollers die een actief proces bevriezen of er een snapshot van maken, kunnen de hostneutrale opschortingshandshake gebruiken:

1. Sta geen nieuwe externe toegang meer toe die door de host wordt beheerd.
2. Roep gateway.suspend.prepare aan met een stabiele, unieke requestId.
3. Als het antwoord busy is, laat je het proces actief en probeer je het later opnieuw.
4. Als het ready is, sla je de geretourneerde suspensionId op en bevriest het proces of maakt er een snapshot van vóór expiresAtMs.
5. Roep na het hervatten, of als de opschorting wordt afgebroken, gateway.suspend.resume aan met die suspensionId via de bestaande WebSocket of het Admin HTTP- besturingspad.

Een voorbereide Gateway weigert nieuwe WebSocket-handshakes. Een WebSocket-controller moet zijn geauthenticeerde verbinding tijdens de hostbewerking openhouden. Als dit niet kan worden gegarandeerd, schakel dan vóór de voorbereiding de Admin HTTP RPC-plugin in en gebruik deze. Als het besturingspad verloren gaat, wacht dan tot de lease van twee minuten verloopt voordat je opnieuw verbinding maakt; na het verlopen wordt toegang automatisch weer toegestaan.

Het RPC-contract is:

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

ID's worden bijgesneden, moeten een teken bevatten dat geen witruimte is en zijn beperkt tot 128 tekens. Een bezet voorbereidingsresultaat bevat status: "busy", reason, retryAfterMs, activeCount en blockers. Een gereed resultaat heeft deze vorm:

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

Status retourneert {"status":"running"} of een gereed resultaat met expiresAtMs. Hervatten retourneert {"ok":true,"status":"running","resumed":true}; als je dit na een geslaagde hervatting herhaalt, wordt resumed: false geretourneerd.

Een concurrerend aanvraag-ID of tijdelijke fout bij het hervatten van de planner retourneert de opnieuw te proberen fout UNAVAILABLE met retryAfterMs. Tijdens het herstel van de planner retourneren voorbereiding, status en hervatten allemaal die fout, blijft de Gateway niet gereed en gesloten bij fouten, en mag de host deze niet bevriezen of er een snapshot van maken. OpenClaw probeert de planner automatisch opnieuw en staat pas weer toegang toe nadat het herstel is geslaagd. Een niet-overeenkomend hervattings-ID retourneert INVALID_REQUEST. Voorbereiding deelt het schrijfbudget van het Gateway-besturingsvlak van drie pogingen per minuut; respecteer de geretourneerde wachttijd voor een nieuwe poging. WebSocket-clients worden per apparaat en IP gegroepeerd. Admin HTTP- controllers worden per vastgesteld client-IP gegroepeerd, waardoor controllers achter één proxy een budget kunnen delen.

Voorbereiding kan alleen weigeren: OpenClaw sluit nieuwe toegang voor root/sessie/opdracht, pauzeert automatische Cron-ticks en inspecteert werk synchroon. Als er iets actief is, hervat het de planner en staat het opnieuw toegang toe voordat busy wordt geretourneerd; dat werk wordt niet onderbroken of afgehandeld. Een gereedheidslease duurt twee minuten. Als prepare met dezelfde requestId wordt herhaald, wordt deze verlengd; bij het verlopen wordt de planner hervat voordat toegang opnieuw wordt toegestaan. Een herstartsignaal dat tijdens een gereedheidslease moet worden verzonden, wacht totdat de lease wordt hervat; een lopende herstart zorgt ervoor dat voorbereiding busy retourneert.

Terwijl de Gateway gereed is, blijft /healthz actief en retourneert /readyz 503. Lokale of geauthenticeerde gereedheidsantwoorden bevatten gateway-draining; niet-geauthenticeerde externe controles ontvangen alleen { "ready": false }. De HTTP-statuscontrole, opschortingsmethoden op bestaande WebSocket-verbindingen en een reeds ingeschakelde Admin HTTP RPC-route blijven beschikbaar. Andere RPC's retourneren de opnieuw te proberen fout UNAVAILABLE. Ingebouwde HTTP-routes voor gebruikerswerk en gewone HTTP-routes van plugins, waaronder OpenAI-compatibele API's, tool-/sessiebewerkingen, Node-observaties en geconfigureerde hooks, retourneren 503 met error.code: "gateway_unavailable". Nieuwe WebSocket-upgrades die eigendom zijn van plugins retourneren ook 503; dit betreft het eigenaarschap van de upgrade, niet werk dat later via een bestaande pluginsocket wordt uitgevoerd.

Deze handshake bewaart geen inkomende berichten, stopt geen kanaaltransporten van derden en bestuurt het hostingplatform niet. De host moet vóór de voorbereiding de eigen toegang afschermen en blijft verantwoordelijk voor activeren, snapshots/bevriezen en stoppen. activeCount is het totale aantal bijgehouden werkzaamheden, terwijl blockers de categorietellingen die niet nul zijn en begrensde taakdetails bevat. Dit is geen algemene barrière voor procesinactiviteit. Een background-exec-blokkering bevat alleen geaggregeerde gegevens: opdrachttekst, proces-ID's, uitvoer en sessie- of bereik-ID's worden nooit via het protocol doorgegeven. Kanaalstatus, onderhoud, cacheverversing, bestaande WebSocket-sessies van plugins en niet-geregistreerd achtergrondwerk dat eigendom is van plugins kunnen actief blijven. Het hostingplatform moet de volledige processtructuur en het bijbehorende bestandssysteem consistent bevriezen of er een snapshot van maken; met dit eerste contract kan niet worden bewezen dat niet-geregistreerd werk inactief is.

Appcode versus plugincode

Gebruik Gateway RPC wanneer code buiten OpenClaw wordt uitgevoerd:

• Node-scripts die agentruns starten of observeren
• CI-taken die een Gateway aanroepen
• dashboards en beheerpanelen
• IDE-extensies
• externe bridges die geen kanaalplugins hoeven te worden
• integratietests met gesimuleerde of echte Gateway-transporten

Gebruik de Plugin SDK wanneer code binnen OpenClaw wordt uitgevoerd:

• providerplugins
• kanaalplugins
• tool- of levenscyclushooks
• agentharnasplugins
• vertrouwde runtimehelpers

Externe apps mogen openclaw/plugin-sdk/* niet importeren; deze subpaden zijn bestemd voor plugins die door OpenClaw worden geladen.

Gerelateerd

• Een Gateway-client bouwen
• OpenClaw insluiten
• Gateway-protocol
• Gateway RPC-referentie
• CLI-agentopdracht
• CLI-berichtopdracht
• Agentlus
• Agentruntimes
• Sessies
• Achtergrondtaken
• ACP-agents
• Overzicht van de Plugin SDK