Gemini 4 Computer Use einrichten: Browser, Desktop und Android

Gemini 4 Computer Use schlägt Bildschirmaktionen vor. Deine Anwendung muss sie ausführen und eine neue Beobachtung zurückgeben. Beginne mit Googles Interactions API, einem unterstützten Modell wie gemini-4-hydrogen und einem computer_use-Tool, dessen environment zum Executor passt. environment: "desktop" gibt dem Modell weder automatisch Kontrolle über deinen Computer noch installiert es einen Betriebssystemtreiber.

Diese Anleitung führt durch ein kleines Browser-Beispiel, erklärt die Unterschiede bei Desktop und Android und liefert einen vollständigen Controller mit ausdrücklichen Freigaben und Abbruchbedingungen zum Download. Dokumentation und Pakete wurden am 13. November 2026 geprüft. Googles aktuelle Computer-Use-Dokumentation nennt Carbon, Argon und Hydrogen als unterstützte Modelle. Das Beispiel verwendet Hydrogen; die Auswahl behandelt unser Vergleich der Gemini-4-Modelle. Verlinkte Herstellerdokumentation ist auf Englisch.

Ofox veröffentlicht diesen Artikel. Unsere Nachweise bestehen aus 22 Offline-Tests mit synthetischen Modellantworten sowie einer echten Prüfung der lokalen Testseite in Chrome, bedient über ein separates UI-Werkzeug. Der mitgelieferte Python-Playwright-Runner wurde nicht mit einem Modell ausgeführt und nicht durchgängig validiert. Wir haben weder kostenpflichtige Inferenz noch Desktop- oder Android-Executors getestet und keine Modellleistung gemessen. Diese Trennung zeigt, was du übernehmen kannst und was du in deiner Umgebung noch prüfen musst.

Zuerst das API-Format wählen, dann die Ausführungsumgebung

Ein Computer-Use-Agent hat drei Aufgaben: Das Modell schlägt Aktionen vor, ein Executor führt unterstützte Aktionen aus, und eine Prüflogik kontrolliert das Anwendungsergebnis. Die letzten beiden Komponenten stellst du bereit. Eine abschließende Modellnachricht wie „fertig“ beweist nicht, dass ein Formular abgeschickt, eine Datei gespeichert oder ein Button angeklickt wurde.

Verwende im gesamten Ablauf dasselbe API-Format. Diese Anleitung nutzt Interactions mit steps, function_call, function_result und previous_interaction_id. Das geprüfte offizielle Referenz-Repository, Commit 77c9797e943aad63bbc963b7fd092a9e51c07863, verwendet GenerateContent. Sein Code unterscheidet außerdem aktuelle Aktionen von älteren Preview-Aktionen. Er ist als Referenz nützlich, aber sein Antwortparser lässt sich nicht unverändert in eine Interactions-Schleife kopieren.

Projekt und Google-Schlüssel richtest du nach der Hydrogen-API-Anleitung ein. Dieses Beispiel erwartet den Google-Schlüssel in GEMINI_API_KEY. Ein Ofox-Schlüssel gehört zum separat dokumentierten Ofox-Authentifizierungsverfahren.

Ofox dokumentiert Chat Completions und eine native Gemini-API-Route. Allgemeine Protokollunterstützung bestätigt jedoch nicht automatisch Googles aktuellen Interactions-Computer-Use-Vertrag. Daher nutzt diese Anleitung die native Google-Route und behauptet nicht, ein Austausch der Base URL gegen Ofox mache die Browser-Schleife funktionsfähig. Für reine Dateitools in einem Repository beschreibt die Hydrogen-Anleitung für Cline und OpenCode eine andere Integration.

Das lokale Paket installieren und ohne Modellschlüssel testen

Lade das vollständige Computer-Use-Testpaket herunter, entpacke es und wechsle in das Verzeichnis gemini-computer-use-kit. Es enthält Controller, Offline-Tests, eine lokale HTML-Testseite, einen optionalen Live-Runner und eine README. Fehlende Teile eines Codeausschnitts musst du nicht selbst ergänzen. Kommentare und README sind auf Englisch; die vollständigen Arbeitsschritte folgen hier.

