From f7b8dac75c7b89acfe4205a8cb869af5b23824bb Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 2 May 2026 12:17:12 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/cli/sessions.md | 54 +-- docs/uk/plugins/sdk-runtime.md | 117 +++--- .../session-management-compaction.md | 363 +++++++++--------- 3 files changed, 271 insertions(+), 263 deletions(-) diff --git a/docs/uk/cli/sessions.md b/docs/uk/cli/sessions.md index c718235ba..53822fe55 100644 --- a/docs/uk/cli/sessions.md +++ b/docs/uk/cli/sessions.md @@ -1,24 +1,24 @@ --- read_when: - - Ви хочете переглянути список збережених сеансів і побачити нещодавню активність -summary: Довідка CLI для `openclaw sessions` (перелік збережених сеансів + використання) + - Ви хочете переглянути список збережених сесій і побачити нещодавню активність +summary: Довідник CLI для `openclaw sessions` (список збережених сеансів + використання) title: Сеанси x-i18n: - generated_at: "2026-05-02T07:08:11Z" + generated_at: "2026-05-02T12:15:29Z" model: gpt-5.5 provider: openai - source_hash: 9c7f0d521756ace4af05451b925256f89661bf971533541764c128e2be9d6431 + source_hash: 8791a36fedc18a1c2d4144c3fd4faeaf8f5320676ceee76026959cbe2dc1873c source_path: cli/sessions.md workflow: 16 --- # `openclaw sessions` -Показує список збережених сеансів розмов. +Виводить список збережених сесій розмов. -Списки сеансів не є перевірками активності каналу/провайдера. Вони показують збережені -рядки розмов зі сховищ сеансів. Тихий Discord, Slack, Telegram або -інший канал може успішно перепідключитися без створення нового рядка сеансу, +Списки сесій не є перевірками доступності каналу/провайдера. Вони показують збережені +рядки розмов зі сховищ сесій. Тихий Discord, Slack, Telegram або +інший канал може успішно перепідключитися без створення нового рядка сесії, доки не буде оброблено повідомлення. Використовуйте `openclaw channels status --probe`, `openclaw status --deep` або `openclaw health --verbose`, коли потрібне живе підключення каналу. @@ -40,7 +40,7 @@ openclaw sessions --json - `--all-agents`: агрегувати всі налаштовані сховища агентів - `--store `: явний шлях до сховища (не можна поєднувати з `--agent` або `--all-agents`) -Експортувати пакет траєкторії для збереженого сеансу: +Експортуйте пакет траєкторії для збереженої сесії: ```bash openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace . @@ -48,14 +48,14 @@ openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:12 ``` Це шлях команди, який використовує slash-команда `/export-trajectory` після того, -як власник схвалить запит на виконання. Каталог виводу завжди визначається +як власник схвалить запит на виконання. Вихідний каталог завжди визначається всередині `.openclaw/trajectory-exports/` у вибраному робочому просторі. -`openclaw sessions --all-agents` читає налаштовані сховища агентів. Виявлення сеансів Gateway і ACP +`openclaw sessions --all-agents` читає налаштовані сховища агентів. Виявлення сесій Gateway і ACP ширше: воно також включає сховища лише на диску, знайдені в -корені `agents/` за замовчуванням або в шаблонізованому корені `session.store`. Такі -виявлені сховища мають визначатися як звичайні файли `sessions.json` всередині -кореня агента; символьні посилання та шляхи за межами кореня пропускаються. +корені `agents/` за замовчуванням або в шаблонному корені `session.store`. Ці +виявлені сховища мають розв’язуватися у звичайні файли `sessions.json` всередині +кореня агента; символьні посилання та шляхи поза коренем пропускаються. Приклади JSON: @@ -80,7 +80,7 @@ openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:12 ## Обслуговування очищення -Запустити обслуговування зараз (замість очікування наступного циклу запису): +Запустіть обслуговування зараз (замість очікування наступного циклу запису): ```bash openclaw sessions cleanup --dry-run @@ -91,19 +91,23 @@ openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123 openclaw sessions cleanup --json ``` -`openclaw sessions cleanup` використовує налаштування `session.maintenance` з конфігурації: +`openclaw sessions cleanup` використовує параметри `session.maintenance` з конфігурації: -- Примітка щодо області: `openclaw sessions cleanup` обслуговує сховища сеансів, транскрипти та побічні файли траєкторій. Вона не очищає журнали запусків cron (`cron/runs/.jsonl`), якими керують `cron.runLog.maxBytes` і `cron.runLog.keepLines` у [конфігурації Cron](/uk/automation/cron-jobs#configuration) та які пояснено в [обслуговуванні Cron](/uk/automation/cron-jobs#maintenance). +- Примітка щодо області: `openclaw sessions cleanup` обслуговує сховища сесій, транскрипти та бічні файли траєкторій. Вона не скорочує журнали запусків cron (`cron/runs/.jsonl`), якими керують `cron.runLog.maxBytes` і `cron.runLog.keepLines` у [конфігурації Cron](/uk/automation/cron-jobs#configuration) та які пояснено в [обслуговуванні Cron](/uk/automation/cron-jobs#maintenance). -- `--dry-run`: попередньо показати, скільки записів буде видалено/обмежено без запису. - - У текстовому режимі dry-run друкує таблицю дій для кожного сеансу (`Action`, `Key`, `Age`, `Model`, `Flags`), щоб можна було побачити, що буде збережено, а що видалено. -- `--enforce`: застосувати обслуговування, навіть коли `session.maintenance.mode` має значення `warn`. -- `--fix-missing`: видалити записи, чиї файли транскриптів відсутні, навіть якщо вони зазвичай ще не підлягали б видаленню за віком/кількістю. -- `--active-key `: захистити конкретний активний ключ від витіснення через дисковий бюджет. Стійкі зовнішні вказівники розмов, як-от групові сеанси та чат-сеанси в межах треду, також зберігаються під час обслуговування за віком/кількістю/дисковим бюджетом. +- `--dry-run`: попередньо переглянути, скільки записів було б видалено/обмежено без запису. + - У текстовому режимі dry-run друкує таблицю дій для кожної сесії (`Action`, `Key`, `Age`, `Model`, `Flags`), щоб можна було побачити, що буде збережено, а що видалено. +- `--enforce`: застосувати обслуговування навіть коли `session.maintenance.mode` має значення `warn`. +- `--fix-missing`: видалити записи, чиї файли транскриптів відсутні, навіть якщо зазвичай вони ще не підпадали б під видалення за віком/кількістю. +- `--active-key `: захистити конкретний активний ключ від витіснення через дисковий бюджет. Довговічні зовнішні вказівники розмов, як-от групові сесії та сесії чату з областю потоку, також зберігаються під час обслуговування за віком/кількістю/дисковим бюджетом. - `--agent `: запустити очищення для одного налаштованого сховища агента. - `--all-agents`: запустити очищення для всіх налаштованих сховищ агентів. - `--store `: виконати для конкретного файлу `sessions.json`. -- `--json`: надрукувати підсумок JSON. З `--all-agents` вивід містить один підсумок на кожне сховище. +- `--json`: надрукувати підсумок JSON. З `--all-agents` вивід включає один підсумок на сховище. + +Коли Gateway доступний, примусове очищення для налаштованих сховищ агентів +надсилається через Gateway, щоб воно використовувало той самий записувач сховища сесій, що й трафік +під час виконання. Використовуйте `--store ` для явного офлайн-відновлення файлу сховища. `openclaw sessions cleanup --all-agents --dry-run --json`: @@ -135,9 +139,9 @@ openclaw sessions cleanup --json Пов’язане: -- Конфігурація сеансів: [довідник із конфігурації](/uk/gateway/config-agents#session) +- Конфігурація сесій: [довідник конфігурації](/uk/gateway/config-agents#session) ## Пов’язане - [довідник CLI](/uk/cli) -- [керування сеансами](/uk/concepts/session) +- [Керування сесіями](/uk/concepts/session) diff --git a/docs/uk/plugins/sdk-runtime.md b/docs/uk/plugins/sdk-runtime.md index 6122dd193..87914b46e 100644 --- a/docs/uk/plugins/sdk-runtime.md +++ b/docs/uk/plugins/sdk-runtime.md @@ -1,16 +1,16 @@ --- read_when: - - Вам потрібно викликати допоміжні функції ядра з Plugin (TTS, STT, генерація зображень, веб-пошук, субагент, вузли) - - Ви хочете зрозуміти, що надає `api.runtime` + - Потрібно викликати допоміжні функції ядра з Plugin (TTS, STT, генерація зображень, вебпошук, субагент, вузли) + - Ви хочете зрозуміти, що надає api.runtime - Ви звертаєтеся до допоміжних засобів конфігурації, агента або медіа з коду Plugin sidebarTitle: Runtime helpers -summary: api.runtime -- впроваджені помічники середовища виконання, доступні для плагінів +summary: api.runtime -- впроваджені допоміжні засоби середовища виконання, доступні для Plugin title: Допоміжні засоби середовища виконання Plugin x-i18n: - generated_at: "2026-04-30T04:07:53Z" + generated_at: "2026-05-02T12:15:45Z" model: gpt-5.5 provider: openai - source_hash: f2264090e062be9892a2bac7d313cad80a550f79b0bf0d74635bf6b80aea5060 + source_hash: 02c0dc6522e80d4a02b1d3c248fa5ac934888035d435df8b1967861f9dcceb6a source_path: plugins/sdk-runtime.md workflow: 16 --- @@ -19,7 +19,7 @@ x-i18n: - Покроковий посібник, який показує використання цих допоміжних функцій у контексті для plugin каналів. + Покроковий посібник, який показує використання цих допоміжних функцій у контексті для channel plugins. Покроковий посібник, який показує використання цих допоміжних функцій у контексті для provider plugins. @@ -34,32 +34,32 @@ register(api) { ## Завантаження й запис конфігурації -Надавайте перевагу конфігурації, яку вже передано в активний шлях виклику, наприклад `api.config` під час реєстрації або аргумент `cfg` у callback-функціях каналу/провайдера. Це дає змогу передавати один знімок процесу через виконання замість повторного розбору конфігурації на гарячих шляхах. +Надавайте перевагу конфігурації, яку вже було передано в активний шлях виклику, наприклад `api.config` під час реєстрації або аргумент `cfg` у callback-функціях каналу чи provider. Це зберігає один знімок процесу протягом роботи замість повторного розбору конфігурації в гарячих шляхах. -Використовуйте `api.runtime.config.current()` лише тоді, коли довготривалому обробнику потрібен поточний знімок процесу й до цієї функції не було передано конфігурацію. Повернене значення доступне лише для читання; перед редагуванням клонуйте його або використовуйте допоміжну функцію мутації. +Використовуйте `api.runtime.config.current()` лише тоді, коли довготривалому обробнику потрібен поточний знімок процесу, а конфігурацію не було передано цій функції. Повернене значення доступне тільки для читання; перед редагуванням створіть копію або скористайтеся допоміжною функцією мутації. -Фабрики інструментів отримують `ctx.runtimeConfig` плюс `ctx.getRuntimeConfig()`. Використовуйте getter всередині callback `execute` довготривалого інструмента, коли конфігурація може змінитися після створення визначення інструмента. +Фабрики інструментів отримують `ctx.runtimeConfig` разом із `ctx.getRuntimeConfig()`. Використовуйте getter усередині callback-функції `execute` довготривалого інструмента, коли конфігурація може змінитися після створення визначення інструмента. -Зберігайте зміни за допомогою `api.runtime.config.mutateConfigFile(...)` або `api.runtime.config.replaceConfigFile(...)`. Кожен запис має вибрати явну політику `afterWrite`: +Зберігайте зміни через `api.runtime.config.mutateConfigFile(...)` або `api.runtime.config.replaceConfigFile(...)`. Кожен запис має вибрати явну політику `afterWrite`: -- `afterWrite: { mode: "auto" }` дає змогу засобу перезавантаження Gateway ухвалити рішення. +- `afterWrite: { mode: "auto" }` дозволяє механізму перезавантаження Gateway ухвалити рішення. - `afterWrite: { mode: "restart", reason: "..." }` примусово виконує чистий перезапуск, коли автор запису знає, що гаряче перезавантаження небезпечне. -- `afterWrite: { mode: "none", reason: "..." }` пригнічує автоматичне перезавантаження/перезапуск лише тоді, коли викликач відповідає за подальшу дію. +- `afterWrite: { mode: "none", reason: "..." }` пригнічує автоматичне перезавантаження або перезапуск лише тоді, коли викликач сам відповідає за подальші дії. -Допоміжні функції мутації повертають `afterWrite` плюс типізований підсумок `followUp`, щоб викликачі могли журналювати або тестувати, чи вони запросили перезапуск. Gateway усе ще відповідає за те, коли цей перезапуск фактично відбудеться. +Допоміжні функції мутації повертають `afterWrite` разом із типізованим підсумком `followUp`, щоб викликачі могли логувати або тестувати, чи запросили вони перезапуск. Gateway і надалі визначає, коли цей перезапуск фактично відбудеться. -`api.runtime.config.loadConfig()` і `api.runtime.config.writeConfigFile(...)` є застарілими допоміжними функціями сумісності в межах `runtime-config-load-write`. Вони попереджають один раз під час виконання й залишаються доступними для старих зовнішніх plugins протягом вікна міграції. Вбудовані plugins не повинні їх використовувати; охоронці меж конфігурації завершаться помилкою, якщо код plugin викликає їх або імпортує ці допоміжні функції з підшляхів SDK plugin. +`api.runtime.config.loadConfig()` і `api.runtime.config.writeConfigFile(...)` є застарілими допоміжними функціями сумісності в межах `runtime-config-load-write`. Вони один раз попереджають під час виконання та залишаються доступними для старих зовнішніх plugins протягом вікна міграції. Вбудовані plugins не повинні їх використовувати; захисні перевірки межі конфігурації завершуються помилкою, якщо код plugin викликає їх або імпортує ці допоміжні функції з підшляхів plugin SDK. -Для прямих імпортів SDK використовуйте сфокусовані підшляхи конфігурації замість широкого сумісного barrel +Для прямих імпортів SDK використовуйте цільові підшляхи конфігурації замість широкого сумісного barrel `openclaw/plugin-sdk/config-runtime`: `config-types` для -типів, `plugin-config-runtime` для тверджень щодо вже завантаженої конфігурації та пошуку запису plugin, -`runtime-config-snapshot` для поточних знімків процесу та -`config-mutation` для записів. Тести вбудованих plugin мають напряму mock-ити ці сфокусовані -підшляхи замість mock широкого сумісного barrel. +типів, `plugin-config-runtime` для перевірок уже завантаженої конфігурації та +пошуку точки входу plugin, `runtime-config-snapshot` для поточних знімків процесу, і +`config-mutation` для записів. Тести вбудованих plugins мають mock-ати ці цільові +підшляхи напряму, а не широкий сумісний barrel. -Внутрішній runtime-код OpenClaw має той самий напрям: завантажити конфігурацію один раз на межі CLI, Gateway або процесу, а потім передавати це значення далі. Успішні записи мутації оновлюють runtime-знімок процесу й просувають його внутрішню ревізію; довготривалі кеші мають спиратися на runtime-owned ключ кешу, а не серіалізувати конфігурацію локально. Довготривалі runtime-модулі мають сканер із нульовою толерантністю до неявних викликів `loadConfig()`; використовуйте переданий `cfg`, `context.getRuntimeConfig()` запиту або `getRuntimeConfig()` на явній межі процесу. +Внутрішній runtime-код OpenClaw рухається в тому самому напрямку: завантажити конфігурацію один раз на межі CLI, Gateway або процесу, а потім передавати це значення далі. Успішні записи мутації оновлюють runtime-знімок процесу й просувають його внутрішню ревізію; довготривалі кеші мають спиратися на runtime-власний ключ кешу, а не серіалізувати конфігурацію локально. Довготривалі runtime-модулі мають сканер із нульовою толерантністю до неявних викликів `loadConfig()`; використовуйте переданий `cfg`, `context.getRuntimeConfig()` запиту або `getRuntimeConfig()` на явній межі процесу. -Шляхи виконання провайдера й каналу мають використовувати активний знімок runtime-конфігурації, а не файловий знімок, повернений для зворотного читання або редагування конфігурації. Файлові знімки зберігають початкові значення, як-от маркери SecretRef, для UI та записів; callback-функціям провайдера потрібне розв’язане runtime-представлення. Коли допоміжну функцію може бути викликано або з активним початковим знімком, або з активним runtime-знімком, перед читанням облікових даних пропустіть її через `selectApplicableRuntimeConfig()`. +Шляхи виконання provider і каналу мають використовувати активний знімок runtime-конфігурації, а не файловий знімок, повернений для зворотного читання або редагування конфігурації. Файлові знімки зберігають вихідні значення, зокрема маркери SecretRef для UI та записів; callback-функціям provider потрібен розв’язаний runtime-перегляд. Коли допоміжну функцію можуть викликати як з активним вихідним знімком, так і з активним runtime-знімком, перед читанням облікових даних спрямовуйте через `selectApplicableRuntimeConfig()`. ## Простори імен runtime @@ -109,26 +109,31 @@ register(api) { }); ``` - `runEmbeddedAgent(...)` — нейтральна допоміжна функція для запуску звичайного ходу агента OpenClaw з коду plugin. Вона використовує те саме визначення провайдера/моделі та вибір agent-harness, що й відповіді, запущені каналом. + `runEmbeddedAgent(...)` — нейтральна допоміжна функція для запуску звичайного ходу агента OpenClaw з коду plugin. Вона використовує те саме розв’язання provider/model і вибір agent-harness, що й відповіді, запущені каналом. - `runEmbeddedPiAgent(...)` залишається псевдонімом сумісності. + `runEmbeddedPiAgent(...)` залишається alias для сумісності. - `resolveThinkingPolicy(...)` повертає підтримувані рівні thinking для провайдера/моделі та необов’язкове значення за замовчуванням. Provider plugins володіють профілем, специфічним для моделі, через свої thinking hooks, тому tool plugins мають викликати цю runtime-допоміжну функцію замість імпорту або дублювання списків провайдерів. + `resolveThinkingPolicy(...)` повертає підтримувані рівні мислення provider/model і необов’язкове значення за замовчуванням. Provider plugins володіють профілем, специфічним для моделі, через свої thinking hooks, тому tool plugins мають викликати цю runtime-допоміжну функцію замість імпорту або дублювання списків provider. - `normalizeThinkingLevel(...)` перетворює текст користувача, як-от `on`, `x-high` або `extra high`, на канонічний збережений рівень перед перевіркою його відповідності розв’язаній політиці. + `normalizeThinkingLevel(...)` перетворює користувацький текст, як-от `on`, `x-high` або `extra high`, на канонічний збережений рівень перед перевіркою щодо розв’язаної політики. - **Допоміжні функції сховища сеансів** містяться в `api.runtime.agent.session`: + **Допоміжні функції сховища сеансів** розміщені в `api.runtime.agent.session`: ```typescript const storePath = api.runtime.agent.session.resolveStorePath(cfg); - const store = api.runtime.agent.session.loadSessionStore(cfg); - await api.runtime.agent.session.saveSessionStore(cfg, store); + const store = api.runtime.agent.session.loadSessionStore(storePath); + await api.runtime.agent.session.updateSessionStore(storePath, (nextStore) => { + // Patch one entry without replacing the whole file from stale state. + nextStore[sessionKey] = { ...nextStore[sessionKey], thinkingLevel: "high" }; + }); const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId); ``` + Надавайте перевагу `updateSessionStore(...)` або `updateSessionStoreEntry(...)` для runtime-записів. Вони проходять через writer сховища сеансів, яким володіє Gateway, зберігають паралельні оновлення та повторно використовують гарячий кеш. `saveSessionStore(...)` залишається доступним для сумісності та офлайн-перезаписів у стилі технічного обслуговування. + - Константи моделі й провайдера за замовчуванням: + Константи моделі та provider за замовчуванням: ```typescript const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6" @@ -137,7 +142,7 @@ register(api) { - Запускайте фонові виконання subagent і керуйте ними. + Запускайте й керуйте фоновими запусками subagent. ```typescript // Start a subagent run @@ -165,14 +170,14 @@ register(api) { ``` - Перевизначення моделі (`provider`/`model`) потребують явної згоди оператора через `plugins.entries..subagent.allowModelOverride: true` у конфігурації. Недовірені plugins усе ще можуть запускати subagents, але запити на перевизначення відхиляються. + Перевизначення моделі (`provider`/`model`) потребують згоди оператора через `plugins.entries..subagent.allowModelOverride: true` у конфігурації. Недовірені plugins усе ще можуть запускати subagents, але запити на перевизначення відхиляються. - `deleteSession(...)` може видаляти сеанси, створені тим самим plugin через `api.runtime.subagent.run(...)`. Видалення довільних сеансів користувача або оператора все ще потребує Gateway-запиту з admin-областю. + `deleteSession(...)` може видаляти сеанси, створені тим самим plugin через `api.runtime.subagent.run(...)`. Видалення довільних користувацьких або операторських сеансів і надалі потребує запиту Gateway з admin-областю. - Перелічуйте підключені nodes і викликайте команду node-хоста з коду plugin, завантаженого Gateway, або з CLI-команд plugin. Використовуйте це, коли plugin володіє локальною роботою на спареному пристрої, наприклад браузерним або аудіомостом на іншому Mac. + Перелічуйте підключені вузли та викликайте команду node-host з коду plugin, завантаженого Gateway, або з CLI-команд plugin. Використовуйте це, коли plugin володіє локальною роботою на спареному пристрої, наприклад браузером або аудіомостом на іншому Mac. ```typescript const { nodes } = await api.runtime.nodes.list({ connected: true }); @@ -185,13 +190,13 @@ register(api) { }); ``` - Усередині Gateway цей runtime є in-process. У CLI-командах plugin він викликає налаштований Gateway через RPC, тому такі команди, як `openclaw googlemeet recover-tab`, можуть перевіряти спарені nodes з термінала. Команди Node все ще проходять через звичайне спарювання nodes у Gateway, allowlist команд, політики node-invoke plugin і локальну обробку команд node. + Усередині Gateway цей runtime працює в процесі. У CLI-командах plugin він викликає налаштований Gateway через RPC, тож такі команди, як `openclaw googlemeet recover-tab`, можуть перевіряти спарені вузли з термінала. Команди Node і надалі проходять звичайне pairing вузлів Gateway, allowlists команд, політики node-invoke plugin і локальну обробку команд на вузлі. - Plugins, які надають небезпечні команди node-хоста, мають зареєструвати політику node-invoke за допомогою `api.registerNodeInvokePolicy(...)`. Політика виконується в Gateway після перевірок allowlist команд і перед пересиланням команди до node, тому прямі виклики `node.invoke` та інструменти plugin вищого рівня мають той самий шлях застосування правил. + Plugins, які відкривають небезпечні команди node-host, мають реєструвати політику node-invoke через `api.registerNodeInvokePolicy(...)`. Політика виконується в Gateway після перевірок allowlist команд і перед пересиланням команди до вузла, тож прямі виклики `node.invoke` і високорівневі інструменти plugin мають спільний шлях застосування правил. - Прив’яжіть runtime Task Flow до наявного ключа сеансу OpenClaw або довіреного контексту інструмента, а потім створюйте Task Flows і керуйте ними без передавання власника в кожному виклику. + Прив’яжіть runtime Task Flow до наявного ключа сеансу OpenClaw або довіреного контексту інструмента, а потім створюйте й керуйте Task Flows без передавання власника в кожному виклику. ```typescript const taskFlow = api.runtime.tasks.managedFlows.fromToolContext(ctx); @@ -218,7 +223,7 @@ register(api) { }); ``` - Використовуйте `bindSession({ sessionKey, requesterOrigin })`, коли у вас уже є довірений ключ сеансу OpenClaw із власного шару прив’язки. Не прив’язуйте з необробленого введення користувача. + Використовуйте `bindSession({ sessionKey, requesterOrigin })`, коли вже маєте довірений ключ сеансу OpenClaw з власного шару прив’язки. Не прив’язуйте з необробленого користувацького введення. @@ -244,7 +249,7 @@ register(api) { }); ``` - Використовує базову конфігурацію `messages.tts` і вибір провайдера. Повертає аудіобуфер PCM + частоту дискретизації. + Використовує базову конфігурацію `messages.tts` і вибір provider. Повертає аудіобуфер PCM + частоту дискретизації. @@ -337,7 +342,7 @@ register(api) { - Поточний знімок конфігурації runtime і транзакційні записи конфігурації. Надавайте перевагу + Поточний знімок конфігурації runtime та транзакційні записи конфігурації. Надавайте перевагу конфігурації, яку вже було передано в активний шлях виклику; використовуйте `current()` лише тоді, коли обробнику потрібен безпосередньо знімок процесу. @@ -354,7 +359,7 @@ register(api) { `mutateConfigFile(...)` і `replaceConfigFile(...)` повертають значення `followUp`, наприклад `{ mode: "restart", requiresRestart: true, reason }`, яке фіксує намір записувача, не забираючи керування перезапуском у - Gateway. + gateway. @@ -391,7 +396,7 @@ register(api) { - Визначення автентифікації моделі та провайдера. + Розв’язання автентифікації моделі та провайдера. ```typescript const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg }); @@ -403,7 +408,7 @@ register(api) { - Визначення каталогу стану та ключове сховище на базі SQLite. + Розв’язання каталогу стану та сховище ключів на базі SQLite. ```typescript const stateDir = api.runtime.state.resolveStateDir(process.env); @@ -419,7 +424,7 @@ register(api) { await store.clear(); ``` - Ключові сховища переживають перезапуски та ізольовані за id Plugin, прив’язаним до runtime. Обмеження: `maxEntries` на простір імен, 1 000 активних рядків на Plugin, значення JSON до 64 КБ і необов’язкове завершення строку дії TTL. + Сховища ключів переживають перезапуски й ізольовані за прив’язаним до runtime ідентифікатором Plugin. Обмеження: `maxEntries` на простір імен, 1 000 активних рядків на Plugin, значення JSON до 64 КБ і необов’язкове завершення строку дії за TTL. У цьому випуску лише вбудовані plugins. @@ -437,7 +442,7 @@ register(api) { - Допоміжні засоби runtime, специфічні для каналів (доступні, коли завантажено Plugin каналу). + Допоміжні засоби runtime для конкретних каналів (доступні, коли завантажено plugin каналу). `api.runtime.channel.mentions` — це спільна поверхня політики вхідних згадок для вбудованих plugins каналів, які використовують ін’єкцію runtime: @@ -474,7 +479,7 @@ register(api) { - `implicitMentionKindWhen` - `resolveInboundMentionDecision` - `api.runtime.channel.mentions` навмисно не надає старі сумісні допоміжні засоби `resolveMentionGating*`. Надавайте перевагу нормалізованому шляху `{ facts, policy }`. + `api.runtime.channel.mentions` навмисно не надає старі допоміжні засоби сумісності `resolveMentionGating*`. Надавайте перевагу нормалізованому шляху `{ facts, policy }`. @@ -484,7 +489,7 @@ register(api) { Використовуйте `createPluginRuntimeStore`, щоб зберігати посилання runtime для використання поза callback `register`: - + ```typescript import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store"; @@ -496,7 +501,7 @@ register(api) { ``` - + ```typescript export default defineChannelPluginEntry({ id: "my-plugin", @@ -507,7 +512,7 @@ register(api) { }); ``` - + ```typescript export function getRuntime() { return store.getRuntime(); // throws if not initialized @@ -522,7 +527,7 @@ register(api) { -Надавайте перевагу `pluginId` для ідентичності runtime-store. Нижчорівнева форма `key` призначена для нетипових випадків, коли одному Plugin навмисно потрібно більше ніж один слот runtime. +Надавайте перевагу `pluginId` для ідентичності runtime-store. Нижчорівнева форма `key` призначена для нетипових випадків, коли одному plugin навмисно потрібно більше ніж один слот runtime. ## Інші поля верхнього рівня `api` @@ -530,29 +535,29 @@ register(api) { Окрім `api.runtime`, об’єкт API також надає: - Id Plugin. + Ідентифікатор Plugin. Відображувана назва Plugin. - Поточний знімок конфігурації (активний знімок runtime у пам’яті, коли доступний). + Поточний знімок конфігурації (активний знімок runtime в пам’яті, коли доступний). - Конфігурація, специфічна для Plugin, з `plugins.entries..config`. + Конфігурація конкретного Plugin з `plugins.entries..config`. - Обмежений за областю logger (`debug`, `info`, `warn`, `error`). + Журналювач з областю дії (`debug`, `info`, `warn`, `error`). Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування перед повним входом. - Визначає шлях відносно кореня Plugin. + Розв’язати шлях відносно кореня plugin. ## Пов’язане -- [Внутрішня архітектура Plugin](/uk/plugins/architecture) — модель можливостей і реєстр +- [Внутрішні механізми Plugin](/uk/plugins/architecture) — модель можливостей і реєстр - [Точки входу SDK](/uk/plugins/sdk-entrypoints) — параметри `definePluginEntry` -- [Огляд SDK](/uk/plugins/sdk-overview) — довідник підшляхів +- [Огляд SDK](/uk/plugins/sdk-overview) — довідка щодо підшляхів diff --git a/docs/uk/reference/session-management-compaction.md b/docs/uk/reference/session-management-compaction.md index 1d3592cd2..9943c063c 100644 --- a/docs/uk/reference/session-management-compaction.md +++ b/docs/uk/reference/session-management-compaction.md @@ -1,28 +1,28 @@ --- read_when: - - Вам потрібно налагодити ідентифікатори сесій, JSONL транскриптів або поля sessions.json - - Ви змінюєте поведінку автоматичної Compaction або додаєте службове впорядкування перед “Compaction” - - Ви хочете реалізувати очищення пам’яті або тихі системні репліки -summary: 'Глибокий огляд: сховище сеансів + транскрипти, життєвий цикл і внутрішні механізми (авто)Compaction' + - Потрібно налагодити ідентифікатори сеансів, JSONL транскриптів або поля sessions.json + - Ви змінюєте поведінку автоматичної Compaction або додаєте підготовче обслуговування перед Compaction + - Ви хочете реалізувати очищення пам’яті або тихі системні ходи +summary: 'Докладно: сховище сеансів і транскрипти, життєвий цикл та внутрішні механізми (авто)Compaction' title: Поглиблений огляд керування сеансами x-i18n: - generated_at: "2026-05-02T06:40:11Z" + generated_at: "2026-05-02T12:15:50Z" model: gpt-5.5 provider: openai - source_hash: b9ca8a35210625051f5051e90a18a005d6103bc1d65d356c34f818d2bfc0058c + source_hash: 6e2097d685381964608096cc0505aeedbd3a8f9bc682168bd519ebe4ffe9218d source_path: reference/session-management-compaction.md workflow: 16 --- -OpenClaw керує сесіями від початку до кінця в таких сферах: +OpenClaw керує сесіями наскрізно в таких областях: - **Маршрутизація сесій** (як вхідні повідомлення зіставляються з `sessionKey`) - **Сховище сесій** (`sessions.json`) і що воно відстежує -- **Збереження транскриптів** (`*.jsonl`) та їхня структура -- **Гігієна транскриптів** (специфічні для провайдера виправлення перед запусками) -- **Обмеження контексту** (контекстне вікно проти відстежуваних токенів) -- **Compaction** (ручний і автоматичний Compaction) і де підключати роботу перед Compaction -- **Тихе обслуговування** (записи в пам’ять, які не мають створювати видимий для користувача вивід) +- **Збереження стенограм** (`*.jsonl`) та їхня структура +- **Гігієна стенограм** (специфічні для провайдера виправлення перед запусками) +- **Ліміти контексту** (контекстне вікно проти відстежуваних токенів) +- **Compaction** (ручна й автоматична Compaction) і де підключати роботу перед Compaction +- **Тихе обслуговування** (записи пам’яті, які не мають створювати видимого для користувача виводу) Якщо спершу потрібен огляд вищого рівня, почніть із: @@ -30,17 +30,17 @@ OpenClaw керує сесіями від початку до кінця в та - [Compaction](/uk/concepts/compaction) - [Огляд пам’яті](/uk/concepts/memory) - [Пошук у пам’яті](/uk/concepts/memory-search) -- [Обрізання сесій](/uk/concepts/session-pruning) -- [Гігієна транскриптів](/uk/reference/transcript-hygiene) +- [Очищення сесій](/uk/concepts/session-pruning) +- [Гігієна стенограм](/uk/reference/transcript-hygiene) --- ## Джерело істини: Gateway -OpenClaw спроєктовано навколо одного **процесу Gateway**, який володіє станом сесій. +OpenClaw спроєктовано навколо єдиного **процесу Gateway**, який володіє станом сесій. -- Інтерфейси користувача (застосунок macOS, веб Control UI, TUI) мають запитувати Gateway для списків сесій і кількості токенів. -- У віддаленому режимі файли сесій розташовані на віддаленому хості; «перевірка ваших локальних файлів Mac» не відображатиме те, що використовує Gateway. +- UI (застосунок macOS, веб Control UI, TUI) мають запитувати в Gateway списки сесій і кількість токенів. +- У віддаленому режимі файли сесій розташовані на віддаленому хості; «перевірка локальних файлів на Mac» не відображатиме того, що використовує Gateway. --- @@ -53,18 +53,18 @@ OpenClaw зберігає сесії на двох рівнях: - Невелике, змінюване, безпечне для редагування (або видалення записів) - Відстежує метадані сесії (поточний ідентифікатор сесії, останню активність, перемикачі, лічильники токенів тощо) -2. **Транскрипт (`.jsonl`)** - - Транскрипт лише з додаванням зі структурою дерева (записи мають `id` + `parentId`) +2. **Стенограма (`.jsonl`)** + - Стенограма лише з додаванням із деревоподібною структурою (записи мають `id` + `parentId`) - Зберігає фактичну розмову + виклики інструментів + підсумки Compaction - Використовується для відновлення контексту моделі для майбутніх ходів - - Великі контрольні точки налагодження перед Compaction пропускаються, щойно активний - транскрипт перевищує ліміт розміру контрольної точки, щоб уникнути другої гігантської + - Великі налагоджувальні контрольні точки перед Compaction пропускаються, щойно активна + стенограма перевищує обмеження розміру контрольної точки, щоб уникнути другої гігантської копії `.checkpoint.*.jsonl`. -Зчитувачі історії Gateway мають уникати матеріалізації всього транскрипту, якщо -поверхня явно не потребує довільного історичного доступу. Історія першої сторінки, -вбудована історія чату, відновлення після перезапуску та перевірки токенів/використання застосовують обмежене читання хвоста. -Повні сканування транскрипту проходять через асинхронний індекс транскриптів, який +Зчитувачі історії Gateway мають уникати матеріалізації всієї стенограми, якщо +поверхні явно не потрібен довільний історичний доступ. Історія першої сторінки, +вбудована історія чату, відновлення після перезапуску та перевірки токенів/використання +використовують обмежене читання хвоста. Повні сканування стенограми проходять через асинхронний індекс стенограм, який кешується за шляхом файлу плюс `mtimeMs`/`size` і спільно використовується паралельними зчитувачами. --- @@ -74,40 +74,40 @@ OpenClaw зберігає сесії на двох рівнях: Для кожного агента, на хості Gateway: - Сховище: `~/.openclaw/agents//sessions/sessions.json` -- Транскрипти: `~/.openclaw/agents//sessions/.jsonl` +- Стенограми: `~/.openclaw/agents//sessions/.jsonl` - Сесії тем Telegram: `.../-topic-.jsonl` -OpenClaw визначає їх через `src/config/sessions.ts`. +OpenClaw визначає ці шляхи через `src/config/sessions.ts`. --- -## Обслуговування сховища та контроль диска +## Обслуговування сховища та керування диском -Збереження сесій має автоматичні засоби обслуговування (`session.maintenance`) для `sessions.json`, артефактів транскриптів і супровідних файлів траєкторій: +Збереження сесій має автоматичні засоби обслуговування (`session.maintenance`) для `sessions.json`, артефактів стенограм і побічних файлів траєкторій: - `mode`: `warn` (типово) або `enforce` -- `pruneAfter`: поріг віку застарілих записів (типово `30d`) -- `maxEntries`: ліміт записів у `sessions.json` (типово `500`) -- `resetArchiveRetention`: строк зберігання архівів транскриптів `*.reset.` (типово: такий самий, як `pruneAfter`; `false` вимикає очищення) +- `pruneAfter`: віковий поріг для застарілих записів (типово `30d`) +- `maxEntries`: обмеження кількості записів у `sessions.json` (типово `500`) +- `resetArchiveRetention`: термін зберігання архівів стенограм `*.reset.` (типово: такий самий, як `pruneAfter`; `false` вимикає очищення) - `maxDiskBytes`: необов’язковий бюджет каталогу сесій - `highWaterBytes`: необов’язкова ціль після очищення (типово `80%` від `maxDiskBytes`) -Звичайні записи Gateway групують очищення `maxEntries` для лімітів виробничого розміру, тому сховище може короткочасно перевищувати налаштований ліміт, перш ніж наступне очищення верхньої межі перепише його назад до меншого розміру. Читання сховища сесій не обрізають і не обмежують записи під час запуску Gateway; для очищення використовуйте записи або `openclaw sessions cleanup --enforce`. `openclaw sessions cleanup --enforce` усе одно негайно застосовує налаштований ліміт. +Звичайні записи Gateway проходять через окремий для сховища записувач сесій, який серіалізує внутрішньопроцесні мутації без отримання файлового блокування під час виконання. Допоміжні засоби виправлення гарячого шляху позичають перевірений змінюваний кеш, поки утримують цей слот записувача, тому великі файли `sessions.json` не клонуються й не перечитуються для кожного оновлення метаданих. Код під час виконання має віддавати перевагу `updateSessionStore(...)` або `updateSessionStoreEntry(...)`; прямі збереження всього сховища є інструментами сумісності та офлайн-обслуговування. Коли Gateway доступний, `openclaw sessions cleanup --enforce` делегує обслуговування Gateway, щоб очищення приєдналося до тієї самої черги записувача; `--store ` — явний офлайн-шлях ремонту для прямого обслуговування файлів. Очищення `maxEntries` досі пакетне для обмежень виробничого розміру, тож сховище може ненадовго перевищити налаштоване обмеження, перш ніж наступне очищення до верхньої межі перепише його назад до меншого розміру. Читання сховища сесій не очищує й не обмежує записи під час запуску Gateway; для очищення використовуйте записи або `openclaw sessions cleanup --enforce`. `openclaw sessions cleanup --enforce` усе одно негайно застосовує налаштоване обмеження. -Обслуговування зберігає тривкі зовнішні покажчики розмов, як-от групові сесії -та сесії чату в межах гілки, але синтетичні runtime-записи для Cron, hooks, -Heartbeat, ACP і субагентів усе ще можуть видалятися, коли перевищують +Обслуговування зберігає довговічні зовнішні вказівники розмов, як-от групові сесії +та сесії чату в межах потоків, але синтетичні записи виконання для cron, хуків, +heartbeat, ACP і субагентів усе ще можуть видалятися, коли вони перевищують налаштований вік, кількість або дисковий бюджет. -OpenClaw більше не створює автоматичні ротаційні резервні копії `sessions.json.bak.*` під час записів Gateway. Застарілий ключ `session.maintenance.rotateBytes` ігнорується, а `openclaw doctor --fix` видаляє його зі старіших конфігурацій. +OpenClaw більше не створює автоматичних ротаційних резервних копій `sessions.json.bak.*` під час записів Gateway. Застарілий ключ `session.maintenance.rotateBytes` ігнорується, а `openclaw doctor --fix` видаляє його зі старіших конфігурацій. -Порядок застосування очищення дискового бюджету (`mode: "enforce"`): +Порядок примусового застосування для очищення дискового бюджету (`mode: "enforce"`): -1. Спершу видалити найстаріші архівовані, осиротілі артефакти транскриптів або осиротілі артефакти траєкторій. -2. Якщо все ще вище цілі, витіснити найстаріші записи сесій і їхні файли транскриптів/траєкторій. -3. Продовжувати, доки використання не буде на рівні або нижче `highWaterBytes`. +1. Спершу видалити найстаріші архівні, осиротілі артефакти стенограм або осиротілі артефакти траєкторій. +2. Якщо розмір усе ще перевищує ціль, вилучити найстаріші записи сесій і їхні файли стенограм/траєкторій. +3. Продовжувати, доки використання не стане на рівні `highWaterBytes` або нижче. -У `mode: "warn"` OpenClaw повідомляє про потенційні витіснення, але не змінює сховище/файли. +У `mode: "warn"` OpenClaw повідомляє про потенційні вилучення, але не змінює сховище/файли. Запуск обслуговування на вимогу: @@ -120,48 +120,47 @@ openclaw sessions cleanup --enforce ## Сесії Cron і журнали запусків -Ізольовані запуски Cron також створюють записи сесій/транскрипти та мають окремі засоби керування зберіганням: +Ізольовані запуски cron також створюють записи сесій/стенограми та мають окремі засоби керування терміном зберігання: -- `cron.sessionRetention` (типово `24h`) обрізає старі ізольовані сесії запусків Cron зі сховища сесій (`false` вимикає). -- `cron.runLog.maxBytes` + `cron.runLog.keepLines` обрізають файли `~/.openclaw/cron/runs/.jsonl` (типово: `2_000_000` байтів і `2000` рядків). +- `cron.sessionRetention` (типово `24h`) очищує старі ізольовані сесії запусків cron зі сховища сесій (`false` вимикає). +- `cron.runLog.maxBytes` + `cron.runLog.keepLines` очищують файли `~/.openclaw/cron/runs/.jsonl` (типово: `2_000_000` байтів і `2000` рядків). -Коли Cron примусово створює нову ізольовану сесію запуску, він санітизує попередній +Коли cron примусово створює нову ізольовану сесію запуску, він очищує попередній запис сесії `cron:` перед записом нового рядка. Він переносить безпечні -налаштування, як-от thinking/fast/verbose, мітки та явно -вибрані користувачем перевизначення моделі/автентифікації. Він відкидає навколишній контекст розмови, як-от -маршрутизацію каналу/групи, політику надсилання або черги, підвищення прав, походження та -runtime-прив’язку ACP, щоб новий ізольований запуск не міг успадкувати застарілу доставку або -runtime-повноваження від старішого запуску. +параметри, як-от налаштування мислення/швидкості/детальності, мітки та явні +перевизначення моделі/автентифікації, вибрані користувачем. Він відкидає навколишній контекст розмови, як-от маршрутизацію каналу/групи, політику надсилання або черги, підвищення прав, походження та +прив’язку виконання ACP, щоб новий ізольований запуск не міг успадкувати застарілу доставку або +повноваження виконання від старішого запуску. --- ## Ключі сесій (`sessionKey`) -`sessionKey` визначає, у якому _контейнері розмови_ ви перебуваєте (маршрутизація + ізоляція). +`sessionKey` визначає, _у якому контейнері розмови_ ви перебуваєте (маршрутизація + ізоляція). Поширені шаблони: -- Основний/прямий чат (для агента): `agent::` (типово `main`) +- Основний/прямий чат (для кожного агента): `agent::` (типово `main`) - Група: `agent:::group:` - Кімната/канал (Discord/Slack): `agent:::channel:` або `...:room:` - Cron: `cron:` - Webhook: `hook:` (якщо не перевизначено) -Канонічні правила задокументовано на [/concepts/session](/uk/concepts/session). +Канонічні правила задокументовано в [/concepts/session](/uk/concepts/session). --- ## Ідентифікатори сесій (`sessionId`) -Кожен `sessionKey` вказує на поточний `sessionId` (файл транскрипту, який продовжує розмову). +Кожен `sessionKey` вказує на поточний `sessionId` (файл стенограми, який продовжує розмову). Практичні правила: - **Скидання** (`/new`, `/reset`) створює новий `sessionId` для цього `sessionKey`. -- **Щоденне скидання** (типово о 4:00 AM за локальним часом на хості Gateway) створює новий `sessionId` у наступному повідомленні після межі скидання. -- **Закінчення строку бездіяльності** (`session.reset.idleMinutes` або застарілий `session.idleMinutes`) створює новий `sessionId`, коли повідомлення надходить після вікна бездіяльності. Коли налаштовані і щоденне скидання, і бездіяльність, спрацьовує те, що завершується першим. -- **Системні події** (Heartbeat, пробудження Cron, сповіщення exec, облік Gateway) можуть змінювати рядок сесії, але не подовжують свіжість щоденного/бездіяльного скидання. Перехід скидання відкидає сповіщення системних подій у черзі для попередньої сесії до побудови свіжого prompt. -- **Політика parent fork** використовує активну гілку Pi під час створення гілки або форка субагента. Якщо ця гілка завелика, OpenClaw запускає дочірній елемент з ізольованим контекстом замість помилки або успадкування непридатної історії. Політика визначення розміру автоматична; застарілу конфігурацію `session.parentForkMaxTokens` видаляє `openclaw doctor --fix`. +- **Щоденне скидання** (типово 4:00 AM за місцевим часом на хості Gateway) створює новий `sessionId` під час наступного повідомлення після межі скидання. +- **Закінчення строку через бездіяльність** (`session.reset.idleMinutes` або застарілий `session.idleMinutes`) створює новий `sessionId`, коли повідомлення надходить після вікна бездіяльності. Коли налаштовано і щоденне скидання, і бездіяльність, спрацьовує те, що завершується першим. +- **Системні події** (heartbeat, пробудження cron, сповіщення exec, службові дії gateway) можуть змінювати рядок сесії, але не подовжують актуальність щоденного/бездіяльного скидання. Перехід скидання відкидає поставлені в чергу сповіщення системних подій для попередньої сесії перед побудовою нового промпта. +- **Політика відгалуження від батька** використовує активну гілку PI під час створення потоку або відгалуження субагента. Якщо ця гілка занадто велика, OpenClaw запускає дочірній об’єкт з ізольованим контекстом замість помилки або успадкування непридатної історії. Політика визначення розміру автоматична; застарілу конфігурацію `session.parentForkMaxTokens` видаляє `openclaw doctor --fix`. Деталь реалізації: рішення ухвалюється в `initSessionState()` у `src/auto-reply/reply/session.ts`. @@ -173,51 +172,51 @@ runtime-повноваження від старішого запуску. Ключові поля (не вичерпно): -- `sessionId`: поточний ідентифікатор транскрипту (ім’я файлу виводиться з нього, якщо не встановлено `sessionFile`) -- `sessionStartedAt`: часова позначка початку поточного `sessionId`; щоденне скидання - використовує це для свіжості. Застарілі рядки можуть виводити її із заголовка сесії JSONL. -- `lastInteractionAt`: часова позначка останньої реальної взаємодії користувача/каналу; скидання через бездіяльність - використовує це для свіжості, щоб Heartbeat, Cron і exec-події не підтримували сесії - активними. Застарілі рядки без цього поля повертаються до відновленого часу початку сесії - для свіжості бездіяльності. -- `updatedAt`: часова позначка останньої зміни рядка сховища, використовується для списків, обрізання та - службового обліку. Вона не є джерелом істини для свіжості щоденного/бездіяльного скидання. -- `sessionFile`: необов’язкове явне перевизначення шляху транскрипту -- `chatType`: `direct | group | room` (допомагає інтерфейсам і політиці надсилання) -- `provider`, `subject`, `room`, `space`, `displayName`: метадані для позначення груп/каналів +- `sessionId`: поточний ідентифікатор стенограми (назва файлу виводиться з нього, якщо не задано `sessionFile`) +- `sessionStartedAt`: часова позначка початку для поточного `sessionId`; актуальність щоденного скидання + використовує її. Застарілі рядки можуть виводити її із заголовка сесії JSONL. +- `lastInteractionAt`: часова позначка останньої реальної взаємодії користувача/каналу; актуальність скидання через бездіяльність + використовує її, тому heartbeat, cron і події exec не підтримують сесії + активними. Застарілі рядки без цього поля для актуальності бездіяльності повертаються до відновленого часу початку + сесії. +- `updatedAt`: часова позначка останньої мутації рядка сховища, використовується для списків, очищення та + службового обліку. Вона не є джерелом істини для актуальності щоденного/бездіяльного скидання. +- `sessionFile`: необов’язкове явне перевизначення шляху стенограми +- `chatType`: `direct | group | room` (допомагає UI та політиці надсилання) +- `provider`, `subject`, `room`, `space`, `displayName`: метадані для маркування груп/каналів - Перемикачі: - `thinkingLevel`, `verboseLevel`, `reasoningLevel`, `elevatedLevel` - `sendPolicy` (перевизначення для окремої сесії) - Вибір моделі: - `providerOverride`, `modelOverride`, `authProfileOverride` -- Лічильники токенів (найкращі зусилля / залежить від провайдера): +- Лічильники токенів (best-effort / залежать від провайдера): - `inputTokens`, `outputTokens`, `totalTokens`, `contextTokens` -- `compactionCount`: як часто автоматичний Compaction завершувався для цього ключа сесії +- `compactionCount`: як часто автоматична Compaction завершувалась для цього ключа сесії - `memoryFlushAt`: часова позначка останнього скидання пам’яті перед Compaction -- `memoryFlushCompactionCount`: кількість Compaction, коли востаннє виконувався flush +- `memoryFlushCompactionCount`: кількість Compaction, коли востаннє запускалося скидання -Сховище безпечно редагувати, але Gateway є джерелом істини: він може переписувати або повторно гідратувати записи під час виконання сесій. +Сховище безпечно редагувати, але Gateway є джерелом істини: він може переписувати або повторно гідратувати записи під час роботи сесій. --- -## Структура транскрипту (`*.jsonl`) +## Структура стенограми (`*.jsonl`) -Транскриптами керує `SessionManager` з `@mariozechner/pi-coding-agent`. +Стенограмами керує `SessionManager` з `@mariozechner/pi-coding-agent`. Файл має формат JSONL: -- Перший рядок: заголовок сесії (`type: "session"`, містить `id`, `cwd`, `timestamp`, необов’язково `parentSession`) +- Перший рядок: заголовок сесії (`type: "session"`, містить `id`, `cwd`, `timestamp`, необов’язковий `parentSession`) - Далі: записи сесії з `id` + `parentId` (дерево) Важливі типи записів: -- `message`: повідомлення user/assistant/toolResult -- `custom_message`: повідомлення, ін’єктовані extension, які _входять_ у контекст моделі (можуть бути приховані від UI) -- `custom`: стан extension, який _не входить_ у контекст моделі -- `compaction`: збережений підсумок Compaction з `firstKeptEntryId` і `tokensBefore` +- `message`: повідомлення користувача/асистента/toolResult +- `custom_message`: повідомлення, вставлені розширенням, які _потрапляють_ у контекст моделі (можуть бути приховані від UI) +- `custom`: стан розширення, який _не потрапляє_ у контекст моделі +- `compaction`: збережений підсумок Compaction із `firstKeptEntryId` і `tokensBefore` - `branch_summary`: збережений підсумок під час навігації гілкою дерева -OpenClaw навмисно **не** «виправляє» транскрипти; Gateway використовує `SessionManager` для їх читання/запису. +OpenClaw навмисно **не** «виправляє» стенограми; Gateway використовує `SessionManager` для їх читання/запису. --- @@ -225,54 +224,54 @@ OpenClaw навмисно **не** «виправляє» транскрипти Важливі два різні поняття: -1. **Контекстне вікно моделі**: жорсткий ліміт для кожної моделі (токени, видимі моделі) -2. **Лічильники сховища сесій**: ковзна статистика, що записується в `sessions.json` (використовується для /status і dashboard) +1. **Контекстне вікно моделі**: жорстке обмеження для кожної моделі (токени, видимі моделі) +2. **Лічильники сховища сесій**: ковзна статистика, записана в `sessions.json` (використовується для /status і панелей) -Якщо ви налаштовуєте ліміти: +Якщо ви налаштовуєте обмеження: -- Контекстне вікно надходить із каталогу моделей (і може бути перевизначене через конфігурацію). -- `contextTokens` у сховищі — runtime-оцінка/звітне значення; не сприймайте його як сувору гарантію. +- Контекстне вікно походить із каталогу моделей (і може бути перевизначене через конфігурацію). +- `contextTokens` у сховищі — це оцінка/звітне значення під час виконання; не вважайте його суворою гарантією. Докладніше див. [/token-use](/uk/reference/token-use). --- -## Compaction: що це +## Compaction: що це таке -Compaction підсумовує старішу розмову в збережений запис `compaction` у транскрипті та залишає недавні повідомлення без змін. +Compaction підсумовує старішу розмову в збережений запис `compaction` у стенограмі та залишає останні повідомлення без змін. Після Compaction майбутні ходи бачать: - Підсумок Compaction - Повідомлення після `firstKeptEntryId` -Compaction є **постійним** (на відміну від обрізання сесій). Див. [/concepts/session-pruning](/uk/concepts/session-pruning). +Compaction є **сталою** (на відміну від очищення сесій). Див. [/concepts/session-pruning](/uk/concepts/session-pruning). ## Межі фрагментів Compaction і поєднання інструментів -Коли OpenClaw розбиває довгий транскрипт на фрагменти Compaction, він зберігає -виклики інструментів assistant разом із відповідними записами `toolResult`. +Коли OpenClaw розбиває довгу стенограму на фрагменти Compaction, він зберігає +виклики інструментів асистента в парі з відповідними записами `toolResult`. -- Якщо розділення за часткою токенів потрапляє між викликом інструмента та його результатом, OpenClaw - зміщує межу до повідомлення assistant із викликом інструмента замість розділення - пари. -- Якщо кінцевий блок результатів інструментів інакше вивів би фрагмент за ціль, - OpenClaw зберігає цей очікуваний блок інструментів і залишає непідсумований хвіст - без змін. -- Перервані/помилкові блоки викликів інструментів не утримують очікуване розділення відкритим. +- Якщо поділ за часткою токенів припадає між викликом інструмента та його результатом, OpenClaw + зміщує межу до повідомлення асистента з викликом інструмента замість того, щоб розділяти + цю пару. +- Якщо кінцевий блок результату інструмента інакше виштовхнув би фрагмент за цільовий розмір, + OpenClaw зберігає цей очікуваний блок інструмента й залишає нескорочений хвіст + неушкодженим. +- Перервані/помилкові блоки виклику інструмента не утримують очікуваний поділ відкритим. --- -## Коли відбувається автоматичний Compaction (runtime Pi) +## Коли відбувається автоматичне ущільнення (середовище виконання Pi) -У вбудованому агенті Pi автоматичний Compaction запускається у двох випадках: +У вбудованому агенті Pi автоматичне ущільнення запускається у двох випадках: 1. **Відновлення після переповнення**: модель повертає помилку переповнення контексту (`request_too_large`, `context length exceeded`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model`, `ollama error: context length -exceeded` і подібні варіанти у форматі провайдерів) → compact → retry. -2. **Підтримка порога**: після успішного ходу, коли: +exceeded` та подібні варіанти, сформовані провайдерами) → ущільнити → повторити. +2. **Підтримання порога**: після успішного ходу, коли: `contextTokens > contextWindow - reserveTokens` @@ -281,34 +280,34 @@ exceeded` і подібні варіанти у форматі провайде - `contextWindow` — контекстне вікно моделі - `reserveTokens` — запас, зарезервований для промптів + наступного виводу моделі -Це семантика runtime Pi (OpenClaw споживає події, але Pi вирішує, коли compact). +Це семантика середовища виконання Pi (OpenClaw споживає події, але Pi вирішує, коли виконувати ущільнення). -OpenClaw також може запускати попередню локальну Compaction перед відкриттям наступного -запуску, коли встановлено `agents.defaults.compaction.maxActiveTranscriptBytes` і -активний файл транскрипта досягає цього розміру. Це захист за розміром файла для локальної -вартості повторного відкриття, а не сирого архівування: OpenClaw усе одно запускає звичайну семантичну Compaction, +OpenClaw також може запускати попереднє локальне ущільнення перед відкриттям наступного +запуску, коли задано `agents.defaults.compaction.maxActiveTranscriptBytes` і +активний файл транскрипту досягає цього розміру. Це обмежувач розміру файлу для вартості +локального повторного відкриття, а не сире архівування: OpenClaw усе одно запускає звичайне семантичне ущільнення, і для цього потрібен `truncateAfterCompaction`, щоб ущільнений підсумок міг стати новим наступним транскриптом. -Для вбудованих запусків Pi, `agents.defaults.compaction.midTurnPrecheck.enabled: true` -додає опційний захист циклу інструментів. Після додавання результату інструмента та перед -наступним викликом моделі OpenClaw оцінює тиск на промпт, використовуючи ту саму логіку попереднього -бюджету, що й на початку ходу. Якщо контекст більше не вміщується, захист не -виконує compact усередині хуку Pi `transformContext`. Він піднімає структурований -сигнал попередньої перевірки посеред ходу, зупиняє поточне надсилання промпта й дає +Для вбудованих запусків Pi `agents.defaults.compaction.midTurnPrecheck.enabled: true` +додає опційний захист циклу інструментів. Після додавання результату інструмента й перед +наступним викликом моделі OpenClaw оцінює навантаження на промпт за тією самою логікою +попереднього бюджету, що використовується на початку ходу. Якщо контекст більше не вміщується, захист +не виконує ущільнення всередині хука Pi `transformContext`. Він піднімає структурований +сигнал попередньої перевірки посеред ходу, зупиняє поточне подання промпта й дає зовнішньому циклу запуску використати наявний шлях відновлення: обрізати завеликі результати інструментів, -коли цього достатньо, або запустити налаштований режим Compaction і повторити спробу. Опцію -вимкнено за замовчуванням, і вона працює з режимами Compaction `default` і `safeguard`, -зокрема з Compaction через провайдера safeguard. -Це незалежно від `maxActiveTranscriptBytes`: захист за розміром у байтах запускається -до відкриття ходу, тоді як попередня перевірка посеред ходу запускається пізніше у вбудованому циклі інструментів Pi +коли цього достатньо, або запустити налаштований режим ущільнення й повторити. Ця +опція вимкнена за замовчуванням і працює з режимами ущільнення `default` і `safeguard`, +зокрема з ущільненням safeguard на основі провайдера. +Це не залежить від `maxActiveTranscriptBytes`: обмежувач за розміром у байтах запускається +перед відкриттям ходу, а попередня перевірка посеред ходу запускається пізніше у вбудованому циклі інструментів Pi після додавання нових результатів інструментів. --- -## Налаштування Compaction (`reserveTokens`, `keepRecentTokens`) +## Налаштування ущільнення (`reserveTokens`, `keepRecentTokens`) -Налаштування Compaction Pi містяться в налаштуваннях Pi: +Налаштування ущільнення Pi містяться в налаштуваннях Pi: ```json5 { @@ -320,52 +319,52 @@ OpenClaw також може запускати попередню локаль } ``` -OpenClaw також застосовує безпечний мінімум для вбудованих запусків: +OpenClaw також застосовує мінімальний безпечний поріг для вбудованих запусків: - Якщо `compaction.reserveTokens < reserveTokensFloor`, OpenClaw підвищує його. -- Типовий мінімум — `20000` токенів. -- Установіть `agents.defaults.compaction.reserveTokensFloor: 0`, щоб вимкнути мінімум. -- Якщо значення вже вище, OpenClaw залишає його без змін. -- Ручний `/compact` враховує явний `agents.defaults.compaction.keepRecentTokens` - і зберігає точку відсікання недавнього хвоста Pi. Без явного бюджету збереження - ручна Compaction залишається жорсткою контрольною точкою, а перебудований контекст починається з +- Стандартний мінімум — `20000` токенів. +- Задайте `agents.defaults.compaction.reserveTokensFloor: 0`, щоб вимкнути цей мінімум. +- Якщо він уже вищий, OpenClaw залишає його без змін. +- Ручний `/compact` враховує явне `agents.defaults.compaction.keepRecentTokens` + і зберігає точку відсікання нещодавнього хвоста Pi. Без явного бюджету збереження + ручне ущільнення залишається жорсткою контрольною точкою, а перебудований контекст починається з нового підсумку. -- Установіть `agents.defaults.compaction.midTurnPrecheck.enabled: true`, щоб запускати - опційну попередню перевірку циклу інструментів після нових результатів інструментів і перед наступним - викликом моделі. Це лише тригер; генерація підсумку й далі використовує налаштований - шлях Compaction. Вона незалежна від `maxActiveTranscriptBytes`, який є - захистом за розміром у байтах активного транскрипта на початку ходу. -- Установіть `agents.defaults.compaction.maxActiveTranscriptBytes` у значення байтів або - рядок на кшталт `"20mb"`, щоб запускати локальну Compaction перед ходом, коли активний - транскрипт стає великим. Цей захист активний лише тоді, коли також увімкнено - `truncateAfterCompaction`. Залиште його невстановленим або встановіть `0`, щоб +- Задайте `agents.defaults.compaction.midTurnPrecheck.enabled: true`, щоб запускати + опційну попередню перевірку циклу інструментів після нових результатів інструментів і перед наступним викликом + моделі. Це лише тригер; створення підсумку все одно використовує налаштований + шлях ущільнення. Він не залежить від `maxActiveTranscriptBytes`, який є + обмежувачем розміру активного транскрипту в байтах на початку ходу. +- Задайте `agents.defaults.compaction.maxActiveTranscriptBytes` як значення в байтах або + рядок на кшталт `"20mb"`, щоб запускати локальне ущільнення перед ходом, коли активний + транскрипт стає великим. Цей захист активний лише коли + `truncateAfterCompaction` також увімкнено. Не задавайте його або задайте `0`, щоб вимкнути. -- Коли ввімкнено `agents.defaults.compaction.truncateAfterCompaction`, - OpenClaw після Compaction ротуює активний транскрипт у стиснутий наступний JSONL. - Старий повний транскрипт залишається в архіві та пов’язується з - контрольною точкою Compaction, а не переписується на місці. +- Коли `agents.defaults.compaction.truncateAfterCompaction` увімкнено, + OpenClaw після ущільнення ротуватиме активний транскрипт у ущільнений наступний JSONL. + Старий повний транскрипт лишається в архіві й посилається з контрольної точки + ущільнення, а не переписується на місці. -Навіщо: залишити достатньо запасу для багатоходового “службового обслуговування” (наприклад, записів пам’яті), перш ніж Compaction стане неминучою. +Причина: залишити достатній запас для багатоходового “обслуговування” (наприклад, записів пам’яті) до того, як ущільнення стане неминучим. Реалізація: `ensurePiCompactionReserveTokens()` у `src/agents/pi-settings.ts` (викликається з `src/agents/pi-embedded-runner.ts`). --- -## Підключувані провайдери Compaction +## Підключувані провайдери ущільнення -Plugins можуть зареєструвати провайдера Compaction через `registerCompactionProvider()` в API Plugin. Коли `agents.defaults.compaction.provider` встановлено на ідентифікатор зареєстрованого провайдера, розширення safeguard делегує підсумовування цьому провайдеру замість вбудованого пайплайна `summarizeInStages`. +Плагіни можуть реєструвати провайдера ущільнення через `registerCompactionProvider()` в API плагіна. Коли `agents.defaults.compaction.provider` задано як ідентифікатор зареєстрованого провайдера, розширення safeguard делегує підсумовування цьому провайдеру замість вбудованого конвеєра `summarizeInStages`. -- `provider`: ідентифікатор зареєстрованого Plugin-провайдера Compaction. Залиште невстановленим для типового LLM-підсумовування. -- Установлення `provider` примусово вмикає `mode: "safeguard"`. -- Провайдери отримують ті самі інструкції Compaction і політику збереження ідентифікаторів, що й вбудований шлях. -- Safeguard усе одно зберігає контекст суфікса недавнього ходу та розділеного ходу після виводу провайдера. +- `provider`: ідентифікатор зареєстрованого плагіна провайдера ущільнення. Не задавайте, щоб використовувати стандартне LLM-підсумовування. +- Задання `provider` примусово встановлює `mode: "safeguard"`. +- Провайдери отримують ті самі інструкції з ущільнення та політику збереження ідентифікаторів, що й вбудований шлях. +- Safeguard усе одно зберігає контекст суфікса нещодавнього ходу та розділеного ходу після виводу провайдера. - Вбудоване підсумовування safeguard повторно дистилює попередні підсумки з новими повідомленнями - замість того, щоб зберігати повний попередній підсумок дослівно. -- Режим safeguard вмикає аудити якості підсумків за замовчуванням; установіть - `qualityGuard.enabled: false`, щоб пропустити поведінку повторної спроби після некоректно сформованого виводу. -- Якщо провайдер зазнає збою або повертає порожній результат, OpenClaw автоматично повертається до вбудованого LLM-підсумовування. -- Сигнали переривання/тайм-ауту перекидаються повторно (не поглинаються), щоб поважати скасування викликачем. + замість дослівного збереження повного попереднього підсумку. +- Режим Safeguard за замовчуванням вмикає аудити якості підсумків; задайте + `qualityGuard.enabled: false`, щоб пропустити поведінку повтору в разі некоректно сформованого виводу. +- Якщо провайдер зазнає невдачі або повертає порожній результат, OpenClaw автоматично повертається до вбудованого LLM-підсумовування. +- Сигнали переривання/тайм-ауту повторно пробрасываются (не поглинаються), щоб поважати скасування викликача. Джерело: `src/plugins/compaction-provider.ts`, `src/agents/pi-hooks/compaction-safeguard.ts`. @@ -373,48 +372,48 @@ Plugins можуть зареєструвати провайдера Compaction ## Поверхні, видимі користувачу -Ви можете спостерігати Compaction і стан сесії через: +Ви можете спостерігати за ущільненням і станом сесії через: - `/status` (у будь-якій чат-сесії) - `openclaw status` (CLI) - `openclaw sessions` / `sessions --json` -- Докладний режим: `🧹 Auto-compaction complete` + лічильник Compaction +- Докладний режим: `🧹 Auto-compaction complete` + кількість ущільнень --- -## Тихе службове обслуговування (`NO_REPLY`) +## Тихе обслуговування (`NO_REPLY`) OpenClaw підтримує “тихі” ходи для фонових завдань, де користувач не має бачити проміжний вивід. -Домовленість: +Угода: - Асистент починає свій вивід з точного тихого токена `NO_REPLY` / - `no_reply`, щоб указати “не доставляти відповідь користувачу”. -- OpenClaw вилучає/пригнічує це на рівні доставки. -- Пригнічення точного тихого токена не залежить від регістру, тому `NO_REPLY` і + `no_reply`, щоб позначити “не доставляти відповідь користувачу”. +- OpenClaw видаляє/пригнічує це на рівні доставки. +- Пригнічення точного тихого токена нечутливе до регістру, тому `NO_REPLY` і `no_reply` обидва зараховуються, коли весь payload є лише тихим токеном. - Це лише для справді фонових ходів без доставки; це не скорочення для звичайних дієвих запитів користувача. -Станом на `2026.1.10`, OpenClaw також пригнічує **потокове передавання чернетки/набору** коли -частковий фрагмент починається з `NO_REPLY`, тож тихі операції не протікають частковим +Станом на `2026.1.10`, OpenClaw також пригнічує **потокову передачу чернетки/набору** коли +частковий фрагмент починається з `NO_REPLY`, тому тихі операції не витікають частковим виводом посеред ходу. --- -## “Скидання пам’яті” перед Compaction (реалізовано) +## Попереднє перед ущільненням "скидання пам’яті" (реалізовано) -Мета: перед автоматичною Compaction запустити тихий агентний хід, який записує довговічний -стан на диск (наприклад, `memory/YYYY-MM-DD.md` у робочому просторі агента), щоб Compaction не могла +Мета: перед автоматичним ущільненням запустити тихий агентний хід, який записує довговічний +стан на диск (наприклад, `memory/YYYY-MM-DD.md` у робочій області агента), щоб ущільнення не могло стерти критичний контекст. OpenClaw використовує підхід **скидання перед порогом**: 1. Відстежувати використання контексту сесії. -2. Коли воно перетинає “м’який поріг” (нижче порога Compaction Pi), запустити тиху +2. Коли воно перетинає “м’який поріг” (нижче порога ущільнення Pi), запустити тиху директиву “запиши пам’ять зараз” для агента. -3. Використати точний тихий токен `NO_REPLY` / `no_reply`, щоб користувач - нічого не бачив. +3. Використати точний тихий токен `NO_REPLY` / `no_reply`, щоб користувач нічого + не бачив. Конфігурація (`agents.defaults.compaction.memoryFlush`): @@ -426,30 +425,30 @@ OpenClaw використовує підхід **скидання перед п Примітки: -- Типові prompt/system prompt містять підказку `NO_REPLY`, щоб пригнітити +- Стандартні prompt/system prompt містять підказку `NO_REPLY`, щоб пригнітити доставку. -- Коли встановлено `model`, хід скидання використовує цю модель без успадкування - ланцюга fallback активної сесії, тож локальне службове обслуговування не буде непомітно - відступати до платної розмовної моделі. -- Скидання запускається один раз за цикл Compaction (відстежується в `sessions.json`). +- Коли `model` задано, хід скидання використовує цю модель без успадкування + ланцюга fallback активної сесії, тому локальне лише обслуговування не буде непомітно + переходити на платну розмовну модель. +- Скидання запускається один раз за цикл ущільнення (відстежується в `sessions.json`). - Скидання запускається лише для вбудованих сесій Pi (CLI-бекенди пропускають його). -- Скидання пропускається, коли робочий простір сесії доступний лише для читання (`workspaceAccess: "ro"` або `"none"`). -- Див. [Пам’ять](/uk/concepts/memory) щодо розкладки файлів робочого простору та патернів запису. +- Скидання пропускається, коли робоча область сесії доступна лише для читання (`workspaceAccess: "ro"` або `"none"`). +- Див. [Пам’ять](/uk/concepts/memory) щодо структури файлів робочої області та шаблонів запису. -Pi також надає хук `session_before_compact` в API розширення, але логіка -скидання OpenClaw сьогодні живе на боці Gateway. +Pi також надає хук `session_before_compact` в API розширень, але логіка скидання OpenClaw +сьогодні живе на боці Gateway. --- ## Контрольний список усунення несправностей - Неправильний ключ сесії? Почніть з [/concepts/session](/uk/concepts/session) і підтвердьте `sessionKey` у `/status`. -- Невідповідність сховища й транскрипта? Підтвердьте хост Gateway і шлях сховища з `openclaw status`. -- Спам Compaction? Перевірте: +- Невідповідність сховища й транскрипту? Підтвердьте хост Gateway і шлях до сховища з `openclaw status`. +- Спам ущільнення? Перевірте: - контекстне вікно моделі (занадто мале) - - налаштування Compaction (`reserveTokens` занадто високий для вікна моделі може спричинити ранішу Compaction) + - налаштування ущільнення (`reserveTokens` завеликий для вікна моделі може спричиняти раніше ущільнення) - роздування результатів інструментів: увімкніть/налаштуйте обрізання сесії -- Тихі ходи протікають? Підтвердьте, що відповідь починається з `NO_REPLY` (точний токен без урахування регістру) і що ви використовуєте збірку, яка містить виправлення пригнічення streaming. +- Тихі ходи витікають? Переконайтеся, що відповідь починається з `NO_REPLY` (точний токен без урахування регістру) і ви використовуєте збірку, яка містить виправлення пригнічення потокової передачі. ## Пов’язане