---
read_when:
    - Вам потрібен точний покроковий опис циклу агента або подій життєвого циклу
    - Ви змінюєте постановку сесій у чергу, записи transcript або поведінку блокування запису сесії
summary: Життєвий цикл циклу агента, потоки та семантика очікування
title: Цикл агента
x-i18n:
    generated_at: "2026-04-23T20:49:10Z"
    model: gpt-5.4
    provider: openai
    source_hash: 849a0737185cb9e26cc4815ac05fee28d2495676579832eeb09d79459d989152
    source_path: concepts/agent-loop.md
    workflow: 15
---

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

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

В OpenClaw цикл — це один серіалізований запуск на сесію, який надсилає події життєвого циклу та потокові події,
коли модель міркує, викликає інструменти й передає вивід потоком. У цьому документі пояснюється, як цей автентичний цикл
підключений наскрізно.

## Точки входу

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

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

1. RPC `agent` перевіряє параметри, визначає сесію (sessionKey/sessionId), зберігає метадані сесії та одразу повертає `{ runId, acceptedAt }`.
2. `agentCommand` запускає агента:
   - визначає типові значення model + thinking/verbose/trace
   - завантажує snapshot Skills
   - викликає `runEmbeddedPiAgent` (runtime pi-agent-core)
   - надсилає **lifecycle end/error**, якщо вбудований цикл не надіслав таку подію сам
3. `runEmbeddedPiAgent`:
   - серіалізує запуски через черги на рівні сесії та глобальні черги
   - визначає profile моделі + auth і будує сесію Pi
   - підписується на події Pi та передає assistant/tool deltas потоком
   - застосовує timeout -> перериває запуск, якщо його перевищено
   - повертає payload і метадані 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), які подаються в цю систему доріжок.
  Див. [Command Queue](/uk/concepts/queue).
- Записи transcript також захищені блокуванням запису сесії на файлі сесії. Блокування
  враховує процес і базується на файлі, тому перехоплює записувачів, які обходять внутрішньопроцесну чергу або надходять
  з іншого процесу.
- Блокування запису сесії типово не є реентрантними. Якщо допоміжний засіб навмисно вкладає захоплення
  того самого блокування, зберігаючи одного логічного записувача, він має явно ввімкнути це через
  `allowReentrant: true`.

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

- Робочий простір визначається та створюється; ізольовані запуски можуть перенаправлятися до кореня sandbox-робочого простору.
- Skills завантажуються (або повторно використовуються зі snapshot) і впроваджуються в env та prompt.
- Bootstrap/context-файли визначаються та впроваджуються в report системного prompt.
- Захоплюється блокування запису сесії; `SessionManager` відкривається й готується перед початком streaming. Будь-який
  пізніший шлях перезапису transcript, Compaction або truncation має захоплювати те саме блокування перед відкриттям чи
  зміною файла transcript.

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

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

## Точки hooks (де можна перехопити)

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

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

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

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

Див. [Hooks](/uk/automation/hooks) для налаштування та прикладів.

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

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

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

Правила прийняття рішень 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 }` нічого не робить і не скасовує попереднє скасування.

Див. [Plugin hooks](/uk/plugins/architecture#provider-runtime-hooks) для API hooks і деталей реєстрації.

## Streaming + часткові відповіді

- Assistant deltas передаються потоком із pi-agent-core і надсилаються як події `assistant`.
- Block streaming може надсилати часткові відповіді або на `text_end`, або на `message_end`.
- Потоковий reasoning може надсилатися як окремий потік або як block-відповіді.
- Див. [Streaming](/uk/concepts/streaming) щодо chunking і поведінки block reply.

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

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

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

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

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

- Автоматична Compaction надсилає події потоку `compaction` і може ініціювати повторну спробу.
- Під час повторної спроби буфери в пам’яті й зведення інструментів скидаються, щоб уникнути дубльованого виводу.
- Див. [Compaction](/uk/concepts/compaction) щодо конвеєра Compaction.

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

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

## Обробка chat-каналу

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

## Тайм-аути

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

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

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

## Пов’язане

- [Tools](/uk/tools) — доступні інструменти агента
- [Hooks](/uk/automation/hooks) — скрипти, що запускаються за подіями життєвого циклу агента
- [Compaction](/uk/concepts/compaction) — як узагальнюються довгі розмови
- [Exec Approvals](/uk/tools/exec-approvals) — погодження для shell-команд
- [Thinking](/uk/tools/thinking) — налаштування рівня thinking/reasoning
