Einen Agenten diagnostizieren

Diese Anleitung zeigt, wie du herausfindest, warum ein Agent keine Läufe erzeugt.

Arbeite von oben nach unten: zuerst die eigenen Läufe des Agenten, dann sein Backend, dann der Server, dann der Host.

1. Die Laufhistorie des Agenten prüfen

Einstellungen → Arbeitsbereich → Agenten → den Agenten auswählen → Protokolle.

Jeder Lauf zeigt ein Status-Badge, eine Dauer („Running…“, solange er läuft), Start- und Endzeit, die PID und den verwendeten Adapter. Ansicht öffnet den rohen Ereignisstrom dieses Laufs. Stoppen beendet einen laufenden Prozess und markiert den Lauf mit „Killed by user“; Laufenden beenden in der Kopfzeile tut dasselbe für jeden laufenden Lauf dieses Agenten.

Lies es so:

Gar keine Läufe — die Ausführung ist nie angestoßen worden. Erwähnungen im Composer sind @ plus Wortzeichen (Buchstaben, Ziffern, Unterstrich). Die Auflösung ist eine exakte oder Präfix-Übereinstimmung mit dem Agentennamen, deshalb wird @code-reviewer als code gelesen und kann trotzdem einen Agenten namens code-reviewer wecken. Ein Name mit Leerzeichen lässt sich nicht als ein Token erwähnen. Danach zu Schritt 2.
Ein Lauf, der sofort mit einem Fehler endete — öffne Ansicht. Ein Fehlstart des Backends erscheint hier als Prozessfehler.
Ein Lauf, der bei „Running…“ hängen bleibt — stoppe ihn und prüfe dann das Stille-Timeout (Minuten) des Agenten im Tab Einstellungen. Ohne gesetzten Wert gilt der Standard des jeweiligen Modus.
Ein abgeschlossener Lauf ohne brauchbare Ausgabe — der Status im Laufprotokoll bleibt completed, auch wenn der Lauf ohne das angekündigte Lieferergebnis endete. Das ehrliche Signal steckt im Zusammenfassungstext.

Der Tab Protokolle zeigt keine Kosten. Die Ausgaben stehen in der Tabelle je Agent unter Observability → Übersicht.

2. Das Backend des Agenten prüfen

Einstellungen → Server → Modellanbieter (/settings/server/providers).

Die Liste Erkannte Runner zeigt jeden Adapter mit seinem Prüfergebnis — eine installierte Version, „Überprüfung…“ oder „Nicht gefunden“ — dazu den aufgelösten Pfad und die Befugnis-Chips einer gefundenen CLI. Aktualisieren in der Kopfzeile der Seite startet die Prüfung neu.

Die Prüfung läuft auf dem Rechner, der cc_server hostet, nicht auf dem Rechner, den du gerade ansiehst. Auf dem Web-Client oder einem gekoppelten Gerät heißt „Nicht gefunden“, dass die CLI auf dem Server-Host fehlt.

Zwei Punkte zum Prüfen:

Der Agent hat überhaupt einen Adapter gesetzt. Ein Agent ohne Adapter fällt auf Control Center (built-in) zurück, und im Laufprotokoll steht cc-harness, das Transkript nennt also, was gelaufen ist. Fehlt auch das Modell, fragt er Anthropic nach dessen Standard. Das scheitert mit No credential for provider "anthropic", solange kein Anthropic-Konto verbunden ist. Die mit dem Arbeitsbereich angelegten Spezialisten kommen ohne Adapter.
Der eingebaute Adapter hat ein Modell. Seine Modellliste kommt live von den Anbietern, die weiter unten auf derselben Seite verbunden sind. Ein Anbieter ohne gespeicherte Zugangsdaten liefert kein Modell.

Der Adapterkatalog selbst ist fest. Einen neuen Adapter registrieren lässt sich nicht. Pro Adapter änderst du hier die Startargumente und die Umgebungsvariablen. Beim Auflösen der Zugangsdaten setzt sich eine Umgebungsüberschreibung je Adapter still gegen ein verbundenes Anbieterkonto durch.

3. Den Server prüfen

Einstellungen → Server → Verbindung und Status (/settings/server/connection) zeigt, mit welchem Server dieser Client spricht und was der Server meldet.

Bei einem Headless-Server ist GET /healthz dieselbe Auskunft ohne Client. Die Route ist absichtlich ohne Authentifizierung und mit offenem CORS:

curl http://localhost:9030/healthz

Sie liefert den Status des Servers, die Laufzeit in Sekunden, die Zahl der lebenden Verbindungen, den gebundenen Port, Build-Version und Git-SHA, die Schemaversion des Arbeitsbereichs, die Version des RPC-Katalogs, Server-ID, Name und Identitätsfingerabdruck, ob die Bindung unsicher ist, und einen codeGraph-Block mit den Zählern watching / indexing / pending. Hat ein Cache schon Verkehr gesehen, kommt ein caches-Block dazu; ein Demo-Server setzt demo: true.

