Cloudworkers

​

Wat waar wordt uitgevoerd

​

Vereisten

• Een provider-Plugin voor workers. De gebundelde crabbox-Plugin stuurt de Crabbox-CLI aan, die leases tussen cloudbackends (AWS, Hetzner en andere) bemiddelt. Het binaire bestand crabbox moet zich op PATH bevinden (of stel settings.binary in), met reeds geconfigureerde providerreferenties. Voor toelating tot AWS is Crabbox 0.38.1 of nieuwer vereist.
• Voor Crabbox AWS-workers moet de effectieve aws.instanceProfile leeg zijn. De provider controleert crabbox config show --json vóór toewijzing en vereist vervolgens dat crabbox inspect --json providerMetadata.instanceProfileAttached: false rapporteert vanuit EC2 DescribeInstances. Leases met een instancerol of zonder gezaghebbende metadata worden gestopt en geweigerd.
• Node.js op de geleasete machine. Kale cloudimages bevatten dit doorgaans niet — installeer het met de opdracht setup van het profiel.
• Een sessie met een door de sessie beheerde worktree (maak er een met worktree: true). Verzending verplaatst de inhoud van die worktree; gewone mappen worden als manifestspiegel gesynchroniseerd.

​

Configuratie

{
  "cloudWorkers": {
    "profiles": {
      "aws": {
        "provider": "crabbox",
        "install": "bundle",
        "settings": {
          "provider": "aws",
          "class": "standard",
          "ttl": "8h",
          "idleTimeout": "45m",
          "setup": "test -x /usr/bin/node || (curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs)"
        }
      }
    }
  }
}

​

De setup-opdracht

​

Installatiekanalen

• bundle verpakt de dist van de actieve Gateway, een opgeschoonde package.json en alle werkruimtepakketten waarnaar de build verwijst, allemaal gedekt door een inhoudshash. De machine verifieert de oorspronkelijke bundel aan de hand van die hash en installeert vervolgens npm-productieafhankelijkheden (scripts uitgeschakeld). Zo voer je een ontwikkelbuild uit op een worker.
• npm verifieert dat de release in het openbare register bestaat, zet de SHA-512-integriteit ervan vast en installeert openclaw@<version> dat exact met de Gateway overeenkomt.

​

Een sessie verzenden

openclaw gateway call sessions.create \
  --params '{"key":"agent:main:big-refactor","worktree":true,"cwd":"/path/to/repo","worktreeName":"big-refactor"}'

openclaw gateway call sessions.dispatch \
  --timeout 1500000 \
  --params '{"key":"agent:main:big-refactor","profileId":"aws"}'

openclaw gateway call sessions.reclaim \
  --timeout 600000 \
  --params '{"key":"agent:main:big-refactor"}'

​

Beveiligingsmodel

• Gesloten inkomend verkeer voor workers. Workers communiceren via een speciaal protocol op de getunnelde socket met een gesloten lijst van toegestane methoden — een worker kan geen RPC’s voor operators aanroepen.
• Door de Gateway beheerde toolbevoegdheid. Vóór elke beurt projecteert de Gateway het actuele beleid voor profiel, provider, agent, groep, afzender, sandbox, delegatie, overerving en runtimebeperkingen op de vaste catalogus met codeertools van de worker. De startenvelop bevat uitsluitend die definitieve subset met een gesloten vocabulaire. Expliciet begrensde geplande beurten hergebruiken hun vertrouwde context van de eigenaarsgroep zonder die identiteit naar de box te sturen of opnieuw een nieuwe afzenderoverlay toe te passen. Tools buiten de catalogus van de worker blijven niet beschikbaar; met een leeg resultaat wordt zonder tools gewerkt.
• Uitgegeven inloggegevens, gehasht opgeslagen. Elke dispatch geeft inloggegevens voor een worker uit; de Gateway slaat alleen de hash ervan op. Rotatie van inloggegevens en afscherming op basis van het eigenaarstijdperk garanderen maximaal één actieve eigenaar per sessie — een verouderde worker die opnieuw verbinding maakt, wordt afgeschermd en nooit samengevoegd.
• Vastzetten van hostsleutels. De provider moet tijdens het beschikbaar stellen de SSH-hostsleutel van de box beschikbaar maken; bootstrap maakt verbinding met strikte sleutelvastzetting en stopt veilig als de sleutel ontbreekt.
• Geen permanent aanwezige model-, forge- of cloudinloggegevens op de box. Modelauthenticatie blijft op de Gateway (inferentie verloopt via de {provider, model}-referentie), Git-commits in de werkruimte worden zonder forge-inloggegevens aangemaakt en de metadata van Crabbox AWS-leases wordt vóór de configuratie gezaghebbend gecontroleerd op een instantierol. Houd ook configuratiecommando’s vrij van inloggegevens.
• Door de provider beheerd uitgaand verkeer. Door de omgekeerde tunnel heeft OpenClaw geen directe modeltoegang nodig, maar OpenClaw herschrijft geen providerfirewalls. Beperk uitgaand verkeer bij de workerprovider wanneer de taak dit vereist.
• Duurzame transcripten die exact één keer worden vastgelegd. De worker legt transcriptbatches vast via een compare-and-swap-protocol tegen het blad van de sessie; bij een verouderde basis wordt de uitvoering onmiddellijk gestopt in plaats van betaalde uitvoer te dupliceren of te rebasen.

