OpenClaw Agent Loop verstehen: Architektur im Detail

Kennst du das Gefühl, wenn du einen Agenten startest und es sich wie eine Black Box anfühlt? Du schickst eine Nachricht ab und wartest, während im Hintergrund irgendetwas passiert, ohne dass du den genauen Ablauf verstehst.

Ein Agentic Loop ist der “echte” Durchlauf eines Agenten: Intake → Context Assembly → Model Inference → Tool Execution → Streaming Replies → Persistence. Es ist der autoritative Pfad, der eine Nachricht in konkrete Aktionen und eine finale Antwort verwandelt, während der Session-Status konsistent bleibt. In OpenClaw ist ein Loop ein einzelner, serialisierter Run pro Session, der Lifecycle- und Stream-Events ausgibt, während das Modell denkt, Tools aufruft und Output streamt.

Entry points

• Gateway RPC: agent und agent.wait.
• CLI: agent Kommando.

How it works (high-level)

1. Der agent RPC validiert Parameter, löst die Session auf (sessionKey/sessionId), speichert Session-Metadaten und gibt { runId, acceptedAt } sofort zurück.
2. agentCommand führt den Agenten aus:
   • löst Modell + Thinking/Verbose Defaults auf
   • lädt Skills Snapshot
   • ruft runEmbeddedPiAgent auf (pi-agent-core Runtime)
   • gibt lifecycle end/error aus, falls der Embedded Loop dies nicht tut
3. runEmbeddedPiAgent:
   • serialisiert Runs über pro-Session + globale Queues
   • löst Modell + Auth Profile auf und baut die Pi-Session
   • abonniert Pi-Events und streamt Assistant/Tool Deltas
   • erzwingt Timeout -> bricht den Run bei Überschreitung ab
   • gibt Payloads + Usage-Metadaten zurück
4. subscribeEmbeddedPiSession schlägt die Brücke von pi-agent-core Events zum OpenClaw agent Stream:
   • Tool-Events => stream: "tool"
   • Assistant Deltas => stream: "assistant"
   • Lifecycle-Events => stream: "lifecycle" (phase: "start" | "end" | "error")
5. agent.wait nutzt waitForAgentJob:
   • wartet auf lifecycle end/error für die runId
   • gibt { status: ok|error|timeout, startedAt, endedAt, error? } zurück

Queueing + concurrency

• Runs werden pro Session Key (Session Lane) und optional über eine globale Lane serialisiert.
• Das verhindert Tool/Session Races und hält die Session History konsistent.
• Messaging-Channels können Queue-Modi wählen (collect/steer/followup), die dieses Lane-System füttern. Details findest du unter Command Queue.

Session + workspace preparation

• Der Workspace wird aufgelöst und erstellt; Sandboxed Runs können zu einem Sandbox-Workspace-Root umgeleitet werden.
• Skills werden geladen (oder aus einem Snapshot wiederverwendet) und in die Environment sowie den Prompt injiziert.
• Bootstrap/Context-Dateien werden aufgelöst und in den System Prompt Report eingefügt.
• Ein Session Write Lock wird angefordert; der SessionManager wird vor dem Streaming geöffnet und vorbereitet.

Prompt assembly + system prompt

• Der System Prompt wird aus dem OpenClaw Base Prompt, dem Skills Prompt, dem Bootstrap Context und Per-Run Overrides zusammengebaut.
• Modellspezifische Limits und Compaction Reserve Tokens werden erzwungen.
• Schau dir System prompt an, um zu sehen, was das Modell tatsächlich sieht.

Hook points (where you can intercept)

OpenClaw bietet zwei Hook-Systeme:

• Internal hooks (Gateway hooks): Event-gesteuerte Skripte für Kommandos und Lifecycle-Events.
• Plugin hooks: Erweiterungspunkte innerhalb des Agent/Tool Lifecycles und der Gateway Pipeline.

Internal hooks (Gateway hooks)

• agent:bootstrap: Läuft während des Erstellens der Bootstrap-Dateien, bevor der System Prompt finalisiert wird. Nutze dies, um Bootstrap-Context-Dateien hinzuzufügen oder zu entfernen.
• Command hooks: /new, /reset, /stop und andere Kommando-Events (siehe Hooks-Dokumentation).

Details findest du unter Hooks.

Plugin hooks (agent + gateway lifecycle)

Diese laufen innerhalb des Agent Loops oder der Gateway Pipeline:

