Agentenschleife

Der Agenten-Loop ist der serialisierte, sitzungsbezogene Lauf, der eine Nachricht in Aktionen und eine Antwort umwandelt: Annahme, Kontextzusammenstellung, Modellinferenz, Werkzeugausführung, Streaming, Persistierung.

​

Einstiegspunkte

• Gateway-RPC: agent und agent.wait.
• CLI: openclaw agent.

​

Ablauf eines Laufs

1. agent-RPC validiert Parameter, löst die Sitzung auf (sessionKey/sessionId), persistiert Sitzungsmetadaten und gibt sofort { runId, acceptedAt } zurück.
2. agentCommand führt den Turn aus: löst die Standardwerte für Modell, Denken, Ausführlichkeit und Ablaufverfolgung auf, lädt den Skills-Snapshot, ruft runEmbeddedAgent auf und gibt ersatzweise Lebenszyklusende/-fehler aus, falls der eingebettete Loop dies nicht bereits getan hat.
3. runEmbeddedAgent: Serialisiert Läufe über sitzungsbezogene und globale Warteschlangen, löst Modell und Authentifizierungsprofil auf, erstellt die OpenClaw-Sitzung, abonniert Laufzeitereignisse, streamt Assistenten-/Werkzeug-Deltas, erzwingt das Laufzeitlimit (mit Abbruch nach dessen Ablauf) und gibt Nutzdaten sowie Nutzungsmetadaten zurück. Bei Turns des Codex-App-Servers bricht es außerdem einen angenommenen Turn ab, der vor einem terminalen Ereignis keinen weiteren App-Server-Fortschritt mehr erzeugt.
4. subscribeEmbeddedAgentSession überführt Laufzeitereignisse in den agent-Stream: Werkzeugereignisse in stream: "tool", Assistenten-Deltas in stream: "assistant", Lebenszyklusereignisse in stream: "lifecycle" (phase: "start" | "end" | "error").
5. agent.wait (waitForAgentRun) wartet auf Lebenszyklusende/-fehler für eine runId und gibt { status: ok|error|timeout, startedAt, endedAt, error? } zurück.

​

Warteschlangen und Nebenläufigkeit

Läufe werden pro Sitzungsschlüssel (Sitzungs-Lane) und optional über eine globale Lane serialisiert, wodurch Werkzeug-/Sitzungs-Wettlaufsituationen verhindert werden. Nachrichtenkanäle wählen einen Warteschlangenmodus (steer/followup/collect/interrupt), der dieses Lane-System speist; siehe Befehlswarteschlange. Transkriptschreibvorgänge werden zusätzlich durch eine Sitzungsschreibsperre für die Sitzungsdatei geschützt. Die Sperre ist prozessbezogen und dateibasiert, sodass sie Schreibende erfasst, die die prozessinterne Warteschlange umgehen oder aus einem anderen Prozess stammen. Schreibende warten standardmäßig bis zu 60 Sekunden (Umgebungsüberschreibung OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS), bevor die Sitzung als beschäftigt gemeldet wird. Sitzungsschreibsperren sind standardmäßig nicht wiedereintrittsfähig. Eine Hilfsfunktion, die absichtlich den Erwerb derselben Sperre verschachtelt und dabei einen einzigen logischen Schreibenden beibehält, muss dies mit allowReentrant: true ausdrücklich aktivieren.

​

Vorbereitung von Sitzung und Arbeitsbereich

• Der Arbeitsbereich wird aufgelöst und erstellt; sandboxgeschützte Läufe können auf ein Sandbox-Arbeitsbereichsstammverzeichnis umgeleitet werden.
• Skills werden geladen (oder aus einem Snapshot wiederverwendet) und in die Umgebung und den Prompt eingefügt.
• Bootstrap-/Kontextdateien werden aufgelöst und in den System-Prompt eingefügt.
• Eine Sitzungsschreibsperre wird erworben und das Ziel für das Sitzungstranskript vorbereitet, bevor das Streaming beginnt. Jeder spätere Pfad zum Umschreiben, zur Compaction oder zur Kürzung des Transkripts muss dieselbe Sperre erwerben, bevor die SQLite-Transkriptzeilen geändert werden.

​

Prompt-Zusammenstellung

