--- read_when: - Вам потрібен точний покроковий опис циклу агента або подій життєвого циклу - Ви змінюєте постановку сеансів у чергу, записи транскриптів або поведінку блокування запису сеансу summary: Життєвий цикл циклу агента, потоки та семантика очікування title: Цикл агента x-i18n: generated_at: "2026-06-27T17:24:14Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 1ccfdf4a3ea6b9c946064f051e32c88cefbcb707c7426abe85b04294030eedaf 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 - викликає `runEmbeddedAgent` (середовище виконання агента OpenClaw) - випускає **завершення/помилку життєвого циклу**, якщо вбудований цикл цього не зробив 3. `runEmbeddedAgent`: - серіалізує запуски через черги на рівні сесії та глобальні черги - визначає модель і профіль автентифікації та будує сесію OpenClaw - підписується на події середовища виконання та транслює дельти асистента/інструментів - застосовує тайм-аут -> перериває запуск, якщо його перевищено - для ходів сервера застосунку Codex перериває прийнятий хід, який перестає створювати прогрес сервера застосунку до термінальної події - повертає корисні навантаження й метадані використання 4. `subscribeEmbeddedAgentSession` зв’язує події середовища виконання агента з потоком OpenClaw `agent`: - події інструментів => `stream: "tool"` - дельти асистента => `stream: "assistant"` - події життєвого циклу => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`) 5. `agent.wait` використовує `waitForAgentRun`: - чекає **завершення/помилки життєвого циклу** для `runId` - повертає `{ status: ok|error|timeout, startedAt, endedAt, error? }` ## Черги + конкурентність - Запуски серіалізуються за ключем сесії (смуга сесії) і за потреби через глобальну смугу. - Це запобігає гонкам інструментів/сесій і зберігає узгоджену історію сесії. - Канали повідомлень можуть вибирати режими черги (steer/followup/collect/interrupt), які подаються в цю систему смуг. Див. [Черга команд](/uk/concepts/queue). - Записи стенограми також захищені блокуванням запису сесії на файлі сесії. Блокування враховує процеси й базується на файлі, тому воно виявляє записувачів, які обходять внутрішньопроцесну чергу або приходять з іншого процесу. Записувачі стенограми сесії чекають до `session.writeLock.acquireTimeoutMs`, перш ніж повідомити, що сесія зайнята; типове значення — `60000` мс. - Блокування запису сесії за замовчуванням не є реентерабельними. Якщо допоміжний компонент навмисно вкладає отримання того самого блокування, зберігаючи одного логічного записувача, він має явно увімкнути це через `allowReentrant: true`. ## Підготовка сесії + робочого простору - Робочий простір визначається та створюється; ізольовані запуски можуть перенаправлятися до кореня ізольованого робочого простору. - 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`), щоб детерміновано перевизначити провайдера/модель перед визначенням моделі. - **`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 після виконання операторської політики встановлення, коли хуки Plugin завантажені в поточному процесі OpenClaw. - **`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 }` нічого не робить і не скасовує попереднє блокування. - Використовуйте `security.installPolicy`, а не `before_install`, для операторських рішень дозволу/блокування встановлення, які мають покривати шляхи встановлення й оновлення CLI. - `message_sending`: `{ cancel: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. - `message_sending`: `{ cancel: false }` нічого не робить і не скасовує попереднє скасування. Див. [Хуки Plugin](/uk/plugins/hooks) для API хуків і деталей реєстрації. Обв’язки можуть адаптувати ці хуки інакше. Обв’язка сервера застосунку Codex зберігає хуки Plugin OpenClaw як контракт сумісності для документованих дзеркальних поверхонь, тоді як нативні хуки Codex залишаються окремим низькорівневим механізмом Codex. ## Потокова передача + часткові відповіді - Дельти асистента транслюються із середовища виконання агента та випускаються як події `assistant`. - Блокова потокова передача може випускати часткові відповіді або на `text_end`, або на `message_end`. - Потокова передача міркувань може випускатися як окремий потік або як блокові відповіді. - Див. [Потокова передача](/uk/concepts/streaming) для поведінки фрагментації та блокових відповідей. ## Виконання інструментів + інструменти повідомлень - Події запуску/оновлення/завершення інструментів випускаються в потоці `tool`. - Результати інструментів очищуються за розміром і графічними корисними навантаженнями перед логуванням/випуском. - Надсилання інструментів повідомлень відстежуються, щоб придушувати дублікати підтверджень асистента. ## Формування відповіді + придушення - Фінальні корисні навантаження збираються з: - тексту асистента (і необов’язкових міркувань) - inline-підсумків інструментів (коли verbose + дозволено) - тексту помилки асистента, коли модель помиляється - Точний мовчазний токен `NO_REPLY` / `no_reply` фільтрується з вихідних корисних навантажень. - Дублікати інструментів повідомлень видаляються з фінального списку корисних навантажень. - Якщо не лишається жодного придатного до рендерингу корисного навантаження й інструмент завершився помилкою, випускається резервна відповідь про помилку інструмента (якщо інструмент повідомлень уже не надіслав видиму користувачу відповідь). ## Compaction + повторні спроби - Автоматична Compaction випускає події потоку `compaction` і може запускати повторну спробу. - Під час повторної спроби буфери в пам’яті та підсумки інструментів скидаються, щоб уникнути дублювання вихідних даних. - Див. [Compaction](/uk/concepts/compaction) для конвеєра Compaction. ## Потоки подій (сьогодні) - `lifecycle`: випускається `subscribeEmbeddedAgentSession` (і як резервний варіант — `agentCommand`) - `assistant`: потокові дельти із середовища виконання агента - `tool`: потокові події інструментів із середовища виконання агента ## Обробка чат-каналів - Дельти асистента буферизуються в чат-повідомлення `delta`. - Чат `final` випускається на **завершенні/помилці життєвого циклу**. ## Тайм-аути - Типове значення `agent.wait`: 30 с (лише очікування). Параметр `timeoutMs` перевизначає його. - Середовище виконання агента: типове значення `agents.defaults.timeoutSeconds` — 172800 с (48 годин); застосовується таймером переривання в `runEmbeddedAgent`. - Середовище виконання Cron: ізольований `timeoutSeconds` для ходу агента належить cron. Планувальник запускає цей таймер, коли починається виконання, перериває базовий запуск у налаштований граничний момент, а потім виконує обмежене очищення перед записом тайм-ауту, щоб застаріла дочірня сесія не могла залишити смугу заблокованою. - Діагностика життєздатності сесії: коли діагностику ввімкнено, `diagnostics.stuckSessionWarnMs` класифікує довгі сесії `processing`, у яких не спостерігається прогресу відповіді, інструмента, статусу, блока або ACP. Активні вбудовані запуски, виклики моделей і виклики інструментів повідомляються як `session.long_running`; власні мовчазні виклики моделей також залишаються `session.long_running` до `diagnostics.stuckSessionAbortMs`, щоб повільні або непотокові провайдери не повідомлялися як зупинені надто рано. Активна робота без недавнього прогресу повідомляється як `session.stalled`; власні виклики моделей перемикаються на `session.stalled` на порозі переривання або після нього, а застаріла активність моделей/інструментів без власника не приховується як довготривала. `session.stuck` зарезервовано для відновлюваного застарілого обліку сесій, зокрема неактивних сесій у черзі із застарілою активністю моделей/інструментів без власника. Застарілий облік сесій звільняє відповідну смугу сесії одразу після проходження шлюзів відновлення; зупинені вбудовані запуски перериваються й осушуються лише після `diagnostics.stuckSessionAbortMs` (типово: щонайменше 5 хвилин і 3x порога попередження), щоб робота в черзі могла продовжитися без обривання просто повільних запусків. Відновлення випускає структуровані запитані/завершені результати, а діагностичний стан позначається як неактивний лише якщо те саме покоління обробки все ще актуальне. Повторні діагностики `session.stuck` застосовують backoff, поки сесія лишається незмінною. - Тайм-аут простою моделі: OpenClaw перериває запит до моделі, коли до завершення вікна простою не надходять фрагменти відповіді. `models.providers..timeoutSeconds` розширює цей сторож простою для повільних local loopback/самостійно розгорнутих провайдерів, але його все одно обмежує будь-яке нижче значення `agents.defaults.timeoutSeconds` або специфічний для запуску тайм-аут, оскільки вони керують усім запуском агента. Інакше OpenClaw використовує `agents.defaults.timeoutSeconds`, коли його налаштовано, з типовим обмеженням 120 с. Запуски хмарних моделей, ініційовані Cron, без явного тайм-ауту моделі або агента використовують той самий типовий сторож простою; з явним тайм-аутом запуску cron зависання потоків хмарної моделі обмежуються 60 с, щоб налаштовані резервні моделі могли виконатися до зовнішнього дедлайну cron. Запуски local loopback або самостійно розгорнутих моделей, ініційовані Cron, вимикають неявний сторож, якщо явний тайм-аут не налаштовано, а явні тайм-аути запуску cron залишаються вікном простою для local loopback/самостійно розгорнутих провайдерів, тому повільні локальні провайдери мають задавати `models.providers..timeoutSeconds`. - Тайм-аут HTTP-запиту провайдера: `models.providers..timeoutSeconds` застосовується до HTTP-запитів моделі цього провайдера, включно з підключенням, заголовками, тілом, тайм-аутом запиту SDK, загальною обробкою переривання guarded-fetch і сторожем простою потоку моделі. Використовуйте це для повільних local loopback/самостійно розгорнутих провайдерів, таких як Ollama, перш ніж підвищувати тайм-аут усього середовища виконання агента, і тримайте тайм-аут агента/середовища виконання щонайменше таким самим високим, коли запиту моделі потрібно виконуватися довше. ## Де все може завершитися рано - Тайм-аут агента (переривання) - AbortSignal (скасування) - Від’єднання Gateway або тайм-аут RPC - Тайм-аут `agent.wait` (лише очікування, не зупиняє агента) ## Пов’язане - [Інструменти](/uk/tools) — доступні інструменти агента - [Хуки](/uk/automation/hooks) — сценарії, керовані подіями, що запускаються подіями життєвого циклу агента - [Compaction](/uk/concepts/compaction) — як узагальнюються довгі розмови - [Схвалення Exec](/uk/tools/exec-approvals) — шлюзи схвалення для команд оболонки - [Мислення](/uk/tools/thinking) — конфігурація рівня мислення/міркування