• before_model_resolve: Läuft vor der Session (keine messages), um Provider/Modell deterministisch zu überschreiben.
• before_prompt_build: Läuft nach dem Laden der Session (mit messages), um prependContext, systemPrompt, prependSystemContext oder appendSystemContext vor der Prompt-Übermittlung zu injizieren. Nutze prependContext für dynamischen Text pro Turn.
• before_agent_start: Legacy-Kompatibilitäts-Hook; bevorzuge die expliziten Hooks oben.
• before_agent_reply: Läuft nach Inline-Aktionen und vor dem LLM-Call. Ein Plugin kann den Turn übernehmen und eine synthetische Antwort zurückgeben.
• agent_end: Inspiziere die finale Nachrichtenliste und Run-Metadaten nach Abschluss.
• before_compaction / after_compaction: Beobachte oder annotiere Compaction-Zyklen.
• before_tool_call / after_tool_call: Interzeptiere Tool-Parameter oder Ergebnisse.
• before_install: Prüfe Scan-Ergebnisse und blockiere optional Skill- oder Plugin-Installationen.
• tool_result_persist: Transformiere Tool-Ergebnisse synchron, bevor sie in das Session-Transkript geschrieben werden.
• message_received / message_sending / message_sent: Hooks für eingehende und ausgehende Nachrichten.
• session_start / session_end: Grenzen des Session-Lifecycles.
• gateway_start / gateway_stop: Gateway Lifecycle-Events.

Entscheidungsregeln für Hooks bei Outbound/Tool-Guards:

• before_tool_call: { block: true } ist terminal und stoppt Handler mit niedrigerer Priorität.
• before_tool_call: { block: false } ist ein No-Op.
• before_install: { block: true } ist terminal.
• before_install: { block: false } ist ein No-Op.
• message_sending: { cancel: true } ist terminal.
• message_sending: { cancel: false } ist ein No-Op.

Siehe Plugin hooks für die API-Details.

Streaming + partial replies

• Assistant Deltas werden von pi-agent-core gestreamt und als assistant Events ausgegeben.
• Block-Streaming kann partielle Antworten entweder bei text_end oder message_end senden.
• Reasoning-Streaming kann als separater Stream oder als Block-Antwort erfolgen.
• Details findest du unter Streaming.

Tool execution + messaging tools

• Tool Start/Update/End Events werden auf dem tool Stream ausgegeben.
• Tool-Ergebnisse werden hinsichtlich Größe und Image-Payloads bereinigt, bevor sie geloggt oder gesendet werden.
• Messaging-Tool-Aufrufe werden getrackt, um doppelte Bestätigungen durch den Assistant zu unterdrücken.

Reply shaping + suppression

• Finale Payloads werden zusammengesetzt aus:
  • Assistant Text (und optionalem Reasoning)
  • Inline Tool Summaries (wenn verbose + erlaubt)
  • Assistant Error Text bei Modellfehlern
• NO_REPLY wird als Silent Token behandelt und aus ausgehenden Payloads gefiltert.
• Duplikate von Messaging-Tools werden aus der finalen Liste entfernt.
• Falls keine renderbaren Payloads übrig bleiben und ein Tool-Fehler auftrat, wird eine Fallback-Fehlermeldung gesendet.

Compaction + retries

• Auto-Compaction gibt compaction Stream-Events aus und kann einen Retry auslösen.
• Bei einem Retry werden In-Memory Buffer und Tool-Summaries zurückgesetzt, um doppelten Output zu vermeiden.
• Siehe Compaction für die Pipeline-Details.

Event streams (today)

• lifecycle: Ausgegeben durch subscribeEmbeddedPiSession (oder als Fallback durch agentCommand).
• assistant: Gestreamte Deltas von pi-agent-core.
• tool: Gestreamte Tool-Events von pi-agent-core.

Chat channel handling

• Assistant Deltas werden in Chat delta Nachrichten gepuffert.
• Ein Chat final wird bei lifecycle end/error ausgegeben.

Timeouts

• agent.wait Default: 30s (nur das Warten). Der timeoutMs Parameter überschreibt dies.
• Agent Runtime: agents.defaults.timeoutSeconds Default 172800s (48 Stunden); erzwungen durch den Abort-Timer in runEmbeddedPiAgent.

Where things can end early

• Agent Timeout (Abort)
• AbortSignal (Cancel)
• Gateway Disconnect oder RPC Timeout
• agent.wait Timeout (stoppt den Agenten nicht, nur das Warten)

Related

• Tools — Verfügbare Agent-Tools
• Hooks — Event-gesteuerte Skripte
• Compaction — Zusammenfassung langer Konversationen
• Exec Approvals — Freigaben für Shell-Kommandos
• Thinking — Konfiguration des Reasoning-Levels

Hast du Fragen zur Implementierung oder brauchst Hilfe bei der Konfiguration? Der AI Setup Assistant hilft dir gerne weiter.

Nächste Schritte

• System prompt verstehen
• Plugin hooks implementieren
• Command Queue konfigurieren