Zwei Dinge, die zählen, wenn eine Änderung „in den Tests klappt, in der App aber nicht“:

Der Desktop startet bevorzugt eine vorgefertigte cc_server-Binärdatei, nicht den Quellstand. Eine neue RPC-Operation oder ein neues MCP-Tool erscheint erst nach einem Neubau der Binärdatei, und beim Start schreibt das Log eine Warnung, wenn die Git-SHA des Kindprozesses von der der App abweicht.
Der Desktop beendet einen gestarteten Server, der seine Bereitschaftsmeldung nicht innerhalb von 20 Sekunden ausgibt, und wechselt auf einen Fehlerbildschirm.

4. Den Host prüfen

Einstellungen → Server → Diagnose und Datenschutz (/settings/server/diagnostics) ist die Seite auf Host-Ebene. Sie enthält:

Sandboxing — den Hauptschalter, das erkannte Backend und einen Installationshinweis. Vom Server kommt nur das erkannte Backend; siehe die Achtung unten. Einen Zurücksetzen-Schalter gibt es nicht.
Semantische Suche — den Lebenszyklus des Embedding-Modells auf dem Gerät: installiert, wird mit Prozentangabe heruntergeladen, nicht installiert oder ein Installationsfehler. Bis es installiert ist, bleiben Gedächtnis und Codesuche bei Schlüsselwörtern.
Systemverhalten — den Computer wach halten, während Agenten laufen.
Log-Level — stell ihn höher, bevor du den Fehler nachstellst.
Datenschutz — ob roher Diff-Inhalt an das Modell des Agenten gehen darf und ob Absturzberichte gesendet werden.

Erkennung und Durchsetzung stimmen inzwischen überein: Meldet der Detektor ein natives Backend, sind Agentenläufe auf diesem Host wirklich darin eingeschlossen. Lebendig ist in diesem Abschnitt nur der Detektor. Hauptschalter und Backend-Auswahl sind Einstellungen auf deinem Gerät, und der Server liest keine davon. Der eigene Schalter des Servers ist --sandbox (Standard on, off zum Abwählen).

Eine Warnung hier lohnt das Handeln. Warum ein Agent scheitert, steht meist woanders. Welchen Zustand der Server hat, steht im Startlog: agent sandbox ON mit der Backend-Notiz, no OS-native agent sandbox on this host mit einem Installationshinweis, oder agent sandbox DISABLED by --sandbox off. GET /healthz hat kein Sandbox-Feld.

Wo kein Backend da ist — unter Windows immer, unter Linux oder WSL2 ohne bwrap und socat — laufen die Läufe ohne Sandbox. Was sie begrenzt, ist der eigene Checkout der Unterhaltung, das Forge-Token des Laufs, das nur lesen darf, und das Push-Gateway, die Schutzregeln für Aktionen, die Bereinigung der Umgebung und die Werkzeugfläche, die der Modus zulässt.

Häufige Fehler

Der Lauf startet nie und der Adapter zeigt „Nicht gefunden“

Installiere die CLI auf dem Server-Host und klicke danach auf der Seite Modellanbieter auf Aktualisieren. Oder stell den Agenten auf den eingebauten Adapter, der keine CLI braucht, und verbinde auf derselben Seite einen Anbieter.

Der Agent kann nicht pushen oder einen Pull Request öffnen

Lies, was git oder der Agent ausgegeben hat. Control Center policy: … heißt, eine Aktionsregel hat es verweigert oder eine Freigabe blieb unbeantwortet: Prüfe Zu einem Remote pushen und Einen Pull Request öffnen unter Einstellungen → Arbeitsbereich → Agent-Berechtigungen. Sagt git, Control Center habe keine GitHub-Zugangsdaten, die pushen können, installiere die GitHub App auf diesem Repo oder verbinde GitHub.

Die semantische Suche liefert nichts Brauchbares

Prüfe Einstellungen → Server → Diagnose und Datenschutz → Semantische Suche. Bis das Embedding-Modell installiert ist, sucht die Suche nur über Schlüsselwörter. Zeilen, die vor der Installation geschrieben wurden, werden nie nachträglich aufgefüllt und bleiben auch danach bei den Schlüsselwörtern.

Der Server startet überhaupt nicht

Native Bibliotheken sind Pflicht, einen eingeschränkten Modus gibt es nicht. Eine fehlende dylib lässt cc_server den Start verweigern und nennt die fehlende Datei im Fehler. Die Natives stellst du mit scripts/natives/build_natives.sh bereit und baust danach die Server-Binärdatei neu.

Eine Aktion wird stillschweigend abgelehnt

Eine Schutzregel-Entscheidung prompt ohne verbundenen Freigeber wird abgelehnt. So ist es vorgesehen. Die Regeln des Arbeitsbereichs stehen unter Einstellungen → Arbeitsbereich → Agent-Berechtigungen.