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

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

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

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

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

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

1. RPC `agent` валідує параметри, визначає сесію (sessionKey/sessionId), зберігає метадані сесії та одразу повертає `{ runId, acceptedAt }`.
2. `agentCommand` запускає агента:
   - визначає модель + типові значення thinking/verbose/trace
   - завантажує знімок Skills
   - викликає `runEmbeddedPiAgent` (середовище виконання pi-agent-core)
   - генерує **lifecycle end/error**, якщо вбудований цикл сам цього не згенерував
3. `runEmbeddedPiAgent`:
   - серіалізує запуски через черги на рівні сесії та глобальні черги
   - визначає модель + профіль автентифікації та будує pi session
   - підписується на події pi і потоково передає дельти асистента/інструментів
   - застосовує timeout -> перериває запуск, якщо його перевищено
   - повертає payload-и та метадані використання
4. `subscribeEmbeddedPiSession` з’єднує події pi-agent-core з потоком OpenClaw `agent`:
   - події інструментів => `stream: "tool"`
   - дельти асистента => `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).
- Записи транскрипту також захищені блокуванням запису сесії на файлі сесії. Це блокування
  враховує процеси та базується на файлі, тому виявляє записувачів, які обходять внутрішньопроцесну чергу або походять
  з іншого процесу.
- Блокування запису сесії за замовчуванням не є реентерабельними. Якщо допоміжний код навмисно вкладає отримання
  того самого блокування, зберігаючи одного логічного записувача, він має явно ввімкнути це через
  `allowReentrant: true`.

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

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

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

- Системний prompt будується з базового prompt OpenClaw, prompt для Skills, bootstrap-контексту та перевизначень для конкретного запуску.
- Застосовуються специфічні для моделі обмеження та резерв токенів для Compaction.
- Див. [System 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, дозволяючи плагіну перехопити хід і повернути синтетичну відповідь або повністю приглушити хід.
- **`agent_end`**: дає змогу перевірити фінальний список повідомлень і метадані запуску після завершення.
- **`before_compaction` / `after_compaction`**: дають змогу спостерігати або анотувати цикли Compaction.
- **`before_tool_call` / `after_tool_call`**: перехоплюють параметри/результати інструментів.
- **`before_install`**: дає змогу перевірити вбудовані результати сканування та за потреби заблокувати встановлення skill або plugin.
- **`tool_result_persist`**: синхронно трансформує результати інструментів перед тим, як вони будуть записані в транскрипт сесії, що належить OpenClaw.
- **`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/hooks), щоб переглянути API хуків і подробиці реєстрації.

Harness-оточення можуть адаптувати ці хуки по-різному. Harness app-server у Codex зберігає
Plugin hooks OpenClaw як контракт сумісності для документованих дзеркальних
поверхонь, тоді як нативні хуки Codex залишаються окремим низькорівневим механізмом Codex.

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

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

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

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

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

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

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

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

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

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

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

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

## Тайм-аути

- Типове значення `agent.wait`: 30s (лише очікування). Його перевизначає параметр `timeoutMs`.
- Час виконання агента: типове значення `agents.defaults.timeoutSeconds` — 172800s (48 годин); застосовується в таймері переривання `runEmbeddedPiAgent`.
- Тайм-аут бездіяльності моделі: OpenClaw перериває запит моделі, якщо до завершення вікна бездіяльності не надходять фрагменти відповіді. `models.providers.<id>.timeoutSeconds` подовжує цей сторож бездіяльності для повільних локальних/self-hosted provider-ів; інакше OpenClaw використовує `agents.defaults.timeoutSeconds`, якщо його налаштовано, з обмеженням 120s за замовчуванням. Запуски, ініційовані Cron, без явного тайм-ауту моделі чи агента вимикають сторож бездіяльності й покладаються на зовнішній тайм-аут Cron.
- Тайм-аут HTTP-запиту provider-а: `models.providers.<id>.timeoutSeconds` застосовується до HTTP fetch-запитів моделі цього provider-а, зокрема до з’єднання, заголовків, тіла, тайм-ауту запиту SDK, обробки переривання guarded-fetch за загальним тайм-аутом і сторожа бездіяльності потоку моделі. Використовуйте це для повільних локальних/self-hosted provider-ів, таких як Ollama, перш ніж збільшувати тайм-аут усього часу виконання агента.

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

- Тайм-аут агента (переривання)
- 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/міркувань
