From 69aa85de326ed9cc8409ee09f840ecccb95bda62 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 30 Apr 2026 18:27:29 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/concepts/agent-loop.md | 195 +++++++++++++++++---------------- docs/uk/concepts/queue.md | 103 ++++++++--------- 2 files changed, 150 insertions(+), 148 deletions(-) diff --git a/docs/uk/concepts/agent-loop.md b/docs/uk/concepts/agent-loop.md index 97a015b97..42c8d14a6 100644 --- a/docs/uk/concepts/agent-loop.md +++ b/docs/uk/concepts/agent-loop.md @@ -1,178 +1,179 @@ --- read_when: - Вам потрібен точний покроковий опис циклу агента або подій життєвого циклу - - Ви змінюєте постановку сеансів у чергу, операції запису транскриптів або поведінку блокування запису сеансу + - Ви змінюєте постановку сеансів у чергу, записи транскриптів або поведінку блокування запису сеансу summary: Життєвий цикл циклу агента, потоки та семантика очікування title: Цикл агента x-i18n: - generated_at: "2026-04-29T15:58:15Z" + generated_at: "2026-04-30T18:26:41Z" model: gpt-5.5 provider: openai - source_hash: 902d543bd71dd517a810d825cbe92e244fe89230f47eeada72477c657a2bec32 + source_hash: 5466893253e1f82482284ff82db56f4c3fca018bf12e4114fad76d37cad954df source_path: concepts/agent-loop.md workflow: 16 --- -Агентний цикл — це повний «реальний» запуск агента: приймання → збирання контексту → інференс моделі → -виконання інструментів → потокові відповіді → збереження. Це авторитетний шлях, який перетворює повідомлення +Агентний цикл — це повний “справжній” запуск агента: приймання → збирання контексту → інференс моделі → +виконання інструментів → потокові відповіді → збереження. Це канонічний шлях, який перетворює повідомлення на дії та фінальну відповідь, водночас підтримуючи узгоджений стан сесії. -В OpenClaw цикл — це один серіалізований запуск на сесію, який видає події життєвого циклу та потоку, -поки модель думає, викликає інструменти й транслює вивід. У цьому документі пояснено, як цей справжній цикл -зв’язаний наскрізно. +В OpenClaw цикл — це один серіалізований запуск на сесію, який випускає події життєвого циклу та потоку, +поки модель думає, викликає інструменти й потоково передає вивід. У цьому документі пояснено, як цей автентичний цикл +з’єднано від початку до кінця. ## Точки входу -- Gateway RPC: `agent` і `agent.wait`. +- RPC Gateway: `agent` і `agent.wait`. - CLI: команда `agent`. ## Як це працює (на високому рівні) -1. `agent` RPC перевіряє параметри, визначає сесію (sessionKey/sessionId), зберігає метадані сесії, негайно повертає `{ runId, acceptedAt }`. +1. RPC `agent` перевіряє параметри, визначає сесію (sessionKey/sessionId), зберігає метадані сесії та негайно повертає `{ runId, acceptedAt }`. 2. `agentCommand` запускає агента: - - визначає модель + типові значення thinking/verbose/trace + - визначає типові значення моделі + thinking/verbose/trace - завантажує знімок Skills - викликає `runEmbeddedPiAgent` (середовище виконання pi-agent-core) - - видає **lifecycle end/error**, якщо вбудований цикл цього не видає + - випускає **кінець/помилку життєвого циклу**, якщо вбудований цикл не випускає таку подію 3. `runEmbeddedPiAgent`: - - серіалізує запуски через черги на рівні сесії та глобальні черги - - визначає модель + профіль автентифікації та будує сесію pi - - підписується на події pi і транслює дельти assistant/tool - - застосовує тайм-аут -> перериває запуск у разі перевищення - - повертає payload-и + метадані використання -4. `subscribeEmbeddedPiSession` зв’язує події pi-agent-core з потоком OpenClaw `agent`: + - серіалізує запуски через черги для кожної сесії + глобальні черги + - визначає модель + профіль авторизації та створює сесію pi + - підписується на події pi й потоково передає дельти асистента/інструментів + - застосовує тайм-аут -> перериває запуск, якщо його перевищено + - для ходів сервера застосунку Codex перериває прийнятий хід, який припиняє створювати прогрес сервера застосунку до термінальної події + - повертає корисні навантаження + метадані використання +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` + - очікує на **кінець/помилку життєвого циклу** для `runId` - повертає `{ status: ok|error|timeout, startedAt, endedAt, error? }` -## Черги + паралельність +## Постановка в чергу + конкурентність -- Запуски серіалізуються за ключем сесії (сесійна смуга) і, за потреби, через глобальну смугу. -- Це запобігає гонкам інструментів/сесії та підтримує узгоджену історію сесії. -- Канали повідомлень можуть вибирати режими черги (collect/steer/followup), які подаються в цю систему смуг. +- Запуски серіалізуються за ключем сесії (лінія сесії) і, за потреби, через глобальну лінію. +- Це запобігає гонкам інструментів/сесій і зберігає узгодженість історії сесії. +- Канали обміну повідомленнями можуть вибирати режими черги (collect/steer/followup), які подають роботу в цю систему ліній. Див. [Черга команд](/uk/concepts/queue). -- Записи транскрипту також захищені сесійним блокуванням запису у файл сесії. Блокування - враховує процеси та базується на файлах, тому воно виявляє записувачів, які обходять внутрішньопроцесну чергу або надходять +- Записи транскрипту також захищені блокуванням запису сесії на файлі сесії. Блокування + враховує процеси та базується на файлі, тож виявляє авторів запису, які обходять внутрішньопроцесну чергу або надходять з іншого процесу. -- Сесійні блокування запису за замовчуванням не є реентерабельними. Якщо допоміжний компонент навмисно вкладає отримання - того самого блокування, зберігаючи одного логічного записувача, він має явно ввімкнути це через +- Блокування запису сесії за замовчуванням не є реентерабельними. Якщо допоміжна функція навмисно вкладає отримання + того самого блокування, зберігаючи одного логічного автора запису, вона має явно ввімкнути це через `allowReentrant: true`. ## Підготовка сесії + робочої області -- Робоча область визначається та створюється; запуски в sandbox можуть перенаправлятися до кореня робочої області sandbox. -- Skills завантажуються (або повторно використовуються зі знімка) та впроваджуються в env і prompt. -- Bootstrap/context файли визначаються та впроваджуються у звіт системного prompt. -- Отримується сесійне блокування запису; `SessionManager` відкривається та готується перед потоковою передачею. Будь-який - подальший шлях перезапису транскрипту, Compaction або обрізання має отримати те саме блокування перед відкриттям або - зміною файлу транскрипту. +- Робоча область визначається та створюється; запуски в пісочниці можуть переспрямовуватися до кореня робочої області пісочниці. +- Skills завантажуються (або повторно використовуються зі знімка) та ін’єктуються в середовище й промпт. +- Файли початкового завантаження/контексту визначаються та ін’єктуються у звіт системного промпта. +- Отримується блокування запису сесії; `SessionManager` відкривається та готується до початку потокової передачі. Будь-який + подальший шлях переписування транскрипту, Compaction або скорочення має отримати те саме блокування перед відкриттям або + зміненням файлу транскрипту. -## Збирання prompt + системний prompt +## Збирання промпта + системний промпт -- Системний prompt будується з базового prompt OpenClaw, prompt Skills, bootstrap-контексту та перевизначень для окремого запуску. -- Застосовуються обмеження, специфічні для моделі, і резерв токенів для Compaction. -- Див. [Системний prompt](/uk/concepts/system-prompt), щоб дізнатися, що бачить модель. +- Системний промпт будується з базового промпта OpenClaw, промпта Skills, контексту початкового завантаження та перевизначень для конкретного запуску. +- Застосовуються специфічні для моделі обмеження та резерв токенів для Compaction. +- Див. [Системний промпт](/uk/concepts/system-prompt), щоб дізнатися, що бачить модель. -## Точки hook (де можна перехопити) +## Точки хуків (де можна перехоплювати) -OpenClaw має дві системи hook: +OpenClaw має дві системи хуків: -- **Внутрішні hooks** (Gateway hooks): скрипти, керовані подіями, для команд і подій життєвого циклу. -- **Plugin hooks**: точки розширення всередині життєвого циклу агента/інструментів і конвеєра gateway. +- **Внутрішні хуки** (хуки Gateway): подієво-керовані скрипти для команд і подій життєвого циклу. +- **Хуки Plugin**: точки розширення всередині життєвого циклу агента/інструментів і конвеєра gateway. -### Внутрішні hooks (Gateway hooks) +### Внутрішні хуки (хуки Gateway) -- **`agent:bootstrap`**: запускається під час побудови bootstrap-файлів до фіналізації системного prompt. - Використовуйте це, щоб додавати/видаляти файли bootstrap-контексту. -- **Command hooks**: `/new`, `/reset`, `/stop` та інші події команд (див. документ Hooks). +- **`agent:bootstrap`**: запускається під час створення файлів початкового завантаження до фіналізації системного промпта. + Використовуйте це, щоб додавати/видаляти файли контексту початкового завантаження. +- **Хуки команд**: `/new`, `/reset`, `/stop` та інші події команд (див. документ про хуки). -Див. [Hooks](/uk/automation/hooks) для налаштування та прикладів. +Див. [Хуки](/uk/automation/hooks) для налаштування та прикладів. -### Plugin hooks (життєвий цикл агента + gateway) +### Хуки Plugin (життєвий цикл агента + gateway) Вони виконуються всередині циклу агента або конвеєра gateway: -- **`before_model_resolve`**: виконується до сесії (без `messages`), щоб детерміновано перевизначити provider/model перед визначенням моделі. -- **`before_prompt_build`**: виконується після завантаження сесії (з `messages`), щоб впровадити `prependContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext` перед надсиланням prompt. Використовуйте `prependContext` для динамічного тексту на окремий хід, а поля системного контексту — для стабільних вказівок, які мають перебувати в просторі системного prompt. -- **`before_agent_start`**: застарілий hook сумісності, який може виконуватися в будь-якій фазі; віддавайте перевагу явним hooks вище. -- **`before_agent_reply`**: виконується після inline-дій і перед викликом LLM, даючи Plugin можливість забрати хід і повернути синтетичну відповідь або повністю заглушити хід. +- **`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. -- **`tool_result_persist`**: синхронно трансформує результати інструментів перед їх записом у транскрипт сесії, яким володіє OpenClaw. -- **`message_received` / `message_sending` / `message_sent`**: hooks вхідних + вихідних повідомлень. +- **`before_compaction` / `after_compaction`**: спостерігає за циклами Compaction або додає до них анотації. +- **`before_tool_call` / `after_tool_call`**: перехоплює параметри/результати інструментів. +- **`before_install`**: перевіряє вбудовані результати сканування та за потреби блокує інсталяції Skills або Plugin. +- **`tool_result_persist`**: синхронно трансформує результати інструментів перед записом у транскрипт сесії, що належить OpenClaw. +- **`message_received` / `message_sending` / `message_sent`**: хуки вхідних + вихідних повідомлень. - **`session_start` / `session_end`**: межі життєвого циклу сесії. - **`gateway_start` / `gateway_stop`**: події життєвого циклу gateway. -Правила рішень hook для вихідних/tool guard: +Правила рішень хуків для вихідних/інструментальних захистів: - `before_tool_call`: `{ block: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. -- `before_tool_call`: `{ block: false }` нічого не робить і не скасовує попереднє блокування. +- `before_tool_call`: `{ block: false }` не виконує дій і не скасовує попереднє блокування. - `before_install`: `{ block: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. -- `before_install`: `{ block: false }` нічого не робить і не скасовує попереднє блокування. +- `before_install`: `{ block: false }` не виконує дій і не скасовує попереднє блокування. - `message_sending`: `{ cancel: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. -- `message_sending`: `{ cancel: false }` нічого не робить і не скасовує попереднє скасування. +- `message_sending`: `{ cancel: false }` не виконує дій і не скасовує попереднє скасування. -Див. [Plugin hooks](/uk/plugins/hooks) для API hook і деталей реєстрації. +Див. [Хуки Plugin](/uk/plugins/hooks) для API хуків і подробиць реєстрації. -Harness-и можуть адаптувати ці hooks по-різному. Harness app-server Codex зберігає -OpenClaw plugin hooks як контракт сумісності для документованих дзеркальних -поверхонь, тоді як нативні hooks Codex залишаються окремим низькорівневим механізмом Codex. +Тестові обв’язки можуть адаптувати ці хуки по-різному. Тестова обв’язка сервера застосунку Codex зберігає +хуки Plugin OpenClaw як контракт сумісності для документованих дзеркальних +поверхонь, тоді як нативні хуки Codex залишаються окремим нижчорівневим механізмом Codex. ## Потокова передача + часткові відповіді -- Дельти асистента транслюються з pi-agent-core і видаються як події `assistant`. -- Потокова передача блоків може видавати часткові відповіді або на `text_end`, або на `message_end`. -- Потокова передача міркувань може видаватися як окремий потік або як блокові відповіді. -- Див. [Потокова передача](/uk/concepts/streaming) для поведінки фрагментації та блокових відповідей. +- Дельти асистента потоково передаються з pi-agent-core і випускаються як події `assistant`. +- Потокова передача блоків може випускати часткові відповіді або на `text_end`, або на `message_end`. +- Потокова передача міркувань може випускатися як окремий потік або як блокові відповіді. +- Див. [Потокова передача](/uk/concepts/streaming) щодо поведінки фрагментації та блокових відповідей. -## Виконання інструментів + інструменти повідомлень +## Виконання інструментів + інструменти обміну повідомленнями -- Події старту/оновлення/завершення інструментів видаються в потоці `tool`. -- Результати інструментів санітизуються за розміром і image payload-ами перед логуванням/видачею. -- Надсилання інструментами повідомлень відстежуються, щоб пригнічувати дублікати підтверджень від асистента. +- Події початку/оновлення/завершення інструментів випускаються в потоці `tool`. +- Результати інструментів очищаються за розміром і корисними навантаженнями зображень перед журналюванням/випуском. +- Надсилання інструментів обміну повідомленнями відстежуються, щоб пригнічувати дублікати підтверджень асистента. ## Формування відповіді + пригнічення -- Фінальні payload-и збираються з: - - тексту асистента (і необов’язкових міркувань) - - inline-підсумків інструментів (коли verbose + дозволено) - - тексту помилки асистента, коли модель повертає помилку -- Точний silent token `NO_REPLY` / `no_reply` фільтрується з вихідних - payload-ів. -- Дублікати інструментів повідомлень видаляються з фінального списку payload-ів. -- Якщо не лишається жодного придатного для рендерингу payload-а, а інструмент завершився помилкою, видається резервна відповідь про помилку інструмента - (якщо інструмент повідомлень уже не надіслав видиму для користувача відповідь). +- Фінальні корисні навантаження збираються з: + - тексту асистента (і необов’язкового міркування) + - inline-зведень інструментів (коли verbose + дозволено) + - тексту помилки асистента, коли модель завершується з помилкою +- Точний тихий токен `NO_REPLY` / `no_reply` фільтрується з вихідних + корисних навантажень. +- Дублікати інструментів обміну повідомленнями вилучаються з фінального списку корисних навантажень. +- Якщо не залишається корисних навантажень, придатних для відображення, і інструмент завершився з помилкою, випускається резервна відповідь про помилку інструмента + (якщо інструмент обміну повідомленнями вже не надіслав видиму користувачу відповідь). ## Compaction + повторні спроби -- Auto-compaction видає події потоку `compaction` і може запускати повторну спробу. -- Під час повторної спроби буфери в пам’яті та підсумки інструментів скидаються, щоб уникнути дублювання виводу. -- Див. [Compaction](/uk/concepts/compaction) для конвеєра Compaction. +- Автоматичний Compaction випускає події потоку `compaction` і може запустити повторну спробу. +- Під час повторної спроби буфери в пам’яті та зведення інструментів скидаються, щоб уникнути дублювання виводу. +- Див. [Compaction](/uk/concepts/compaction) щодо конвеєра Compaction. ## Потоки подій (сьогодні) -- `lifecycle`: видається `subscribeEmbeddedPiSession` (і як резервний варіант `agentCommand`) +- `lifecycle`: випускається `subscribeEmbeddedPiSession` (і як резервний варіант `agentCommand`) - `assistant`: потокові дельти з pi-agent-core - `tool`: потокові події інструментів з pi-agent-core -## Обробка чат-каналів +## Обробка чат-каналу - Дельти асистента буферизуються в чат-повідомлення `delta`. -- Чат `final` видається на **lifecycle end/error**. +- Чат `final` випускається на **кінці/помилці життєвого циклу**. ## Тайм-аути -- `agent.wait` за замовчуванням: 30 с (лише очікування). Параметр `timeoutMs` перевизначає. -- Середовище виконання агента: `agents.defaults.timeoutSeconds` за замовчуванням 172800 с (48 годин); застосовується в таймері переривання `runEmbeddedPiAgent`. -- Середовище виконання Cron: ізольований agent-turn `timeoutSeconds` належить cron. Планувальник запускає цей таймер, коли починається виконання, перериває базовий запуск у налаштований граничний час, а потім виконує обмежене очищення перед записом тайм-ауту, щоб застаріла дочірня сесія не могла тримати смугу заблокованою. -- Відновлення завислої сесії: коли діагностику ввімкнено, `diagnostics.stuckSessionWarnMs` виявляє довгі сесії `processing`. Активні вбудовані запуски, активні операції відповіді та активні завдання сесійної смуги за замовчуванням залишаються лише попередженнями; якщо діагностика не показує активної роботи для сесії, watchdog звільняє відповідну сесійну смугу, щоб робота запуску в черзі могла виконатися. -- Тайм-аут простою моделі: OpenClaw перериває запит до моделі, коли до завершення idle window не надходять фрагменти відповіді. `models.providers..timeoutSeconds` розширює цей idle watchdog для повільних локальних/самостійно розгорнутих providers; інакше OpenClaw використовує `agents.defaults.timeoutSeconds`, коли це налаштовано, з обмеженням 120 с за замовчуванням. Запуски, ініційовані Cron, без явного тайм-ауту моделі або агента вимикають idle watchdog і покладаються на зовнішній тайм-аут cron. -- Тайм-аут HTTP-запиту provider: `models.providers..timeoutSeconds` застосовується до HTTP fetch-ів моделі цього provider, включно з connect, headers, body, тайм-аутом запиту SDK, загальною обробкою guarded-fetch abort і watchdog простою потоку моделі. Використовуйте це для повільних локальних/самостійно розгорнутих providers, таких як Ollama, перш ніж підвищувати тайм-аут усього середовища виконання агента. +- Типове значення `agent.wait`: 30 с (лише очікування). Параметр `timeoutMs` перевизначає. +- Середовище виконання агента: типове значення `agents.defaults.timeoutSeconds` — 172800 с (48 годин); застосовується в таймері переривання `runEmbeddedPiAgent`. +- Середовище виконання Cron: ізольований агентний хід `timeoutSeconds` належить cron. Планувальник запускає цей таймер, коли починається виконання, перериває базовий запуск у налаштований граничний момент, а потім виконує обмежене очищення перед записом тайм-ауту, щоб застаріла дочірня сесія не могла заблокувати лінію. +- Відновлення застряглої сесії: з увімкненою діагностикою `diagnostics.stuckSessionWarnMs` виявляє тривалі сесії `processing`. Активні вбудовані запуски, активні операції відповідей і активні завдання лінії сесії за замовчуванням залишаються лише попередженнями; якщо діагностика не показує активної роботи для сесії, сторожовий механізм звільняє зачеплену лінію сесії, щоб робота запуску в черзі могла спорожнитися. +- Тайм-аут простою моделі: OpenClaw перериває запит до моделі, коли до завершення вікна простою не надходять фрагменти відповіді. `models.providers..timeoutSeconds` розширює цей сторожовий механізм простою для повільних локальних/самостійно розміщених провайдерів; інакше OpenClaw використовує `agents.defaults.timeoutSeconds`, коли його налаштовано, з типовим обмеженням у 120 с. Запуски, ініційовані Cron, без явного тайм-ауту моделі або агента вимикають сторожовий механізм простою та покладаються на зовнішній тайм-аут cron. +- Тайм-аут HTTP-запиту провайдера: `models.providers..timeoutSeconds` застосовується до HTTP-запитів моделі цього провайдера, включно з підключенням, заголовками, тілом, тайм-аутом запиту SDK, загальною обробкою переривання захищеного fetch і сторожовим механізмом простою потоку моделі. Використовуйте це для повільних локальних/самостійно розміщених провайдерів, як-от Ollama, перед підвищенням тайм-ауту всього середовища виконання агента. ## Де все може завершитися раніше @@ -184,7 +185,7 @@ OpenClaw plugin hooks як контракт сумісності для доку ## Пов’язане - [Інструменти](/uk/tools) — доступні інструменти агента -- [Hooks](/uk/automation/hooks) — скрипти, керовані подіями, що запускаються подіями життєвого циклу агента -- [Compaction](/uk/concepts/compaction) — як узагальнюються довгі розмови -- [Exec Approvals](/uk/tools/exec-approvals) — approval gates для shell-команд -- [Thinking](/uk/tools/thinking) — конфігурація рівня thinking/reasoning +- [Хуки](/uk/automation/hooks) — подієво-керовані скрипти, що запускаються подіями життєвого циклу агента +- [Compaction](/uk/concepts/compaction) — як підсумовуються довгі розмови +- [Затвердження Exec](/uk/tools/exec-approvals) — шлюзи затвердження для команд оболонки +- [Thinking](/uk/tools/thinking) — налаштування рівня thinking/міркування diff --git a/docs/uk/concepts/queue.md b/docs/uk/concepts/queue.md index d113827e8..b6d8297e3 100644 --- a/docs/uk/concepts/queue.md +++ b/docs/uk/concepts/queue.md @@ -2,63 +2,63 @@ read_when: - Зміна виконання автовідповідей або паралельності - Пояснення режимів /queue або поведінки спрямування повідомлень -summary: Режими черги автовідповідей, типові значення та перевизначення для окремих сеансів +summary: Режими черги автовідповідей, значення за замовчуванням і перевизначення для окремих сеансів title: Черга команд x-i18n: - generated_at: "2026-04-30T00:29:46Z" + generated_at: "2026-04-30T18:26:36Z" model: gpt-5.5 provider: openai - source_hash: 2ac0c0ded9558b080714fa4b8be0d552f985911bf19b427020f9654ae4955b2d + source_hash: fbf1bb1ffd4ce06fa138f63e31651b8821226d9c95dd6b93d68326a5fb91fdd0 source_path: concepts/queue.md workflow: 16 --- -Ми серіалізуємо вхідні автозапуски відповідей (усі канали) через невелику внутрішньопроцесну чергу, щоб кілька запусків агента не конфліктували між собою, водночас зберігаючи безпечний паралелізм між сесіями. +Ми серіалізуємо вхідні запуски автовідповідей (усі канали) через невелику внутрішньопроцесну чергу, щоб запобігти конфліктам між кількома запусками агента, водночас зберігаючи безпечний паралелізм між сесіями. -## Навіщо +## Чому -- Автозапуски відповідей можуть бути витратними (виклики LLM) і можуть конфліктувати, коли кілька вхідних повідомлень надходять майже одночасно. -- Серіалізація запобігає конкуренції за спільні ресурси (файли сесій, журнали, CLI stdin) і зменшує ймовірність обмежень частоти на боці вищого рівня. +- Запуски автовідповідей можуть бути дорогими (виклики LLM) і можуть конфліктувати, коли кілька вхідних повідомлень надходять майже одночасно. +- Серіалізація уникає конкуренції за спільні ресурси (файли сесій, журнали, stdin CLI) і зменшує ймовірність досягнення лімітів швидкості upstream. ## Як це працює -- Черга FIFO з урахуванням смуг обробляє кожну смугу з налаштовуваним лімітом конкурентності (типово 1 для неналаштованих смуг; `main` типово 4, `subagent` — 8). -- `runEmbeddedPiAgent` ставить у чергу за **ключем сесії** (смуга `session:`), щоб гарантувати лише один активний запуск на сесію. -- Потім кожен запуск сесії ставиться у **глобальну смугу** (`main` типово), щоб загальний паралелізм обмежувався `agents.defaults.maxConcurrent`. -- Коли ввімкнено докладне журналювання, запуски в черзі видають коротке повідомлення, якщо чекали понад ~2 с перед стартом. -- Індикатори набору все одно спрацьовують одразу під час додавання в чергу (якщо канал це підтримує), тому користувацький досвід не змінюється, поки ми чекаємо своєї черги. +- FIFO-черга з урахуванням lane обробляє кожну lane з налаштовуваним обмеженням конкурентності (типово 1 для неналаштованих lane; main типово має 4, subagent — 8). +- `runEmbeddedPiAgent` ставить у чергу за **ключем сесії** (lane `session:`), щоб гарантувати лише один активний запуск на сесію. +- Кожен запуск сесії потім ставиться в **глобальну lane** (`main` за замовчуванням), тож загальний паралелізм обмежується `agents.defaults.maxConcurrent`. +- Коли увімкнено докладне журналювання, поставлені в чергу запуски виводять коротке повідомлення, якщо чекали понад ~2 с перед стартом. +- Індикатори набору все одно спрацьовують одразу під час додавання в чергу (коли це підтримує канал), тож користувацький досвід не змінюється, поки ми чекаємо своєї черги. -## Типові значення +## Значення за замовчуванням -Якщо не задано, усі поверхні вхідних каналів використовують: +Коли не задано, усі поверхні вхідних каналів використовують: - `mode: "steer"` - `debounceMs: 500` - `cap: 20` - `drop: "summarize"` -`steer` є типовим, бо він зберігає активний хід моделі чутливим без -запуску другої сесії. Він обробляє всі керівні повідомлення, що надійшли -до наступної межі моделі. Якщо поточний запуск не може приймати керування, -OpenClaw повертається до запису черги подальшого ходу. +`steer` є типовим режимом, бо він зберігає активний хід моделі швидким без +запуску другого запуску сесії. Він обробляє всі steering-повідомлення, що надійшли +до наступної межі моделі. Якщо поточний запуск не може приймати steering, +OpenClaw повертається до запису followup у черзі. ## Режими черги -Вхідні повідомлення можуть керувати поточним запуском, чекати подальшого ходу або робити і те, і те: +Вхідні повідомлення можуть спрямовувати поточний запуск, чекати наступного ходу followup або робити і те, й інше: -- `steer`: поставити керівні повідомлення в чергу активного середовища виконання. Pi доставляє всі очікувані керівні повідомлення **після того, як поточний хід асистента завершить виконання викликів інструментів**, перед наступним викликом LLM; Codex app-server отримує один пакетний `turn/steer`. Якщо запуск не транслюється активно або керування недоступне, OpenClaw повертається до запису черги подальшого ходу. -- `queue` (застарілий): старе керування по одному повідомленню за раз. Pi доставляє одне керівне повідомлення з черги на кожній межі моделі; Codex app-server отримує окремі запити `turn/steer`. Віддавайте перевагу `steer`, якщо вам не потрібна попередня серіалізована поведінка. -- `followup`: поставити кожне повідомлення в чергу для пізнішого ходу агента після завершення поточного запуску. -- `collect`: об’єднати повідомлення в черзі в **один** подальший хід після вікна тиші. Якщо повідомлення адресовані різним каналам/темам, вони обробляються окремо, щоб зберегти маршрутизацію. -- `steer-backlog` (також `steer+backlog`): керувати зараз **і** зберегти те саме повідомлення для подальшого ходу. -- `interrupt` (застарілий): перервати активний запуск для цієї сесії, а потім запустити найновіше повідомлення. +- `steer`: ставить steering-повідомлення в чергу активного runtime. Pi доставляє всі очікувані steering-повідомлення **після того, як поточний хід асистента завершить виконання своїх викликів інструментів**, перед наступним викликом LLM; app-server Codex отримує один пакетний `turn/steer`. Якщо запуск не перебуває в активному streaming або steering недоступний, OpenClaw повертається до запису followup у черзі. +- `queue` (застарілий): старий steering по одному повідомленню. Pi доставляє одне повідомлення steering із черги на кожній межі моделі; app-server Codex отримує окремі запити `turn/steer`. Надавайте перевагу `steer`, якщо вам не потрібна попередня серіалізована поведінка. +- `followup`: ставить кожне повідомлення в чергу для пізнішого ходу агента після завершення поточного запуску. +- `collect`: об’єднує повідомлення з черги в **один** хід followup після тихого вікна. Якщо повідомлення спрямовані в різні канали/треди, вони обробляються окремо, щоб зберегти маршрутизацію. +- `steer-backlog` (також `steer+backlog`): спрямовує зараз **і** зберігає те саме повідомлення для ходу followup. +- `interrupt` (застарілий): перериває активний запуск для цієї сесії, а потім запускає найновіше повідомлення. -Steer-backlog означає, що ви можете отримати подальшу відповідь після керованого запуску, тому -поверхні потокового передавання можуть виглядати як дублікати. Віддавайте перевагу `collect`/`steer`, якщо хочете +Steer-backlog означає, що після спрямованого запуску можна отримати відповідь followup, тому +на streaming-поверхнях це може виглядати як дублікати. Надавайте перевагу `collect`/`steer`, якщо хочете одну відповідь на кожне вхідне повідомлення. -Щодо часової поведінки й залежностей, специфічних для середовища виконання, див. -[Черга керування](/uk/concepts/queue-steering). +Про специфічні для runtime часові характеристики та поведінку залежностей див. +[Черга steering](/uk/concepts/queue-steering). Налаштуйте глобально або для кожного каналу через `messages.queue`: @@ -78,52 +78,53 @@ Steer-backlog означає, що ви можете отримати подал ## Параметри черги -Параметри застосовуються до `followup`, `collect` і `steer-backlog` (а також до `steer` або застарілого `queue`, коли керування повертається до подальшого ходу): +Параметри застосовуються до `followup`, `collect` і `steer-backlog` (а також до `steer` або застарілого `queue`, коли steering повертається до followup): -- `debounceMs`: вікно тиші перед обробкою подальших ходів із черги. Числа без одиниць — це мілісекунди; одиниці `ms`, `s`, `m`, `h` і `d` приймаються параметрами `/queue`. +- `debounceMs`: тихе вікно перед обробкою поставлених у чергу followup. Числа без одиниць — це мілісекунди; одиниці `ms`, `s`, `m`, `h` і `d` приймаються параметрами `/queue`. - `cap`: максимальна кількість повідомлень у черзі на сесію. Значення нижче `1` ігноруються. -- `drop: "summarize"`: типово. За потреби відкидати найстаріші записи черги, зберігати компактні підсумки та вставляти їх як синтетичний запит подальшого ходу. -- `drop: "old"`: за потреби відкидати найстаріші записи черги без збереження підсумків. -- `drop: "new"`: відхиляти найновіше повідомлення, коли черга вже заповнена. +- `drop: "summarize"`: типово. За потреби відкидає найстаріші записи черги, зберігає компактні підсумки та вставляє їх як синтетичний prompt followup. +- `drop: "old"`: за потреби відкидає найстаріші записи черги без збереження підсумків. +- `drop: "new"`: відхиляє найновіше повідомлення, коли черга вже заповнена. -Типові значення: `debounceMs: 500`, `cap: 20`, `drop: summarize`. +Типово: `debounceMs: 500`, `cap: 20`, `drop: summarize`. ## Пріоритет Для вибору режиму OpenClaw визначає: -1. Вбудоване або збережене перевизначення `/queue` для сесії. +1. Inline або збережене перевизначення `/queue` для сесії. 2. `messages.queue.byChannel.`. 3. `messages.queue.mode`. 4. Типовий `steer`. -Для параметрів вбудовані або збережені параметри `/queue` мають перевагу над конфігурацією. Потім -застосовуються затримка для конкретного каналу (`messages.queue.debounceMsByChannel`), типові значення затримки -Plugin, глобальні параметри `messages.queue` і вбудовані типові значення. -`cap` і `drop` — це глобальні/сесійні параметри, а не ключі конфігурації для кожного каналу. +Для параметрів inline або збережені параметри `/queue` мають пріоритет над конфігурацією. Потім +застосовуються debounce для каналу (`messages.queue.debounceMsByChannel`), типові значення debounce +Plugin, глобальні параметри `messages.queue` і вбудовані типові значення. `cap` і `drop` є глобальними/сесійними параметрами, а не конфігураційними +ключами для кожного каналу. ## Перевизначення для сесії - Надішліть `/queue ` як окрему команду, щоб зберегти режим для поточної сесії. -- Параметри можна поєднувати: `/queue collect debounce:0.5s cap:25 drop:summarize` +- Параметри можна комбінувати: `/queue collect debounce:0.5s cap:25 drop:summarize` - `/queue default` або `/queue reset` очищає перевизначення сесії. -## Обсяг і гарантії +## Область дії та гарантії -- Застосовується до запусків агентів авто-відповідей у всіх вхідних каналах, що використовують конвеєр відповідей Gateway (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat тощо). -- Типова смуга (`main`) є загальною для процесу для вхідних повідомлень і основних Heartbeat; задайте `agents.defaults.maxConcurrent`, щоб дозволити кілька сесій паралельно. -- Можуть існувати додаткові смуги (наприклад, `cron`, `cron-nested`, `nested`, `subagent`), щоб фонові завдання могли виконуватися паралельно, не блокуючи вхідні відповіді. Ізольовані ходи агента cron утримують слот `cron`, поки їхнє внутрішнє виконання агента використовує `cron-nested`; обидва використовують `cron.maxConcurrentRuns`. Спільні не-cron потоки `nested` зберігають власну поведінку смуги. Ці відокремлені запуски відстежуються як [фонові завдання](/uk/automation/tasks). -- Смуги для сесій гарантують, що лише один запуск агента торкається певної сесії одночасно. -- Без зовнішніх залежностей або фонових робочих потоків; чистий TypeScript + проміси. +- Застосовується до запусків агентів автовідповіді в усіх вхідних каналах, які використовують reply pipeline Gateway (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat тощо). +- Типова lane (`main`) є процесно-глобальною для вхідних повідомлень і основних Heartbeat; задайте `agents.defaults.maxConcurrent`, щоб дозволити кілька сесій паралельно. +- Можуть існувати додаткові lane (наприклад, `cron`, `cron-nested`, `nested`, `subagent`), щоб фонові завдання могли виконуватися паралельно, не блокуючи вхідні відповіді. Ізольовані ходи cron-агента утримують слот `cron`, поки їхнє внутрішнє виконання агента використовує `cron-nested`; обидва використовують `cron.maxConcurrentRuns`. Спільні не-cron потоки `nested` зберігають власну поведінку lane. Ці відокремлені запуски відстежуються як [фонові завдання](/uk/automation/tasks). +- Lane для сесії гарантують, що лише один запуск агента одночасно торкається певної сесії. +- Без зовнішніх залежностей або фонових worker-тредів; чистий TypeScript + promises. ## Усунення несправностей -- Якщо здається, що команди застрягли, увімкніть докладні журнали й шукайте рядки “queued for …ms”, щоб підтвердити, що черга обробляється. -- Якщо вам потрібна глибина черги, увімкніть докладні журнали й стежте за рядками часу черги. -- Коли діагностику ввімкнено, сесії, що залишаються в `processing` довше за `diagnostics.stuckSessionWarnMs`, записують попередження про застряглу сесію. Активні вбудовані запуски, активні операції відповіді та активні завдання смуги типово залишаються лише попередженнями; застарілий облік запуску без активної роботи сесії може звільнити відповідну смугу сесії, щоб робота з черги оброблялася. +- Якщо команди здаються завислими, увімкніть докладні журнали та шукайте рядки “queued for …ms”, щоб підтвердити, що черга обробляється. +- Якщо вам потрібна глибина черги, увімкніть докладні журнали та стежте за рядками часу черги. +- Запуски app-server Codex, які приймають хід, а потім перестають виводити прогрес, перериваються адаптером Codex, щоб активна lane сесії могла звільнитися замість очікування timeout зовнішнього запуску. +- Коли діагностику увімкнено, сесії, що залишаються в `processing` довше за `diagnostics.stuckSessionWarnMs`, записують попередження про завислу сесію. Активні вбудовані запуски, активні операції відповіді та активні завдання lane типово залишаються лише попередженнями; застарілий startup-облік без активної роботи сесії може звільнити відповідну lane сесії, щоб робота з черги продовжилася. ## Пов’язане - [Керування сесіями](/uk/concepts/session) -- [Черга керування](/uk/concepts/queue-steering) +- [Черга steering](/uk/concepts/queue-steering) - [Політика повторних спроб](/uk/concepts/retry)