diff --git a/docs/uk/concepts/parallel-specialist-lanes.md b/docs/uk/concepts/parallel-specialist-lanes.md new file mode 100644 index 000000000..9d3dad27a --- /dev/null +++ b/docs/uk/concepts/parallel-specialist-lanes.md @@ -0,0 +1,134 @@ +--- +read_when: + - Ви маршрутизуєте групові чати до виділених агентів + - Вам потрібна паралельна робота без того, щоб одне тривале завдання блокувало кожен чат + - Ви проєктуєте мультиагентну операційну конфігурацію +sidebarTitle: Specialist lanes +status: active +summary: Запускайте паралельних спеціалізованих агентів, не перевантажуючи спільні ресурси моделі та інструментів +title: Паралельні спеціалізовані напрями +x-i18n: + generated_at: "2026-05-02T10:18:23Z" + model: gpt-5.5 + provider: openai + source_hash: b09f10ce4fbd79954a7196fbedb23f9b3f34b459b98eb7a5480f7eeb0bb6be98 + source_path: concepts/parallel-specialist-lanes.md + workflow: 16 +--- + +Паралельні спеціалізовані лінії дають одному Gateway змогу спрямовувати різні чати або кімнати до +різних агентів, зберігаючи швидкий користувацький досвід. Суть у тому, щоб розглядати +паралелізм як задачу проєктування для дефіцитних ресурсів, а не просто як «більше агентів». + +## Базові принципи + +Спеціалізована лінія покращує пропускну здатність лише тоді, коли зменшує конкуренцію за +справжні вузькі місця: + +- **Блокування сесій**: лише один запуск має змінювати певну сесію одночасно. +- **Глобальна ємність моделі**: усі видимі запуски чатів усе одно спільно використовують ліміти провайдера. +- **Ємність інструментів**: робота із shell, браузером, мережею та репозиторієм може бути повільнішою + за сам хід моделі. +- **Бюджет контексту**: довгі стенограми роблять кожен майбутній хід повільнішим і менш + сфокусованим. +- **Неоднозначність власності**: дублікати агентів, які виконують ту саму роботу, марнують ємність. + +OpenClaw вже серіалізує запуски для кожної сесії та обмежує глобальний паралелізм через +[чергу команд](/uk/concepts/queue). Спеціалізовані лінії додають політику поверх цього: +який агент володіє якою роботою, що лишається в чаті, а що стає фоновою +роботою. + +## Рекомендоване впровадження + +### Етап 1: контракти ліній + важка фонова робота + +Дайте кожній лінії письмовий контракт у її робочому просторі та системному prompt: + +- **Призначення**: робота, якою володіє ця лінія. +- **Нецілі**: робота, яку вона має передавати далі замість того, щоб виконувати самостійно. +- **Бюджет чату**: швидкі відповіді залишаються в чаті; довгі завдання слід коротко + підтвердити, а потім виконати у фоновому субагенті або задачі. +- **Правило передачі**: коли роботою володіє інша лінія, скажіть, куди її слід спрямувати, і + надайте стислий підсумок для передачі. +- **Правило ризику інструментів**: віддавайте перевагу найменшій поверхні інструментів, здатній виконати завдання. + +Це найдешевший етап, який усуває більшість заторів: одне завдання з кодування більше не +перетворює дослідницьку лінію на патоку, і кожен чат зберігає власний контекст чистим. + +### Етап 2: пріоритети та керування конкурентністю + +Налаштуйте ємність черги й моделі навколо бізнес-цінності кожної лінії: + +```json5 +{ + agents: { + defaults: { + maxConcurrent: 4, + subagents: { maxConcurrent: 8 }, + }, + }, + messages: { + queue: { + mode: "collect", + debounceMs: 1000, + cap: 20, + drop: "summarize", + }, + }, +} +``` + +Використовуйте прямі/особисті чати та агентів production-ops для високопріоритетної роботи. Дозволяйте +дослідженням, чернеткам і пакетному кодуванню переходити у фонові задачі, коли система +завантажена. + +### Етап 3: координатор / диспетчер трафіку + +Додайте невеликий патерн координатора, коли активні кілька ліній: + +- Відстежуйте активні задачі ліній і власників. +- Виявляйте дублікати запитів у різних групах. +- Спрямовуйте підсумки передачі між лініями. +- Показуйте лише блокери, завершені результати та рішення, які має ухвалити людина. + +Не починайте з цього. Координатор без контрактів ліній лише координує хаос. + +## Мінімальний шаблон контракту лінії + +```md +# Lane contract + +## Owns + +- + +## Does not own + +- + +## Chat budget + +- Answer quick questions directly. +- For multi-step, slow, or tool-heavy work: acknowledge briefly, spawn/background + the work, then return the result when complete. + +## Handoff + +If another lane owns the request, reply with: + +- target lane +- objective +- relevant context +- exact next action + +## Tool posture + +Use the smallest tool surface that can complete the task. Avoid broad shell or +network work unless this lane explicitly owns it. +``` + +## Пов’язане + +- [Маршрутизація між кількома агентами](/uk/concepts/multi-agent) +- [Черга команд](/uk/concepts/queue) +- [Субагенти](/uk/tools/subagents) diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index 852c4b7e9..bf411197e 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -1,40 +1,40 @@ --- read_when: - - Вам потрібна точна семантика конфігурації на рівні полів або точні значення за замовчуванням + - Вам потрібна точна семантика конфігурації на рівні полів або значення за замовчуванням - Ви перевіряєте блоки конфігурації каналу, моделі, Gateway або інструмента -summary: Довідник з конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем +summary: Довідник із конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем title: Довідник із конфігурації x-i18n: - generated_at: "2026-05-02T09:29:32Z" + generated_at: "2026-05-02T10:18:16Z" model: gpt-5.5 provider: openai - source_hash: fa8aeec6143ae70905e75f1034005c97c3a72fcaa34f14f61294dece561f4ce6 + source_hash: 615dda0385c6a4efb9bfcc010de221b2d799dab73e612f6e4681fd14d45f15d0 source_path: gateway/configuration-reference.md workflow: 16 --- -Основна довідка з конфігурації для `~/.openclaw/openclaw.json`. Огляд, орієнтований на завдання, див. у [Конфігурації](/uk/gateway/configuration). +Основний довідник конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Конфігурація](/uk/gateway/configuration). -Охоплює основні поверхні конфігурації OpenClaw і посилається назовні, коли підсистема має власну глибшу довідку. Каталоги команд, що належать каналам і plugin, а також глибокі параметри пам'яті/QMD розміщені на власних сторінках, а не на цій. +Охоплює основні поверхні конфігурації OpenClaw і посилається назовні, коли підсистема має власний докладніший довідник. Каталоги команд, що належать каналам і Plugin, а також глибокі параметри памʼяті/QMD розміщені на власних сторінках, а не на цій. -Істина в коді: +Правда коду: -- `openclaw config schema` виводить поточну JSON Schema, що використовується для валідації та Control UI, з об'єднаними метаданими вбудованих/plugin/каналів, коли вони доступні -- `config.schema.lookup` повертає один вузол схеми, обмежений шляхом, для інструментів деталізації +- `openclaw config schema` виводить живу JSON Schema, що використовується для валідації та Control UI, з обʼєднаними метаданими вбудованих/Plugin/каналів, коли вони доступні +- `config.schema.lookup` повертає один вузол схеми з областю дії за шляхом для інструментів деталізації - `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш документації конфігурації щодо поточної поверхні схеми -Шлях пошуку для агента: використовуйте дію інструмента `gateway` `config.schema.lookup` для +Шлях пошуку агента: використовуйте дію інструмента `gateway` `config.schema.lookup` для точної документації та обмежень на рівні полів перед редагуванням. Використовуйте -[Конфігурацію](/uk/gateway/configuration) для порад, орієнтованих на завдання, а цю сторінку -для ширшої карти полів, значень за замовчуванням і посилань на довідки підсистем. +[Конфігурація](/uk/gateway/configuration) для орієнтованих на завдання настанов, а цю сторінку +для ширшої карти полів, значень за замовчуванням і посилань на довідники підсистем. -Окремі глибокі довідки: +Окремі глибокі довідники: -- [Довідка з конфігурації пам'яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації Dreaming у `plugins.entries.memory-core.config.dreaming` -- [Slash-команди](/uk/tools/slash-commands) для поточного каталогу вбудованих + bundled команд -- сторінки відповідних власників каналів/plugin для поверхонь команд, специфічних для каналу +- [Довідник конфігурації памʼяті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації dreaming у `plugins.entries.memory-core.config.dreaming` +- [Slash-команди](/uk/tools/slash-commands) для поточного каталогу вбудованих + пакетних команд +- сторінки відповідних каналів/Plugin для поверхонь команд, специфічних для каналів -Формат конфігурації — **JSON5** (дозволені коментарі + кінцеві коми). Усі поля необов'язкові — OpenClaw використовує безпечні значення за замовчуванням, коли їх пропущено. +Формат конфігурації — **JSON5** (дозволені коментарі + кінцеві коми). Усі поля необовʼязкові — OpenClaw використовує безпечні значення за замовчуванням, коли їх пропущено. --- @@ -42,21 +42,21 @@ x-i18n: Ключі конфігурації для окремих каналів перенесено на окрему сторінку — див. [Конфігурація — канали](/uk/gateway/config-channels) для `channels.*`, -включно зі Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та іншими -bundled каналами (автентифікація, контроль доступу, кілька акаунтів, керування згадками). +зокрема Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та інших +пакетних каналів (автентифікація, контроль доступу, кілька облікових записів, керування згадками). -## Значення агента за замовчуванням, multi-agent, сеанси та повідомлення +## Значення агента за замовчуванням, багато агентів, сесії та повідомлення Перенесено на окрему сторінку — див. [Конфігурація — агенти](/uk/gateway/config-agents) для: -- `agents.defaults.*` (робоча область, модель, мислення, Heartbeat, пам'ять, медіа, Skills, sandbox) -- `multiAgent.*` (маршрутизація та прив'язки multi-agent) -- `session.*` (життєвий цикл сеансу, Compaction, обрізання) -- `messages.*` (доставка повідомлень, TTS, рендеринг markdown) +- `agents.defaults.*` (робоча область, модель, мислення, heartbeat, памʼять, медіа, skills, sandbox) +- `multiAgent.*` (маршрутизація та привʼязки багатьох агентів) +- `session.*` (життєвий цикл сесії, compaction, pruning) +- `messages.*` (доставка повідомлень, TTS, відтворення markdown) - `talk.*` (режим Talk) - - `talk.speechLocale`: необов'язковий ідентифікатор локалі BCP 47 для розпізнавання мовлення Talk на iOS/macOS - - `talk.silenceTimeoutMs`: коли не задано, Talk зберігає стандартне вікно паузи платформи перед надсиланням транскрипту (`700 ms on macOS and Android, 900 ms on iOS`) + - `talk.speechLocale`: необовʼязковий ідентифікатор локалі BCP 47 для розпізнавання мовлення Talk на iOS/macOS + - `talk.silenceTimeoutMs`: коли не задано, Talk зберігає стандартне для платформи вікно паузи перед надсиланням транскрипту (`700 ms on macOS and Android, 900 ms on iOS`) ## Інструменти та власні провайдери @@ -66,7 +66,7 @@ bundled каналами (автентифікація, контроль дос ## Моделі -Визначення провайдерів, allowlist моделей і налаштування власного провайдера розміщені в +Визначення провайдерів, списки дозволених моделей і налаштування власних провайдерів розміщені в [Конфігурація — інструменти та власні провайдери](/uk/gateway/config-tools#custom-providers-and-base-urls). Корінь `models` також відповідає за глобальну поведінку каталогу моделей. @@ -80,15 +80,16 @@ bundled каналами (автентифікація, контроль дос ``` - `models.mode`: поведінка каталогу провайдера (`merge` або `replace`). -- `models.providers`: мапа власних провайдерів із ключами за id провайдера. -- `models.pricing.enabled`: керує фоновою ініціалізацією цін. Коли - `false`, запуск Gateway пропускає отримання каталогів цін OpenRouter і LiteLLM; - налаштовані значення `models.providers.*.models[].cost` все одно працюють для локальних оцінок вартості. +- `models.providers`: мапа власних провайдерів із ключами за ідентифікатором провайдера. +- `models.pricing.enabled`: керує фоновою ініціалізацією цін, яка + запускається після того, як sidecar-и та канали досягають шляху готовності Gateway. Коли `false`, + Gateway пропускає отримання каталогів цін OpenRouter і LiteLLM; налаштовані + значення `models.providers.*.models[].cost` усе ще працюють для локальних оцінок вартості. ## MCP Визначення MCP-серверів, керованих OpenClaw, розміщені в `mcp.servers` і -використовуються вбудованим Pi та іншими runtime-адаптерами. Команди `openclaw mcp list`, +споживаються вбудованим Pi та іншими runtime-адаптерами. Команди `openclaw mcp list`, `show`, `set` і `unset` керують цим блоком без підключення до цільового сервера під час редагування конфігурації. @@ -114,17 +115,17 @@ bundled каналами (автентифікація, контроль дос } ``` -- `mcp.servers`: іменовані визначення stdio або віддалених MCP-серверів для runtime, які - надають налаштовані MCP-інструменти. +- `mcp.servers`: іменовані stdio або віддалені визначення MCP-серверів для runtime, які + надають налаштовані інструменти MCP. Віддалені записи використовують `transport: "streamable-http"` або `transport: "sse"`; - `type: "http"` — це CLI-нативний alias, який `openclaw mcp set` і + `type: "http"` є CLI-native псевдонімом, який `openclaw mcp set` і `openclaw doctor --fix` нормалізують у канонічне поле `transport`. -- `mcp.sessionIdleTtlMs`: TTL простою для bundled MCP runtime, обмежених сеансом. - Одноразові вбудовані запуски запитують очищення після завершення запуску; цей TTL є резервним механізмом для - довготривалих сеансів і майбутніх викликачів. -- Зміни в `mcp.*` застосовуються гаряче шляхом звільнення кешованих MCP runtime сеансу. - Наступне виявлення/використання інструментів відтворює їх із нової конфігурації, тож видалені - записи `mcp.servers` прибираються негайно, а не чекають на TTL простою. +- `mcp.sessionIdleTtlMs`: idle TTL для пакетних MCP-runtime з областю дії сесії. + Одноразові вбудовані запуски запитують очищення наприкінці запуску; цей TTL є резервним механізмом для + довгоживучих сесій і майбутніх викликачів. +- Зміни в `mcp.*` застосовуються гаряче шляхом утилізації кешованих MCP-runtime сесії. + Наступне виявлення/використання інструментів відтворює їх із нової конфігурації, тому вилучені + записи `mcp.servers` прибираються негайно, а не чекають idle TTL. Див. [MCP](/uk/cli/mcp#openclaw-as-an-mcp-client-registry) і [CLI-бекенди](/uk/gateway/cli-backends#bundle-mcp-overlays) щодо поведінки runtime. @@ -154,14 +155,14 @@ bundled каналами (автентифікація, контроль дос } ``` -- `allowBundled`: необов'язковий allowlist лише для bundled Skills (керовані/робочі Skills не зачіпаються). +- `allowBundled`: необовʼязковий список дозволів лише для пакетних Skills (керовані/робочі Skills не зачіпаються). - `load.extraDirs`: додаткові спільні корені Skills (найнижчий пріоритет). -- `install.preferBrew`: коли true, надавати перевагу інсталяторам Homebrew, якщо `brew` - доступний, перед переходом до інших типів інсталяторів. -- `install.nodeManager`: перевага інсталятора node для специфікацій `metadata.openclaw.install` +- `install.preferBrew`: коли true, надавати перевагу інсталяторам Homebrew, коли `brew` + доступний, перш ніж повертатися до інших типів інсталяторів. +- `install.nodeManager`: перевага Node-інсталятора для специфікацій `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` вимикає skill, навіть якщо він bundled/встановлений. -- `entries..apiKey`: зручність для Skills, що оголошують основну змінну env (plaintext string або об'єкт SecretRef). +- `entries..enabled: false` вимикає Skill, навіть якщо він пакетний/встановлений. +- `entries..apiKey`: зручність для Skills, які оголошують основну env-змінну (звичайний текстовий рядок або обʼєкт SecretRef). --- @@ -189,41 +190,41 @@ bundled каналами (автентифікація, контроль дос } ``` -- Завантажується з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. -- Виявлення приймає нативні plugins OpenClaw, а також сумісні Codex bundles і Claude bundles, включно з manifestless Claude bundles зі стандартним layout. -- **Зміни конфігурації потребують перезапуску gateway.** -- `allow`: необов'язковий allowlist (завантажуються лише перелічені plugins). `deny` має пріоритет. -- `plugins.entries..apiKey`: зручне поле API-ключа на рівні plugin (коли підтримується plugin). -- `plugins.entries..env`: мапа змінних env, обмежена plugin. -- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` та ігнорує поля, що змінюють prompt, із legacy `before_agent_start`, зберігаючи legacy `modelOverride` і `providerOverride`. Застосовується до нативних hook plugin і підтримуваних директорій hook, наданих bundle. -- `plugins.entries..hooks.allowConversationAccess`: коли `true`, довірені небудовані bundled plugins можуть читати сирий вміст розмови з типізованих hook, як-от `llm_input`, `llm_output`, `before_agent_finalize` і `agent_end`. -- `plugins.entries..subagent.allowModelOverride`: явно довірити цьому plugin запитувати per-run перевизначення `provider` і `model` для фонових запусків subagent. -- `plugins.entries..subagent.allowedModels`: необов'язковий allowlist канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"` лише тоді, коли навмисно хочете дозволити будь-яку модель. -- `plugins.entries..config`: об'єкт конфігурації, визначений plugin (валідується нативною схемою plugin OpenClaw, коли доступна). -- Налаштування акаунта/runtime channel plugin розміщені в `channels.` і мають описуватися метаданими `channelConfigs` маніфесту plugin-власника, а не центральним реєстром опцій OpenClaw. +- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, плюс `plugins.load.paths`. +- Виявлення приймає нативні Plugin OpenClaw, а також сумісні пакети Codex і пакети Claude, зокрема пакети стандартного макета Claude без маніфеста. +- **Зміни конфігурації потребують перезапуску Gateway.** +- `allow`: необовʼязковий список дозволів (завантажуються лише перелічені Plugin). `deny` має перевагу. +- `plugins.entries..apiKey`: зручне поле API-ключа на рівні Plugin (коли підтримується Plugin). +- `plugins.entries..env`: мапа env-змінних з областю дії Plugin. +- `plugins.entries..hooks.allowPromptInjection`: коли `false`, ядро блокує `before_prompt_build` та ігнорує поля, що змінюють prompt, із застарілого `before_agent_start`, водночас зберігаючи застарілі `modelOverride` і `providerOverride`. Застосовується до нативних hooks Plugin і підтримуваних директорій hooks, наданих пакетами. +- `plugins.entries..hooks.allowConversationAccess`: коли `true`, довірені непакетні Plugin можуть читати сирий вміст розмови з типізованих hooks, таких як `llm_input`, `llm_output`, `before_agent_finalize` і `agent_end`. +- `plugins.entries..subagent.allowModelOverride`: явно довірити цьому Plugin запитувати перевизначення `provider` і `model` для кожного запуску фонових subagent-запусків. +- `plugins.entries..subagent.allowedModels`: необовʼязковий список дозволених канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"` лише тоді, коли навмисно хочете дозволити будь-яку модель. +- `plugins.entries..config`: обʼєкт конфігурації, визначений Plugin (валідується нативною схемою Plugin OpenClaw, коли доступна). +- Налаштування облікових записів/runtime Plugin каналу розміщені в `channels.` і мають описуватися метаданими `channelConfigs` маніфеста відповідного Plugin, а не центральним реєстром опцій OpenClaw. - `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера web-fetch Firecrawl. - - `apiKey`: API-ключ Firecrawl (приймає SecretRef). Резервно використовує `plugins.entries.firecrawl.config.webSearch.apiKey`, legacy `tools.web.fetch.firecrawl.apiKey` або змінну env `FIRECRAWL_API_KEY`. - - `baseUrl`: базовий URL API Firecrawl (за замовчуванням: `https://api.firecrawl.dev`; self-hosted перевизначення мають вказувати на приватні/внутрішні endpoints). + - `apiKey`: API-ключ Firecrawl (приймає SecretRef). Повертається до `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілого `tools.web.fetch.firecrawl.apiKey` або env-змінної `FIRECRAWL_API_KEY`. + - `baseUrl`: базовий URL API Firecrawl (за замовчуванням: `https://api.firecrawl.dev`; self-hosted перевизначення мають націлюватися на приватні/внутрішні endpoints). - `onlyMainContent`: витягувати зі сторінок лише основний вміст (за замовчуванням: `true`). - `maxAgeMs`: максимальний вік кешу в мілісекундах (за замовчуванням: `172800000` / 2 дні). - - `timeoutSeconds`: timeout запиту scrape в секундах (за замовчуванням: `60`). + - `timeoutSeconds`: timeout запиту scrape у секундах (за замовчуванням: `60`). - `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (вебпошук Grok). - - `enabled`: увімкнути провайдера X Search. + - `enabled`: увімкнути провайдер X Search. - `model`: модель Grok для використання в пошуку (наприклад, `"grok-4-1-fast"`). - `plugins.entries.memory-core.config.dreaming`: налаштування memory dreaming. Див. [Dreaming](/uk/concepts/dreaming) щодо фаз і порогів. - `enabled`: головний перемикач dreaming (за замовчуванням `false`). - - `frequency`: cron-періодичність для кожного повного проходу dreaming (`"0 3 * * *"` за замовчуванням). - - `model`: необов'язкове перевизначення моделі subagent Dream Diary. Потребує `plugins.entries.memory-core.subagent.allowModelOverride: true`; поєднуйте з `allowedModels`, щоб обмежити цілі. Помилки недоступності моделі повторюються один раз із моделлю сеансу за замовчуванням; збої довіри або allowlist не мають тихого fallback. - - політика фаз і пороги є деталями реалізації (не user-facing ключами конфігурації). -- Повна конфігурація пам'яті розміщена в [Довідці з конфігурації пам'яті](/uk/reference/memory-config): + - `frequency`: cron-каденція для кожного повного проходу dreaming (`"0 3 * * *"` за замовчуванням). + - `model`: необовʼязкове перевизначення моделі subagent Dream Diary. Потребує `plugins.entries.memory-core.subagent.allowModelOverride: true`; поєднуйте з `allowedModels`, щоб обмежити цілі. Помилки недоступності моделі повторюються один раз із моделлю сесії за замовчуванням; збої довіри або списку дозволів не мають тихого fallback. + - політика фаз і пороги є деталями реалізації (не користувацькими ключами конфігурації). +- Повна конфігурація памʼяті розміщена в [Довідник конфігурації памʼяті](/uk/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Увімкнені Claude bundle plugins також можуть додавати вбудовані значення Pi за замовчуванням із `settings.json`; OpenClaw застосовує їх як санітизовані налаштування агента, а не як сирі патчі конфігурації OpenClaw. -- `plugins.slots.memory`: вибрати id активного memory plugin або `"none"`, щоб вимкнути memory plugins. -- `plugins.slots.contextEngine`: вибрати id активного context engine plugin; за замовчуванням `"legacy"`, якщо ви не встановите й не виберете інший engine. +- Увімкнені пакетні Plugin Claude також можуть додавати вбудовані значення Pi за замовчуванням із `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як сирі патчі конфігурації OpenClaw. +- `plugins.slots.memory`: виберіть ідентифікатор активного memory Plugin або `"none"`, щоб вимкнути memory Plugin. +- `plugins.slots.contextEngine`: виберіть ідентифікатор активного context engine Plugin; за замовчуванням `"legacy"`, якщо ви не встановите й не виберете інший engine. Див. [Plugins](/uk/tools/plugin). @@ -276,47 +277,47 @@ bundled каналами (автентифікація, контроль дос ``` - `evaluateEnabled: false` вимикає `act:evaluate` і `wait --fn`. -- `tabCleanup` звільняє відстежувані вкладки основного агента після часу простою або коли сеанс - перевищує свій ліміт. Установіть `idleMinutes: 0` або `maxTabsPerSession: 0`, щоб +- `tabCleanup` повертає відстежувані вкладки основного агента після часу бездіяльності або коли + сесія перевищує свій ліміт. Установіть `idleMinutes: 0` або `maxTabsPerSession: 0`, щоб вимкнути ці окремі режими очищення. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо значення не задано, тому навігація браузера за замовчуванням залишається суворою. -- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації браузера приватною мережею. -- У суворому режимі кінцеві точки віддалених профілів CDP (`profiles.*.cdpUrl`) підпадають під те саме блокування приватної мережі під час перевірок доступності та виявлення. -- `ssrfPolicy.allowPrivateNetwork` залишається підтримуваним як застарілий псевдонім. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому навігація браузера за замовчуванням залишається суворою. +- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли навмисно довіряєте навігації браузера в приватній мережі. +- У суворому режимі кінцеві точки віддалених профілів CDP (`profiles.*.cdpUrl`) підпадають під таке саме блокування приватної мережі під час перевірок доступності/виявлення. +- `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім. - У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків. -- Віддалені профілі працюють лише в режимі підключення (запуск/зупинка/скидання вимкнені). +- Віддалені профілі працюють лише в режимі приєднання (запуск/зупинка/скидання вимкнені). - `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`. - Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявляв `/json/version`; використовуйте WS(S), - коли ваш провайдер надає прямий URL WebSocket DevTools. -- `remoteCdpTimeoutMs` і `remoteCdpHandshakeTimeoutMs` застосовуються до віддаленої та - `attachOnly` доступності CDP, а також до запитів відкриття вкладок. Керовані профілі - loopback зберігають локальні стандартні значення CDP. -- Якщо зовнішньо керована служба CDP доступна через loopback, установіть для цього + Використовуйте HTTP(S), коли потрібно, щоб OpenClaw виявляв `/json/version`; використовуйте WS(S), + коли ваш провайдер надає прямий URL DevTools WebSocket. +- `remoteCdpTimeoutMs` і `remoteCdpHandshakeTimeoutMs` застосовуються до перевірки доступності віддаленого та + `attachOnly` CDP, а також до запитів відкриття вкладок. Керовані профілі loopback + зберігають локальні стандартні значення CDP. +- Якщо зовнішньо керований сервіс CDP доступний через loopback, установіть для цього профілю `attachOnly: true`; інакше OpenClaw розглядатиме порт loopback як - локально керований профіль браузера й може повідомляти про помилки володіння локальним портом. -- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися на - вибраному хості або через підключений браузерний вузол. -- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на певний - профіль браузера на базі Chromium, наприклад Brave або Edge. + локальний керований профіль браузера й може повідомляти про помилки володіння локальним портом. +- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть приєднуватися на + вибраному хості або через підключений вузол браузера. +- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний + профіль браузера на основі Chromium, наприклад Brave або Edge. - Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP: - дії на основі snapshot/ref замість націлювання CSS-селектором, хуки завантаження - одного файлу, без перевизначень тайм-аутів діалогів, без `wait --load networkidle` і без + дії на основі знімків/ref замість націлювання CSS-селектором, хуки завантаження одного файлу, + без перевизначень тайм-аутів діалогів, без `wait --load networkidle`, а також без `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій. -- Локально керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; задавайте - `cdpUrl` явно лише для віддаленого CDP. -- Локально керовані профілі можуть задавати `executablePath`, щоб перевизначити глобальний +- Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно + задавайте `cdpUrl` лише для віддаленого CDP. +- Локальні керовані профілі можуть задавати `executablePath`, щоб перевизначити глобальний `browser.executablePath` для цього профілю. Використовуйте це, щоб запускати один профіль у Chrome, а інший у Brave. -- Локально керовані профілі використовують `browser.localLaunchTimeoutMs` для HTTP-виявлення Chrome CDP +- Локальні керовані профілі використовують `browser.localLaunchTimeoutMs` для HTTP-виявлення Chrome CDP після запуску процесу та `browser.localCdpReadyTimeoutMs` для готовності CDP websocket після запуску. Збільшуйте їх на повільніших хостах, де Chrome успішно запускається, але перевірки готовності змагаються зі стартом. Обидва значення мають бути додатними цілими числами до `120000` мс; недійсні значення конфігурації відхиляються. -- Порядок автовиявлення: стандартний браузер, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- Порядок автовиявлення: стандартний браузер, якщо він на основі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. - `browser.executablePath` і `browser.profiles..executablePath` обидва приймають `~` і `~/...` для домашнього каталогу вашої ОС перед запуском Chromium. - `userDataDir` для кожного профілю на профілях `existing-session` також розгортається з тильдою. -- Служба керування: лише loopback (порт виводиться з `gateway.port`, стандартно `18791`). + `userDataDir` окремого профілю в профілях `existing-session` також розгортається з тильдою. +- Сервіс керування: лише loopback (порт виводиться з `gateway.port`, стандартно `18791`). - `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад `--disable-gpu`, розмір вікна або прапорці налагодження). @@ -336,8 +337,8 @@ bundled каналами (автентифікація, контроль дос } ``` -- `seamColor`: акцентний колір для хрому UI нативного застосунку (відтінок бульбашки Talk Mode тощо). -- `assistant`: перевизначення ідентичності Control UI. Відступає до ідентичності активного агента. +- `seamColor`: акцентний колір для хрому UI нативного застосунку (відтінок бульбашки режиму Talk Mode тощо). +- `assistant`: перевизначення ідентичності Control UI. Повертається до ідентичності активного агента. --- @@ -412,74 +413,66 @@ bundled каналами (автентифікація, контроль дос } ``` - + -- `mode`: `local` (запустити gateway) або `remote` (підключитися до віддаленого gateway). Gateway відмовляється запускатися, якщо значення не `local`. +- `mode`: `local` (запустити Gateway) або `remote` (підключитися до віддаленого Gateway). Gateway відмовляється запускатися, якщо не встановлено `local`. - `port`: єдиний мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (типово), `lan` (`0.0.0.0`), `tailnet` (лише IP Tailscale) або `custom`. -- **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хоста (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Примітка щодо Docker**: типовий bind `loopback` слухає на `127.0.0.1` всередині контейнера. З мережевим мостом Docker (`-p 18789:18789`) трафік надходить на `eth0`, тому gateway недоступний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. -- **Автентифікація**: типово обов’язкова. Bind не на loopback вимагає автентифікації gateway. На практиці це означає спільний токен/пароль або reverse proxy з підтримкою ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер онбордингу типово генерує токен. -- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (зокрема SecretRefs), явно задайте `gateway.auth.mode` як `token` або `password`. Потоки запуску та встановлення/ремонту служби завершуються помилкою, коли обидва параметри налаштовані, а режим не задано. +- **Застарілі псевдоніми прив’язки**: використовуйте значення режиму прив’язки в `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хоста (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Примітка щодо Docker**: типова прив’язка `loopback` слухає на `127.0.0.1` усередині контейнера. За мережі Docker bridge (`-p 18789:18789`) трафік надходить через `eth0`, тому Gateway недоступний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. +- **Автентифікація**: типово обов’язкова. Прив’язки не до loopback потребують автентифікації Gateway. На практиці це означає спільний токен/пароль або reverse proxy з урахуванням ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер онбордингу типово генерує токен. +- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (зокрема SecretRefs), явно встановіть `gateway.auth.mode` на `token` або `password`. Потоки запуску й встановлення/ремонту сервісу завершуються помилкою, коли налаштовано обидва значення, а режим не задано. - `gateway.auth.mode: "none"`: явний режим без автентифікації. Використовуйте лише для довірених налаштувань local loopback; це навмисно не пропонується підказками онбордингу. -- `gateway.auth.mode: "trusted-proxy"`: делегує автентифікацію браузера/користувача reverse proxy з підтримкою ідентичності та довіряє заголовкам ідентичності з `gateway.trustedProxies` (див. [Автентифікація через довірений proxy](/uk/gateway/trusted-proxy-auth)). Цей режим типово очікує джерело proxy **не на loopback**; reverse proxy на loopback того самого хоста вимагають явного `gateway.auth.trustedProxy.allowLoopback = true`. Внутрішні виклики з того самого хоста можуть використовувати `gateway.auth.password` як локальний прямий резервний варіант; `gateway.auth.token` залишається взаємовиключним із режимом trusted-proxy. -- `gateway.auth.allowTailscale`: коли `true`, заголовки ідентичності Tailscale Serve можуть задовольняти автентифікацію інтерфейсу керування/WebSocket (перевіряється через `tailscale whois`). Кінцеві точки HTTP API **не** використовують цю автентифікацію заголовками Tailscale; натомість вони дотримуються звичайного режиму HTTP-автентифікації gateway. Цей потік без токена припускає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб автентифікації. Застосовується для кожної IP-адреси клієнта та кожної області автентифікації (shared-secret і device-token відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`. - - На асинхронному шляху інтерфейсу керування Tailscale Serve невдалі спроби для тієї самої пари `{scope, clientIp}` серіалізуються перед записом помилки. Тому одночасні неправильні спроби від того самого клієнта можуть спрацювати обмежувачем уже на другому запиті, замість того щоб обидві пройшли як прості невідповідності. - - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; задайте `false`, коли навмисно хочете обмежувати частоту й для localhost-трафіку (для тестових налаштувань або суворих розгортань proxy). -- Спроби автентифікації WS з браузерного origin завжди обмежуються з вимкненим винятком для loopback (додатковий захист від браузерного перебору localhost). -- На loopback такі блокування з браузерного origin ізольовані за нормалізованим значенням `Origin`, - тому повторні помилки з одного localhost-origin не блокують автоматично - інший origin. -- `tailscale.mode`: `serve` (лише tailnet, bind на loopback) або `funnel` (публічний, вимагає автентифікації). -- `controlUi.allowedOrigins`: явний список дозволених браузерних origin для підключень WebSocket до Gateway. Обов’язковий, коли очікуються браузерні клієнти з origin не на loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, що вмикає резервне визначення origin за заголовком Host для розгортань, які навмисно покладаються на політику origin за заголовком Host. +- `gateway.auth.mode: "trusted-proxy"`: делегує автентифікацію браузера/користувача reverse proxy з урахуванням ідентичності та довіряє заголовкам ідентичності від `gateway.trustedProxies` (див. [Автентифікація через довірений проксі](/uk/gateway/trusted-proxy-auth)). Цей режим типово очікує джерело проксі **не з loopback**; reverse proxy на loopback того самого хоста потребують явного `gateway.auth.trustedProxy.allowLoopback = true`. Внутрішні викликачі з того самого хоста можуть використовувати `gateway.auth.password` як локальний прямий резервний варіант; `gateway.auth.token` залишається взаємовиключним із режимом trusted-proxy. +- `gateway.auth.allowTailscale`: коли `true`, заголовки ідентичності Tailscale Serve можуть задовольняти автентифікацію Control UI/WebSocket (перевірено через `tailscale whois`). Ендпоінти HTTP API **не** використовують цю автентифікацію заголовків Tailscale; натомість вони дотримуються звичайного режиму HTTP-автентифікації Gateway. Цей потік без токена припускає, що хост Gateway є довіреним. Типово має значення `true`, коли `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб автентифікації. Застосовується для кожної IP-адреси клієнта та кожної області автентифікації (shared-secret і device-token відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`. + - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом помилки. Тому одночасні невдалі спроби від того самого клієнта можуть спрацювати на обмежувачі вже на другому запиті, замість того щоб обидві пройшли як звичайні невідповідності. + - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; установіть `false`, коли ви навмисно хочете обмежувати частоту трафіку localhost також (для тестових налаштувань або суворих розгортань проксі). +- Спроби автентифікації WS з browser-origin завжди обмежуються з вимкненим винятком loopback (глибший захист від browser-based перебору localhost). +- На loopback такі блокування browser-origin ізольовані для кожного нормалізованого значення `Origin`, тому повторні невдалі спроби з одного походження localhost не блокують автоматично інше походження. +- `tailscale.mode`: `serve` (лише tailnet, прив’язка loopback) або `funnel` (публічний, потребує автентифікації). +- `controlUi.allowedOrigins`: явний allowlist browser-origin для підключень Gateway WebSocket. Потрібний, коли очікуються браузерні клієнти з джерел не з loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає резервне визначення походження за Host-header для розгортань, що навмисно покладаються на політику походження Host-header. - `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`, не впливає на клієнтів - WebSocket Gateway. -- `gateway.remote.token` / `.password` — поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують автентифікацію gateway. -- `gateway.push.apns.relay.baseUrl`: базова HTTPS-URL для зовнішнього relay APNs, який використовується офіційними/TestFlight збірками iOS після публікації реєстрацій із підтримкою relay до gateway. Ця URL має збігатися з URL relay, скомпільованою в iOS-збірку. -- `gateway.push.apns.relay.timeoutMs`: таймаут надсилання від gateway до relay у мілісекундах. Типово `10000`. -- Реєстрації з підтримкою relay делегуються конкретній ідентичності gateway. Спарений iOS-застосунок отримує `gateway.identity.get`, включає цю ідентичність у реєстрацію relay і пересилає gateway дозвіл надсилання, обмежений реєстрацією. Інший gateway не може повторно використати цю збережену реєстрацію. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові env-перевизначення для наведеної вище конфігурації relay. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: лише для розробки, аварійний обхід для HTTP-URL relay на loopback. Production-URL relay мають залишатися на HTTPS. -- `gateway.handshakeTimeoutMs`: таймаут WebSocket-рукостискання Gateway до автентифікації в мілісекундах. Типово: `15000`. `OPENCLAW_HANDSHAKE_TIMEOUT_MS` має пріоритет, коли задано. Збільшуйте це значення на навантажених або малопотужних хостах, де локальні клієнти можуть підключатися, поки прогрів запуску ще стабілізується. -- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналу в хвилинах. Задайте `0`, щоб глобально вимкнути перезапуски монітора стану. Типово: `5`. -- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого socket у хвилинах. Тримайте його більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`. -- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітора стану на канал/обліковий запис у ковзній годині. Типово: `10`. -- `channels..healthMonitor.enabled`: вимкнення перезапусків монітора стану для окремого каналу з увімкненим глобальним монітором. -- `channels..accounts..healthMonitor.enabled`: перевизначення для окремого облікового запису в багатооблікових каналах. Коли задано, має пріоритет над перевизначенням на рівні каналу. -- Локальні шляхи викликів gateway можуть використовувати `gateway.remote.*` як резерв лише тоді, коли `gateway.auth.*` не задано. -- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не розв’язано, розв’язання завершується закрито (без маскування віддаленим резервом). -- `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.nodes.pairing.autoApproveCidrs`: необов’язковий список дозволених CIDR/IP для автоматичного схвалення першого спарювання пристрою node без запитаних scopes. Вимкнено, коли не задано. Це не схвалює автоматично спарювання оператора/браузера/інтерфейсу керування/вебчату, а також не схвалює автоматично оновлення ролі, scope, metadata або публічного ключа. -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування allow/deny для оголошених команд node після спарювання та оцінки списку дозволеного платформою. Використовуйте `allowCommands`, щоб увімкнути небезпечні команди node, як-от `camera.snap`, `camera.clip` і `screen.record`; `denyCommands` вилучає команду, навіть якщо типовий дозвіл платформи або явний allow інакше включив би її. Після того як node змінює свій оголошений список команд, відхиліть і повторно схваліть спарювання цього пристрою, щоб gateway зберіг оновлений знімок команд. -- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список заборон). -- `gateway.tools.allow`: вилучити назви інструментів із типового списку HTTP-заборон. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське аварійне перевизначення через середовище процесу, яке дозволяє plaintext `ws://` до довірених IP приватної мережі; типово plaintext залишається дозволеним лише для loopback. Еквівалента в `openclaw.json` немає, а конфігурація приватної мережі браузера, як-от `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, не впливає на клієнтів Gateway WebSocket. +- `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Самі по собі вони не налаштовують автентифікацію Gateway. +- `gateway.push.apns.relay.baseUrl`: базова HTTPS-URL для зовнішнього реле APNs, яке використовують офіційні/TestFlight збірки iOS після публікації реєстрацій із підтримкою реле до Gateway. Ця URL має збігатися з URL реле, скомпільованою в збірку iOS. +- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від Gateway до реле в мілісекундах. Типово `10000`. +- Реєстрації з підтримкою реле делегуються конкретній ідентичності Gateway. Спарений застосунок iOS отримує `gateway.identity.get`, включає цю ідентичність у реєстрацію реле та пересилає Gateway грант надсилання, обмежений реєстрацією. Інший Gateway не може повторно використати цю збережену реєстрацію. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові перевизначення env для наведеної вище конфігурації реле. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: виняток лише для розробки для HTTP-URL реле loopback. Виробничі URL реле мають залишатися на HTTPS. +- `gateway.handshakeTimeoutMs`: тайм-аут попереднього до автентифікації рукостискання Gateway WebSocket у мілісекундах. Типово: `15000`. `OPENCLAW_HANDSHAKE_TIMEOUT_MS` має пріоритет, коли задано. Збільшуйте це значення на завантажених або малопотужних хостах, де локальні клієнти можуть підключатися, поки прогрів запуску ще стабілізується. +- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналу в хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски монітора стану. Типово: `5`. +- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Тримайте його більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`. +- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітора стану на канал/обліковий запис за ковзну годину. Типово: `10`. +- `channels..healthMonitor.enabled`: відмова на рівні каналу від перезапусків монітора стану з увімкненим глобальним монітором. +- `channels..accounts..healthMonitor.enabled`: перевизначення на рівні облікового запису для каналів із кількома обліковими записами. Коли задано, має пріоритет над перевизначенням на рівні каналу. +- Локальні шляхи викликів Gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано. +- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не розв’язано, розв’язання завершується закрито (без маскування віддаленим резервним варіантом). +- `trustedProxies`: IP-адреси reverse proxy, які завершують TLS або вставляють заголовки forwarded-client. Указуйте лише проксі, які ви контролюєте. Записи loopback усе ще чинні для налаштувань проксі/локального виявлення на тому самому хості (наприклад Tailscale Serve або локальний reverse proxy), але вони **не** роблять запити loopback придатними для `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback`: коли `true`, Gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. Типово `false` для fail-closed поведінки. +- `gateway.nodes.pairing.autoApproveCidrs`: необов’язковий allowlist CIDR/IP для автоматичного схвалення першого спарювання пристрою вузла без запитаних областей. Вимкнено, коли не задано. Це не схвалює автоматично спарювання оператора/браузера/Control UI/WebChat, а також не схвалює автоматично оновлення ролі, області, метаданих або відкритого ключа. +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування дозволів/заборон для оголошених команд вузлів після спарювання та оцінювання платформного allowlist. Використовуйте `allowCommands`, щоб увімкнути небезпечні команди вузлів, як-от `camera.snap`, `camera.clip` і `screen.record`; `denyCommands` вилучає команду, навіть якщо платформне типове значення або явний дозвіл інакше включали б її. Після зміни вузлом оголошеного списку команд відхиліть і повторно схваліть це спарювання пристрою, щоб Gateway зберіг оновлений знімок команд. +- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список заборони). +- `gateway.tools.allow`: вилучити назви інструментів із типового HTTP-списку заборони. -### OpenAI-сумісні кінцеві точки +### Ендпоінти, сумісні з OpenAI - 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` - Порожні списки дозволених вважаються незаданими; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` - та/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. -- Необов’язковий заголовок посилення безпеки відповіді: - - `gateway.http.securityHeaders.strictTransportSecurity` (задавайте лише для HTTPS-origin, які ви контролюєте; див. [Автентифікація через довірений proxy](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + Порожні allowlist вважаються незаданими; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` та/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. +- Необов’язковий заголовок посилення відповіді: + - `gateway.http.securityHeaders.strictTransportSecurity` (установлюйте лише для HTTPS-джерел, які ви контролюєте; див. [Автентифікація через довірений проксі](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) ### Ізоляція кількох екземплярів -Запускайте кілька gateway на одному хості з унікальними портами й каталогами стану: +Запускайте кілька Gateway на одному хості з унікальними портами та каталогами стану: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -507,10 +500,10 @@ openclaw gateway --port 19001 } ``` -- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типово: `false`). -- `autoGenerate`: автоматично генерує локальну самопідписану пару сертифікат/ключ, коли явні файли не налаштовані; лише для локального використання/розробки. -- `certPath`: шлях у файловій системі до файлу TLS-сертифіката. -- `keyPath`: шлях у файловій системі до файлу приватного TLS-ключа; тримайте права доступу обмеженими. +- `enabled`: вмикає завершення TLS на слухачі Gateway (HTTPS/WSS) (типово: `false`). +- `autoGenerate`: автоматично генерує локальну самопідписану пару сертифікат/ключ, коли явні файли не налаштовано; лише для локального використання/розробки. +- `certPath`: шлях файлової системи до файлу сертифіката TLS. +- `keyPath`: шлях файлової системи до файлу приватного ключа TLS; обмежте права доступу. - `caPath`: необов’язковий шлях до CA bundle для перевірки клієнтів або власних ланцюгів довіри. ### `gateway.reload` @@ -528,12 +521,12 @@ openclaw gateway --port 19001 ``` - `mode`: керує тим, як зміни конфігурації застосовуються під час виконання. - - `"off"`: ігнорувати live-зміни; зміни потребують явного перезапуску. - - `"restart"`: завжди перезапускати процес gateway у разі зміни конфігурації. - - `"hot"`: застосовувати зміни в процесі без перезапуску. - - `"hybrid"` (типово): спочатку спробувати гаряче перезавантаження; за потреби перейти до перезапуску. -- `debounceMs`: debounce-вікно в мс перед застосуванням змін конфігурації (невід’ємне ціле число). -- `deferralTimeoutMs`: необов’язковий максимальний час у мс для очікування операцій у процесі перед примусовим перезапуском. Не вказуйте, щоб використати типове обмежене очікування (`300000`); задайте `0`, щоб чекати безстроково й періодично записувати попередження про ще незавершені операції. + - `"off"`: ігнорувати live-редагування; зміни потребують явного перезапуску. + - `"restart"`: завжди перезапускати процес Gateway у разі зміни конфігурації. + - `"hot"`: застосовувати зміни всередині процесу без перезапуску. + - `"hybrid"` (типово): спочатку спробувати hot reload; за потреби перейти до перезапуску. +- `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число). +- `deferralTimeoutMs`: необов’язковий максимальний час у мс очікування поточних операцій перед примусовим перезапуском. Пропустіть, щоб використовувати типове обмежене очікування (`300000`); установіть `0`, щоб чекати безстроково й періодично логувати попередження про все ще незавершені операції. --- @@ -571,47 +564,47 @@ openclaw gateway --port 19001 ``` Автентифікація: `Authorization: Bearer ` або `x-openclaw-token: `. -Токени hook у рядку запиту відхиляються. +Токени хуків у query-string відхиляються. -Примітки щодо валідації та безпеки: +Примітки щодо перевірки та безпеки: - `hooks.enabled=true` вимагає непорожнього `hooks.token`. - `hooks.token` має бути **відмінним** від `gateway.auth.token`; повторне використання токена Gateway відхиляється. - `hooks.path` не може бути `/`; використовуйте окремий підшлях, наприклад `/hooks`. - Якщо `hooks.allowRequestSessionKey=true`, обмежте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). -- Якщо зіставлення або пресет використовує шаблонний `sessionKey`, задайте `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі зіставлення не потребують такого opt-in. +- Якщо зіставлення або пресет використовує шаблонний `sessionKey`, задайте `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі зіставлення не потребують такого явного ввімкнення. **Кінцеві точки:** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - `sessionKey` з payload запиту приймається лише коли `hooks.allowRequestSessionKey=true` (типово: `false`). -- `POST /hooks/` → розв'язується через `hooks.mappings` - - Значення `sessionKey` зіставлення, відрендерені шаблоном, вважаються наданими ззовні й також потребують `hooks.allowRequestSessionKey=true`. + - `sessionKey` з корисного навантаження запиту приймається лише коли `hooks.allowRequestSessionKey=true` (типово: `false`). +- `POST /hooks/` → розвʼязується через `hooks.mappings` + - Значення `sessionKey` зіставлення, відрендерені з шаблону, вважаються наданими ззовні й також вимагають `hooks.allowRequestSessionKey=true`. -- `match.path` зіставляє підшлях після `/hooks` (наприклад `/hooks/gmail` → `gmail`). -- `match.source` зіставляє поле payload для загальних шляхів. -- Шаблони на кшталт `{{messages[0].subject}}` читають із payload. -- `transform` може вказувати на JS/TS-модуль, який повертає дію hook. - - `transform.module` має бути відносним шляхом і лишатися в межах `hooks.transformsDir` (абсолютні шляхи та traversal відхиляються). - - Тримайте `hooks.transformsDir` у `~/.openclaw/hooks/transforms`; директорії Skills у workspace відхиляються. Якщо `openclaw doctor` повідомляє, що цей шлях недійсний, перемістіть модуль transform у директорію hooks transforms або приберіть `hooks.transformsDir`. -- `agentId` маршрутизує до конкретного агента; невідомі ID повертаються до типового. +- `match.path` зіставляє підшлях після `/hooks` (наприклад, `/hooks/gmail` → `gmail`). +- `match.source` зіставляє поле корисного навантаження для загальних шляхів. +- Шаблони на кшталт `{{messages[0].subject}}` читають дані з корисного навантаження. +- `transform` може вказувати на модуль JS/TS, який повертає дію hook. + - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та обхід каталогів відхиляються). + - Тримайте `hooks.transformsDir` у `~/.openclaw/hooks/transforms`; каталоги Skills робочої області відхиляються. Якщо `openclaw doctor` повідомляє, що цей шлях недійсний, перемістіть модуль transform до каталогу transforms для hooks або видаліть `hooks.transformsDir`. +- `agentId` спрямовує до конкретного агента; невідомі ідентифікатори повертаються до типового. - `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити всі, `[]` = заборонити всі). -- `defaultSessionKey`: необов'язковий фіксований ключ сесії для запусків агента hook без явного `sessionKey`. -- `allowRequestSessionKey`: дозволяє викликачам `/hooks/agent` і керованим шаблонами ключам сесії зіставлення задавати `sessionKey` (типово: `false`). -- `allowedSessionKeyPrefixes`: необов'язковий allowlist префіксів для явних значень `sessionKey` (запит + зіставлення), наприклад `["hook:"]`. Він стає обов'язковим, коли будь-яке зіставлення або пресет використовує шаблонний `sessionKey`. -- `deliver: true` надсилає фінальну відповідь у канал; `channel` типово дорівнює `last`. -- `model` перевизначає LLM для цього запуску hook (має бути дозволено, якщо задано каталог моделей). +- `defaultSessionKey`: необовʼязковий фіксований ключ сесії для запусків агента hook без явного `sessionKey`. +- `allowRequestSessionKey`: дозволяє викликачам `/hooks/agent` і ключам сесій зіставлення, керованим шаблонами, задавати `sessionKey` (типово: `false`). +- `allowedSessionKeyPrefixes`: необовʼязковий список дозволених префіксів для явних значень `sessionKey` (запит + зіставлення), наприклад `["hook:"]`. Він стає обовʼязковим, коли будь-яке зіставлення або пресет використовує шаблонний `sessionKey`. +- `deliver: true` надсилає фінальну відповідь до каналу; `channel` типово має значення `last`. +- `model` перевизначає LLM для цього запуску hook (має бути дозволено, якщо каталог моделей задано). ### Інтеграція Gmail - Вбудований пресет Gmail використовує `sessionKey: "hook:gmail:{{messages[0].id}}"`. -- Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, задайте `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes` відповідно до простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. -- Якщо вам потрібно `hooks.allowRequestSessionKey: false`, перевизначте пресет статичним `sessionKey` замість типового шаблонного значення. +- Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, задайте `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes`, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. +- Якщо вам потрібен `hooks.allowRequestSessionKey: false`, перевизначте пресет статичним `sessionKey` замість шаблонного типового значення. ```json5 { @@ -639,7 +632,7 @@ openclaw gateway --port 19001 --- -## Хост Canvas +## Хост полотна ```json5 { @@ -651,18 +644,18 @@ openclaw gateway --port 19001 } ``` -- Обслуговує доступні для редагування агентом HTML/CSS/JS і A2UI через HTTP під портом Gateway: +- Обслуговує редаговані агентом HTML/CSS/JS і A2UI через HTTP на порту Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- Лише локально: залишайте `gateway.bind: "loopback"` (типово). -- Прив'язки не до loopback: маршрути canvas потребують автентифікації Gateway (токен/пароль/trusted-proxy), як і інші HTTP-поверхні Gateway. -- Node WebViews зазвичай не надсилають заголовки автентифікації; після pairing і підключення node Gateway оголошує URL можливостей, scoped до node, для доступу до canvas/A2UI. -- URL можливостей прив'язані до активної WS-сесії node і швидко закінчуються. Fallback на основі IP не використовується. +- Лише локально: зберігайте `gateway.bind: "loopback"` (типово). +- Привʼязки не до loopback: маршрути полотна потребують автентифікації Gateway (токен/пароль/довірений проксі), так само як інші HTTP-поверхні Gateway. +- Node WebViews зазвичай не надсилають заголовки автентифікації; після того як вузол спарено й підключено, Gateway оголошує URL можливостей, обмежені вузлом, для доступу до canvas/A2UI. +- URL можливостей привʼязані до активної WS-сесії вузла та швидко спливають. Резервний варіант на основі IP не використовується. - Вставляє клієнт live-reload в обслуговуваний HTML. -- Автоматично створює стартовий `index.html`, коли порожньо. +- Автоматично створює початковий `index.html`, коли каталог порожній. - Також обслуговує A2UI за `/__openclaw__/a2ui/`. - Зміни потребують перезапуску gateway. -- Вимикайте live reload для великих директорій або помилок `EMFILE`. +- Вимкніть live reload для великих каталогів або помилок `EMFILE`. --- @@ -680,11 +673,11 @@ openclaw gateway --port 19001 } ``` -- `minimal` (типово): не включати `cliPath` + `sshPort` у TXT-записи. +- `minimal` (типово): пропускати `cliPath` + `sshPort` із записів TXT. - `full`: включати `cliPath` + `sshPort`. -- Ім'я хоста типово дорівнює системному імені хоста, коли воно є дійсною DNS-міткою, і повертається до `openclaw` інакше. Перевизначте через `OPENCLAW_MDNS_HOSTNAME`. +- Імʼя хоста типово дорівнює системному імені хоста, коли воно є дійсною міткою DNS, із поверненням до `openclaw`. Перевизначте через `OPENCLAW_MDNS_HOSTNAME`. -### Wide-area (DNS-SD) +### Широка зона (DNS-SD) ```json5 { @@ -694,7 +687,7 @@ openclaw gateway --port 19001 } ``` -Записує unicast DNS-SD-зону в `~/.openclaw/dns/`. Для виявлення між мережами поєднайте з DNS-сервером (рекомендовано CoreDNS) + Tailscale split DNS. +Записує unicast-зону DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднайте із DNS-сервером (рекомендовано CoreDNS) + Tailscale split DNS. Налаштування: `openclaw dns setup --apply`. @@ -702,7 +695,7 @@ openclaw gateway --port 19001 ## Середовище -### `env` (inline змінні середовища) +### `env` (вбудовані змінні середовища) ```json5 { @@ -719,14 +712,14 @@ openclaw gateway --port 19001 } ``` -- Inline змінні середовища застосовуються лише якщо в process env відсутній ключ. -- Файли `.env`: CWD `.env` + `~/.openclaw/.env` (жоден не перевизначає наявні змінні). -- `shellEnv`: імпортує відсутні очікувані ключі з вашого профілю login shell. -- Див. [Середовище](/uk/help/environment) для повного пріоритету. +- Вбудовані змінні середовища застосовуються лише якщо в середовищі процесу відсутній ключ. +- Файли `.env`: `.env` у CWD + `~/.openclaw/.env` (жоден не перевизначає наявні змінні). +- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell. +- Див. [Середовище](/uk/help/environment) для повного порядку пріоритетів. -### Підстановка змінних середовища +### Підставлення змінних середовища -Посилайтеся на змінні середовища в будь-якому рядку конфігурації через `${VAR_NAME}`: +Посилайтеся на змінні середовища в будь-якому рядку конфігурації за допомогою `${VAR_NAME}`: ```json5 { @@ -738,36 +731,36 @@ openclaw gateway --port 19001 - Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. - Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації. -- Екрануйте через `$${VAR}` для буквального `${VAR}`. +- Екрануйте за допомогою `$${VAR}`, щоб отримати буквальний `${VAR}`. - Працює з `$include`. --- ## Секрети -Посилання на секрети є additive: plaintext значення все ще працюють. +Посилання на секрети є додатковими: plaintext-значення все ще працюють. ### `SecretRef` -Використовуйте одну форму об'єкта: +Використовуйте одну форму обʼєкта: ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } ``` -Валідація: +Перевірка: -- шаблон `provider`: `^[a-z][a-z0-9_-]{0,63}$` -- шаблон id для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` +- Шаблон `provider`: `^[a-z][a-z0-9_-]{0,63}$` +- Шаблон id для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` - id для `source: "file"`: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`) -- шаблон id для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- id для `source: "exec"` не мають містити сегменти шляху `.` або `..`, розділені скісними рисками (наприклад `a/../b` відхиляється) +- Шаблон id для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- ids для `source: "exec"` не мають містити сегменти шляху `.` або `..`, розділені скісними рисками (наприклад, `a/../b` відхиляється) ### Підтримувана поверхня облікових даних - Канонічна матриця: [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface) - `secrets apply` націлюється на підтримувані шляхи облікових даних `openclaw.json`. -- Посилання `auth-profiles.json` включені в runtime resolution і audit coverage. +- Посилання `auth-profiles.json` включені до runtime-розвʼязання та покриття аудиту. ### Конфігурація постачальників секретів @@ -799,14 +792,14 @@ openclaw gateway --port 19001 Примітки: -- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (`id` має бути `"value"` в режимі singleValue). -- Шляхи провайдерів file і exec fail closed, коли перевірка Windows ACL недоступна. Задавайте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. -- Провайдер `exec` вимагає абсолютного шляху `command` і використовує protocol payloads через stdin/stdout. -- Типово symlink шляхи команд відхиляються. Задайте `allowSymlinkCommand: true`, щоб дозволити symlink шляхи під час валідації розв'язаного цільового шляху. -- Якщо налаштовано `trustedDirs`, перевірка trusted-dir застосовується до розв'язаного цільового шляху. +- Постачальник `file` підтримує `mode: "json"` і `mode: "singleValue"` (`id` має бути `"value"` у режимі singleValue). +- Шляхи постачальників file і exec завершуються відмовою, коли перевірка Windows ACL недоступна. Задавайте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. +- Постачальник `exec` вимагає абсолютний шлях `command` і використовує протокольні корисні навантаження через stdin/stdout. +- Типово шляхи команд-симлінків відхиляються. Задайте `allowSymlinkCommand: true`, щоб дозволити шляхи-симлінки, водночас перевіряючи розвʼязаний цільовий шлях. +- Якщо `trustedDirs` налаштовано, перевірка довіреного каталогу застосовується до розвʼязаного цільового шляху. - Дочірнє середовище `exec` типово мінімальне; передавайте потрібні змінні явно через `passEnv`. -- Посилання на секрети розв'язуються під час активації в in-memory snapshot, після чого шляхи запитів читають лише snapshot. -- Фільтрація active-surface застосовується під час активації: нерозв'язані посилання на ввімкнених поверхнях зупиняють startup/reload з помилкою, тоді як неактивні поверхні пропускаються з diagnostics. +- Посилання на секрети розвʼязуються під час активації у знімок у памʼяті, після чого шляхи запитів читають лише цей знімок. +- Фільтрація активної поверхні застосовується під час активації: нерозвʼязані посилання на ввімкнених поверхнях спричиняють збій запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. --- @@ -829,13 +822,13 @@ openclaw gateway --port 19001 ``` - Профілі для кожного агента зберігаються в `/auth-profiles.json`. -- `auth-profiles.json` підтримує refs на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних. -- Застарілі плоскі мапи `auth-profiles.json`, як-от `{ "provider": { "apiKey": "..." } }`, не є runtime-форматом; `openclaw doctor --fix` переписує їх у канонічні API-key-профілі `provider:default` із резервною копією `.legacy-flat.*.bak`. -- Профілі в OAuth-режимі (`auth.profiles..mode = "oauth"`) не підтримують облікові дані auth-profile на основі SecretRef. -- Статичні runtime облікові дані надходять з in-memory resolved snapshots; застарілі статичні записи `auth.json` очищаються, коли їх виявлено. -- Застарілі OAuth імпорти з `~/.openclaw/credentials/oauth.json`. +- `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних. +- Застарілі пласкі мапи `auth-profiles.json`, такі як `{ "provider": { "apiKey": "..." } }`, не є runtime-форматом; `openclaw doctor --fix` переписує їх у канонічні профілі API-key `provider:default` з резервною копією `.legacy-flat.*.bak`. +- Профілі OAuth-режиму (`auth.profiles..mode = "oauth"`) не підтримують облікові дані auth-profile на основі SecretRef. +- Статичні runtime-облікові дані надходять із розвʼязаних знімків у памʼяті; застарілі статичні записи `auth.json` очищуються під час виявлення. +- Застарілі OAuth імпортуються з `~/.openclaw/credentials/oauth.json`. - Див. [OAuth](/uk/concepts/oauth). -- Runtime-поведінка секретів і інструменти `audit/configure/apply`: [Керування секретами](/uk/gateway/secrets). +- Runtime-поведінка секретів та інструменти `audit/configure/apply`: [Керування секретами](/uk/gateway/secrets). ### `auth.cooldowns` @@ -857,15 +850,20 @@ openclaw gateway --port 19001 } ``` -- `billingBackoffHours`: базовий backoff у годинах, коли профіль зазнає збою через справжні помилки білінгу/недостатнього кредиту (типово: `5`). Явний текст про білінг усе ще може потрапити сюди навіть у відповідях `401`/`403`, але специфічні для провайдера текстові зіставлення залишаються обмеженими провайдером, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Повідомлення повторюваного HTTP `402` про вікно використання або ліміти витрат організації/робочого простору натомість залишаються в шляху `rate_limit`. -- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин backoff для білінгу за провайдерами. -- `billingMaxHours`: обмеження в годинах для експоненційного зростання backoff білінгу (типово: `24`). -- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для високодостовірних збоїв `auth_permanent` (типово: `10`). -- `authPermanentMaxMinutes`: обмеження в хвилинах для зростання backoff `auth_permanent` (типово: `60`). -- `failureWindowHours`: рухоме вікно в годинах, що використовується для лічильників backoff (типово: `24`). -- `overloadedProfileRotations`: максимальна кількість ротацій профілів автентифікації того самого провайдера для помилок перевантаження перед перемиканням на резервну модель (типово: `1`). Сюди потрапляють форми зайнятості провайдера, як-от `ModelNotReadyException`. +- `billingBackoffHours`: базова затримка в годинах, коли профіль зазнає невдачі через справжні + помилки billing/insufficient-credit (типово: `5`). Явний текст про billing може + все одно потрапити сюди навіть у відповідях `401`/`403`, але специфічні для провайдера + текстові зіставлювачі залишаються обмеженими провайдером, якому вони належать (наприклад OpenRouter + `Key limit exceeded`). Повторювані HTTP-повідомлення `402` про usage-window або + ліміт витрат організації/робочого простору натомість залишаються в шляху `rate_limit`. +- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин затримки billing для кожного провайдера. +- `billingMaxHours`: обмеження в годинах для експоненційного зростання затримки billing (типово: `24`). +- `authPermanentBackoffMinutes`: базова затримка в хвилинах для високовпевнених збоїв `auth_permanent` (типово: `10`). +- `authPermanentMaxMinutes`: обмеження в хвилинах для зростання затримки `auth_permanent` (типово: `60`). +- `failureWindowHours`: ковзне вікно в годинах, що використовується для лічильників затримок (типово: `24`). +- `overloadedProfileRotations`: максимальна кількість ротацій auth-профілів того самого провайдера для помилок перевантаження перед переходом до fallback моделі (типово: `1`). Сюди потрапляють форми зайнятості провайдера, як-от `ModelNotReadyException`. - `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`). -- `rateLimitedProfileRotations`: максимальна кількість ротацій профілів автентифікації того самого провайдера для помилок ліміту частоти перед перемиканням на резервну модель (типово: `1`). Цей кошик ліміту частоти включає текст у форматі провайдера, як-от `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. +- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-профілів того самого провайдера для помилок обмеження швидкості перед переходом до fallback моделі (типово: `1`). Цей кошик обмеження швидкості включає тексти у форматі провайдера, як-от `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. --- @@ -887,8 +885,8 @@ openclaw gateway --port 19001 - Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Задайте `logging.file` для стабільного шляху. - `consoleLevel` підвищується до `debug`, коли використано `--verbose`. -- `maxFileBytes`: максимальний розмір активного файла журналу в байтах перед ротацією (додатне ціле число; типово: `104857600` = 100 MB). OpenClaw зберігає до п’яти нумерованих архівів поруч з активним файлом. -- `redactSensitive` / `redactPatterns`: маскування за найкращим зусиллям для виводу консолі, файлових журналів, записів журналів OTLP і збереженого тексту транскрипту сесії. `redactSensitive: "off"` вимикає лише цю загальну політику журналів/транскриптів; поверхні безпеки UI/інструментів/діагностики все одно редагують секрети перед виведенням. +- `maxFileBytes`: максимальний розмір активного файлу журналу в байтах перед ротацією (додатне ціле число; типово: `104857600` = 100 MB). OpenClaw зберігає до п’яти пронумерованих архівів поруч з активним файлом. +- `redactSensitive` / `redactPatterns`: best-effort маскування для виводу в консоль, файлових журналів, записів журналів OTLP і збереженого тексту транскрипту сесії. `redactSensitive: "off"` вимикає лише цю загальну політику журналів/транскриптів; поверхні безпеки UI/інструментів/діагностики все одно редагують секрети перед виведенням. --- @@ -937,22 +935,22 @@ openclaw gateway --port 19001 ``` - `enabled`: головний перемикач для виводу інструментування (типово: `true`). -- `flags`: масив рядків прапорців, що вмикають цільовий вивід журналів (підтримує шаблони на кшталт `"telegram.*"` або `"*"`). -- `stuckSessionWarnMs`: поріг віку без прогресу в мс для класифікації довготривалих сесій обробки як `session.long_running`, `session.stalled` або `session.stuck`. Відповідь, інструмент, статус, блок і прогрес ACP скидають таймер; повторна діагностика `session.stuck` виконує backoff, доки стан не змінюється. -- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). Повну конфігурацію, каталог сигналів і модель приватності див. у [експорті OpenTelemetry](/uk/gateway/opentelemetry). +- `flags`: масив рядків прапорців, що вмикають цільовий вивід журналів (підтримує шаблони із символами підстановки, як-от `"telegram.*"` або `"*"`). +- `stuckSessionWarnMs`: поріг віку без прогресу в мс для класифікації довготривалих сесій обробки як `session.long_running`, `session.stalled` або `session.stuck`. Відповідь, інструмент, статус, блок і прогрес ACP скидають таймер; повторні діагностики `session.stuck` відступають із затримкою, поки стан не змінюється. +- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). Повну конфігурацію, каталог сигналів і модель приватності див. в [експорті OpenTelemetry](/uk/gateway/opentelemetry). - `otel.endpoint`: URL колектора для експорту OTel. -- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: необов’язкові OTLP-ендпоїнти для конкретних сигналів. Коли задано, вони перевизначають `otel.endpoint` лише для цього сигналу. +- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: необов’язкові OTLP-ендпоїнти, специфічні для сигналів. Коли задані, вони перевизначають `otel.endpoint` лише для цього сигналу. - `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`. - `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються із запитами експорту OTel. -- `otel.serviceName`: назва сервісу для атрибутів ресурсу. +- `otel.serviceName`: ім’я сервісу для атрибутів ресурсу. - `otel.traces` / `otel.metrics` / `otel.logs`: вмикають експорт трас, метрик або журналів. - `otel.sampleRate`: частота семплювання трас `0`–`1`. - `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в мс. -- `otel.captureContent`: явне ввімкнення захоплення сирого вмісту для атрибутів span OTEL. Типово вимкнено. Булеве `true` захоплює несистемний вміст повідомлень/інструментів; форма об’єкта дає змогу явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`. -- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: перемикач середовища для найновіших експериментальних атрибутів провайдера span GenAI. Типово spans зберігають застарілий атрибут `gen_ai.system` для сумісності; метрики GenAI використовують обмежені семантичні атрибути. -- `OPENCLAW_OTEL_PRELOADED=1`: перемикач середовища для хостів, які вже зареєстрували глобальний OpenTelemetry SDK. Тоді OpenClaw пропускає запуск/завершення SDK, що належить Plugin, зберігаючи діагностичні слухачі активними. -- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` і `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: змінні середовища для ендпоїнтів конкретних сигналів, що використовуються, коли відповідний ключ конфігурації не задано. -- `cacheTrace.enabled`: журналювати знімки трасування кешу для вбудованих запусків (типово: `false`). +- `otel.captureContent`: опціональне захоплення сирого вмісту для атрибутів span OTEL. Типово вимкнено. Boolean `true` захоплює несистемний вміст повідомлень/інструментів; форма об’єкта дає змогу явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`. +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: змінна середовища для найновіших експериментальних атрибутів провайдера span GenAI. Типово spans зберігають застарілий атрибут `gen_ai.system` для сумісності; метрики GenAI використовують обмежені семантичні атрибути. +- `OPENCLAW_OTEL_PRELOADED=1`: змінна середовища для хостів, які вже зареєстрували глобальний OpenTelemetry SDK. Тоді OpenClaw пропускає запуск/завершення SDK, що належить Plugin, зберігаючи активними діагностичні слухачі. +- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` і `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: змінні середовища ендпоїнтів, специфічні для сигналів, що використовуються, коли відповідний ключ конфігурації не задано. +- `cacheTrace.enabled`: записувати snapshots трасування кешу для вбудованих запусків (типово: `false`). - `cacheTrace.filePath`: шлях виводу для JSONL трасування кешу (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). - `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід трасування кешу (усі типово: `true`). @@ -976,11 +974,11 @@ openclaw gateway --port 19001 } ``` -- `channel`: канал випуску для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`. -- `checkOnStart`: перевіряти оновлення npm під час запуску Gateway (типово: `true`). -- `auto.enabled`: увімкнути фонове автооновлення для пакетних встановлень (типово: `false`). +- `channel`: канал релізів для npm/git-інсталяцій — `"stable"`, `"beta"` або `"dev"`. +- `checkOnStart`: перевіряти оновлення npm під час запуску gateway (типово: `true`). +- `auto.enabled`: увімкнути фонове автооновлення для пакетних інсталяцій (типово: `false`). - `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням stable-каналу (типово: `6`; макс.: `168`). -- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable-каналу в годинах (типово: `12`; макс.: `168`). +- `auto.stableJitterHours`: додаткове вікно рознесення розгортання stable-каналу в годинах (типово: `12`; макс.: `168`). - `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу в годинах (типово: `1`; макс.: `24`). --- @@ -1015,22 +1013,22 @@ openclaw gateway --port 19001 ``` - `enabled`: глобальний feature gate ACP (типово: `true`; задайте `false`, щоб приховати dispatch ACP і можливості spawn). -- `dispatch.enabled`: незалежний gate для dispatch ходу сесії ACP (типово: `true`). Задайте `false`, щоб зберегти команди ACP доступними, але заблокувати виконання. -- `backend`: стандартний ідентифікатор бекенда середовища виконання ACP (має збігатися із зареєстрованим Plugin середовища виконання ACP). - Спочатку встановіть Plugin бекенда, і якщо задано `plugins.allow`, додайте ідентифікатор Plugin бекенда (наприклад `acpx`), інакше бекенд ACP не завантажиться. -- `defaultAgent`: резервний ідентифікатор цільового агента ACP, коли spawns не вказують явну ціль. -- `allowedAgents`: allowlist ідентифікаторів агентів, дозволених для сесій середовища виконання ACP; порожній означає відсутність додаткового обмеження. +- `dispatch.enabled`: незалежний gate для dispatch ходу сесії ACP (типово: `true`). Задайте `false`, щоб залишити команди ACP доступними, але заблокувати виконання. +- `backend`: типовий id backend середовища виконання ACP (має збігатися із зареєстрованим ACP runtime Plugin). + Спершу встановіть backend Plugin, і якщо задано `plugins.allow`, включіть id backend Plugin (наприклад `acpx`), інакше ACP backend не завантажиться. +- `defaultAgent`: fallback id цільового агента ACP, коли spawn не задає явну ціль. +- `allowedAgents`: allowlist id агентів, дозволених для сесій середовища виконання ACP; порожній означає відсутність додаткових обмежень. - `maxConcurrentSessions`: максимальна кількість одночасно активних сесій ACP. -- `stream.coalesceIdleMs`: вікно idle flush у мс для потокового тексту. -- `stream.maxChunkChars`: максимальний розмір фрагмента перед поділом проєкції потокового блока. +- `stream.coalesceIdleMs`: idle-вікно скидання в мс для потокового тексту. +- `stream.maxChunkChars`: максимальний розмір фрагмента перед розбиттям проекції потокового блока. - `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструментів за хід (типово: `true`). -- `stream.deliveryMode`: `"live"` транслює інкрементально; `"final_only"` буферизує до термінальних подій ходу. +- `stream.deliveryMode`: `"live"` передає потік інкрементально; `"final_only"` буферизує до термінальних подій ходу. - `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (типово: `"paragraph"`). -- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, що проєктується за хід ACP. +- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, проєктована за хід ACP. - `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлення ACP. -- `stream.tagVisibility`: запис імен тегів у булеві перевизначення видимості для потокових подій. -- `runtime.ttlMinutes`: idle TTL у хвилинах для працівників сесії ACP перед тим, як вони стають придатними для очищення. -- `runtime.installCommand`: необов’язкова команда встановлення для запуску під час bootstrap середовища виконання ACP. +- `stream.tagVisibility`: запис імен тегів до boolean-перевизначень видимості для потокових подій. +- `runtime.ttlMinutes`: idle TTL у хвилинах для workers сесій ACP перед тим, як вони стануть придатними до очищення. +- `runtime.installCommand`: необов’язкова команда встановлення, яку слід виконати під час bootstrap середовища виконання ACP. --- @@ -1046,11 +1044,11 @@ openclaw gateway --port 19001 } ``` -- `cli.banner.taglineMode` керує стилем tagline банера: - - `"random"` (типово): змінні смішні/сезонні taglines. - - `"default"`: фіксована нейтральна tagline (`All your chats, one OpenClaw.`). - - `"off"`: без тексту tagline (заголовок/версія банера все одно показуються). -- Щоб приховати весь банер (а не лише taglines), задайте env `OPENCLAW_HIDE_BANNER=1`. +- `cli.banner.taglineMode` керує стилем слогана банера: + - `"random"` (типово): ротаційні кумедні/сезонні слогани. + - `"default"`: фіксований нейтральний слоган (`All your chats, one OpenClaw.`). + - `"off"`: без тексту слогана (назва/версія банера все одно показуються). +- Щоб приховати весь банер (а не лише слогани), задайте env `OPENCLAW_HIDE_BANNER=1`. --- @@ -1074,15 +1072,15 @@ openclaw gateway --port 19001 ## Ідентичність -Див. поля ідентичності `agents.list` у [стандартних налаштуваннях агента](/uk/gateway/config-agents#agent-defaults). +Див. поля ідентичності `agents.list` у [типових значеннях агента](/uk/gateway/config-agents#agent-defaults). --- -## Міст (застарілий, вилучено) +## Міст (застарілий, вилучений) -Поточні збірки більше не містять TCP-міст. Nodes підключаються через Gateway WebSocket. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація не проходить, доки їх не буде вилучено; `openclaw doctor --fix` може прибрати невідомі ключі). +Поточні збірки більше не включають TCP-міст. Вузли підключаються через WebSocket Gateway. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде вилучено; `openclaw doctor --fix` може прибрати невідомі ключі). - + ```json { @@ -1120,11 +1118,11 @@ openclaw gateway --port 19001 } ``` -- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків cron перед видаленням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів cron. Типово: `24h`; задайте `false`, щоб вимкнути. -- `runLog.maxBytes`: максимальний розмір файла журналу на запуск (`cron/runs/.jsonl`) перед обрізанням. Типово: `2_000_000` байтів. +- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків cron перед обрізанням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів cron. Типово: `24h`; задайте `false`, щоб вимкнути. +- `runLog.maxBytes`: максимальний розмір для кожного файла журналу запуску (`cron/runs/.jsonl`) перед обрізанням. Типово: `2_000_000` байтів. - `runLog.keepLines`: найновіші рядки, що зберігаються, коли запускається обрізання журналу запуску. Типово: `2000`. -- `webhookToken`: bearer-токен, що використовується для доставки cron webhook POST (`delivery.mode = "webhook"`); якщо пропущено, заголовок автентифікації не надсилається. -- `webhook`: застарілий резервний URL webhook (http/https), що використовується лише для збережених завдань, які все ще мають `notify: true`. +- `webhookToken`: bearer-токен, що використовується для доставки cron Webhook POST (`delivery.mode = "webhook"`); якщо не вказано, заголовок auth не надсилається. +- `webhook`: застарілий fallback URL webhook (http/https), що використовується лише для збережених завдань, які все ще мають `notify: true`. ### `cron.retry` @@ -1141,10 +1139,10 @@ openclaw gateway --port 19001 ``` - `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань у разі тимчасових помилок (за замовчуванням: `3`; діапазон: `0`–`10`). -- `backoffMs`: масив затримок відступу в мс для кожної повторної спроби (за замовчуванням: `[30000, 60000, 300000]`; 1–10 записів). -- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Опустіть, щоб повторювати всі тимчасові типи. +- `backoffMs`: масив затримок повторних спроб у мс для кожної спроби (за замовчуванням: `[30000, 60000, 300000]`; 1–10 записів). +- `retryOn`: типи помилок, що запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Не вказуйте, щоб повторювати всі тимчасові типи. -Застосовується лише до одноразових завдань cron. Повторювані завдання використовують окрему обробку збоїв. +Застосовується лише до одноразових cron-завдань. Повторювані завдання використовують окрему обробку збоїв. ### `cron.failureAlert` @@ -1163,12 +1161,12 @@ openclaw gateway --port 19001 } ``` -- `enabled`: увімкнути сповіщення про збої для завдань cron (за замовчуванням: `false`). -- `after`: кількість послідовних збоїв до спрацювання сповіщення (додатне ціле число, мін.: `1`). +- `enabled`: увімкнути сповіщення про збої для cron-завдань (за замовчуванням: `false`). +- `after`: кількість послідовних збоїв перед надсиланням сповіщення (додатне ціле число, мін.: `1`). - `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число). -- `includeSkipped`: враховувати послідовні пропущені запуски в порозі сповіщення (за замовчуванням: `false`). Пропущені запуски відстежуються окремо й не впливають на відступ після помилок виконання. -- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` публікує в налаштований webhook. -- `accountId`: необов’язковий ідентифікатор облікового запису або каналу для обмеження області доставки сповіщення. +- `includeSkipped`: зараховувати послідовні пропущені запуски до порога сповіщення (за замовчуванням: `false`). Пропущені запуски відстежуються окремо й не впливають на затримку повторів після помилок виконання. +- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` публікує в налаштований Webhook. +- `accountId`: необов’язковий ідентифікатор облікового запису або каналу для обмеження області доставки сповіщень. ### `cron.failureDestination` @@ -1186,26 +1184,26 @@ openclaw gateway --port 19001 ``` - Типове призначення для сповіщень про збої cron в усіх завданнях. -- `mode`: `"announce"` або `"webhook"`; за замовчуванням `"announce"`, коли є достатньо даних цілі. +- `mode`: `"announce"` або `"webhook"`; за замовчуванням використовується `"announce"`, коли наявно достатньо цільових даних. - `channel`: перевизначення каналу для доставки announce. `"last"` повторно використовує останній відомий канал доставки. -- `to`: явна ціль announce або URL webhook. Обов’язково для режиму webhook. +- `to`: явна ціль announce або URL Webhook. Обов’язково для режиму Webhook. - `accountId`: необов’язкове перевизначення облікового запису для доставки. -- `delivery.failureDestination` на рівні завдання перевизначає це глобальне значення за замовчуванням. -- Коли ні глобальне, ні задане на рівні завдання призначення збою не встановлено, завдання, які вже доставляють через `announce`, у разі збою повертаються до цієї основної цілі announce. -- `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо основний `delivery.mode` завдання не дорівнює `"webhook"`. +- `delivery.failureDestination` на рівні завдання перевизначає це глобальне типове значення. +- Коли ні глобальне, ні рівня завдання призначення збою не задано, завдання, які вже доставляють через `announce`, у разі збою повертаються до цієї основної цілі announce. +- `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо основний `delivery.mode` завдання не є `"webhook"`. -Див. [Завдання Cron](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [фонові завдання](/uk/automation/tasks). +Див. [Cron-завдання](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [фонові завдання](/uk/automation/tasks). --- -## Змінні шаблону медіамоделі +## Змінні шаблонів медіамоделі Заповнювачі шаблону, що розгортаються в `tools.media.models[].args`: | Змінна | Опис | | ------------------ | ------------------------------------------------- | | `{{Body}}` | Повний текст вхідного повідомлення | -| `{{RawBody}}` | Необроблений текст (без обгорток історії/відправника) | +| `{{RawBody}}` | Сирий текст (без обгорток історії/відправника) | | `{{BodyStripped}}` | Текст із вилученими згадками групи | | `{{From}}` | Ідентифікатор відправника | | `{{To}}` | Ідентифікатор призначення | @@ -1213,11 +1211,11 @@ openclaw gateway --port 19001 | `{{SessionId}}` | UUID поточної сесії | | `{{IsNewSession}}` | `"true"`, коли створено нову сесію | | `{{MediaUrl}}` | Псевдо-URL вхідного медіа | -| `{{MediaPath}}` | Локальний шлях до медіа | +| `{{MediaPath}}` | Локальний шлях медіа | | `{{MediaType}}` | Тип медіа (зображення/аудіо/документ/…) | | `{{Transcript}}` | Транскрипт аудіо | -| `{{Prompt}}` | Визначений медіапромпт для записів CLI | -| `{{MaxChars}}` | Визначена максимальна кількість символів виводу для записів CLI | +| `{{Prompt}}` | Розв’язаний медіапромпт для записів CLI | +| `{{MaxChars}}` | Розв’язана максимальна кількість символів виводу для записів CLI | | `{{ChatType}}` | `"direct"` або `"group"` | | `{{GroupSubject}}` | Тема групи (за можливості) | | `{{GroupMembers}}` | Попередній перегляд учасників групи (за можливості) | @@ -1245,17 +1243,17 @@ openclaw gateway --port 19001 **Поведінка злиття:** - Один файл: замінює об’єкт, що його містить. -- Масив файлів: глибоко зливається по порядку (пізніші значення перевизначають попередні). +- Масив файлів: глибоко зливається за порядком (пізніші перевизначають попередні). - Сусідні ключі: зливаються після включень (перевизначають включені значення). - Вкладені включення: до 10 рівнів углиб. -- Шляхи: розв’язуються відносно файлу, що виконує включення, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` файлу `openclaw.json`). Абсолютні форми або форми з `../` дозволені лише тоді, коли вони все одно розв’язуються в цих межах. -- Записи, керовані OpenClaw, які змінюють лише один розділ верхнього рівня, підкріплений включенням одного файлу, записуються наскрізно в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін. -- Кореневі включення, масиви включень і включення із сусідніми перевизначеннями є лише для читання для записів, керованих OpenClaw; такі записи завершуються закритою помилкою замість вирівнювання конфігурації. +- Шляхи: розв’язуються відносно файлу, що виконує включення, але мають залишатися всередині каталогу конфігурації верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми/форми з `../` дозволені лише тоді, коли вони все одно розв’язуються всередині цієї межі. +- Записи, якими володіє OpenClaw і які змінюють лише один розділ верхнього рівня, підкріплений однофайловим включенням, записуються напряму до цього включеного файлу. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін. +- Кореневі включення, масиви включень і включення із сусідніми перевизначеннями є лише для читання для записів, якими володіє OpenClaw; такі записи завершуються закрито, а не сплощують конфігурацію. - Помилки: зрозумілі повідомлення для відсутніх файлів, помилок розбору та циклічних включень. --- -_Пов’язане: [Конфігурація](/uk/gateway/configuration) · [Приклади конфігурації](/uk/gateway/configuration-examples) · [Діагностика](/uk/gateway/doctor)_ +_Пов’язане: [Конфігурація](/uk/gateway/configuration) · [Приклади конфігурації](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_ ## Пов’язане diff --git a/docs/uk/reference/token-use.md b/docs/uk/reference/token-use.md index 4d4160038..4cd5d183a 100644 --- a/docs/uk/reference/token-use.md +++ b/docs/uk/reference/token-use.md @@ -5,10 +5,10 @@ read_when: summary: Як OpenClaw формує контекст промпта та звітує про використання токенів і витрати title: Використання токенів і витрати x-i18n: - generated_at: "2026-04-28T11:25:26Z" + generated_at: "2026-05-02T10:18:08Z" model: gpt-5.5 provider: openai - source_hash: a3807ccae3313a731c2673edace8a5b37dc22259d436a67b4d787e45682dad3c + source_hash: 648c1624aa81e896dacdbdc10784ca10fba2e43114823903da6455e7de512ace source_path: reference/token-use.md workflow: 16 --- @@ -20,103 +20,103 @@ OpenClaw відстежує **токени**, а не символи. Токен ## Як будується системний промпт -OpenClaw збирає власний системний промпт під час кожного запуску. Він містить: +OpenClaw збирає власний системний промпт під час кожного запуску. Він включає: - Список інструментів + короткі описи - Список Skills (лише метадані; інструкції завантажуються на вимогу через `read`). - Компактний блок Skills обмежується `skills.limits.maxSkillsPromptChars`, - з необов’язковим перевизначенням для окремого агента в + Компактний блок skills обмежується `skills.limits.maxSkillsPromptChars`, + з необов'язковим перевизначенням для окремого агента в `agents.list[].skillsLimits.maxSkillsPromptChars`. - Інструкції для самооновлення -- Робочу область + bootstrap-файли (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` для нових запусків, плюс `MEMORY.md`, якщо він присутній). Кореневий `memory.md` у нижньому регістрі не інжектиться; це застарілий вхід для відновлення через `openclaw doctor --fix`, коли він поєднаний із `MEMORY.md`. Великі файли обрізаються за `agents.defaults.bootstrapMaxChars` (типово: 12000), а загальна bootstrap-ін’єкція обмежується `agents.defaults.bootstrapTotalMaxChars` (типово: 60000). Щоденні файли `memory/*.md` не є частиною звичайного bootstrap-промпта; у звичайних ходах вони залишаються доступними на вимогу через інструменти пам’яті, але модельні запуски скидання/старту можуть додати на початок одноразовий блок стартового контексту з нещодавньою щоденною пам’яттю для цього першого ходу. Команди чату `/new` і `/reset` без аргументів підтверджуються без виклику моделі. Стартовий вступ контролюється `agents.defaults.startupContext`. +- Робочий простір + bootstrap-файли (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, коли новий, плюс `MEMORY.md`, коли наявний). Кореневий `memory.md` у нижньому регістрі не ін'єктується; це застарілий вхід для виправлення через `openclaw doctor --fix`, коли він поєднаний із `MEMORY.md`. Великі файли обрізаються за `agents.defaults.bootstrapMaxChars` (типово: 12000), а загальна bootstrap-ін'єкція обмежується `agents.defaults.bootstrapTotalMaxChars` (типово: 60000). Щоденні файли `memory/*.md` не є частиною звичайного bootstrap-промпта; у звичайних ходах вони залишаються доступними на вимогу через інструменти пам'яті, але модельні запуски reset/startup можуть додати перед першим ходом одноразовий блок startup-контексту з нещодавньою щоденною пам'яттю. Прості команди чату `/new` і `/reset` підтверджуються без виклику моделі. Startup-прелюдія керується `agents.defaults.startupContext`. - Час (UTC + часовий пояс користувача) -- Теги відповіді + поведінку Heartbeat -- Метадані середовища виконання (хост/ОС/модель/мислення) +- Теги відповіді + поведінка Heartbeat +- Метадані runtime (хост/ОС/модель/мислення) Повний розбір див. у [Системний промпт](/uk/concepts/system-prompt). ## Що враховується у вікні контексту -Усе, що отримує модель, враховується в ліміті контексту: +Усе, що отримує модель, зараховується до ліміту контексту: - Системний промпт (усі розділи, перелічені вище) - Історія розмови (повідомлення користувача + асистента) - Виклики інструментів і результати інструментів - Вкладення/транскрипти (зображення, аудіо, файли) -- Підсумки Compaction та артефакти обрізання -- Обгортки провайдера або заголовки безпеки (не видимі, але все одно враховуються) +- Підсумки Compaction і артефакти обрізання +- Обгортки провайдера або заголовки безпеки (невидимі, але все одно враховуються) -Деякі поверхні з високим навантаженням середовища виконання мають власні явні обмеження: +Деякі runtime-інтенсивні поверхні мають власні явні обмеження: - `agents.defaults.contextLimits.memoryGetMaxChars` - `agents.defaults.contextLimits.memoryGetDefaultLines` - `agents.defaults.contextLimits.toolResultMaxChars` - `agents.defaults.contextLimits.postCompactionMaxChars` -Перевизначення для окремих агентів розташовані в `agents.list[].contextLimits`. Ці налаштування -призначені для обмежених фрагментів середовища виконання та інжектованих блоків, якими володіє середовище виконання. Вони -відокремлені від bootstrap-лімітів, лімітів стартового контексту та лімітів промпта Skills. +Перевизначення для окремого агента розміщені під `agents.list[].contextLimits`. Ці перемикачі +призначені для обмежених runtime-фрагментів і runtime-власних ін'єктованих блоків. Вони +відокремлені від bootstrap-лімітів, лімітів startup-контексту та лімітів промпта Skills. -Для зображень OpenClaw зменшує масштаб payload-зображень транскриптів/інструментів перед викликами провайдера. -Налаштовуйте це через `agents.defaults.imageMaxDimensionPx` (типово: `1200`): +Для зображень OpenClaw зменшує масштаб payload-ів зображень із транскриптів/інструментів перед викликами провайдера. +Використовуйте `agents.defaults.imageMaxDimensionPx` (типово: `1200`) для налаштування цього: - Нижчі значення зазвичай зменшують використання vision-токенів і розмір payload. - Вищі значення зберігають більше візуальних деталей для OCR/UI-насичених знімків екрана. -Для практичного розбору (за кожним інжектованим файлом, інструментами, Skills і розміром системного промпта) використовуйте `/context list` або `/context detail`. Див. [Контекст](/uk/concepts/context). +Для практичного розбору (за кожним ін'єктованим файлом, інструментами, Skills і розміром системного промпта) використовуйте `/context list` або `/context detail`. Див. [Контекст](/uk/concepts/context). ## Як переглянути поточне використання токенів Використовуйте це в чаті: -- `/status` → **статусна картка з великою кількістю емодзі** з моделлю сесії, використанням контексту, - токенами входу/виходу останньої відповіді та **орієнтовною вартістю** (лише для API-ключа). -- `/usage off|tokens|full` → додає **footer використання для кожної відповіді** до кожної відповіді. - - Зберігається для сесії (як `responseUsage`). +- `/status` → **картка стану з багатьма емодзі** з моделлю сеансу, використанням контексту, + токенами введення/виведення останньої відповіді та **орієнтовною вартістю** (лише API-ключ). +- `/usage off|tokens|full` → додає **футер використання для кожної відповіді** до кожної відповіді. + - Зберігається для сеансу (зберігається як `responseUsage`). - OAuth-автентифікація **приховує вартість** (лише токени). -- `/usage cost` → показує локальний підсумок витрат із журналів сесій OpenClaw. +- `/usage cost` → показує локальний підсумок вартості з журналів сеансу OpenClaw. Інші поверхні: - **TUI/Web TUI:** підтримуються `/status` + `/usage`. - **CLI:** `openclaw status --usage` і `openclaw channels list` показують - нормалізовані вікна квот провайдера (`X% left`, а не витрати на окрему відповідь). - Поточні провайдери вікон використання: Anthropic, GitHub Copilot, Gemini CLI, + нормалізовані вікна квот провайдера (`X% left`, а не вартість за відповідь). + Поточні провайдери з вікнами використання: Anthropic, GitHub Copilot, Gemini CLI, OpenAI Codex, MiniMax, Xiaomi та z.ai. -Поверхні використання нормалізують поширені нативні псевдоніми полів провайдера перед відображенням. -Для трафіку Responses сімейства OpenAI це включає як `input_tokens` / -`output_tokens`, так і `prompt_tokens` / `completion_tokens`, тому специфічні для транспорту -назви полів не змінюють `/status`, `/usage` або підсумки сесії. -JSON-використання Gemini CLI також нормалізується: текст відповіді береться з `response`, а -`stats.cached` мапиться на `cacheRead` з використанням `stats.input_tokens - stats.cached`, -коли CLI не містить явного поля `stats.input`. +Поверхні використання нормалізують поширені власні псевдоніми полів провайдерів перед показом. +Для трафіку Responses сімейства OpenAI це включає і `input_tokens` / +`output_tokens`, і `prompt_tokens` / `completion_tokens`, тому назви полів, специфічні для транспорту, +не змінюють `/status`, `/usage` або підсумки сеансу. +Використання Gemini CLI JSON також нормалізується: текст відповіді береться з `response`, а +`stats.cached` зіставляється з `cacheRead`, використовуючи `stats.input_tokens - stats.cached`, +коли CLI пропускає явне поле `stats.input`. Для нативного трафіку Responses сімейства OpenAI псевдоніми використання WebSocket/SSE -нормалізуються так само, а підсумки fallback-яться до нормалізованих входу + виходу, коли +нормалізуються так само, а підсумки повертаються до нормалізованого введення + виведення, коли `total_tokens` відсутній або дорівнює `0`. -Коли поточний знімок сесії розріджений, `/status` і `session_status` також можуть -відновлювати лічильники токенів/кешу та мітку активної моделі середовища виконання з -найновішого журналу використання транскрипта. Наявні ненульові live-значення все одно мають -пріоритет над fallback-значеннями транскрипта, а більші підсумки транскрипта, орієнтовані на промпт, -можуть перемагати, коли збережені підсумки відсутні або менші. -Автентифікація використання для вікон квот провайдера береться зі спеціальних hook-ів провайдера, коли -вони доступні; інакше OpenClaw fallback-иться до відповідних облікових даних OAuth/API-ключа -з профілів автентифікації, env або конфігурації. -Записи транскрипта асистента зберігають ту саму нормалізовану форму використання, включно з -`usage.cost`, коли для активної моделі налаштовано ціни, а провайдер -повертає метадані використання. Це дає `/usage cost` і статусу сесії на основі транскрипта -стабільне джерело навіть після зникнення live-стану середовища виконання. +Коли поточний знімок сеансу розріджений, `/status` і `session_status` також можуть +відновлювати лічильники токенів/кешу та активну мітку runtime-моделі з +найновішого журналу використання транскрипту. Наявні ненульові live-значення все одно мають +пріоритет над fallback-значеннями транскрипту, а більші промпт-орієнтовані +підсумки транскрипту можуть перемагати, коли збережені підсумки відсутні або менші. +Авторизація використання для вікон квот провайдера береться з провайдер-специфічних хуків, коли +вони доступні; інакше OpenClaw повертається до відповідних облікових даних OAuth/API-ключа +з auth-профілів, env або конфігурації. +Записи транскрипту асистента зберігають ту саму нормалізовану форму використання, включно з +`usage.cost`, коли активна модель має налаштовані ціни, а провайдер +повертає метадані використання. Це дає `/usage cost` і session status на основі транскрипту +стабільне джерело навіть після зникнення live-стану runtime. OpenClaw тримає облік використання провайдера окремо від поточного знімка контексту. -`usage.total` провайдера може включати кешований вхід, вихід і кілька -модельних викликів циклу інструментів, тому це корисно для витрат і телеметрії, але може завищувати -live-вікно контексту. Відображення контексту й діагностика використовують найновіший знімок промпта +`usage.total` провайдера може включати кешоване введення, виведення та кілька +модельних викликів у циклі інструментів, тому це корисно для вартості й телеметрії, але може завищувати +живе вікно контексту. Відображення контексту та діагностика використовують найновіший знімок промпта (`promptTokens` або останній виклик моделі, коли знімок промпта недоступний) для `context.used`. -## Оцінювання витрат (коли показується) +## Оцінка вартості (коли показується) -Витрати оцінюються з конфігурації цін вашої моделі: +Вартість оцінюється з конфігурації цін вашої моделі: ``` models.providers..models[].cost @@ -126,36 +126,37 @@ models.providers..models[].cost `cacheWrite`. Якщо ціни відсутні, OpenClaw показує лише токени. OAuth-токени ніколи не показують вартість у доларах. -Запуск Gateway також виконує необов’язковий фоновий bootstrap цін для -налаштованих посилань на моделі, які ще не мають локальних цін. Цей bootstrap -отримує віддалені каталоги цін OpenRouter і LiteLLM. Установіть -`models.pricing.enabled: false`, щоб пропустити ці стартові завантаження каталогів в офлайн -або обмежених мережах; явні записи `models.providers.*.models[].cost` -і далі керують локальними оцінками витрат. +Після того як sidecars і канали доходять до готового шляху Gateway, OpenClaw запускає +необов'язковий фоновий pricing bootstrap для налаштованих посилань на моделі, які ще +не мають локальних цін. Цей bootstrap отримує віддалені каталоги цін OpenRouter і LiteLLM. +Встановіть `models.pricing.enabled: false`, щоб пропустити ці отримання каталогів +в офлайн- або обмежених мережах; явні записи +`models.providers.*.models[].cost` і далі керують локальними +оцінками вартості. -## Cache TTL і вплив обрізання +## TTL кешу та вплив обрізання -Кешування промптів провайдера застосовується лише в межах вікна cache TTL. OpenClaw може -необов’язково запускати **обрізання cache-ttl**: він обрізає сесію після завершення cache TTL, -а потім скидає вікно кешу, щоб наступні запити могли повторно використовувати -свіжокешований контекст замість повторного кешування всієї історії. Це знижує -витрати на записи в кеш, коли сесія простоює довше за TTL. +Кешування промптів провайдера застосовується лише в межах вікна TTL кешу. OpenClaw може +необов'язково запускати **cache-ttl pruning**: він обрізає сеанс після завершення TTL кешу, +а потім скидає вікно кешу, щоб наступні запити могли повторно використати +щойно кешований контекст замість повторного кешування всієї історії. Це знижує +витрати на запис кешу, коли сеанс простоює довше за TTL. -Налаштуйте це в [Конфігурація Gateway](/uk/gateway/configuration) і перегляньте -деталі поведінки в [Обрізання сесії](/uk/concepts/session-pruning). +Налаштуйте це в [конфігурації Gateway](/uk/gateway/configuration) і див. подробиці +поведінки в [Обрізання сеансу](/uk/concepts/session-pruning). -Heartbeat може тримати кеш **теплим** під час перерв простою. Якщо TTL кешу вашої моделі -становить `1h`, встановлення інтервалу Heartbeat трохи меншим за нього (наприклад, `55m`) може уникнути -повторного кешування повного промпта, зменшуючи витрати на записи в кеш. +Heartbeat може підтримувати кеш **теплим** під час періодів простою. Якщо TTL кешу вашої моделі +становить `1h`, налаштування інтервалу Heartbeat трохи менше за це (наприклад, `55m`) може уникнути +повторного кешування всього промпта, зменшуючи витрати на запис кешу. -У налаштуваннях із кількома агентами ви можете зберігати одну спільну конфігурацію моделі й налаштовувати поведінку кешу +У налаштуваннях з кількома агентами можна тримати одну спільну конфігурацію моделі та налаштовувати поведінку кешу для кожного агента через `agents.list[].params.cacheRetention`. -Повний покроковий довідник щодо кожного перемикача див. у [Кешування промптів](/uk/reference/prompt-caching). +Повний покроковий довідник за кожним перемикачем див. у [Кешування промптів](/uk/reference/prompt-caching). -Для цін Anthropic API читання з кешу значно дешевші за вхідні -токени, тоді як записи в кеш тарифікуються з вищим множником. Найновіші ставки й TTL-множники див. у цінах Anthropic -на кешування промптів: +Для цін Anthropic API читання кешу значно дешевше за вхідні +токени, а записи кешу виставляються з вищим множником. Актуальні тарифи та множники TTL див. у цінах Anthropic +для кешування промптів: [https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching) ### Приклад: підтримувати 1h кеш теплим за допомогою Heartbeat @@ -194,12 +195,12 @@ agents: cacheRetention: "none" # avoid cache writes for bursty notifications ``` -`agents.list[].params` зливається поверх `params` вибраної моделі, тож ви можете +`agents.list[].params` об'єднується поверх `params` вибраної моделі, тож ви можете перевизначити лише `cacheRetention` і успадкувати інші типові значення моделі без змін. ### Приклад: увімкнути beta-заголовок Anthropic 1M context -Вікно контексту Anthropic 1M наразі обмежене beta-доступом. OpenClaw може інжектувати +Вікно контексту Anthropic 1M наразі обмежене beta-доступом. OpenClaw може ін'єктувати потрібне значення `anthropic-beta`, коли ви вмикаєте `context1m` на підтримуваних моделях Opus або Sonnet. @@ -212,28 +213,28 @@ agents: context1m: true ``` -Це мапиться на beta-заголовок Anthropic `context-1m-2025-08-07`. +Це зіставляється з beta-заголовком Anthropic `context-1m-2025-08-07`. -Це застосовується лише коли `context1m: true` встановлено в записі цієї моделі. +Це застосовується лише тоді, коли `context1m: true` встановлено в цьому записі моделі. Вимога: облікові дані мають мати право на використання довгого контексту. Якщо ні, -Anthropic відповість помилкою обмеження швидкості на боці провайдера для цього запиту. +Anthropic відповідає помилкою обмеження швидкості з боку провайдера для цього запиту. -Якщо ви автентифікуєте Anthropic за допомогою OAuth/підпискових токенів (`sk-ant-oat-*`), -OpenClaw пропускає beta-заголовок `context-1m-*`, тому що Anthropic наразі -відхиляє таку комбінацію з HTTP 401. +Якщо ви автентифікуєте Anthropic за допомогою OAuth/subscription-токенів (`sk-ant-oat-*`), +OpenClaw пропускає beta-заголовок `context-1m-*`, оскільки Anthropic наразі +відхиляє цю комбінацію з HTTP 401. -## Поради щодо зменшення токенового навантаження +## Поради для зменшення тиску токенів -- Використовуйте `/compact`, щоб підсумовувати довгі сесії. -- Обрізайте великі виводи інструментів у своїх workflows. -- Зменшуйте `agents.defaults.imageMaxDimensionPx` для сесій із великою кількістю знімків екрана. -- Тримайте описи Skills короткими (список Skills інжектується в промпт). +- Використовуйте `/compact`, щоб підсумовувати довгі сеанси. +- Обрізайте великі виведення інструментів у своїх робочих процесах. +- Зменшуйте `agents.defaults.imageMaxDimensionPx` для сеансів із великою кількістю знімків екрана. +- Тримайте описи skills короткими (список skills ін'єктується в промпт). - Надавайте перевагу меншим моделям для багатослівної дослідницької роботи. -Точну формулу накладних витрат списку Skills див. у [Skills](/uk/tools/skills). +Точну формулу накладних витрат списку skills див. у [Skills](/uk/tools/skills). -## Пов’язане +## Пов'язане - [Використання API та витрати](/uk/reference/api-usage-costs) - [Кешування промптів](/uk/reference/prompt-caching)