Der System-Prompt wird aus dem Basis-Prompt von OpenClaw, dem Skills-Prompt, dem Bootstrap-Kontext und laufbezogenen Überschreibungen erstellt. Modellspezifische Limits und für die Compaction reservierte Tokens werden durchgesetzt. Unter System-Prompt finden Sie, was das Modell sieht.

​

Hooks

OpenClaw verfügt über zwei Hook-Systeme:

• Interne Hooks (Gateway-Hooks): ereignisgesteuerte Skripte für Befehle und Lebenszyklusereignisse.
• Plugin-Hooks: Erweiterungspunkte innerhalb des Agenten-/Werkzeuglebenszyklus und der Gateway-Pipeline.

​

Interne Hooks (Gateway-Hooks)

• agent:bootstrap: Wird beim Erstellen der Bootstrap-Dateien ausgeführt, bevor der System-Prompt finalisiert wird. Verwenden Sie ihn, um Bootstrap-Kontextdateien hinzuzufügen oder zu entfernen.
• Befehls-Hooks: /new, /reset, /stop und andere Befehlsereignisse (siehe die Hooks-Dokumentation).

Einrichtung und Beispiele finden Sie unter Hooks.

​

Plugin-Hooks

Diese werden innerhalb des Agenten-Loops oder der Gateway-Pipeline ausgeführt: Hook-Entscheidungsregeln für ausgehende/Werkzeug-Guards:

• before_tool_call: { block: true } ist terminal und stoppt Handler mit niedrigerer Priorität. { block: false } ist eine wirkungslose Operation und hebt eine vorherige Blockierung nicht auf.
• before_install: dieselbe Terminal-/Keine-Wirkung-Semantik wie oben. Verwenden Sie security.installPolicy und nicht before_install für betreiberseitige Entscheidungen zum Zulassen/Blockieren von Installationen, die CLI-Installations- und Aktualisierungspfade abdecken müssen.
• message_sending: { cancel: true } ist terminal und stoppt Handler mit niedrigerer Priorität. { cancel: false } ist eine wirkungslose Operation und hebt einen vorherigen Abbruch nicht auf.

Die Hook-API und Einzelheiten zur Registrierung finden Sie unter Plugin-Hooks. Testumgebungen können diese Hooks anpassen. Die Codex-App-Server-Testumgebung behält OpenClaw-Plugin-Hooks als Kompatibilitätsvertrag für dokumentierte gespiegelte Oberflächen bei; native Codex-Hooks sind ein separater, systemnäherer Codex-Mechanismus.

​

Streaming

• Assistenten-Deltas werden von der Agentenlaufzeit als assistant-Ereignisse gestreamt.
• Block-Streaming kann Teilantworten bei text_end oder message_end ausgeben.
• Das Streaming von Schlussfolgerungen kann als separater Stream oder in Blockantworten erfolgen.
• Informationen zu Aufteilung und Blockantwortverhalten finden Sie unter Streaming.

​

Werkzeugausführung

• Ereignisse für Werkzeugstart/-aktualisierung/-ende werden im tool-Stream ausgegeben.
• Werkzeugergebnisse werden vor der Protokollierung/Ausgabe hinsichtlich Größe und Bildnutzdaten bereinigt.
• Sendungen durch Nachrichtenwerkzeuge werden verfolgt, um doppelte Assistentenbestätigungen zu unterdrücken.

​

Antwortgestaltung

Endgültige Nutzdaten werden aus Assistententext (zuzüglich optionaler Schlussfolgerungen), Inline-Werkzeugzusammenfassungen (wenn ausführlich und zulässig) und Assistentenfehlertext bei Modellfehlern zusammengestellt.

• Das exakte Stille-Token NO_REPLY wird aus ausgehenden Nutzdaten herausgefiltert.
• Duplikate von Nachrichtenwerkzeugen werden aus der endgültigen Nutzdatenliste entfernt.
• Wenn keine darstellbaren Nutzdaten verbleiben und bei einem Werkzeug ein Fehler aufgetreten ist, wird ersatzweise eine Werkzeugfehlerantwort ausgegeben, sofern nicht bereits ein Nachrichtenwerkzeug eine für Benutzende sichtbare Antwort gesendet hat.

​

Compaction und Wiederholungsversuche

