chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
5bce178f8e
commit
56c7a96df5
@ -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.<skillKey>.enabled: false` вимикає skill, навіть якщо він bundled/встановлений.
|
||||
- `entries.<skillKey>.apiKey`: зручне поле для skills, які оголошують основну змінну середовища (рядок відкритим текстом або об’єкт SecretRef).
|
||||
- `install.preferBrew`: якщо `true`, надавати перевагу інсталяторам Homebrew, коли доступний `brew`, перш ніж переходити до інших типів інсталяторів.
|
||||
- `install.nodeManager`: пріоритет інсталятора Node для специфікацій `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`).
|
||||
- `entries.<skillKey>.enabled: false` вимикає skill, навіть якщо він комплектний/встановлений.
|
||||
- `entries.<skillKey>.apiKey`: зручне поле для skills, які оголошують основну змінну середовища (рядок відкритого тексту або об’єкт SecretRef).
|
||||
|
||||
---
|
||||
|
||||
@ -118,48 +116,48 @@ bundled каналів (автентифікація, контроль дост
|
||||
}
|
||||
```
|
||||
|
||||
- Завантажуються з `~/.openclaw/extensions`, `<workspace>/.openclaw/extensions`, а також `plugins.load.paths`.
|
||||
- Виявлення підтримує нативні Plugins OpenClaw, а також сумісні пакунки Codex і Claude, зокрема пакунки Claude зі стандартним розташуванням без manifest.
|
||||
- Завантажуються з `~/.openclaw/extensions`, `<workspace>/.openclaw/extensions` і `plugins.load.paths`.
|
||||
- Виявлення підтримує нативні Plugins OpenClaw, а також сумісні пакети Codex і Claude, зокрема пакети Claude із типовим макетом без manifest.
|
||||
- **Зміни конфігурації потребують перезапуску gateway.**
|
||||
- `allow`: необов’язковий список дозволених (завантажуються лише вказані Plugins). `deny` має пріоритет.
|
||||
- `plugins.entries.<id>.apiKey`: зручне поле API key на рівні Plugin (коли Plugin це підтримує).
|
||||
- `plugins.entries.<id>.env`: мапа змінних середовища в межах Plugin.
|
||||
- `plugins.entries.<id>.hooks.allowPromptInjection`: якщо `false`, ядро блокує `before_prompt_build` та ігнорує поля, що змінюють prompt, із застарілого `before_agent_start`, водночас зберігаючи застарілі `modelOverride` і `providerOverride`. Застосовується до нативних хуків Plugin і підтримуваних каталогів хуків, що надаються пакунками.
|
||||
- `plugins.entries.<id>.hooks.allowConversationAccess`: якщо `true`, довірені небандловані Plugins можуть читати необроблений вміст розмови з типізованих хуків, таких як `llm_input`, `llm_output` і `agent_end`.
|
||||
- `plugins.entries.<id>.subagent.allowModelOverride`: явно довіряє цьому Plugin запитувати перевизначення `provider` і `model` для окремого запуску фонових subagent.
|
||||
- `plugins.entries.<id>.subagent.allowedModels`: необов’язковий список дозволених канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"` лише тоді, коли справді хочете дозволити будь-яку модель.
|
||||
- `plugins.entries.<id>.config`: об’єкт конфігурації, визначений Plugin (валідується за нативною схемою Plugin OpenClaw, якщо вона доступна).
|
||||
- `allow`: необов’язковий список дозволених (завантажуються лише перелічені Plugins). `deny` має пріоритет.
|
||||
- `plugins.entries.<id>.apiKey`: зручне поле API-ключа на рівні Plugin (коли підтримується Plugin).
|
||||
- `plugins.entries.<id>.env`: карта змінних середовища в межах Plugin.
|
||||
- `plugins.entries.<id>.hooks.allowPromptInjection`: коли `false`, ядро блокує `before_prompt_build` і ігнорує поля, що змінюють prompt, із застарілого `before_agent_start`, зберігаючи при цьому застарілі `modelOverride` і `providerOverride`. Застосовується до нативних хуків Plugin і підтримуваних каталогів хуків, наданих пакетами.
|
||||
- `plugins.entries.<id>.hooks.allowConversationAccess`: коли `true`, довірені некомплектні Plugins можуть читати необроблений вміст розмови з типізованих хуків, таких як `llm_input`, `llm_output` і `agent_end`.
|
||||
- `plugins.entries.<id>.subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для окремих запусків фонових subagent.
|
||||
- `plugins.entries.<id>.subagent.allowedModels`: необов’язковий список дозволених канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"`, лише якщо ви навмисно хочете дозволити будь-яку модель.
|
||||
- `plugins.entries.<id>.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 каналів (автентифікація, контроль дост
|
||||
|
||||
<Accordion title="Докладно про поля Gateway">
|
||||
|
||||
- `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.<provider>.healthMonitor.enabled`: вимкнення на рівні каналу для перезапусків health-monitor, при цьому глобальний монітор залишається увімкненим.
|
||||
- `channels.<provider>.accounts.<accountId>.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.<provider>.healthMonitor.enabled`: вимкнення перезапусків монітора стану для окремого каналу зі збереженням глобального монітора.
|
||||
- `channels.<provider>.accounts.<accountId>.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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
### Кінцеві точки, сумісні з 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 <token>` або `x-openclaw-token: <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/<name>` → розв’язується через `hooks.mappings`
|
||||
- Значення `sessionKey` у mapping, зрендерені через шаблон, вважаються зовнішньо заданими і також вимагають `hooks.allowRequestSessionKey=true`.
|
||||
- Значення `sessionKey` у mapping, згенеровані шаблоном, вважаються зовнішньо переданими й також потребують `hooks.allowRequestSessionKey=true`.
|
||||
|
||||
<Accordion title="Докладно про mappings">
|
||||
<Accordion title="Докладно про mapping">
|
||||
|
||||
- `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 (має бути дозволено, якщо задано каталог моделей).
|
||||
|
||||
</Accordion>
|
||||
|
||||
### Інтеграція 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 <token>` або `x-openclaw-token: <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 <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- Обслуговує HTML/CSS/JS і A2UI, які агент може редагувати, через HTTP на порту Gateway:
|
||||
- Обслуговує HTML/CSS/JS і A2UI, які може редагувати агент, через HTTP на порту Gateway:
|
||||
- `http://<gateway-host>:<gateway.port>/__openclaw__/canvas/`
|
||||
- `http://<gateway-host>:<gateway.port>/__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 <token>` або `x-openclaw-token: <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 <token>` або `x-openclaw-token: <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 <token>` або `x-openclaw-token: <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 <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`.
|
||||
- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`.
|
||||
- Відсутні/порожні змінні викликають помилку під час завантаження конфігурації.
|
||||
- Екрануйте через `$${VAR}`, щоб отримати буквальний `${VAR}`.
|
||||
- Екрануйте як `$${VAR}` для буквального `${VAR}`.
|
||||
- Працює з `$include`.
|
||||
|
||||
---
|
||||
@ -637,7 +634,7 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
|
||||
### `SecretRef`
|
||||
|
||||
Використовуйте одну таку форму об’єкта:
|
||||
Використовуйте одну з форм об’єкта:
|
||||
|
||||
```json5
|
||||
{ source: "env" | "file" | "exec", provider: "default", id: "..." }
|
||||
@ -647,15 +644,15 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <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 <token>` або `x-openclaw-token: <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 <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- Профілі для кожного агента зберігаються в `<agentDir>/auth-profiles.json`.
|
||||
- Профілі для окремих агентів зберігаються в `<agentDir>/auth-profiles.json`.
|
||||
- `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних.
|
||||
- Профілі режиму OAuth (`auth.profiles.<id>.mode = "oauth"`) не підтримують облікові дані профілю auth на основі SecretRef.
|
||||
- Статичні runtime-облікові дані надходять із розв’язаних snapshot у пам’яті; застарілі статичні записи `auth.json` очищаються при виявленні.
|
||||
- Застарілий імпорт OAuth виконується з `~/.openclaw/credentials/oauth.json`.
|
||||
- Профілі режиму OAuth (`auth.profiles.<id>.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 <token>` або `x-openclaw-token: <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 <token>` або `x-openclaw-token: <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 <token>` або `x-openclaw-token: <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 <token>` або `x-openclaw-token: <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 <token>` або `x-openclaw-token: <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 <token>` або `x-openclaw-token: <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 <token>` або `x-openclaw-token: <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 <token>` або `x-openclaw-token: <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` може прибрати невідомі ключі).
|
||||
|
||||
<Accordion title="Застаріла конфігурація bridge (історична довідка)">
|
||||
|
||||
@ -995,11 +1001,11 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- `sessionRetention`: як довго зберігати завершені ізольовані сесії виконання Cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів Cron. Типове значення: `24h`; установіть `false`, щоб вимкнути.
|
||||
- `runLog.maxBytes`: максимальний розмір файла журналу одного запуску (`cron/runs/<jobId>.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/<jobId>.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 <token>` або `x-openclaw-token: <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 <token>` або `x-openclaw-token: <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 <token>` або `x-openclaw-token: <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 <token>` або `x-openclaw-token: <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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -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 <url>` / `--token <token>` / `--timeout <ms>`: стандартні прапорці RPC Gateway
|
||||
- `--expect-final`: прапорець очікування остаточної відповіді для agent-backed RPC (тут приймається через спільний client layer)
|
||||
- `--local-time`: відображати часові мітки у вашому локальному часовому поясі
|
||||
- `--url <url>` / `--token <token>` / `--timeout <ms>`: стандартні прапорці 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 <level>`** (наприклад, `openclaw --log-level debug gateway run`), який для цієї команди перевизначає змінну середовища.
|
||||
Ви можете перевизначити обидва через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має вищий пріоритет за файл конфігурації, тому ви можете підвищити деталізацію для одного запуску без редагування `openclaw.json`. Ви також можете передати глобальний параметр CLI **`--log-level <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 і конфігурація трасування кешу
|
||||
|
||||
Loading…
Reference in New Issue
Block a user