diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index a958a6e94..538e140ac 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -1,61 +1,61 @@ --- read_when: - Вам потрібні точні семантики полів конфігурації або значення за замовчуванням - - Ви перевіряєте блоки конфігурації каналу, моделі, Gateway або інструмента -summary: Довідник конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем -title: Довідник конфігурації + - Ви перевіряєте блоки конфігурації каналів, моделей, Gateway або інструментів +summary: Довідник з конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем +title: Довідник з конфігурації x-i18n: - generated_at: "2026-04-24T19:33:59Z" + generated_at: "2026-04-24T23:44:41Z" model: gpt-5.4 provider: openai - source_hash: f54e51abc83dd7e72cc4220fa881f488cfb441b97710ba6852382814d4055344 + source_hash: 94a945cbe0633c75e55b99324ae9174a7c82770b07bd773fe82f342f67c5a44c source_path: gateway/configuration-reference.md workflow: 15 --- -Основний довідник конфігурації для `~/.openclaw/openclaw.json`. Огляд, орієнтований на завдання, див. у [Configuration](/uk/gateway/configuration). +Основний довідник з конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration). -Ця сторінка охоплює основні поверхні конфігурації OpenClaw і дає посилання назовні, коли підсистема має власний докладніший довідник. Вона **не** намагається вбудувати на одній сторінці кожен каталог команд, що належить каналу/Plugin, або кожен глибокий параметр пам’яті/QMD. +На цій сторінці описано основні поверхні конфігурації OpenClaw і наведено посилання туди, де підсистема має власний докладніший довідник. Вона **не** намагається вбудувати на одній сторінці кожен каталог команд, що належить каналу/Plugin, або всі глибокі параметри memory/QMD. Джерело істини в коді: -- `openclaw config schema` виводить актуальну схему JSON Schema, що використовується для валідації та інтерфейсу Control UI, з об’єднаними метаданими bundled/plugin/channel, коли вони доступні -- `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів деталізованого перегляду -- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють хеш базового стану config-doc щодо поточної поверхні схеми +- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та Control UI, із вбудованими метаданими Plugin/каналів, об’єднаними за наявності +- `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 для поверхонь команд, специфічних для каналів +- [Slash Commands](/uk/tools/slash-commands) для поточного вбудованого + комплектного каталогу команд +- сторінки каналу/Plugin-власника для поверхонь команд, специфічних для каналу -Формат конфігурації — **JSON5** (дозволені коментарі та фінальні коми). Усі поля необов’язкові — якщо їх пропущено, OpenClaw використовує безпечні значення за замовчуванням. +Формат конфігурації — **JSON5** (дозволені коментарі й кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено. --- ## Канали -Ключі конфігурації для кожного каналу перенесено на окрему сторінку — див. +Ключі конфігурації для кожного каналу винесено на окрему сторінку — див. [Configuration — channels](/uk/gateway/config-channels) для `channels.*`, зокрема для Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та інших -bundled каналів (автентифікація, контроль доступу, кілька облікових записів, обмеження за згадуваннями). +комплектних каналів (автентифікація, керування доступом, кілька облікових записів, обмеження за згадуванням). -## Типові значення агента, multi-agent, сесії та повідомлення +## Типові налаштування агентів, multi-agent, сесії та повідомлення -Перенесено на окрему сторінку — див. +Винесено на окрему сторінку — див. [Configuration — agents](/uk/gateway/config-agents) для: -- `agents.defaults.*` (робоча область, модель, thinking, heartbeat, пам’ять, медіа, skills, sandbox) -- `multiAgent.*` (маршрутизація multi-agent і прив’язки) -- `session.*` (життєвий цикл сесії, compaction, pruning) +- `agents.defaults.*` (робочий простір, модель, thinking, heartbeat, memory, media, skills, sandbox) +- `multiAgent.*` (маршрутизація та прив’язки multi-agent) +- `session.*` (життєвий цикл сесії, compaction, очищення) - `messages.*` (доставка повідомлень, TTS, рендеринг markdown) - `talk.*` (режим Talk) - `talk.silenceTimeoutMs`: якщо не задано, Talk зберігає стандартне для платформи вікно паузи перед надсиланням транскрипту (`700 ms на macOS і Android, 900 ms на iOS`) -## Інструменти та користувацькі провайдери +## Інструменти й користувацькі провайдери -Політика інструментів, експериментальні перемикачі, конфігурація інструментів на основі провайдерів і налаштування користувацьких -провайдерів / base-URL перенесені на окрему сторінку — див. +Політика інструментів, експериментальні перемикачі, конфігурація інструментів на базі провайдерів, а також налаштування користувацьких +провайдерів / базових URL винесено на окрему сторінку — див. [Configuration — tools and custom providers](/uk/gateway/config-tools). ## Skills @@ -83,14 +83,12 @@ bundled каналів (автентифікація, контроль дост } ``` -- `allowBundled`: необов’язковий список дозволених лише для bundled skills (керовані/workspace skills це не зачіпає). +- `allowBundled`: необов’язковий список дозволених лише для комплектних 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, які оголошують основну змінну середовища (рядок відкритим текстом або об’єкт SecretRef). +- `install.preferBrew`: якщо `true`, надавати перевагу інсталяторам Homebrew, коли доступний `brew`, перш ніж переходити до інших типів інсталяторів. +- `install.nodeManager`: пріоритет інсталятора Node для специфікацій `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). +- `entries..enabled: false` вимикає skill, навіть якщо він комплектний/встановлений. +- `entries..apiKey`: зручне поле для skills, які оголошують основну змінну середовища (рядок відкритого тексту або об’єкт SecretRef). --- @@ -118,48 +116,48 @@ bundled каналів (автентифікація, контроль дост } ``` -- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. -- Виявлення підтримує нативні Plugins OpenClaw, а також сумісні пакунки Codex і Claude, зокрема пакунки Claude зі стандартним розташуванням без manifest. +- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions` і `plugins.load.paths`. +- Виявлення підтримує нативні Plugins OpenClaw, а також сумісні пакети Codex і Claude, зокрема пакети Claude із типовим макетом без manifest. - **Зміни конфігурації потребують перезапуску gateway.** -- `allow`: необов’язковий список дозволених (завантажуються лише вказані Plugins). `deny` має пріоритет. -- `plugins.entries..apiKey`: зручне поле API key на рівні Plugin (коли Plugin це підтримує). -- `plugins.entries..env`: мапа змінних середовища в межах Plugin. -- `plugins.entries..hooks.allowPromptInjection`: якщо `false`, ядро блокує `before_prompt_build` та ігнорує поля, що змінюють prompt, із застарілого `before_agent_start`, водночас зберігаючи застарілі `modelOverride` і `providerOverride`. Застосовується до нативних хуків Plugin і підтримуваних каталогів хуків, що надаються пакунками. -- `plugins.entries..hooks.allowConversationAccess`: якщо `true`, довірені небандловані Plugins можуть читати необроблений вміст розмови з типізованих хуків, таких як `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, якщо вона доступна). +- `allow`: необов’язковий список дозволених (завантажуються лише перелічені Plugins). `deny` має пріоритет. +- `plugins.entries..apiKey`: зручне поле API-ключа на рівні Plugin (коли підтримується Plugin). +- `plugins.entries..env`: карта змінних середовища в межах Plugin. +- `plugins.entries..hooks.allowPromptInjection`: коли `false`, ядро блокує `before_prompt_build` і ігнорує поля, що змінюють prompt, із застарілого `before_agent_start`, зберігаючи при цьому застарілі `modelOverride` і `providerOverride`. Застосовується до нативних хуків Plugin і підтримуваних каталогів хуків, наданих пакетами. +- `plugins.entries..hooks.allowConversationAccess`: коли `true`, довірені некомплектні Plugins можуть читати необроблений вміст розмови з типізованих хуків, таких як `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, якщо доступна). - `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера web-fetch Firecrawl. - - `apiKey`: API key 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`). + - `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`: тайм-аут запиту scrape у секундах (типово: `60`). + - `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). + - `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 * * *"`). - політика фаз і пороги є деталями реалізації (не користувацькими ключами конфігурації). -- Повна конфігурація пам’яті міститься в [Memory configuration reference](/uk/reference/memory-config): +- Повна конфігурація memory міститься в [Memory configuration reference](/uk/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Увімкнені Plugins-пакунки Claude також можуть додавати вбудовані типові значення Pi з `settings.json`; OpenClaw застосовує їх як санітизовані налаштування агента, а не як сирі патчі конфігурації OpenClaw. -- `plugins.slots.memory`: вибір id активного Plugin пам’яті або `"none"` для вимкнення Plugins пам’яті. -- `plugins.slots.contextEngine`: вибір id активного Plugin механізму контексту; типово `"legacy"`, доки ви не встановите й не виберете інший механізм. -- `plugins.installs`: метадані встановлення, керовані CLI та використовувані `openclaw plugins update`. +- Увімкнені Plugins-пакети Claude також можуть надавати вбудовані типові значення Pi із `settings.json`; OpenClaw застосовує їх як санітизовані налаштування агента, а не як необроблені патчі конфігурації OpenClaw. +- `plugins.slots.memory`: вибрати id активного Plugin memory або `"none"` для вимкнення Plugins memory. +- `plugins.slots.contextEngine`: вибрати id активного Plugin рушія контексту; типове значення — `"legacy"`, якщо ви не встановите й не виберете інший рушій. +- `plugins.installs`: метадані інсталяцій, керовані CLI і використовувані `openclaw plugins update`. - Містить `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Сприймайте `plugins.installs.*` як керований стан; віддавайте перевагу командам CLI замість ручного редагування. + - Розглядайте `plugins.installs.*` як керований стан; віддавайте перевагу командам CLI замість ручних змін. Див. [Plugins](/uk/tools/plugin). --- -## Браузер +## Browser ```json5 { @@ -196,29 +194,29 @@ bundled каналів (автентифікація, контроль дост ``` - `evaluateEnabled: false` вимикає `act:evaluate` і `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо значення не задано, тож навігація браузера типово залишається суворо обмеженою. -- Встановлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте браузерній навігації в приватній мережі. -- У суворому режимі віддалені кінцеві точки профілів CDP (`profiles.*.cdpUrl`) підлягають тому самому блокуванню приватної мережі під час перевірок доступності/виявлення. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому навігація browser за замовчуванням залишається суворою. +- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації browser у приватній мережі. +- У суворому режимі віддалені кінцеві точки профілів CDP (`profiles.*.cdpUrl`) підпадають під ті самі обмеження приватної мережі під час перевірок доступності/виявлення. - `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім. - У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків. -- Віддалені профілі працюють лише в режимі attach-only (запуск/зупинка/скидання недоступні). +- Віддалені профілі є лише attach-only (start/stop/reset вимкнено). - `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`. - Використовуйте HTTP(S), якщо хочете, щоб OpenClaw виявив `/json/version`; використовуйте WS(S), - якщо ваш провайдер надає пряму URL-адресу DevTools WebSocket. -- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися - до вибраного хоста або через підключений browser node. -- Профілі `existing-session` можуть задавати `userDataDir`, щоб указати конкретний - профіль браузера на основі Chromium, наприклад Brave або Edge. + Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявив `/json/version`; використовуйте WS(S), + коли ваш провайдер надає прямий URL WebSocket DevTools. +- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися на + вибраному хості або через підключений вузол browser. +- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлюватися на конкретний + профіль браузера на базі Chromium, наприклад Brave або Edge. - Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP: - дії на основі snapshot/ref замість націлювання через CSS-селектори, хуки завантаження одного файла, - без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, а також без + дії на основі snapshot/ref замість націлення за CSS-селектором, хуки завантаження + одного файла, без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, а також без `responsebody`, експорту PDF, перехоплення завантажень чи пакетних дій. -- Для локальних керованих профілів `openclaw` `cdpPort` і `cdpUrl` призначаються автоматично; явно +- Для локально керованих профілів `openclaw` `cdpPort` і `cdpUrl` призначаються автоматично; явно задавайте `cdpUrl` лише для віддаленого CDP. -- Порядок автовиявлення: браузер за замовчуванням, якщо він на основі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. -- Служба керування: лише loopback (порт похідний від `gateway.port`, типово `18791`). +- Порядок автовиявлення: типовий браузер, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- Служба керування: лише loopback (порт виводиться з `gateway.port`, типово `18791`). - `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад, - `--disable-gpu`, розмір вікна або налагоджувальні прапорці). + `--disable-gpu`, розмір вікна або прапорці налагодження). --- @@ -236,8 +234,8 @@ bundled каналів (автентифікація, контроль дост } ``` -- `seamColor`: акцентний колір для chrome нативного інтерфейсу застосунку (відтінок бульбашки режиму Talk тощо). -- `assistant`: перевизначення ідентичності Control UI. Якщо не задано, використовується ідентичність активного агента. +- `seamColor`: акцентний колір для chrome інтерфейсу нативного застосунку (відтінок бульбашки режиму Talk тощо). +- `assistant`: перевизначення ідентичності для Control UI. Якщо не задано, використовується ідентичність активного агента. --- @@ -306,69 +304,68 @@ bundled каналів (автентифікація, контроль дост -- `mode`: `local` (запустити gateway) або `remote` (підключитися до віддаленого gateway). Gateway відмовляється запускатися, якщо не `local`. +- `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` (лише IP Tailscale) або `custom`. -- **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хостів (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Примітка щодо Docker**: типове значення `loopback` для bind слухає `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 потребують gateway auth. На практиці це означає спільний 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; локальні loopback reverse proxy на тому самому хості не задовольняють вимоги trusted-proxy auth. -- `gateway.auth.allowTailscale`: якщо `true`, заголовки ідентичності Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). Кінцеві точки HTTP API **не** використовують цю auth за заголовками Tailscale; вони дотримуються звичайного режиму HTTP auth gateway. Цей потік без token припускає, що хост gateway є довіреним. Типове значення — `true`, коли `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: необов’язковий лімітер невдалих спроб auth. Застосовується для кожного IP клієнта та для кожної області auth окремо (спільний секрет і token пристрою відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`. - - В асинхронному шляху Tailscale Serve для Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом про невдачу. Тому одночасні хибні спроби від одного клієнта можуть спровокувати лімітер уже на другому запиті, замість того щоб обидві пройшли як звичайні невідповідності. - - `gateway.auth.rateLimit.exemptLoopback` типово дорівнює `true`; установіть `false`, якщо свідомо хочете також обмежувати 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`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються browser-клієнти не з loopback-origin. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає fallback 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`: поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують gateway auth. -- `gateway.push.apns.relay.baseUrl`: базова HTTPS URL зовнішнього APNs relay, який використовують офіційні/TestFlight збірки iOS після публікації relay-реєстрацій у gateway. Ця URL має збігатися з URL relay, вбудованою в збірку iOS. +- **Застарілі псевдоніми 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**: типово обов’язкова. Binds не для 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 **не** використовують цю auth заголовками Tailscale; натомість вони дотримуються звичайного режиму HTTP auth gateway. Цей безтокеновий потік передбачає, що хост gateway є довіреним. Типове значення — `true`, коли `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: необов’язкове обмеження невдалих спроб auth. Застосовується на IP клієнта й область auth (спільний секрет і device-token відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`. + - В асинхронному шляху Tailscale Serve для Control UI невдалі спроби для одного й того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому одночасні хибні спроби від одного клієнта можуть спрацювати на обмежувач уже на другому запиті замість того, щоб обидві «проскочили» як звичайні невідповідності. + - `gateway.auth.rateLimit.exemptLoopback` типово дорівнює `true`; встановіть `false`, якщо свідомо хочете, щоб трафік localhost також підпадав під rate limiting (для тестових конфігурацій або суворих proxy-розгортань). +- Спроби auth WS із browser-origin завжди обмежуються без винятку для loopback (додатковий рівень захисту від brute force localhost через браузер). +- На loopback такі блокування browser-origin ізолюються за нормалізованим значенням `Origin`, + тому повторні невдачі з одного localhost origin не блокують автоматично + інший origin. +- `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічно, потребує auth). +- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються браузерні клієнти з origin не-loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає fallback origin за заголовком Host для розгортань, що навмисно покладаються на політику origin за заголовком Host. +- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` `remote.url` має бути `ws://` або `wss://`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське аварійне перевизначення через + змінну середовища процесу, яке дозволяє незашифрований `ws://` до довірених IP + приватної мережі; типовим залишається дозвіл незашифрованого з’єднання лише для loopback. Еквівалента в `openclaw.json` немає, а конфігурація приватної мережі browser, така як + `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, не впливає на Gateway + WebSocket-клієнти. +- `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Вони самі собою не налаштовують auth gateway. +- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL для зовнішнього APNs relay, який використовують офіційні/TestFlight збірки iOS після публікації реєстрацій relay-backed у gateway. Цей URL має збігатися з URL relay, вбудованим у збірку iOS. - `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до relay у мілісекундах. Типове значення: `10000`. -- Реєстрації на основі relay делегуються конкретній ідентичності gateway. Пов’язаний застосунок iOS отримує `gateway.identity.get`, включає цю ідентичність у реєстрацію relay і пересилає gateway право надсилання в межах цієї реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. +- Реєстрації 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 URL relay. У production URL relay мають залишатися на HTTPS. -- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналу в хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски health-monitor. Типове значення: `5`. -- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Тримайте його більшим або рівним `gateway.channelHealthCheckMinutes`. Типове значення: `30`. -- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor на канал/обліковий запис у межах ковзної години. Типове значення: `10`. -- `channels..healthMonitor.enabled`: вимкнення на рівні каналу для перезапусків health-monitor, при цьому глобальний монітор залишається увімкненим. -- `channels..accounts..healthMonitor.enabled`: перевизначення на рівні облікового запису для multi-account каналів. Якщо задано, воно має пріоритет над перевизначенням рівня каналу. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний механізм лише для розробки, який дозволяє loopback HTTP URL relay. 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.*` як fallback лише тоді, коли `gateway.auth.*` не задано. -- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і значення не вдалося розв’язати, розв’язання завершується fail-closed (без маскування через fallback на remote). -- `trustedProxies`: IP reverse proxy, які завершують TLS або додають заголовки пересланого клієнта. Вказуйте лише proxy, які ви контролюєте. Записи loopback і далі допустимі для налаштувань проксі на тому самому хості/локального виявлення (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: якщо `true`, gateway приймає `X-Real-IP`, коли `X-Forwarded-For` відсутній. Типово `false` для поведінки fail-closed. -- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список заборон). -- `gateway.tools.allow`: прибирає назви інструментів із типового списку заборон для HTTP. +- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не розв’язано, розв’язання завершується в закритому режимі (без маскування fallback на remote). +- `trustedProxies`: IP reverse proxy, які завершують TLS або вставляють заголовки forwarded-client. Додавайте лише ті 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.tools.deny`: додаткові назви інструментів, заблокованих для HTTP `POST /tools/invoke` (розширює типовий список deny). +- `gateway.tools.allow`: видаляє назви інструментів із типового списку deny для HTTP. -### Кінцеві точки, сумісні з OpenAI +### OpenAI-compatible endpoints - Chat Completions: типово вимкнено. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: `gateway.http.endpoints.responses.enabled`. -- Посилене захист URL-вводу 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. + Порожні 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)) + - `gateway.http.securityHeaders.strictTransportSecurity` (установлюйте лише для HTTPS-origin, які ви контролюєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) ### Ізоляція кількох екземплярів -Запускайте кілька gateway на одному хості з унікальними портами та каталогами стану: +Запускайте кілька gateway на одному хості з унікальними портами й каталогами стану: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -396,11 +393,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: вмикає завершення TLS на прослуховувачі gateway (HTTPS/WSS) (типово: `false`). -- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, якщо явні файли не налаштовані; лише для локального/dev використання. -- `certPath`: шлях файлової системи до файла TLS certificate. -- `keyPath`: шлях файлової системи до файла приватного TLS key; обмежуйте доступ через дозволи. -- `caPath`: необов’язковий шлях до пакета CA для перевірки клієнтів або користувацьких ланцюжків довіри. +- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типово: `false`). +- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовано; лише для локального/dev використання. +- `certPath`: шлях у файловій системі до файла TLS-сертифіката. +- `keyPath`: шлях у файловій системі до файла приватного TLS-ключа; обмежуйте права доступу. +- `caPath`: необов’язковий шлях до пакета CA для перевірки клієнта або користувацьких ланцюжків довіри. ### `gateway.reload` @@ -417,12 +414,12 @@ openclaw gateway --port 19001 ``` - `mode`: керує тим, як зміни конфігурації застосовуються під час виконання. - - `"off"`: ігнорувати зміни наживо; зміни потребують явного перезапуску. + - `"off"`: ігнорувати зміни в реальному часі; зміни потребують явного перезапуску. - `"restart"`: завжди перезапускати процес gateway при зміні конфігурації. - `"hot"`: застосовувати зміни в процесі без перезапуску. - - `"hybrid"` (типово): спочатку спробувати hot reload; якщо потрібно, перейти до перезапуску. + - `"hybrid"` (типово): спочатку спробувати hot reload; якщо потрібно — перейти до перезапуску. - `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число). -- `deferralTimeoutMs`: максимальний час у мс очікування завершення операцій у процесі перед примусовим перезапуском (типово: `300000` = 5 хвилин). +- `deferralTimeoutMs`: максимальний час у мс очікування на операції в процесі перед примусовим перезапуском (типово: `300000` = 5 хвилин). --- @@ -464,42 +461,42 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. Примітки щодо валідації та безпеки: -- `hooks.enabled=true` вимагає непорожній `hooks.token`. +- `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 не потребують. +- Якщо `hooks.allowRequestSessionKey=true`, обмежте `hooks.allowedSessionKeyPrefixes` (наприклад, `["hook:"]`). +- Якщо mapping або preset використовує шаблонний `sessionKey`, установіть `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не потребують цього явного дозволу. **Кінцеві точки:** - `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`: обмежує явну маршрутизацію (`*` або відсутнє значення = дозволити всі, `[]` = заборонити всі). -- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook-агента без явного `sessionKey`. -- `allowRequestSessionKey`: дозволяє викликачам `/hooks/agent` і session key mapping на основі шаблонів задавати `sessionKey` (типово: `false`). +- `match.path` зіставляє підшлях після `/hooks` (наприклад, `/hooks/gmail` → `gmail`). +- `match.source` зіставляє поле в тілі для загальних шляхів. +- Шаблони на кшталт `{{messages[0].subject}}` читають дані з тіла. +- `transform` може вказувати на модуль JS/TS, який повертає дію hook. + - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи й traversal відхиляються). +- `agentId` маршрутизує до конкретного агента; невідомі ID повертаються до типового значення. +- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити всі, `[]` = заборонити всі). +- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook agent без явного `sessionKey`. +- `allowRequestSessionKey`: дозволити викликам `/hooks/agent` і session key у mapping на основі шаблонів задавати `sessionKey` (типово: `false`). - `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Стає обов’язковим, коли будь-який mapping або preset використовує шаблонний `sessionKey`. -- `deliver: true` надсилає фінальну відповідь у канал; типове значення `channel` — `last`. -- `model` перевизначає LLM для цього запуску hook (має бути дозволена, якщо задано каталог моделей). +- `deliver: true` надсилає фінальну відповідь у канал; `channel` типово дорівнює `last`. +- `model` перевизначає LLM для цього запуску hook (має бути дозволено, якщо задано каталог моделей). ### Інтеграція Gmail - Вбудований preset Gmail використовує `sessionKey: "hook:gmail:{{messages[0].id}}"`. -- Якщо ви зберігаєте таку маршрутизацію для кожного повідомлення, задайте `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes` так, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. -- Якщо вам потрібне `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість шаблонного типового значення. +- Якщо ви зберігаєте таку маршрутизацію за окремими повідомленнями, установіть `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes` так, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. +- Якщо вам потрібне `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість типового шаблонного. ```json5 { @@ -522,12 +519,12 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- 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. --- -## Canvas host +## Хост Canvas ```json5 { @@ -539,16 +536,16 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Обслуговує 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 оголошує URL-адреси можливостей у межах node для доступу до canvas/A2UI. -- URL-адреси можливостей прив’язані до активної WS-сесії node і швидко спливають. Fallback на основі IP не використовується. -- Вбудовує клієнт live-reload у HTML, що віддається. -- Автоматично створює стартовий `index.html`, якщо каталог порожній. -- Також віддає A2UI за адресою `/__openclaw__/a2ui/`. +- Лише локально: зберігайте `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 і швидко спливають. Fallback на основі IP не використовується. +- Впроваджує клієнт live reload у відданий HTML. +- Автоматично створює початковий `index.html`, якщо каталог порожній. +- Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`. - Зміни потребують перезапуску gateway. - Вимкніть live reload для великих каталогів або при помилках `EMFILE`. @@ -568,9 +565,9 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `minimal` (типово): не включає `cliPath` + `sshPort` у записи TXT. -- `full`: включає `cliPath` + `sshPort`. -- Ім’я хоста типово `openclaw`. Для перевизначення використовуйте `OPENCLAW_MDNS_HOSTNAME`. +- `minimal` (типово): не включати `cliPath` + `sshPort` до записів TXT. +- `full`: включати `cliPath` + `sshPort`. +- Типове ім’я хоста — `openclaw`. Для перевизначення використовуйте `OPENCLAW_MDNS_HOSTNAME`. ### Wide-area (DNS-SD) @@ -582,7 +579,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + split DNS у Tailscale. +Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + split DNS Tailscale. Налаштування: `openclaw dns setup --apply`. @@ -607,12 +604,12 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Вбудовані змінні середовища застосовуються лише тоді, коли в середовищі процесу відсутній ключ. -- Файли `.env`: `.env` у CWD + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). +- Вбудовані змінні середовища застосовуються лише тоді, коли в середовищі процесу немає цього ключа. +- Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). - `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell. -- Повний порядок пріоритету див. у [Environment](/uk/help/environment). +- Повний порядок пріоритетів див. у [Environment](/uk/help/environment). -### Підстановка змінних середовища +### Підстановка env var Посилайтеся на змінні середовища в будь-якому рядку конфігурації через `${VAR_NAME}`: @@ -624,9 +621,9 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. +- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. - Відсутні/порожні змінні викликають помилку під час завантаження конфігурації. -- Екрануйте через `$${VAR}`, щоб отримати буквальний `${VAR}`. +- Екрануйте як `$${VAR}` для буквального `${VAR}`. - Працює з `$include`. --- @@ -637,7 +634,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ### `SecretRef` -Використовуйте одну таку форму об’єкта: +Використовуйте одну з форм об’єкта: ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -647,15 +644,15 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - шаблон `provider`: `^[a-z][a-z0-9_-]{0,63}$` - шаблон `id` для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` `id`: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`) +- `source: "file"` id: абсолютний JSON pointer (наприклад, `"/providers/openai/apiKey"`) - шаблон `id` для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `id` для `source: "exec"` не повинні містити сегменти шляху `.` або `..`, розділені `/` (наприклад, `a/../b` відхиляється) +- `source: "exec"` id не повинен містити сегментів шляху `.` або `..`, розділених слешами (наприклад, `a/../b` відхиляється) ### Підтримувана поверхня облікових даних - Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface) - `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`. -- Посилання в `auth-profiles.json` входять до runtime-розв’язання та покриття аудиту. +- Посилання в `auth-profiles.json` включаються до розв’язання під час виконання й покриття аудиту. ### Конфігурація провайдерів секретів @@ -687,18 +684,18 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. Примітки: -- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue значення `id` має бути `"value"`). -- Шляхи провайдерів file і exec переходять у fail closed, коли перевірка Windows ACL недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. -- Провайдер `exec` вимагає абсолютний шлях у `command` і використовує корисні навантаження протоколу через stdin/stdout. -- Типово шляхи команд-симлінків відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-симлінки, водночас перевіряючи розв’язаний цільовий шлях. +- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue `id` має бути `"value"`). +- Шляхи провайдерів file і exec завершуються в закритому режимі, якщо перевірка Windows ACL недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. +- Провайдер `exec` потребує абсолютного шляху `command` і використовує корисні навантаження протоколу через stdin/stdout. +- Типово символьні шляхи command відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити symlink-шляхи з перевіркою розв’язаного цільового шляху. - Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до розв’язаного цільового шляху. -- Дочірнє середовище `exec` типово мінімальне; передавайте потрібні змінні явно через `passEnv`. -- Посилання на секрети розв’язуються під час активації в snapshot у пам’яті, а потім шляхи запитів читають лише цей snapshot. -- Під час активації застосовується фільтрація активної поверхні: нерозв’язані посилання на увімкнених поверхнях призводять до помилки запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. +- Середовище дочірнього процесу `exec` типово мінімальне; передавайте потрібні змінні явно через `passEnv`. +- Посилання на секрети розв’язуються під час активації в знімок у пам’яті, після чого шляхи запитів читають лише цей знімок. +- Фільтрація активної поверхні застосовується під час активації: нерозв’язані посилання на ввімкнених поверхнях призводять до помилки запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. --- -## Сховище auth +## Сховище Auth ```json5 { @@ -716,13 +713,13 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Профілі для кожного агента зберігаються в `/auth-profiles.json`. +- Профілі для окремих агентів зберігаються в `/auth-profiles.json`. - `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних. -- Профілі режиму OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілю auth на основі SecretRef. -- Статичні runtime-облікові дані надходять із розв’язаних snapshot у пам’яті; застарілі статичні записи `auth.json` очищаються при виявленні. -- Застарілий імпорт OAuth виконується з `~/.openclaw/credentials/oauth.json`. +- Профілі режиму OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілів auth на основі SecretRef. +- Статичні облікові дані під час виконання надходять із розв’язаних знімків у пам’яті; застарілі статичні записи `auth.json` очищаються під час виявлення. +- Застарілі імпорти OAuth із `~/.openclaw/credentials/oauth.json`. - Див. [OAuth](/uk/concepts/oauth). -- Runtime-поведінка секретів і інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). +- Поведінка Secrets під час виконання та інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). ### `auth.cooldowns` @@ -744,21 +741,21 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `billingBackoffHours`: базовий backoff у годинах, коли профіль завершується помилкою через справжні - billing/insufficient-credit помилки (типово: `5`). Явний текст про billing - усе ще може потрапити сюди навіть для відповідей `401`/`403`, але - зіставлювачі тексту, специфічні для провайдера, залишаються обмеженими тим - провайдером, якому вони належать (наприклад, OpenRouter - `Key limit exceeded`). Повторювані HTTP `402` повідомлення usage-window або - organization/workspace spend-limit натомість залишаються в шляху `rate_limit`. -- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин billing backoff для кожного провайдера. -- `billingMaxHours`: верхня межа в годинах для експоненційного зростання billing backoff (типово: `24`). -- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для збоїв `auth_permanent` з високою впевненістю (типово: `10`). +- `billingBackoffHours`: базовий backoff у годинах, коли профіль завершується помилкою через справжні помилки білінгу/нестачі кредитів (типово: `5`). Явний текст про білінг + усе ще може потрапити сюди навіть у відповідях `401`/`403`, але + текстові зіставлення, специфічні для провайдера, + залишаються обмеженими провайдером, якому вони належать (наприклад OpenRouter + `Key limit exceeded`). Повторювані повідомлення `402` про вікно використання або + ліміти витрат організації/робочого простору + натомість залишаються в гілці `rate_limit`. +- `billingBackoffHoursByProvider`: необов’язкові перевизначення backoff білінгу в годинах для окремих провайдерів. +- `billingMaxHours`: верхня межа в годинах для експоненційного зростання backoff білінгу (типово: `24`). +- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для збоїв `auth_permanent` із високою впевненістю (типово: `10`). - `authPermanentMaxMinutes`: верхня межа в хвилинах для зростання backoff `auth_permanent` (типово: `60`). -- `failureWindowHours`: ковзне вікно в годинах, що використовується для лічильників backoff (типово: `24`). -- `overloadedProfileRotations`: максимальна кількість ротацій auth-профілю в межах того самого провайдера для помилок перевантаження перед переходом до fallback моделі (типово: `1`). Сюди потрапляють форми provider-busy, такі як `ModelNotReadyException`. +- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників backoff (типово: `24`). +- `overloadedProfileRotations`: максимальна кількість ротацій auth-профілю в межах одного провайдера для помилок перевантаження перед переходом до fallback моделі (типово: `1`). Сюди потрапляють форми «провайдер зайнятий», як-от `ModelNotReadyException`. - `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`). -- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-профілю в межах того самого провайдера для помилок rate-limit перед переходом до fallback моделі (типово: `1`). До цього сегмента rate-limit входить текст у стилі провайдера, такий як `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. +- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-профілю в межах одного провайдера для помилок обмеження швидкості перед переходом до fallback моделі (типово: `1`). До цього кошика rate-limit входить текст у стилі провайдерів, як-от `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. --- @@ -778,9 +775,9 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. -- Задайте `logging.file` для стабільного шляху. -- `consoleLevel` підвищується до `debug` з `--verbose`. -- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого запис припиняється (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів. +- Установіть `logging.file` для стабільного шляху. +- `consoleLevel` підвищується до `debug` із `--verbose`. +- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого записування пригнічується (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів. --- @@ -804,6 +801,14 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. logs: false, sampleRate: 1.0, flushIntervalMs: 5000, + captureContent: { + enabled: false, + inputMessages: false, + outputMessages: false, + toolInputs: false, + toolOutputs: false, + systemPrompt: false, + }, }, cacheTrace: { @@ -818,19 +823,20 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - `enabled`: головний перемикач для виводу інструментування (типово: `true`). -- `flags`: масив рядків-прапорців, що вмикають цільовий вивід журналу (підтримує шаблони з підстановками, як-от `"telegram.*"` або `"*"`). -- `stuckSessionWarnMs`: поріг віку в мс для виводу попереджень про завислу сесію, поки сесія залишається в стані обробки. +- `flags`: масив рядків прапорців, що вмикають цільовий вивід у журнали (підтримує шаблони з wildcard, як-от `"telegram.*"` або `"*"`). +- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислі сесії, поки сесія залишається в стані обробки. - `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). - `otel.endpoint`: URL колектора для експорту OTel. - `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`. -- `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, які надсилаються із запитами експорту OTel. -- `otel.serviceName`: назва сервісу для атрибутів ресурсу. +- `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються із запитами експорту OTel. +- `otel.serviceName`: ім’я сервісу для атрибутів ресурсу. - `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт trace, metrics або logs. - `otel.sampleRate`: частота вибірки trace `0`–`1`. -- `otel.flushIntervalMs`: інтервал періодичного скидання telemetry у мс. -- `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.flushIntervalMs`: інтервал періодичного скидання телеметрії в мс. +- `otel.captureContent`: явний дозвіл на захоплення необробленого вмісту для атрибутів span OTEL. Типово вимкнено. Булеве `true` захоплює вміст повідомлень/інструментів, крім system; форма об’єкта дає змогу явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`. +- `cacheTrace.enabled`: журналювати знімки трасування кешу для вбудованих запусків (типово: `false`). +- `cacheTrace.filePath`: шлях виводу для JSONL трасування кешу (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається до виводу трасування кешу (усі типово: `true`). --- @@ -852,12 +858,12 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `channel`: канал випусків для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`. +- `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`). +- `auto.enabled`: увімкнути фонове автооновлення для package-встановлень (типово: `false`). +- `auto.stableDelayHours`: мінімальна затримка в годинах перед автозастосуванням на каналі stable (типово: `6`; макс.: `168`). +- `auto.stableJitterHours`: додаткове вікно розподілу розгортання для каналу stable в годинах (типово: `12`; макс.: `168`). +- `auto.betaCheckIntervalHours`: як часто виконуються перевірки каналу beta в годинах (типово: `1`; макс.: `24`). --- @@ -890,22 +896,22 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `enabled`: глобальний feature gate для ACP (типово: `false`). -- `dispatch.enabled`: окремий gate для диспетчеризації ходів ACP-сесії (типово: `true`). Установіть `false`, щоб команди ACP залишалися доступними, але виконання блокувалося. -- `backend`: id типового runtime backend ACP (має відповідати зареєстрованому runtime Plugin ACP). -- `defaultAgent`: id цільового агента ACP за замовчуванням, коли spawn не задає явної цілі. -- `allowedAgents`: список дозволених id агентів для runtime-сесій ACP; порожнє значення означає відсутність додаткового обмеження. -- `maxConcurrentSessions`: максимальна кількість одночасно активних ACP-сесій. +- `enabled`: глобальний feature gate ACP (типово: `false`). +- `dispatch.enabled`: незалежний gate для диспетчеризації ходів сесії ACP (типово: `true`). Установіть `false`, щоб команди ACP залишалися доступними, але виконання блокувалося. +- `backend`: id типового runtime-backend ACP (має збігатися із зареєстрованим runtime Plugin ACP). +- `defaultAgent`: fallback id цільового агента ACP, коли spawn не задає явну ціль. +- `allowedAgents`: список дозволених id агентів для runtime-сесій ACP; порожнє значення означає відсутність додаткових обмежень. +- `maxConcurrentSessions`: максимальна кількість одночасно активних сесій ACP. - `stream.coalesceIdleMs`: вікно idle flush у мс для потокового тексту. - `stream.maxChunkChars`: максимальний розмір фрагмента перед розбиттям проєкції потокового блока. -- `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструмента за хід (типово: `true`). -- `stream.deliveryMode`: `"live"` передає поступово; `"final_only"` буферизує до термінальних подій ходу. -- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструмента (типово: `"paragraph"`). -- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, що проєктується за хід ACP. -- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлення ACP. -- `stream.tagVisibility`: запис відповідності назв тегів логічним перевизначенням видимості для потокових подій. -- `runtime.ttlMinutes`: idle TTL у хвилинах для воркерів ACP-сесій до моменту, коли вони можуть бути очищені. -- `runtime.installCommand`: необов’язкова команда встановлення, яку слід виконати під час bootstrap середовища runtime ACP. +- `stream.repeatSuppression`: пригнічувати повторювані рядки стану/інструментів на хід (типово: `true`). +- `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до термінальних подій ходу. +- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (типово: `"paragraph"`). +- `stream.maxOutputChars`: максимальна кількість символів виводу помічника, що проєктується за один хід ACP. +- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлень ACP. +- `stream.tagVisibility`: запис назв тегів у булеві перевизначення видимості для потокових подій. +- `runtime.ttlMinutes`: idle TTL у хвилинах для воркерів сесії ACP до моменту, коли вони можуть бути очищені. +- `runtime.installCommand`: необов’язкова команда встановлення, яку слід запускати під час bootstrap середовища runtime ACP. --- @@ -922,10 +928,10 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - `cli.banner.taglineMode` керує стилем слогана банера: - - `"random"` (типово): змінні кумедні/сезонні слогани. + - `"random"` (типово): ротація кумедних/сезонних слоганів. - `"default"`: фіксований нейтральний слоган (`All your chats, one OpenClaw.`). - - `"off"`: без тексту слогана (назва/версія банера все одно показуються). -- Щоб приховати весь банер (а не лише слогани), задайте змінну середовища `OPENCLAW_HIDE_BANNER=1`. + - `"off"`: без тексту слогана (заголовок/версія банера все одно показуються). +- Щоб приховати весь банер (а не лише слогани), установіть env `OPENCLAW_HIDE_BANNER=1`. --- @@ -947,15 +953,15 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. --- -## Ідентичність +## Identity -Див. поля ідентичності `agents.list` у розділі [Agent defaults](/uk/gateway/config-agents#agent-defaults). +Див. поля identity у `agents.list` в розділі [Agent defaults](/uk/gateway/config-agents#agent-defaults). --- -## Bridge (застарілий, вилучений) +## Bridge (застарілий, видалено) -Поточні збірки більше не містять TCP bridge. Nodes підключаються через Gateway WebSocket. Ключі `bridge.*` більше не входять до схеми конфігурації (валідація завершиться помилкою, доки їх не буде вилучено; `openclaw doctor --fix` може прибрати невідомі ключі). +Поточні збірки більше не містять TCP bridge. Nodes підключаються через Gateway WebSocket. Ключі `bridge.*` більше не входять до схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). @@ -995,11 +1001,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `sessionRetention`: як довго зберігати завершені ізольовані сесії виконання Cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів Cron. Типове значення: `24h`; установіть `false`, щоб вимкнути. -- `runLog.maxBytes`: максимальний розмір файла журналу одного запуску (`cron/runs/.jsonl`) до очищення. Типове значення: `2_000_000` байтів. -- `runLog.keepLines`: кількість найновіших рядків, що зберігаються, коли запускається очищення журналу виконання. Типове значення: `2000`. -- `webhookToken`: bearer token, що використовується для доставки POST до webhook у Cron (`delivery.mode = "webhook"`); якщо не задано, заголовок auth не надсилається. -- `webhook`: застаріла резервна URL webhook (http/https), яка використовується лише для збережених завдань, що все ще мають `notify: true`. +- `sessionRetention`: як довго зберігати завершені ізольовані сесії запуску Cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів Cron. Типово: `24h`; установіть `false`, щоб вимкнути. +- `runLog.maxBytes`: максимальний розмір одного файла журналу запуску (`cron/runs/.jsonl`) перед очищенням. Типово: `2_000_000` байтів. +- `runLog.keepLines`: кількість найновіших рядків, що зберігаються, коли спрацьовує очищення журналу запуску. Типово: `2000`. +- `webhookToken`: bearer-токен, який використовується для доставлення POST до Cron Webhook (`delivery.mode = "webhook"`); якщо не задано, заголовок auth не надсилається. +- `webhook`: застарілий fallback URL Webhook (http/https), який використовується лише для збережених завдань, у яких усе ще є `notify: true`. ### `cron.retry` @@ -1015,11 +1021,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань при тимчасових помилках (типово: `3`; діапазон: `0`–`10`). -- `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів). -- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Не задавайте, щоб повторювати всі тимчасові типи. +- `maxAttempts`: максимальна кількість повторів для одноразових завдань за тимчасових помилок (типово: `3`; діапазон: `0`–`10`). +- `backoffMs`: масив затримок backoff у мс для кожної спроби повтору (типово: `[30000, 60000, 300000]`; 1–10 записів). +- `retryOn`: типи помилок, які запускають повтор — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати для всіх тимчасових типів. -Застосовується лише до одноразових завдань Cron. Для повторюваних завдань використовується окрема обробка збоїв. +Застосовується лише до одноразових завдань Cron. Для періодичних завдань використовується окрема обробка збоїв. ### `cron.failureAlert` @@ -1039,9 +1045,9 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - `enabled`: увімкнути сповіщення про збої для завдань Cron (типово: `false`). - `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мін.: `1`). -- `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число). -- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` виконує POST на налаштований webhook. -- `accountId`: необов’язковий id облікового запису або каналу для обмеження доставки сповіщення. +- `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для одного завдання (невід’ємне ціле число). +- `mode`: режим доставлення — `"announce"` надсилає через повідомлення каналу; `"webhook"` виконує POST на налаштований Webhook. +- `accountId`: необов’язковий id облікового запису або каналу для обмеження доставлення сповіщень. ### `cron.failureDestination` @@ -1058,43 +1064,43 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Типове місце призначення для сповіщень про збої Cron для всіх завдань. -- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо даних цілі. -- `channel`: перевизначення каналу для доставки announce. `"last"` повторно використовує останній відомий канал доставки. -- `to`: явна ціль announce або URL webhook. Обов’язкове для режиму webhook. -- `accountId`: необов’язкове перевизначення облікового запису для доставки. +- Типове призначення для сповіщень про збої Cron для всіх завдань. +- `mode`: `"announce"` або `"webhook"`; типове значення — `"announce"`, коли є достатньо даних цілі. +- `channel`: перевизначення каналу для доставлення announce. `"last"` повторно використовує останній відомий канал доставлення. +- `to`: явна ціль announce або URL Webhook. Обов’язково для режиму webhook. +- `accountId`: необов’язкове перевизначення облікового запису для доставлення. - `delivery.failureDestination` на рівні завдання перевизначає це глобальне типове значення. -- Коли не задано ні глобального, ні рівня завдання місця призначення для збоїв, завдання, які вже доставляють через `announce`, у разі збою повертаються до цієї основної цілі announce. -- `delivery.failureDestination` підтримується лише для завдань із `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` завдання не дорівнює `"webhook"`. +- Якщо не задано ні глобальне, ні на рівні завдання призначення збоїв, завдання, які вже доставляють через `announce`, у разі збою повертаються до цієї основної цілі announce. +- `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` завдання не дорівнює `"webhook"`. Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання Cron відстежуються як [background tasks](/uk/automation/tasks). --- -## Змінні шаблону моделі медіа +## Змінні шаблону моделі media -Заповнювачі шаблонів, що розгортаються в `tools.media.models[].args`: +Заповнювачі шаблону, що розгортаються в `tools.media.models[].args`: | Variable | Description | | ------------------ | ------------------------------------------------- | | `{{Body}}` | Повний текст вхідного повідомлення | -| `{{RawBody}}` | Необроблений текст (без обгорток історії/відправника) | -| `{{BodyStripped}}` | Текст без згадувань групи | +| `{{RawBody}}` | Сирий текст (без обгорток history/sender) | +| `{{BodyStripped}}` | Текст без згадок групи | | `{{From}}` | Ідентифікатор відправника | | `{{To}}` | Ідентифікатор призначення | | `{{MessageSid}}` | id повідомлення каналу | | `{{SessionId}}` | UUID поточної сесії | | `{{IsNewSession}}` | `"true"`, коли створено нову сесію | -| `{{MediaUrl}}` | Псевдо-URL вхідного медіа | -| `{{MediaPath}}` | Локальний шлях до медіа | -| `{{MediaType}}` | Тип медіа (image/audio/document/…) | +| `{{MediaUrl}}` | Псевдо-URL вхідного media | +| `{{MediaPath}}` | Локальний шлях до media | +| `{{MediaType}}` | Тип media (image/audio/document/…) | | `{{Transcript}}` | Транскрипт аудіо | -| `{{Prompt}}` | Розв’язаний prompt медіа для записів CLI | -| `{{MaxChars}}` | Розв’язаний максимум символів виводу для записів CLI | +| `{{Prompt}}` | Розв’язаний prompt media для записів CLI | +| `{{MaxChars}}` | Розв’язана макс. кількість символів виводу для записів CLI | | `{{ChatType}}` | `"direct"` або `"group"` | | `{{GroupSubject}}` | Тема групи (best effort) | -| `{{GroupMembers}}` | Попередній список учасників групи (best effort) | -| `{{SenderName}}` | Відображуване ім’я відправника (best effort) | +| `{{GroupMembers}}` | Попередній перегляд учасників групи (best effort) | +| `{{SenderName}}` | Ім’я відображення відправника (best effort) | | `{{SenderE164}}` | Номер телефону відправника (best effort) | | `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) | @@ -1117,14 +1123,14 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. **Поведінка злиття:** -- Один файл: замінює об’єкт-контейнер. -- Масив файлів: глибоко зливається за порядком (пізніші перевизначають ранніші). +- Один файл: замінює об’єкт, що його містить. +- Масив файлів: глибоко зливається за порядком (пізніші перевизначають попередні). - Сусідні ключі: зливаються після 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. +- Шляхи: розв’язуються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли вони все одно розв’язуються в межах цього кордону. +- Записи, які виконує OpenClaw і які змінюють лише один розділ верхнього рівня, підкріплений include одного файла, записуються безпосередньо в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін. +- Кореневі include, масиви include та include із сусідніми перевизначеннями є лише для читання для записів, які виконує OpenClaw; такі записи завершуються в закритому режимі замість сплощення конфігурації. +- Помилки: зрозумілі повідомлення для відсутніх файлів, помилок парсингу та циклічних include. --- diff --git a/docs/uk/logging.md b/docs/uk/logging.md index 4cb45d6a2..274042637 100644 --- a/docs/uk/logging.md +++ b/docs/uk/logging.md @@ -1,38 +1,37 @@ --- read_when: - - Вам потрібен дружній до початківців огляд логування - - Ви хочете налаштувати рівні або формати логування - - Ви усуваєте несправності й хочете швидко знайти логи -summary: 'Огляд логування: файлові логи, вивід у консоль, tail у CLI та Control UI' -title: Огляд логування + - Вам потрібен дружній до початківців огляд журналювання + - Ви хочете налаштувати рівні журналювання або формати + - Ви усуваєте несправності й хочете швидко знайти журнали +summary: 'Огляд журналювання: журнали у файлах, вивід у консолі, відстеження в CLI та інтерфейс керування' +title: Огляд журналювання x-i18n: - generated_at: "2026-04-23T20:58:21Z" + generated_at: "2026-04-24T23:44:42Z" model: gpt-5.4 provider: openai - source_hash: 9b6f274600bcb9f5597c91aa6c30512871105a3e0de446773394abbe27276058 + source_hash: 8e179c883d98caa7fd8d3ece8962d0b628562d35568ebf452c34bededba22e2c source_path: logging.md workflow: 15 --- -# Логування +# Журналювання -OpenClaw має дві основні поверхні логування: +OpenClaw має дві основні поверхні журналювання: -- **Файлові логи** (рядки JSON), які записує Gateway. -- **Вивід у консоль**, що показується в terminal і Gateway Debug UI. +- **Журнали у файлах** (рядки JSON), які записує Gateway. +- **Вивід у консолі**, що показується в терміналах і в інтерфейсі налагодження Gateway. -Вкладка **Logs** у Control UI виконує tail файлового логу gateway. На цій сторінці пояснюється, де -зберігаються логи, як їх читати та як налаштовувати рівні й формати логування. +Вкладка **Logs** в інтерфейсі керування відстежує журнал файлу gateway. На цій сторінці пояснюється, де зберігаються журнали, як їх читати та як налаштовувати рівні й формати журналювання. -## Де зберігаються логи +## Де зберігаються журнали -Типово Gateway записує rolling log file у: +За замовчуванням Gateway записує ротаційний файл журналу за шляхом: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` Дата використовує локальний часовий пояс хоста gateway. -Це можна перевизначити в `~/.openclaw/openclaw.json`: +Ви можете змінити це в `~/.openclaw/openclaw.json`: ```json { @@ -42,11 +41,11 @@ OpenClaw має дві основні поверхні логування: } ``` -## Як читати логи +## Як читати журнали -### CLI: live tail (рекомендовано) +### CLI: відстеження в реальному часі (рекомендовано) -Використовуйте CLI, щоб виконувати tail файлового логу gateway через RPC: +Використовуйте CLI, щоб відстежувати файл журналу gateway через RPC: ```bash openclaw logs --follow @@ -54,76 +53,71 @@ openclaw logs --follow Корисні поточні параметри: -- `--local-time`: відображати часові позначки у вашому локальному часовому поясі -- `--url ` / `--token ` / `--timeout `: стандартні прапорці RPC Gateway -- `--expect-final`: прапорець очікування остаточної відповіді для agent-backed RPC (тут приймається через спільний client layer) +- `--local-time`: відображати часові мітки у вашому локальному часовому поясі +- `--url ` / `--token ` / `--timeout `: стандартні прапорці Gateway RPC +- `--expect-final`: прапорець очікування фінальної відповіді для RPC на основі агентів (тут приймається через спільний клієнтський шар) Режими виводу: -- **TTY-сесії**: красиві, кольорові, структуровані рядки логів. -- **Не-TTY сесії**: plain text. -- `--json`: JSON із розділенням по рядках (одна подія логу на рядок). -- `--plain`: примусово plain text у TTY-сесіях. -- `--no-color`: вимкнути ANSI-кольори. +- **Сеанси TTY**: гарні, кольорові, структуровані рядки журналу. +- **Сеанси без TTY**: звичайний текст. +- `--json`: JSON з розділенням по рядках (одна подія журналу на рядок). +- `--plain`: примусово використовувати звичайний текст у сеансах TTY. +- `--no-color`: вимкнути кольори ANSI. -Коли ви передаєте явний `--url`, CLI не застосовує автоматично credentials із конфігурації або -змінних середовища; якщо цільовий Gateway -вимагає auth, самі передайте `--token`. +Коли ви передаєте явний `--url`, CLI не застосовує автоматично облікові дані з конфігурації або середовища; вкажіть `--token` самостійно, якщо цільовий Gateway вимагає автентифікації. У режимі JSON CLI виводить об’єкти з тегом `type`: -- `meta`: метадані потоку (file, cursor, size) -- `log`: розібраний запис логу -- `notice`: підказки про truncation / rotation -- `raw`: нерозібраний рядок логу +- `meta`: метадані потоку (файл, курсор, розмір) +- `log`: розібраний запис журналу +- `notice`: підказки щодо обрізання / ротації +- `raw`: нерозібраний рядок журналу -Якщо локальний loopback Gateway просить pairing, `openclaw logs` автоматично переходить до -налаштованого локального log file. Для явних цілей `--url` цей fallback не -використовується. +Якщо Gateway на local loopback просить виконати pairing, `openclaw logs` автоматично переходить до налаштованого локального файла журналу. Явні цілі `--url` не використовують цей резервний варіант. -Якщо Gateway недоступний, CLI показує коротку підказку виконати: +Якщо Gateway недоступний, CLI виводить коротку підказку виконати: ```bash openclaw doctor ``` -### Control UI (web) +### Інтерфейс керування (веб) -Вкладка **Logs** у Control UI виконує tail того самого файлу через `logs.tail`. -Як її відкрити, див. у [/web/control-ui](/uk/web/control-ui). +Вкладка **Logs** в інтерфейсі керування відстежує той самий файл за допомогою `logs.tail`. +Див. [/web/control-ui](/uk/web/control-ui), щоб дізнатися, як його відкрити. -### Логи лише каналів +### Журнали лише каналів -Щоб фільтрувати активність каналу (WhatsApp/Telegram тощо), використовуйте: +Щоб відфільтрувати активність каналів (WhatsApp/Telegram/etc), використовуйте: ```bash openclaw channels logs --channel whatsapp ``` -## Формати логів +## Формати журналів -### Файлові логи (JSONL) +### Журнали у файлах (JSONL) -Кожен рядок у log file — це JSON-об’єкт. CLI і Control UI розбирають ці -записи, щоб відображати структурований вивід (час, рівень, підсистема, повідомлення). +Кожен рядок у файлі журналу є об’єктом JSON. CLI та інтерфейс керування розбирають ці записи, щоб відображати структурований вивід (час, рівень, підсистема, повідомлення). -### Вивід у консоль +### Вивід у консолі -Логи консолі **враховують TTY** і форматуються для зручності читання: +Журнали консолі **враховують TTY** і форматуються для зручності читання: -- Префікси підсистем (наприклад `gateway/channels/whatsapp`) +- Префікси підсистем (наприклад, `gateway/channels/whatsapp`) - Кольори рівнів (info/warn/error) -- Необов’язковий compact або JSON mode +- Необов’язковий компактний або JSON-режим Форматування консолі керується через `logging.consoleStyle`. -### Логи Gateway WebSocket +### Журнали Gateway WebSocket -`openclaw gateway` також має логування протоколу WebSocket для RPC-трафіку: +`openclaw gateway` також має журналювання протоколу WebSocket для RPC-трафіку: - звичайний режим: лише цікаві результати (помилки, помилки розбору, повільні виклики) -- `--verbose`: увесь request/response-трафік -- `--ws-log auto|compact|full`: вибір стилю відображення в verbose-режимі +- `--verbose`: увесь трафік запитів/відповідей +- `--ws-log auto|compact|full`: вибір стилю детального відображення - `--compact`: псевдонім для `--ws-log compact` Приклади: @@ -134,9 +128,9 @@ openclaw gateway --verbose --ws-log compact openclaw gateway --verbose --ws-log full ``` -## Налаштування логування +## Налаштування журналювання -Уся конфігурація логування знаходиться в розділі `logging` у `~/.openclaw/openclaw.json`. +Усі параметри журналювання містяться в `logging` у `~/.openclaw/openclaw.json`. ```json { @@ -151,80 +145,80 @@ openclaw gateway --verbose --ws-log full } ``` -### Рівні логування +### Рівні журналювання -- `logging.level`: рівень **файлових логів** (JSONL). +- `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 на кожен рядок (для log processor-ів). +- `pretty`: зручний для людини, кольоровий, із часовими мітками. +- `compact`: щільніший вивід (найкраще для довгих сеансів). +- `json`: JSON у кожному рядку (для обробників журналів). -### Редагування +### Редагування чутливих даних -Зведення інструментів можуть редагувати чутливі токени до потрапляння в консоль: +Підсумки інструментів можуть приховувати чутливі токени до того, як вони потраплять у консоль: - `logging.redactSensitive`: `off` | `tools` (типово: `tools`) - `logging.redactPatterns`: список рядків regex для перевизначення типового набору -Редагування впливає **лише на вивід у консоль** і не змінює файлові логи. +Редагування впливає **лише на вивід у консоль** і не змінює журнали у файлах. -## Diagnostics + OpenTelemetry +## Діагностика + OpenTelemetry -Diagnostics — це структуровані, машиночитані події для запусків моделей **і** -телеметрії потоку повідомлень (webhooks, черги, стан сесії). Вони **не** -замінюють логи; вони існують, щоб живити метрики, traces та інші exporter-и. +Діагностика — це структуровані, машинозчитувані події для запусків моделей **і** +телеметрії потоку повідомлень (webhooks, постановка в чергу, стан сеансу). Вони **не** +замінюють журнали; вони існують для передавання метрик, трасувань та інших експортерів. -Події diagnostics генеруються в процесі, але exporter-и під’єднуються лише тоді, коли -увімкнено diagnostics + Plugin exporter-а. +Події діагностики генеруються в процесі, але експортери підключаються лише тоді, коли +увімкнено діагностику + Plugin експортера. ### OpenTelemetry проти OTLP -- **OpenTelemetry (OTel)**: модель даних + SDK для traces, metrics і logs. -- **OTLP**: wire protocol, який використовується для експорту даних OTel у collector/backend. -- OpenClaw сьогодні експортує через **OTLP/HTTP (protobuf)**. +- **OpenTelemetry (OTel)**: модель даних + SDK для трасувань, метрик і журналів. +- **OTLP**: мережевий протокол, який використовується для експорту даних OTel до колектора/бекенда. +- Сьогодні OpenClaw експортує через **OTLP/HTTP (protobuf)**. -### Сигнали, що експортуються +### Експортовані сигнали -- **Metrics**: counters + histograms (використання токенів, потік повідомлень, постановка в чергу). -- **Traces**: spans для використання моделей + обробки webhook/message. -- **Logs**: експортуються через OTLP, коли увімкнено `diagnostics.otel.logs`. Обсяг логів може бути високим; зважайте на `logging.level` і фільтри exporter-а. +- **Метрики**: лічильники + гістограми (використання токенів, потік повідомлень, постановка в чергу). +- **Трасування**: span-и для використання моделей + обробки webhook/повідомлень. +- **Журнали**: експортуються через OTLP, коли ввімкнено `diagnostics.otel.logs`. Обсяг журналів + може бути високим; враховуйте `logging.level` і фільтри експортера. -### Каталог подій diagnostics +### Каталог подій діагностики Використання моделей: -- `model.usage`: токени, вартість, тривалість, контекст, provider/model/channel, id сесій. +- `model.usage`: токени, вартість, тривалість, контекст, провайдер/модель/канал, ідентифікатори сеансів. Потік повідомлень: - `webhook.received`: вхід webhook для кожного каналу. -- `webhook.processed`: оброблено webhook + тривалість. +- `webhook.processed`: webhook оброблено + тривалість. - `webhook.error`: помилки обробника webhook. - `message.queued`: повідомлення поставлено в чергу на обробку. - `message.processed`: результат + тривалість + необов’язкова помилка. -Черга + сесія: +Черга + сеанс: -- `queue.lane.enqueue`: постановка в чергу в lane команд + глибина. -- `queue.lane.dequeue`: зняття з черги з lane команд + час очікування. -- `session.state`: перехід стану сесії + причина. -- `session.stuck`: попередження про завислу сесію + вік. -- `run.attempt`: метадані повторних спроб/спроб запуску. -- `diagnostic.heartbeat`: агреговані лічильники (webhooks/черга/сесія). +- `queue.lane.enqueue`: постановка в lane черги команд + глибина. +- `queue.lane.dequeue`: зняття з lane черги команд + час очікування. +- `session.state`: перехід стану сеансу + причина. +- `session.stuck`: попередження про завислий сеанс + вік. +- `run.attempt`: метадані повторної спроби/спроби запуску. +- `diagnostic.heartbeat`: агреговані лічильники (webhooks/черга/сеанс). -### Увімкнути diagnostics (без exporter-а) +### Увімкнення діагностики (без експортера) -Використовуйте це, якщо хочете, щоб події diagnostics були доступні plugins або custom sink-ам: +Використовуйте це, якщо хочете, щоб події діагностики були доступні для плагінів або власних приймачів: ```json { @@ -234,10 +228,10 @@ Diagnostics — це структуровані, машиночитані под } ``` -### Прапорці diagnostics (цільові логи) +### Прапорці діагностики (цільові журнали) -Використовуйте прапорці, щоб увімкнути додаткові цільові debug-логи без підвищення `logging.level`. -Прапорці нечутливі до регістру й підтримують wildcard-и (наприклад `telegram.*` або `*`). +Використовуйте прапорці, щоб увімкнути додаткові, цільові журнали налагодження без підвищення `logging.level`. +Прапорці нечутливі до регістру та підтримують шаблони з wildcard (наприклад, `telegram.*` або `*`). ```json { @@ -247,7 +241,7 @@ Diagnostics — це структуровані, машиночитані под } ``` -Перевизначення через env (одноразово): +Перевизначення через змінну середовища (для разового запуску): ``` OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload @@ -255,14 +249,14 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload Примітки: -- Логи за прапорцями потрапляють у стандартний log file (той самий, що в `logging.file`). -- Вивід однаково редагується відповідно до `logging.redactSensitive`. +- Журнали за прапорцями записуються у стандартний файл журналу (той самий, що й `logging.file`). +- Вивід усе одно редагується відповідно до `logging.redactSensitive`. - Повний посібник: [/diagnostics/flags](/uk/diagnostics/flags). ### Експорт до OpenTelemetry -Diagnostics можна експортувати через Plugin `diagnostics-otel` (OTLP/HTTP). Це -працює з будь-яким OpenTelemetry collector/backend, який приймає OTLP/HTTP. +Діагностику можна експортувати через Plugin `diagnostics-otel` (OTLP/HTTP). Це +працює з будь-яким колектором/бекендом OpenTelemetry, який приймає OTLP/HTTP. ```json { @@ -285,7 +279,15 @@ Diagnostics можна експортувати через Plugin `diagnostics-o "metrics": true, "logs": true, "sampleRate": 0.2, - "flushIntervalMs": 60000 + "flushIntervalMs": 60000, + "captureContent": { + "enabled": false, + "inputMessages": false, + "outputMessages": false, + "toolInputs": false, + "toolOutputs": false, + "systemPrompt": false + } } } } @@ -293,62 +295,74 @@ Diagnostics можна експортувати через Plugin `diagnostics-o Примітки: -- Ви також можете ввімкнути Plugin через `openclaw plugins enable diagnostics-otel`. -- Наразі `protocol` підтримує лише `http/protobuf`. `grpc` ігнорується. -- Metrics включають використання токенів, вартість, розмір контексту, тривалість запуску та - counters/histograms потоку повідомлень (webhooks, постановка в чергу, стан сесії, глибина/очікування черги). -- Traces/metrics можна перемикати через `traces` / `metrics` (типово: увімкнено). Traces - включають spans використання моделі, а також spans обробки webhook/message, якщо їх увімкнено. -- Установіть `headers`, якщо ваш collector вимагає auth. +- Ви також можете ввімкнути Plugin за допомогою `openclaw plugins enable diagnostics-otel`. +- `protocol` наразі підтримує лише `http/protobuf`. `grpc` ігнорується. +- Метрики включають використання токенів, вартість, розмір контексту, тривалість запуску та + лічильники/гістограми потоку повідомлень (webhooks, постановка в чергу, стан сеансу, глибина/очікування черги). +- Трасування/метрики можна перемикати через `traces` / `metrics` (типово: увімкнено). Трасування + включають span-и використання моделей, а також span-и обробки webhook/повідомлень, коли це ввімкнено. +- Вміст сирих моделей/інструментів типово не експортується. Використовуйте + `diagnostics.otel.captureContent` лише тоді, коли ваш колектор і політика зберігання + схвалені для тексту підказок, відповідей, інструментів або системних підказок. +- Установіть `headers`, якщо ваш колектор вимагає автентифікації. - Підтримувані змінні середовища: `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_PROTOCOL`. -### Експортовані metrics (назви + типи) +### Експортовані метрики (назви + типи) Використання моделей: -- `openclaw.tokens` (counter, attrs: `openclaw.token`, `openclaw.channel`, +- `openclaw.tokens` (лічильник, атрибути: `openclaw.token`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `openclaw.cost.usd` (counter, attrs: `openclaw.channel`, `openclaw.provider`, +- `openclaw.cost.usd` (лічильник, атрибути: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `openclaw.run.duration_ms` (histogram, attrs: `openclaw.channel`, +- `openclaw.run.duration_ms` (гістограма, атрибути: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `openclaw.context.tokens` (histogram, attrs: `openclaw.context`, +- `openclaw.context.tokens` (гістограма, атрибути: `openclaw.context`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`) Потік повідомлень: -- `openclaw.webhook.received` (counter, attrs: `openclaw.channel`, +- `openclaw.webhook.received` (лічильник, атрибути: `openclaw.channel`, `openclaw.webhook`) -- `openclaw.webhook.error` (counter, attrs: `openclaw.channel`, +- `openclaw.webhook.error` (лічильник, атрибути: `openclaw.channel`, `openclaw.webhook`) -- `openclaw.webhook.duration_ms` (histogram, attrs: `openclaw.channel`, +- `openclaw.webhook.duration_ms` (гістограма, атрибути: `openclaw.channel`, `openclaw.webhook`) -- `openclaw.message.queued` (counter, attrs: `openclaw.channel`, +- `openclaw.message.queued` (лічильник, атрибути: `openclaw.channel`, `openclaw.source`) -- `openclaw.message.processed` (counter, attrs: `openclaw.channel`, +- `openclaw.message.processed` (лічильник, атрибути: `openclaw.channel`, `openclaw.outcome`) -- `openclaw.message.duration_ms` (histogram, attrs: `openclaw.channel`, +- `openclaw.message.duration_ms` (гістограма, атрибути: `openclaw.channel`, `openclaw.outcome`) -Черги + сесії: +Черги + сеанси: -- `openclaw.queue.lane.enqueue` (counter, attrs: `openclaw.lane`) -- `openclaw.queue.lane.dequeue` (counter, attrs: `openclaw.lane`) -- `openclaw.queue.depth` (histogram, attrs: `openclaw.lane` або +- `openclaw.queue.lane.enqueue` (лічильник, атрибути: `openclaw.lane`) +- `openclaw.queue.lane.dequeue` (лічильник, атрибути: `openclaw.lane`) +- `openclaw.queue.depth` (гістограма, атрибути: `openclaw.lane` або `openclaw.channel=heartbeat`) -- `openclaw.queue.wait_ms` (histogram, attrs: `openclaw.lane`) -- `openclaw.session.state` (counter, attrs: `openclaw.state`, `openclaw.reason`) -- `openclaw.session.stuck` (counter, attrs: `openclaw.state`) -- `openclaw.session.stuck_age_ms` (histogram, attrs: `openclaw.state`) -- `openclaw.run.attempt` (counter, attrs: `openclaw.attempt`) +- `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`) -### Експортовані spans (назви + ключові атрибути) +### Експортовані span-и (назви + ключові атрибути) - `openclaw.model.usage` - `openclaw.channel`, `openclaw.provider`, `openclaw.model` - - `openclaw.sessionKey`, `openclaw.sessionId` - `openclaw.tokens.*` (input/output/cache_read/cache_write/total) +- `openclaw.run` + - `openclaw.outcome`, `openclaw.channel`, `openclaw.provider`, + `openclaw.model`, `openclaw.errorCategory` +- `openclaw.model.call` + - `gen_ai.system`, `gen_ai.request.model`, `gen_ai.operation.name`, + `openclaw.provider`, `openclaw.model`, `openclaw.api`, + `openclaw.transport` +- `openclaw.tool.execution` + - `gen_ai.tool.name`, `openclaw.toolName`, `openclaw.errorCategory`, + `openclaw.tool.params.*` - `openclaw.webhook.processed` - `openclaw.channel`, `openclaw.webhook`, `openclaw.chatId` - `openclaw.webhook.error` @@ -356,40 +370,42 @@ Diagnostics можна експортувати через Plugin `diagnostics-o `openclaw.error` - `openclaw.message.processed` - `openclaw.channel`, `openclaw.outcome`, `openclaw.chatId`, - `openclaw.messageId`, `openclaw.sessionKey`, `openclaw.sessionId`, - `openclaw.reason` + `openclaw.messageId`, `openclaw.reason` - `openclaw.session.stuck` - - `openclaw.state`, `openclaw.ageMs`, `openclaw.queueDepth`, - `openclaw.sessionKey`, `openclaw.sessionId` + - `openclaw.state`, `openclaw.ageMs`, `openclaw.queueDepth` -### Sampling + flushing +Коли захоплення вмісту явно ввімкнено, span-и моделі/інструментів також можуть містити +обмежені, відредаговані атрибути `openclaw.content.*` для конкретних класів вмісту, +які ви дозволили. -- Sampling traces: `diagnostics.otel.sampleRate` (0.0–1.0, лише root spans). -- Інтервал експорту metrics: `diagnostics.otel.flushIntervalMs` (мінімум 1000 мс). +### Вибірка + скидання + +- Вибірка трасувань: `diagnostics.otel.sampleRate` (0.0–1.0, лише кореневі span-и). +- Інтервал експорту метрик: `diagnostics.otel.flushIntervalMs` (мінімум 1000 мс). ### Примітки щодо протоколу -- Endpoints OTLP/HTTP можна задати через `diagnostics.otel.endpoint` або +- Кінцеві точки OTLP/HTTP можна задати через `diagnostics.otel.endpoint` або `OTEL_EXPORTER_OTLP_ENDPOINT`. -- Якщо endpoint уже містить `/v1/traces` або `/v1/metrics`, він використовується як є. -- Якщо endpoint уже містить `/v1/logs`, він використовується як є для logs. -- `diagnostics.otel.logs` вмикає експорт основного logger output через OTLP. +- Якщо кінцева точка вже містить `/v1/traces` або `/v1/metrics`, вона використовується як є. +- Якщо кінцева точка вже містить `/v1/logs`, вона використовується як є для журналів. +- `diagnostics.otel.logs` вмикає експорт журналів OTLP для основного виводу журналювача. -### Поведінка експорту логів +### Поведінка експорту журналів -- Логи OTLP використовують ті самі структуровані записи, які записуються в `logging.file`. -- Дотримуються `logging.level` (рівня файлових логів). Редагування консолі **не** застосовується - до логів OTLP. -- На встановленнях із великим обсягом логів краще покладатися на sampling/filtering у collector OTLP. +- Журнали OTLP використовують ті самі структуровані записи, що записуються до `logging.file`. +- Враховується `logging.level` (рівень журналів у файлах). Редагування консолі **не** застосовується + до журналів OTLP. +- Для інсталяцій із великим обсягом даних варто віддавати перевагу вибірці/фільтрації в колекторі OTLP. -## Поради щодо усунення несправностей +## Поради з усунення несправностей - **Gateway недоступний?** Спочатку виконайте `openclaw doctor`. -- **Логи порожні?** Перевірте, що Gateway запущено й він записує у шлях файлу, - заданий у `logging.file`. -- **Потрібно більше деталей?** Установіть `logging.level` у `debug` або `trace` і повторіть спробу. +- **Журнали порожні?** Перевірте, що Gateway запущений і записує у шлях файлу, + вказаний у `logging.file`. +- **Потрібно більше деталей?** Установіть `logging.level` на `debug` або `trace` і повторіть спробу. ## Пов’язане -- [Внутрішня будова логування Gateway](/uk/gateway/logging) — стилі логів WS, префікси підсистем і захоплення консолі -- [Diagnostics](/uk/gateway/configuration-reference#diagnostics) — експорт OpenTelemetry і конфігурація trace кешу +- [Внутрішня будова журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі +- [Діагностика](/uk/gateway/configuration-reference#diagnostics) — експорт OpenTelemetry і конфігурація трасування кешу