​

Цикл агента (OpenClaw)

Агентний цикл — це повний «реальний» запуск агента: прийом → збирання контексту → інференс моделі → виконання інструментів → потокова передача відповідей → збереження стану. Це авторитетний шлях, який перетворює повідомлення на дії та фінальну відповідь, водночас зберігаючи узгодженість стану сесії. В OpenClaw цикл — це один серіалізований запуск на сесію, який генерує події життєвого циклу та потоків, поки модель міркує, викликає інструменти й передає вивід потоком. У цьому документі пояснюється, як цей справжній цикл повністю з’єднаний наскрізь.

​

Точки входу

• Gateway RPC: agent і agent.wait.
• CLI: команда agent.

​

Як це працює (на високому рівні)

1. RPC agent перевіряє параметри, визначає сесію (sessionKey/sessionId), зберігає метадані сесії та негайно повертає { runId, acceptedAt }.
2. agentCommand запускає агента:
   • визначає типові значення model + thinking/verbose
   • завантажує знімок Skills
   • викликає runEmbeddedPiAgent (середовище виконання pi-agent-core)
   • генерує lifecycle end/error, якщо вбудований цикл цього не згенерував
3. runEmbeddedPiAgent:
   • серіалізує запуски через черги для кожної сесії та глобальні черги
   • визначає профіль model + auth і будує pi-сесію
   • підписується на події pi та передає assistant/tool deltas потоком
   • застосовує timeout -> перериває запуск, якщо його перевищено
   • повертає payloads + метадані usage
4. subscribeEmbeddedPiSession з’єднує події pi-agent-core з потоком OpenClaw agent:
   • події інструментів => stream: "tool"
   • deltas помічника => stream: "assistant"
   • події життєвого циклу => stream: "lifecycle" (phase: "start" | "end" | "error")
5. agent.wait використовує waitForAgentRun:
   • очікує на lifecycle end/error для runId
   • повертає { status: ok|error|timeout, startedAt, endedAt, error? }

​

Черги й паралельність

• Запуски серіалізуються для кожного ключа сесії (доріжка сесії) і за потреби також через глобальну доріжку.
• Це запобігає гонкам інструментів/сесій і зберігає узгодженість історії сесії.
• Канали обміну повідомленнями можуть вибирати режими черги (collect/steer/followup), які подаються в цю систему доріжок. Див. Черга команд.

​

Підготовка сесії та workspace

• Workspace визначається й створюється; запуски в sandbox можуть бути перенаправлені до кореня workspace sandbox.
• Skills завантажуються (або повторно використовуються зі знімка) та впроваджуються в env і prompt.
• Файли bootstrap/context визначаються й додаються до звіту системного prompt.
• Отримується блокування запису сесії; SessionManager відкривається й готується до потокової передачі.

​

Збирання prompt і системний prompt

• Системний prompt будується з базового prompt OpenClaw, prompt Skills, bootstrap-контексту та перевизначень для окремого запуску.
• Застосовуються обмеження, специфічні для моделі, і резерв токенів для compaction.
• Див. Системний prompt, щоб дізнатися, що бачить модель.

​

Точки hook (де можна втрутитися)

OpenClaw має дві системи hook:

• Внутрішні hooks (hooks Gateway): скрипти, керовані подіями, для команд і подій життєвого циклу.
• Hooks плагінів: точки розширення всередині життєвого циклу агента/інструментів і конвеєра шлюзу.

​

Внутрішні hooks (hooks Gateway)

• agent:bootstrap: запускається під час збирання bootstrap-файлів до фіналізації системного prompt. Використовуйте це, щоб додавати/видаляти bootstrap-файли контексту.
• Hooks команд: /new, /reset, /stop та інші події команд (див. документ про Hooks).

Налаштування й приклади див. у Hooks.

​

Hooks плагінів (життєвий цикл агента + шлюзу)

Вони запускаються всередині циклу агента або конвеєра шлюзу:

