Pętla agenta (OpenClaw)¶

Pętla agentowa to pełny, „rzeczywisty” przebieg agenta: przyjęcie → złożenie kontekstu → inferencja modelu → wykonanie narzędzi → strumieniowanie odpowiedzi → utrwalenie. Jest to autorytatywna ścieżka, która zamienia wiadomość w działania i odpowiedź końcową, jednocześnie utrzymując spójny stan sesji.

W OpenClaw pętla to pojedyncze, zserializowane uruchomienie na sesję, które emituje zdarzenia cyklu życia i strumieni w trakcie myślenia modelu, wywołań narzędzi oraz strumieniowania wyjścia. Ten dokument wyjaśnia, jak ta właściwa pętla jest połączona end-to-end.

Punkty wejścia¶

• RPC Gateway: agent i agent.wait.
• CLI: polecenie agent.

Jak to działa (wysoki poziom)¶

1. RPC agent weryfikuje parametry, rozwiązuje sesję (sessionKey/sessionId), zapisuje metadane sesji i natychmiast zwraca { runId, acceptedAt }.
2. agentCommand uruchamia agenta: - rozwiązuje model + domyślne ustawienia thinking/verbose - ładuje migawkę skills - wywołuje runEmbeddedPiAgent (środowisko uruchomieniowe pi-agent-core) - emituje lifecycle end/error, jeśli osadzona pętla nie wyemituje takiego zdarzenia
3. runEmbeddedPiAgent: - serializuje uruchomienia przez kolejki per-sesja + globalne - rozwiązuje model + profil uwierzytelniania i buduje sesję pi - subskrybuje zdarzenia pi i strumieniuje delty asystenta/narzędzi - wymusza limit czasu -> przerywa działanie, jeśli przekroczony - zwraca ładunki + metadane użycia
4. subscribeEmbeddedPiSession mostkuje zdarzenia pi-agent-core do strumienia OpenClaw agent: - zdarzenia narzędzi => stream: "tool" - delty asystenta => stream: "assistant" - zdarzenia cyklu życia => stream: "lifecycle" (phase: "start" | "end" | "error")
5. agent.wait używa waitForAgentJob: - czeka na lifecycle end/error dla runId - zwraca { status: ok|error|timeout, startedAt, endedAt, error? }

Kolejkowanie + współbieżność¶

• Uruchomienia są serializowane per klucz sesji (pas sesji) i opcjonalnie przez pas globalny.
• Zapobiega to wyścigom narzędzi/sesji i utrzymuje spójność historii sesji.
• Kanały komunikacyjne mogą wybierać tryby kolejek (collect/steer/followup), które zasilają ten system pasów. Zobacz Command Queue.

Przygotowanie sesji + obszaru roboczego¶

• Obszar roboczy jest rozwiązywany i tworzony; uruchomienia w sandboxie mogą przekierowywać do katalogu głównego obszaru roboczego sandbox.
• Skills są ładowane (lub ponownie używane z migawki) i wstrzykiwane do środowiska oraz promptu.
• Pliki bootstrap/kontekstu są rozwiązywane i wstrzykiwane do raportu promptu systemowego.
• Uzyskiwana jest blokada zapisu sesji; SessionManager jest otwierany i przygotowywany przed strumieniowaniem.

Składanie promptu + prompt systemowy¶

• Prompt systemowy jest budowany z bazowego promptu OpenClaw, promptu skills, kontekstu bootstrap oraz nadpisań per-uruchomienie.
• Egzekwowane są limity specyficzne dla modelu oraz rezerwa tokenów na kompaktowanie.
• Zobacz System prompt, aby dowiedzieć się, co widzi model.

Punkty hooków (gdzie można przechwycić)¶

OpenClaw ma dwa systemy hooków:

• Hooki wewnętrzne (hooki Gateway): skrypty sterowane zdarzeniami dla poleceń i zdarzeń cyklu życia.
• Hooki wtyczek: punkty rozszerzeń wewnątrz cyklu życia agenta/narzędzi oraz potoku gateway.

Hooki wewnętrzne (hooki Gateway)¶

• agent:bootstrap: uruchamiany podczas budowania plików bootstrap przed finalizacją promptu systemowego. Użyj tego, aby dodać/usunąć pliki kontekstu bootstrap.
• Hooki poleceń: /new, /reset, /stop oraz inne zdarzenia poleceń (zobacz dokumentację Hooków).