​

Probleemoplossing

• sessions.dispatch is een onbekende methode — er zijn geen cloudWorkers.profiles geconfigureerd of de aanroeper beschikt niet over operator.admin.
• “Cloudworkerbeurten vereisen de OpenClaw-runtime” — kies een model waarvan OpenClaw de geconfigureerde runtime is. Externe CLI-runtimes zoals claude-cli ondersteunen geen workerinferentie.
• “Voor de bootstrap van een worker is Node.js vereist op de geleasete host” — voeg een Node-installatie toe aan settings.setup (zie hierboven).
• Attestatie van de AWS-instantierol mislukt — wis aws.instanceProfile (en CRABBOX_AWS_INSTANCE_PROFILE, indien ingesteld). Installeer Crabbox 0.38.1 of nieuwer; oudere binaire bestanden bieden niet het gezaghebbende providerMetadata.instanceProfileAttached-contract dat voor AWS-toelating vereist is.
• Dispatch mislukt met een providerfout — de plaatsingsrecord en environments.list bewaren de laatste fout, inclusief het laatste deel van stderr van de configuratie/bootstrap. Boxen worden bij een fout vernietigd, dus dat laatste deel is de primaire bron voor forensisch onderzoek.
• Clienttime-out tijdens de dispatch — openclaw gateway call gebruikt standaard een time-out van 10s; geef --timeout ruim mee (de dispatch blijft in beide gevallen aan de serverzijde actief en een nieuwe poging tijdens het beschikbaar stellen wordt geweigerd met session cannot dispatch from placement provisioning).
• Worker teruggevorderd na een upgrade vanaf een bèta van 2026.7.2 — die bèta’s gebruikten het oudere startcontract voor workers. Bij een herstart vernietigt OpenClaw een inactieve incompatibele worker, behoudt het de sessie en werkruimte, markeert het de plaatsing als teruggevorderd en stelt het bij de volgende dispatch of beurt een actuele worker beschikbaar. Een bèta-worker die wordt onderbroken terwijl deze nog wordt gestart, wordt na het opschonen als mislukt gemarkeerd; probeer de dispatch opnieuw om de worker met het actuele contract beschikbaar te stellen.
• Melding van een conflict in de cloudwerkruimte — de beurt is voltooid en de lokale versie van elk vermeld pad is behouden. Gebruik de commando’s voor de klaargezette ref in de melding om de cloudversie te inspecteren of over te nemen; voor de niet-conflicterende wijzigingen, die al zijn toegepast, is geen nieuwe poging nodig.
• “Het werkruimteresultaat van de vorige cloudbeurt wordt nog gereconcilieerd” — de Gateway heeft kort gewacht op de duurzame barrière van het vorige resultaat en kon de sessieclaim niet verkrijgen. Wacht totdat de reconciliatie is voltooid en probeer de beurt vervolgens opnieuw; het herstarten van de Gateway is veilig, omdat het herstel klaargezette resultaten behoudt voordat een niet-werkende worker wordt teruggevorderd.
• Leasebeheer — crabbox list --provider <backend> toont actieve leases; crabbox stop --provider <backend> --id <lease> geeft er handmatig één vrij. Inactieve leases verlopen op basis van idleTimeout van het profiel.

​

Gerelateerd

• Sandboxing — de impact van lokale tooluitvoering beperken
• Sessies-CLI — opgeslagen sessies inspecteren
• Configuratiereferentie