Cloud-Worker

​

Was wo ausgeführt wird

​

Anforderungen

• Ein Worker-Provider-Plugin. Das mitgelieferte crabbox-Plugin steuert die Crabbox-CLI, die Leases über verschiedene Cloud-Backends hinweg vermittelt (AWS, Hetzner und andere). Die crabbox-Binärdatei muss sich in PATH befinden (oder legen Sie settings.binary fest), und die Provider-Anmeldedaten müssen bereits konfiguriert sein. Für die AWS-Zulassung ist Crabbox 0.38.1 oder neuer erforderlich.
• Für Crabbox-AWS-Worker muss der effektive Wert von aws.instanceProfile leer sein. Der Provider prüft crabbox config show --json vor der Zuweisung und verlangt anschließend, dass crabbox inspect --json den Wert providerMetadata.instanceProfileAttached: false aus EC2-DescribeInstances meldet. Leases mit einer Instanzrolle oder ohne maßgebliche Metadaten werden gestoppt und abgelehnt.
• Node.js auf der geleasten Maschine. Unveränderte Cloud-Images enthalten es üblicherweise nicht – installieren Sie es mit dem setup-Befehl des Profils.
• Eine Sitzung mit einem sitzungseigenen verwalteten Worktree (erstellen Sie einen mit worktree: true). Beim Dispatch wird der Inhalt dieses Worktrees verschoben; einfache Verzeichnisse werden als Manifestspiegel synchronisiert.

​

Konfiguration

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

​

Der Einrichtungsbefehl

​

Installationskanäle

• bundle bündelt dist des laufenden Gateways, eine bereinigte package.json und alle Arbeitsbereichspakete, auf die der Build verweist; alles wird durch einen Inhalts-Hash abgedeckt. Die Box prüft das unveränderte Bundle anhand dieses Hashs und installiert anschließend die npm-Produktionsabhängigkeiten (Skripte deaktiviert). So führen Sie einen Entwicklungs-Build auf einem Worker aus.
• npm weist nach, dass die Version in der öffentlichen Registry vorhanden ist, pinnt ihre SHA-512-Integrität und installiert openclaw@<version> exakt passend zum Gateway.

​

Eine Sitzung dispatchen

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

​

Sicherheitsmodell

• Geschlossener Worker-Eingang. Worker kommunizieren über ein dediziertes Protokoll auf dem getunnelten Socket mit einer geschlossenen Methoden-Positivliste – ein Worker kann keine Operator-RPCs aufrufen.
• Gateway-eigene Tool-Berechtigung. Vor jedem Durchlauf projiziert das Gateway die aktuellen Richtlinien für Profil, Provider, Agent, Gruppe, Absender, Sandbox, Delegierung, Vererbung und Laufzeitbegrenzung auf den festen Katalog der Coding-Tools des Workers. Der Start-Umschlag enthält nur diese endgültige Teilmenge aus einem geschlossenen Vokabular. Explizit begrenzte geplante Durchläufe verwenden ihren vertrauenswürdigen Kontext der Eigentümergruppe erneut, ohne diese Identität an die Box zu senden oder ein neues Absender-Overlay anzuwenden. Tools außerhalb des Worker-Katalogs bleiben nicht verfügbar; bei einem leeren Ergebnis erfolgt die Ausführung ohne Tools.
• Ausgestellte Anmeldedaten, gehasht gespeichert. Jede Verteilung stellt Worker-Anmeldedaten aus; das Gateway speichert nur deren Hash. Die Rotation der Anmeldedaten und die Absicherung durch Eigentümer-Epochen gewährleisten höchstens einen aktiven Eigentümer pro Sitzung – ein veralteter Worker, der sich erneut verbindet, wird abgegrenzt und niemals zusammengeführt.
• Fixierung des Host-Schlüssels. Der Provider muss bei der Bereitstellung den SSH-Host-Schlüssel der Box bereitstellen; der Bootstrap stellt die Verbindung mit strikter Fixierung her und schlägt ohne ihn sicher geschlossen fehl.
• Keine dauerhaft hinterlegten Modell-, Forge- oder Cloud-Anmeldedaten auf der Box. Die Modellauthentifizierung verbleibt auf dem Gateway (die Inferenz wird über eine {provider, model}-Referenz übertragen), Git-Commits im Workspace werden ohne Forge-Anmeldedaten erstellt und die AWS-Lease-Metadaten von Crabbox werden vor der Einrichtung verbindlich auf eine Instanzrolle geprüft. Auch Einrichtungsbefehle müssen frei von Anmeldedaten bleiben.
• Provider-eigener ausgehender Datenverkehr. Der Rückwärtstunnel beseitigt für OpenClaw die Notwendigkeit eines direkten Modellzugriffs, aber OpenClaw schreibt Provider-Firewalls nicht um. Beschränken Sie den ausgehenden Datenverkehr beim Worker-Provider, wenn die Aufgabe dies erfordert.
• Dauerhafte, genau einmal gespeicherte Transkripte. Der Worker schreibt Transkript-Batches über ein Compare-and-Swap-Protokoll gegen das Blatt der Sitzung fest; bei einer veralteten Basis wird der Durchlauf sicher angehalten, statt kostenpflichtige Ausgabe zu duplizieren oder neu zu basieren.

