Computernutzung

Mit der Computernutzung kann der Gateway-Agent einen leistungsfähigen gekoppelten Desktop sehen und steuern. Die Eignung basiert auf Fähigkeiten: Der verbundene Node muss sowohl computer.act als auch screen.snapshot ankündigen, wobei dessen Ergebnis ein displayFrameId enthalten muss. Das Tool erfasst einen Screenshot als Referenzbild und steuert anschließend Zeiger und Tastatur über den gefährlichen Befehl computer.act. Der Aktionssatz entspricht den zentralen Anthropic-Computer-Use-Aktionen; der optionale computer_20251124-Zoom wird nicht bereitgestellt. Ein visionsfähiges Modell steuert ihn über das integrierte Agent-Tool computer.

Der Agent gibt einen einheitlichen Befehl aus, computer.act; er kann nicht erkennen, wie ein Node ihn ausführt. Die mitgelieferte macOS-App verarbeitet den Befehl prozessintern mit eingebetteten Peekaboo-Diensten sowie gezielten CoreGraphics-Primitiven (korrekte TCC-Berechtigungen, kein zusätzlicher Prozess). Windows und Linux können das optionale, experimentelle Plugin cua-computer mit einer separat installierten Binärdatei cua-driver verwenden. Beide Implementierungen verwenden dieselben Richtlinien für Kopplung und Aktivierung.

Anforderungen

• Ein gekoppelter, verbundener Node, der sowohl computer.act als auch screen.snapshot ankündigt, wobei screen.snapshot den Wert displayFrameId zurückgibt.
• macOS-Implementierung: App-Einstellung Allow Computer Control aktiviert (Standard: aus).
• macOS-Implementierung: OpenClaw wurde die Berechtigung Accessibility (für die Zeiger-/Tastatureingabe) sowie die Berechtigung Screen Recording (für screen.snapshot) erteilt.
• Windows-/Linux-Implementierung: Mitgeliefertes Plugin cua-computer aktiviert und eine kompatible ausführbare Datei cua-driver der Version 0.10.x installiert.
• Der Befehl computer.act ist auf dem Gateway aktiviert (er ist gefährlich und standardmäßig deaktiviert).
• Ein visionsfähiges Agent-Modell.
• Eine Tool-Richtlinie, die computer bereitstellt. Das standardmäßige Profil coding tut dies nicht. Fügen Sie computer zu tools.alsoAllow hinzu; Sandbox-Agenten benötigen es außerdem in tools.sandbox.tools.alsoAllow.

Das Agent-Tool computer

Das integrierte Tool computer führt pro Aufruf eine Aktion aus. Koordinaten sind nicht negative ganzzahlige Pixel im neuesten Screenshot; der Node ordnet sie Anzeigepunkten zu. Koordinatenaktionen müssen den frameId des Screenshot-Ergebnisses unverändert zurückgeben, und ein expliziter screenIndex muss mit diesem Bild übereinstimmen. OpenClaw überträgt außerdem eine vom Node ausgegebene Anzeigeidentität aus dem Screenshot in die Aktion, sodass bei einer erneuten Verbindung der Anzeige oder einer Geometrieänderung sicher abgebrochen wird, statt denselben Index unbemerkt auf ein anderes Ziel umzuleiten. Diese Prüfungen weisen erratene Token sowie Token aus einem anderen bereitgestellten Bild oder von einer anderen Anzeige zurück. Ein Token garantiert keine Aktualität: Apps können Pixel auf derselben Anzeige nach der Erfassung ändern. Erstellen Sie daher einen neuen Screenshot, sobald sich die dargestellte Szene geändert haben könnte.

• Lesen: screenshot.
• Zeiger: left_click, right_click, middle_click, double_click, triple_click, mouse_move, left_click_drag (mit startCoordinate), left_mouse_down, left_mouse_up.
• Scrollen: scroll mit scrollDirection (up|down|left|right) und scrollAmount (Mausradschritte).
• Tastatur: type (Text), key (Tastenkombination wie cmd+shift+t oder Return), hold_key (Tastenkombination text, die duration Sekunden lang gehalten wird).
• Zeitsteuerung: wait (duration Sekunden).

Modifikatortasten werden im Feld text von Klick- und Scrollaktionen übertragen (shift, ctrl, alt, cmd). Nach einer Eingabeaktion gibt das Tool einen neuen Screenshot zurück, damit das Modell das Ergebnis beobachten kann. Wenn mehrere computerfähige Nodes verbunden sind, geben Sie node ausdrücklich an.

