diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index 8686ea3df..044b26416 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -2,73 +2,73 @@ read_when: - Вам потрібні точні семантики полів конфігурації або значення за замовчуванням - Ви перевіряєте блоки конфігурації каналу, моделі, Gateway або інструмента -summary: Довідник з конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем -title: Довідник з конфігурації +summary: Довідник конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем +title: Довідник конфігурації x-i18n: - generated_at: "2026-04-25T23:38:38Z" + generated_at: "2026-04-25T23:50:23Z" model: gpt-5.4 provider: openai - source_hash: ac5e520e3ddb687b7575cf4cb9c058b4a914de1628fe48baabf33dd785f5c48a + source_hash: 6506e09f5bd8d45892bb519ebb66ee827967f785a11dda16e9aea4d941b7cfd1 source_path: gateway/configuration-reference.md workflow: 15 --- -Довідник з основної конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration). +Основний довідник конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration). -Охоплює основні поверхні конфігурації OpenClaw і містить посилання назовні, коли підсистема має власний, глибший довідник. Каталоги команд, що належать каналам і Plugin, а також детальні параметри memory/QMD винесені на окремі сторінки, а не розміщені тут. +Охоплює основні поверхні конфігурації OpenClaw і дає посилання назовні, коли підсистема має власний докладніший довідник. Каталоги команд, що належать каналам і Plugin, а також глибокі параметри пам’яті/QMD винесені на окремі сторінки, а не описуються тут. Джерело істини в коді: -- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та Control UI, з об’єднаними метаданими bundled/plugin/channel, якщо вони доступні -- `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів детального перегляду -- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють baseline hash документації конфігурації щодо поточної поверхні схеми +- `openclaw config schema` виводить актуальну JSON Schema, що використовується для валідації та Control UI, з об’єднаними метаданими bundled/plugin/channel, коли вони доступні +- `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів деталізації +- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють хеш базового рівня документації конфігурації відносно поточної поверхні схеми Окремі поглиблені довідники: -- [Memory configuration reference](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації dreaming у `plugins.entries.memory-core.config.dreaming` -- [Slash commands](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд -- сторінки каналів/Plugin-власників для специфічних для каналу поверхонь команд +- [Довідник конфігурації пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації dreaming у `plugins.entries.memory-core.config.dreaming` +- [Слеш-команди](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд +- сторінки відповідних каналів/Plugin для поверхонь команд, специфічних для каналів -Формат конфігурації — **JSON5** (коментарі + кінцеві коми дозволені). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх не вказано. +Формат конфігурації — **JSON5** (дозволено коментарі + кінцеві коми). Усі поля необов’язкові — якщо їх пропущено, OpenClaw використовує безпечні значення за замовчуванням. --- ## Канали -Ключі конфігурації для кожного каналу перенесено на окрему сторінку — див. +Ключі конфігурації для окремих каналів перенесено на окрему сторінку — див. [Configuration — channels](/uk/gateway/config-channels) для `channels.*`, -включно зі Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та іншими -bundled каналами (автентифікація, контроль доступу, кілька облікових записів, керування згадками). +зокрема Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та інших +bundled каналів (автентифікація, контроль доступу, кілька облікових записів, керування згадками). ## Значення агентів за замовчуванням, multi-agent, сесії та повідомлення Перенесено на окрему сторінку — див. [Configuration — agents](/uk/gateway/config-agents) для: -- `agents.defaults.*` (робочий простір, модель, thinking, heartbeat, memory, медіа, skills, sandbox) -- `multiAgent.*` (маршрутизація multi-agent і прив’язки) +- `agents.defaults.*` (робоча область, модель, thinking, heartbeat, пам’ять, медіа, skills, sandbox) +- `multiAgent.*` (маршрутизація та прив’язки multi-agent) - `session.*` (життєвий цикл сесії, compaction, очищення) - `messages.*` (доставка повідомлень, TTS, рендеринг markdown) - `talk.*` (режим Talk) - `talk.speechLocale`: необов’язковий ідентифікатор локалі BCP 47 для розпізнавання мовлення Talk на iOS/macOS - `talk.silenceTimeoutMs`: якщо не задано, Talk зберігає стандартне для платформи вікно паузи перед надсиланням транскрипту (`700 ms на macOS і Android, 900 ms на iOS`) -## Інструменти та користувацькі провайдери +## Інструменти та власні провайдери -Політика інструментів, експериментальні перемикачі, конфігурація інструментів на основі провайдерів і налаштування користувацьких провайдерів / base-URL перенесено на окрему сторінку — див. +Політика інструментів, експериментальні перемикачі, конфігурація інструментів із підтримкою провайдерів і налаштування власних провайдерів / базових URL перенесені на окрему сторінку — див. [Configuration — tools and custom providers](/uk/gateway/config-tools). ## MCP -Визначення MCP-серверів, керованих OpenClaw, розміщуються в `mcp.servers` і -використовуються вбудованим Pi та іншими runtime-адаптерами. Команди `openclaw mcp list`, +Визначення MCP-серверів, якими керує OpenClaw, розміщені в `mcp.servers` і +використовуються вбудованим Pi та іншими адаптерами середовища виконання. Команди `openclaw mcp list`, `show`, `set` і `unset` керують цим блоком без підключення до цільового сервера під час редагування конфігурації. ```json5 { mcp: { - // Необов’язково. За замовчуванням: 600000 ms (10 хвилин). Встановіть 0, щоб вимкнути idle eviction. + // Optional. Default: 600000 ms (10 minutes). Set 0 to disable idle eviction. sessionIdleTtlMs: 600000, servers: { docs: { @@ -87,17 +87,17 @@ bundled каналами (автентифікація, контроль дос } ``` -- `mcp.servers`: іменовані визначення stdio або віддалених MCP-серверів для runtime-середовищ, які +- `mcp.servers`: іменовані визначення stdio або віддалених MCP-серверів для середовищ виконання, які надають налаштовані MCP-інструменти. -- `mcp.sessionIdleTtlMs`: idle TTL для session-scoped bundled MCP runtime-середовищ. - Одноразові вбудовані запуски запитують очищення наприкінці виконання; цей TTL є запасним механізмом для +- `mcp.sessionIdleTtlMs`: TTL простою для bundled MCP-середовищ виконання в межах сесії. + Одноразові вбудовані запуски запитують очищення після завершення виконання; цей TTL є резервним механізмом для довготривалих сесій і майбутніх викликів. -- Зміни в `mcp.*` застосовуються на гарячу шляхом вивільнення кешованих session MCP runtime-середовищ. - Наступне виявлення/використання інструментів відтворює їх із нової конфігурації, тому видалені - записи `mcp.servers` прибираються негайно, а не чекають idle TTL. +- Зміни в `mcp.*` застосовуються на льоту шляхом вивільнення кешованих MCP-середовищ виконання сесії. + Наступне виявлення/використання інструмента створює їх заново з нової конфігурації, тому видалені + записи `mcp.servers` прибираються негайно, а не чекають завершення TTL простою. Див. [MCP](/uk/cli/mcp#openclaw-as-an-mcp-client-registry) і -[CLI backends](/uk/gateway/cli-backends#bundle-mcp-overlays) щодо runtime-поведінки. +[CLI backends](/uk/gateway/cli-backends#bundle-mcp-overlays) щодо поведінки середовища виконання. ## Skills @@ -124,14 +124,13 @@ bundled каналами (автентифікація, контроль дос } ``` -- `allowBundled`: необов’язковий список дозволу лише для bundled skills (керовані/workspace skills не зачіпаються). -- `load.extraDirs`: додаткові спільні корені skills (найнижчий пріоритет). -- `install.preferBrew`: якщо `true`, надавати перевагу інсталяторам Homebrew, коли `brew` - доступний, перш ніж переходити до інших типів інсталяторів. -- `install.nodeManager`: пріоритет node-інсталятора для специфікацій `metadata.openclaw.install` +- `allowBundled`: необов’язковий список дозволених лише для bundled skills (керовані/workspace skills не зачіпаються). +- `load.extraDirs`: додаткові спільні кореневі каталоги skills (найнижчий пріоритет). +- `install.preferBrew`: якщо `true`, спочатку надається перевага інсталяторам Homebrew, коли доступний `brew`, а вже потім іншим типам інсталяторів. +- `install.nodeManager`: налаштування пріоритетного менеджера Node для специфікацій `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` вимикає skill, навіть якщо він bundled/встановлений. -- `entries..apiKey`: зручне поле для skills, які оголошують основну env-змінну (рядок відкритим текстом або об’єкт SecretRef). +- `entries..enabled: false` вимикає skill, навіть якщо він bundled/installed. +- `entries..apiKey`: зручне поле для skills, які оголошують основну змінну середовища (простий рядок або об’єкт SecretRef). --- @@ -159,48 +158,48 @@ bundled каналами (автентифікація, контроль дос } ``` -- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. -- Виявлення підтримує нативні OpenClaw Plugins, а також сумісні пакети Codex і Claude, включно з пакетами Claude стандартної структури без manifest. -- **Зміни конфігурації потребують перезапуску gateway.** -- `allow`: необов’язковий список дозволу (завантажуються лише перелічені Plugins). `deny` має пріоритет. +- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також з `plugins.load.paths`. +- Виявлення підтримує нативні Plugin OpenClaw, а також сумісні пакети Codex і Claude, включно з пакетами Claude типового макета без маніфесту. +- **Зміни конфігурації вимагають перезапуску gateway.** +- `allow`: необов’язковий список дозволених (завантажуються лише перелічені Plugin). `deny` має пріоритет. - `plugins.entries..apiKey`: зручне поле API-ключа на рівні Plugin (коли Plugin це підтримує). -- `plugins.entries..env`: карта env-змінних у межах Plugin. -- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` і ігнорує поля legacy `before_agent_start`, що змінюють prompt, зберігаючи legacy `modelOverride` і `providerOverride`. Застосовується до нативних hook-ів Plugin і підтримуваних каталогів hook-ів, наданих пакетами. -- `plugins.entries..hooks.allowConversationAccess`: коли `true`, довірені небандловані Plugins можуть читати необроблений вміст розмови з типізованих hook-ів, таких як `llm_input`, `llm_output` і `agent_end`. -- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для окремих запусків у фонових підзапусках агента. -- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволу канонічних цілей `provider/model` для довірених перевизначень підзапусків агента. Використовуйте `"*"`, лише якщо ви свідомо хочете дозволити будь-яку модель. -- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (валідується схемою нативного OpenClaw Plugin, якщо вона доступна). -- Налаштування облікових записів/runtime для channel Plugin розміщуються в `channels.` і мають бути описані метаданими `channelConfigs` у manifest Plugin-власника, а не центральним реєстром параметрів OpenClaw. +- `plugins.entries..env`: мапа змінних середовища в межах Plugin. +- `plugins.entries..hooks.allowPromptInjection`: якщо `false`, ядро блокує `before_prompt_build` та ігнорує поля мутації prompt із застарілого `before_agent_start`, при цьому зберігає застарілі `modelOverride` і `providerOverride`. Застосовується до нативних хуків Plugin і підтримуваних каталогів хуків, наданих пакетами. +- `plugins.entries..hooks.allowConversationAccess`: якщо `true`, довірені небандловані Plugin можуть читати необроблений вміст розмови з типізованих хуків, таких як `llm_input`, `llm_output` і `agent_end`. +- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запит перевизначень `provider` і `model` для окремих запусків фонових subagent. +- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволених канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"` лише тоді, коли свідомо хочете дозволити будь-яку модель. +- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (перевіряється схемою нативного Plugin OpenClaw, якщо вона доступна). +- Налаштування облікових записів/середовища виконання Plugin-каналів містяться в `channels.` і мають описуватися метаданими `channelConfigs` у маніфесті відповідного Plugin, а не центральним реєстром параметрів OpenClaw. - `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера web-fetch Firecrawl. - - `apiKey`: API-ключ Firecrawl (підтримує SecretRef). Якщо відсутній, використовується `plugins.entries.firecrawl.config.webSearch.apiKey`, legacy `tools.web.fetch.firecrawl.apiKey` або env-змінна `FIRECRAWL_API_KEY`. - - `baseUrl`: базова URL-адреса API Firecrawl (за замовчуванням: `https://api.firecrawl.dev`). - - `onlyMainContent`: витягувати лише основний вміст сторінок (за замовчуванням: `true`). - - `maxAgeMs`: максимальний вік кешу в мілісекундах (за замовчуванням: `172800000` / 2 дні). - - `timeoutSeconds`: тайм-аут запиту scrape у секундах (за замовчуванням: `60`). -- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (Grok web search). - - `enabled`: увімкнути провайдер X Search. + - `apiKey`: API-ключ Firecrawl (підтримує SecretRef). Використовує як запасний варіант `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілий `tools.web.fetch.firecrawl.apiKey` або змінну середовища `FIRECRAWL_API_KEY`. + - `baseUrl`: базовий URL API Firecrawl (типово: `https://api.firecrawl.dev`). + - `onlyMainContent`: витягувати лише основний вміст сторінок (типово: `true`). + - `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні). + - `timeoutSeconds`: тайм-аут запиту зчитування в секундах (типово: `60`). +- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (вебпошук Grok). + - `enabled`: увімкнути провайдера X Search. - `model`: модель Grok для пошуку (наприклад, `"grok-4-1-fast"`). - `plugins.entries.memory-core.config.dreaming`: налаштування memory dreaming. Див. [Dreaming](/uk/concepts/dreaming) щодо фаз і порогів. - - `enabled`: головний перемикач dreaming (за замовчуванням `false`). - - `frequency`: Cron-розклад для кожного повного циклу dreaming (за замовчуванням `"0 3 * * *"`). + - `enabled`: головний перемикач dreaming (типово `false`). + - `frequency`: Cron-інтервал для кожного повного циклу dreaming (типово `"0 3 * * *"`). - політика фаз і пороги є деталями реалізації (не користувацькими ключами конфігурації). -- Повна конфігурація memory міститься в [Memory configuration reference](/uk/reference/memory-config): +- Повна конфігурація пам’яті міститься в [Довіднику конфігурації пам’яті](/uk/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Увімкнені bundle Plugins Claude також можуть додавати вбудовані значення Pi за замовчуванням із `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як необроблені патчі конфігурації OpenClaw. -- `plugins.slots.memory`: вибрати id активного memory Plugin або `"none"` для вимкнення memory Plugins. -- `plugins.slots.contextEngine`: вибрати id активного Plugin механізму контексту; за замовчуванням `"legacy"`, якщо ви не встановите й не виберете інший механізм. -- `plugins.installs`: застарілий сумісний резервний варіант для legacy - метаданих встановлення, якими керує CLI. Нові встановлення Plugin записують +- Увімкнені Plugin-пакети Claude також можуть додавати вбудовані значення Pi за замовчуванням із `settings.json`; OpenClaw застосовує їх як очищені налаштування агентів, а не як сирі патчі конфігурації OpenClaw. +- `plugins.slots.memory`: вибрати id активного Plugin пам’яті або `"none"` для вимкнення Plugin пам’яті. +- `plugins.slots.contextEngine`: вибрати id активного Plugin рушія контексту; типово `"legacy"`, якщо ви не встановите й не виберете інший рушій. +- `plugins.installs`: застарілий резервний механізм сумісності для застарілих + метаданих установлення, якими керує CLI. Нові встановлення Plugin записують керований журнал стану `plugins/installs.json`. - - Legacy-записи містять `source`, `spec`, `sourcePath`, `installPath`, + - Застарілі записи містять `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Розглядайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI над - ручним редагуванням. + - Розглядайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI замість + ручного редагування. Див. [Plugins](/uk/tools/plugin). @@ -215,7 +214,7 @@ bundled каналами (автентифікація, контроль дос evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // вмикайте лише для довіреного доступу до приватної мережі + // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access // allowPrivateNetwork: true, // legacy alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -253,49 +252,49 @@ bundled каналами (автентифікація, контроль дос ``` - `evaluateEnabled: false` вимикає `act:evaluate` і `wait --fn`. -- `tabCleanup` очищає відстежувані вкладки основного агента після простою або коли - сесія перевищує свій ліміт. Встановіть `idleMinutes: 0` або `maxTabsPerSession: 0`, щоб +- `tabCleanup` звільняє відстежувані вкладки основного агента після простою або коли + сесія перевищує свій ліміт. Установіть `idleMinutes: 0` або `maxTabsPerSession: 0`, щоб вимкнути ці окремі режими очищення. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо його не задано, тому навігація браузера за замовчуванням залишається суворо обмеженою. -- Встановлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації браузера в приватній мережі. -- У суворому режимі віддалені кінцеві точки профілю CDP (`profiles.*.cdpUrl`) підпадають під те саме блокування приватної мережі під час перевірок доступності/виявлення. -- `ssrfPolicy.allowPrivateNetwork` і далі підтримується як legacy alias. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому навігація браузера за замовчуванням залишається суворо обмеженою. +- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації браузера в приватній мережі. +- У суворому режимі кінцеві точки віддалених профілів CDP (`profiles.*.cdpUrl`) підлягають тому самому блокуванню приватної мережі під час перевірок доступності/виявлення. +- `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім. - У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків. -- Віддалені профілі працюють лише в режимі attach-only (start/stop/reset вимкнено). +- Віддалені профілі працюють лише в режимі підключення (запуск/зупинка/скидання вимкнено). - `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`. Використовуйте HTTP(S), якщо хочете, щоб OpenClaw виявляв `/json/version`; використовуйте WS(S), - коли ваш провайдер надає вам пряму URL-адресу DevTools WebSocket. -- `remoteCdpTimeoutMs` і `remoteCdpHandshakeTimeoutMs` застосовуються до перевірки доступності віддаленого й - `attachOnly` CDP, а також до запитів на відкриття вкладок. Керовані loopback-профілі - зберігають локальні значення CDP за замовчуванням. + коли ваш провайдер надає прямий URL DevTools WebSocket. +- `remoteCdpTimeoutMs` і `remoteCdpHandshakeTimeoutMs` застосовуються до віддалених і + `attachOnly` перевірок доступності CDP, а також до запитів відкриття вкладок. Керовані loopback- + профілі зберігають типові локальні значення CDP. - Якщо зовнішньо керований сервіс CDP доступний через loopback, установіть для цього - профілю `attachOnly: true`; інакше OpenClaw сприйматиме loopback-порт як - локальний керований профіль браузера й може повідомляти про помилки володіння локальним портом. + профілю `attachOnly: true`; інакше OpenClaw вважатиме loopback-порт + локальним керованим профілем браузера та може повідомляти про помилки володіння локальним портом. - Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися - до вибраного вузла або через підключений browser Node. -- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний + до вибраного хоста або через підключений вузол браузера. +- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлюватися на конкретний профіль браузера на базі Chromium, наприклад Brave або Edge. - Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP: - дії через snapshot/ref замість націлювання через CSS-селектори, hooks завантаження одного файлу, - без перевизначення тайм-ауту діалогів, без `wait --load networkidle`, а також без + дії на основі snapshot/ref замість націлювання через CSS-селектори, хуки завантаження + одного файла, без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, а також без `responsebody`, експорту PDF, перехоплення завантажень чи пакетних дій. - Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно задавайте `cdpUrl` лише для віддаленого CDP. - Локальні керовані профілі можуть задавати `executablePath`, щоб перевизначити глобальний `browser.executablePath` для цього профілю. Використовуйте це, щоб запускати один профіль у - Chrome, а інший — у Brave. + Chrome, а інший у Brave. - Локальні керовані профілі використовують `browser.localLaunchTimeoutMs` для HTTP-виявлення Chrome CDP - після запуску процесу і `browser.localCdpReadyTimeoutMs` для - готовності CDP websocket після запуску. Збільшуйте ці значення на повільніших хостах, де Chrome - успішно запускається, але перевірки готовності змагаються зі стартом. Обидва значення мають бути + після запуску процесу та `browser.localCdpReadyTimeoutMs` для + готовності CDP websocket після запуску. Збільшуйте їх на повільніших хостах, де Chrome + успішно запускається, але перевірки готовності випереджають завершення запуску. Обидва значення мають бути додатними цілими числами до `120000` ms; некоректні значення конфігурації відхиляються. -- Порядок автовиявлення: браузер за замовчуванням, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- Порядок автовиявлення: типовий браузер, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. - `browser.executablePath` і `browser.profiles..executablePath` обидва приймають `~` і `~/...` для домашнього каталогу вашої ОС перед запуском Chromium. - `userDataDir` для `existing-session` профілів також розгортається з тильдою. -- Служба керування: лише loopback (порт похідний від `gateway.port`, за замовчуванням `18791`). + `userDataDir` для профілів `existing-session` також розгортає тильду. +- Сервіс керування: лише loopback (порт визначається на основі `gateway.port`, типово `18791`). - `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад, - `--disable-gpu`, розміри вікна або прапорці налагодження). + `--disable-gpu`, розмір вікна або прапорці налагодження). --- @@ -313,7 +312,7 @@ bundled каналами (автентифікація, контроль дос } ``` -- `seamColor`: колір акценту для chrome інтерфейсу нативного застосунку (тон бульбашки Talk Mode тощо). +- `seamColor`: колір акценту для chrome UI нативного застосунку (відтінок бульбашки Talk Mode тощо). - `assistant`: перевизначення ідентичності Control UI. Якщо не задано, використовується ідентичність активного агента. --- @@ -389,69 +388,68 @@ bundled каналами (автентифікація, контроль дос } ``` - + - `mode`: `local` (запуск gateway) або `remote` (підключення до віддаленого gateway). Gateway відмовляється запускатися, якщо не `local`. - `port`: єдиний мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. -- `bind`: `auto`, `loopback` (за замовчуванням), `lan` (`0.0.0.0`), `tailnet` (лише Tailscale IP) або `custom`. -- **Legacy alias-и bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не host alias-и (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Примітка щодо Docker**: bind `loopback` за замовчуванням слухає `127.0.0.1` усередині контейнера. Із bridge-мережею Docker (`-p 18789:18789`) трафік надходить через `eth0`, тому gateway недосяжний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` із `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. -- **Auth**: обов’язкова за замовчуванням. Bind-и не на loopback вимагають auth gateway. На практиці це означає спільний token/password або reverse proxy з урахуванням ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер онбордингу за замовчуванням генерує token. -- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно встановіть `gateway.auth.mode` у `token` або `password`. Потоки запуску та встановлення/відновлення сервісу завершуються помилкою, якщо налаштовано обидва, а mode не задано. -- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних конфігурацій local loopback; цей варіант навмисно не пропонується в підказках онбордингу. -- `gateway.auth.mode: "trusted-proxy"`: делегує auth reverse proxy з урахуванням ідентичності та довіряє заголовкам ідентичності від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; reverse proxy loopback на тому ж хості не задовольняють auth trusted-proxy. -- `gateway.auth.allowTailscale`: коли `true`, заголовки ідентичності Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). HTTP API endpoints **не** використовують цю auth заголовками Tailscale; вони натомість дотримуються звичайного режиму HTTP auth gateway. Цей потік без token передбачає, що хост gateway є довіреним. За замовчуванням `true`, коли `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: необов’язковий лімітер невдалих спроб auth. Застосовується для кожної IP-адреси клієнта та для кожної області auth окремо (shared-secret і device-token відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`. - - В асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому одночасні хибні спроби від того самого клієнта можуть спровокувати лімітер на другому запиті, а не пройти обидві як звичайні невідповідності. - - `gateway.auth.rateLimit.exemptLoopback` за замовчуванням має значення `true`; встановіть `false`, якщо ви навмисно хочете також застосовувати rate limit до localhost-трафіку (для тестових конфігурацій або суворих proxy-розгортань). -- Спроби WS auth із browser-origin завжди обмежуються без звільнення для loopback (додатковий захист від brute force localhost через браузер). -- На loopback ці блокування browser-origin ізолюються за нормалізованим значенням `Origin`, - тому повторні невдачі з одного localhost origin не призводять автоматично - до блокування іншого origin. -- `tailscale.mode`: `serve` (лише tailnet, bind на loopback) або `funnel` (публічний, потребує auth). -- `controlUi.allowedOrigins`: явний allowlist browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються browser-клієнти з origin-ів не на loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає резервне визначення origin через Host-header для розгортань, що навмисно покладаються на політику origin за Host-header. -- `remote.transport`: `ssh` (за замовчуванням) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: аварійне клієнтське перевизначення через - process-environment, яке дозволяє plaintext `ws://` до довірених IP-адрес - приватної мережі; за замовчуванням plaintext і далі обмежено лише loopback. Еквівалента в `openclaw.json` - немає, а конфігурація browser private-network, така як - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, не впливає на клієнтів - Gateway WebSocket. -- `gateway.remote.token` / `.password`: це поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують auth gateway. -- `gateway.push.apns.relay.baseUrl`: базова HTTPS URL-адреса для зовнішнього APNs relay, який використовують офіційні/TestFlight збірки iOS після публікації relay-backed registrations до gateway. Ця URL-адреса має збігатися з URL relay, зібраною в iOS build. -- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання gateway-to-relay у мілісекундах. За замовчуванням `10000`. -- Реєстрації з relay-backed делегуються конкретній ідентичності gateway. Спарений застосунок iOS отримує `gateway.identity.get`, включає цю ідентичність у реєстрацію relay і передає gateway дозвіл на надсилання в межах реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові env-перевизначення для наведеної вище конфігурації relay. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: лише для розробки, аварійний варіант для loopback HTTP relay URL-адрес. URL-адреси production relay мають залишатися на HTTPS. -- `gateway.channelHealthCheckMinutes`: інтервал монітора стану каналу в хвилинах. Встановіть `0`, щоб глобально вимкнути перезапуски health-monitor. За замовчуванням: `5`. -- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого socket у хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. За замовчуванням: `30`. -- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor на канал/обліковий запис за ковзну годину. За замовчуванням: `10`. -- `channels..healthMonitor.enabled`: відмова на рівні каналу від перезапусків health-monitor за збереження глобального монітора ввімкненим. -- `channels..accounts..healthMonitor.enabled`: перевизначення на рівні облікового запису для каналів із кількома обліковими записами. Якщо задано, воно має пріоритет над перевизначенням на рівні каналу. -- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резерв лише тоді, коли `gateway.auth.*` не задано. -- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не розв’язано, розв’язання завершується за принципом fail closed (без маскування резервним remote-варіантом). -- `trustedProxies`: IP-адреси reverse proxy, які термінують TLS або вставляють forwarded-client headers. Указуйте лише ті proxy, якими ви керуєте. Записи loopback і далі є валідними для конфігурацій proxy на тому ж хості / локального виявлення (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. За замовчуванням `false` для поведінки fail-closed. -- `gateway.nodes.pairing.autoApproveCidrs`: необов’язковий allowlist CIDR/IP для автоматичного схвалення першого спарювання пристрою Node без запитаних scopes. Якщо не задано, вимкнено. Це не схвалює автоматично спарювання operator/browser/Control UI/WebChat і не схвалює автоматично підвищення role, scope, metadata або public-key. -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування allow/deny для оголошених команд Node після спарювання та перевірки allowlist. -- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює список deny за замовчуванням). -- `gateway.tools.allow`: прибирає назви інструментів зі списку deny HTTP за замовчуванням. +- `bind`: `auto`, `loopback` (типово), `lan` (`0.0.0.0`), `tailnet` (лише IP Tailscale) або `custom`. +- **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хоста (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Примітка щодо Docker**: типовий bind `loopback` слухає `127.0.0.1` усередині контейнера. З мережевим режимом Docker bridge (`-p 18789:18789`) трафік надходить через `eth0`, тому gateway недоступний. Використовуйте `--network host` або задайте `bind: "lan"` (чи `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. +- **Auth**: за замовчуванням обов’язкова. Bind не на loopback вимагають auth gateway. На практиці це означає спільний токен/пароль або reverse proxy з контролем ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер початкового налаштування за замовчуванням генерує токен. +- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно задайте `gateway.auth.mode` як `token` або `password`. Запуск і потоки встановлення/відновлення сервісу завершуються помилкою, якщо налаштовано обидва значення, а режим не задано. +- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних налаштувань loopback; цей варіант навмисно не пропонується в запитах початкового налаштування. +- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy з контролем ідентичності та довіряти заголовкам ідентичності від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; reverse proxy loopback на тій самій машині не задовольняють вимоги auth trusted-proxy. +- `gateway.auth.allowTailscale`: якщо `true`, заголовки ідентичності Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). Кінцеві точки HTTP API **не** використовують цю auth заголовків Tailscale; вони натомість дотримуються звичайного режиму HTTP auth gateway. Цей безтокенний потік виходить із припущення, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: необов’язковий лімітатор невдалих спроб auth. Застосовується для кожної IP-адреси клієнта та для кожної області auth (спільний секрет і токен пристрою відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`. + - В асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому одночасні неправильні спроби від того самого клієнта можуть спровокувати спрацювання лімітатора вже на другому запиті, замість того щоб обидві одночасно пройти як звичайні невідповідності. + - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; задайте `false`, якщо ви навмисно хочете обмежувати за rate limit також localhost-трафік (для тестових середовищ або суворих розгортань proxy). +- Спроби WS auth з походженням браузера завжди обмежуються без винятку для loopback (додатковий захист від brute force localhost через браузер). +- На loopback ці блокування для походження браузера ізольовані за нормалізованим значенням `Origin`, + тож повторні невдалі спроби з одного походження localhost не блокують автоматично + інше походження. +- `tailscale.mode`: `serve` (лише tailnet, bind на loopback) або `funnel` (публічно, потребує auth). +- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються браузерні клієнти не з loopback-origin. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, що вмикає резервне визначення origin через заголовок Host для розгортань, які навмисно покладаються на політику origin на основі заголовка Host. +- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: аварійне перевизначення в середовищі процесу на стороні клієнта, + яке дозволяє plaintext `ws://` до довірених IP приватної мережі; за замовчуванням plaintext, як і раніше, дозволено лише для loopback. Еквівалента в `openclaw.json` + немає, а конфігурація приватної мережі браузера, така як + `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, не впливає на клієнтів Gateway + WebSocket. +- `gateway.remote.token` / `.password`: поля облікових даних віддаленого клієнта. Самі по собі вони не налаштовують auth gateway. +- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL для зовнішнього relay APNs, який використовують офіційні/TestFlight-збірки iOS після публікації ними relay-реєстрацій до gateway. Цей URL має збігатися з URL relay, вкомпільованим у збірку iOS. +- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до relay у мілісекундах. Типово `10000`. +- Реєстрації, що працюють через relay, делегуються конкретній ідентичності gateway. Спарений застосунок iOS викликає `gateway.identity.get`, включає цю ідентичність у relay-реєстрацію та пересилає gateway дозвіл на надсилання в межах реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові перевизначення через env для наведеної вище конфігурації relay. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний вихід лише для розробки для URL relay HTTP на loopback. URL relay у production мають залишатися на HTTPS. +- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналу в хвилинах. Задайте `0`, щоб глобально вимкнути перезапуски монітора стану. Типово: `5`. +- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Тримайте його більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`. +- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітора стану на канал/обліковий запис у ковзній годині. Типово: `10`. +- `channels..healthMonitor.enabled`: відмова на рівні каналу від перезапусків монітора стану зі збереженням глобального монітора увімкненим. +- `channels..accounts..healthMonitor.enabled`: перевизначення на рівні облікового запису для багатокористувацьких каналів. Якщо задано, має пріоритет над перевизначенням на рівні каналу. +- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано. +- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і його не вдається розв’язати, розв’язання завершується за принципом fail-closed (без маскування резервним віддаленим варіантом). +- `trustedProxies`: IP-адреси reverse proxy, які завершують TLS або додають заголовки пересланого клієнта. Указуйте лише proxy, які ви контролюєте. Записи loopback і далі лишаються валідними для налаштувань proxy/локального виявлення на тій самій машині (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback`: якщо `true`, gateway приймає `X-Real-IP`, якщо відсутній `X-Forwarded-For`. Типово `false` для поведінки fail-closed. +- `gateway.nodes.pairing.autoApproveCidrs`: необов’язковий список дозволених CIDR/IP для автоматичного схвалення першого спарювання пристрою вузла без запитаних scopes. Якщо не задано, вимкнено. Це не схвалює автоматично спарювання operator/browser/Control UI/WebChat і не схвалює автоматично оновлення ролі, scope, метаданих чи публічного ключа. +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування списків дозволених/заборонених для оголошених команд вузла після спарювання та оцінки allowlist. +- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список deny). +- `gateway.tools.allow`: прибрати назви інструментів із типового HTTP-списку deny. -### Endpoints, сумісні з OpenAI +### OpenAI-сумісні кінцеві точки - Chat Completions: вимкнено за замовчуванням. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: `gateway.http.endpoints.responses.enabled`. -- Захист URL-input для Responses: +- Посилене захист URL-входів Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Порожні allowlist-и трактуються як незадані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` - і/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. -- Необов’язковий заголовок додаткового захисту відповіді: - - `gateway.http.securityHeaders.strictTransportSecurity` (задавайте лише для контрольованих вами HTTPS origin; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + Порожні списки allowlist трактуються як незадані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` + та/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. +- Необов’язковий заголовок посиленого захисту відповідей: + - `gateway.http.securityHeaders.strictTransportSecurity` (задавайте лише для HTTPS-origin, які ви контролюєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) ### Ізоляція кількох екземплярів @@ -465,7 +463,7 @@ openclaw gateway --port 19001 Зручні прапорці: `--dev` (використовує `~/.openclaw-dev` + порт `19001`), `--profile ` (використовує `~/.openclaw-`). -Див. [Multiple Gateways](/uk/gateway/multiple-gateways). +Див. [Кілька Gateway](/uk/gateway/multiple-gateways). ### `gateway.tls` @@ -483,11 +481,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: вмикає TLS termination на слухачі gateway (HTTPS/WSS) (за замовчуванням: `false`). +- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типово: `false`). - `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, якщо явні файли не налаштовано; лише для локального/dev використання. -- `certPath`: шлях файлової системи до файла TLS certificate. -- `keyPath`: шлях файлової системи до файла TLS private key; обмежуйте доступ правами. -- `caPath`: необов’язковий шлях до CA bundle для перевірки клієнта або користувацьких ланцюжків довіри. +- `certPath`: шлях у файловій системі до файла сертифіката TLS. +- `keyPath`: шлях у файловій системі до файла приватного ключа TLS; обмежуйте доступ дозволами. +- `caPath`: необов’язковий шлях до пакета CA для верифікації клієнта або власних ланцюжків довіри. ### `gateway.reload` @@ -504,12 +502,12 @@ openclaw gateway --port 19001 ``` - `mode`: керує тим, як зміни конфігурації застосовуються під час виконання. - - `"off"`: ігнорувати зміни наживо; зміни потребують явного перезапуску. + - `"off"`: ігнорувати зміни в реальному часі; зміни потребують явного перезапуску. - `"restart"`: завжди перезапускати процес gateway при зміні конфігурації. - - `"hot"`: застосовувати зміни в процесі без перезапуску. - - `"hybrid"` (за замовчуванням): спочатку спробувати hot reload; якщо потрібно, перейти до перезапуску. + - `"hot"`: застосовувати зміни в межах процесу без перезапуску. + - `"hybrid"` (типово): спочатку спробувати hot reload; за потреби перейти до перезапуску. - `debounceMs`: вікно debounce у ms перед застосуванням змін конфігурації (невід’ємне ціле число). -- `deferralTimeoutMs`: необов’язковий максимальний час у ms очікування завершення поточних операцій перед примусовим перезапуском. Не задавайте його або встановіть `0`, щоб чекати необмежено довго й періодично журналювати попередження про те, що щось усе ще очікує. +- `deferralTimeoutMs`: необов’язковий максимальний час у ms очікування завершення поточних операцій перед примусовим перезапуском. Не задавайте його або встановіть `0`, щоб чекати необмежено довго та періодично журналювати попередження про те, що щось іще не завершено. --- @@ -547,46 +545,46 @@ openclaw gateway --port 19001 ``` Auth: `Authorization: Bearer ` або `x-openclaw-token: `. -Hook token-и в query string відхиляються. +Токени hooks у рядку запиту відхиляються. Примітки щодо валідації та безпеки: -- `hooks.enabled=true` вимагає непорожній `hooks.token`. -- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання token gateway відхиляється. +- `hooks.enabled=true` вимагає непорожнього `hooks.token`. +- `hooks.token` має бути **відмінним** від `gateway.auth.token`; повторне використання токена Gateway відхиляється. - `hooks.path` не може бути `/`; використовуйте окремий підшлях, наприклад `/hooks`. - Якщо `hooks.allowRequestSessionKey=true`, обмежте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). - Якщо mapping або preset використовує шаблонізований `sessionKey`, задайте `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не потребують цього opt-in. -**Endpoints:** +**Кінцеві точки:** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - `sessionKey` із тіла запиту приймається лише коли `hooks.allowRequestSessionKey=true` (за замовчуванням: `false`). + - `sessionKey` із тіла запиту приймається лише тоді, коли `hooks.allowRequestSessionKey=true` (типово: `false`). - `POST /hooks/` → розв’язується через `hooks.mappings` - - Значення `sessionKey` у mapping, згенеровані через шаблон, вважаються зовнішньо наданими й також вимагають `hooks.allowRequestSessionKey=true`. + - Значення `sessionKey` у mapping, згенеровані шаблоном, вважаються зовнішньо наданими й також потребують `hooks.allowRequestSessionKey=true`. - + - `match.path` відповідає підшляху після `/hooks` (наприклад, `/hooks/gmail` → `gmail`). - `match.source` відповідає полю payload для загальних шляхів. - Шаблони на кшталт `{{messages[0].subject}}` читають дані з payload. -- `transform` може вказувати на JS/TS-модуль, що повертає дію hook. - - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи й traversal відхиляються). -- `agentId` спрямовує до конкретного агента; невідомі ID повертаються до агента за замовчуванням. -- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або не задано = дозволити все, `[]` = заборонити все). +- `transform` може вказувати на модуль JS/TS, що повертає дію hook. + - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та traversal відхиляються). +- `agentId` маршрутизує до конкретного агента; невідомі ID повертаються до типового. +- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити всі, `[]` = заборонити всі). - `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook-агента без явного `sessionKey`. -- `allowRequestSessionKey`: дозволяє викликачам `/hooks/agent` і ключам сесії mapping, керованим шаблонами, задавати `sessionKey` (за замовчуванням: `false`). +- `allowRequestSessionKey`: дозволити викликачам `/hooks/agent` і ключам сесії mapping, що керуються шаблонами, задавати `sessionKey` (типово: `false`). - `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Він стає обов’язковим, коли будь-який mapping або preset використовує шаблонізований `sessionKey`. -- `deliver: true` надсилає фінальну відповідь у канал; `channel` за замовчуванням має значення `last`. +- `deliver: true` надсилає фінальну відповідь до каналу; `channel` типово дорівнює `last`. - `model` перевизначає LLM для цього запуску hook (має бути дозволено, якщо задано каталог моделей). ### Інтеграція Gmail -- Вбудований Gmail preset використовує `sessionKey: "hook:gmail:{{messages[0].id}}"`. -- Якщо ви зберігаєте таку маршрутизацію для кожного повідомлення, установіть `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes` так, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. -- Якщо вам потрібно `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість шаблонізованого значення за замовчуванням. +- Вбудований preset Gmail використовує `sessionKey: "hook:gmail:{{messages[0].id}}"`. +- Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, задайте `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes`, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. +- Якщо вам потрібне `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість типового шаблонізованого. ```json5 { @@ -609,7 +607,7 @@ Hook token-и в query string відхиляються. } ``` -- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, якщо це налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути це. +- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, якщо його налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути це. - Не запускайте окремий `gog gmail watch serve` паралельно з Gateway. --- @@ -626,14 +624,14 @@ Hook token-и в query string відхиляються. } ``` -- Обслуговує редаговані агентом HTML/CSS/JS і A2UI через HTTP на порту Gateway: +- Обслуговує HTML/CSS/JS і A2UI, які може редагувати агент, через HTTP на порту Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- Лише локально: зберігайте `gateway.bind: "loopback"` (за замовчуванням). -- Bind-и не на loopback: маршрути canvas потребують auth Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway. -- Node WebView зазвичай не надсилають заголовки auth; після спарювання та підключення Node Gateway оголошує capability URL-адреси в межах Node для доступу до canvas/A2UI. -- Capability URL-адреси прив’язані до активної WS-сесії Node і швидко спливають. Резервний варіант на основі IP не використовується. -- Вбудовує клієнт live-reload у HTML, що обслуговується. +- Лише локально: залишайте `gateway.bind: "loopback"` (типово). +- Для bind не на loopback: маршрути canvas вимагають auth Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway. +- Node WebView зазвичай не надсилають заголовки auth; після спарювання й підключення node Gateway рекламує URL можливостей з областю node для доступу до canvas/A2UI. +- URL можливостей прив’язані до активної WS-сесії node і швидко спливають. Резервний варіант на основі IP не використовується. +- Впроваджує клієнт live-reload у HTML, що обслуговується. - Автоматично створює стартовий `index.html`, якщо каталог порожній. - Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`. - Зміни потребують перезапуску gateway. @@ -655,9 +653,9 @@ Hook token-и в query string відхиляються. } ``` -- `minimal` (за замовчуванням): не включає `cliPath` + `sshPort` до TXT-записів. +- `minimal` (типово): не включає `cliPath` + `sshPort` до TXT-записів. - `full`: включає `cliPath` + `sshPort`. -- Назва хоста за замовчуванням — `openclaw`. Перевизначається через `OPENCLAW_MDNS_HOSTNAME`. +- Ім’я хоста типово `openclaw`. Перевизначається через `OPENCLAW_MDNS_HOSTNAME`. ### Wide-area (DNS-SD) @@ -669,7 +667,7 @@ Hook token-и в query string відхиляються. } ``` -Записує unicast DNS-SD zone до `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + Tailscale split DNS. +Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + split DNS у Tailscale. Налаштування: `openclaw dns setup --apply`. @@ -677,7 +675,7 @@ Hook token-и в query string відхиляються. ## Середовище -### `env` (вбудовані env-змінні) +### `env` (вбудовані змінні середовища) ```json5 { @@ -694,14 +692,14 @@ Hook token-и в query string відхиляються. } ``` -- Вбудовані env-змінні застосовуються лише якщо в process env відсутній цей ключ. +- Вбудовані змінні середовища застосовуються лише тоді, коли в середовищі процесу бракує цього ключа. - Файли `.env`: `.env` у CWD + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). -- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашого login shell. +- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell. - Повний порядок пріоритету див. у [Environment](/uk/help/environment). -### Підстановка env-змінних +### Підстановка env var -Посилайтеся на env-змінні в будь-якому рядку конфігурації через `${VAR_NAME}`: +Посилайтеся на змінні середовища в будь-якому рядку конфігурації через `${VAR_NAME}`: ```json5 { @@ -711,16 +709,16 @@ Hook token-и в query string відхиляються. } ``` -- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. +- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. - Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації. -- Екрануйте через `$${VAR}`, щоб отримати буквальний `${VAR}`. +- Екрануйте через `$${VAR}` для буквального `${VAR}`. - Працює з `$include`. --- ## Секрети -Посилання на секрети є адитивними: значення у відкритому тексті й далі працюють. +Посилання на секрети є адитивними: прості текстові значення теж продовжують працювати. ### `SecretRef` @@ -736,13 +734,13 @@ Hook token-и в query string відхиляються. - шаблон `id` для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` - `id` для `source: "file"`: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`) - шаблон `id` для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `id` для `source: "exec"` не повинен містити сегменти шляху `.` або `..`, розділені `/` (наприклад, `a/../b` відхиляється) +- `id` для `source: "exec"` не повинні містити сегменти шляху `.` або `..`, розділені слешами (наприклад, `a/../b` відхиляється) ### Підтримувана поверхня облікових даних -- Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface) +- Канонічна матриця: [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface) - `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`. -- Посилання в `auth-profiles.json` включено в розв’язання під час виконання та покриття аудиту. +- Посилання в `auth-profiles.json` включаються до розв’язання під час виконання та охоплення аудиту. ### Конфігурація провайдерів секретів @@ -775,13 +773,13 @@ Hook token-и в query string відхиляються. Примітки: - Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue значення `id` має бути `"value"`). -- Шляхи провайдерів file та exec завершуються за принципом fail closed, якщо перевірка Windows ACL недоступна. Встановлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. -- Провайдер `exec` вимагає абсолютний шлях `command` і використовує payload-и протоколу через stdin/stdout. -- За замовчуванням шляхи command, що є symlink, відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи symlink із перевіркою розв’язаного цільового шляху. -- Якщо налаштовано `trustedDirs`, перевірка trusted-dir застосовується до розв’язаного цільового шляху. -- Дочірнє середовище `exec` за замовчуванням мінімальне; явно передавайте потрібні змінні через `passEnv`. -- Посилання на секрети розв’язуються під час активації у snapshot в пам’яті, після чого шляхи запитів читають лише цей snapshot. -- Під час активації застосовується фільтрація активної поверхні: нерозв’язані посилання на ввімкнених поверхнях призводять до помилки запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. +- Шляхи до провайдерів file і exec завершуються за принципом fail-closed, коли недоступна перевірка Windows ACL. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. +- Провайдер `exec` вимагає абсолютний шлях `command` і використовує корисні навантаження протоколу через stdin/stdout. +- Типово шляхи команд-симлінків відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-симлінки з валідацією розв’язаного цільового шляху. +- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до розв’язаного цільового шляху. +- Дочірнє середовище `exec` типово мінімальне; передавайте потрібні змінні явно через `passEnv`. +- Посилання на секрети розв’язуються під час активації у знімок у пам’яті, після чого шляхи запитів читають лише цей знімок. +- Під час активації застосовується фільтрація активної поверхні: нерозв’язані посилання на ввімкнених поверхнях спричиняють збій запуску/перезавантаження, а неактивні поверхні пропускаються з діагностикою. --- @@ -804,12 +802,12 @@ Hook token-и в query string відхиляються. ``` - Профілі для кожного агента зберігаються в `/auth-profiles.json`. -- `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для режимів статичних облікових даних. +- `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних. - Профілі в режимі OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілю auth на основі SecretRef. -- Статичні runtime-облікові дані надходять із розв’язаних snapshot-ів у пам’яті; legacy записи `auth.json` очищуються, коли їх виявлено. -- Legacy імпорт OAuth виконується з `~/.openclaw/credentials/oauth.json`. +- Статичні облікові дані середовища виконання надходять зі знімків, розв’язаних у пам’яті; застарілі статичні записи `auth.json` очищуються під час виявлення. +- Застарілий імпорт OAuth здійснюється з `~/.openclaw/credentials/oauth.json`. - Див. [OAuth](/uk/concepts/oauth). -- Поведінка секретів під час виконання та інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). +- Поведінка секретів під час виконання та інструменти `audit/configure/apply`: [Керування секретами](/uk/gateway/secrets). ### `auth.cooldowns` @@ -831,22 +829,19 @@ Hook token-и в query string відхиляються. } ``` -- `billingBackoffHours`: базовий backoff у годинах, коли профіль завершується помилкою через справжні - помилки billing/недостатнього кредиту (за замовчуванням: `5`). Явний текст billing - і далі може потрапляти сюди навіть на відповідях `401`/`403`, але - matcher-и тексту, специфічні для провайдера, залишаються прив’язаними до провайдера, - якому вони належать (наприклад, OpenRouter - `Key limit exceeded`). Повторювані HTTP `402` повідомлення про usage-window або - ліміти витрат organization/workspace залишаються в шляху `rate_limit` - натомість. -- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин billing backoff для окремих провайдерів. -- `billingMaxHours`: верхня межа в годинах для експоненційного зростання billing backoff (за замовчуванням: `24`). -- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для збоїв `auth_permanent` із високою впевненістю (за замовчуванням: `10`). -- `authPermanentMaxMinutes`: верхня межа в хвилинах для зростання backoff `auth_permanent` (за замовчуванням: `60`). -- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників backoff (за замовчуванням: `24`). -- `overloadedProfileRotations`: максимальна кількість ротацій auth-профілю того самого провайдера для помилок перевантаження перед переходом до резервної моделі (за замовчуванням: `1`). Сюди потрапляють і форми зайнятості провайдера, такі як `ModelNotReadyException`. -- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (за замовчуванням: `0`). -- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-профілю того самого провайдера для помилок rate limit перед переходом до резервної моделі (за замовчуванням: `1`). Цей кошик rate limit включає й текстові форми від провайдерів, такі як `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. +- `billingBackoffHours`: базова затримка в годинах, коли профіль завершується помилкою через справжні помилки білінгу/недостатнього кредиту (типово: `5`). Явний текст про білінг + усе ще може потрапити сюди навіть у відповідях `401`/`403`, але провайдер-специфічні + зіставлення тексту залишаються обмеженими провайдером, якому вони належать (наприклад, OpenRouter + `Key limit exceeded`). Повторювані HTTP `402` повідомлення про вікно використання або + ліміти витрат організації/робочої області лишаються натомість у шляху `rate_limit`. +- `billingBackoffHoursByProvider`: необов’язкові перевизначення затримки білінгу в годинах для кожного провайдера. +- `billingMaxHours`: обмеження в годинах для експоненційного зростання затримки білінгу (типово: `24`). +- `authPermanentBackoffMinutes`: базова затримка в хвилинах для збоїв `auth_permanent` із високою впевненістю (типово: `10`). +- `authPermanentMaxMinutes`: обмеження в хвилинах для зростання затримки `auth_permanent` (типово: `60`). +- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників затримки (типово: `24`). +- `overloadedProfileRotations`: максимальна кількість ротацій auth-профілю того самого провайдера для помилок перевантаження перед перемиканням на резервну модель (типово: `1`). Форми перевантаження провайдера на кшталт `ModelNotReadyException` потрапляють сюди. +- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`). +- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-профілю того самого провайдера для помилок rate limit перед перемиканням на резервну модель (типово: `1`). До цього кошика rate limit належить текст, характерний для провайдерів, наприклад `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. --- @@ -865,10 +860,10 @@ Hook token-и в query string відхиляються. } ``` -- Файл журналу за замовчуванням: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. +- Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Установіть `logging.file` для стабільного шляху. -- `consoleLevel` підвищується до `debug` із `--verbose`. -- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого запис пригнічується (додатне ціле число; за замовчуванням: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів. +- `consoleLevel` підвищується до `debug` з `--verbose`. +- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого записи пригнічуються (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів. --- @@ -913,23 +908,23 @@ Hook token-и в query string відхиляються. } ``` -- `enabled`: головний перемикач для виводу інструментування (за замовчуванням: `true`). -- `flags`: масив рядків-прапорців, що вмикають цільовий вивід журналу (підтримує wildcard-и на кшталт `"telegram.*"` або `"*"`). +- `enabled`: головний перемикач для виводу інструментування (типово: `true`). +- `flags`: масив рядків-прапорців, що вмикають цільовий вивід журналу (підтримуються wildcard, як-от `"telegram.*"` або `"*"`). - `stuckSessionWarnMs`: поріг віку в ms для виводу попереджень про завислі сесії, поки сесія залишається в стані обробки. -- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (за замовчуванням: `false`). -- `otel.endpoint`: URL collector для експорту OTel. -- `otel.protocol`: `"http/protobuf"` (за замовчуванням) або `"grpc"`. +- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). Повну конфігурацію, каталог сигналів і модель конфіденційності див. у [Експорт OpenTelemetry](/uk/gateway/opentelemetry). +- `otel.endpoint`: URL колектора для експорту OTel. +- `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`. - `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються із запитами експорту OTel. -- `otel.serviceName`: ім’я сервісу для атрибутів ресурсу. -- `otel.traces` / `otel.metrics` / `otel.logs`: вмикають експорт trace, metrics або log. +- `otel.serviceName`: назва сервісу для атрибутів ресурсу. +- `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт trace, metrics або logs. - `otel.sampleRate`: частота семплювання trace `0`–`1`. - `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в ms. -- `otel.captureContent`: opt-in захоплення сирого вмісту для атрибутів OTel span. За замовчуванням вимкнено. Булеве значення `true` захоплює вміст повідомлень/інструментів, що не є системним; форма об’єкта дозволяє явно вмикати `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`. -- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: перемикач середовища для найновіших експериментальних атрибутів провайдера GenAI span. За замовчуванням span-и зберігають legacy атрибут `gen_ai.system` для сумісності; метрики GenAI використовують обмежені семантичні атрибути. -- `OPENCLAW_OTEL_PRELOADED=1`: перемикач середовища для хостів, які вже зареєстрували глобальний OpenTelemetry SDK. Тоді OpenClaw пропускає запуск/завершення SDK, що належить Plugin, зберігаючи активними слухачі діагностики. -- `cacheTrace.enabled`: журналювати snapshot-и cache trace для вбудованих запусків (за замовчуванням: `false`). -- `cacheTrace.filePath`: шлях виводу для cache trace JSONL (за замовчуванням: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається до виводу cache trace (усі за замовчуванням: `true`). +- `otel.captureContent`: opt-in для захоплення сирого вмісту в атрибути span OTEL. Типово вимкнено. Булеве значення `true` захоплює вміст повідомлень/інструментів, крім системного; форма об’єкта дає змогу явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`. +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: перемикач середовища для найновіших експериментальних атрибутів провайдера span GenAI. За замовчуванням span зберігають застарілий атрибут `gen_ai.system` для сумісності; метрики GenAI використовують обмежені семантичні атрибути. +- `OPENCLAW_OTEL_PRELOADED=1`: перемикач середовища для хостів, які вже зареєстрували глобальний SDK OpenTelemetry. У такому разі OpenClaw пропускає запуск/завершення SDK, яким володіє Plugin, зберігаючи активними слухачі діагностики. +- `cacheTrace.enabled`: журналювати знімки trace кешу для вбудованих запусків (типово: `false`). +- `cacheTrace.filePath`: шлях виводу для JSONL trace кешу (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається до виводу trace кешу (усе типово: `true`). --- @@ -951,12 +946,12 @@ Hook token-и в query string відхиляються. } ``` -- `channel`: канал релізу для npm/git-встановлень — `"stable"`, `"beta"` або `"dev"`. -- `checkOnStart`: перевіряти оновлення npm під час запуску gateway (за замовчуванням: `true`). -- `auto.enabled`: увімкнути фонове автооновлення для встановлень пакетів (за замовчуванням: `false`). -- `auto.stableDelayHours`: мінімальна затримка в годинах перед авто застосуванням для stable-каналу (за замовчуванням: `6`; максимум: `168`). -- `auto.stableJitterHours`: додаткове вікно розподілу розгортання для stable-каналу в годинах (за замовчуванням: `12`; максимум: `168`). -- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу в годинах (за замовчуванням: `1`; максимум: `24`). +- `channel`: канал релізів для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`. +- `checkOnStart`: перевіряти оновлення npm під час запуску gateway (типово: `true`). +- `auto.enabled`: увімкнути фонове автооновлення для пакетних установлень (типово: `false`). +- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням для каналу stable (типово: `6`; максимум: `168`). +- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable-каналу в годинах (типово: `12`; максимум: `168`). +- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу, у годинах (типово: `1`; максимум: `24`). --- @@ -989,23 +984,23 @@ Hook token-и в query string відхиляються. } ``` -- `enabled`: глобальний feature gate ACP (за замовчуванням: `true`; установіть `false`, щоб приховати можливості dispatch і spawn ACP). -- `dispatch.enabled`: незалежний gate для dispatch ходів сесії ACP (за замовчуванням: `true`). Установіть `false`, щоб зберегти команди ACP доступними, але заблокувати виконання. -- `backend`: id backend runtime ACP за замовчуванням (має відповідати зареєстрованому Plugin runtime ACP). - Якщо задано `plugins.allow`, включіть id backend Plugin (наприклад `acpx`), інакше bundled Plugin за замовчуванням не завантажиться. -- `defaultAgent`: резервний id цільового агента ACP, коли spawn-и не задають явну ціль. -- `allowedAgents`: allowlist id агентів, дозволених для сесій runtime ACP; порожнє значення означає відсутність додаткових обмежень. -- `maxConcurrentSessions`: максимальна кількість одночасно активних сесій ACP. +- `enabled`: глобальний feature gate для ACP (типово: `true`; установіть `false`, щоб приховати можливості dispatch і spawn ACP). +- `dispatch.enabled`: окремий gate для dispatch ходу ACP-сесії (типово: `true`). Установіть `false`, щоб залишити ACP-команди доступними, але заблокувати виконання. +- `backend`: типовий id backend середовища виконання ACP (має відповідати зареєстрованому Plugin середовища виконання ACP). + Якщо задано `plugins.allow`, включіть id backend Plugin (наприклад `acpx`), інакше bundled типовий Plugin не завантажиться. +- `defaultAgent`: резервний id цільового агента ACP, коли spawn не задає явну ціль. +- `allowedAgents`: список дозволених id агентів для сесій середовища виконання ACP; порожній список означає відсутність додаткових обмежень. +- `maxConcurrentSessions`: максимальна кількість одночасно активних ACP-сесій. - `stream.coalesceIdleMs`: вікно idle flush у ms для потокового тексту. - `stream.maxChunkChars`: максимальний розмір chunk перед розбиттям проєкції потокового блока. -- `stream.repeatSuppression`: пригнічує повторювані рядки статусу/інструментів на хід (за замовчуванням: `true`). +- `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструментів у межах ходу (типово: `true`). - `stream.deliveryMode`: `"live"` транслює поступово; `"final_only"` буферизує до термінальних подій ходу. -- `stream.hiddenBoundarySeparator`: розділювач перед видимим текстом після прихованих подій інструмента (за замовчуванням: `"paragraph"`). -- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, проєктованих на один хід ACP. -- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлення ACP. -- `stream.tagVisibility`: запис відповідностей назв тегів до булевих перевизначень видимості для потокових подій. -- `runtime.ttlMinutes`: idle TTL у хвилинах для worker-ів сесій ACP до моменту, коли їх можна очищати. -- `runtime.installCommand`: необов’язкова команда встановлення для запуску під час bootstrap середовища runtime ACP. +- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (типово: `"paragraph"`). +- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, що проєктується на один хід ACP. +- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлень ACP. +- `stream.tagVisibility`: запис імен тегів у перевизначення видимості streamed подій типу boolean. +- `runtime.ttlMinutes`: idle TTL у хвилинах для worker ACP-сесій до моменту, коли вони підлягають очищенню. +- `runtime.installCommand`: необов’язкова команда встановлення для запуску під час початкового налаштування середовища виконання ACP. --- @@ -1021,17 +1016,17 @@ Hook token-и в query string відхиляються. } ``` -- `cli.banner.taglineMode` керує стилем tagline у банері: - - `"random"` (за замовчуванням): змінні кумедні/сезонні tagline-и. - - `"default"`: фіксований нейтральний tagline (`All your chats, one OpenClaw.`). - - `"off"`: без тексту tagline (заголовок/версія банера все одно показуються). -- Щоб приховати весь банер (а не лише tagline-и), установіть env `OPENCLAW_HIDE_BANNER=1`. +- `cli.banner.taglineMode` керує стилем слогана банера: + - `"random"` (типово): змінні кумедні/сезонні слогани. + - `"default"`: фіксований нейтральний слоган (`Усі ваші чати, один OpenClaw.`). + - `"off"`: без тексту слогана (назва/версія банера все одно показуються). +- Щоб приховати весь банер (а не лише слогани), задайте env `OPENCLAW_HIDE_BANNER=1`. --- ## Wizard -Метадані, які записуються керованими CLI потоками налаштування (`onboard`, `configure`, `doctor`): +Метадані, які записують потоки покрокового налаштування CLI (`onboard`, `configure`, `doctor`): ```json5 { @@ -1049,15 +1044,15 @@ Hook token-и в query string відхиляються. ## Ідентичність -Див. поля ідентичності `agents.list` у розділі [Agent defaults](/uk/gateway/config-agents#agent-defaults). +Див. поля ідентичності `agents.list` у [Значеннях агентів за замовчуванням](/uk/gateway/config-agents#agent-defaults). --- -## Bridge (legacy, видалено) +## Bridge (застарілий, вилучено) -Поточні збірки більше не містять TCP bridge. Node підключаються через Gateway WebSocket. Ключі `bridge.*` більше не входять до схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). +Поточні збірки більше не містять TCP bridge. Node підключаються через Gateway WebSocket. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). - + ```json { @@ -1095,11 +1090,11 @@ Hook token-и в query string відхиляються. } ``` -- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів cron. За замовчуванням: `24h`; установіть `false`, щоб вимкнути. -- `runLog.maxBytes`: максимальний розмір файла журналу для одного запуску (`cron/runs/.jsonl`) перед очищенням. За замовчуванням: `2_000_000` байт. -- `runLog.keepLines`: найновіші рядки, що зберігаються під час очищення журналу запуску. За замовчуванням: `2000`. -- `webhookToken`: bearer token, що використовується для POST-доставки Cron Webhook (`delivery.mode = "webhook"`); якщо не задано, заголовок auth не надсилається. -- `webhook`: застаріла legacy URL-адреса Webhook fallback (`http/https`), яка використовується лише для збережених завдань, що все ще мають `notify: true`. +- `sessionRetention`: як довго зберігати завершені сесії ізольованих запусків cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів cron. Типово: `24h`; задайте `false`, щоб вимкнути. +- `runLog.maxBytes`: максимальний розмір файла журналу на запуск (`cron/runs/.jsonl`) перед очищенням. Типово: `2_000_000` bytes. +- `runLog.keepLines`: кількість найновіших рядків, що зберігаються, коли спрацьовує очищення журналу запуску. Типово: `2000`. +- `webhookToken`: bearer token, що використовується для POST-доставки cron Webhook (`delivery.mode = "webhook"`); якщо пропущено, заголовок auth не надсилається. +- `webhook`: застарілий резервний URL Webhook (http/https), який використовується лише для збережених завдань, що все ще мають `notify: true`. ### `cron.retry` @@ -1115,11 +1110,11 @@ Hook token-и в query string відхиляються. } ``` -- `maxAttempts`: максимальна кількість повторів для одноразових завдань при тимчасових помилках (за замовчуванням: `3`; діапазон: `0`–`10`). -- `backoffMs`: масив затримок backoff у ms для кожної повторної спроби (за замовчуванням: `[30000, 60000, 300000]`; 1–10 записів). -- `retryOn`: типи помилок, що запускають повтори — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Не задавайте, щоб повторювати для всіх тимчасових типів. +- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань при тимчасових помилках (типово: `3`; діапазон: `0`–`10`). +- `backoffMs`: масив затримок backoff у ms для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів). +- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати всі тимчасові типи. -Застосовується лише до одноразових завдань cron. Повторювані завдання використовують окрему обробку збоїв. +Застосовується лише до одноразових cron-завдань. Повторювані завдання використовують окрему обробку помилок. ### `cron.failureAlert` @@ -1137,11 +1132,11 @@ Hook token-и в query string відхиляються. } ``` -- `enabled`: увімкнути сповіщення про збої для завдань cron (за замовчуванням: `false`). +- `enabled`: увімкнути сповіщення про помилки для cron-завдань (типово: `false`). - `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мінімум: `1`). - `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число). -- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` публікує в налаштований Webhook. -- `accountId`: необов’язковий id облікового запису або каналу для обмеження доставки сповіщень. +- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` виконує POST на налаштований Webhook. +- `accountId`: необов’язковий id облікового запису або каналу для обмеження доставки сповіщення. ### `cron.failureDestination` @@ -1158,51 +1153,51 @@ Hook token-и в query string відхиляються. } ``` -- Цільове місце за замовчуванням для сповіщень про збої cron у всіх завданнях. -- `mode`: `"announce"` або `"webhook"`; за замовчуванням `"announce"`, коли є достатньо даних цілі. +- Типове призначення для сповіщень про помилки cron для всіх завдань. +- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли достатньо даних цілі. - `channel`: перевизначення каналу для доставки announce. `"last"` повторно використовує останній відомий канал доставки. -- `to`: явна ціль announce або URL-адреса Webhook. Обов’язково для режиму webhook. +- `to`: явна ціль announce або URL Webhook. Обов’язково для режиму webhook. - `accountId`: необов’язкове перевизначення облікового запису для доставки. -- `delivery.failureDestination` на рівні завдання перевизначає це глобальне значення за замовчуванням. -- Коли не задано ні глобальне, ні значення призначення для збоїв на рівні завдання, завдання, які вже доставляють через `announce`, у разі збою повертаються до цієї основної цілі announce. +- `delivery.failureDestination` для окремого завдання перевизначає це глобальне значення за замовчуванням. +- Коли не задано ні глобального, ні для окремого завдання призначення помилки, завдання, які вже доставляють через `announce`, у разі помилки повертаються до цієї основної цілі announce. - `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` завдання не дорівнює `"webhook"`. -Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [background tasks](/uk/automation/tasks). +Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [фонові завдання](/uk/automation/tasks). --- -## Змінні шаблонів медіамоделі +## Змінні шаблону моделі медіа Заповнювачі шаблонів, що розгортаються в `tools.media.models[].args`: | Змінна | Опис | | ------------------ | ------------------------------------------------- | -| `{{Body}}` | Повний текст вхідного повідомлення | -| `{{RawBody}}` | Сирий текст (без обгорток історії/відправника) | -| `{{BodyStripped}}` | Текст без згадок групи | +| `{{Body}}` | Повне тіло вхідного повідомлення | +| `{{RawBody}}` | Сире тіло (без обгорток історії/відправника) | +| `{{BodyStripped}}` | Тіло з вилученими згадками групи | | `{{From}}` | Ідентифікатор відправника | | `{{To}}` | Ідентифікатор призначення | -| `{{MessageSid}}` | id повідомлення каналу | +| `{{MessageSid}}` | ID повідомлення каналу | | `{{SessionId}}` | UUID поточної сесії | | `{{IsNewSession}}` | `"true"`, коли створено нову сесію | | `{{MediaUrl}}` | Псевдо-URL вхідного медіа | | `{{MediaPath}}` | Локальний шлях до медіа | | `{{MediaType}}` | Тип медіа (image/audio/document/…) | | `{{Transcript}}` | Транскрипт аудіо | -| `{{Prompt}}` | Розв’язаний media prompt для записів CLI | +| `{{Prompt}}` | Розв’язаний prompt медіа для записів CLI | | `{{MaxChars}}` | Розв’язана максимальна кількість символів виводу для записів CLI | | `{{ChatType}}` | `"direct"` або `"group"` | | `{{GroupSubject}}` | Тема групи (best effort) | -| `{{GroupMembers}}` | Попередній список учасників групи (best effort) | +| `{{GroupMembers}}` | Попередній перегляд учасників групи (best effort) | | `{{SenderName}}` | Відображуване ім’я відправника (best effort) | | `{{SenderE164}}` | Номер телефону відправника (best effort) | | `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) | --- -## Include конфігурації (`$include`) +## Включення конфігурації (`$include`) -Розділіть конфігурацію на кілька файлів: +Розділяйте конфігурацію на кілька файлів: ```json5 // ~/.openclaw/openclaw.json @@ -1217,20 +1212,20 @@ Hook token-и в query string відхиляються. **Поведінка злиття:** -- Один файл: замінює об’єкт, що його містить. -- Масив файлів: deep merge у вказаному порядку (пізніші перевизначають ранні). -- Сусідні ключі: зливаються після include-ів (перевизначають включені значення). -- Вкладені include-и: до 10 рівнів углиб. -- Шляхи: розв’язуються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли вони все одно розв’язуються в межах цієї границі. -- Записи, що належать OpenClaw і змінюють лише один розділ верхнього рівня, який підтримується include-ом одного файла, записуються безпосередньо в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін. -- Кореневі include-и, масиви include-ів і include-и з перевизначеннями сусідніх ключів доступні лише для читання для записів, що належать OpenClaw; такі записи завершуються за принципом fail closed замість сплющення конфігурації. -- Помилки: зрозумілі повідомлення для відсутніх файлів, помилок розбору та циклічних include-ів. +- Один файл: замінює об’єкт-контейнер. +- Масив файлів: глибоко зливається в заданому порядку (пізніші перевизначають раніші). +- Сусідні ключі: зливаються після включень (перевизначають включені значення). +- Вкладені включення: до 10 рівнів углиб. +- Шляхи: розв’язуються відносно файла, що включає, але мають залишатися в межах конфігураційного каталогу верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли вони все одно розв’язуються в межах цієї межі. +- Записи, якими володіє OpenClaw і які змінюють лише один розділ верхнього рівня, підкріплений включенням одного файла, записуються безпосередньо в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін. +- Кореневі включення, масиви включень і включення із сусідніми перевизначеннями доступні для OpenClaw-власних записів лише в режимі читання; такі записи завершуються за принципом fail-closed замість сплощення конфігурації. +- Помилки: зрозумілі повідомлення для відсутніх файлів, помилок парсингу та циклічних включень. --- -_Пов’язано: [Configuration](/uk/gateway/configuration) · [Configuration Examples](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_ +_Пов’язане: [Configuration](/uk/gateway/configuration) · [Configuration Examples](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_ ## Пов’язане - [Configuration](/uk/gateway/configuration) -- [Configuration examples](/uk/gateway/configuration-examples) +- [Приклади конфігурації](/uk/gateway/configuration-examples) diff --git a/docs/uk/gateway/diagnostics.md b/docs/uk/gateway/diagnostics.md index 45110a618..5cb2f4962 100644 --- a/docs/uk/gateway/diagnostics.md +++ b/docs/uk/gateway/diagnostics.md @@ -1,22 +1,20 @@ --- read_when: - Підготовка звіту про помилку або запиту до служби підтримки - - Налагодження збоїв Gateway, перезапусків, тиску на пам’ять або надто великих payload-ів - - Перегляд того, які діагностичні дані записуються або редагуються -summary: Створення придатних для поширення діагностичних пакетів Gateway для звітів про помилки + - Налагодження збоїв Gateway, перезапусків, нестачі пам’яті або надто великих корисних навантажень + - Перегляд того, які діагностичні дані записуються або редагуються для приховування конфіденційної інформації +summary: Створюйте придатні для поширення діагностичні пакети Gateway для звітів про помилки title: Експорт діагностики x-i18n: - generated_at: "2026-04-23T20:52:46Z" + generated_at: "2026-04-25T23:50:23Z" model: gpt-5.4 provider: openai - source_hash: 3773b623a3f94a1f1340f2d278d9f5236f18fbf9aa38f84ec9ddbe41aea44e8c + source_hash: 64866d929ed42f8484aa7c153e3056bad7b594d9e02705c095b7005f3094ec36 source_path: gateway/diagnostics.md workflow: 15 --- -OpenClaw може створити локальний zip-пакет діагностики, який безпечно додавати до звітів -про помилки. Він поєднує санітизовані дані про стан Gateway, health, логи, форму конфігурації та -останні події стабільності без payload. +OpenClaw може створювати локальний zip-архів із діагностикою, який безпечно додавати до звітів про помилки. Він поєднує очищені дані про стан Gateway, перевірки працездатності, журнали, структуру конфігурації та нещодавні події стабільності без корисного навантаження. ## Швидкий старт @@ -24,7 +22,7 @@ OpenClaw може створити локальний zip-пакет діагн openclaw gateway diagnostics export ``` -Команда виводить шлях до записаного zip-файла. Щоб вибрати власний шлях: +Команда виводить шлях до записаного zip-архіву. Щоб вибрати шлях: ```bash openclaw gateway diagnostics export --output openclaw-diagnostics.zip @@ -38,47 +36,41 @@ openclaw gateway diagnostics export --json ## Що містить експорт -Zip-файл містить: +Zip-архів містить: - `summary.md`: зрозумілий для людини огляд для служби підтримки. -- `diagnostics.json`: придатний для машинного читання підсумок конфігурації, логів, стану, health - і даних стабільності. +- `diagnostics.json`: придатне для машинного читання зведення конфігурації, журналів, стану, перевірок працездатності та даних стабільності. - `manifest.json`: метадані експорту та список файлів. -- Санітизовану форму конфігурації й не секретні деталі конфігурації. -- Санітизовані підсумки логів і нещодавні відредаговані рядки логів. -- Best-effort snapshot стану Gateway і health. +- Очищену структуру конфігурації та несекретні відомості конфігурації. +- Очищені зведення журналів і нещодавні відредаговані рядки журналу. +- Найкращим чином отримані знімки стану Gateway і перевірок працездатності. - `stability/latest.json`: найновіший збережений пакет стабільності, якщо доступний. -Експорт корисний навіть тоді, коли Gateway нездоровий. Якщо Gateway не може -відповісти на запити стану або health, локальні логи, форма конфігурації та останній -пакет стабільності все одно збираються, якщо це можливо. +Експорт корисний навіть тоді, коли Gateway працює нестабільно. Якщо Gateway не може відповісти на запити стану або перевірки працездатності, локальні журнали, структура конфігурації та найновіший пакет стабільності все одно збираються, якщо доступні. ## Модель конфіденційності -Діагностику спроєктовано так, щоб її можна було безпечно поширювати. Експорт зберігає операційні дані, -які допомагають у налагодженні, зокрема: +Діагностику створено так, щоб нею можна було ділитися. Експорт зберігає операційні дані, які допомагають у налагодженні, зокрема: -- назви підсистем, id Plugin, id провайдерів, id каналів і налаштовані режими +- назви підсистем, ідентифікатори плагінів, постачальників, каналів і налаштовані режими - коди стану, тривалості, кількість байтів, стан черги та показники пам’яті -- санітизовані метадані логів і відредаговані операційні повідомлення -- форму конфігурації та несекретні налаштування функцій +- очищені метадані журналів і відредаговані операційні повідомлення +- структуру конфігурації та несекретні налаштування функцій -Експорт пропускає або редагує: +Експорт пропускає або редагує для приховування конфіденційної інформації: -- текст чатів, prompt, інструкції, тіла webhook і вивід інструментів -- облікові дані, API-ключі, токени, cookies і секретні значення -- сирі тіла запитів або відповідей -- account id, message id, сирі id сесій, hostname і локальні імена користувачів +- текст чатів, промпти, інструкції, тіла Webhook і результати інструментів +- облікові дані, API-ключі, токени, cookie та секретні значення +- необроблені тіла запитів або відповідей +- ідентифікатори облікових записів, ідентифікатори повідомлень, необроблені ідентифікатори сесій, імена хостів і локальні імена користувачів -Коли повідомлення логу схоже на текст payload користувача, чату, prompt або інструмента, експорт -залишає лише факт того, що повідомлення було пропущено, і кількість байтів. +Якщо повідомлення журналу схоже на текст користувача, чату, промпту або корисного навантаження інструмента, експорт зберігає лише факт того, що повідомлення було пропущено, і кількість байтів. -## Recorder стабільності +## Засіб запису стабільності -Gateway типово записує обмежений потік стабільності без payload, коли -діагностику увімкнено. Він призначений для операційних фактів, а не для вмісту. +Gateway типово записує обмежений потік стабільності без корисного навантаження, коли діагностику ввімкнено. Він призначений для операційних фактів, а не вмісту. -Переглянути live recorder: +Перегляньте активний засіб запису: ```bash openclaw gateway stability @@ -86,20 +78,19 @@ openclaw gateway stability --type payload.large openclaw gateway stability --json ``` -Переглянути найновіший збережений пакет стабільності після фатального завершення, тайм-ауту -вимкнення або збою запуску після перезапуску: +Перегляньте найновіший збережений пакет стабільності після фатального завершення, перевищення часу очікування під час вимкнення або помилки запуску після перезапуску: ```bash openclaw gateway stability --bundle latest ``` -Створити zip-файл діагностики з найновішого збереженого пакета: +Створіть zip-архів із діагностикою з найновішого збереженого пакета: ```bash openclaw gateway stability --bundle latest --export ``` -Збережені пакети містяться в `~/.openclaw/logs/stability/`, якщо події існують. +Збережені пакети розміщуються в `~/.openclaw/logs/stability/`, якщо події існують. ## Корисні параметри @@ -110,20 +101,19 @@ openclaw gateway diagnostics export \ --log-bytes 1000000 ``` -- `--output `: записати в конкретний шлях zip-файла. -- `--log-lines `: максимальна кількість санітизованих рядків логів для включення. -- `--log-bytes `: максимальна кількість байтів логів для аналізу. -- `--url `: WebSocket URL Gateway для snapshot стану й health. -- `--token `: токен Gateway для snapshot стану й health. -- `--password `: пароль Gateway для snapshot стану й health. -- `--timeout `: тайм-аут snapshot стану й health. +- `--output `: записати в конкретний шлях zip-архіву. +- `--log-lines `: максимальна кількість очищених рядків журналу для включення. +- `--log-bytes `: максимальна кількість байтів журналу для аналізу. +- `--url `: URL WebSocket Gateway для знімків стану та перевірок працездатності. +- `--token `: токен Gateway для знімків стану та перевірок працездатності. +- `--password `: пароль Gateway для знімків стану та перевірок працездатності. +- `--timeout `: час очікування знімків стану та перевірок працездатності. - `--no-stability-bundle`: пропустити пошук збереженого пакета стабільності. -- `--json`: вивести метадані експорту в машинозчитуваному вигляді. +- `--json`: вивести придатні для машинного читання метадані експорту. ## Вимкнення діагностики -Діагностика типово увімкнена. Щоб вимкнути recorder стабільності та -збір діагностичних подій: +Діагностику типово ввімкнено. Щоб вимкнути засіб запису стабільності та збирання діагностичних подій: ```json5 { @@ -133,12 +123,12 @@ openclaw gateway diagnostics export \ } ``` -Вимкнення діагностики зменшує деталізацію звітів про помилки. Це не впливає на звичайне -логування Gateway. +Вимкнення діагностики зменшує обсяг відомостей у звітах про помилки. Воно не впливає на звичайне журналювання Gateway. -## Пов’язана документація +## Пов’язане -- [Перевірки стану](/uk/gateway/health) +- [Перевірки працездатності](/uk/gateway/health) - [CLI Gateway](/uk/cli/gateway#gateway-diagnostics-export) - [Протокол Gateway](/uk/gateway/protocol#system-and-identity) -- [Логування](/uk/logging) +- [Журналювання](/uk/logging) +- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — окремий процес для потокового передавання діагностики до збирача diff --git a/docs/uk/gateway/logging.md b/docs/uk/gateway/logging.md index 316091e69..a84f43baf 100644 --- a/docs/uk/gateway/logging.md +++ b/docs/uk/gateway/logging.md @@ -5,34 +5,34 @@ read_when: summary: Поверхні журналювання, файлові журнали, стилі журналів WS і форматування консолі title: Журналювання Gateway x-i18n: - generated_at: "2026-04-24T04:13:48Z" + generated_at: "2026-04-25T23:50:23Z" model: gpt-5.4 provider: openai - source_hash: 17ecbb9b781734727fc7aa8e3b0a59bc7ea22b455affd02fbc2db924c144b9f3 + source_hash: 706c9eb05f805057c2465cf00a4654dea81d53d24acb4b6fc63658bc959bc8ff source_path: gateway/logging.md workflow: 15 --- # Журналювання -Огляд для користувачів (CLI + Control UI + конфігурація) див. у [/logging](/uk/logging). +Щоб переглянути огляд для користувачів (CLI + Control UI + config), див. [/logging](/uk/logging). -В OpenClaw є дві “поверхні” журналювання: +OpenClaw має дві «поверхні» журналювання: - **Вивід у консоль** (те, що ви бачите в терміналі / Debug UI). -- **Файлові журнали** (рядки JSON), які записує засіб журналювання gateway. +- **Файлові журнали** (рядки JSON), які записуються реєстратором Gateway. -## Файловий засіб журналювання +## Файловий реєстратор -- Типовий файл ротації журналів розміщується в `/tmp/openclaw/` (один файл на день): `openclaw-YYYY-MM-DD.log` - - Дата використовує локальний часовий пояс хоста gateway. -- Шлях до файла журналу й рівень можна налаштувати через `~/.openclaw/openclaw.json`: +- Типовий файл журналу з ротацією розташований у `/tmp/openclaw/` (один файл на день): `openclaw-YYYY-MM-DD.log` + - Дата використовує локальний часовий пояс хоста Gateway. +- Шлях до файлу журналу та рівень можна налаштувати через `~/.openclaw/openclaw.json`: - `logging.file` - `logging.level` -Формат файла — один JSON-об’єкт на рядок. +Формат файлу — один об’єкт JSON на рядок. -Вкладка Logs у Control UI відстежує цей файл через gateway (`logs.tail`). +Вкладка Logs у Control UI відстежує цей файл через Gateway (`logs.tail`). CLI може робити те саме: ```bash @@ -43,14 +43,14 @@ openclaw logs --follow - **Файлові журнали** керуються виключно через `logging.level`. - `--verbose` впливає лише на **деталізацію консолі** (і стиль журналів WS); він **не** - підвищує рівень файлового журналювання. -- Щоб зафіксувати у файлових журналах деталі, видимі лише в verbose-режимі, установіть `logging.level` у `debug` або + підвищує рівень файлового журналу. +- Щоб зберігати деталі, доступні лише у verbose, у файлових журналах, встановіть `logging.level` на `debug` або `trace`. ## Захоплення консолі CLI перехоплює `console.log/info/warn/error/debug/trace` і записує їх у файлові журнали, -при цьому все одно виводячи їх у stdout/stderr. +водночас продовжуючи виводити їх у stdout/stderr. Ви можете окремо налаштувати деталізацію консолі через: @@ -59,32 +59,32 @@ CLI перехоплює `console.log/info/warn/error/debug/trace` і запис ## Редагування зведень інструментів -Докладні зведення інструментів (наприклад, `🛠️ Exec: ...`) можуть маскувати чутливі токени перед тим, як вони потраплять у +Докладні зведення інструментів (наприклад, `🛠️ Exec: ...`) можуть маскувати чутливі токени до того, як вони потраплять у потік консолі. Це стосується **лише інструментів** і не змінює файлові журнали. - `logging.redactSensitive`: `off` | `tools` (типово: `tools`) - `logging.redactPatterns`: масив рядків regex (перевизначає типові значення) - Використовуйте сирі рядки regex (автоматично `gi`) або `/pattern/flags`, якщо потрібні власні прапорці. - - Збіги маскуються так, що зберігаються перші 6 і останні 4 символи (для довжини >= 18), інакше `***`. - - Типові значення охоплюють поширені присвоєння ключів, прапорці CLI, поля JSON, заголовки bearer, блоки PEM і популярні префікси токенів. + - Збіги маскуються зі збереженням перших 6 + останніх 4 символів (довжина >= 18), інакше `***`. + - Типові значення охоплюють поширені присвоєння ключів, прапорці CLI, поля JSON, заголовки bearer, PEM-блоки та популярні префікси токенів. -## Журнали Gateway WebSocket +## Журнали WebSocket Gateway Gateway виводить журнали протоколу WebSocket у двох режимах: -- **Звичайний режим (без `--verbose`)**: виводяться лише “цікаві” результати RPC: +- **Звичайний режим (без `--verbose`)**: виводяться лише «цікаві» результати RPC: - помилки (`ok=false`) - повільні виклики (типовий поріг: `>= 50ms`) - помилки розбору -- **Verbose-режим (`--verbose`)**: виводить увесь трафік запитів/відповідей WS. +- **Режим verbose (`--verbose`)**: виводить увесь трафік запитів/відповідей WS. ### Стиль журналів WS -`openclaw gateway` підтримує перемикач стилю для кожного gateway: +`openclaw gateway` підтримує перемикання стилю для кожного Gateway: -- `--ws-log auto` (типово): звичайний режим оптимізовано; verbose-режим використовує компактний вивід -- `--ws-log compact`: компактний вивід (пари запит/відповідь) у verbose-режимі -- `--ws-log full`: повний вивід по кадрах у verbose-режимі +- `--ws-log auto` (типово): звичайний режим оптимізований; режим verbose використовує компактний вивід +- `--ws-log compact`: компактний вивід (запит/відповідь у парі) у режимі verbose +- `--ws-log full`: повний вивід по кожному кадру в режимі verbose - `--compact`: псевдонім для `--ws-log compact` Приклади: @@ -102,24 +102,25 @@ openclaw gateway --verbose --ws-log full ## Форматування консолі (журналювання підсистем) -Форматер консолі **враховує TTY** і виводить узгоджені рядки з префіксами. -Засоби журналювання підсистем зберігають вивід згрупованим і зручним для перегляду. +Форматувач консолі **враховує TTY** і виводить узгоджені рядки з префіксами. +Реєстратори підсистем зберігають вивід згрупованим і зручним для перегляду. Поведінка: - **Префікси підсистем** у кожному рядку (наприклад, `[gateway]`, `[canvas]`, `[tailscale]`) - **Кольори підсистем** (сталі для кожної підсистеми) плюс кольори рівнів -- **Колір, коли вивід є TTY або середовище схоже на багатий термінал** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), з урахуванням `NO_COLOR` -- **Скорочені префікси підсистем**: відкидає початкові `gateway/` і `channels/`, зберігає останні 2 сегменти (наприклад, `whatsapp/outbound`) -- **Підзасоби журналювання за підсистемами** (автоматичний префікс + структуроване поле `{ subsystem }`) +- **Колір, коли вивід є TTY або середовище виглядає як розширений термінал** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), з урахуванням `NO_COLOR` +- **Скорочені префікси підсистем**: відкидає початкові `gateway/` + `channels/`, зберігає останні 2 сегменти (наприклад, `whatsapp/outbound`) +- **Підреєстратори за підсистемами** (автоматичний префікс + структуроване поле `{ subsystem }`) - **`logRaw()`** для виводу QR/UX (без префікса, без форматування) - **Стилі консолі** (наприклад, `pretty | compact | json`) -- **Рівень журналювання консолі** окремо від рівня файлового журналювання (файл зберігає повну деталізацію, коли `logging.level` установлено на `debug`/`trace`) -- **Тіла повідомлень WhatsApp** журналюються на рівні `debug` (використовуйте `--verbose`, щоб їх бачити) +- **Рівень журналу консолі** окремо від рівня файлового журналу (файл зберігає повні деталі, коли `logging.level` встановлено на `debug`/`trace`) +- **Тіла повідомлень WhatsApp** записуються на рівні `debug` (використовуйте `--verbose`, щоб їх бачити) -Це зберігає стабільність наявних файлових журналів і водночас робить інтерактивний вивід зручним для перегляду. +Це зберігає наявні файлові журнали стабільними, водночас роблячи інтерактивний вивід зручним для перегляду. ## Пов’язане -- [Огляд журналювання](/uk/logging) +- [Журналювання](/uk/logging) +- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) - [Експорт діагностики](/uk/gateway/diagnostics) diff --git a/docs/uk/gateway/opentelemetry.md b/docs/uk/gateway/opentelemetry.md new file mode 100644 index 000000000..73c769172 --- /dev/null +++ b/docs/uk/gateway/opentelemetry.md @@ -0,0 +1,311 @@ +--- +read_when: + - Ви хочете надсилати використання моделей OpenClaw, потік повідомлень або метрики сеансів до збирача OpenTelemetry + - Ви налаштовуєте трасування, метрики або журнали для Grafana, Datadog, Honeycomb, New Relic, Tempo або іншого бекенда OTLP + - Вам потрібні точні назви метрик, назви спанів або форми атрибутів, щоб створювати інформаційні панелі чи сповіщення +summary: Експортуйте діагностику OpenClaw до будь-якого збирача OpenTelemetry через plugin diagnostics-otel (OTLP/HTTP) +title: Експорт OpenTelemetry +x-i18n: + generated_at: "2026-04-25T23:50:24Z" + model: gpt-5.4 + provider: openai + source_hash: d478625ec525e76993d0a587b3aa8bc1c98a4d66d1ae8990316be241d3dc96a4 + source_path: gateway/opentelemetry.md + workflow: 15 +--- + +OpenClaw експортує діагностику через вбудований plugin `diagnostics-otel` +за допомогою **OTLP/HTTP (protobuf)**. Будь-який збирач або бекенд, що приймає OTLP/HTTP, +працює без змін у коді. Про локальні файлові журнали та те, як їх читати, див. +у [Журналюванні](/uk/logging). + +## Як це працює разом + +- **Події діагностики** — це структуровані внутрішньопроцесні записи, які створюються + Gateway і вбудованими plugin для запусків моделей, потоку повідомлень, сеансів, черг + та exec. +- **plugin `diagnostics-otel`** підписується на ці події та експортує їх як + OpenTelemetry **метрики**, **трасування** і **журнали** через OTLP/HTTP. +- Експортери підключаються лише тоді, коли увімкнено і поверхню діагностики, і plugin, + тому внутрішньопроцесні витрати за замовчуванням залишаються майже нульовими. + +## Швидкий початок + +```json5 +{ + plugins: { + allow: ["diagnostics-otel"], + entries: { + "diagnostics-otel": { enabled: true }, + }, + }, + diagnostics: { + enabled: true, + otel: { + enabled: true, + endpoint: "http://otel-collector:4318", + protocol: "http/protobuf", + serviceName: "openclaw-gateway", + traces: true, + metrics: true, + logs: true, + sampleRate: 0.2, + flushIntervalMs: 60000, + }, + }, +} +``` + +Ви також можете увімкнути plugin з CLI: + +```bash +openclaw plugins enable diagnostics-otel +``` + + +`protocol` наразі підтримує лише `http/protobuf`. `grpc` ігнорується. + + +## Експортовані сигнали + +| Сигнал | Що до нього входить | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| **Метрики** | Лічильники та гістограми для використання токенів, вартості, тривалості запуску, потоку повідомлень, смуг черги, стану сеансу, exec і тиску на пам’ять. | +| **Трасування** | Спани для використання моделей, викликів моделей, виконання інструментів, exec, обробки Webhook/повідомлень, збирання контексту та циклів інструментів. | +| **Журнали** | Структуровані записи `logging.file`, експортовані через OTLP, коли увімкнено `diagnostics.otel.logs`. | + +Перемикайте `traces`, `metrics` і `logs` незалежно. Усі три параметри за замовчуванням +увімкнені, коли `diagnostics.otel.enabled` має значення true. + +## Довідник з конфігурації + +```json5 +{ + diagnostics: { + enabled: true, + otel: { + enabled: true, + endpoint: "http://otel-collector:4318", + protocol: "http/protobuf", // grpc ігнорується + serviceName: "openclaw-gateway", + headers: { "x-collector-token": "..." }, + traces: true, + metrics: true, + logs: true, + sampleRate: 0.2, // семплер кореневого спану, 0.0..1.0 + flushIntervalMs: 60000, // інтервал експорту метрик (мінімум 1000 мс) + captureContent: { + enabled: false, + inputMessages: false, + outputMessages: false, + toolInputs: false, + toolOutputs: false, + systemPrompt: false, + }, + }, + }, +} +``` + +### Змінні середовища + +| Variable | Призначення | +| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | Перевизначає `diagnostics.otel.endpoint`. Якщо значення вже містить `/v1/traces`, `/v1/metrics` або `/v1/logs`, воно використовується як є. | +| `OTEL_SERVICE_NAME` | Перевизначає `diagnostics.otel.serviceName`. | +| `OTEL_EXPORTER_OTLP_PROTOCOL` | Перевизначає дротовий протокол (сьогодні враховується лише `http/protobuf`). | +| `OTEL_SEMCONV_STABILITY_OPT_IN` | Установіть значення `gen_ai_latest_experimental`, щоб надсилати найновіший експериментальний атрибут GenAI для спанів (`gen_ai.provider.name`) замість застарілого `gen_ai.system`. Метрики GenAI завжди використовують обмежені семантичні атрибути з низькою кардинальністю незалежно від цього. | +| `OPENCLAW_OTEL_PRELOADED` | Установіть значення `1`, якщо інший preload або хост-процес уже зареєстрував глобальний OpenTelemetry SDK. Тоді plugin пропускає власний життєвий цикл NodeSDK, але все одно підключає слухачі діагностики та враховує `traces`/`metrics`/`logs`. | + +## Конфіденційність і захоплення вмісту + +Необроблений вміст моделі/інструментів **не** експортується за замовчуванням. Спани містять обмежені +ідентифікатори (канал, провайдер, модель, категорія помилки, ідентифікатори запитів лише у вигляді хешів) +і ніколи не включають текст підказки, текст відповіді, входи інструментів, виходи інструментів або ключі сеансу. + +Установлюйте `diagnostics.otel.captureContent.*` у значення `true` лише тоді, коли ваш збирач і +політика зберігання схвалені для тексту підказок, відповідей, інструментів або системних підказок. +Кожен вкладений ключ підключається незалежно: + +- `inputMessages` — вміст користувацької підказки. +- `outputMessages` — вміст відповіді моделі. +- `toolInputs` — корисні навантаження аргументів інструментів. +- `toolOutputs` — корисні навантаження результатів інструментів. +- `systemPrompt` — зібрана системна/розробницька підказка. + +Коли увімкнено будь-який вкладений ключ, спани моделей та інструментів отримують обмежені, відредаговані +атрибути `openclaw.content.*` лише для цього класу. + +## Семплювання та скидання + +- **Трасування:** `diagnostics.otel.sampleRate` (лише для кореневого спану, `0.0` відкидає все, + `1.0` зберігає все). +- **Метрики:** `diagnostics.otel.flushIntervalMs` (мінімум `1000`). +- **Журнали:** журнали OTLP враховують `logging.level` (рівень файлового журналу). До + журналів OTLP **не** застосовується редагування для консолі. Інсталяціям із великим + обсягом даних варто віддавати перевагу семплюванню/фільтруванню на рівні OTLP-збирача, + а не локальному семплюванню. + +## Експортовані метрики + +### Використання моделей + +- `openclaw.tokens` (лічильник, атрибути: `openclaw.token`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`) +- `openclaw.cost.usd` (лічильник, атрибути: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) +- `openclaw.run.duration_ms` (гістограма, атрибути: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) +- `openclaw.context.tokens` (гістограма, атрибути: `openclaw.context`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`) +- `gen_ai.client.token.usage` (гістограма, метрика семантичних угод GenAI, атрибути: `gen_ai.token.type` = `input`/`output`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`) +- `gen_ai.client.operation.duration` (гістограма, секунди, метрика семантичних угод GenAI, атрибути: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, необов’язковий `error.type`) + +### Потік повідомлень + +- `openclaw.webhook.received` (лічильник, атрибути: `openclaw.channel`, `openclaw.webhook`) +- `openclaw.webhook.error` (лічильник, атрибути: `openclaw.channel`, `openclaw.webhook`) +- `openclaw.webhook.duration_ms` (гістограма, атрибути: `openclaw.channel`, `openclaw.webhook`) +- `openclaw.message.queued` (лічильник, атрибути: `openclaw.channel`, `openclaw.source`) +- `openclaw.message.processed` (лічильник, атрибути: `openclaw.channel`, `openclaw.outcome`) +- `openclaw.message.duration_ms` (гістограма, атрибути: `openclaw.channel`, `openclaw.outcome`) +- `openclaw.message.delivery.started` (лічильник, атрибути: `openclaw.channel`, `openclaw.delivery.kind`) +- `openclaw.message.delivery.duration_ms` (гістограма, атрибути: `openclaw.channel`, `openclaw.delivery.kind`, `openclaw.outcome`, `openclaw.errorCategory`) + +### Черги та сеанси + +- `openclaw.queue.lane.enqueue` (лічильник, атрибути: `openclaw.lane`) +- `openclaw.queue.lane.dequeue` (лічильник, атрибути: `openclaw.lane`) +- `openclaw.queue.depth` (гістограма, атрибути: `openclaw.lane` або `openclaw.channel=heartbeat`) +- `openclaw.queue.wait_ms` (гістограма, атрибути: `openclaw.lane`) +- `openclaw.session.state` (лічильник, атрибути: `openclaw.state`, `openclaw.reason`) +- `openclaw.session.stuck` (лічильник, атрибути: `openclaw.state`) +- `openclaw.session.stuck_age_ms` (гістограма, атрибути: `openclaw.state`) +- `openclaw.run.attempt` (лічильник, атрибути: `openclaw.attempt`) + +### Exec + +- `openclaw.exec.duration_ms` (гістограма, атрибути: `openclaw.exec.target`, `openclaw.exec.mode`, `openclaw.outcome`, `openclaw.failureKind`) + +### Внутрішні метрики діагностики (пам’ять і цикл інструментів) + +- `openclaw.memory.heap_used_bytes` (гістограма, атрибути: `openclaw.memory.kind`) +- `openclaw.memory.rss_bytes` (гістограма) +- `openclaw.memory.pressure` (лічильник, атрибути: `openclaw.memory.level`) +- `openclaw.tool.loop.iterations` (лічильник, атрибути: `openclaw.toolName`, `openclaw.outcome`) +- `openclaw.tool.loop.duration_ms` (гістограма, атрибути: `openclaw.toolName`, `openclaw.outcome`) + +## Експортовані спани + +- `openclaw.model.usage` + - `openclaw.channel`, `openclaw.provider`, `openclaw.model` + - `openclaw.tokens.*` (input/output/cache_read/cache_write/total) + - `gen_ai.system` за замовчуванням, або `gen_ai.provider.name`, якщо ввімкнено найновіші семантичні угоди GenAI + - `gen_ai.request.model`, `gen_ai.operation.name`, `gen_ai.usage.*` +- `openclaw.run` + - `openclaw.outcome`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.errorCategory` +- `openclaw.model.call` + - `gen_ai.system` за замовчуванням, або `gen_ai.provider.name`, якщо ввімкнено найновіші семантичні угоди GenAI + - `gen_ai.request.model`, `gen_ai.operation.name`, `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport` + - `openclaw.provider.request_id_hash` (обмежений хеш на основі SHA для ідентифікатора запиту до зовнішнього провайдера; сирі ідентифікатори не експортуються) +- `openclaw.tool.execution` + - `gen_ai.tool.name`, `openclaw.toolName`, `openclaw.errorCategory`, `openclaw.tool.params.*` +- `openclaw.exec` + - `openclaw.exec.target`, `openclaw.exec.mode`, `openclaw.outcome`, `openclaw.failureKind`, `openclaw.exec.command_length`, `openclaw.exec.exit_code`, `openclaw.exec.timed_out` +- `openclaw.webhook.processed` + - `openclaw.channel`, `openclaw.webhook`, `openclaw.chatId` +- `openclaw.webhook.error` + - `openclaw.channel`, `openclaw.webhook`, `openclaw.chatId`, `openclaw.error` +- `openclaw.message.processed` + - `openclaw.channel`, `openclaw.outcome`, `openclaw.chatId`, `openclaw.messageId`, `openclaw.reason` +- `openclaw.message.delivery` + - `openclaw.channel`, `openclaw.delivery.kind`, `openclaw.outcome`, `openclaw.errorCategory`, `openclaw.delivery.result_count` +- `openclaw.session.stuck` + - `openclaw.state`, `openclaw.ageMs`, `openclaw.queueDepth` +- `openclaw.context.assembled` + - `openclaw.prompt.size`, `openclaw.history.size`, `openclaw.context.tokens`, `openclaw.errorCategory` (без вмісту підказки, історії, відповіді або ключа сеансу) +- `openclaw.tool.loop` + - `openclaw.toolName`, `openclaw.outcome`, `openclaw.iterations`, `openclaw.errorCategory` (без повідомлень циклу, параметрів або виводу інструмента) +- `openclaw.memory.pressure` + - `openclaw.memory.level`, `openclaw.memory.heap_used_bytes`, `openclaw.memory.rss_bytes` + +Коли захоплення вмісту явно ввімкнено, спани моделей та інструментів також можуть +містити обмежені, відредаговані атрибути `openclaw.content.*` для конкретних +класів вмісту, які ви ввімкнули. + +## Каталог подій діагностики + +Події нижче є основою для метрик і спанів вище. Plugin також можуть підписуватися +на них напряму без експорту через OTLP. + +**Використання моделей** + +- `model.usage` — токени, вартість, тривалість, контекст, провайдер/модель/канал, + ідентифікатори сеансів. `usage` — це облік провайдера/ходу для вартості й телеметрії; + `context.used` — це знімок поточного prompt/контексту, і він може бути меншим за + `usage.total` провайдера, коли задіяно кешований вхід або виклики циклу інструментів. + +**Потік повідомлень** + +- `webhook.received` / `webhook.processed` / `webhook.error` +- `message.queued` / `message.processed` +- `message.delivery.started` / `message.delivery.completed` / `message.delivery.error` + +**Черга та сеанс** + +- `queue.lane.enqueue` / `queue.lane.dequeue` +- `session.state` / `session.stuck` +- `run.attempt` +- `diagnostic.heartbeat` (агреговані лічильники: Webhook/черга/сеанс) + +**Exec** + +- `exec.process.completed` — фінальний результат, тривалість, ціль, режим, код + виходу та тип збою. Текст команди й робочі каталоги не + включаються. + +## Без експортера + +Ви можете залишити події діагностики доступними для plugin або користувацьких приймачів без +запуску `diagnostics-otel`: + +```json5 +{ + diagnostics: { enabled: true }, +} +``` + +Для цільового виводу налагодження без підвищення `logging.level` використовуйте +прапори діагностики. Прапори нечутливі до регістру та підтримують шаблони (наприклад, `telegram.*` або +`*`): + +```json5 +{ + diagnostics: { flags: ["telegram.http"] }, +} +``` + +Або як одноразове перевизначення через змінну середовища: + +```bash +OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway +``` + +Вивід прапорів записується до стандартного файлу журналу (`logging.file`) і все ще +редагується через `logging.redactSensitive`. Повний посібник: +[Прапори діагностики](/uk/diagnostics/flags). + +## Вимкнення + +```json5 +{ + diagnostics: { otel: { enabled: false } }, +} +``` + +Ви також можете не додавати `diagnostics-otel` до `plugins.allow` або виконати +`openclaw plugins disable diagnostics-otel`. + +## Пов’язане + +- [Журналювання](/uk/logging) — файлові журнали, консольний вивід, tailing у CLI та вкладка Logs у Control UI +- [Внутрішня структура журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі +- [Прапори діагностики](/uk/diagnostics/flags) — прапори цільового журналювання налагодження +- [Експорт діагностики](/uk/gateway/diagnostics) — інструмент пакета підтримки для операторів (окремо від експорту OTEL) +- [Довідник з конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник з полів `diagnostics.*` diff --git a/docs/uk/logging.md b/docs/uk/logging.md index 55fcae28e..cc81d25db 100644 --- a/docs/uk/logging.md +++ b/docs/uk/logging.md @@ -1,27 +1,26 @@ --- read_when: - - Вам потрібен огляд журналювання, дружній до початківців - - Ви хочете налаштувати рівні або формати журналювання - - Ви усуваєте несправності й вам потрібно швидко знайти журнали -summary: 'Огляд журналювання: журнали файлів, виведення в консоль, перегляд через CLI та Control UI' -title: Огляд журналювання + - Вам потрібен огляд журналювання OpenClaw, зрозумілий для початківців. + - Ви хочете налаштувати рівні журналювання, формати або редагування конфіденційних даних. + - Ви усуваєте неполадки й вам потрібно швидко знайти журнали. +summary: Журнали файлів, вивід консолі, CLI tailing і вкладка Logs в Control UI +title: Журналювання x-i18n: - generated_at: "2026-04-25T19:33:45Z" + generated_at: "2026-04-25T23:50:25Z" model: gpt-5.4 provider: openai - source_hash: 47bd7c3c515248ba2580bd372417e5842f6936bcc92b0fd83301491293d0be2c + source_hash: 01b139a45937e4a718837ddcf58cfcf6f0230e416942fd6844c27d0c7d71605e source_path: logging.md workflow: 15 --- -# Журналювання - OpenClaw має дві основні поверхні журналювання: -- **Файлові журнали** (рядки JSON), які записує Gateway. -- **Виведення в консоль**, яке показується в терміналах і в Gateway Debug UI. +- **Журнали файлів** (рядки JSON), які записує Gateway. +- **Вивід консолі**, що показується в терміналах і в Gateway Debug UI. -Вкладка **Logs** у Control UI відстежує файловий журнал gateway. На цій сторінці пояснюється, де зберігаються журнали, як їх читати та як налаштовувати рівні й формати журналювання. +Вкладка **Logs** у Control UI виконує tail для журналу файлу gateway. На цій сторінці +пояснюється, де зберігаються журнали, як їх читати та як налаштовувати рівні й формати журналювання. ## Де зберігаються журнали @@ -43,9 +42,9 @@ OpenClaw має дві основні поверхні журналювання: ## Як читати журнали -### CLI: перегляд у реальному часі (рекомендовано) +### CLI: live tail (рекомендовано) -Використовуйте CLI, щоб відстежувати файл журналу gateway через RPC: +Використовуйте CLI, щоб виконувати tail для файлу журналу gateway через RPC: ```bash openclaw logs --follow @@ -55,28 +54,32 @@ openclaw logs --follow - `--local-time`: відображати часові мітки у вашому локальному часовому поясі - `--url ` / `--token ` / `--timeout `: стандартні прапорці Gateway RPC -- `--expect-final`: прапорець очікування фінальної відповіді для RPC із підтримкою агентів (тут підтримується через спільний клієнтський шар) +- `--expect-final`: прапорець очікування фінальної відповіді для RPC на основі агентів (тут приймається через спільний клієнтський шар) -Режими виведення: +Режими виводу: -- **TTY-сеанси**: зручні для читання, кольорові, структуровані рядки журналу. +- **TTY-сеанси**: гарні, кольорові, структуровані рядки журналу. - **Не-TTY-сеанси**: звичайний текст. - `--json`: JSON із розділенням по рядках (одна подія журналу на рядок). - `--plain`: примусово використовувати звичайний текст у TTY-сеансах. -- `--no-color`: вимкнути ANSI-кольори. +- `--no-color`: вимкнути кольори ANSI. -Коли ви передаєте явний `--url`, CLI не застосовує автоматично облікові дані з конфігурації або середовища; додайте `--token` самостійно, якщо цільовий Gateway вимагає автентифікації. +Коли ви передаєте явний `--url`, CLI не застосовує автоматично облікові дані з конфігурації або +середовища; якщо цільовий Gateway +вимагає автентифікацію, самостійно додайте `--token`. -У режимі JSON CLI виводить об’єкти з міткою `type`: +У режимі JSON CLI виводить об’єкти з позначкою `type`: - `meta`: метадані потоку (файл, курсор, розмір) - `log`: розібраний запис журналу - `notice`: підказки про обрізання / ротацію - `raw`: нерозібраний рядок журналу -Якщо Gateway local loopback запитує сполучення, `openclaw logs` автоматично переключається на налаштований локальний файл журналу. Явні цілі `--url` не використовують цей резервний механізм. +Якщо local loopback Gateway запитує pairing, `openclaw logs` автоматично повертається +до налаштованого локального файлу журналу. Явні цілі `--url` не +використовують цей резервний варіант. -Якщо Gateway недоступний, CLI показує коротку підказку виконати: +Якщо Gateway недоступний, CLI виводить коротку підказку виконати: ```bash openclaw doctor @@ -84,12 +87,12 @@ openclaw doctor ### Control UI (веб) -Вкладка **Logs** у Control UI відстежує той самий файл за допомогою `logs.tail`. +Вкладка **Logs** у Control UI виконує tail того самого файлу за допомогою `logs.tail`. Див. [/web/control-ui](/uk/web/control-ui), щоб дізнатися, як її відкрити. -### Журнали лише каналу +### Журнали лише каналів -Щоб відфільтрувати активність каналу (WhatsApp/Telegram тощо), використовуйте: +Щоб фільтрувати активність каналів (WhatsApp/Telegram тощо), використовуйте: ```bash openclaw channels logs --channel whatsapp @@ -97,27 +100,28 @@ openclaw channels logs --channel whatsapp ## Формати журналів -### Файлові журнали (JSONL) +### Журнали файлів (JSONL) -Кожен рядок у файлі журналу — це JSON-об’єкт. CLI і Control UI розбирають ці записи, щоб відображати структуроване виведення (час, рівень, підсистема, повідомлення). +Кожен рядок у файлі журналу — це об’єкт JSON. CLI і Control UI аналізують ці +записи, щоб відображати структурований вивід (час, рівень, підсистема, повідомлення). -### Виведення в консоль +### Вивід консолі Журнали консолі **враховують TTY** і форматуються для зручності читання: - Префікси підсистем (наприклад, `gateway/channels/whatsapp`) -- Кольорове позначення рівня (info/warn/error) -- Необов’язковий компактний режим або режим JSON +- Кольори рівнів (info/warn/error) +- Необов’язковий компактний або JSON-режим -Форматування консолі керується через `logging.consoleStyle`. +Форматування консолі керується `logging.consoleStyle`. -### Журнали Gateway WebSocket +### Журнали WebSocket Gateway `openclaw gateway` також має журналювання протоколу WebSocket для RPC-трафіку: - звичайний режим: лише цікаві результати (помилки, помилки розбору, повільні виклики) - `--verbose`: увесь трафік запитів/відповідей -- `--ws-log auto|compact|full`: вибір стилю детального відображення +- `--ws-log auto|compact|full`: вибір стилю докладного відображення - `--compact`: псевдонім для `--ws-log compact` Приклади: @@ -130,7 +134,7 @@ openclaw gateway --verbose --ws-log full ## Налаштування журналювання -Усі налаштування журналювання розміщені в `logging` у `~/.openclaw/openclaw.json`. +Уся конфігурація журналювання знаходиться в `logging` у `~/.openclaw/openclaw.json`. ```json { @@ -147,339 +151,71 @@ openclaw gateway --verbose --ws-log full ### Рівні журналювання -- `logging.level`: рівень **файлових журналів** (JSONL). -- `logging.consoleLevel`: рівень деталізації **консолі**. +- `logging.level`: рівень **журналів файлів** (JSONL). +- `logging.consoleLevel`: рівень докладності **консолі**. -Ви можете перевизначити обидва значення через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має вищий пріоритет, ніж файл конфігурації, тому ви можете підвищити деталізацію для одного запуску без редагування `openclaw.json`. Ви також можете передати глобальний параметр CLI **`--log-level `** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди. +Ви можете перевизначити обидва через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має пріоритет над файлом конфігурації, тож ви можете підвищити докладність для одного запуску без редагування `openclaw.json`. Також можна передати глобальний параметр CLI **`--log-level `** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди. -`--verbose` впливає лише на виведення в консоль і деталізацію журналів WS; він не змінює рівні файлових журналів. +`--verbose` впливає лише на вивід консолі та докладність WS-журналу; він не змінює +рівні журналів файлів. ### Стилі консолі `logging.consoleStyle`: -- `pretty`: зручно для читання, з кольорами та часовими мітками. -- `compact`: щільніше виведення (найкраще для тривалих сеансів). -- `json`: JSON на рядок (для обробників журналів). +- `pretty`: зручно для людей, кольорово, із часовими мітками. +- `compact`: щільніший вивід (найкраще для довгих сеансів). +- `json`: JSON у кожному рядку (для обробників журналів). -### Редагування чутливих даних +### Редагування конфіденційних даних -Підсумки інструментів можуть приховувати чутливі токени до того, як вони потраплять у консоль: +Підсумки інструментів можуть редагувати конфіденційні токени до того, як вони потраплять у консоль: - `logging.redactSensitive`: `off` | `tools` (типово: `tools`) - `logging.redactPatterns`: список рядків regex для перевизначення типового набору -Приховування чутливих даних впливає **лише на виведення в консоль** і не змінює файлові журнали. +Редагування конфіденційних даних впливає **лише на вивід консолі** і не змінює журнали файлів. -## Діагностика + OpenTelemetry +## Діагностика та OpenTelemetry -Діагностика — це структуровані, машиночитані події для запусків моделей **і** -телеметрії потоку повідомлень (webhooks, постановка в чергу, стан сесії). Вони **не** -замінюють журнали; вони існують для передачі метрик, трасувань та інших даних у експортери. +Діагностика — це структуровані, машинозчитувані події для запусків моделей і +телеметрії потоку повідомлень (webhooks, черги, стан сеансу). Вони **не** +замінюють журнали — вони живлять метрики, трасування та експортери. Події генеруються +в процесі незалежно від того, експортуєте ви їх чи ні. -Події діагностики створюються в процесі, але експортери підключаються лише тоді, коли ввімкнено діагностику + плагін експорту. +Дві суміжні поверхні: -### OpenTelemetry vs OTLP +- **Експорт OpenTelemetry** — надсилання метрик, трасувань і журналів через OTLP/HTTP до + будь-якого колектора або бекенда, сумісного з OpenTelemetry (Grafana, Datadog, + Honeycomb, New Relic, Tempo тощо). Повна конфігурація, каталог сигналів, + назви метрик/span, змінні середовища та модель конфіденційності описані на окремій сторінці: + [Експорт OpenTelemetry](/uk/gateway/opentelemetry). +- **Прапорці діагностики** — цільові прапорці debug-журналу, які спрямовують додаткові журнали в + `logging.file` без підвищення `logging.level`. Прапорці нечутливі до регістру + та підтримують wildcard-вирази (`telegram.*`, `*`). Налаштовуються в `diagnostics.flags` + або через перевизначення змінною середовища `OPENCLAW_DIAGNOSTICS=...`. Повний посібник: + [Прапорці діагностики](/uk/diagnostics/flags). -- **OpenTelemetry (OTel)**: модель даних + SDK для трасувань, метрик і журналів. -- **OTLP**: мережевий протокол, який використовується для експорту даних OTel до колектора/бекенда. -- OpenClaw зараз експортує через **OTLP/HTTP (protobuf)**. +Щоб увімкнути події діагностики для Plugin або спеціальних sink без експорту OTLP: -### Експортовані сигнали - -- **Метрики**: лічильники + гістограми (використання токенів, потік повідомлень, черги). -- **Трасування**: span-и для використання моделей + обробки webhook/повідомлень. -- **Журнали**: експортуються через OTLP, коли ввімкнено `diagnostics.otel.logs`. Обсяг журналів може бути великим; зважайте на `logging.level` і фільтри експортера. - -### Каталог діагностичних подій - -Використання моделі: - -- `model.usage`: токени, вартість, тривалість, контекст, провайдер/модель/канал, ідентифікатори сесії. - `usage` — це облік провайдера/ходу для вартості та телеметрії; `context.used` - — це поточний знімок запиту/контексту і він може бути меншим за `usage.total` - від провайдера, коли задіяно кешований вхід або виклики циклу інструментів. - -Потік повідомлень: - -- `webhook.received`: вхідний webhook для кожного каналу. -- `webhook.processed`: webhook оброблено + тривалість. -- `webhook.error`: помилки обробника webhook. -- `message.queued`: повідомлення поставлено в чергу на обробку. -- `message.processed`: результат + тривалість + необов’язкова помилка. -- `message.delivery.started`: почато спробу вихідної доставки. -- `message.delivery.completed`: завершено спробу вихідної доставки + тривалість/кількість результатів. -- `message.delivery.error`: спроба вихідної доставки завершилася помилкою + тривалість/обмежена категорія помилки. - -Черга + сесія: - -- `queue.lane.enqueue`: додавання в lane черги команд + глибина. -- `queue.lane.dequeue`: вилучення з lane черги команд + час очікування. -- `session.state`: перехід стану сесії + причина. -- `session.stuck`: попередження про завислу сесію + вік. -- `run.attempt`: метадані повторної спроби/спроби запуску. -- `diagnostic.heartbeat`: агреговані лічильники (webhooks/черга/сесія). - -Виконання: - -- `exec.process.completed`: результат процесу terminal exec, тривалість, ціль, режим, - код виходу та тип помилки. Текст команди й робочі каталоги не - включаються. - -### Увімкнення діагностики (без експортера) - -Використовуйте це, якщо хочете, щоб події діагностики були доступні для Plugin або власних приймачів: - -```json +```json5 { - "diagnostics": { - "enabled": true - } + diagnostics: { enabled: true }, } ``` -### Прапорці діагностики (цільові журнали) +Для експорту OTLP до колектора див. [Експорт OpenTelemetry](/uk/gateway/opentelemetry). -Використовуйте прапорці, щоб увімкнути додаткові цільові журнали налагодження без підвищення `logging.level`. -Прапорці нечутливі до регістру й підтримують wildcards (наприклад, `telegram.*` або `*`). - -```json -{ - "diagnostics": { - "flags": ["telegram.http"] - } -} -``` - -Перевизначення через середовище (одноразово): - -``` -OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload -``` - -Примітки: - -- Журнали прапорців потрапляють до стандартного файлу журналу (того самого, що й `logging.file`). -- Виведення все одно редагується відповідно до `logging.redactSensitive`. -- Повний посібник: [/diagnostics/flags](/uk/diagnostics/flags). - -### Експорт у OpenTelemetry - -Діагностику можна експортувати через плагін `diagnostics-otel` (OTLP/HTTP). Це -працює з будь-яким колектором/бекендом OpenTelemetry, який приймає OTLP/HTTP. - -```json -{ - "plugins": { - "allow": ["diagnostics-otel"], - "entries": { - "diagnostics-otel": { - "enabled": true - } - } - }, - "diagnostics": { - "enabled": true, - "otel": { - "enabled": true, - "endpoint": "http://otel-collector:4318", - "protocol": "http/protobuf", - "serviceName": "openclaw-gateway", - "traces": true, - "metrics": true, - "logs": true, - "sampleRate": 0.2, - "flushIntervalMs": 60000, - "captureContent": { - "enabled": false, - "inputMessages": false, - "outputMessages": false, - "toolInputs": false, - "toolOutputs": false, - "systemPrompt": false - } - } - } -} -``` - -Примітки: - -- Ви також можете ввімкнути плагін за допомогою `openclaw plugins enable diagnostics-otel`. -- `protocol` наразі підтримує лише `http/protobuf`. `grpc` ігнорується. -- Метрики включають використання токенів, вартість, розмір контексту, тривалість запуску та - лічильники/гістограми потоку повідомлень (webhooks, черги, стан сесії, глибина/очікування черги), - а також гістограми використання GenAI токенів і тривалості викликів моделі. -- Трасування/метрики можна вмикати й вимикати через `traces` / `metrics` (типово: увімкнено). Трасування - включають span-и використання моделей, а також span-и обробки webhook/повідомлень, якщо це ввімкнено. -- Необроблений вміст моделі/інструментів типово не експортується. Використовуйте - `diagnostics.otel.captureContent` лише тоді, коли ваш колектор і політика зберігання - схвалені для тексту запитів, відповідей, інструментів або системного запиту. -- Встановіть `headers`, якщо ваш колектор вимагає автентифікації. -- Підтримувані змінні середовища: `OTEL_EXPORTER_OTLP_ENDPOINT`, - `OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_PROTOCOL`. -- Встановіть `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`, щоб передавати - найновіший експериментальний атрибут span провайдера GenAI (`gen_ai.provider.name`) - замість застарілого атрибута span (`gen_ai.system`). Метрики GenAI завжди - використовують обмежені семантичні атрибути з низькою кардинальністю. -- Встановіть `OPENCLAW_OTEL_PRELOADED=1`, якщо інше попереднє завантаження або хост-процес уже - зареєстрував глобальний OpenTelemetry SDK. У цьому режимі плагін не запускає - і не завершує власний SDK, але все одно підключає слухачі діагностики OpenClaw і - враховує `diagnostics.otel.traces`, `metrics` і `logs`. - -### Експортовані метрики (назви + типи) - -Використання моделі: - -- `openclaw.tokens` (лічильник, атрибути: `openclaw.token`, `openclaw.channel`, - `openclaw.provider`, `openclaw.model`) -- `openclaw.cost.usd` (лічильник, атрибути: `openclaw.channel`, `openclaw.provider`, - `openclaw.model`) -- `openclaw.run.duration_ms` (гістограма, атрибути: `openclaw.channel`, - `openclaw.provider`, `openclaw.model`) -- `openclaw.context.tokens` (гістограма, атрибути: `openclaw.context`, - `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `gen_ai.client.token.usage` (гістограма, метрика семантичних конвенцій GenAI, - атрибути: `gen_ai.token.type` = `input`/`output`, `gen_ai.provider.name`, - `gen_ai.operation.name`, `gen_ai.request.model`) -- `gen_ai.client.operation.duration` (гістограма, секунди, метрика - семантичних конвенцій GenAI, атрибути: `gen_ai.provider.name`, - `gen_ai.operation.name`, `gen_ai.request.model`, необов’язковий `error.type`) - -Потік повідомлень: - -- `openclaw.webhook.received` (лічильник, атрибути: `openclaw.channel`, - `openclaw.webhook`) -- `openclaw.webhook.error` (лічильник, атрибути: `openclaw.channel`, - `openclaw.webhook`) -- `openclaw.webhook.duration_ms` (гістограма, атрибути: `openclaw.channel`, - `openclaw.webhook`) -- `openclaw.message.queued` (лічильник, атрибути: `openclaw.channel`, - `openclaw.source`) -- `openclaw.message.processed` (лічильник, атрибути: `openclaw.channel`, - `openclaw.outcome`) -- `openclaw.message.duration_ms` (гістограма, атрибути: `openclaw.channel`, - `openclaw.outcome`) -- `openclaw.message.delivery.started` (лічильник, атрибути: `openclaw.channel`, - `openclaw.delivery.kind`) -- `openclaw.message.delivery.duration_ms` (гістограма, атрибути: - `openclaw.channel`, `openclaw.delivery.kind`, `openclaw.outcome`, - `openclaw.errorCategory`) - -Черги + сесії: - -- `openclaw.queue.lane.enqueue` (лічильник, атрибути: `openclaw.lane`) -- `openclaw.queue.lane.dequeue` (лічильник, атрибути: `openclaw.lane`) -- `openclaw.queue.depth` (гістограма, атрибути: `openclaw.lane` або - `openclaw.channel=heartbeat`) -- `openclaw.queue.wait_ms` (гістограма, атрибути: `openclaw.lane`) -- `openclaw.session.state` (лічильник, атрибути: `openclaw.state`, `openclaw.reason`) -- `openclaw.session.stuck` (лічильник, атрибути: `openclaw.state`) -- `openclaw.session.stuck_age_ms` (гістограма, атрибути: `openclaw.state`) -- `openclaw.run.attempt` (лічильник, атрибути: `openclaw.attempt`) - -Виконання: - -- `openclaw.exec.duration_ms` (гістограма, атрибути: `openclaw.exec.target`, - `openclaw.exec.mode`, `openclaw.outcome`, `openclaw.failureKind`) - -Внутрішні метрики діагностики (пам’ять + цикл інструментів): - -- `openclaw.memory.heap_used_bytes` (гістограма, атрибути: `openclaw.memory.kind`) -- `openclaw.memory.rss_bytes` (гістограма) -- `openclaw.memory.pressure` (лічильник, атрибути: `openclaw.memory.level`) -- `openclaw.tool.loop.iterations` (лічильник, атрибути: `openclaw.toolName`, - `openclaw.outcome`) -- `openclaw.tool.loop.duration_ms` (гістограма, атрибути: `openclaw.toolName`, - `openclaw.outcome`) - -### Експортовані span-и (назви + ключові атрибути) - -- `openclaw.model.usage` - - `openclaw.channel`, `openclaw.provider`, `openclaw.model` - - `openclaw.tokens.*` (input/output/cache_read/cache_write/total) - - `gen_ai.system` за замовчуванням, або `gen_ai.provider.name`, коли ввімкнено - найновіші семантичні конвенції GenAI - - `gen_ai.request.model`, `gen_ai.operation.name`, `gen_ai.usage.*` -- `openclaw.run` - - `openclaw.outcome`, `openclaw.channel`, `openclaw.provider`, - `openclaw.model`, `openclaw.errorCategory` -- `openclaw.model.call` - - `gen_ai.system` за замовчуванням, або `gen_ai.provider.name`, коли ввімкнено - найновіші семантичні конвенції GenAI - - `gen_ai.request.model`, `gen_ai.operation.name`, - `openclaw.provider`, `openclaw.model`, `openclaw.api`, - `openclaw.transport`, `openclaw.provider.request_id_hash` (обмежений - SHA-хеш ідентифікатора запиту до висхідного провайдера; сирі ідентифікатори - не експортуються) -- `openclaw.tool.execution` - - `gen_ai.tool.name`, `openclaw.toolName`, `openclaw.errorCategory`, - `openclaw.tool.params.*` -- `openclaw.exec` - - `openclaw.exec.target`, `openclaw.exec.mode`, `openclaw.outcome`, - `openclaw.failureKind`, `openclaw.exec.command_length`, - `openclaw.exec.exit_code`, `openclaw.exec.timed_out` -- `openclaw.webhook.processed` - - `openclaw.channel`, `openclaw.webhook`, `openclaw.chatId` -- `openclaw.webhook.error` - - `openclaw.channel`, `openclaw.webhook`, `openclaw.chatId`, - `openclaw.error` -- `openclaw.message.processed` - - `openclaw.channel`, `openclaw.outcome`, `openclaw.chatId`, - `openclaw.messageId`, `openclaw.reason` -- `openclaw.message.delivery` - - `openclaw.channel`, `openclaw.delivery.kind`, `openclaw.outcome`, - `openclaw.errorCategory`, `openclaw.delivery.result_count` -- `openclaw.session.stuck` - - `openclaw.state`, `openclaw.ageMs`, `openclaw.queueDepth` -- `openclaw.context.assembled` - - `openclaw.prompt.size`, `openclaw.history.size`, - `openclaw.context.tokens`, `openclaw.errorCategory` (без вмісту запиту, - історії, відповіді або ключа сесії) -- `openclaw.tool.loop` - - `openclaw.toolName`, `openclaw.outcome`, `openclaw.iterations`, - `openclaw.errorCategory` (без повідомлень циклу, параметрів або виводу інструмента) -- `openclaw.memory.pressure` - - `openclaw.memory.level`, `openclaw.memory.heap_used_bytes`, - `openclaw.memory.rss_bytes` - -Коли захоплення вмісту явно ввімкнене, span-и моделі/інструментів також можуть включати -обмежені, відредаговані атрибути `openclaw.content.*` для конкретних класів вмісту, -які ви вибрали. - -### Семплювання + скидання - -- Семплювання трасувань: `diagnostics.otel.sampleRate` (0.0–1.0, лише кореневі span-и). -- Інтервал експорту метрик: `diagnostics.otel.flushIntervalMs` (мінімум 1000 мс). - -### Примітки щодо протоколу - -- Кінцеві точки OTLP/HTTP можна задати через `diagnostics.otel.endpoint` або - `OTEL_EXPORTER_OTLP_ENDPOINT`. -- Якщо кінцева точка вже містить `/v1/traces` або `/v1/metrics`, вона використовується як є. -- Якщо кінцева точка вже містить `/v1/logs`, вона використовується як є для журналів. -- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental` керує лише формою - атрибута провайдера span GenAI. Наявні панелі, які читають - `gen_ai.system`, можуть залишатися на типовому варіанті, доки не буде виконано міграцію. -- `OPENCLAW_OTEL_PRELOADED=1` повторно використовує зовнішньо зареєстрований OpenTelemetry SDK - для трасувань/метрик замість запуску NodeSDK, що належить плагіну. -- `diagnostics.otel.logs` вмикає експорт журналів OTLP для основного виведення логера. - -### Поведінка експорту журналів - -- Журнали OTLP використовують ті самі структуровані записи, що записуються в `logging.file`. -- Дотримуються `logging.level` (рівень файлових журналів). Редагування консолі **не** застосовується - до журналів OTLP. -- Для інсталяцій із великим обсягом журналів слід надавати перевагу семплюванню/фільтрації в OTLP collector. - -## Поради з усунення несправностей +## Поради з усунення неполадок - **Gateway недоступний?** Спочатку виконайте `openclaw doctor`. -- **Журнали порожні?** Перевірте, чи Gateway запущений і чи записує у шлях до файлу, +- **Журнали порожні?** Перевірте, що Gateway запущено і він записує у шлях до файлу, вказаний у `logging.file`. -- **Потрібно більше деталей?** Встановіть `logging.level` у `debug` або `trace` і повторіть спробу. +- **Потрібно більше деталей?** Установіть `logging.level` у `debug` або `trace` і повторіть спробу. ## Пов’язане -- [Внутрішня будова журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі -- [Діагностика](/uk/gateway/configuration-reference#diagnostics) — експорт OpenTelemetry і конфігурація трасування кешу +- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — експорт OTLP/HTTP, каталог метрик/span, модель конфіденційності +- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці debug-журналу +- [Внутрішня будова журналювання Gateway](/uk/gateway/logging) — стилі WS-журналу, префікси підсистем і захоплення консолі +- [Довідник з конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*`