Autorhinweis: Dieser Artikel behandelt die Installation und Autorisierung von agent-desktop, den geschlossenen Kreislauf aus snapshot/click und die MCP-Anbindung. Außerdem erklärt er, wie man das Modell und die Base-URL für das „Gehirn in der Schleife“ konfiguriert.
Ein Coding-Agent oder ein selbstgebauter Agent sollte Finder anklicken, Systemeinstellungen ausfüllen und eine native App bedienen – bisher ging das im Wesentlichen nur über Screenshots, visuelle Modelle und Pixelkoordinaten. Die Kette war lang, und danebengetippt wurde schnell. Das von Vercel Labs Open-Source-Projekt agent-desktop geht einen anderen Weg: Es liest den Barrierefreiheitsbaum (Accessibility Tree) des Betriebssystems und verwandelt die Desktop-Oberfläche in JSON mit refs. Der Agent führt Klicks und Eingaben anhand der refs aus. Genau das meint es mit „Computer-Use ohne Screenshots“.
Das ist nicht noch ein Desktop-Roboter mit eingebauter KI. Drei Dinge sollten vorab klar sein:
- agent-desktop enthält kein Modell: In der Binärdatei ist kein LLM eingebettet, es gibt keine GUI und keine interaktiven Eingabeaufforderungen. Jeder Befehl gibt ein JSON-Envelope aus und beendet sich dann.
- Die Schleife liegt beim Aufrufer: Die Schleife aus Beobachten, Handeln und Prüfen (observe-act-verify) verantwortet der aufrufende Agent, etwa Claude Code, OpenCode oder dein eigenes Skript.
- Keine Web-Oberflächen: Web-Automatisierung übernimmt das Schwesterprojekt agent-browser; agent-desktop kümmert sich ausschließlich um native Desktop-Apps.
Da das Tool selbst kein Modell enthält, muss das „Gehirn“ vom aufrufenden Agenten bereitgestellt werden. Dafür braucht es einen API-Schlüssel und ein Token. Du kannst die Base-URL des aufrufenden Agenten auf APIYI apiyi.com zeigen lassen und mit einem Schlüssel Modelle wie claude-opus-5-5 und claude-sonnet-5-5 aufrufen.
Kernnutzen: Nach dem Lesen dieses Artikels kannst du agent-desktop installieren, autorisieren und den minimalen Ablauf snapshot → click → erneutes snapshot zum Laufen bringen. Danach bindest du es über MCP in deinen Agenten ein und richtest auf der Modellseite die Base-URL und die Modellnamen ein.
Kernpunkte von agent-desktop
Die folgende Tabelle gibt einen Überblick über die Positionierung von agent-desktop. Die Informationen stammen aus dem offiziellen README, den FAQ und der Dokumentationsseite; Stand der Beobachtung: 13.11.2026.
| Punkt | Erläuterung | Nutzen für Entwickler |
|---|---|---|
| Datenquelle | Liest den Accessibility-Baum des Betriebssystems: unter macOS über die AX API, unter Windows über UI Automation, unter Linux über AT-SPI | Keine Abhängigkeit von Screenshots oder Pixel-Matching, hoher Strukturierungsgrad |
| Ausgabeformat | Jeder Befehl gibt ein JSON-Envelope aus und beendet sich danach; Elemente enthalten eine ref | Leicht von LLMs zu parsen und für Assertions in Skripten geeignet |
| Standardmodus | headless, nutzt die Accessibility-API, bewegt den Mauszeiger nicht und übernimmt nicht den Fokus | Lässt sich im Hintergrund ausführen, ohne den Nutzer zu unterbrechen |
| Modell enthalten? | Nein, die Schleife verantwortet der Aufrufer | Modell frei wählbar; Kosten und Wirkung steuert der Aufrufer |
| Integrationswege | CLI, MCP (stdio), Skills, C-Bibliothek via FFI | Lässt sich in Claude Code, OpenCode und eigene Agenten integrieren |
Stand 13.11.2026 hat das GitHub-Repository vercel-labs/agent-desktop rund 22.900 Stars, steht unter der Apache-2.0-Lizenz und der npm-Paketname lautet agent-desktop; an diesem Tag kamen noch neue Commits hinzu. Insgesamt gibt es etwa 61 Befehlsnamen, 57 davon sind ausführbar. Sie sind in Gruppen wie Observe, Act on ref, Keyboard mouse, Apps windows, Notifications, Clipboard, Wait, Sessions, Sandboxes und System unterteilt.
Wie agent-desktop funktioniert: Accessibility-Baum und ref
Das Kernkonzept von agent-desktop sind snapshot und ref. Wenn snapshot ausgeführt wird, durchläuft es den Accessibility-Baum der Zielanwendung und gibt Elemente wie Schaltflächen, Textfelder und Menüeinträge als JSON aus, wobei jedes Element eine ref erhält. Eine vollständige ref sieht in etwa so aus wie @s8f3k2p9:e8: Die erste Hälfte ist die Kennung dieses snapshots, die zweite Hälfte die Elementnummer.
Eine ref gehört ausschließlich zu dem snapshot, der sie erzeugt hat. Wird nur eine nackte @e8 übergeben, erhält man INVALID_ARGS. Nach einer Änderung der Oberfläche kann die alte ref ungültig werden und STALE_REF oder AMBIGUOUS_TARGET zurückgeben – dann ist ein erneuter snapshot nötig. Dieses Design zwingt den Aufrufer, nach jeder Aktion erneut zu beobachten, also den „Verifizieren“-Schritt in observe-act-verify.
Der Schritt „Agent wählt ref“ in der obigen Abbildung ist der Punkt, an dem das Modell Entscheidungen trifft. agent-desktop ist dafür zuständig, die Oberfläche strukturiert herauszugeben; das JSON zu verstehen und zu entscheiden, welches Element angeklickt wird, ist Aufgabe des aufrufenden Modells.
Wie sich agent-desktop und agent-browser die Aufgaben teilen
Beide Projekte gehören zu Vercel Labs, und auch der Dokumentationsbereich ist gemeinsam – trotzdem sind die Zuständigkeiten klar abgegrenzt:
| Vergleichspunkt | agent-desktop | agent-browser |
|---|---|---|
| Ziel | Native Desktop-Apps (Finder, Systemeinstellungen, native Clients) | Webseiten und Browser-Seiten |
| Beobachtungsmethode | Barrierefreiheitsbaum des Betriebssystems | Seitenstruktur auf der Browserseite |
| Chromium-/Electron-Apps | Kann über den DevTools-Port an agent-browser übergeben werden | Eignet sich, um die Web-Inhalte solcher Apps zu übernehmen |
| Enthält ein Modell | Nein | Wird ebenso als Werkzeug für den Agent bereitgestellt |
| Typische Befehle | snapshot, click, clipboard-set |
Seitenorientierte Navigation und Interaktion |
Eine recht praktische Aufteilung sieht so aus: native Fenster, Menüleiste, Dock und Benachrichtigungen übernimmt agent-desktop; sobald man auf Webseiten oder auf Web-Inhalte in Electron-Apps stößt, wechselt man über den DevTools-Port zu agent-browser.
Versionsmeilensteine von agent-desktop und die Quellenlage
agent-desktop wird sehr schnell weiterentwickelt, und mehrere Schlüsselversionen brachten Verhaltensänderungen mit sich – einige davon sind Breaking Changes. Die folgende Tabelle ist nach Quelle gekennzeichnet; „Unbekannt“ bedeutet, dass die offiziellen Unterlagen dazu noch nichts Genaues sagen.
| Version / Datum | Wichtigste Änderungen | Quelle |
|---|---|---|
| 1.0.0 (2026-10-27) | Linux-Unterstützung erreicht offiziell 1.0 | Offizielles Changelog |
| 1.1.0 (2026-11-02) | envelope auf 2.6 angehoben; Unterstützung für macOS Dock und menu-bar-extras; Breaking Changes bei Identitätsnachweisen | Offizielles Changelog |
| 1.2.0 (2026-11-05) | Neu: MCP (agent-desktop mcp); type / set-value / clipboard-set unterstützen --stdin |
Offizielles Changelog |
| 1.3.0 (2026-11-11) | Neu: agent-desktop sandbox und macOS-Sandbox-Provider; menu/menubar snapshot enthält kein data.window mehr (Breaking) |
Offizielles Changelog |
| Windows-/Linux-Sandbox | Ob ein entsprechender Provider bereitgestellt wird | Unbekannt |
agent-desktop – Schnellstart
Im Folgenden gehen wir die Reihenfolge „Installation → Autorisierung → minimaler Durchlauf → MCP-Anbindung“ durch.
Schritt 1: agent-desktop installieren
Plattformanforderungen: macOS 13+; Windows 10 1809+ (x64 / ARM64); Linux als Ubuntu 24.04+ (x86_64 / aarch64), X11 oder Wayland werden beide unterstützt. Wählen Sie eine der Installationsmethoden:
- npm (Node 18+ erforderlich, das Paket enthält native Binärdateien für jede Plattform):
npm install -g agent-desktop - Homebrew (macOS / Linux, bereits in homebrew-core enthalten):
brew install agent-desktop - Native Archive: von GitHub Releases herunterladen; der Helper muss neben der ausführbaren Datei liegen
Nach der Installation führen Sie zunächst agent-desktop status aus, um zu prüfen, ob die Binärdatei und die aktuelle Plattformumgebung in Ordnung sind.
Schritt 2: Berechtigungen für agent-desktop erteilen
Unter macOS müssen Sie dem Terminal oder dem Host-Prozess die Berechtigung für „Bedienungshilfen“ erteilen. Sonst lässt sich der Accessibility-Baum nicht lesen. Offiziell stehen dafür folgende Befehle zur Verfügung:
agent-desktop permissions --guide: Folgen Sie den Anweisungen in den Systemeinstellungen, um die Berechtigung für Bedienungshilfen zu erteilen- Führen Sie nach der Freigabe erneut
agent-desktop statusaus, um die Berechtigung zu überprüfen
Wichtig: Die Berechtigung gilt für den Prozess, der agent-desktop ausführt. Wenn Sie es indirekt über Claude Code, eine IDE oder einen MCP-Client aufrufen, müssen Sie möglicherweise die jeweilige Host-Anwendung berechtigen.
Schritt 3: Den minimalen Zyklus snapshot → click → snapshot durchspielen
Am Beispiel von Finder reichen drei Befehle aus, um einen vollständigen Zyklus aus Beobachten, Handeln und Prüfen zu bilden:
agent-desktop snapshot --app Finder -i: Ruft den Accessibility-Baum von Finder ab.-ifokussiert interaktive Elemente; die JSON-Ausgabe enthält Refs wie@s8f3k2p9:e8agent-desktop click @s8f3k2p9:e8: Klickt auf das Zielelement aus dem vorherigen Snapshot. Die vollständige Ref muss angegeben werdenagent-desktop snapshot --app Finder -i: Beobachtet die Oberfläche erneut und prüft, ob sie sich wie erwartet verändert hat
Wenn Schritt 2 STALE_REF oder AMBIGUOUS_TARGET meldet, hat sich die Oberfläche geändert. Dann kehren Sie einfach zu Schritt 1 zurück und erstellen einen neuen Snapshot. Bei Apps, die echte Zeiger- oder Tastaturereignisse benötigen, können Sie das globale Flag --headed setzen und in den Modus für physische Eingaben wechseln.
Bei Oberflächen mit vielen Elementen wird ein vollständiger Snapshot auf einmal sehr lang und verschwendet Modell-Token. Sie können ihn in zwei Stufen abrufen:
agent-desktop snapshot --skeleton --app Finder: Zuerst einen Skelett-Snapshot erstellen, um die ungefähren Bereiche zu erkennenagent-desktop snapshot --app Finder --root @<骨架中的 ref>: Dann von einem bestimmten Teilbaum aus weiter in die Tiefe gehen
Diese Technik verkürzt den Kontext, der an das Modell übergeben wird, deutlich. Für die aufrufende Anwendung gilt: Je kürzer der Kontext, desto geringer sind die Kosten bei Token-Abrechnung.
Schritt 4: Agent über MCP und Skills anbinden
Seit 1.2.0 bringt agent-desktop einen integrierten MCP-Dienst mit, der über stdio läuft und Tools wie desktop_snapshot, desktop_click usw. bereitstellt. Die Konfigurationsformate unterscheiden sich je nach Client leicht; hier einige Beispiele:
- Startbefehl:
agent-desktop mcp - Allgemeines JSON-Konfigurationsbeispiel:
{"mcpServers": {"agent-desktop": {"command": "agent-desktop", "args": ["mcp"]}}} - Beispiel für Claude Code:
claude mcp add agent-desktop -- agent-desktop mcp
Wenn dein Agent Skills unterstützt, kannst du auch direkt die offizielle Nutzungsanleitung laden, damit das Modell weiß, wie es aufgerufen werden soll:
agent-desktop skills get desktop,agent-desktop skills get platform: gibt die Skill-Beschreibung ausnpx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop: Installation über skills.sh
Wenn du Aufrufe im selben Prozess benötigst, kannst du auch die C-Bibliothek libagent_desktop_ffi verwenden.
Optional: agent-desktop sandbox in 1.3.0
1.3.0 führt den Unterbefehl agent-desktop sandbox und einen macOS-Sandbox-Provider ein. Damit lässt sich Automatisierung in einer lokal signierten macOS-VM ausführen und die Aktionen des Agents von deinem echten Desktop isolieren. Das ist kein Pflichtschritt; der minimale Workflow hängt nicht davon ab. Wenn du befürchtest, dass der Agent echte Dateien versehentlich verändert, oder viele explorative Aufgaben ausführen möchtest, kann sich das als sinnvoll erweisen.
🚀 Schnellstart: Sobald MCP eingerichtet ist, benötigt der aufrufende Agent noch ein nutzbares Modell. Die offiziell empfohlene Vorgehensweise: Erstelle im APIYI-Kontrollzentrum unter apiyi.com ein Token und richte die Base URL des Agents darauf aus. Mit einem Key kannst du zwischen Modellen wie Claude, GPT, Gemini usw. wechseln und sie vergleichen.
Dem agent-desktop-Loop ein Modell-„Gehirn“ anschließen
agent-desktop ist nur für die „Augen und Hände“ zuständig – das „Gehirn“, das entscheidet, welcher ref angeklickt wird und ob eine Aufgabe abgeschlossen ist, sitzt beim Aufrufer. In diesem Schritt gibt es zwei entscheidende Konfigurationen: die Base URL und das Modell.
Base URL: Mit oder ohne /v1 – der Unterschied ist entscheidend
Aufrufende Agents nutzen in der Regel zwei Arten von Protokollen, die jeweils eine andere Schreibweise der Base URL erfordern – eine falsche Schreibweise ist die häufigste Ursache für 404-Fehler:
- OpenAI-kompatibles Protokoll (die meisten selbstgebauten Skripte, der OpenAI-kompatible Provider von OpenCode):
https://api.apiyi.com/v1, mit/v1 - Anthropic-Nativprotokoll (Clients wie Claude Code, die direkt die messages-Schnittstelle nutzen):
https://api.apiyi.com, ohne/v1
Am Beispiel von Claude Code lässt sich die Konfiguration über Umgebungsvariablen verdeutlichen:
export ANTHROPIC_BASE_URL=https://api.apiyi.comexport ANTHROPIC_AUTH_TOKEN=你的令牌
Bei selbstgebauten Python- oder Node-Skripten, die das OpenAI SDK verwenden, setzt man base_url auf https://api.apiyi.com/v1 und trägt bei model einfach claude-opus-5-5 ein. Tokens werden unter api.apiyi.com/token erstellt; die detaillierte Konfiguration findet sich in docs.apiyi.com/faq/base-url-config.md.
Wie man die Schleife eines selbstgebauten Agents schreibt
Wenn Sie nicht auf einen fertigen Agent angewiesen sein wollen, ist es gar nicht so kompliziert, selbst eine Schleife zu schreiben. Die Kernschritte sehen so aus:
agent-desktop snapshot --app 目标应用 -iausführen und den JSON-Envelope aus stdout lesen- Aufgabenziel und Snapshot-JSON gemeinsam an das Modell schicken und verlangen, dass es nur die nächste Aktion plus vollständigen ref zurückgibt
- Den vom Modell gelieferten Befehl ausführen, zum Beispiel
agent-desktop click @sxxxx:eN - Erneut einen Snapshot erstellen und das neue Ergebnis an das Modell geben, damit es entscheidet, ob die Aufgabe fertig ist; bei
STALE_REFeinfach neu beobachten - Eine maximale Schrittzahl und Punkte für die manuelle Bestätigung festlegen, um Endlosschleifen oder ungewollte Aktionen zu vermeiden
Die Schritte 2 und 4 verbrauchen jeweils Tokens. Die zuvor erwähnte Vorgehensweise mit --skeleton plus --root zum schrittweisen Aufbohren wirkt sich hier direkt auf die Kosten aus.
Modellwahl: claude-opus-5-5 und claude-sonnet-5-5
Beide Claude-Modelle sind in der Modellübersicht von APIYI gelistet und unterstützen sowohl den chat- als auch den messages-Endpunkt. Die Preisdaten in der folgenden Tabelle haben den Stand 2026-11-13, die Einheit ist pro 1M Tokens, Modelle und Preise richten sich nach der Modellliste der Plattform.
| Modell | Eingabe | Ausgabe | Cache-Lesen | Geeignete agent-desktop-Szenarien | Verfügbare Plattform |
|---|---|---|---|---|---|
claude-opus-5-5 |
$4 | $20 | $0.2 | Mehrstufige Aufgaben mit komplexer Oberfläche und hohem Planungsbedarf | APIYI apiyi.com |
claude-sonnet-5-5 |
$2 | $10 | $0.1 | Alltagsaufgaben mit klaren Schritten und hoher Wiederholung | APIYI apiyi.com |
Ein gangbarer Ansatz: zuerst mit claude-opus-5-5 den ganzen Ablauf durchlaufen lassen, und nachdem Eingabeaufforderung und Schritte feststehen, prüfen, ob sich die stabilen Teile auf claude-sonnet-5-5 umstellen lassen. Im Snapshot-JSON steckt eine Menge wiederholter System-Eingabeaufforderungen und Tool-Beschreibungen, und der Cache-Lesepreis liegt deutlich unter dem Eingabepreis – deshalb ist das Aktivieren des Eingabeaufforderungs-Caches bei langen Schleifen von Vorteil. Die aktuellen Preise finden Sie unter docs.apiyi.com/models.
agent-desktop Fehlersuche: Berechtigungsproblem oder Modellproblem
agent-desktop und das Modell laufen über zwei voneinander unabhängige Pfade. Bei einer Fehlermeldung lohnt es sich, zuerst zu klären, auf welcher Seite das Problem liegt – das spart viele Umwege:
| Symptom | Pfad | Mögliche Ursache | Vorgehen |
|---|---|---|---|
| snapshot ist leer oder die Anwendung lässt sich nicht auslesen | Tool-Seite | Bedienungshilfen-Berechtigung nicht erteilt, oder die Anwendung stellt keinen Accessibility-Baum bereit | agent-desktop permissions --guide ausführen und die Berechtigung des Host-Prozesses prüfen |
INVALID_ARGS |
Tool-Seite | Es wurde nur ein nackter ref angegeben, zum Beispiel @e8 |
Vollständigen ref verwenden, zum Beispiel @s8f3k2p9:e8 |
STALE_REF / AMBIGUOUS_TARGET |
Tool-Seite | Die Oberfläche hat sich geändert, der ref ist nicht mehr gültig | Erneut snapshot ausführen |
| Modellanfrage 401 | Modell-Seite | Token falsch, abgelaufen oder die Umgebungsvariable hat nicht gegriffen | Token auf api.apiyi.com/token prüfen und neu exportieren |
| Modellanfrage 404 | Modell-Seite | /v1 in der Base URL falsch geschrieben oder der Modellname vertippt |
OpenAI-kompatibel mit /v1, Anthropic nativ ohne; Modell-Vergleichstabelle |
Eine einfache Faustregel: Sobald der Befehl agent-desktop im Terminal für sich allein JSON ausgibt, ist die Tool-Seite in Ordnung – die übrigen Fehler liegen dann praktisch alle auf der Modell-Seite. Bei 401/404 auf der Modell-Seite kannst du die Base-URL-Konfiguration in der Doku-Zentrale von APIYI apiyi.com Punkt für Punkt durchgehen.
agent-desktop: Berechtigungen und Datenschutzrisiken
In diesem Abschnitt geht es um die Risiken der Desktop-Automatisierung selbst – unabhängig vom Account, aber vor dem Start lohnt es sich, ihn einmal aufmerksam durchzulesen.
Das Gewicht der Bedienungshilfen-Berechtigung. Wenn Sie auf macOS die Bedienungshilfen aktivieren, kann der berechtigte Prozess die Oberfläche anderer Apps lesen und bedienen. Sobald Sie die Berechtigung an ein Terminal oder einen Agent-Host vergeben, können alle Programme, die in diesem Prozess laufen, die gleiche Fähigkeit erhalten. Vergeben Sie die Berechtigung am besten nur an die nötigen Hosts und schalten Sie sie nach Gebrauch in den Systemeinstellungen wieder ab.
Snapshots, Zwischenablage und Screenshots können private Daten enthalten. Die offiziellen Hinweise sind da eindeutig: Snapshots, der Inhalt der Zwischenablage, Screenshots, Benachrichtigungen und Debug-HTML können sensible Informationen vom Desktop enthalten – etwa Chat-Inhalte, E-Mail-Betreffzeilen, Dateinamen oder die Oberfläche eines Passwortmanagers. Diese Daten werden vom aufrufenden Programm an das Modell geschickt. Laden Sie Debug-Logs deshalb nicht öffentlich hoch und posten Sie komplette Snapshots nicht direkt in einem Issue.
Der optionale Helper greift aufs Netz zu. Die native CLI selbst benötigt keinen entfernten Modell-Dienst. Wenn Sie jedoch den optionalen JEV-Helper aktivieren, sendet er das Ziel und die Bildschirmbeschreibung an den von Ihnen konfigurierten Modell-Anbieter. Ob Sie ihn aktivieren und an wen die Daten gehen, sollten Sie bewusst entscheiden.
Die Folgen der Aktionen tragen die Nutzer. Ein Agent kann den falschen Button klicken, die falsche Datei löschen oder eine Nachricht senden, die er nicht hätte senden sollen. Um das Risiko zu senken, bieten sich diese Vorgehensweisen an: Testläufe in der Sandbox von 1.3.0, den Bereich von --app einschränken und bei risikoreichen Aktionen wie Löschen, Senden oder Bezahlen eine manuelle Bestätigung einbauen. Außerdem sind Apps, die der Accessibility-Baum nicht lesen kann, für agent-desktop unsichtbar. Das ist eine Grenze der Fähigkeiten – erwarten Sie nicht, dass es jede Software bedienen kann.
Ein Drittanbieter-Agent an einem Gateway ist ein anderes Risiko. Wenn Sie Drittanbieter-Agenten wie Claude Code oder OpenCode an ein beliebiges API-Gateway anbinden, achten Sie auf die Aufbewahrung der Tokens, Obergrenzen für das Kontingent und darauf, ob sensible Inhalte in die Logs geschrieben werden. Das ist getrennt von den Risiken der Desktop-Automatisierung zu bewerten. Legen Sie für den Agenten am besten ein eigenes Token an und setzen Sie ein Kontingent – bei Problemen können Sie es dann separat widerrufen.
Häufig gestellte Fragen (FAQ)
Q1: Was ist agent-desktop?
agent-desktop ist ein von Vercel Labs quelloffenes Computer-Use-CLI. Über den Barrierefreiheitsbaum des Betriebssystems ermöglicht es KI-Agenten, Desktop-Anwendungen unter macOS, Windows und Linux zu sehen und zu bedienen – ohne auf Screenshots oder Pixel-Matching angewiesen zu sein. Es ist ein Werkzeug, kein Agent, und enthält selbst kein Modell.
Q2: Worin unterscheidet sich agent-desktop von screenshot-basiertem Computer Use?
Screenshot-basierte Ansätze verlassen sich darauf, dass ein Vision-Modell die Pixel versteht und dann Koordinaten liefert – eine lange Kette, die auch empfindlich auf die Auflösung reagiert. agent-desktop gibt stattdessen direkt strukturiertes JSON und eine ref aus; das Modell arbeitet über die ref und läuft standardmäßig headless, ohne Mauszeiger und Fokus zu übernehmen. Der Preis dafür: Es sieht nur Anwendungen, die Barrierefreiheitsinformationen bereitstellen.
Q3: Welche Version hat agent-desktop derzeit?
Stand 2026-11-13 ist der sichtbar letzte Versionsstand 1.3.0 (2026-11-11) mit neu hinzugekommener Sandbox. MCP gibt es seit 1.2.0 (2026-11-05), Linux ist mit 1.0.0 (2026-10-27) offiziell in die 1.0 eingestiegen. Die Versionen ändern sich schnell; maßgeblich sind die GitHub Releases.
Q4: Für welche Szenarien eignet sich agent-desktop?
– **Test nativer Anwendungen**: automatisch Einstellungsfenster anklicken, Oberflächenzustand prüfen
– **Erweiterung für Programmier-Agenten**: Claude Code nach dem Schreiben von Code eine Desktop-App öffnen und das Ergebnis prüfen lassen
– **Wiederkehrende Desktop-Abläufe**: Finder-Dateien aufräumen, Benachrichtigungen lesen, Zwischenablage lesen und schreiben
Aufgaben rund ums Web gehören zu agent-browser.
Q5: Wie bindet ein Agent, der agent-desktop aufruft, schnell ein Modell an?
1. Bei APIYI apiyi.com registrieren und auf der Token-Seite einen API-Schlüssel erstellen; neue Nutzer erhalten ein kostenloses Testkontingent
2. Bei einem OpenAI-kompatiblen Client die Base URL auf `https://api.apiyi.com/v1` setzen, bei einem nativen Anthropic-Client auf `https://api.apiyi.com`
3. Als Modell `claude-opus-5-5` oder `claude-sonnet-5-5` wählen und dann die snapshot-Schleife aus diesem Artikel durchlaufen
Q6: MCP ist eingerichtet, aber der Agent meldet 401 oder 404 – liegt das an agent-desktop?
Meist nicht. agent-desktop verbindet sich nicht mit dem Modelldienst; 401 deutet in der Regel auf ein Token-Problem hin, 404 meist auf ein falsch geschriebenes `/v1` oder einen Tippfehler im Modellnamen. Führe zunächst im Terminal allein `agent-desktop snapshot` aus, um zu bestätigen, dass das Werkzeug läuft, und gleiche dann anhand der Base-URL-Konfigurationsdokumentation von APIYI apiyi.com die Modellseite ab.
Q7: Welche bekannten Einschränkungen hat agent-desktop?
– Anwendungen, deren Barrierefreiheitsbaum nicht lesbar ist, bleiben für es unsichtbar
– Einige Versionen enthalten Breaking Changes (z. B. 1.1.0, 1.3.0); vor dem Upgrade bitte das Changelog lesen
– Der Sandbox-Provider richtet sich derzeit an macOS; ob andere Plattformen folgen, ist derzeit unbekannt
– Es macht keine Web-Automatisierung und muss mit agent-browser kombiniert werden
agent-desktop – die wichtigsten Punkte (Key Takeaways)
- Das Tool enthält kein Modell: agent-desktop gibt nur ein JSON-Envelope aus; Schleife und Entscheidungen liegen beim Aufrufer
- Computer Use ohne Screenshots: basiert auf den Barrierefreiheitsbäumen von AX, UI Automation und AT-SPI und arbeitet über ref
- ref muss vollständig sein: in der Form
@s8f3k2p9:e8; nach einer Änderung der Oberfläche ist ein neuer Snapshot nötig - Auf drei Plattformen verfügbar: macOS 13+, Windows 10 1809+, Ubuntu 24.04+
- MCP-Anbindung in einer Zeile: seit 1.2.0 läuft
agent-desktop mcpüber stdio - Webseiten an agent-browser übergeben: Electron-Anwendungen lassen sich über den DevTools-Port übergeben
- Das Gehirn anbinden: Die Base URL des Aufrufers zeigt auf APIYI apiyi.com, ausgewählt wird
claude-opus-5-5
Zusammenfassung
Die Kernpunkte von agent-desktop:
- Klare Positionierung: Es sind die „Augen und Hände“ von Desktop-Anwendungen, ohne Modell und ohne Zuständigkeit für Webseiten
- Einfacher Regelkreis: Installation →
permissions --guide→ Snapshot → Klick → erneuter Snapshot; mit--skeletonlässt sich die Kontextlänge steuern - Flexible Anbindung: CLI, MCP, Skills und FFI sind alle möglich; die Sandbox von 1.3.0 eignet sich für isolierte Testläufe
- Risiken im Griff behalten: Bedienungshilfen-Berechtigungen und private Inhalte in Snapshots müssen nach den Standards der Desktop-Automatisierung verwaltet werden
Wenn die Tool-Seite erst einmal läuft, bleibt nur noch die Aufgabe, der Schleife ein passendes Gehirn zur Seite zu stellen. Empfohlen: Erstellen Sie einen Token über APIYI apiyi.com, richten Sie die Base URL von Claude Code, OpenCode oder selbstgebauten Skripten dorthin, verifizieren Sie den Ablauf zunächst mit claude-opus-5-5 und prüfen Sie dann je nach Aufgabenkomplexität, ob ein Wechsel zu claude-sonnet-5-5 sinnvoll ist.
📚 Referenzen
- GitHub – agent-desktop: Das offizielle Open-Source-Repository mit README, FAQ und Changelog
- Link:
github.com/vercel-labs/agent-desktop -
Hinweis: Versionsänderungen, Befehlsliste und Datenschutzhinweise orientieren sich an dieser Quelle
-
agent-desktop offizielle Dokumentation: Konzepte und Schnellstart
- Link:
agent-browser.dev/desktop,agent-browser.dev/desktop/quick-start -
Hinweis: Installation, Autorisierung und ein minimales End-to-End-Beispiel
-
npm – agent-desktop: npm-Paketseite
- Link:
npmjs.com/package/agent-desktop -
Hinweis: Aktuell veröffentlichte Version einsehen
-
Vercel – What is computer use: Einführung in das computer-use-Konzept
- Link:
vercel.com/i/what-is-computer-use -
Hinweis: Den Unterschied zwischen dem Accessibility-Tree-Ansatz und dem Screenshot-Ansatz verstehen
-
APIYI Dokumentationszentrum: Modellübersicht, Base-URL-Konfiguration, Claude-Funktionsbeschreibung
- Link:
docs.apiyi.com/models.md,docs.apiyi.com/faq/base-url-config.md,docs.apiyi.com/api-capabilities/claude.md - Hinweis: Modelle und Preise richten sich nach der Modellliste der Plattform
Autor: APIYI Technikteam
Technischer Austausch: Kontaktieren Sie uns gerne über die Startseite der APIYI-Website apiyi.com. Weitere Materialien finden Sie im Dokumentationszentrum unter docs.apiyi.com