• before_model_resolve: запускається до сесії (без messages), щоб детерміновано перевизначити provider/model до визначення моделі.
• before_prompt_build: запускається після завантаження сесії (з messages), щоб впровадити prependContext, systemPrompt, prependSystemContext або appendSystemContext перед надсиланням prompt. Використовуйте prependContext для динамічного тексту на окремий хід, а поля системного контексту — для стабільних настанов, які мають розміщуватися в просторі системного prompt.
• before_agent_start: застарілий hook сумісності, який може запускатися в будь-якій фазі; віддавайте перевагу явним hooks вище.
• before_agent_reply: запускається після вбудованих дій і до виклику LLM, дозволяючи плагіну перехопити хід і повернути синтетичну відповідь або повністю заглушити хід.
• agent_end: перевіряє фінальний список повідомлень і метадані запуску після завершення.
• before_compaction / after_compaction: спостереження або анотування циклів compaction.
• before_tool_call / after_tool_call: перехоплення параметрів/результатів інструментів.
• before_install: перевірка вбудованих результатів сканування та, за потреби, блокування встановлення skill або плагіна.
• tool_result_persist: синхронно перетворює результати інструментів перед їх записом у транскрипт сесії.
• message_received / message_sending / message_sent: hooks для вхідних і вихідних повідомлень.
• session_start / session_end: межі життєвого циклу сесії.
• gateway_start / gateway_stop: події життєвого циклу шлюзу.

Правила рішень hooks для вихідних/інструментальних обмежень:

• before_tool_call: { block: true } є термінальним і зупиняє обробники з нижчим пріоритетом.
• before_tool_call: { block: false } нічого не робить і не скасовує попереднє блокування.
• before_install: { block: true } є термінальним і зупиняє обробники з нижчим пріоритетом.
• before_install: { block: false } нічого не робить і не скасовує попереднє блокування.
• message_sending: { cancel: true } є термінальним і зупиняє обробники з нижчим пріоритетом.
• message_sending: { cancel: false } нічого не робить і не скасовує попереднє скасування.

API hooks і подробиці реєстрації див. у Hooks плагінів.

​

Потокова передача і часткові відповіді

• deltas помічника передаються потоком із pi-agent-core і генеруються як події assistant.
• Потокова передача блоків може видавати часткові відповіді або на text_end, або на message_end.
• Потокова передача міркування може видаватися як окремий потік або як блокові відповіді.
• Поведінку розбиття на частини та блокових відповідей див. у Потокова передача.

​

Виконання інструментів і інструменти обміну повідомленнями

• Події початку/оновлення/завершення інструментів генеруються в потоці tool.
• Результати інструментів очищуються з урахуванням розміру та image payloads перед журналюванням/генерацією.
• Надсилання через інструменти обміну повідомленнями відстежується, щоб придушувати дубльовані підтвердження від помічника.

​

Формування відповіді і придушення

• Фінальні payloads збираються з:
  • тексту помічника (і необов’язково міркування)
  • вбудованих підсумків інструментів (коли verbose + дозволено)
  • тексту помилки помічника, коли модель завершується з помилкою
• Точний тихий токен NO_REPLY / no_reply відфільтровується з вихідних payloads.
• Дублікати від інструментів обміну повідомленнями видаляються з фінального списку payload.
• Якщо не залишається жодного payload, який можна відобразити, і інструмент завершився з помилкою, генерується резервна відповідь про помилку інструмента (якщо тільки інструмент обміну повідомленнями вже не надіслав видиму користувачеві відповідь).

​

Compaction і повторні спроби

• Автоматичний compaction генерує події потоку compaction і може спричинити повторну спробу.
• Під час повторної спроби буфери в пам’яті та підсумки інструментів скидаються, щоб уникнути дублювання виводу.
• Докладніше про конвеєр compaction див. у Compaction.

​

Потоки подій (сьогодні)

• lifecycle: генерується subscribeEmbeddedPiSession (і як резервний варіант через agentCommand)
• assistant: потокові deltas із pi-agent-core
• tool: потокові події інструментів із pi-agent-core

​

Обробка чат-каналів

• deltas помічника буферизуються в чат-повідомлення delta.
• Чат final генерується під час lifecycle end/error.

​

Тайм-аути

• Типове значення agent.wait: 30 с (лише очікування). Параметр timeoutMs перевизначає його.
• Час виконання агента: типове значення agents.defaults.timeoutSeconds — 172800 с (48 годин); застосовується в таймері переривання runEmbeddedPiAgent.

​

Де все може завершитися раніше

• Тайм-аут агента (переривання)
• AbortSignal (скасування)
• Роз’єднання Gateway або тайм-аут RPC
• Тайм-аут agent.wait (лише очікування, не зупиняє агента)

​

Пов’язане

• Інструменти — доступні інструменти агента
• Hooks — скрипти, керовані подіями, які запускаються подіями життєвого циклу агента
• Compaction — як узагальнюються довгі розмови
• Підтвердження exec — перевірки схвалення для команд shell
• Thinking — налаштування рівня thinking/reasoning