Zobacz Hooks w celu konfiguracji i przykładów.

Hooki wtyczek (cykl życia agenta + gateway)¶

Działają one wewnątrz pętli agenta lub potoku gateway:

• before_agent_start: wstrzykuje kontekst lub nadpisuje prompt systemowy przed startem uruchomienia.
• agent_end: inspekcja końcowej listy wiadomości i metadanych uruchomienia po zakończeniu.
• before_compaction / after_compaction: obserwacja lub adnotacja cykli kompaktowania.
• before_tool_call / after_tool_call: przechwytywanie parametrów/wyników narzędzi.
• tool_result_persist: synchroniczna transformacja wyników narzędzi przed zapisaniem ich do transkryptu sesji.
• message_received / message_sending / message_sent: hooki wiadomości przychodzących i wychodzących.
• session_start / session_end: granice cyklu życia sesji.
• gateway_start / gateway_stop: zdarzenia cyklu życia gateway.

Zobacz Plugins w celu zapoznania się z API hooków i szczegółami rejestracji.

Strumieniowanie + odpowiedzi częściowe¶

• Delty asystenta są strumieniowane z pi-agent-core i emitowane jako zdarzenia assistant.
• Strumieniowanie blokowe może emitować odpowiedzi częściowe na text_end lub message_end.
• Strumieniowanie rozumowania może być emitowane jako osobny strumień lub jako odpowiedzi blokowe.
• Zobacz Streaming w celu informacji o dzieleniu na fragmenty i zachowaniu odpowiedzi blokowych.

Wykonanie narzędzi + narzędzia komunikacyjne¶

• Zdarzenia start/update/end narzędzi są emitowane na strumieniu tool.
• Wyniki narzędzi są sanityzowane pod kątem rozmiaru i ładunków obrazów przed logowaniem/emisją.
• Wysyłki narzędzi komunikacyjnych są śledzone w celu tłumienia zduplikowanych potwierdzeń asystenta.

Kształtowanie odpowiedzi + tłumienie¶

• Końcowe ładunki są składane z:
• tekstu asystenta (i opcjonalnego rozumowania)
• wbudowanych podsumowań narzędzi (gdy verbose + dozwolone)
• tekstu błędu asystenta, gdy model zwróci błąd
• NO_REPLY jest traktowany jako cichy token i filtrowany z wychodzących ładunków.
• Duplikaty narzędzi komunikacyjnych są usuwane z końcowej listy ładunków.
• Jeśli nie pozostaną renderowalne ładunki, a narzędzie zwróciło błąd, emitowana jest zapasowa odpowiedź błędu narzędzia (chyba że narzędzie komunikacyjne już wysłało odpowiedź widoczną dla użytkownika).

Kompaktowanie + ponowienia¶

• Automatyczne kompaktowanie emituje zdarzenia strumienia compaction i może wyzwolić ponowienie.
• Przy ponowieniu bufory w pamięci i podsumowania narzędzi są resetowane, aby uniknąć zduplikowanego wyjścia.
• Zobacz Compaction w celu poznania potoku kompaktowania.

Strumienie zdarzeń (obecnie)¶

• lifecycle: emitowane przez subscribeEmbeddedPiSession (oraz jako fallback przez agentCommand)
• assistant: strumieniowane delty z pi-agent-core
• tool: strumieniowane zdarzenia narzędzi z pi-agent-core

Obsługa kanału czatu¶

• Delty asystenta są buforowane do wiadomości czatu delta.
• Wiadomość czatu final jest emitowana przy lifecycle end/error.

Limity czasu¶

• Domyślnie agent.wait: 30 s (tylko oczekiwanie). Parametr timeoutMs nadpisuje.
• Czas działania agenta: domyślnie agents.defaults.timeoutSeconds 600 s; egzekwowane w runEmbeddedPiAgent przez timer przerwania.

Gdzie proces może zakończyć się wcześniej¶

• Limit czasu agenta (przerwanie)
• AbortSignal (anulowanie)
• Rozłączenie gateway lub timeout RPC
• Limit czasu agent.wait (tylko oczekiwanie, nie zatrzymuje agenta)