Цикл агента

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

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

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

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

Збирання промпта + системний промпт

• Системний промпт будується з базового промпта OpenClaw, промпта Skills, bootstrap-контексту та перевизначень на рівні запуску.
• Застосовуються специфічні для моделі ліміти та резерв токенів Compaction.
• Див. Системний промпт, щоб дізнатися, що бачить модель.

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

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

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

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

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

Див. Хуки для налаштування та прикладів.

Хуки 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 для API хуків і деталей реєстрації.

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

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

• Дельти асистента транслюються із середовища виконання агента та випускаються як події assistant.
• Блокова потокова передача може випускати часткові відповіді або на text_end, або на message_end.
• Потокова передача міркувань може випускатися як окремий потік або як блокові відповіді.
• Див. Потокова передача для поведінки фрагментації та блокових відповідей.

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

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

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

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

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

• Автоматична Compaction випускає події потоку compaction і може запускати повторну спробу.
• Під час повторної спроби буфери в пам’яті та підсумки інструментів скидаються, щоб уникнути дублювання вихідних даних.
• Див. 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.<id>.timeoutSeconds розширює цей сторож простою для повільних local loopback/самостійно розгорнутих провайдерів, але його все одно обмежує будь-яке нижче значення agents.defaults.timeoutSeconds або специфічний для запуску тайм-аут, оскільки вони керують усім запуском агента. Інакше OpenClaw використовує agents.defaults.timeoutSeconds, коли його налаштовано, з типовим обмеженням 120 с. Запуски хмарних моделей, ініційовані Cron, без явного тайм-ауту моделі або агента використовують той самий типовий сторож простою; з явним тайм-аутом запуску cron зависання потоків хмарної моделі обмежуються 60 с, щоб налаштовані резервні моделі могли виконатися до зовнішнього дедлайну cron. Запуски local loopback або самостійно розгорнутих моделей, ініційовані Cron, вимикають неявний сторож, якщо явний тайм-аут не налаштовано, а явні тайм-аути запуску cron залишаються вікном простою для local loopback/самостійно розгорнутих провайдерів, тому повільні локальні провайдери мають задавати models.providers.<id>.timeoutSeconds.
• Тайм-аут HTTP-запиту провайдера: models.providers.<id>.timeoutSeconds застосовується до HTTP-запитів моделі цього провайдера, включно з підключенням, заголовками, тілом, тайм-аутом запиту SDK, загальною обробкою переривання guarded-fetch і сторожем простою потоку моделі. Використовуйте це для повільних local loopback/самостійно розгорнутих провайдерів, таких як Ollama, перш ніж підвищувати тайм-аут усього середовища виконання агента, і тримайте тайм-аут агента/середовища виконання щонайменше таким самим високим, коли запиту моделі потрібно виконуватися довше.

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

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

Пов’язане

• Інструменти — доступні інструменти агента
• Хуки — сценарії, керовані подіями, що запускаються подіями життєвого циклу агента
• Compaction — як узагальнюються довгі розмови
• Схвалення Exec — шлюзи схвалення для команд оболонки
• Мислення — конфігурація рівня мислення/міркування