Die automatische Compaction gibt compaction-Stream-Ereignisse aus und kann einen Wiederholungsversuch auslösen. Beim Wiederholungsversuch werden speicherinterne Puffer und Werkzeugzusammenfassungen zurückgesetzt, um doppelte Ausgaben zu vermeiden. Siehe Compaction.

​

Ereignis-Streams

• lifecycle: Wird von subscribeEmbeddedAgentSession ausgegeben (und ersatzweise von agentCommand).
• assistant: Gestreamte Deltas aus der Agentenlaufzeit.
• tool: Gestreamte Werkzeugereignisse aus der Agentenlaufzeit.

Das Gateway projiziert Lebenszyklusereignisse sowie Start-/Terminalereignisse von Werkzeugen in das begrenzte, rein metadatenbasierte Audit-Ledger. Diese Projektion zeichnet Herkunft und Ergebniscodes auf, ohne Prompts, Nachrichten, Werkzeugargumente, Werkzeugergebnisse oder Rohfehler aus dem Transkript-/Laufzeitpfad zu kopieren.

​

Verarbeitung von Chatkanälen

Assistenten-Deltas werden in Chat-delta-Nachrichten gepuffert. Bei Lebenszyklusende/-fehler wird ein Chat-final ausgegeben.

​

Zeitlimits

​

Diagnose festgefahrener Sitzungen

Bei aktivierter Diagnose klassifiziert ein integrierter Schwellenwert von zwei Minuten lang laufende processing-Sitzungen, bei denen keine Antwort sowie kein Werkzeug-, Status-, Block- oder ACP-Fortschritt beobachtet wurde:

• Aktive eingebettete Läufe, Modellaufrufe und Werkzeugaufrufe werden als session.long_running gemeldet. Zugeordnete stille Modellaufrufe bleiben bis zum Abbruchschwellenwert session.long_running, damit langsame oder nicht streamende Provider nicht zu früh als festgefahren gekennzeichnet werden.
• Aktive Arbeit ohne kürzlichen Fortschritt wird als session.stalled gemeldet. Zugeordnete Modellaufrufe wechseln beim oder nach dem Abbruchschwellenwert zu session.stalled; veraltete Modell-/Werkzeugaktivität ohne Eigentümer wird nicht als lang laufend verborgen.
• session.stuck ist für wiederherstellbare veraltete Sitzungsbuchführung reserviert, einschließlich inaktiver Sitzungen in der Warteschlange mit veralteter Modell-/Werkzeugaktivität ohne Eigentümer.

Der Abbruchschwellenwert beträgt mindestens 5 Minuten und das Dreifache des Warnschwellenwerts. Die Bereinigung veralteter Sitzungsbuchführung gibt die betroffene Sitzungs-Lane unmittelbar frei, nachdem die Wiederherstellungsprüfungen bestanden wurden; festgefahrene eingebettete Läufe werden erst nach dem Abbruchschwellenwert abgebrochen und geleert, sodass Arbeit in der Warteschlange fortgesetzt wird, ohne lediglich langsame Läufe abzubrechen. Die Wiederherstellung gibt strukturierte Ergebnisse für Anforderung und Abschluss aus; der Diagnosestatus wird nur dann als inaktiv markiert, wenn dieselbe Verarbeitungsgeneration noch aktuell ist, und wiederholte session.stuck-Diagnosen verwenden ein zunehmendes Warteintervall, solange die Sitzung unverändert bleibt.

​

Mögliche Gründe für eine vorzeitige Beendigung

• Agent-Zeitüberschreitung (Abbruch)
• AbortSignal (Abbrechen)
• Gateway-Verbindungsabbruch oder RPC-Zeitüberschreitung
• Zeitüberschreitung von agent.wait (nur Warten, stoppt den Agent nicht)

​

Verwandte Themen

• Werkzeuge – verfügbare Agent-Werkzeuge
• Hooks – ereignisgesteuerte Skripte, die durch Ereignisse im Agent-Lebenszyklus ausgelöst werden
• Compaction – wie lange Unterhaltungen zusammengefasst werden
• Ausführungsgenehmigungen – Genehmigungsschranken für Shell-Befehle
• Denken – Konfiguration der Denk-/Schlussfolgerungsebene