---
read_when:
    - Вам потрібен точний покроковий опис циклу агента або подій життєвого циклу
    - Ви змінюєте постановку сеансів у чергу, записи стенограми або поведінку блокування запису сеансу
summary: Життєвий цикл циклу агента, потоки та семантика очікування
title: Цикл агента
x-i18n:
    generated_at: "2026-05-02T13:59:23Z"
    model: gpt-5.5
    provider: openai
    source_hash: 39c49e8c5d1e380e0569e31856d855484d5a8fa33b04cf85cccde4c9ac21fbe7
    source_path: concepts/agent-loop.md
    workflow: 16
---

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

В 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
   - підписується на події pi та транслює дельти асистента/інструментів
   - примусово застосовує тайм-аут -> перериває запуск, якщо його перевищено
   - для ходів Codex app-server перериває прийнятий хід, який припинив створювати прогрес app-server до термінальної події
   - повертає 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), які подаються в цю систему доріжок.
  Див. [Черга команд](/uk/concepts/queue).
- Записи транскрипту також захищені блокуванням запису сеансу на файлі сеансу. Блокування
  враховує процеси й базується на файлі, тому воно ловить записувачів, які обходять внутрішньопроцесну чергу або приходять
  з іншого процесу. Записувачі транскрипту сеансу очікують до `session.writeLock.acquireTimeoutMs`
  перед тим як повідомити, що сеанс зайнятий; типове значення — `60000` мс.
- Блокування запису сеансу за замовчуванням не є реентерабельними. Якщо допоміжний засіб навмисно вкладає отримання
  того самого блокування, зберігаючи одного логічного записувача, він має явно увімкнути це за допомогою
  `allowReentrant: true`.

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

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

## Складання промпта + системний промпт

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

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

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

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

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

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

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

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

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

- **`before_model_resolve`**: виконується до сеансу (без `messages`), щоб детерміновано перевизначити provider/model до визначення моделі.
- **`before_prompt_build`**: виконується після завантаження сеансу (з `messages`), щоб інжектити `prependContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext` перед надсиланням промпта. Використовуйте `prependContext` для динамічного тексту на хід і поля системного контексту для стабільних настанов, які мають перебувати в просторі системного промпта.
- **`before_agent_start`**: застарілий хук сумісності, який може виконуватися в будь-якій фазі; віддавайте перевагу явним хукам вище.
- **`before_agent_reply`**: виконується після inline-дій і перед викликом LLM, даючи Plugin змогу забрати хід і повернути синтетичну відповідь або повністю приглушити хід.
- **`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](/uk/plugins/hooks) для API хуків і деталей реєстрації.

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

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

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

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

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

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

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

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

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

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

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

## Обробка каналу чату

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

## Тайм-аути

- Типове значення `agent.wait`: 30 с (лише очікування). Параметр `timeoutMs` перевизначає.
- Час виконання агента: типове значення `agents.defaults.timeoutSeconds` — 172800 с (48 годин); застосовується таймером переривання в `runEmbeddedPiAgent`.
- Час виконання Cron: ізольований агентний хід `timeoutSeconds` належить cron. Планувальник запускає цей таймер, коли починається виконання, перериває базовий запуск у налаштований дедлайн, а потім виконує обмежене очищення перед записом тайм-ауту, щоб застарілий дочірній сеанс не міг утримувати доріжку заблокованою.
- Діагностика активності сеансу: коли діагностику ввімкнено, `diagnostics.stuckSessionWarnMs` класифікує довгі сеанси `processing`, які не мають спостережуваної відповіді, інструмента, статусу, блока або прогресу ACP. Активні вбудовані запуски, виклики моделі та виклики інструментів повідомляються як `session.long_running`; активна робота без нещодавнього прогресу повідомляється як `session.stalled`; `session.stuck` зарезервовано для застарілого обліку сеансів без активної роботи, і лише цей шлях звільняє відповідну доріжку сеансу, щоб робота запуску в черзі могла продовжитися. Повторні діагностики `session.stuck` відступають, доки сеанс залишається незмінним.
- Тайм-аут простою моделі: OpenClaw перериває запит до моделі, коли до завершення вікна простою не надходять фрагменти відповіді. `models.providers.<id>.timeoutSeconds` розширює цей idle watchdog для повільних local/self-hosted провайдерів; інакше OpenClaw використовує `agents.defaults.timeoutSeconds`, коли його налаштовано, з типовим обмеженням 120 с. Запуски, викликані Cron, без явного тайм-ауту моделі або агента вимикають idle watchdog і покладаються на зовнішній тайм-аут cron.
- Тайм-аут HTTP-запиту провайдера: `models.providers.<id>.timeoutSeconds` застосовується до HTTP fetch-ів моделі цього провайдера, включно з підключенням, заголовками, тілом, тайм-аутом SDK-запиту, загальною обробкою переривання guarded-fetch і idle watchdog потоку моделі. Використовуйте це для повільних local/self-hosted провайдерів, як-от Ollama, перед підвищенням тайм-ауту всього часу виконання агента.

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

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

## Пов’язане

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