Für die geprüfte Paketversion brauchst du Python 3.11 oder neuer:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'google-genai==3.3.0'
python test_controller.py

Unter Windows aktivierst du die Umgebung in PowerShell mit .venv\Scripts\Activate.ps1 statt mit source. Die Offline-Prüfungen benötigen weder Playwright noch einen API-Schlüssel. Erwartet werden 22 bestandene Tests. Wir haben sie auch aus einer frisch entpackten Version des Download-Archivs ausgeführt, nicht nur im Arbeitsverzeichnis.

Die Tests verwenden echte google-genai-Antwortklassen mit synthetischen Daten und eine simulierte Seite, die Aktionen protokolliert. Geprüft werden Koordinaten, zugeordnete Aufruf-IDs, Ablehnung vor Seiteneffekten, Zustimmung und Ablehnung, doppelte Aufrufe, unvollständige Antworten, Timeouts und Aktionsgrenzen. Dabei startet kein Browser. Die Tests belegen nicht, dass Google einen bestimmten echten Request akzeptiert.

Für die separate Browser-Integration installierst du Playwright und dessen Browser:

python -m pip install playwright
python -m playwright install chromium

Öffne im Paketverzeichnis ein zweites Terminal und stelle die Testseite lokal bereit:

python -m http.server 8877 --bind 127.0.0.1

Rufe http://127.0.0.1:8877/fixture.html auf. Du solltest eine englische Seite sehen, die ORANGE-42 verlangt, ein leeres Marker-Feld und den Button Check marker. Gib den Marker ein und klicke auf den Button, um die Seite selbst zu prüfen. Lade sie anschließend neu, damit der Agent mit einem leeren Feld und nicht mit einer bereits erledigten Aufgabe beginnt.

Echter Chrome-Screenshot der lokalen Seite bei 1000 × 700 Pixeln, bedient über ein separates UI-Werkzeug. Er belegt das sichtbare Seitenverhalten, nicht die erfolgreiche Ausführung durch Hydrogen oder den Python-Runner. Für diesen Screenshot war kein Modell verbunden.

Die optionale Google-Browser-Integration ausführen

Lass den lokalen HTTP-Server laufen. Setze in der aktivierten Python-Umgebung deinen Google-Schlüssel als GEMINI_API_KEY über deine übliche Geheimnisverwaltung. Schreibe ihn weder in die Testseite noch in die Versionsverwaltung. Der nächste Befehl ruft den echten Dienst auf und kann Projektkontingent oder kostenpflichtige Nutzung verbrauchen. Anders als die Offline-Tests ist das keine Prüfung ohne Modell.

python run_live.py

Der Runner erzeugt einen neuen Browserkontext mit 1000 × 700 CSS-Pixeln, Geräteskalierungsfaktor 1, blockierten Service Workern und deaktivierten Downloads. Sein Request-Filter lässt nur die exakte URL der Testseite zu. Das hält das Beispiel überschaubar; es ist weder eine Betriebssystem-Sandbox noch eine allgemeine Absicherung für beliebige Websites.

Der vollständige Aufgaben-Prompt im Runner lautet:

Read the local page instructions. Enter the marker in its field and click Check marker. Stop when the page shows PASS. Stay on this page.

Er fordert dazu auf, die Seitenanweisung zu lesen, den Marker einzugeben, Check marker anzuklicken und bei PASS auf derselben Seite anzuhalten. Der erste Request enthält diesen Prompt, den ersten Screenshot und das Computer-Use-Tool. Die wesentlichen Einstellungen sind:

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[
        {"type": "text", "text": task_prompt},
        {"type": "image", "data": screenshot_base64, "mime_type": "image/png"}
    ],
    tools=[{
        "type": "computer_use",
        "environment": "browser",
        "enable_prompt_injection_detection": True
    }],
    timeout=120.0,
    automatic_continuation=False
)

Dieser Ausschnitt erklärt das Request-Format; nutze zum Ausführen das vollständige Paket. Es schließt zusätzlich vordefinierte Aktionen aus, die es nicht implementiert, und lehnt sie auch im Executor ab. Für diese eine Seite unterstützt es click, type, wait und take_screenshot. Eine nicht unterstützte Aktion wird nicht stillschweigend als erfolgreich gemeldet.