Screenshots bleiben ausschließlich für das Modell bestimmt: Sie werden niemals automatisch an den Chat-Kanal übermittelt. Behandeln Sie alle Bildschirminhalte als nicht vertrauenswürdige Eingaben; das Tool weist das Modell darauf hin, keine Bildschirmanweisungen zu befolgen, die der Anfrage des Benutzers widersprechen.

Windows und Linux (experimentell, über cua-driver)

Das mitgelieferte Plugin cua-computer stellt eine experimentelle Implementierung für Windows- und Linux-Node-Hosts bereit. Es ist standardmäßig deaktiviert und erfordert den Vorabversionsvertrag des Treibers 0.10.x:

1. Installieren Sie eine Binärdatei cua-driver der Version 0.10.x aus den Upstream-Releases und stellen Sie sie unter PATH bereit. Um einen anderen Speicherort der ausführbaren Datei zu verwenden, legen Sie plugins.entries.cua-computer.config.driverPath fest.

2. Aktivieren Sie das Plugin:

   openclaw plugins enable cua-computer

3. Starten Sie openclaw node run aus der interaktiven Desktop-Sitzung. Das Plugin startet den lokalen Treiber-Daemon verzögert, sobald die erste Erfassung oder Aktion eingeht.

Diese Implementierung steuert derzeit nur die primäre Anzeige. X11/XWayland ist der bevorzugte Linux-Pfad. Natives Wayland bleibt eine Upstream-Opt-in-Funktion: Legen Sie CUA_DRIVER_RS_ENABLE_WAYLAND selbst fest, bevor Sie den Node starten; OpenClaw legt es niemals automatisch fest. KDE/KWin wird vom nativen Wayland-Eingabepfad des Upstreams nicht unterstützt. hold_key, left_mouse_down und left_mouse_up sind nicht verfügbar, da cua-driver 0.10.x keinen plattformübergreifenden Haltevertrag für den gesamten Desktop besitzt. Scrollen und Ziehen mit gedrückter Modifikatortaste sind auf beiden Plattformen nicht verfügbar; Klicks mit gedrückter Modifikatortaste sind unter Linux ebenfalls nicht verfügbar. Die Aktion key akzeptiert benannte Tasten, Buchstaben und Modifikatorkombinationen (zum Beispiel cmd+c oder Return); Ziffern- und Satzzeichentasten werden zurückgewiesen, da der Treiber ihren layoutabhängigen Umschaltzustand verwirft. Senden Sie diesen Text daher stattdessen über die Aktion type. Die Texteingabe kann während eines Treiberaufrufs type_text nicht vorzeitig abgebrochen werden.

Da cua-driver keine stabile Anzeigeidentität meldet, wird die Bildautorisierung an die Treiberverbindung sowie die aktuelle Geometrie der primären Anzeige gebunden. Eine erneute Verbindung des Daemons oder der Sitzung macht ausstehende Bilder ungültig. Der Austausch der primären Anzeige gegen eine Anzeige mit gleicher Geometrie kann jedoch nicht erkannt werden, solange die Verbindung bestehen bleibt; verwenden Sie für diese Implementierung vorzugsweise eine stabile Sitzung mit nur einer Anzeige.

OpenClaw deaktiviert Telemetrie und Updateprüfungen von cua-driver für die verwalteten Prozesse mcp und serve. Die Binärdatei des Treibers wird weder heruntergeladen noch aktualisiert.

Fehlerbehebung

Die Implementierung cua-computer stellt typisierte Fehlercodes im Tool-Ergebnis und in den Node-Protokollen bereit. Häufige Codes:

Der Node-Befehl computer.act

computer.act ist der einzige Node-Befehl, über den das Tool Eingaben weiterleitet (node.invoke mit command: "computer.act"). Er ist:

• Standardmäßig gefährlich: Er ist in den integrierten gefährlichen Node-Befehlen aufgeführt und von der Laufzeit-Zulassungsliste ausgeschlossen, bis er ausdrücklich aktiviert wird. macOS-, Windows- und Linux-Desktop-Nodes können ihn dennoch bei der Kopplung deklarieren, sodass die Oberfläche einmalig genehmigt wird.
• Fähigkeitsbasiert: Das Tool erfordert einen verbundenen Node, der sowohl computer.act als auch screen.snapshot ankündigt. Die mitgelieferte macOS-App und das optional aktivierbare experimentelle Plugin cua-computer führen dasselbe Befehlspaar aus.

