Цикл агента

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

Точки входу

• RPC Gateway: agent і agent.wait.
• CLI: openclaw agent.

Послідовність запуску

1. agent RPC перевіряє параметри, визначає сеанс (sessionKey/sessionId), зберігає метадані сеансу та негайно повертає { runId, acceptedAt }.
2. agentCommand виконує цикл обробки: визначає модель і типові значення мислення/докладності/трасування, завантажує знімок Skills, викликає runEmbeddedAgent і створює резервну подію завершення/помилки життєвого циклу, якщо вбудований цикл її ще не створив.
3. runEmbeddedAgent: серіалізує запуски через черги для кожного сеансу та глобальні черги, визначає модель і профіль автентифікації, створює сеанс OpenClaw, підписується на події середовища виконання, потоково передає зміни асистента/інструментів, забезпечує дотримання тайм-ауту запуску (перериваючи його після завершення часу) та повертає корисні навантаження разом із метаданими використання. Для циклів обробки сервера застосунку Codex він також перериває прийнятий цикл, який припинив створювати події поступу сервера застосунку до настання термінальної події.
4. subscribeEmbeddedAgentSession передає події середовища виконання в потік agent: події інструментів — у stream: "tool", зміни асистента — у stream: "assistant", події життєвого циклу — у stream: "lifecycle" (phase: "start" | "end" | "error").
5. agent.wait (waitForAgentRun) очікує завершення/помилки життєвого циклу в runId і повертає { status: ok|error|timeout, startedAt, endedAt, error? }.

Черги та паралельність

Запуски серіалізуються за ключем сеансу (лінія сеансу) і, за потреби, через глобальну лінію, що запобігає конфліктам інструментів/сеансів. Канали обміну повідомленнями вибирають режим черги (керування/продовження/збирання/переривання), який передає дані в цю систему ліній; див. Черга команд.

Запис транскрипту додатково захищено блокуванням запису сеансу для файла сеансу. Блокування враховує процеси й базується на файлах, тому виявляє записувачів, які оминають внутрішньопроцесну чергу або походять з іншого процесу. Записувачі очікують до session.writeLock.acquireTimeoutMs (типове значення — 60000 мс; перевизначення змінною середовища — OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS), перш ніж повідомити, що сеанс зайнятий.

За замовчуванням блокування запису сеансу не є повторно вхідними. Допоміжна функція, яка навмисно виконує вкладене отримання того самого блокування, зберігаючи одного логічного записувача, має явно дозволити це за допомогою allowReentrant: true.

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

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

Складання запиту

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

Перехоплювачі

OpenClaw має дві системи перехоплювачів:

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

Внутрішні перехоплювачі (перехоплювачі Gateway)

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

Налаштування та приклади див. у розділі Перехоплювачі.

Перехоплювачі Plugin

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

Правила ухвалення рішень перехоплювачами для захисту вихідних даних/інструментів:

• before_tool_call: { block: true } є термінальним і зупиняє обробники з нижчим пріоритетом. { block: false } не виконує жодних дій і не скасовує попереднє блокування.
• before_install: така сама термінальна семантика й семантика відсутності дії, як вище. Використовуйте security.installPolicy, а не before_install, для належних оператору рішень щодо дозволу/блокування встановлення, які мають охоплювати шляхи встановлення й оновлення через CLI.
• message_sending: { cancel: true } є термінальним і зупиняє обробники з нижчим пріоритетом. { cancel: false } не виконує жодних дій і не скасовує попереднє скасування.

API перехоплювачів і подробиці реєстрації див. у розділі Перехоплювачі Plugin.

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

Потокове передавання

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

Виконання інструментів

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

Формування відповіді

Остаточні корисні навантаження складаються з тексту асистента (разом із необов'язковими міркуваннями), вбудованих зведень інструментів (коли ввімкнено докладний режим і це дозволено) та тексту помилки асистента, якщо в моделі виникла помилка.

• Точний токен мовчання NO_REPLY відфільтровується з вихідних корисних навантажень.
• Дублікати інструмента обміну повідомленнями вилучаються з остаточного списку корисних навантажень.
• Якщо не залишилося придатних до відтворення корисних навантажень і в інструменті виникла помилка, створюється резервна відповідь про помилку інструмента, якщо інструмент обміну повідомленнями ще не надіслав видиму користувачеві відповідь.

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

Автоматичний Compaction створює події потоку compaction і може ініціювати повторну спробу. Під час повторної спроби буфери в пам'яті та зведення інструментів скидаються, щоб уникнути дублювання виведення. Див. Compaction.

Потоки подій

• lifecycle: створюється subscribeEmbeddedAgentSession (і як резервний варіант — agentCommand).
• assistant: потокові зміни із середовища виконання агента.
• tool: потокові події інструментів із середовища виконання агента.

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

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

Зміни асистента буферизуються в повідомленнях чату delta. Подія чату final створюється під час завершення/помилки життєвого циклу.

Тайм-аути

Діагностика завислих сеансів

Коли діагностику ввімкнено, diagnostics.stuckSessionWarnMs (типово 120000 ms) класифікує тривалі сеанси processing, у яких не спостерігається відповіді, виклику інструмента, стану, блокування або поступу ACP:

• Активні вбудовані запуски, виклики моделі та виклики інструментів позначаються як session.long_running. Керовані беззвучні виклики моделі залишаються session.long_running до diagnostics.stuckSessionAbortMs, щоб повільні провайдери або провайдери без потокового передавання не позначалися як завислі надто рано.
• Активна робота без нещодавнього поступу позначається як session.stalled. Керовані виклики моделі переходять у стан session.stalled після досягнення порога переривання; застаріла активність моделі або інструмента без власника не приховується як довготривала.
• session.stuck призначено для відновлюваних застарілих облікових даних сеансу, зокрема для неактивних сеансів у черзі із застарілою активністю моделі або інструмента без власника.

diagnostics.stuckSessionAbortMs типово становить щонайменше 5 хвилин і втричі перевищує поріг попередження. Застарілі облікові дані сеансу звільняють відповідний канал сеансу відразу після проходження перевірок відновлення; завислі вбудовані запуски перериваються з очікуванням завершення лише після досягнення порога переривання, тому робота в черзі відновлюється без припинення запусків, які лише виконуються повільно. Під час відновлення створюються структуровані результати запиту та завершення; діагностичний стан позначається як неактивний, лише якщо те саме покоління обробки все ще є поточним, а повторна діагностика session.stuck виконується дедалі рідше, доки сеанс залишається незмінним.

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

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

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

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