Bei einer Freigabeanforderung zeigt das Terminal Absicht und Erklärung. Gib nur dann APPROVE ein, wenn du die angezeigte Aktion erlaubst; jede andere Antwort stoppt den Lauf. Die anwendungsseitige Erfolgsbedingung ist exakt PASS: ORANGE-42 im Ergebniselement. Danach wird result.png gespeichert. Stoppt das Modell, während die Seite noch „Waiting for input“ zeigt, schlägt diese Abnahme fehl.

Da wir diesen Live-Runner nicht ausgeführt haben, ist ein erfolgreicher Lauf in deinem Konto ein neuer Nachweis. Halte Client-Version, Modell-ID, tatsächliches Ergebnis und Nutzung fest. Verwende weder die Offline-Testdauer als Modellgeschwindigkeit noch simulierte Antworten als Abrechnungsdaten.

Koordinaten, Screenshots und Aufruf-IDs aufeinander abstimmen

Googles aktuelle Aktionen nutzen normalisierte ganzzahlige Koordinaten von 0 bis 999, skaliert auf eine Achse mit 1000 Einheiten. Rechne anhand der Abmessungen der Beobachtung um, die dein Executor tatsächlich verwendet:

def to_pixel(value, size):
    if type(value) is not int or not 0 <= value <= 999:
        raise ValueError("Expected an integer coordinate from 0 to 999")
    return int(value * size / 1000)

Bei einem Screenshot mit 1000 × 700 Pixeln wird eine synthetische Aktion an (400, 500) zu (400, 350) CSS-Pixeln. Das ist ein Rechenbeispiel und keine aufgezeichnete Hydrogen-Vorhersage. Das Paket prüft Koordinaten vor der Ausführung und erstellt Screenshots mit scale="css", damit die Browserkoordinaten übereinstimmen.

Kombiniere keinen Screenshot des gesamten Desktops mit Browser-Viewport-Koordinaten und vergiss nach einem Bildzuschnitt nicht dessen Versatz. Bei hoher Pixeldichte können Bildpixel und Eingabekoordinaten unterschiedlich sein. Die Drehung eines Mobilgeräts erzeugt eine weitere Transformation. Ein erfolgreicher API-Request kann nicht ausgleichen, dass der Executor im falschen Koordinatensystem klickt.

Gib nach jedem ausgeführten Aufruf seine eigene ID, die aktuelle URL und einen frischen Screenshot zurück. Das Ergebnis des Pakets hat diese Struktur:

{
  "type": "function_result",
  "name": "click",
  "call_id": "the-id-from-the-model-function-call",
  "result": [
    {"type": "text", "text": "{\"url\":\"http://127.0.0.1:8877/fixture.html\"}"},
    {"type": "image", "data": "BASE64_OF_NEW_SCREENSHOT", "mime_type": "image/png"}
  ]
}

Die Platzhalter dienen zur Erklärung und dürfen nicht unverändert gesendet werden. Enthält eine Antwort mehrere Aufrufe, braucht jeder ausgeführte Aufruf ein passendes Ergebnis. Der nächste Request verwendet als previous_interaction_id die Interaction mit diesen Aufrufen. Diese ID ist nicht mit einer Funktionsaufruf-ID austauschbar.

Das Beispiel baut auf gespeichertem Interaction-Zustand auf. Füge store=False erst hinzu, nachdem du die Historienverwaltung anhand der Interactions-Dokumentation neu gestaltet hast. Bei einem anderen Protokoll oder eigener Historienverwaltung musst du erforderlichen Modellzustand und Signaturen unverändert erhalten. Der Leitfaden zu fehlenden Gemini-Thought-Signatures (Englisch) erklärt ein Fehlermuster, belegt aber keinen erfolgreichen Live-Signaturtest dieses Beispiels.

Den Executor für Desktop oder Android anpassen

Die Umgebung teilt dem Modell mit, welchen Aktionsumfang es verwenden soll. Sie stellt keinen Browser, keine VM, keine Desktop-Sitzung und kein Telefon bereit. Googles Umgebungsreferenz unterscheidet diese Ziele:

