---
read_when:
    - Вам потрібен точний покроковий опис циклу агента або подій життєвого циклу
summary: Життєвий цикл циклу агента, потоки та семантика очікування
title: Цикл агента
x-i18n:
    generated_at: "2026-04-12T18:22:00Z"
    model: gpt-5.4
    provider: openai
    source_hash: 3c2986708b444055340e0c91b8fce7d32225fcccf3d197b797665fd36b1991a5
    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
   - завантажує знімок 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), які подаються в цю систему доріжок.
  Див. [Черга команд](/uk/concepts/queue).

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

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

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

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

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

OpenClaw має дві системи хуків:

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

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

- **`agent:bootstrap`**: запускається під час побудови bootstrap-файлів до того, як буде фіналізовано системний prompt.
  Використовуйте це, щоб додавати/видаляти bootstrap-файли контексту.
- **Хуки команд**: `/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` для динамічного тексту на кожен хід, а поля системного контексту — для стабільних вказівок, які мають перебувати в просторі системного 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](/uk/plugins/architecture#provider-runtime-hooks), щоб переглянути API хуків і деталі реєстрації.

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

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

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

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

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

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

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

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

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

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