Перейти до основного вмісту

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

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

​
Точки входу

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

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

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

​
Підготовка сесії + робочого простору

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

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

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

​
Точки перехоплення (де можна втрутитися)

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

​
Внутрішні хуки (хуки Gateway)

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

​
Plugin hooks (життєвий цикл агента + gateway)

Вони запускаються всередині циклу агента або конвеєра gateway:
  • before_model_resolve: запускається до сесії (без messages), щоб детерміновано перевизначити provider/model до визначення моделі.
  • before_prompt_build: запускається після завантаження сесії (з messages), щоб впровадити prependContext, systemPrompt, prependSystemContext або appendSystemContext до надсилання prompt. Використовуйте prependContext для динамічного тексту на кожен хід, а поля системного контексту — для стабільних вказівок, які мають перебувати в просторі системного prompt.
  • before_agent_start: застарілий хук сумісності, який може запускатися в будь-якій фазі; віддавайте перевагу наведеним вище явним хукам.
  • before_agent_reply: запускається після вбудованих дій і перед викликом LLM, дозволяючи Plugin перехопити хід і повернути синтетичну відповідь або повністю приглушити хід.
  • agent_end: дає змогу перевірити фінальний список повідомлень і метадані запуску після завершення.
  • before_compaction / after_compaction: дає змогу спостерігати або анотувати цикли Compaction.
  • before_tool_call / after_tool_call: перехоплює параметри/результати інструментів.
  • before_install: дає змогу перевірити результати вбудованого сканування й за потреби заблокувати встановлення Skill або Plugin.
  • tool_result_persist: синхронно трансформує результати інструментів перед тим, як вони будуть записані до транскрипту сесії.
  • message_received / message_sending / message_sent: вхідні та вихідні хуки повідомлень.
  • session_start / session_end: межі життєвого циклу сесії.
  • gateway_start / gateway_stop: події життєвого циклу gateway.
Правила рішень хуків для вихідних даних/запобіжників інструментів:
  • 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 } не виконує жодної дії та не скасовує попереднє скасування.
Див. Plugin hooks, щоб переглянути API хуків і деталі реєстрації.

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

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

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

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

​
Формування відповіді + пригнічення

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

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

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

​
Потоки подій (зараз)

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

​
Обробка чат-каналу

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

​
Тайм-аути

  • Типове значення agent.wait: 30 с (лише очікування). Параметр timeoutMs його перевизначає.
  • Час виконання агента: типове значення agents.defaults.timeoutSeconds — 172800 с (48 годин); застосовується в таймері переривання runEmbeddedPiAgent.
  • Тайм-аут бездіяльності LLM: agents.defaults.llm.idleTimeoutSeconds перериває запит до моделі, якщо жодні фрагменти відповіді не надходять до завершення вікна бездіяльності. Установіть його явно для повільних локальних моделей або provider-ів reasoning/tool-call; установіть 0, щоб вимкнути. Якщо його не задано, OpenClaw використовує agents.defaults.timeoutSeconds, якщо його налаштовано, інакше 120 с. Запуски, ініційовані Cron, без явного тайм-ауту LLM або агента вимикають watchdog бездіяльності й покладаються на зовнішній тайм-аут Cron.

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

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

​
Пов’язані теми

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