Das Download-Paket implementiert nur die Browser-Testseite. Für einen Desktop-Adapter behältst du die Request-/Result-Schleife, ersetzt aber die Browseroperationen auf page:

1. Wähle einen separaten Testdesktop oder eine VM mit einem Bildschirm. Halte die Größe beim ersten Lauf fest und vermeide eine persönliche Sitzung mit fremden Fenstern.
2. Prüfe die Bildschirmaufnahme unabhängig und notiere Breite und Höhe. Teste vor dem Modellanschluss auch eine harmlose Eingabe separat in einer lokalen Test-App.
3. Übertrage normalisierte Koordinaten in das Eingabekoordinatensystem. Liefert die Capture-Bibliothek Gerätepixel, während die Eingabebibliothek logische Koordinaten erwartet, skaliere die Beobachtung oder nutze durchgehend eine dokumentierte Transformation.
4. Binde jede unterstützte Desktop-Aktion an einen ausdrücklichen Handler: Zeigerklick, Texteinfügung, Tastendruck, Scrollen und neue Aufnahme. Schließe nicht implementierte Aktionen aus oder lehne sie ab. Browsernavigation ist keine allgemeine Desktop-Aktion.
5. Ändere die Tool-Umgebung auf desktop, behalte die Zuordnung von Aufruf-ID und Ergebnis bei und prüfe nach der ersten Aktion den Anwendungszustand. Eine Cursorbewegung allein reicht nicht als Erfolgsnachweis.

Unter macOS sind Bildschirmaufnahme und Bedienungshilfen-Zugriff getrennte Berechtigungen. Ein Screenshot beweist nicht, dass der Prozess klicken oder tippen darf. Gewähre nur den Zugriff, den der bewusst installierte Executor benötigt. Diese Einstellungen brauchen keinen anderen Gemini-API-Schlüssel. Windows und Linux benötigen eigene Aufnahme-/Eingabe-Backends und Sitzungsprüfungen; das Browserpaket liefert diese Treiber nicht.

Für ein Android-Gerät oder einen Emulator bereitest du zuerst Verbindung und Aufnahmeweg nach der offiziellen Android-Debug-Bridge-Anleitung vor. Mit einem autorisierten Testgerät identifizieren diese Befehle das Gerät und holen einen Screenshot, ohne Gemini aufzurufen:

adb devices
adb -s YOUR_TEST_SERIAL shell screencap /sdcard/computer-use-test.png
adb -s YOUR_TEST_SERIAL pull /sdcard/computer-use-test.png ./computer-use-test.png

Ersetze die Seriennummer durch die des vorgesehenen Testgeräts, nicht durch einen beliebigen Eintrag einer Liste mehrerer Geräte. Ein unauthorized-Gerät muss zuerst auf dem Gerät freigegeben werden. Öffne die PNG-Datei, kontrolliere die richtige Test-App und fixiere für den ersten Lauf die Ausrichtung.

Implementiere anschließend die Geräteaktionen: click wird nach der Koordinatenumrechnung zum Tippen, type fügt Text ins fokussierte Feld ein, go_back führt „Zurück“ aus, und open_app/list_apps müssen reale Paketkennungen auflösen. Implementiere Ziehen und langes Drücken ausdrücklich, wenn du diese Aktionen aktivierst. Gib nach der Ausführung einen neuen Gerätescreenshot zurück, setze environment auf mobile und teste eine kleine Aufgabe in der Test-App. Googles dokumentierte mobile Aktionen sind für Android optimiert; daraus folgt nicht, dass dieser ADB-Ablauf ein iPhone steuert.

Die beschriebenen Desktop- und Android-Schritte wurden für diesen Artikel nicht an einem Gerät getestet. Sie zeigen die erforderlichen Integrationsarbeiten und Abnahmepunkte, statt einen fertigen Port durch das Ändern einer Zeichenfolge zu versprechen.

Freigabe, Abbruch und Wiederaufnahme ausdrücklich behandeln

Das intent des Modells erklärt eine vorgeschlagene Aktion, ist aber keine Erlaubnis. Enthält ein Funktionsaufruf safety_decision.decision: "require_confirmation", warte auf den Nutzer. Googles Dokumentation zu Sicherheitsentscheidungen sieht eine Bestätigung nach der Zustimmung vor. Das Paket ergänzt safety_acknowledgement: true erst nach Zustimmung im Text des Aktionsergebnisses.