Lesevorgänge verwenden screen.snapshot erneut; es gibt keinen zweiten Erfassungspfad. Informationen zum gemeinsam verwendeten Erfassungsbefehl finden Sie unter Kamera- und Bildschirm-Nodes.

Aktivieren und freischalten

1. Aktivieren Sie den Plattform-Fulfiller: Aktivieren Sie unter macOS Settings → Allow Computer Control und gewähren Sie anschließend unter Settings → Permissions die Berechtigungen Accessibility und Screen Recording; befolgen Sie unter Windows/Linux die oben beschriebene experimentelle Einrichtung für cua-computer.

2. Genehmigen Sie die Pairing-Aktualisierung am Gateway (ein neuer Befehl erzwingt ein erneutes Pairing).

3. Stellen Sie das Tool dem visionsfähigen Agenten zur Verfügung. Für das standardmäßige coding-Profil:

   {  tools: {    alsoAllow: ["computer"],    // Agenten in einer Sandbox benötigen auch dieses zweite Gate:    sandbox: { tools: { alsoAllow: ["computer"] } },  },}

4. Aktivieren Sie computer.act für ein begrenztes Zeitfenster. Das phone-control-Plugin stellt eine computer-Gruppe bereit:

   /phone arm computer 30m/phone status/phone disarm

   Die Aktivierung erfordert operator.admin (oder den Eigentümer) und läuft automatisch ab. Die ältere /phone arm all-Gruppe schließt die Desktop-Steuerung absichtlich aus; verwenden Sie die explizite computer-Gruppe. Die Aktivierung legt lediglich fest, was das Gateway aufrufen darf; die Node-App erzwingt weiterhin ihre plattformspezifischen Einstellungen und Betriebssystemberechtigungen, einschließlich Allow Computer Control, Accessibility und Screen Recording unter macOS.

Fügen Sie für eine dauerhafte Autorisierung computer.act zu gateway.nodes.commands.allow hinzu und entfernen Sie es aus gateway.nodes.commands.deny; die Sperrliste hat Vorrang. Eine dauerhafte Autorisierung läuft nicht automatisch ab. Einträge, die bereits vor /phone arm vorhanden waren, bleiben nach /phone disarm bestehen; wandeln Sie eine temporäre Gewährung nicht in eine dauerhafte um, solange sie aktiviert ist.

Die Autorisierung ist bewusst in Aktivierung und Nutzung aufgeteilt. Das Aktivieren oder dauerhafte Konfigurieren von computer.act erfordert administrative Berechtigungen. Nach der Aktivierung kann ein authentifizierter Operator mit operator.write computer.act über node.invoke aufrufen, bis die Gewährung abläuft oder deaktiviert wird; es gibt keine administrative Prüfung für jede einzelne Aktion. Die Genehmigung einer Node, die computer.act deklariert, erfasst lediglich die Oberfläche, damit sie später aktiviert werden kann, und ermöglicht für sich allein keinen Aufruf.

Sicherheit

• Vor der Autorisierung müssen alle Ebenen (Tool-Richtlinie, Gateway-Befehlsrichtlinie, Einstellung der Node-App und Plattformberechtigungen) übereinstimmen. Beim aktuellen macOS-Fulfiller umfasst dies Allow Computer Control, Accessibility und Screen Recording. Nach der Aktivierung werden Aktionen bis zum Ablauf oder bis /phone disarm ohne Bestätigung für jede einzelne Aktion ausgeführt.
• Der macOS-Fulfiller gibt Text Graphem für Graphem ein, sodass ein Abbruch, eine Trennung, eine Pause, eine Deaktivierung oder ein Austausch des Endpunkts die Eingabe vor dem nächsten Graphem stoppt. Der experimentelle cua-driver-Fulfiller kann einen type_text-Aufruf nicht während der Eingabe abbrechen.
• Screenshots sind ausschließlich für das Modell bestimmt und werden niemals automatisch an den Chat gesendet (Issue #44759).
• Behandeln Sie Bildschirminhalte als nicht vertrauenswürdig; sie können Prompt-Injection enthalten.

Beziehung zu anderen Pfaden für die Desktop-Steuerung

Dies ist der vom Agenten gesteuerte Pfad. Unter Peekaboo-Bridge erfahren Sie, wie er mit dem PeekabooBridge-Host, Codex Computer Use und dem direkten cua-driver-MCP zusammenhängt.