​

Fehlerbehebung

• sessions.dispatch ist eine unbekannte Methode – es sind keine cloudWorkers.profiles konfiguriert oder dem Aufrufer fehlt operator.admin.
• „Cloud-Worker-Durchläufe erfordern die OpenClaw-Laufzeit“ – wählen Sie ein Modell, dessen konfigurierte Laufzeit OpenClaw ist. Externe CLI-Laufzeiten wie claude-cli unterstützen keine Worker-Inferenz.
• „Der Worker-Bootstrap erfordert Node.js auf dem geleasten Host“ – fügen Sie settings.setup eine Node-Installation hinzu (siehe oben).
• Die Attestierung der AWS-Instanzrolle schlägt fehl – leeren Sie aws.instanceProfile (und CRABBOX_AWS_INSTANCE_PROFILE, falls festgelegt). Installieren Sie Crabbox 0.38.1 oder neuer; ältere Binärdateien stellen den für die AWS-Zulassung erforderlichen verbindlichen providerMetadata.instanceProfileAttached-Vertrag nicht bereit.
• Die Verteilung schlägt mit einem Provider-Fehler fehl – der Platzierungsdatensatz und environments.list speichern den letzten Fehler einschließlich des Endes der stderr-Ausgabe von Einrichtung und Bootstrap. Boxen werden bei einem Fehler zerstört, daher ist dieses Ausgabeende die primäre forensische Informationsquelle.
• Client-Zeitüberschreitung während der Verteilung – openclaw gateway call verwendet standardmäßig eine Zeitüberschreitung von 10s; bemessen Sie --timeout großzügig (die Verteilung läuft in jedem Fall serverseitig weiter, und ein erneuter Versuch während der Bereitstellung wird mit session cannot dispatch from placement provisioning abgelehnt).
• Worker nach einem Upgrade von einer Beta-Version 2026.7.2 zurückgefordert – diese Beta-Versionen verwendeten den älteren Worker-Startvertrag. Bei einem Neustart zerstört OpenClaw einen inaktiven inkompatiblen Worker, behält Sitzung und Workspace bei, markiert die Platzierung als zurückgefordert und stellt bei der nächsten Verteilung oder beim nächsten Durchlauf einen aktuellen Worker bereit. Ein Beta-Worker, der während des Starts unterbrochen wurde, wird nach der Bereinigung als fehlgeschlagen markiert; wiederholen Sie die Verteilung, um ihn mit dem aktuellen Vertrag bereitzustellen.
• Hinweis auf einen Cloud-Workspace-Konflikt – der Durchlauf wurde abgeschlossen und hat für jeden aufgeführten Pfad die lokale Version beibehalten. Verwenden Sie die Befehle für die bereitgestellte Referenz im Hinweis, um die Cloud-Version zu prüfen oder zu übernehmen; für die konfliktfreien Änderungen ist kein erneuter Versuch erforderlich, da sie bereits angewendet wurden.
• „Das Workspace-Ergebnis des vorherigen Cloud-Durchlaufs wird noch abgeglichen“ – das Gateway hat kurz auf die dauerhafte Sperre des vorherigen Ergebnisses gewartet und konnte den Anspruch auf die Sitzung nicht erwerben. Warten Sie, bis der Abgleich abgeschlossen ist, und wiederholen Sie dann den Durchlauf; ein Neustart des Gateways ist sicher, da die Wiederherstellung bereitgestellte Ergebnisse erhält, bevor sie einen ausgefallenen Worker zurückfordert.
• Lease-Verwaltung – crabbox list --provider <backend> zeigt aktive Leases an; crabbox stop --provider <backend> --id <lease> gibt eine Lease manuell frei. Inaktive Leases laufen entsprechend dem idleTimeout des Profils ab.

​

Verwandte Themen

• Sandboxing – Verringerung des Schadensradius bei lokaler Tool-Ausführung
• Sitzungs-CLI – Überprüfung gespeicherter Sitzungen
• Konfigurationsreferenz