Der Controller prüft den gesamten Stapel und holt erforderliche Freigaben ein, bevor er eine Aktion daraus ausführt. Bei nicht unterstützten Aktionen, fehlerhaften Sicherheitsmetadaten und anderen ausdrücklichen Entscheidungszuständen stoppt er. Für die Testseite ist das bewusst konservativ. Eine fehlende Sicherheitsentscheidung ersetzt nicht die eigenen Regeln deiner Anwendung zur Autorisierung einer Aufgabe.

Standardmäßig gelten 12 Aktionsstapel und 120 Sekunden pro Modellrequest, bei deaktivierter automatischer Fortsetzung. Das ist weder ein globales Zeitlimit noch ein Dollarbudget: Eine Freigabe kann warten, ein Stapel mehrere Aktionen enthalten, und Screenshots plus wiederholter Kontext beeinflussen die Nutzung. Auch Transportwiederholungen im SDK sind möglich. Wir versprechen weder null Wiederholungen noch feste Kosten.

Läuft der Request nach einem Klick in einen Timeout, kann der Klick bereits erfolgt sein. Die Anwendung wiederholt ihn nicht automatisch. Stoppe, kontrolliere die echte Seite, bewahre Interaction- und Aufruf-IDs auf und entscheide, ob du das protokollierte Gespräch fortsetzt oder eine neue Aufgabe beginnst. Starte eine Formularübermittlung mit unklarem Ergebnis nicht blind erneut. Bei dieser lokalen Seite kannst du Feld und Ausgabe prüfen und vor einem sauberen Test durch Neuladen zurücksetzen.

Ein Screenshot- oder Browserfehler nach der Aktion macht diese nicht rückgängig. Definiere für produktive Abläufe eine passende unabhängige Ergebnisprüfung, etwa eine gespeicherte Datensatz-ID oder einen geänderten Dokumentwert. Der sichtbare Marker reicht nur für diese einfache Seite und ist keine allgemeine Transaktionsprüfung. Das frühere Offline-Labor für Computer-Use-Controller (Englisch) untersucht einen anderen, OpenAI-orientierten Controller und die Prüfung auf Empfängerseite.

Fehler auf der verursachenden Ebene diagnostizieren

Authentifizierung, Kontingente und fehlerhafte Requests behandelt auch der Gemini-API-Fehlerleitfaden. Er entstand für Argon; übertrage allgemeine Fehlerklassen auf die tatsächliche Hydrogen-Antwort, statt alle modellspezifischen Details gleichzusetzen. Für eine separate Ofox-Route verwendest du die dort dokumentierte Ofox-Fehlerbehandlung. Sie ersetzt keine Google-Projektdiagnose.

Zwischen API-Schleife und fertigem Agenten entscheiden

Diese API-Lösung passt, wenn du Executor, Freigaben, Beobachtungen und Anwendungsprüfung selbst kontrollieren musst. Geht es dir um ein sofort nutzbares Desktopprodukt, beschreibt die Antigravity-Plattformübersicht (Englisch) einen anderen Einstieg. Auch der Vergleich von Chrome-Erweiterung, Computer Use und Fernsteuerung trennt diese Produktkategorien.

Bevor du die Testseite verlässt, dokumentiere Modell- und SDK-Version, API, Umgebung, Bildmaße, implementierte Aktionen, Freigabepolitik und unabhängige Erfolgsbedingung. Trenne im Prüfprotokoll Offline-Controller-Tests, Browserbedienung und echte Modellinferenz. Bei diesem Paket gibt es nur für die ersten beiden Nachweise; der Browsertest lief separat vom Python-Runner.

Der nächste Meilenstein ist eine echte Aufgabe, bei der vorgesehenes Konto, Executor und Prüflogik gemeinsam funktionieren. Erweitere Aktionen oder wechsle zu Desktop/Mobilgerät erst, wenn das Ergebnis sichtbar und wiederholbar ist. Mehr Modellfähigkeit beseitigt nicht die Notwendigkeit festzustellen, welche Aktion tatsächlich lief und was sie veränderte.