diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index 048295012..20f4a286d 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -2,72 +2,72 @@ read_when: - Вам потрібна точна семантика конфігурації на рівні полів або значення за замовчуванням - Ви перевіряєте блоки конфігурації каналу, моделі, Gateway або інструмента -summary: Довідник конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем +summary: Довідник конфігурації Gateway для основних ключів OpenClaw, стандартних значень і посилань на спеціалізовані довідники підсистем title: Довідник із конфігурації x-i18n: - generated_at: "2026-05-03T18:20:31Z" + generated_at: "2026-05-04T22:54:31Z" model: gpt-5.5 provider: openai - source_hash: 52fa15e85a41ed5ed39102fb641bd33f0aec2e8f244c9d7b3d12b3a1b6dc62a9 + source_hash: 82164a3ea7592f667573b643ee9e0ec840b9b622c9d86c382a3feaf192e75684 source_path: gateway/configuration-reference.md workflow: 16 --- Довідник основної конфігурації для `~/.openclaw/openclaw.json`. Огляд, орієнтований на завдання, див. у [Конфігурація](/uk/gateway/configuration). -Охоплює основні поверхні конфігурації OpenClaw і посилається на окремі глибші довідники, коли підсистема має власну довідкову сторінку. Каталоги команд, що належать каналам і Plugin, а також глибокі параметри пам’яті/QMD розміщені на власних сторінках, а не на цій. +Охоплює основні поверхні конфігурації OpenClaw і посилається назовні, коли підсистема має власний детальніший довідник. Каталоги команд, що належать каналам і plugin, а також глибокі налаштування пам’яті/QMD розміщені на власних сторінках, а не на цій. Джерело істини в коді: -- `openclaw config schema` виводить актуальну JSON Schema, що використовується для валідації та Control UI, з об’єднаними метаданими вбудованих/Plugin/каналів, коли вони доступні +- `openclaw config schema` виводить актуальну JSON Schema, що використовується для валідації та Control UI, з об’єднаними метаданими bundled/plugin/каналів, коли вони доступні - `config.schema.lookup` повертає один вузол схеми, обмежений шляхом, для інструментів деталізації - `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш документації конфігурації відносно поточної поверхні схеми Шлях пошуку агента: використовуйте дію інструмента `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 для поверхонь команд, специфічних для каналів +- [Slash-команди](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд +- сторінки відповідних каналів/plugin для специфічних для каналів поверхонь команд -Формат конфігурації — **JSON5** (дозволено коментарі та кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні стандартні значення, якщо їх пропущено. +Формат конфігурації — **JSON5** (дозволені коментарі + завершальні коми). Усі поля необов’язкові — OpenClaw використовує безпечні стандартні значення, коли їх пропущено. --- ## Канали -Ключі конфігурації для окремих каналів перенесено на спеціальну сторінку — див. +Ключі конфігурації для окремих каналів перенесено на окрему сторінку — див. [Конфігурація — канали](/uk/gateway/config-channels) для `channels.*`, -зокрема Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та інших -bundled каналів (автентифікація, контроль доступу, кілька облікових записів, обмеження за згадками). +включно зі Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та іншими +bundled каналами (автентифікація, контроль доступу, кілька облікових записів, обмеження згадок). -## Стандартні значення агентів, кілька агентів, сесії та повідомлення +## Стандартні значення агента, багато агентів, сесії та повідомлення -Перенесено на спеціальну сторінку — див. +Перенесено на окрему сторінку — див. [Конфігурація — агенти](/uk/gateway/config-agents) для: - `agents.defaults.*` (робоча область, модель, мислення, heartbeat, пам’ять, медіа, skills, sandbox) - `multiAgent.*` (маршрутизація та прив’язки для кількох агентів) -- `session.*` (життєвий цикл сесії, compaction, pruning) +- `session.*` (життєвий цикл сесії, compaction, обрізання) - `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.silenceTimeoutMs`: коли не задано, Talk зберігає стандартне для платформи вікно паузи перед надсиланням транскрипту (`700 ms on macOS and Android, 900 ms on iOS`) -## Інструменти та користувацькі провайдери +## Інструменти та власні провайдери -Політики інструментів, експериментальні перемикачі, конфігурацію інструментів на базі провайдерів і налаштування -користувацького провайдера / базової URL-адреси перенесено на спеціальну сторінку — див. -[Конфігурація — інструменти та користувацькі провайдери](/uk/gateway/config-tools). +Політику інструментів, експериментальні перемикачі, конфігурацію інструментів на базі провайдерів і налаштування власних +provider / base-URL перенесено на окрему сторінку — див. +[Конфігурація — інструменти та власні провайдери](/uk/gateway/config-tools). ## Моделі -Визначення провайдерів, allowlist моделей і налаштування користувацьких провайдерів містяться в -[Конфігурація — інструменти та користувацькі провайдери](/uk/gateway/config-tools#custom-providers-and-base-urls). +Визначення провайдерів, списки дозволених моделей і налаштування власного провайдера наведено в +[Конфігурація — інструменти та власні провайдери](/uk/gateway/config-tools#custom-providers-and-base-urls). Корінь `models` також керує глобальною поведінкою каталогу моделей. ```json5 @@ -80,15 +80,15 @@ bundled каналів (автентифікація, контроль дост ``` - `models.mode`: поведінка каталогу провайдера (`merge` або `replace`). -- `models.providers`: мапа користувацьких провайдерів із ключами за id провайдера. -- `models.pricing.enabled`: керує фоновою ініціалізацією цін, яка - запускається після того, як sidecars і канали досягають шляху готовності Gateway. Коли `false`, +- `models.providers`: мапа власних провайдерів за ідентифікатором провайдера. +- `models.pricing.enabled`: керує фоновим початковим завантаженням цін, + яке стартує після того, як sidecars і канали досягають шляху готовності Gateway. Коли `false`, Gateway пропускає отримання каталогів цін OpenRouter і LiteLLM; налаштовані значення `models.providers.*.models[].cost` і далі працюють для локальних оцінок вартості. ## MCP -Визначення MCP-серверів, керованих OpenClaw, містяться в `mcp.servers` і +Визначення MCP-серверів, керованих OpenClaw, розміщені в `mcp.servers` і використовуються вбудованим Pi та іншими runtime-адаптерами. Команди `openclaw mcp list`, `show`, `set` і `unset` керують цим блоком без підключення до цільового сервера під час редагування конфігурації. @@ -115,20 +115,20 @@ bundled каналів (автентифікація, контроль дост } ``` -- `mcp.servers`: іменовані stdio або віддалені визначення MCP-серверів для runtime, які +- `mcp.servers`: іменовані визначення stdio або віддалених MCP-серверів для runtime, які надають налаштовані MCP-інструменти. Віддалені записи використовують `transport: "streamable-http"` або `transport: "sse"`; `type: "http"` — це CLI-native псевдонім, який `openclaw mcp set` і `openclaw doctor --fix` нормалізують у канонічне поле `transport`. - `mcp.sessionIdleTtlMs`: idle TTL для bundled MCP runtime, обмежених сесією. - Одноразові вбудовані запуски запитують очищення наприкінці запуску; цей TTL є запасним механізмом для + Одноразові вбудовані запуски запитують очищення наприкінці запуску; цей TTL є резервним механізмом для довготривалих сесій і майбутніх викликачів. -- Зміни в `mcp.*` застосовуються гаряче шляхом звільнення кешованих session MCP runtime. - Наступне виявлення/використання інструментів створює їх заново з нової конфігурації, тому видалені +- Зміни в `mcp.*` застосовуються гаряче через dispose кешованих сесійних 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-поведінки. +[CLI-бекенди](/uk/gateway/cli-backends#bundle-mcp-overlays) щодо поведінки runtime. ## Skills @@ -155,14 +155,14 @@ bundled каналів (автентифікація, контроль дост } ``` -- `allowBundled`: необов’язковий allowlist лише для bundled skills (керовані/workspace skills не зачіпаються). -- `load.extraDirs`: додаткові спільні корені skills (найнижчий пріоритет). -- `install.preferBrew`: коли true, надавати перевагу інсталяторам Homebrew, коли `brew` +- `allowBundled`: необов’язковий список дозволених лише для bundled skills (керовані/workspace skills не зачіпаються). +- `load.extraDirs`: додаткові спільні корені skill (найнижчий пріоритет). +- `install.preferBrew`: коли true, надавати перевагу інсталяторів Homebrew, коли `brew` доступний, перш ніж переходити до інших типів інсталяторів. -- `install.nodeManager`: налаштування переваги інсталятора node для специфікацій `metadata.openclaw.install` +- `install.nodeManager`: налаштування переваги node-інсталятора для специфікацій `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` вимикає skill, навіть якщо вона bundled/installed. -- `entries..apiKey`: зручне поле для skills, що оголошують основну env-змінну (plaintext-рядок або об’єкт SecretRef). +- `entries..enabled: false` вимикає skill, навіть якщо він bundled/встановлений. +- `entries..apiKey`: зручність для skills, які оголошують основну змінну env (plaintext string або об’єкт SecretRef). --- @@ -173,6 +173,7 @@ bundled каналів (автентифікація, контроль дост plugins: { enabled: true, allow: ["voice-call"], + bundledDiscovery: "allowlist", deny: [], load: { paths: ["~/Projects/oss/voice-call-plugin"], @@ -190,41 +191,45 @@ bundled каналів (автентифікація, контроль дост } ``` -- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. -- Discovery приймає нативні OpenClaw plugins, а також сумісні bundles Codex і bundles Claude, зокрема manifestless bundles Claude зі стандартним layout. +- Завантажується з `~/.openclaw/extensions`, `/.openclaw/extensions`, плюс `plugins.load.paths`. +- Discovery приймає native OpenClaw plugins, а також сумісні Codex bundles і Claude bundles, включно з manifestless Claude default-layout bundles. - **Зміни конфігурації потребують перезапуску 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`, довірені небандловані plugins можуть читати raw вміст розмови з типізованих hook, як-от `llm_input`, `llm_output`, `before_agent_finalize` і `agent_end`. -- `plugins.entries..subagent.allowModelOverride`: явно довірити цьому Plugin запитувати override `provider` і `model` для кожного запуску фонових subagent-запусків. -- `plugins.entries..subagent.allowedModels`: необов’язковий allowlist канонічних цілей `provider/model` для довірених subagent override. Використовуйте `"*"` лише тоді, коли ви навмисно хочете дозволити будь-яку модель. -- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (валідується нативною схемою OpenClaw Plugin, коли доступна). -- Налаштування облікового запису/runtime для channel Plugin містяться в `channels.` і мають описуватися метаданими `channelConfigs` у manifest відповідного Plugin, а не центральним реєстром опцій OpenClaw. -- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера веб-вибірки 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 override мають вказувати на приватні/внутрішні endpoint). - - `onlyMainContent`: витягувати зі сторінок лише основний вміст (стандартно: `true`). - - `maxAgeMs`: максимальний вік кешу в мілісекундах (стандартно: `172800000` / 2 дні). - - `timeoutSeconds`: таймаут scrape-запиту в секундах (стандартно: `60`). -- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (вебпошук Grok). - - `enabled`: увімкнути провайдер X Search. - - `model`: модель Grok для пошуку (наприклад, `"grok-4-1-fast"`). +- `allow`: необов’язковий список дозволених (завантажуються лише перелічені plugins). `deny` має пріоритет. +- `bundledDiscovery`: за замовчуванням `"allowlist"` для нових конфігурацій, тому непорожній + `plugins.allow` також обмежує bundled provider plugins, включно з web-search + runtime providers. Doctor записує `"compat"` для мігрованих legacy allowlist + конфігурацій, щоб зберегти наявну поведінку bundled provider, доки ви не погодитеся на нову. +- `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`. Застосовується до native plugin hooks і підтримуваних директорій hook, наданих bundle. +- `plugins.entries..hooks.allowConversationAccess`: коли `true`, довірені non-bundled plugins можуть читати raw вміст розмови з typed hooks, таких як `llm_input`, `llm_output`, `before_agent_finalize` і `agent_end`. +- `plugins.entries..subagent.allowModelOverride`: явно довіряє цьому plugin запитувати per-run перевизначення `provider` і `model` для фонових subagent запусків. +- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволених canonical цілей `provider/model` для довірених subagent overrides. Використовуйте `"*"` лише тоді, коли навмисно хочете дозволити будь-яку модель. +- `plugins.entries..config`: об’єкт конфігурації, визначений plugin (валідується схемою native OpenClaw plugin, коли доступна). +- Налаштування облікового запису/runtime для channel plugin розміщені в `channels.` і мають описуватися метаданими `channelConfigs` manifest відповідного plugin, а не центральним реєстром опцій OpenClaw. +- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера Firecrawl web-fetch. + - `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). + - `onlyMainContent`: витягувати зі сторінок лише основний вміст (за замовчуванням: `true`). + - `maxAgeMs`: максимальний вік кешу в мілісекундах (за замовчуванням: `172800000` / 2 дні). + - `timeoutSeconds`: таймаут scrape-запиту в секундах (за замовчуванням: `60`). +- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (Grok web 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`: необов’язковий override моделі subagent Dream Diary. Потребує `plugins.entries.memory-core.subagent.allowModelOverride: true`; поєднуйте з `allowedModels`, щоб обмежити цілі. Помилки недоступності моделі повторюються один раз із стандартною моделлю сесії; збої довіри або allowlist не мають тихого fallback. + - `enabled`: головний перемикач dreaming (за замовчуванням `false`). + - `frequency`: cron cadence для кожного повного проходу dreaming (`"0 3 * * *"` за замовчуванням). + - `model`: необов’язкове перевизначення моделі subagent Dream Diary. Потребує `plugins.entries.memory-core.subagent.allowModelOverride: true`; поєднуйте з `allowedModels`, щоб обмежити цілі. Помилки недоступності моделі повторюються один раз із стандартною моделлю сесії; збої довіри або allowlist не переходять у fallback мовчки. - політика фаз і пороги є деталями реалізації (не користувацькими ключами конфігурації). -- Повна конфігурація пам’яті міститься в [Довідник конфігурації пам’яті](/uk/reference/memory-config): +- Повна конфігурація пам’яті наведена в [Довідник конфігурації пам’яті](/uk/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Увімкнені bundle plugins Claude також можуть додавати вбудовані стандартні значення Pi з `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як raw patches конфігурації OpenClaw. -- `plugins.slots.memory`: виберіть id активного memory Plugin або `"none"`, щоб вимкнути memory plugins. -- `plugins.slots.contextEngine`: виберіть id активного context engine Plugin; стандартно `"legacy"`, якщо ви не встановите та не виберете інший engine. +- Увімкнені Claude bundle plugins також можуть додавати embedded Pi defaults із `settings.json`; OpenClaw застосовує їх як sanitized agent settings, а не як raw OpenClaw config patches. +- `plugins.slots.memory`: виберіть активний ідентифікатор memory plugin або `"none"`, щоб вимкнути memory plugins. +- `plugins.slots.contextEngine`: виберіть активний ідентифікатор context engine plugin; за замовчуванням `"legacy"`, якщо ви не встановите й не виберете інший engine. Див. [Plugins](/uk/tools/plugin). @@ -232,10 +237,10 @@ bundled каналів (автентифікація, контроль дост ## Зобов’язання -`commitments` керує inferred follow-up memory: OpenClaw може виявляти check-ins із ходів розмови та доставляти їх через heartbeat runs. +`commitments` керує inferred follow-up memory: OpenClaw може виявляти check-ins з ходів розмови та доставляти їх через heartbeat runs. -- `commitments.enabled`: увімкнути приховане LLM-витягування, зберігання та heartbeat-доставку для inferred follow-up commitments. Стандартно: `false`. -- `commitments.maxPerDay`: максимальна кількість inferred follow-up commitments, доставлених на сесію агента протягом rolling day. Стандартно: `3`. +- `commitments.enabled`: увімкнути hidden LLM extraction, storage і heartbeat delivery для inferred follow-up commitments. За замовчуванням: `false`. +- `commitments.maxPerDay`: максимальна кількість inferred follow-up commitments, доставлених за agent session протягом rolling day. За замовчуванням: `3`. Див. [Inferred commitments](/uk/concepts/commitments). @@ -288,49 +293,29 @@ bundled каналів (автентифікація, контроль дост ``` - `evaluateEnabled: false` вимикає `act:evaluate` і `wait --fn`. -- `tabCleanup` звільняє відстежувані вкладки основного агента після часу простою або коли - сесія перевищує свій ліміт. Задайте `idleMinutes: 0` або `maxTabsPerSession: 0`, щоб - вимкнути ці окремі режими очищення. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому навігація браузера типово залишається суворою. -- Задавайте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте браузерній навігації приватною мережею. -- У суворому режимі кінцеві точки віддалених CDP-профілів (`profiles.*.cdpUrl`) підпадають під те саме блокування приватної мережі під час перевірок доступності/виявлення. +- `tabCleanup` звільняє відстежувані вкладки основного агента після простою або коли сеанс перевищує свій ліміт. Установіть `idleMinutes: 0` або `maxTabsPerSession: 0`, щоб вимкнути ці окремі режими очищення. +- `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), - коли ваш провайдер надає прямий DevTools WebSocket URL. -- `remoteCdpTimeoutMs` і `remoteCdpHandshakeTimeoutMs` застосовуються до перевірки доступності віддаленого та - `attachOnly` CDP, а також до запитів відкриття вкладок. Керовані loopback-профілі - зберігають локальні типові значення CDP. -- Якщо зовнішньо керована CDP-служба доступна через loopback, задайте для цього - профілю `attachOnly: true`; інакше OpenClaw сприйматиме loopback-порт як - локальний керований браузерний профіль і може повідомляти про помилки володіння локальним портом. -- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися на - вибраному хості або через підключений браузерний вузол. -- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний - Chromium-базований браузерний профіль, наприклад Brave або Edge. + Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявляв `/json/version`; використовуйте WS(S), коли ваш провайдер надає прямий URL WebSocket DevTools. +- `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: - дії на основі snapshot/ref замість націлювання CSS-селектором, хуки завантаження - одного файла, без перевизначень таймаутів діалогів, без `wait --load networkidle` і без - `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій. -- Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; задавайте - `cdpUrl` явно лише для віддаленого CDP. -- Локальні керовані профілі можуть задавати `executablePath`, щоб перевизначити глобальний - `browser.executablePath` для цього профілю. Використовуйте це, щоб запускати один профіль у - Chrome, а інший у Brave. -- Локальні керовані профілі використовують `browser.localLaunchTimeoutMs` для HTTP-виявлення Chrome CDP - після запуску процесу та `browser.localCdpReadyTimeoutMs` для - готовності CDP websocket після запуску. Збільшуйте їх на повільніших хостах, де Chrome - успішно запускається, але перевірки готовності випереджають старт. Обидва значення мають бути - додатними цілими числами до `120000` мс; недійсні значення конфігурації відхиляються. -- Порядок автовиявлення: браузер за замовчуванням, якщо він Chromium-базований → Chrome → Brave → Edge → Chromium → Chrome Canary. -- `browser.executablePath` і `browser.profiles..executablePath` обидва - приймають `~` і `~/...` для домашнього каталогу вашої ОС перед запуском Chromium. - Профільний `userDataDir` у профілях `existing-session` також розгортає тильду. -- Сервіс керування: лише loopback (порт походить від `gateway.port`, типово `18791`). -- `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад - `--disable-gpu`, розмір вікна або прапорці налагодження). + дії на основі snapshot/ref замість націлювання CSS-селектором, хуки завантаження одного файлу, без перевизначень тайм-ауту діалогів, без `wait --load networkidle`, а також без `responsebody`, експорту PDF, перехоплення завантажень чи пакетних дій. +- Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; задавайте `cdpUrl` явно лише для віддаленого CDP. +- Локальні керовані профілі можуть задавати `executablePath`, щоб перевизначити глобальний `browser.executablePath` для цього профілю. Використовуйте це, щоб запускати один профіль у Chrome, а інший у Brave. +- Локальні керовані профілі використовують `browser.localLaunchTimeoutMs` для HTTP-виявлення Chrome CDP після запуску процесу та `browser.localCdpReadyTimeoutMs` для готовності websocket CDP після запуску. Збільшуйте їх на повільніших хостах, де Chrome успішно стартує, але перевірки готовності випереджають запуск. Обидва значення мають бути додатними цілими числами до `120000` мс; недійсні значення конфігурації відхиляються. +- Порядок автовиявлення: типовий браузер, якщо він на основі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- `browser.executablePath` і `browser.profiles..executablePath` обидва приймають `~` і `~/...` для домашнього каталогу вашої ОС перед запуском Chromium. + `userDataDir` для окремого профілю в профілях `existing-session` також розгортається з тильдою. +- Служба керування: лише loopback (порт походить від `gateway.port`, типово `18791`). +- `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад `--disable-gpu`, розмір вікна або прапорці налагодження). --- @@ -348,7 +333,7 @@ bundled каналів (автентифікація, контроль дост } ``` -- `seamColor`: акцентний колір для хрому UI нативного застосунку (відтінок бульбашки Talk Mode тощо). +- `seamColor`: акцентний колір для хрому UI нативного застосунку (відтінок бульбашки режиму розмови тощо). - `assistant`: перевизначення ідентичності Control UI. Повертається до ідентичності активного агента. --- @@ -425,75 +410,67 @@ bundled каналів (автентифікація, контроль дост } ``` - + - `mode`: `local` (запустити gateway) або `remote` (підключитися до віддаленого gateway). Gateway відмовляється запускатися, якщо значення не `local`. -- `port`: єдиний мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. -- `bind`: `auto`, `loopback` (за замовчуванням), `lan` (`0.0.0.0`), `tailnet` (лише 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. На практиці це означає спільний токен/пароль або identity-aware зворотний проксі з `gateway.auth.mode: "trusted-proxy"`. Майстер початкового налаштування генерує токен за замовчуванням. -- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRefs), явно встановіть `gateway.auth.mode` у `token` або `password`. Потоки запуску та встановлення/ремонту сервісу завершуються помилкою, коли обидва значення налаштовані, а режим не задано. +- `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. На практиці це означає спільний токен/пароль або identity-aware 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"`: делегує автентифікацію браузера/користувача identity-aware зворотному проксі та довіряє заголовкам ідентичності від `gateway.trustedProxies` (див. [Автентифікація через довірений проксі](/uk/gateway/trusted-proxy-auth)). Цей режим за замовчуванням очікує джерело проксі **не через loopback**; same-host loopback зворотні проксі потребують явного `gateway.auth.trustedProxy.allowLoopback = true`. Внутрішні same-host виклики можуть використовувати `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`, - тому повторні помилки з одного origin localhost не блокують автоматично - інший origin. -- `tailscale.mode`: `serve` (лише tailnet, bind через loopback) або `funnel` (публічний, потребує автентифікації). -- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Потрібен, коли очікуються клієнти браузера з origin не через loopback. -- `controlUi.chatMessageMaxWidth`: необов’язкова максимальна ширина для згрупованих повідомлень чату Control UI. Приймає обмежені значення ширини CSS, як-от `960px`, `82%`, `min(1280px, 82%)` і `calc(100% - 2rem)`. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає запасний варіант origin із заголовка Host для розгортань, що навмисно покладаються на політику origin за заголовком Host. -- `remote.transport`: `ssh` (за замовчуванням) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: аварійне перевизначення на рівні process-environment - клієнта, яке дозволяє plaintext `ws://` до довірених IP у приватній мережі; - за замовчуванням plaintext залишається дозволеним лише для loopback. Еквівалента в `openclaw.json` - немає, а конфігурація приватної мережі браузера, як-от - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, не впливає на клієнти Gateway - WebSocket. -- `gateway.remote.token` / `.password` — поля облікових даних віддаленого клієнта. Самі по собі вони не налаштовують автентифікацію gateway. -- `gateway.push.apns.relay.baseUrl`: базова HTTPS-URL-адреса зовнішнього ретранслятора APNs, який використовується офіційними/TestFlight збірками iOS після публікації relay-backed реєстрацій у gateway. Ця URL-адреса має збігатися з URL ретранслятора, скомпільованою в iOS-збірку. -- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до ретранслятора в мілісекундах. За замовчуванням `10000`. -- Relay-backed реєстрації делегуються конкретній ідентичності gateway. Спарений iOS-застосунок отримує `gateway.identity.get`, включає цю ідентичність у реєстрацію ретранслятора та пересилає gateway дозвіл на надсилання в межах реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові перевизначення env для наведеної вище конфігурації ретранслятора. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch лише для розробки для loopback HTTP URL-адрес ретранслятора. У production URL-адреси ретранслятора мають залишатися на HTTPS. -- `gateway.handshakeTimeoutMs`: тайм-аут pre-auth Gateway WebSocket handshake у мілісекундах. За замовчуванням: `15000`. `OPENCLAW_HANDSHAKE_TIMEOUT_MS` має пріоритет, коли задано. Збільшіть це значення на навантажених або малопотужних хостах, де локальні клієнти можуть підключатися, поки прогрів запуску ще стабілізується. -- `gateway.channelHealthCheckMinutes`: інтервал монітора стану каналу в хвилинах. Встановіть `0`, щоб глобально вимкнути перезапуски монітора стану. За замовчуванням: `5`. -- `gateway.channelStaleEventThresholdMinutes`: поріг stale-socket у хвилинах. Тримайте його більшим або рівним `gateway.channelHealthCheckMinutes`. За замовчуванням: `30`. -- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітора стану на канал/обліковий запис за рухому годину. За замовчуванням: `10`. -- `channels..healthMonitor.enabled`: opt-out на рівні каналу для перезапусків монітора стану, зберігаючи глобальний монітор увімкненим. -- `channels..accounts..healthMonitor.enabled`: перевизначення на рівні облікового запису для каналів із кількома обліковими записами. Коли задано, має пріоритет над перевизначенням на рівні каналу. -- Локальні шляхи викликів gateway можуть використовувати `gateway.remote.*` як запасний варіант лише тоді, коли `gateway.auth.*` не задано. -- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не вирішено, resolution fail-closed (без маскування віддаленим запасним варіантом). -- `trustedProxies`: IP-адреси зворотних проксі, які завершують TLS або впроваджують заголовки forwarded-client. Вказуйте лише проксі, які ви контролюєте. Записи loopback усе ще чинні для same-host proxy/local-detection налаштувань (наприклад, Tailscale Serve або локальний зворотний проксі), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. За замовчуванням `false` для fail-closed поведінки. -- `gateway.nodes.pairing.autoApproveCidrs`: необов’язковий allowlist CIDR/IP для автоматичного схвалення першого спарення пристрою Node без запитаних scopes. Вимкнено, коли не задано. Це не схвалює автоматично спарення operator/browser/Control UI/WebChat, а також не схвалює автоматично оновлення role, scope, metadata або public-key. -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне allow/deny формування для оголошених команд Node після спарення та оцінки platform allowlist. Використовуйте `allowCommands`, щоб увімкнути небезпечні команди Node, як-от `camera.snap`, `camera.clip` і `screen.record`; `denyCommands` вилучає команду, навіть якщо стандарт платформи або явний allow інакше включав би її. Після того як Node змінює свій оголошений список команд, відхиліть і повторно схваліть це спарення пристрою, щоб gateway зберіг оновлений snapshot команд. -- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює стандартний deny list). -- `gateway.tools.allow`: вилучити назви інструментів зі стандартного HTTP deny list. +- `gateway.auth.mode: "trusted-proxy"`: делегуйте автентифікацію браузера/користувача identity-aware reverse proxy і довіряйте заголовкам ідентичності від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим типово очікує джерело проксі **не через loopback**; loopback reverse proxy на тому самому хості потребують явного `gateway.auth.trustedProxy.allowLoopback = true`. Внутрішні виклики з того самого хоста можуть використовувати `gateway.auth.password` як локальний прямий fallback; `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 brute force на localhost). +- На loopback ці блокування browser-origin ізольовані для кожного нормалізованого значення `Origin`, тому повторні помилки з одного localhost origin не блокують автоматично інший origin. +- `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічний, потребує автентифікації). +- `controlUi.allowedOrigins`: явний allowlist browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються браузерні клієнти з origin не через loopback. +- `controlUi.chatMessageMaxWidth`: необов’язкова max-width для згрупованих повідомлень чату Control UI. Приймає обмежені значення ширини CSS, як-от `960px`, `82%`, `min(1280px, 82%)` і `calc(100% - 2rem)`. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, що вмикає fallback origin із заголовка Host для розгортань, які навмисно покладаються на політику origin із заголовка Host. +- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: client-side process-environment break-glass override, що дозволяє 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 після публікації реєстрацій із relay-backed підтримкою до gateway. Цей URL має збігатися з URL ретранслятора, скомпільованим у збірку iOS. +- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до ретранслятора в мілісекундах. Типово `10000`. +- Реєстрації з relay-backed підтримкою делегуються конкретній ідентичності gateway. Спарений застосунок iOS отримує `gateway.identity.get`, додає цю ідентичність до реєстрації ретранслятора і пересилає gateway send grant з областю цієї реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові перевизначення env для конфігурації ретранслятора вище. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch лише для розробки для loopback HTTP URL ретранслятора. Production URL ретранслятора мають залишатися на HTTPS. +- `gateway.handshakeTimeoutMs`: тайм-аут pre-auth Gateway WebSocket handshake у мілісекундах. Типово: `15000`. `OPENCLAW_HANDSHAKE_TIMEOUT_MS` має пріоритет, коли задано. Збільште це значення на навантажених або малопотужних хостах, де локальні клієнти можуть підключатися, поки прогрів запуску ще стабілізується. +- `gateway.channelHealthCheckMinutes`: інтервал health-monitor каналу в хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски health-monitor. Типово: `5`. +- `gateway.channelStaleEventThresholdMinutes`: поріг stale-socket у хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`. +- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor на канал/акаунт у ковзній годині. Типово: `10`. +- `channels..healthMonitor.enabled`: поканальне opt-out для перезапусків health-monitor зі збереженням глобального monitor увімкненим. +- `channels..accounts..healthMonitor.enabled`: поакаунтне перевизначення для multi-account каналів. Коли задано, має пріоритет над перевизначенням на рівні каналу. +- Шляхи локальних викликів gateway можуть використовувати `gateway.remote.*` як fallback лише коли `gateway.auth.*` не задано. +- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і він не розв’язується, розв’язання завершується закритою помилкою (без маскування через remote fallback). +- `trustedProxies`: IP reverse proxy, які завершують TLS або додають forwarded-client заголовки. Вказуйте лише проксі, які ви контролюєте. Записи loopback усе ще валідні для same-host proxy/local-detection налаштувань (наприклад 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 allowlist для автоматичного схвалення першого pairing node device без запитаних scopes. Вимкнено, коли не задано. Це не схвалює автоматично pairing operator/browser/Control UI/WebChat, а також не схвалює автоматично оновлення role, scope, metadata або public-key. +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування allow/deny для оголошених команд node після pairing і оцінювання platform allowlist. Використовуйте `allowCommands`, щоб явно дозволити небезпечні команди node, як-от `camera.snap`, `camera.clip` і `screen.record`; `denyCommands` вилучає команду, навіть якщо platform default або явний allow інакше включив би її. Після того як node змінює свій оголошений список команд, відхиліть і повторно схваліть pairing цього пристрою, щоб gateway зберіг оновлений snapshot команд. +- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий deny list). +- `gateway.tools.allow`: вилучити назви інструментів із типового HTTP deny list. ### OpenAI-сумісні кінцеві точки -- Chat Completions: вимкнено за замовчуванням. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`. +- Chat Completions: типово вимкнено. Увімкніть за допомогою `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: `gateway.http.endpoints.responses.enabled`. -- Посилення захисту URL-введення Responses: +- Посилення захисту URL-input у Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Порожні allowlists вважаються незаданими; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` - і/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. -- Необов’язковий заголовок посилення відповіді: - - `gateway.http.securityHeaders.strictTransportSecurity` (встановлюйте лише для HTTPS origins, які ви контролюєте; див. [Автентифікація через довірений проксі](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + Порожні allowlists вважаються незаданими; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` та/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. +- Необов’язковий заголовок посилення захисту відповіді: + - `gateway.http.securityHeaders.strictTransportSecurity` (задавайте лише для HTTPS origins, які ви контролюєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) -### Ізоляція кількох інстансів +### Ізоляція кількох екземплярів -Запускайте кілька gateways на одному хості з унікальними портами та каталогами стану: +Запускайте кілька gateways на одному хості з унікальними портами і каталогами стану: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -503,7 +480,7 @@ openclaw gateway --port 19001 Зручні прапорці: `--dev` (використовує `~/.openclaw-dev` + порт `19001`), `--profile ` (використовує `~/.openclaw-`). -Див. [Кілька Gateways](/uk/gateway/multiple-gateways). +Див. [Multiple Gateways](/uk/gateway/multiple-gateways). ### `gateway.tls` @@ -521,11 +498,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (за замовчуванням: `false`). -- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовані; лише для local/dev використання. -- `certPath`: шлях файлової системи до файлу сертифіката TLS. -- `keyPath`: шлях файлової системи до файлу приватного ключа TLS; тримайте доступ обмеженим. -- `caPath`: необов’язковий шлях до CA bundle для перевірки клієнтів або користувацьких ланцюгів довіри. +- `enabled`: вмикає TLS termination на listener gateway (HTTPS/WSS) (типово: `false`). +- `autoGenerate`: автоматично генерує локальну пару самопідписаного сертифіката/ключа, коли явні файли не налаштовано; лише для local/dev використання. +- `certPath`: шлях файлової системи до файлу TLS-сертифіката. +- `keyPath`: шлях файлової системи до файлу приватного TLS-ключа; обмежте права доступу. +- `caPath`: необов’язковий шлях до CA bundle для перевірки клієнта або користувацьких ланцюгів довіри. ### `gateway.reload` @@ -542,16 +519,16 @@ openclaw gateway --port 19001 ``` - `mode`: керує тим, як зміни конфігурації застосовуються під час виконання. - - `"off"`: ігнорувати живі зміни; зміни потребують явного перезапуску. + - `"off"`: ігнорувати live edits; зміни потребують явного перезапуску. - `"restart"`: завжди перезапускати процес gateway при зміні конфігурації. - - `"hot"`: застосовувати зміни в процесі без перезапуску. - - `"hybrid"` (за замовчуванням): спочатку спробувати hot reload; за потреби перейти до перезапуску. + - `"hot"`: застосовувати зміни всередині процесу без перезапуску. + - `"hybrid"` (типово): спочатку спробувати hot reload; якщо потрібно, fallback до перезапуску. - `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число). -- `deferralTimeoutMs`: необов’язковий максимальний час у мс очікування операцій in-flight перед примусовим перезапуском. Опустіть його, щоб використати стандартне обмежене очікування (`300000`); встановіть `0`, щоб чекати безстроково та періодично журналювати попередження still-pending. +- `deferralTimeoutMs`: необов’язковий максимальний час у мс очікування in-flight операцій перед примусовим перезапуском. Не вказуйте, щоб використати типове обмежене очікування (`300000`); установіть `0`, щоб чекати безстроково і журналювати періодичні попередження still-pending. --- -## Hooks +## Хуки ```json5 { @@ -585,47 +562,47 @@ openclaw gateway --port 19001 ``` Автентифікація: `Authorization: Bearer ` або `x-openclaw-token: `. -Токени хуків у рядку запиту відхиляються. +Токени хука в рядку запиту відхиляються. Примітки щодо валідації та безпеки: - `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`. Статичні ключі зіставлення не потребують цієї явної згоди. +- Якщо `hooks.allowRequestSessionKey=true`, обмежте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). +- Якщо зіставлення або пресет використовує шаблонний `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`. +- `POST /hooks/` → розпізнається через `hooks.mappings` + - Значення `sessionKey` зіставлення, відрендерені з шаблону, вважаються наданими ззовні й також потребують `hooks.allowRequestSessionKey=true`. - + -- `match.path` зіставляє підшлях після `/hooks` (наприклад, `/hooks/gmail` → `gmail`). +- `match.path` зіставляє підшлях після `/hooks` (наприклад `/hooks/gmail` → `gmail`). - `match.source` зіставляє поле payload для загальних шляхів. - Шаблони на кшталт `{{messages[0].subject}}` читають дані з payload. -- `transform` може вказувати на модуль JS/TS, що повертає дію хука. +- `transform` може вказувати на JS/TS-модуль, що повертає дію хука. - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та обхід каталогів відхиляються). - - Тримайте `hooks.transformsDir` у межах `~/.openclaw/hooks/transforms`; каталоги Skills робочого простору відхиляються. Якщо `openclaw doctor` повідомляє, що цей шлях недійсний, перемістіть модуль перетворення в каталог перетворень хуків або вилучіть `hooks.transformsDir`. + - Тримайте `hooks.transformsDir` у `~/.openclaw/hooks/transforms`; каталоги Skills робочої області відхиляються. Якщо `openclaw doctor` повідомляє, що цей шлях недійсний, перемістіть модуль трансформації до каталогу трансформацій хуків або видаліть `hooks.transformsDir`. - `agentId` спрямовує до конкретного агента; невідомі ID повертаються до типового. - `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити всі, `[]` = заборонити всі). -- `defaultSessionKey`: необов'язковий фіксований ключ сесії для запусків агента хуків без явного `sessionKey`. -- `allowRequestSessionKey`: дозволяє викликачам `/hooks/agent` і ключам сесії зіставлення на основі шаблонів задавати `sessionKey` (типово: `false`). -- `allowedSessionKeyPrefixes`: необов'язковий список дозволених префіксів для явних значень `sessionKey` (запит + зіставлення), наприклад `["hook:"]`. Він стає обов'язковим, коли будь-яке зіставлення або пресет використовує шаблонний `sessionKey`. +- `defaultSessionKey`: необов’язковий фіксований ключ сеансу для запусків агента хуків без явного `sessionKey`. +- `allowRequestSessionKey`: дозволяє викликачам `/hooks/agent` і керованим шаблонами ключам сеансу зіставлення задавати `sessionKey` (типово: `false`). +- `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + зіставлення), наприклад `["hook:"]`. Він стає обов’язковим, коли будь-яке зіставлення або пресет використовує шаблонний `sessionKey`. - `deliver: true` надсилає фінальну відповідь у канал; `channel` типово має значення `last`. -- `model` перевизначає LLM для цього запуску хука (має бути дозволено, якщо задано каталог моделей). +- `model` перевизначає LLM для цього запуску хука (має бути дозволено, якщо каталог моделей задано). ### Інтеграція 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 { @@ -648,7 +625,7 @@ openclaw gateway --port 19001 } ``` -- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, коли це налаштовано. Задайте `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути. +- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, якщо це налаштовано. Задайте `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути. - Не запускайте окремий `gog gmail watch serve` паралельно з Gateway. --- @@ -665,15 +642,15 @@ 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 (токен/пароль/довірений проксі), як і інші HTTP-поверхні Gateway. -- Node WebViews зазвичай не надсилають заголовки автентифікації; після сполучення й підключення вузла Gateway оголошує URL можливостей, обмежені вузлом, для доступу до canvas/A2UI. -- URL можливостей прив'язані до активної WS-сесії вузла й швидко завершуються. Резервний варіант на основі IP не використовується. -- Вставляє клієнт live-reload в обслуговуваний HTML. -- Автоматично створює стартовий `index.html`, коли порожньо. +- Прив’язки не до loopback: маршрути canvas потребують автентифікації Gateway (токен/пароль/довірений проксі), так само як інші HTTP-поверхні Gateway. +- Node WebViews зазвичай не надсилають заголовки автентифікації; після сполучення та підключення вузла Gateway оголошує URL-адреси можливостей, обмежені вузлом, для доступу до canvas/A2UI. +- URL-адреси можливостей прив’язані до активного WS-сеансу вузла й швидко спливають. Резервний варіант на основі IP не використовується. +- Впроваджує клієнт live-reload в HTML, що обслуговується. +- Автоматично створює початковий `index.html`, коли порожньо. - Також обслуговує A2UI за `/__openclaw__/a2ui/`. - Зміни потребують перезапуску Gateway. - Вимкніть live reload для великих каталогів або помилок `EMFILE`. @@ -694,11 +671,11 @@ openclaw gateway --port 19001 } ``` -- `minimal` (типово, коли ввімкнено вбудований Plugin `bonjour`): пропускати `cliPath` + `sshPort` у TXT-записах. -- `full`: включати `cliPath` + `sshPort`; багатоадресне оголошення в LAN усе одно потребує ввімкненого вбудованого Plugin `bonjour`. -- `off`: пригнічує багатоадресне оголошення в LAN без зміни ввімкнення Plugin. +- `minimal` (типово, коли ввімкнено вбудований Plugin `bonjour`): пропускає `cliPath` + `sshPort` у TXT-записах. +- `full`: включає `cliPath` + `sshPort`; для multicast-рекламування в LAN усе одно потрібно, щоб вбудований Plugin `bonjour` був увімкнений. +- `off`: пригнічує multicast-рекламування в LAN без зміни ввімкнення Plugin. - Вбудований Plugin `bonjour` автоматично запускається на хостах macOS і вмикається явно на Linux, Windows і контейнеризованих розгортаннях Gateway. -- Ім'я хоста типово дорівнює системному імені хоста, коли воно є дійсною DNS-міткою, з поверненням до `openclaw`. Перевизначте за допомогою `OPENCLAW_MDNS_HOSTNAME`. +- Ім’я хоста типово дорівнює системному імені хоста, коли воно є дійсною DNS-міткою, з поверненням до `openclaw`. Перевизначте через `OPENCLAW_MDNS_HOSTNAME`. ### Широка зона (DNS-SD) @@ -735,14 +712,14 @@ openclaw gateway --port 19001 } ``` -- Вбудовані змінні середовища застосовуються лише якщо у середовищі процесу відсутній відповідний ключ. +- Вбудовані змінні середовища застосовуються лише якщо в середовищі процесу немає відповідного ключа. - Файли `.env`: `.env` у CWD + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). - `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell. -- Повний порядок пріоритету див. у [Середовище](/uk/help/environment). +- Повний порядок пріоритетів див. у розділі [Середовище](/uk/help/environment). ### Підстановка змінних середовища -Посилайтеся на змінні середовища в будь-якому рядку конфігурації за допомогою `${VAR_NAME}`: +Посилайтеся на змінні середовища в будь-якому конфігураційному рядку за допомогою `${VAR_NAME}`: ```json5 { @@ -754,18 +731,18 @@ openclaw gateway --port 19001 - Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. - Відсутні або порожні змінні спричиняють помилку під час завантаження конфігурації. -- Екрануйте як `$${VAR}`, щоб отримати літеральне `${VAR}`. +- Екрануйте як `$${VAR}` для літерального `${VAR}`. - Працює з `$include`. --- ## Секрети -Посилання на секрети є додатковими: відкриті текстові значення все ще працюють. +Посилання на секрети є додатковими: звичайні текстові значення все ще працюють. ### `SecretRef` -Використовуйте одну форму об'єкта: +Використовуйте одну форму об’єкта: ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -777,15 +754,15 @@ openclaw gateway --port 19001 - Шаблон id для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` - id для `source: "file"`: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`) - Шаблон id для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- id для `source: "exec"` не мають містити розділених скісними рисками сегментів шляху `.` або `..` (наприклад, `a/../b` відхиляється) +- id для `source: "exec"` не повинні містити розділені скісними рисками сегменти шляху `.` або `..` (наприклад `a/../b` буде відхилено) ### Підтримувана поверхня облікових даних - Канонічна матриця: [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface) -- `secrets apply` націлюється на підтримувані шляхи облікових даних `openclaw.json`. -- Посилання `auth-profiles.json` включені до runtime-розв'язання та покриття аудиту. +- Цілі `secrets apply` підтримують шляхи облікових даних `openclaw.json`. +- Посилання `auth-profiles.json` включені до runtime-вирішення та покриття аудиту. -### Конфігурація провайдерів секретів +### Конфігурація постачальників секретів ```json5 { @@ -815,14 +792,14 @@ openclaw gateway --port 19001 Примітки: -- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (`id` має бути `"value"` у режимі singleValue). -- Шляхи провайдерів file і exec завершуються закрито, коли перевірка Windows ACL недоступна. Встановлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. -- Провайдер `exec` вимагає абсолютний шлях `command` і використовує протокольні payload-и через stdin/stdout. -- За замовчуванням шляхи команд, що є символічними посиланнями, відхиляються. Встановіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символічні посилання з перевіркою розв'язаного цільового шляху. -- Якщо налаштовано `trustedDirs`, перевірка довіреного каталогу застосовується до розв'язаного цільового шляху. -- Дочірнє середовище `exec` за замовчуванням мінімальне; явно передавайте потрібні змінні через `passEnv`. -- Посилання на секрети розв'язуються під час активації в in-memory знімок, після чого шляхи запитів читають лише цей знімок. -- Фільтрація активної поверхні застосовується під час активації: нерозв'язані посилання на ввімкнених поверхнях спричиняють помилку запуску або перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. +- Постачальник `file` підтримує `mode: "json"` і `mode: "singleValue"` (`id` має бути `"value"` у режимі singleValue). +- Шляхи постачальників file та exec завершуються із закритою помилкою, коли перевірка Windows ACL недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. +- Постачальник `exec` вимагає абсолютного шляху `command` і використовує протокольні payload-и через stdin/stdout. +- За замовчуванням шляхи команд через symlink відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи через symlink із валідацією розв’язаного цільового шляху. +- Якщо налаштовано `trustedDirs`, перевірка довіреного каталогу застосовується до розв’язаного цільового шляху. +- Дочірнє середовище `exec` за замовчуванням мінімальне; передавайте потрібні змінні явно через `passEnv`. +- Посилання на секрети під час активації розв’язуються у знімок у пам’яті, після чого шляхи запитів читають лише цей знімок. +- Фільтрація активної поверхні застосовується під час активації: нерозв’язані посилання на ввімкнених поверхнях призводять до збою запуску або перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. --- @@ -846,10 +823,10 @@ openclaw gateway --port 19001 - Профілі для кожного агента зберігаються в `/auth-profiles.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-облікові дані надходять із розв'язаних in-memory знімків; застарілі статичні записи `auth.json` очищаються після виявлення. -- Застарілі імпорти OAuth надходять із `~/.openclaw/credentials/oauth.json`. +- Застарілі плоскі мапи `auth-profiles.json`, як-от `{ "provider": { "apiKey": "..." } }`, не є runtime-форматом; `openclaw doctor --fix` переписує їх у канонічні профілі API-ключів `provider:default` із резервною копією `.legacy-flat.*.bak`. +- Профілі в режимі OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілю автентифікації на основі SecretRef. +- Статичні runtime-облікові дані надходять із розв’язаних знімків у пам’яті; застарілі статичні записи `auth.json` очищаються після виявлення. +- Застарілі імпорти OAuth походять із `~/.openclaw/credentials/oauth.json`. - Див. [OAuth](/uk/concepts/oauth). - Runtime-поведінка секретів та інструменти `audit/configure/apply`: [Керування секретами](/uk/gateway/secrets). @@ -873,15 +850,20 @@ openclaw gateway --port 19001 } ``` -- `billingBackoffHours`: базовий backoff у годинах, коли профіль зазнає збою через справжні помилки billing/insufficient-credit (типово: `5`). Явний текст про billing усе ще може потрапити сюди навіть у відповідях `401`/`403`, але текстові matcher-и, специфічні для provider, залишаються обмеженими provider-ом, якому вони належать (наприклад OpenRouter `Key limit exceeded`). Повторювані HTTP `402` повідомлення про usage-window або organization/workspace spend-limit натомість залишаються в шляху `rate_limit`. -- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин billing backoff для окремих provider-ів. -- `billingMaxHours`: обмеження в годинах для експоненційного зростання billing backoff (типово: `24`). -- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для високодостовірних збоїв `auth_permanent` (типово: `10`). -- `authPermanentMaxMinutes`: обмеження в хвилинах для зростання backoff `auth_permanent` (типово: `60`). -- `failureWindowHours`: ковзне вікно в годинах, що використовується для лічильників backoff (типово: `24`). -- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile того самого provider-а для помилок перевантаження перед переходом до model fallback (типово: `1`). Сюди потрапляють provider-busy форми, такі як `ModelNotReadyException`. -- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого provider/профілю (типово: `0`). -- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile того самого provider-а для помилок rate-limit перед переходом до model fallback (типово: `1`). Цей rate-limit кошик містить текст у формі provider-а, зокрема `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. +- `billingBackoffHours`: базове відтермінування у годинах, коли профіль зазнає збою через справжні помилки + білінгу/недостатнього кредиту (типово: `5`). Явний текст про білінг може + все одно потрапити сюди навіть у відповідях `401`/`403`, але специфічні для провайдера + текстові зіставники залишаються обмеженими провайдером, якому вони належать (наприклад OpenRouter + `Key limit exceeded`). Повідомлення HTTP `402`, придатні до повторної спроби, про вікно використання або + ліміт витрат організації/робочого простору натомість залишаються у шляху `rate_limit`. +- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин відтермінування білінгу для окремих провайдерів. +- `billingMaxHours`: обмеження в годинах для експоненційного зростання відтермінування білінгу (типово: `24`). +- `authPermanentBackoffMinutes`: базове відтермінування у хвилинах для високодостовірних збоїв `auth_permanent` (типово: `10`). +- `authPermanentMaxMinutes`: обмеження у хвилинах для зростання відтермінування `auth_permanent` (типово: `60`). +- `failureWindowHours`: ковзне вікно у годинах, що використовується для лічильників відтермінування (типово: `24`). +- `overloadedProfileRotations`: максимальна кількість ротацій профілів автентифікації того самого провайдера для помилок перевантаження перед перемиканням на резервну модель (типово: `1`). Форми зайнятості провайдера, як-от `ModelNotReadyException`, потрапляють сюди. +- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`). +- `rateLimitedProfileRotations`: максимальна кількість ротацій профілів автентифікації того самого провайдера для помилок обмеження швидкості перед перемиканням на резервну модель (типово: `1`). Цей кошик обмеження швидкості включає текст у форматі провайдера, як-от `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. --- @@ -901,10 +883,10 @@ openclaw gateway --port 19001 ``` - Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. -- Установіть `logging.file` для стабільного шляху. -- `consoleLevel` підвищується до `debug`, коли вказано `--verbose`. -- `maxFileBytes`: максимальний розмір активного файлу журналу в байтах перед ротацією (додатне ціле число; типово: `104857600` = 100 МБ). OpenClaw зберігає до п’яти нумерованих архівів поруч з активним файлом. -- `redactSensitive` / `redactPatterns`: найкраще можливе маскування для виводу в консоль, файлових журналів, записів журналу OTLP і збереженого тексту транскрипту сесії. `redactSensitive: "off"` вимикає лише цю загальну політику журналів/транскриптів; UI/tool/diagnostic поверхні безпеки все одно редагують секрети перед емісією. +- Задайте `logging.file` для стабільного шляху. +- `consoleLevel` підвищується до `debug` під час `--verbose`. +- `maxFileBytes`: максимальний розмір активного файлу журналу в байтах перед ротацією (додатне ціле число; типово: `104857600` = 100 MB). OpenClaw зберігає до п’яти пронумерованих архівів поруч з активним файлом. +- `redactSensitive` / `redactPatterns`: маскування на основі найкращих зусиль для виводу консолі, файлових журналів, записів журналу OTLP і збереженого тексту стенограми сеансу. `redactSensitive: "off"` вимикає лише цю загальну політику журналів/стенограм; поверхні безпеки UI/інструментів/діагностики все одно редагують секрети перед надсиланням. --- @@ -953,24 +935,24 @@ openclaw gateway --port 19001 ``` - `enabled`: головний перемикач для виводу інструментації (типово: `true`). -- `flags`: масив рядків прапорців, які вмикають цільовий вивід журналів (підтримує wildcard-и на кшталт `"telegram.*"` або `"*"`). -- `stuckSessionWarnMs`: поріг віку без прогресу в мс для класифікації довготривалих сесій обробки як `session.long_running`, `session.stalled` або `session.stuck`. Відповідь, tool, статус, блок і прогрес ACP скидають таймер; повторні діагностичні події `session.stuck` відступають, доки стан не змінюється. -- `otel.enabled`: вмикає pipeline експорту OpenTelemetry (типово: `false`). Повну конфігурацію, каталог сигналів і модель приватності див. у [експорті OpenTelemetry](/uk/gateway/opentelemetry). -- `otel.endpoint`: URL collector-а для експорту OTel. -- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: необов’язкові OTLP endpoint-и для окремих сигналів. Коли встановлені, вони перевизначають `otel.endpoint` лише для відповідного сигналу. +- `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.protocol`: `"http/protobuf"` (типово) або `"grpc"`. -- `otel.headers`: додаткові HTTP/gRPC metadata headers, що надсилаються із запитами експорту OTel. -- `otel.serviceName`: назва сервісу для resource attributes. -- `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт trace, metrics або log. -- `otel.sampleRate`: частота семплювання trace `0`–`1`. -- `otel.flushIntervalMs`: інтервал періодичного flush телеметрії в мс. -- `otel.captureContent`: opt-in захоплення сирого вмісту для OTEL span attributes. Типово вимкнено. Булеве `true` захоплює non-system вміст повідомлень/tool; форма об’єкта дає змогу явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`. -- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: перемикач середовища для найновіших експериментальних GenAI span provider attributes. Типово span-и зберігають legacy attribute `gen_ai.system` для сумісності; GenAI metrics використовують обмежені semantic attributes. -- `OPENCLAW_OTEL_PRELOADED=1`: перемикач середовища для hosts, які вже зареєстрували глобальний OpenTelemetry SDK. OpenClaw тоді пропускає запуск/зупинку SDK, що належать Plugin, зберігаючи діагностичні listener-и активними. -- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` і `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: signal-specific env vars endpoint-ів, що використовуються, коли відповідний ключ конфігурації не встановлено. -- `cacheTrace.enabled`: журналювати знімки cache trace для вбудованих запусків (типово: `false`). -- `cacheTrace.filePath`: шлях виводу для cache trace JSONL (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід cache trace (усі типово: `true`). +- `otel.headers`: додаткові заголовки HTTP/gRPC metadata, що надсилаються із запитами експорту OTel. +- `otel.serviceName`: назва сервісу для атрибутів ресурсу. +- `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт трас, метрик або журналів. +- `otel.sampleRate`: частота вибірки трас `0`–`1`. +- `otel.flushIntervalMs`: періодичний інтервал скидання телеметрії в мс. +- `otel.captureContent`: явне ввімкнення захоплення необробленого вмісту для атрибутів діапазонів OTEL. Типово вимкнено. Булеве `true` захоплює несистемний вміст повідомлень/інструментів; об’єктна форма дає змогу явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`. +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: змінна середовища для найновіших експериментальних атрибутів провайдера діапазонів GenAI. Типово діапазони зберігають застарілий атрибут `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`). +- `cacheTrace.filePath`: шлях виводу для JSONL трасування кешу (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід трасування кешу (усі типово: `true`). --- @@ -992,12 +974,12 @@ openclaw gateway --port 19001 } ``` -- `channel`: канал релізів для npm/git install-ів — `"stable"`, `"beta"` або `"dev"`. -- `checkOnStart`: перевіряти npm updates під час запуску gateway (типово: `true`). -- `auto.enabled`: увімкнути фонове auto-update для package install-ів (типово: `false`). -- `auto.stableDelayHours`: мінімальна затримка в годинах перед stable-channel auto-apply (типово: `6`; макс.: `168`). -- `auto.stableJitterHours`: додаткове вікно розподілу rollout для stable-channel у годинах (типово: `12`; макс.: `168`). -- `auto.betaCheckIntervalHours`: як часто виконуються beta-channel перевірки, у годинах (типово: `1`; макс.: `24`). +- `channel`: канал випусків для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`. +- `checkOnStart`: перевіряти оновлення npm під час запуску Gateway (типово: `true`). +- `auto.enabled`: увімкнути фонове автоматичне оновлення для пакетних встановлень (типово: `false`). +- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням для стабільного каналу (типово: `6`; максимум: `168`). +- `auto.stableJitterHours`: додаткове вікно розподілу розгортання стабільного каналу в годинах (типово: `12`; максимум: `168`). +- `auto.betaCheckIntervalHours`: як часто виконуються перевірки бета-каналу в годинах (типово: `1`; максимум: `24`). --- @@ -1030,23 +1012,23 @@ openclaw gateway --port 19001 } ``` -- `enabled`: глобальний feature gate ACP (типово: `true`; установіть `false`, щоб приховати ACP dispatch і spawn affordances). -- `dispatch.enabled`: незалежний gate для dispatch ходу сесії ACP (типово: `true`). Установіть `false`, щоб залишити команди ACP доступними, але заблокувати виконання. -- `backend`: типовий id backend-а runtime ACP (має відповідати зареєстрованому runtime Plugin ACP). - Спочатку встановіть backend Plugin, і якщо `plugins.allow` встановлено, додайте id backend Plugin (наприклад `acpx`), інакше backend ACP не завантажиться. -- `defaultAgent`: резервний id цільового агента ACP, коли spawns не вказують явну ціль. -- `allowedAgents`: allowlist id агентів, дозволених для runtime сесій ACP; порожній список означає відсутність додаткового обмеження. -- `maxConcurrentSessions`: максимальна кількість одночасно активних сесій ACP. -- `stream.coalesceIdleMs`: idle flush window у мс для потокового тексту. -- `stream.maxChunkChars`: максимальний розмір chunk перед розділенням проєкції потокового блока. -- `stream.repeatSuppression`: пригнічувати повторювані status/tool рядки на хід (типово: `true`). -- `stream.deliveryMode`: `"live"` транслює інкрементально; `"final_only"` буферизує до terminal events ходу. -- `stream.hiddenBoundarySeparator`: розділювач перед видимим текстом після прихованих tool events (типово: `"paragraph"`). -- `stream.maxOutputChars`: максимальна кількість символів виводу assistant, що проєктується на хід ACP. +- `enabled`: глобальний функціональний перемикач ACP (типово: `true`; задайте `false`, щоб приховати диспетчеризацію ACP і можливості створення). +- `dispatch.enabled`: незалежний перемикач для диспетчеризації ходу сеансу ACP (типово: `true`). Задайте `false`, щоб залишити команди ACP доступними, блокуючи виконання. +- `backend`: типовий id бекенда середовища виконання ACP (має відповідати зареєстрованому Plugin середовища виконання ACP). + Спочатку встановіть Plugin бекенда, і якщо задано `plugins.allow`, включіть id Plugin бекенда (наприклад `acpx`), інакше бекенд ACP не завантажиться. +- `defaultAgent`: резервний id цільового агента ACP, коли створення не вказує явну ціль. +- `allowedAgents`: allowlist id агентів, дозволених для сеансів середовища виконання ACP; порожній список означає відсутність додаткового обмеження. +- `maxConcurrentSessions`: максимальна кількість одночасно активних сеансів ACP. +- `stream.coalesceIdleMs`: вікно скидання під час простою в мс для потокового тексту. +- `stream.maxChunkChars`: максимальний розмір фрагмента перед розділенням проєкції потокового блока. +- `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструментів у межах ходу (типово: `true`). +- `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до кінцевих подій ходу. +- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (типово: `"paragraph"`). +- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, що проєктується на хід ACP. - `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлення ACP. -- `stream.tagVisibility`: запис назв тегів у boolean перевизначення видимості для streamed events. -- `runtime.ttlMinutes`: idle TTL у хвилинах для worker-ів сесій ACP перед тим, як вони стають придатними для очищення. -- `runtime.installCommand`: необов’язкова команда install, яку потрібно виконати під час bootstrap середовища runtime ACP. +- `stream.tagVisibility`: запис назв тегів до булевих перевизначень видимості для потокових подій. +- `runtime.ttlMinutes`: TTL простою в хвилинах для робочих процесів сеансів ACP перед можливим очищенням. +- `runtime.installCommand`: необов’язкова команда встановлення для запуску під час початкового налаштування середовища виконання ACP. --- @@ -1062,17 +1044,17 @@ openclaw gateway --port 19001 } ``` -- `cli.banner.taglineMode` керує стилем tagline банера: - - `"random"` (типово): rotating funny/seasonal taglines. - - `"default"`: фіксований нейтральний tagline (`All your chats, one OpenClaw.`). - - `"off"`: без тексту tagline (title/version банера все одно показуються). -- Щоб приховати весь банер (не лише taglines), установіть env `OPENCLAW_HIDE_BANNER=1`. +- `cli.banner.taglineMode` керує стилем слогана банера: + - `"random"` (типово): змінні жартівливі/сезонні слогани. + - `"default"`: фіксований нейтральний слоган (`All your chats, one OpenClaw.`). + - `"off"`: без тексту слогана (заголовок/версія банера все одно показуються). +- Щоб приховати весь банер (а не лише слогани), задайте змінну середовища `OPENCLAW_HIDE_BANNER=1`. --- ## Майстер -Метадані, записані guided setup flows CLI (`onboard`, `configure`, `doctor`): +Метадані, записані керованими потоками налаштування CLI (`onboard`, `configure`, `doctor`): ```json5 { @@ -1090,15 +1072,15 @@ openclaw gateway --port 19001 ## Ідентичність -Див. поля ідентичності `agents.list` у [типових налаштуваннях агента](/uk/gateway/config-agents#agent-defaults). +Див. поля ідентичності `agents.list` у [типових значеннях агентів](/uk/gateway/config-agents#agent-defaults). --- ## Міст (застарілий, видалено) -Поточні builds більше не містять TCP bridge. Вузли підключаються через Gateway WebSocket. Ключі `bridge.*` більше не є частиною схеми конфігурації (validation не проходитиме, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). +Поточні збірки більше не містять TCP-міст. Вузли підключаються через WebSocket Gateway. Ключі `bridge.*` більше не є частиною схеми конфігурації (перевірка завершується помилкою, доки їх не видалено; `openclaw doctor --fix` може прибрати невідомі ключі). - + ```json { @@ -1136,11 +1118,11 @@ openclaw gateway --port 19001 } ``` -- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків cron перед pruning із `sessions.json`. Також керує очищенням archived deleted cron transcripts. Типово: `24h`; установіть `false`, щоб вимкнути. -- `runLog.maxBytes`: максимальний розмір на файл журналу запуску (`cron/runs/.jsonl`) перед pruning. Типово: `2_000_000` байтів. -- `runLog.keepLines`: найновіші рядки, що зберігаються, коли спрацьовує pruning журналу запуску. Типово: `2000`. -- `webhookToken`: bearer token, що використовується для POST-доставки cron webhook (`delivery.mode = "webhook"`), якщо пропущено, auth header не надсилається. -- `webhook`: застарілий legacy fallback URL webhook (http/https), що використовується лише для збережених jobs, які досі мають `notify: true`. +- `sessionRetention`: як довго зберігати завершені ізольовані сеанси запусків Cron перед видаленням із `sessions.json`. Також керує очищенням архівованих стенограм видалених Cron. Типово: `24h`; задайте `false`, щоб вимкнути. +- `runLog.maxBytes`: максимальний розмір файлу журналу для одного запуску (`cron/runs/.jsonl`) перед обрізанням. Типово: `2_000_000` байт. +- `runLog.keepLines`: найновіші рядки, що зберігаються, коли запускається обрізання журналу запуску. Типово: `2000`. +- `webhookToken`: bearer token, що використовується для доставки POST Webhook Cron (`delivery.mode = "webhook"`), якщо його не вказано, заголовок автентифікації не надсилається. +- `webhook`: застарілий резервний URL Webhook (http/https), що використовується лише для збережених завдань, які все ще мають `notify: true`. ### `cron.retry` @@ -1156,11 +1138,11 @@ openclaw gateway --port 19001 } ``` -- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань у разі тимчасових помилок (за замовчуванням: `3`; діапазон: `0`–`10`). -- `backoffMs`: масив затримок відступу в мс для кожної повторної спроби (за замовчуванням: `[30000, 60000, 300000]`; 1–10 елементів). -- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати спроби для всіх тимчасових типів. +- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань у разі тимчасових помилок (типово: `3`; діапазон: `0`–`10`). +- `backoffMs`: масив затримок відступу в мс для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів). +- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати всі тимчасові типи. -Застосовується лише до одноразових Cron-завдань. Періодичні завдання використовують окрему обробку збоїв. +Застосовується лише до одноразових завдань cron. Повторювані завдання використовують окрему обробку збоїв. ### `cron.failureAlert` @@ -1179,12 +1161,12 @@ openclaw gateway --port 19001 } ``` -- `enabled`: увімкнути сповіщення про збої для Cron-завдань (за замовчуванням: `false`). -- `after`: кількість послідовних збоїв до спрацювання сповіщення (додатне ціле число, мін.: `1`). +- `enabled`: увімкнути сповіщення про збої для завдань cron (типово: `false`). +- `after`: кількість послідовних збоїв до надсилання сповіщення (додатне ціле число, мін.: `1`). - `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число). -- `includeSkipped`: враховувати послідовно пропущені запуски в порозі сповіщення (за замовчуванням: `false`). Пропущені запуски відстежуються окремо й не впливають на відступ для помилок виконання. +- `includeSkipped`: зараховувати послідовно пропущені запуски до порогу сповіщення (типово: `false`). Пропущені запуски відстежуються окремо й не впливають на відступ для помилок виконання. - `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` публікує в налаштований Webhook. -- `accountId`: необов’язковий ідентифікатор облікового запису або каналу для обмеження доставки сповіщень. +- `accountId`: необов’язковий ідентифікатор облікового запису або каналу для обмеження області доставки сповіщень. ### `cron.failureDestination` @@ -1201,38 +1183,38 @@ openclaw gateway --port 19001 } ``` -- Типове місце призначення для сповіщень про збої Cron в усіх завданнях. -- `mode`: `"announce"` або `"webhook"`; за замовчуванням використовується `"announce"`, коли є достатньо цільових даних. +- Типове місце призначення для сповіщень про збої cron для всіх завдань. +- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо цільових даних. - `channel`: перевизначення каналу для доставки announce. `"last"` повторно використовує останній відомий канал доставки. - `to`: явна ціль announce або URL Webhook. Обов’язково для режиму Webhook. - `accountId`: необов’язкове перевизначення облікового запису для доставки. - `delivery.failureDestination` для окремого завдання перевизначає це глобальне типове значення. -- Коли не задано ні глобального, ні окремого для завдання місця призначення збоїв, завдання, які вже доставляються через `announce`, у разі збою повертаються до цієї основної цілі announce. -- `delivery.failureDestination` підтримується лише для завдань із `sessionTarget="isolated"`, якщо основний `delivery.mode` завдання не є `"webhook"`. +- Коли не задано ні глобального, ні окремого місця призначення для сповіщень про збій, завдання, які вже доставляються через `announce`, у разі збою повертаються до цієї основної цілі announce. +- `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо основний `delivery.mode` завдання не є `"webhook"`. -Див. [Cron-завдання](/uk/automation/cron-jobs). Ізольовані виконання Cron відстежуються як [фонові завдання](/uk/automation/tasks). +Див. [Завдання Cron](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [фонові завдання](/uk/automation/tasks). --- -## Змінні шаблонів моделі медіа +## Змінні шаблонів медіамоделі -Заповнювачі шаблону, що розгортаються в `tools.media.models[].args`: +Заповнювачі шаблонів, що розгортаються в `tools.media.models[].args`: | Змінна | Опис | | ------------------ | ------------------------------------------------- | -| `{{Body}}` | Повне тіло вхідного повідомлення | -| `{{RawBody}}` | Сире тіло (без обгорток історії/відправника) | -| `{{BodyStripped}}` | Тіло з вилученими згадками групи | +| `{{Body}}` | Повний вміст вхідного повідомлення | +| `{{RawBody}}` | Необроблений вміст (без обгорток історії/відправника) | +| `{{BodyStripped}}` | Вміст без згадок групи | | `{{From}}` | Ідентифікатор відправника | -| `{{To}}` | Ідентифікатор призначення | +| `{{To}}` | Ідентифікатор місця призначення | | `{{MessageSid}}` | Ідентифікатор повідомлення каналу | -| `{{SessionId}}` | UUID поточної сесії | -| `{{IsNewSession}}` | `"true"`, коли створено нову сесію | +| `{{SessionId}}` | UUID поточного сеансу | +| `{{IsNewSession}}` | `"true"`, коли створено новий сеанс | | `{{MediaUrl}}` | Псевдо-URL вхідного медіа | | `{{MediaPath}}` | Локальний шлях до медіа | | `{{MediaType}}` | Тип медіа (зображення/аудіо/документ/…) | | `{{Transcript}}` | Транскрипт аудіо | -| `{{Prompt}}` | Розв’язаний запит медіа для записів CLI | +| `{{Prompt}}` | Розв’язаний медіапромпт для записів CLI | | `{{MaxChars}}` | Розв’язана максимальна кількість символів виводу для записів CLI | | `{{ChatType}}` | `"direct"` або `"group"` | | `{{GroupSubject}}` | Тема групи (за можливості) | @@ -1261,19 +1243,19 @@ 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) · [Doctor](/uk/gateway/doctor)_ +_Пов’язане: [Конфігурація](/uk/gateway/configuration) · [Приклади конфігурації](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_ -## Пов’язано +## Пов’язане - [Конфігурація](/uk/gateway/configuration) - [Приклади конфігурації](/uk/gateway/configuration-examples) diff --git a/docs/uk/gateway/doctor.md b/docs/uk/gateway/doctor.md index 39a81e222..0b2fd6e97 100644 --- a/docs/uk/gateway/doctor.md +++ b/docs/uk/gateway/doctor.md @@ -1,20 +1,20 @@ --- read_when: - Додавання або змінення міграцій doctor - - Запровадження несумісних змін конфігурації + - Впровадження несумісних змін конфігурації sidebarTitle: Doctor -summary: 'Команда Doctor: перевірки працездатності, міграції конфігурації та кроки відновлення' +summary: 'Команда doctor: перевірки стану, міграції конфігурації та кроки відновлення' title: Діагностика x-i18n: - generated_at: "2026-05-04T19:04:53Z" + generated_at: "2026-05-04T22:54:33Z" model: gpt-5.5 provider: openai - source_hash: e6b18967c4a352290057afc2da95f1d6a1389f46f9d1e49ad4864baf7b77d343 + source_hash: 86d862ccc56c0d979c2a957272b2e2f5c5fc7bb1ae8142748630ede0003891de source_path: gateway/doctor.md workflow: 16 --- -`openclaw doctor` — це інструмент ремонту й міграції для OpenClaw. Він виправляє застарілі конфігурацію/стан, перевіряє справність і надає дієві кроки для ремонту. +`openclaw doctor` — це інструмент ремонту та міграції для OpenClaw. Він виправляє застарілі конфігурацію/стан, перевіряє працездатність і надає практичні кроки для ремонту. ## Швидкий старт @@ -30,7 +30,7 @@ openclaw doctor openclaw doctor --yes ``` - Приймати типові значення без запитів (зокрема кроки ремонту перезапуску/служби/пісочниці, коли застосовно). + Прийняти типові значення без запитів (зокрема кроки ремонту перезапуску/служби/пісочниці, коли застосовно). @@ -54,7 +54,7 @@ openclaw doctor openclaw doctor --non-interactive ``` - Запускати без запитів і застосовувати лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії перезапуску/служби/пісочниці, які потребують підтвердження людини. Міграції застарілого стану запускаються автоматично після виявлення. + Запустити без запитів і застосовувати лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії перезапуску/служби/пісочниці, які потребують підтвердження людини. Міграції застарілого стану запускаються автоматично, коли їх виявлено. @@ -62,12 +62,12 @@ openclaw doctor openclaw doctor --deep ``` - Сканувати системні служби на наявність додаткових встановлень Gateway (launchd/systemd/schtasks). + Сканувати системні служби на наявність додаткових встановлень gateway (launchd/systemd/schtasks). -Якщо хочете переглянути зміни перед записом, спочатку відкрийте файл конфігурації: +Якщо ви хочете переглянути зміни перед записом, спершу відкрийте файл конфігурації: ```bash cat ~/.openclaw/openclaw.json @@ -76,63 +76,63 @@ cat ~/.openclaw/openclaw.json ## Що він робить (підсумок) - - - Необов’язкове попереднє оновлення для git-встановлень (лише інтерактивно). + + - Необов’язкове попереднє оновлення для встановлень із git (лише інтерактивно). - Перевірка актуальності протоколу UI (перезбирає Control UI, коли схема протоколу новіша). - - Перевірка справності + запит на перезапуск. - - Підсумок стану Skills (придатні/відсутні/заблоковані) і стан плагінів. + - Перевірка стану + запит на перезапуск. + - Підсумок стану Skills (придатні/відсутні/заблоковані) і стан Plugin. - Нормалізація конфігурації для застарілих значень. - - Міграція конфігурації Talk із застарілих плоских полів `talk.*` до `talk.provider` + `talk.providers.`. + - Міграція конфігурації Talk із застарілих пласких полів `talk.*` у `talk.provider` + `talk.providers.`. - Перевірки міграції браузера для застарілих конфігурацій розширення Chrome і готовності Chrome MCP. - Попередження про перевизначення провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). - Попередження про затінення Codex OAuth (`models.providers.openai-codex`). - Перевірка передумов OAuth TLS для профілів OpenAI Codex OAuth. - - Попередження allowlist плагінів/інструментів, коли `plugins.allow` є обмежувальним, але політика інструментів усе ще вимагає wildcard або інструменти, що належать плагінам. - - Міграція застарілого стану на диску (sessions/agent dir/WhatsApp auth). - - Міграція застарілих ключів контракту маніфесту плагіна (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). - - Міграція застарілого сховища cron (`jobId`, `schedule.cron`, поля доставки/payload верхнього рівня, payload `provider`, прості резервні завдання Webhook `notify: true`). - - Міграція застарілої політики виконання агента до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`. - - Очищення застарілої конфігурації плагінів, коли плагіни ввімкнені; коли `plugins.enabled=false`, застарілі посилання на плагіни вважаються інертною конфігурацією ізоляції та зберігаються. + - Попередження allowlist Plugin/інструментів, коли `plugins.allow` обмежувальний, але політика інструментів усе ще запитує wildcard або інструменти, що належать Plugin. + - Міграція застарілого стану на диску (сеанси/каталог агента/автентифікація WhatsApp). + - Міграція застарілих ключів контракту маніфесту Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). + - Міграція застарілого сховища cron (`jobId`, `schedule.cron`, поля доставки/навантаження верхнього рівня, payload `provider`, прості резервні webhook-завдання `notify: true`). + - Міграція застарілої runtime-політики агента до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`. + - Очищення застарілої конфігурації Plugin, коли plugins увімкнено; коли `plugins.enabled=false`, застарілі посилання на Plugin вважаються інертною конфігурацією стримування й зберігаються. - - Перевірка lock-файлів сесій і очищення застарілих lock-файлів. - - Ремонт транскриптів сесій для дубльованих гілок переписування prompt, створених ураженими збірками 2026.4.24. - - Виявлення tombstone відновлення після перезапуску завислого subagent, з підтримкою `--fix` для очищення застарілих прапорців перерваного відновлення, щоб під час запуску дочірній процес не продовжував вважатися перерваним перезапуском. - - Перевірки цілісності стану та дозволів (сесії, транскрипти, каталог стану). + - Перевірка файлів блокування сеансів і очищення застарілих блокувань. + - Ремонт транскриптів сеансів для дубльованих гілок переписування підказок, створених ураженими збірками 2026.4.24. + - Виявлення tombstone для відновлення після перезапуску завислих subagent, з підтримкою `--fix` для очищення застарілих aborted recovery flags, щоб запуск не продовжував вважати дочірній процес перерваним під час перезапуску. + - Перевірки цілісності стану та дозволів (сеанси, транскрипти, каталог стану). - Перевірки дозволів файлу конфігурації (chmod 600) під час локального запуску. - - Справність автентифікації моделей: перевіряє завершення строку дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє стани cooldown/disabled профілів автентифікації. - - Виявлення додаткового каталогу workspace (`~/openclaw`). + - Стан автентифікації моделі: перевіряє завершення OAuth, може оновлювати токени, термін яких спливає, і повідомляє про стани cooldown/disabled для auth-profile. + - Виявлення додаткового каталогу робочого простору (`~/openclaw`). - - Ремонт образу пісочниці, коли пісочницю ввімкнено. - - Міграція застарілої служби та виявлення додаткового Gateway. + - Ремонт образу пісочниці, коли sandboxing увімкнено. + - Міграція застарілих служб і виявлення додаткових gateway. - Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`). - - Перевірки виконання Gateway (служба встановлена, але не запущена; кешована мітка launchd). - - Попередження стану каналів (перевірено із запущеного Gateway). + - Runtime-перевірки Gateway (службу встановлено, але не запущено; кешована мітка launchd). + - Попередження про стан каналу (пробуються із запущеного gateway). - Аудит конфігурації супервізора (launchd/systemd/schtasks) з необов’язковим ремонтом. - - Очищення середовища вбудованого проксі для служб Gateway, які захопили значення shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час встановлення або оновлення. - - Перевірки найкращих практик виконання Gateway (Node проти Bun, шляхи менеджера версій). - - Діагностика конфліктів порту Gateway (типово `18789`). + - Очищення середовища вбудованого proxy для служб gateway, які захопили значення shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час встановлення або оновлення. + - Перевірки найкращих практик runtime Gateway (Node проти Bun, шляхи version-manager). + - Діагностика конфлікту портів Gateway (типовий `18789`). - Попередження безпеки для відкритих політик DM. - Перевірки автентифікації Gateway для режиму локального токена (пропонує генерацію токена, коли джерела токена немає; не перезаписує конфігурації token SecretRef). - - Виявлення проблем зі сполученням пристрою (очікувані запити першого сполучення, очікувані підвищення ролі/області, розбіжність застарілого локального кешу device-token і розбіжність автентифікації запису сполучення). + - Виявлення проблем зі сполученням пристрою (очікувані первинні запити на сполучення, очікувані підвищення ролі/обсягу, drift застарілого локального кешу device-token і drift автентифікації paired-record). - + - Перевірка systemd linger у Linux. - - Перевірка розміру bootstrap-файлу workspace (попередження про обрізання/наближення до ліміту для контекстних файлів). - - Перевірка готовності Skills для типового агента; повідомляє дозволені навички з відсутніми bin, env, config або вимогами OS, а `--fix` може вимкнути недоступні навички в `skills.entries`. - - Перевірка стану shell completion і автоматичне встановлення/оновлення. - - Перевірка готовності провайдера embeddings для пошуку пам’яті (локальна модель, ключ віддаленого API або бінарний файл QMD). - - Перевірки встановлення з джерел (невідповідність pnpm workspace, відсутні UI-ресурси, відсутній бінарний файл tsx). + - Перевірка розміру bootstrap-файлу робочого простору (попередження про обрізання/наближення до ліміту для контекстних файлів). + - Перевірка готовності Skills для типового агента; повідомляє про дозволені skills із відсутніми bins, env, config або вимогами ОС, а `--fix` може вимкнути недоступні skills у `skills.entries`. + - Перевірка стану shell completion та автоматичне встановлення/оновлення. + - Перевірка готовності провайдера embedding для пошуку пам’яті (локальна модель, remote API key або QMD binary). + - Перевірки source install (невідповідність pnpm workspace, відсутні UI assets, відсутній tsx binary). - Записує оновлену конфігурацію + метадані wizard. @@ -140,21 +140,21 @@ cat ~/.openclaw/openclaw.json ## Зворотне заповнення та скидання Dreams UI -Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для процесу grounded dreaming. Ці дії використовують RPC-методи Gateway у стилі doctor, але вони **не** є частиною ремонту/міграції CLI `openclaw doctor`. +Сцена Control UI Dreams містить дії **Backfill**, **Reset** і **Clear Grounded** для grounded dreaming workflow. Ці дії використовують RPC-методи у стилі gateway doctor, але вони **не** є частиною ремонту/міграції `openclaw doctor` CLI. Що вони роблять: -- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному workspace, запускає grounded REM diary pass і записує оборотні записи backfill до `DREAMS.md`. -- **Reset** видаляє з `DREAMS.md` лише ці позначені записи backfill diary. -- **Clear Grounded** видаляє лише staged grounded-only короткострокові записи, що походять з історичного replay і ще не накопичили live recall або daily support. +- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному робочому просторі, запускає прохід grounded REM diary і записує оборотні записи backfill у `DREAMS.md`. +- **Reset** видаляє лише ці позначені backfill diary entries із `DREAMS.md`. +- **Clear Grounded** видаляє лише staged grounded-only short-term entries, які походять з історичного replay і ще не накопичили live recall або daily support. -Чого вони **не** роблять самі по собі: +Що вони **не** роблять самі по собі: - вони не редагують `MEMORY.md` -- вони не запускають повні міграції doctor -- вони не додають автоматично grounded candidates до live short-term promotion store, якщо ви явно не запустите спочатку staged CLI path +- вони не запускають повні doctor migrations +- вони не додають grounded candidates автоматично до live short-term promotion store, якщо ви спершу явно не запустите staged CLI path -Якщо хочете, щоб grounded historical replay вплинув на звичайну deep promotion lane, натомість використовуйте CLI-потік: +Якщо ви хочете, щоб grounded historical replay впливав на звичайну deep promotion lane, натомість використовуйте CLI flow: ```bash openclaw memory rem-backfill --path ./memory --stage-short-term @@ -165,18 +165,20 @@ openclaw memory rem-backfill --path ./memory --stage-short-term ## Докладна поведінка та обґрунтування - - Якщо це git checkout і doctor запущено інтерактивно, він пропонує оновитися (fetch/rebase/build) перед запуском doctor. + + Якщо це git checkout і doctor працює інтерактивно, він пропонує оновити (fetch/rebase/build) перед запуском doctor. - Якщо конфігурація містить застарілі форми значень (наприклад `messages.ackReaction` без перевизначення для конкретного каналу), doctor нормалізує їх до поточної схеми. + Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без перевизначення для конкретного каналу), doctor нормалізує їх у поточну схему. - Це включає застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у map провайдера. + Це включає застарілі пласкі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у мапу провайдера. - Doctor також попереджає, коли `plugins.allow` не порожній, а політика інструментів використовує - wildcard або записи інструментів, що належать плагінам. `tools.allow: ["*"]` збігається лише з інструментами - з плагінів, які фактично завантажуються; він не обходить ексклюзивний - allowlist плагінів. + Doctor також попереджає, коли `plugins.allow` непорожній і політика інструментів використовує + wildcard або записи інструментів, що належать Plugin. `tools.allow: ["*"]` відповідає лише інструментам + із plugins, які фактично завантажуються; це не обходить ексклюзивний + allowlist Plugin. Doctor записує `plugins.bundledDiscovery: "compat"` для мігрованих + застарілих конфігурацій allowlist, щоб зберегти наявну поведінку bundled provider, а + потім вказує на суворіший параметр `"allowlist"`. @@ -186,9 +188,9 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - Пояснить, які застарілі ключі знайдено. - Покаже застосовану міграцію. - - Перепише `~/.openclaw/openclaw.json` з оновленою схемою. + - Перезапише `~/.openclaw/openclaw.json` оновленою схемою. - Gateway також автоматично запускає міграції doctor під час запуску, коли виявляє застарілий формат конфігурації, тож застарілі конфігурації ремонтуються без ручного втручання. Міграції сховища завдань Cron обробляються `openclaw doctor --fix`. + Gateway також автоматично запускає doctor migrations під час запуску, коли виявляє застарілий формат конфігурації, тож застарілі конфігурації ремонтуються без ручного втручання. Міграції сховища Cron job обробляються командою `openclaw doctor --fix`. Поточні міграції: @@ -199,7 +201,7 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `channels.telegram.requireMention` → `channels.telegram.groups."*".requireMention` - конфігурації налаштованих каналів без видимої політики відповідей → `messages.groupChat.visibleReplies: "message_tool"` - `routing.queue` → `messages.queue` - - `routing.bindings` → `bindings` верхнього рівня + - `routing.bindings` → верхньорівневий `bindings` - `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default` - застарілі `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.` - `routing.agentToAgent` → `tools.agentToAgent` @@ -215,24 +217,24 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider` - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` - - Для каналів з іменованими `accounts`, але залишковими значеннями каналу верхнього рівня для одного облікового запису, перемістіть ці значення з областю дії облікового запису в підвищений обліковий запис, вибраний для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/стандартну ціль) + - Для каналів з іменованими `accounts`, але з залишковими верхньорівневими значеннями каналу для одного облікового запису, перемістіть ці значення з областю дії облікового запису в просунутий обліковий запис, вибраний для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/типову ціль) - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents) - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - видалити `agents.defaults.llm`; використовуйте `models.providers..timeoutSeconds` для тайм-аутів повільних провайдерів/моделей - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` - - видалити `browser.relayBindHost` (застаріле налаштування ретрансляції розширення) - - застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (запуск Gateway також пропускає провайдерів, у яких `api` задано як майбутнє або невідоме значення enum, замість аварійного завершення) + - видалити `browser.relayBindHost` (застаріле налаштування ретранслятора розширення) + - застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (запуск Gateway також пропускає провайдерів, у яких `api` встановлено на майбутнє або невідоме значення enum, замість аварійно завершуватися у закритому режимі) - Попередження doctor також містять рекомендації щодо стандартного облікового запису для багатоканальних облікових записів: + Попередження doctor також містять поради щодо типового облікового запису для багатооблікових каналів: - - Якщо два або більше записів `channels..accounts` налаштовано без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис. - - Якщо `channels..defaultAccount` задано як невідомий ID облікового запису, doctor попереджає і перелічує налаштовані ID облікових записів. + - Якщо налаштовано два або більше записів `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис. + - Якщо `channels..defaultAccount` встановлено на невідомий ID облікового запису, doctor попереджає та перелічує налаштовані ID облікових записів. - - Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. Це може примусово спрямувати моделі на неправильний API або занулити витрати. Doctor попереджає, щоб ви могли видалити перевизначення та відновити маршрутизацію API і витрати для кожної моделі. + + Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. Це може примусово спрямувати моделі на неправильний API або обнулити витрати. Doctor попереджає, щоб ви могли видалити перевизначення та відновити маршрутизацію API + витрати для кожної моделі. Якщо ваша конфігурація браузера досі вказує на видалений шлях розширення Chrome, doctor нормалізує її до поточної моделі підключення Chrome MCP на локальному хості: @@ -242,262 +244,262 @@ openclaw memory rem-backfill --path ./memory --stage-short-term Doctor також перевіряє шлях Chrome MCP на локальному хості, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`: - - перевіряє, чи встановлено Google Chrome на тому самому хості для стандартних профілів автопідключення - - перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144 - - нагадує увімкнути віддалене налагодження на сторінці інспектування браузера (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`) + - перевіряє, чи встановлено Google Chrome на тому самому хості для типових профілів автопідключення + - перевіряє виявлену версію Chrome і попереджає, коли вона нижча за Chrome 144 + - нагадує увімкнути віддалене налагодження на сторінці інспекції браузера (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`) - Doctor не може увімкнути це налаштування на стороні Chrome за вас. Chrome MCP на локальному хості все ще потребує: + Doctor не може увімкнути налаштування на боці Chrome за вас. Chrome MCP на локальному хості все ще потребує: - - браузер на базі Chromium 144+ на хості gateway/node - - браузер запущено локально - - у цьому браузері увімкнено віддалене налагодження + - браузера на базі Chromium 144+ на хості Gateway/Node + - локально запущеного браузера + - увімкненого віддаленого налагодження в цьому браузері - схвалення першого запиту згоди на підключення в браузері - Готовність тут стосується лише передумов локального підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути на кшталт `responsebody`, експорту PDF, перехоплення завантажень і пакетних дій усе ще потребують керованого браузера або сирого профілю CDP. + Готовність тут стосується лише передумов локального підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, все ще потребують керованого браузера або сирого профілю CDP. Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших headless-потоків. Вони й надалі використовують сирий CDP. - Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє кінцеву точку авторизації OpenAI, щоб упевнитися, що локальний стек TLS Node/OpenSSL може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), doctor виводить рекомендації з виправлення для конкретної платформи. На macOS з Homebrew Node виправлення зазвичай таке: `brew postinstall ca-certificates`. З `--deep` перевірка виконується навіть тоді, коли gateway справний. + Коли налаштовано профіль OpenAI Codex OAuth, doctor опитує endpoint авторизації OpenAI, щоб перевірити, чи локальний стек Node/OpenSSL TLS може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), doctor виводить поради з виправлення для конкретної платформи. На macOS з Homebrew Node виправленням зазвичай є `brew postinstall ca-certificates`. З `--deep` перевірка виконується навіть якщо Gateway справний. - Якщо раніше ви додали застарілі налаштування транспорту OpenAI у `models.providers.openai-codex`, вони можуть перекрити вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі налаштування транспорту разом із Codex OAuth, щоб ви могли видалити або переписати застаріле перевизначення транспорту й повернути вбудовану поведінку маршрутизації/резервування. Користувацькі проксі та перевизначення лише заголовків усе ще підтримуються й не запускають це попередження. + Якщо раніше ви додали застарілі транспортні налаштування в `models.providers.openai-codex`, вони можуть затінити вбудований шлях провайдера Codex OAuth, який новіші релізи використовують автоматично. Doctor попереджає, коли бачить ці старі транспортні налаштування поруч із Codex OAuth, щоб ви могли видалити або переписати застаріле транспортне перевизначення та повернути вбудовану поведінку маршрутизації/резервування. Користувацькі проксі та перевизначення лише заголовків усе ще підтримуються й не спричиняють це попередження. - Коли ввімкнено вбудований Plugin Codex, doctor також перевіряє, чи посилання на основні моделі `openai-codex/*` досі розв’язуються через стандартний runner PI. Така комбінація коректна, коли ви хочете використовувати автентифікацію Codex OAuth/підписки через PI, але її легко сплутати з нативним app-server harness Codex. Doctor попереджає та вказує на явну форму app-server: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`. + Коли ввімкнено вбудований Plugin Codex, doctor також перевіряє, чи refs основної моделі `openai-codex/*` досі розв’язуються через типовий runner PI. Ця комбінація коректна, коли ви хочете використовувати Codex OAuth/автентифікацію підписки через PI, але її легко сплутати з нативним середовищем app-server Codex. Doctor попереджає та вказує на явну форму app-server: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`. - Doctor не виправляє це автоматично, оскільки обидва маршрути коректні: + Doctor не виправляє це автоматично, бо обидва маршрути коректні: - - `openai-codex/*` + PI означає "використовувати автентифікацію Codex OAuth/підписки через звичайний runner OpenClaw." - - `openai/*` + `agentRuntime.id: "codex"` означає "виконати вбудований turn через нативний app-server Codex." - - `/codex ...` означає "керувати нативною розмовою Codex або прив’язати її з чату." - - `/acp ...` або `runtime: "acp"` означає "використовувати зовнішній адаптер ACP/acpx." + - `openai-codex/*` + PI означає «використовувати Codex OAuth/автентифікацію підписки через звичайний runner OpenClaw». + - `openai/*` + `agentRuntime.id: "codex"` означає «запустити вбудований turn через нативний app-server Codex». + - `/codex ...` означає «керувати нативною розмовою Codex або прив’язати її з чату». + - `/acp ...` або `runtime: "acp"` означає «використовувати зовнішній адаптер ACP/acpx». - Якщо з’являється попередження, виберіть задуманий маршрут і відредагуйте конфігурацію вручну. Залиште попередження як є, коли PI Codex OAuth використовується навмисно. + Якщо з’являється попередження, виберіть задуманий маршрут і відредагуйте конфігурацію вручну. Залиште попередження як є, коли PI Codex OAuth є навмисним. - - Doctor може мігрувати старіші структури на диску до поточної структури: + + Doctor може мігрувати старіші дискові структури в поточну структуру: - - Сховище сеансів + transcripts: + - Сховище сеансів + транскрипти: - з `~/.openclaw/sessions/` до `~/.openclaw/agents//sessions/` - Каталог агента: - з `~/.openclaw/agent/` до `~/.openclaw/agents//agent/` - Стан автентифікації WhatsApp (Baileys): - із застарілих `~/.openclaw/credentials/*.json` (крім `oauth.json`) - - до `~/.openclaw/credentials/whatsapp//...` (стандартний ID облікового запису: `default`) + - до `~/.openclaw/credentials/whatsapp//...` (типовий ID облікового запису: `default`) - Ці міграції виконуються за принципом best-effort і є ідемпотентними; doctor виводитиме попередження, коли залишатиме будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сеанси + каталог агента під час запуску, щоб історія/автентифікація/моделі потрапляли в шлях для кожного агента без ручного запуску doctor. Автентифікацію WhatsApp навмисно мігрують лише через `openclaw doctor`. Нормалізація провайдера talk/мапи провайдерів тепер порівнює за структурною рівністю, тож відмінності лише в порядку ключів більше не запускають повторні no-op зміни `doctor --fix`. + Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor виводитиме попередження, коли залишає будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застаріле сховище сеансів + каталог агента під час запуску, щоб історія/автентифікація/моделі потрапляли в шлях для конкретного агента без ручного запуску doctor. Автентифікація WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація провайдера talk/карти провайдерів тепер порівнює за структурною рівністю, тому відмінності лише в порядку ключів більше не спричиняють повторних no-op змін `doctor --fix`. - Doctor сканує всі встановлені маніфести Plugin на наявність застарілих ключів можливостей верхнього рівня (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Коли їх знайдено, він пропонує перемістити їх в об’єкт `contracts` і переписати файл маніфесту на місці. Ця міграція ідемпотентна; якщо ключ `contracts` уже має такі самі значення, застарілий ключ видаляється без дублювання даних. + Doctor сканує всі маніфести встановлених Plugin на застарілі верхньорівневі ключі можливостей (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Коли знаходить їх, він пропонує перемістити їх в об’єкт `contracts` і переписати файл маніфесту на місці. Ця міграція є ідемпотентною; якщо ключ `contracts` уже має ті самі значення, застарілий ключ видаляється без дублювання даних. - - Doctor також перевіряє сховище завдань cron (`~/.openclaw/cron/jobs.json` за замовчуванням або `cron.store`, якщо перевизначено) на старі форми завдань, які планувальник досі приймає для сумісності. + + Doctor також перевіряє сховище завдань Cron (`~/.openclaw/cron/jobs.json` типово або `cron.store`, коли перевизначено) на старі форми завдань, які scheduler досі приймає для сумісності. - Поточні очищення cron включають: + Поточні очищення Cron містять: - `jobId` → `id` - `schedule.cron` → `schedule.expr` - - поля payload верхнього рівня (`message`, `model`, `thinking`, ...) → `payload` - - поля delivery верхнього рівня (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` - - псевдоніми delivery для `provider` у payload → явний `delivery.channel` - - прості застарілі резервні webhook-завдання `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook` + - верхньорівневі поля payload (`message`, `model`, `thinking`, ...) → `payload` + - верхньорівневі поля доставки (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` + - псевдоніми доставки payload `provider` → явний `delivery.channel` + - прості застарілі резервні Webhook-завдання `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook` - Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий резервний notify з наявним режимом доставки не через webhook, doctor попереджає і залишає це завдання для ручного перегляду. + Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий резервний notify із наявним режимом доставки не через Webhook, doctor попереджає та залишає це завдання для ручного перегляду. - На Linux doctor також попереджає, коли crontab користувача досі викликає застарілий `~/.openclaw/bin/ensure-whatsapp.sh`. Цей скрипт локального хоста не підтримується поточним OpenClaw і може записувати хибні повідомлення `Gateway inactive` до `~/.openclaw/logs/whatsapp-health.log`, коли cron не може звернутися до шини користувача systemd. Видаліть застарілий запис crontab за допомогою `crontab -e`; використовуйте `openclaw channels status --probe`, `openclaw doctor` і `openclaw gateway status` для поточних перевірок стану. + На Linux doctor також попереджає, коли crontab користувача досі викликає застарілий `~/.openclaw/bin/ensure-whatsapp.sh`. Цей скрипт на локальному хості не підтримується поточним OpenClaw і може записувати хибні повідомлення `Gateway inactive` до `~/.openclaw/logs/whatsapp-health.log`, коли Cron не може досягти користувацької шини systemd. Видаліть застарілий запис crontab за допомогою `crontab -e`; використовуйте `openclaw channels status --probe`, `openclaw doctor` і `openclaw gateway status` для поточних перевірок справності. - Doctor сканує кожен каталог сеансів агентів на наявність застарілих файлів блокування запису — файлів, що лишилися після аварійного завершення сеансу. Для кожного знайденого файла блокування він повідомляє: шлях, PID, чи PID досі активний, вік блокування та чи вважається воно застарілим (мертвий PID або старше за 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше друкує примітку та вказує повторно запустити з `--fix`. + Doctor сканує кожен каталог сеансу агента на застарілі файли блокування запису — файли, що залишилися після аварійного завершення сеансу. Для кожного знайденого файлу блокування він повідомляє: шлях, PID, чи PID досі активний, вік блокування та чи вважається воно застарілим (мертвий PID або старше за 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше виводить примітку й радить перезапустити з `--fix`. - - Doctor сканує JSONL-файли сеансів агентів на наявність дубльованої форми гілки, створеної помилкою переписування транскрипту промпта 2026.4.24: покинутий хід користувача з внутрішнім runtime-контекстом OpenClaw плюс активний сусідній елемент із тим самим видимим промптом користувача. У режимі `--fix` / `--repair` Doctor створює резервну копію кожного ураженого файла поруч з оригіналом і переписує транскрипт до активної гілки, щоб історія gateway і зчитувачі памʼяті більше не бачили дубльованих ходів. + + Doctor сканує JSONL-файли сеансів агента на дубльовану форму гілки, створену помилкою переписування транскрипту промпта 2026.4.24: покинутий хід користувача з внутрішнім runtime-контекстом OpenClaw та активний сусідній хід із тим самим видимим промптом користувача. У режимі `--fix` / `--repair` doctor створює резервну копію кожного ураженого файлу поруч з оригіналом і переписує транскрипт до активної гілки, щоб історія gateway і читачі пам’яті більше не бачили дубльованих ходів. - Каталог стану — це операційний мозковий стовбур. Якщо він зникне, ви втратите сеанси, облікові дані, журнали й конфігурацію (якщо не маєте резервних копій деінде). + Каталог стану — це операційний мозковий стовбур. Якщо він зникне, ви втратите сеанси, облікові дані, журнали та конфігурацію (якщо не маєте резервних копій в іншому місці). Doctor перевіряє: - - **Відсутній каталог стану**: попереджає про катастрофічну втрату стану, пропонує повторно створити каталог і нагадує, що не може відновити відсутні дані. - - **Дозволи каталогу стану**: перевіряє доступність для запису; пропонує відновити дозволи (і виводить підказку `chown`, коли виявлено невідповідність власника/групи). - - **Синхронізований із хмарою каталог стану на macOS**: попереджає, коли стан розміщується в iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, бо шляхи з синхронізацією можуть спричиняти повільніше I/O та гонки блокування/синхронізації. - - **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розміщується на джерелі монтування `mmcblk*`, бо випадкове I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час записів сеансів та облікових даних. - - **Відсутні каталоги сеансів**: `sessions/` і каталог сховища сеансів потрібні для збереження історії та уникнення аварій `ENOENT`. + - **Каталог стану відсутній**: попереджає про катастрофічну втрату стану, пропонує повторно створити каталог і нагадує, що не може відновити відсутні дані. + - **Дозволи каталогу стану**: перевіряє можливість запису; пропонує виправити дозволи (і виводить підказку `chown`, коли виявлено невідповідність власника/групи). + - **Каталог стану macOS із хмарною синхронізацією**: попереджає, коли стан розташовано під iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, оскільки шляхи із синхронізацією можуть спричиняти повільніший I/O та перегони блокувань/синхронізації. + - **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розташовано на джерелі монтування `mmcblk*`, оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час записів сеансів та облікових даних. + - **Каталоги сеансів відсутні**: `sessions/` і каталог сховища сеансів потрібні для збереження історії та уникнення аварій `ENOENT`. - **Невідповідність транскрипту**: попереджає, коли в нещодавніх записах сеансів бракує файлів транскриптів. - - **Основний сеанс "1-line JSONL"**: позначає, коли основний транскрипт має лише один рядок (історія не накопичується). - - **Кілька каталогів стану**: попереджає, коли в різних домашніх каталогах існує кілька папок `~/.openclaw` або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може розділитися між інсталяціями). - - **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, Doctor нагадує запустити його на віддаленому хості (стан зберігається там). - - **Дозволи файла конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групі/всім, і пропонує обмежити до `600`. + - **Головний сеанс "1-line JSONL"**: позначає випадок, коли головний транскрипт має лише один рядок (історія не накопичується). + - **Кілька каталогів стану**: попереджає, коли в домашніх каталогах існує кілька папок `~/.openclaw` або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може розділитися між інсталяціями). + - **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запустити його на віддаленому хості (стан зберігається там). + - **Дозволи конфігураційного файлу**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групі/всім, і пропонує посилити дозволи до `600`. - - Doctor перевіряє OAuth-профілі в сховищі автентифікації, попереджає, коли токени невдовзі завершаться або вже завершилися, і може безпечно оновити їх. Якщо профіль Anthropic OAuth/токена застарів, він пропонує ключ API Anthropic або шлях із setup-токеном Anthropic. Запити на оновлення зʼявляються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення. + + Doctor перевіряє OAuth-профілі у сховищі автентифікації, попереджає, коли токени скоро закінчаться або вже закінчилися, і може безпечно їх оновити. Якщо профіль Anthropic OAuth/токена застарів, він пропонує ключ API Anthropic або шлях setup-token Anthropic. Запити на оновлення з’являються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення. - Коли оновлення OAuth остаточно не вдається (наприклад, `refresh_token_reused`, `invalid_grant` або провайдер просить увійти знову), Doctor повідомляє, що потрібна повторна автентифікація, і друкує точну команду `openclaw models auth login --provider ...` для запуску. + Коли оновлення OAuth остаточно не вдається (наприклад, `refresh_token_reused`, `invalid_grant` або провайдер просить увійти знову), doctor повідомляє, що потрібна повторна автентифікація, і виводить точну команду `openclaw models auth login --provider ...`, яку слід запустити. Doctor також повідомляє про профілі автентифікації, які тимчасово непридатні через: - - короткі періоди очікування (обмеження швидкості/тайм-аути/збої автентифікації) - - довші вимкнення (проблеми з оплатою/кредитами) + - короткі cooldown-и (обмеження швидкості/тайм-аути/збої автентифікації) + - довші вимкнення (збої білінгу/кредитів) - - Якщо задано `hooks.gmail.model`, Doctor перевіряє посилання на модель за каталогом і allowlist та попереджає, коли воно не розвʼязується або заборонене. + + Якщо `hooks.gmail.model` задано, doctor перевіряє посилання на модель за каталогом і allowlist та попереджає, коли його неможливо розв’язати або воно заборонене. - - Коли sandboxing увімкнено, Doctor перевіряє образи Docker і пропонує зібрати їх або перемкнутися на legacy-назви, якщо поточного образу бракує. + + Коли sandboxing увімкнено, doctor перевіряє Docker-образи та пропонує зібрати або перейти на застарілі назви, якщо поточний образ відсутній. - - Doctor видаляє legacy проміжний стан залежностей Plugin, згенерований OpenClaw, у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Це охоплює застарілі згенеровані корені залежностей, старі каталоги етапу інсталяції, пакетні залишки від попереднього коду відновлення залежностей bundled-plugin, а також осиротілі або відновлені керовані npm-копії bundled `@openclaw/*` plugins, які можуть затіняти поточний bundled-маніфест. + + Doctor видаляє застарілий staging-стан залежностей Plugin, згенерований OpenClaw, у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Це охоплює застарілі згенеровані корені залежностей, старі каталоги install-stage, локальні для package залишки від попереднього коду виправлення залежностей bundled-plugin, а також осиротілі або відновлені керовані npm-копії bundled `@openclaw/*` plugins, які можуть затіняти поточний bundled manifest. - Doctor також може перевстановлювати налаштовані downloadable plugins, коли конфігурація посилається на них, але локальний реєстр Plugin не може їх знайти. Для зовнішнього винесення bundled-plugin 2026.5.2 Doctor автоматично встановлює downloadable plugins, які вже використовує наявна конфігурація, а потім покладається на `meta.lastTouchedVersion`, щоб виконати цей release-прохід лише один раз. Запуск Gateway і перезавантаження конфігурації не запускають менеджери пакетів; інсталяції Plugin лишаються явною роботою doctor/install/update. + Doctor також може повторно встановити налаштовані завантажувані plugins, коли конфігурація посилається на них, але локальний реєстр Plugin не може їх знайти. Для externalization bundled-plugin 2026.5.2 doctor автоматично встановлює завантажувані plugins, які вже використовує наявна конфігурація, а потім покладається на `meta.lastTouchedVersion`, щоб виконати цей релізний прохід лише один раз. Запуск Gateway і перезавантаження конфігурації не запускають менеджери пакетів; встановлення Plugin лишається явною роботою doctor/install/update. - Doctor виявляє legacy-служби gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити службу OpenClaw із поточним портом gateway. Він також може сканувати додаткові gateway-подібні служби й друкувати підказки з очищення. Служби gateway OpenClaw з іменами профілів вважаються повноцінними й не позначаються як "зайві". + Doctor виявляє застарілі служби gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити службу OpenClaw з поточним портом gateway. Він також може сканувати додаткові gateway-подібні служби й виводити підказки з очищення. Служби OpenClaw gateway з іменами профілів вважаються повноцінними й не позначаються як "extra." - На Linux, якщо користувацька служба gateway відсутня, але існує системна служба gateway OpenClaw, Doctor не встановлює автоматично другу користувацьку службу. Перевірте за допомогою `openclaw gateway status --deep` або `openclaw doctor --deep`, потім видаліть дублікат або задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли системний supervisor керує життєвим циклом gateway. + У Linux, якщо user-level служба gateway відсутня, але існує system-level служба OpenClaw gateway, doctor не встановлює автоматично другу user-level службу. Перевірте через `openclaw gateway status --deep` або `openclaw doctor --deep`, потім видаліть дублікат або задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли системний supervisor керує життєвим циклом gateway. - Коли обліковий запис каналу Matrix має очікувану або придатну до дії legacy-міграцію стану, Doctor (у режимі `--fix` / `--repair`) створює знімок перед міграцією, а потім запускає best-effort кроки міграції: legacy-міграцію стану Matrix і підготовку legacy зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, а запуск триває. У режимі лише для читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається. + Коли обліковий запис каналу Matrix має очікувану або придатну до дії міграцію застарілого стану, doctor (у режимі `--fix` / `--repair`) створює знімок перед міграцією, а потім виконує best-effort кроки міграції: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, а запуск продовжується. У режимі лише для читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається. - - Doctor тепер перевіряє стан сполучення пристроїв як частину звичайного проходу перевірки справності. + + Doctor тепер перевіряє стан спарювання пристроїв як частину звичайного проходу перевірки здоров’я. Що він повідомляє: - - очікувані запити першого сполучення - - очікувані підвищення ролі для вже сполучених пристроїв - - очікувані підвищення scope для вже сполучених пристроїв - - відновлення невідповідності відкритого ключа, коли id пристрою досі збігається, але ідентичність пристрою більше не збігається із затвердженим записом - - сполучені записи, яким бракує активного токена для затвердженої ролі - - сполучені токени, scope яких виходять за межі затвердженого базового рівня сполучення - - локальні кешовані записи device-token для поточної машини, що передують ротації токена на боці gateway або містять застарілі метадані scope + - очікувані запити на перше спарювання + - очікувані підвищення ролі для вже спарених пристроїв + - очікувані підвищення scope для вже спарених пристроїв + - виправлення невідповідності public-key, коли id пристрою досі збігається, але ідентичність пристрою більше не збігається із затвердженим записом + - спарені записи, яким бракує активного токена для затвердженої ролі + - спарені токени, чиї scopes відхилилися від затвердженої базової лінії спарювання + - локальні кешовані записи device-token для поточної машини, які передують ротації токена на стороні gateway або містять застарілі метадані scope - Doctor не схвалює автоматично запити на сполучення і не ротує автоматично токени пристроїв. Натомість він друкує точні наступні кроки: + Doctor не затверджує автоматично запити спарювання й не ротуються автоматично токени пристроїв. Натомість він виводить точні наступні кроки: - перегляньте очікувані запити за допомогою `openclaw devices list` - - схваліть точний запит за допомогою `openclaw devices approve ` + - затвердьте точний запит за допомогою `openclaw devices approve ` - згенеруйте свіжий токен ротацією за допомогою `openclaw devices rotate --device --role ` - - видаліть і повторно схваліть застарілий запис за допомогою `openclaw devices remove ` + - видаліть і повторно затвердьте застарілий запис за допомогою `openclaw devices remove ` - Це закриває поширену прогалину "already paired but still getting pairing required": Doctor тепер відрізняє перше сполучення від очікуваних підвищень ролі/scope і від дрейфу застарілого токена/ідентичності пристрою. + Це закриває поширену прогалину "already paired but still getting pairing required": doctor тепер відрізняє перше спарювання від очікуваних підвищень ролі/scope та від дрейфу застарілого токена/ідентичності пристрою. Doctor виводить попередження, коли провайдер відкритий для DM без allowlist або коли політику налаштовано небезпечним способом. - Якщо запуск відбувається як користувацька служба systemd, Doctor гарантує, що lingering увімкнено, щоб gateway залишався активним після виходу з системи. + Якщо запущено як systemd user service, doctor гарантує, що lingering увімкнено, щоб gateway залишався активним після виходу з системи. - - Doctor друкує підсумок стану робочого простору для агента за замовчуванням: + + Doctor виводить зведення стану робочого простору для агента за замовчуванням: - - **Стан Skills**: рахує придатні, з відсутніми вимогами та заблоковані allowlist skills. - - **Legacy-каталоги робочого простору**: попереджає, коли `~/openclaw` або інші legacy-каталоги робочого простору існують поруч із поточним робочим простором. - - **Стан Plugin**: рахує ввімкнені/вимкнені/помилкові plugins; перелічує ID Plugin для будь-яких помилок; повідомляє про можливості bundle plugin. + - **Стан Skills**: рахує eligible, missing-requirements і allowlist-blocked skills. + - **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору існують поруч із поточним робочим простором. + - **Стан Plugin**: рахує ввімкнені/вимкнені/помилкові plugins; перелічує Plugin IDs для будь-яких помилок; повідомляє можливості bundle plugin. - **Попередження сумісності Plugin**: позначає plugins, що мають проблеми сумісності з поточним runtime. - - **Діагностика Plugin**: показує будь-які попередження або помилки під час завантаження, виведені реєстром Plugin. + - **Діагностика Plugin**: показує будь-які попередження або помилки часу завантаження, які видав реєстр Plugin. - - Doctor перевіряє, чи bootstrap-файли робочого простору (наприклад, `AGENTS.md`, `CLAUDE.md` або інші інжектовані файли контексту) наближаються до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файла необроблену кількість символів проти інжектованої, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість інжектованих символів як частку від загального бюджету. Коли файли обрізані або близькі до ліміту, Doctor друкує поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. + + Doctor перевіряє, чи bootstrap-файли робочого простору (наприклад `AGENTS.md`, `CLAUDE.md` або інші інжектовані файли контексту) близькі до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файлу raw і injected кількість символів, відсоток truncation, причину truncation (`max/file` або `max/total`) і загальну кількість injected символів як частку загального бюджету. Коли файли truncate-яться або близькі до ліміту, doctor виводить поради з налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. - - Коли `openclaw doctor --fix` видаляє відсутній channel plugin, він також видаляє завислу конфігурацію в області каналу, що посилалася на цей Plugin: записи `channels.`, цілі Heartbeat, які називали канал, і перевизначення `agents.*.models["/*"]`. Це запобігає boot loop Gateway, коли runtime каналу зник, але конфігурація все ще просить gateway привʼязатися до нього. + + Коли `openclaw doctor --fix` видаляє відсутній Plugin каналу, він також видаляє dangling channel-scoped конфігурацію, що посилалася на цей Plugin: записи `channels.`, цілі Heartbeat, які називали канал, і перевизначення `agents.*.models["/*"]`. Це запобігає boot loop-ам Gateway, коли runtime каналу зник, але конфігурація все ще просить gateway прив’язатися до нього. - Doctor перевіряє, чи встановлено автодоповнення вкладкою для поточного shell (zsh, bash, fish або PowerShell): + Doctor перевіряє, чи встановлено tab completion для поточного shell (zsh, bash, fish або PowerShell): - - Якщо профіль shell використовує повільний шаблон динамічного автодоповнення (`source <(openclaw completion ...)`), Doctor оновлює його до швидшого варіанта з кешованим файлом. - - Якщо автодоповнення налаштовано в профілі, але кеш-файл відсутній, Doctor автоматично регенерує кеш. - - Якщо автодоповнення взагалі не налаштовано, Doctor пропонує встановити його (лише інтерактивний режим; пропускається з `--non-interactive`). + - Якщо профіль shell використовує повільний динамічний шаблон completion (`source <(openclaw completion ...)`), doctor оновлює його до швидшого варіанта з кешованим файлом. + - Якщо completion налаштовано в профілі, але файл кешу відсутній, doctor автоматично регенерує кеш. + - Якщо completion взагалі не налаштовано, doctor пропонує встановити його (лише інтерактивний режим; пропускається з `--non-interactive`). Запустіть `openclaw completion --write-state`, щоб регенерувати кеш вручну. - Doctor перевіряє готовність автентифікації токена локального gateway. + Doctor перевіряє готовність автентифікації локального gateway токеном. - - Якщо режим токена потребує токена й джерела токена не існує, Doctor пропонує згенерувати його. - - Якщо `gateway.auth.token` керується SecretRef, але недоступний, Doctor попереджає і не перезаписує його відкритим текстом. - - `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано SecretRef токена. + - Якщо режим токена потребує токена й джерела токена не існує, doctor пропонує згенерувати його. + - Якщо `gateway.auth.token` керується SecretRef, але недоступний, doctor попереджає й не перезаписує його plaintext. + - `openclaw doctor --generate-gateway-token` примусово генерує лише тоді, коли SecretRef токена не налаштовано. - - Деякі потоки відновлення мають перевіряти налаштовані облікові дані, не послаблюючи runtime-поведінку fail-fast. + + Деяким потокам виправлення потрібно перевіряти налаштовані облікові дані, не послаблюючи runtime поведінку fail-fast. - - `openclaw doctor --fix` тепер використовує ту саму модель підсумку SecretRef лише для читання, що й команди родини status, для цільових відновлень конфігурації. - - Приклад: відновлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використовувати налаштовані облікові дані бота, коли вони доступні. - - Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, Doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне розвʼязання замість аварійного завершення або хибного повідомлення, що токен відсутній. + - `openclaw doctor --fix` тепер використовує ту саму read-only модель зведення SecretRef, що й команди status-family, для цільових виправлень конфігурації. + - Приклад: виправлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані облікові дані бота, коли вони доступні. + - Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне розв’язання замість аварійного завершення або хибного повідомлення, що токен відсутній. - - Doctor виконує перевірку справності та пропонує перезапустити Gateway, коли він виглядає несправним. + + Doctor виконує перевірку стану та пропонує перезапустити gateway, коли він виглядає несправним. - - Doctor перевіряє, чи налаштований постачальник embedding для пошуку в памʼяті готовий для агента за замовчуванням. Поведінка залежить від налаштованого бекенда й постачальника: + + Doctor перевіряє, чи налаштований постачальник embedding для пошуку в пам’яті готовий для агента за замовчуванням. Поведінка залежить від налаштованого бекенда та постачальника: - - **Бекенд QMD**: перевіряє, чи доступний і придатний до запуску бінарний файл `qmd`. Якщо ні, виводить рекомендації щодо виправлення, зокрема npm-пакет і варіант ручного шляху до бінарного файлу. - - **Явний локальний постачальник**: перевіряє наявність локального файла моделі або розпізнаної віддаленої/завантажуваної URL-адреси моделі. Якщо її бракує, пропонує перейти на віддаленого постачальника. - - **Явний віддалений постачальник** (`openai`, `voyage` тощо): перевіряє, чи є API-ключ у середовищі або сховищі автентифікації. Якщо його бракує, виводить практичні підказки для виправлення. + - **Бекенд QMD**: перевіряє, чи доступний і чи може запускатися бінарний файл `qmd`. Якщо ні, виводить інструкції з виправлення, зокрема npm-пакет і варіант ручного шляху до бінарного файла. + - **Явний локальний постачальник**: перевіряє наявність локального файла моделі або розпізнаної віддаленої/завантажуваної URL-адреси моделі. Якщо немає, пропонує перемкнутися на віддаленого постачальника. + - **Явний віддалений постачальник** (`openai`, `voyage` тощо): перевіряє, чи є API-ключ у середовищі або сховищі автентифікації. Якщо його немає, виводить дієві підказки для виправлення. - **Автоматичний постачальник**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого постачальника в порядку автоматичного вибору. - Коли доступний кешований результат перевірки Gateway (Gateway був справним на момент перевірки), doctor зіставляє його результат із конфігурацією, видимою для CLI, і зазначає будь-яку невідповідність. Doctor не запускає новий embedding ping у типовому шляху; використовуйте команду глибокого статусу памʼяті, коли потрібна live-перевірка постачальника. + Коли доступний кешований результат проби gateway (gateway був справний на момент перевірки), doctor зіставляє його результат із конфігурацією, видимою для CLI, і зазначає будь-яку невідповідність. Doctor не запускає новий embedding ping у стандартному шляху; використовуйте команду глибокого стану пам’яті, коли потрібна жива перевірка постачальника. Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час виконання. - - Якщо Gateway справний, doctor запускає перевірку стану каналу й повідомляє попередження із запропонованими виправленнями. + + Якщо gateway справний, doctor запускає пробу стану каналів і повідомляє попередження із запропонованими виправленнями. - - Doctor перевіряє встановлену конфігурацію супервізора (launchd/systemd/schtasks) на відсутні або застарілі типові значення (наприклад, залежності systemd від network-online і затримку перезапуску). Коли знаходить невідповідність, він рекомендує оновлення й може переписати файл сервісу/завдання до поточних типових значень. + + Doctor перевіряє встановлену конфігурацію супервізора (launchd/systemd/schtasks) на відсутні або застарілі значення за замовчуванням (наприклад, залежності systemd від network-online і затримку перезапуску). Коли виявляє невідповідність, рекомендує оновлення та може переписати файл служби/завдання до поточних значень за замовчуванням. Примітки: - `openclaw doctor` запитує підтвердження перед переписуванням конфігурації супервізора. - - `openclaw doctor --yes` приймає типові запити на ремонт. + - `openclaw doctor --yes` приймає стандартні запити на відновлення. - `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів. - - `openclaw doctor --repair --force` перезаписує власні конфігурації супервізора. - - `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу сервісу Gateway. Він усе одно повідомляє про справність сервісу й виконує ремонти, не повʼязані із сервісом, але пропускає встановлення/запуск/перезапуск/bootstrap сервісу, переписування конфігурації супервізора й очищення застарілого сервісу, бо цим життєвим циклом керує зовнішній супервізор. - - У Linux doctor не переписує метадані команди/entrypoint, доки відповідний systemd-юніт Gateway активний. Він також ігнорує неактивні незастарілі додаткові Gateway-подібні юніти під час сканування дубльованих сервісів, щоб супутні файли сервісів не створювали зайвого шуму очищення. - - Якщо автентифікація токеном вимагає токен і `gateway.auth.token` керується SecretRef, встановлення/ремонт сервісу doctor перевіряє SecretRef, але не зберігає розвʼязані відкриті значення токена в метадані середовища сервісу супервізора. - - Doctor виявляє керовані `.env`/SecretRef-backed значення середовища сервісу, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудували inline, і переписує метадані сервісу так, щоб ці значення завантажувалися з джерела runtime, а не з визначення супервізора. - - Doctor виявляє, коли команда сервісу досі фіксує старий `--port` після зміни `gateway.port`, і переписує метадані сервісу на поточний порт. - - Якщо автентифікація токеном вимагає токен, а налаштований SecretRef токена не розвʼязується, doctor блокує шлях встановлення/ремонту з практичними рекомендаціями. - - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/ремонт, доки режим не буде задано явно. - - Для Linux user-systemd-юнітів перевірки дрейфу токена doctor тепер враховують джерела і `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації сервісу. - - Ремонти сервісу doctor відмовляються переписувати, зупиняти або перезапускати сервіс Gateway зі старішого бінарного файла OpenClaw, коли конфігурацію востаннє записала новіша версія. Див. [усунення несправностей Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). + - `openclaw doctor --repair --force` перезаписує користувацькі конфігурації супервізора. + - `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу служби gateway. Він і надалі повідомляє про стан служби та виконує відновлення, не пов’язані зі службою, але пропускає встановлення/запуск/перезапуск/bootstrap служби, переписування конфігурації супервізора та очищення застарілих служб, оскільки цим життєвим циклом керує зовнішній супервізор. + - У Linux doctor не переписує метадані команди/точки входу, поки відповідний systemd-модуль gateway активний. Він також ігнорує неактивні додаткові gateway-подібні модулі, які не є застарілими, під час сканування дубльованих служб, щоб супутні файли служб не створювали шуму очищення. + - Якщо автентифікація за токеном потребує токена, а `gateway.auth.token` керується SecretRef, встановлення/відновлення служби doctor перевіряє SecretRef, але не зберігає розв’язані значення токенів у відкритому тексті в метаданих середовища служби супервізора. + - Doctor виявляє керовані `.env`/SecretRef-backed значення середовища служби, які старіші інсталяції LaunchAgent, systemd або Windows Scheduled Task вбудовували inline, і переписує метадані служби так, щоб ці значення завантажувалися з джерела runtime, а не з визначення супервізора. + - Doctor виявляє, коли команда служби досі фіксує старий `--port` після зміни `gateway.port`, і переписує метадані служби на поточний порт. + - Якщо автентифікація за токеном потребує токена, а налаштований SecretRef токена не розв’язується, doctor блокує шлях встановлення/відновлення з дієвими інструкціями. + - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/відновлення, доки режим не буде задано явно. + - Для Linux user-systemd модулів перевірки doctor на розбіжність токенів тепер включають джерела `Environment=` і `EnvironmentFile=` під час порівняння метаданих автентифікації служби. + - Відновлення служби doctor відмовляються переписувати, зупиняти або перезапускати службу gateway зі старішого бінарного файла OpenClaw, коли конфігурацію востаннє записала новіша версія. Див. [усунення несправностей Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). - Ви завжди можете примусово виконати повне переписування через `openclaw gateway install --force`. - - Doctor перевіряє runtime сервісу (PID, останній статус виходу) і попереджає, коли сервіс встановлено, але він фактично не працює. Він також перевіряє конфлікти портів на порту Gateway (типово `18789`) і повідомляє ймовірні причини (Gateway уже запущений, SSH-тунель). + + Doctor перевіряє runtime служби (PID, останній статус виходу) і попереджає, коли службу встановлено, але вона фактично не працює. Він також перевіряє конфлікти портів на порту gateway (за замовчуванням `18789`) і повідомляє ймовірні причини (gateway уже працює, SSH-тунель). - Doctor попереджає, коли сервіс Gateway працює на Bun або шляху Node, керованому менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджерів версій можуть ламатися після оновлень, бо сервіс не завантажує ініціалізацію вашої оболонки. Doctor пропонує мігрувати на системне встановлення Node, коли воно доступне (Homebrew/apt/choco). + Doctor попереджає, коли служба gateway працює на Bun або шляху Node, керованому версіями (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджерів версій можуть ламатися після оновлень, оскільки служба не завантажує ініціалізацію вашої оболонки. Doctor пропонує мігрувати на системну інсталяцію Node, коли вона доступна (Homebrew/apt/choco). - Ново встановлені або відремонтовані macOS LaunchAgents використовують канонічний системний PATH (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) замість копіювання PATH інтерактивної оболонки, тому каталоги Volta, asdf, fnm, pnpm та інших менеджерів версій не змінюють, які дочірні процеси Node розвʼязуються. Linux-сервіси все ще зберігають явні корені середовища (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) і стабільні user-bin каталоги, але вгадані резервні каталоги менеджерів версій записуються в PATH сервісу лише тоді, коли ці каталоги існують на диску. + Нововстановлені або відновлені macOS LaunchAgents використовують канонічний системний PATH (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) замість копіювання PATH інтерактивної оболонки, тому каталоги Volta, asdf, fnm, pnpm та інших менеджерів версій не змінюють, який Node розв’язують дочірні процеси. Служби Linux усе ще зберігають явні корені середовища (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) і стабільні user-bin каталоги, але вгадані fallback-каталоги менеджерів версій записуються до PATH служби лише тоді, коли ці каталоги існують на диску. - Doctor зберігає будь-які зміни конфігурації та проставляє метадані майстра, щоб зафіксувати запуск doctor. + Doctor зберігає будь-які зміни конфігурації та ставить штамп метаданих майстра, щоб записати запуск doctor. - - Doctor пропонує систему памʼяті робочого простору, коли її бракує, і виводить пораду щодо резервної копії, якщо робочий простір ще не перебуває під git. + + Doctor пропонує систему пам’яті робочого простору, якщо її немає, і виводить пораду щодо резервного копіювання, якщо робочий простір ще не перебуває під git. - Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб отримати повний посібник зі структури робочого простору та резервного копіювання git (рекомендовано приватний GitHub або GitLab). + Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace) для повного посібника зі структури робочого простору та резервного копіювання git (рекомендовано приватний GitHub або GitLab). -## Повʼязане +## Пов’язане - [Runbook Gateway](/uk/gateway) - [Усунення несправностей Gateway](/uk/gateway/troubleshooting) diff --git a/docs/uk/tools/plugin.md b/docs/uk/tools/plugin.md index 0b8c35541..66966d6dc 100644 --- a/docs/uk/tools/plugin.md +++ b/docs/uk/tools/plugin.md @@ -4,38 +4,38 @@ read_when: - Розуміння правил виявлення та завантаження Plugin - Робота з пакетами Plugin, сумісними з Codex/Claude sidebarTitle: Install and Configure -summary: Встановлення, налаштування й керування плагінами OpenClaw +summary: Встановлюйте, налаштовуйте та керуйте Plugin OpenClaw title: Plugins x-i18n: - generated_at: "2026-05-03T17:12:20Z" + generated_at: "2026-05-04T22:54:53Z" model: gpt-5.5 provider: openai - source_hash: 30e3cffc15c5c52dd539e21103c207c9e38955f9fd3acd561a52964eefafb8f0 + source_hash: 1de640f7766a6b312a2385075ae1abdb19f5c2afcb0e7063eba0d3edde697004 source_path: tools/plugin.md workflow: 16 --- -Plugins розширюють OpenClaw новими можливостями: канали, постачальники моделей, -середовища агентів, інструменти, Skills, мовлення, транскрипція в реальному часі, -голос у реальному часі, розуміння медіа, генерація зображень, генерація відео, веботримання, вебпошук -та інше. Деякі plugins є **основними** (постачаються з OpenClaw), інші -є **зовнішніми**. Більшість зовнішніх plugins публікуються й виявляються через -[ClawHub](/uk/tools/clawhub). Npm і далі підтримується для прямих установлень і для -тимчасового набору пакетів plugins, що належать OpenClaw, поки ця міграція завершується. +Plugins розширюють OpenClaw новими можливостями: каналами, постачальниками моделей, +агентними обв’язками, інструментами, Skills, мовленням, транскрипцією в реальному часі, голосом у реальному часі, +розумінням медіа, генерацією зображень, генерацією відео, отриманням даних з вебу, вебпошуком +та іншим. Деякі plugins є **core** (постачаються з OpenClaw), інші +є **зовнішніми**. Більшість зовнішніх plugins публікуються й знаходяться через +[ClawHub](/uk/tools/clawhub). Npm і далі підтримується для прямих встановлень і для +тимчасового набору пакетів plugins, що належать OpenClaw, доки ця міграція завершується. ## Швидкий старт -Приклади встановлення, перегляду списку, видалення, оновлення та публікації для копіювання і вставлення див. +Приклади встановлення, перегляду списку, видалення, оновлення та публікації для копіювання й вставлення дивіться в [Керування plugins](/uk/plugins/manage-plugins). - + ```bash openclaw plugins list ``` - + ```bash # Search ClawHub plugins openclaw plugins search "calendar" @@ -56,26 +56,26 @@ Plugins розширюють OpenClaw новими можливостями: к - + ```bash openclaw gateway restart ``` - Потім налаштуйте в `plugins.entries.\.config` у вашому файлі конфігурації. + Потім налаштуйте в `plugins.entries.\.config` у своєму файлі конфігурації. - - У запущеному Gateway доступні лише власнику `/plugins enable` і `/plugins disable` - запускають перезавантажувач конфігурації Gateway. Gateway перезавантажує runtime-поверхні - plugin у поточному процесі, а нові ходи агента перебудовують свій список інструментів з + + У запущеному Gateway команди лише для власника `/plugins enable` і `/plugins disable` + запускають перезавантажувач конфігурації Gateway. Gateway перезавантажує runtime-поверхні plugin + у процесі, а нові ходи агента перебудовують свій список інструментів з оновленого реєстру. `/plugins install` змінює вихідний код plugin, тому - Gateway запитує перезапуск замість того, щоб удавати, ніби поточний процес може + Gateway запитує перезапуск замість того, щоб вдавати, ніби поточний процес може безпечно перезавантажити вже імпортовані модулі. - + ```bash openclaw plugins inspect --runtime --json @@ -83,14 +83,14 @@ Plugins розширюють OpenClaw новими можливостями: к openclaw --help ``` - Використовуйте `--runtime`, коли потрібно довести зареєстровані інструменти, сервіси, методи gateway, - хуки або CLI-команди, що належать plugin. Звичайний `inspect` є холодною - перевіркою маніфесту/реєстру й навмисно уникає імпорту runtime plugin. + Використовуйте `--runtime`, коли потрібно підтвердити зареєстровані інструменти, служби, методи gateway, + hooks або CLI-команди, що належать plugin. Звичайний `inspect` — це холодна + перевірка маніфесту/реєстру, яка навмисно уникає імпортування runtime plugin. -Якщо ви віддаєте перевагу керуванню безпосередньо з чату, увімкніть `commands.plugins: true` і використовуйте: +Якщо ви надаєте перевагу керуванню з чату, увімкніть `commands.plugins: true` і використовуйте: ```text /plugin install clawhub: @@ -98,54 +98,54 @@ Plugins розширюють OpenClaw новими можливостями: к /plugin enable ``` -Шлях встановлення використовує той самий резолвер, що й CLI: локальний шлях/архів, явний -`clawhub:`, явний `npm:`, явний `git:` або проста специфікація пакета +Шлях встановлення використовує той самий resolver, що й CLI: локальний шлях/архів, явний +`clawhub:`, явний `npm:`, явний `git:` або специфікацію пакета без префікса через npm. -Якщо конфігурація недійсна, встановлення зазвичай відмовляє закрито й спрямовує вас до -`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях перевстановлення -вбудованого plugin для plugins, які явно обирають +Якщо конфігурація недійсна, встановлення зазвичай завершується закрито та спрямовує вас до +`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях перевстановлення bundled-plugin +для plugins, які явно вмикають `openclaw.install.allowInvalidConfigRecovery`. -Під час запуску Gateway недійсна конфігурація plugin відмовляє закрито, як і будь-яка інша недійсна +Під час запуску Gateway недійсна конфігурація plugin завершується закрито, як і будь-яка інша недійсна конфігурація. Запустіть `openclaw doctor --fix`, щоб ізолювати погану конфігурацію plugin, -вимкнувши цей запис plugin і видаливши його недійсне корисне навантаження конфігурації; звичайна +вимкнувши цей запис plugin і видаливши його недійсний payload конфігурації; звичайна резервна копія конфігурації зберігає попередні значення. -Коли конфігурація каналу посилається на plugin, який більше не виявляється, але той самий -застарілий id plugin лишається в конфігурації plugin або записах установлення, запуск Gateway +Коли конфігурація каналу посилається на plugin, який більше не можна знайти, але +той самий застарілий id plugin лишається в конфігурації plugin або записах встановлення, запуск Gateway записує попередження в журнали й пропускає цей канал замість блокування всіх інших каналів. Запустіть `openclaw doctor --fix`, щоб видалити застарілі записи каналу/plugin; невідомі -ключі каналів без доказів застарілого plugin і далі не проходять валідацію, щоб помилки друку залишались +ключі каналів без доказів застарілого plugin і далі не проходять перевірку, щоб друкарські помилки лишалися помітними. -Якщо задано `plugins.enabled: false`, застарілі посилання на plugin трактуються як інертні: +Якщо встановлено `plugins.enabled: false`, застарілі посилання на plugin вважаються інертними: запуск Gateway пропускає роботу з виявлення/завантаження plugin, а `openclaw doctor` зберігає -вимкнену конфігурацію plugin замість автоматичного видалення. Повторно ввімкніть plugins перед +вимкнену конфігурацію plugin замість її автоматичного видалення. Повторно увімкніть plugins перед запуском очищення doctor, якщо хочете видалити застарілі id plugin. -Установлення залежностей plugin відбувається лише під час явних потоків install/update або -виправлення doctor. Запуск Gateway, перезавантаження конфігурації та інспекція runtime не -запускають менеджери пакетів і не відновлюють дерева залежностей. Локальні plugins вже повинні -мати встановлені залежності, тоді як npm, git і ClawHub plugins встановлюються -в керовані корені plugin OpenClaw. Залежності npm можуть бути підняті -в межах керованого npm-кореня OpenClaw; install/update сканує цей керований корінь перед +Встановлення залежностей plugin відбувається лише під час явних потоків install/update або +відновлення doctor. Запуск Gateway, перезавантаження конфігурації та runtime-інспекція +не запускають менеджери пакетів і не відновлюють дерева залежностей. Локальні plugins уже повинні +мати встановлені залежності, тоді як npm, git і ClawHub plugins +встановлюються під керованими коренями plugins OpenClaw. Залежності npm можуть бути hoisted +у межах керованого npm-кореня OpenClaw; install/update сканує цей керований корінь перед довірою, а uninstall видаляє керовані npm пакети через npm. Зовнішні plugins -і власні шляхи завантаження все одно мають бути встановлені через `openclaw plugins install`. +і користувацькі шляхи завантаження все одно мають встановлюватися через `openclaw plugins install`. Використовуйте `openclaw plugins list --json`, щоб побачити статичний `dependencyStatus` для кожного -видимого plugin без імпорту runtime-коду або відновлення залежностей. -Див. [Розв’язання залежностей Plugin](/uk/plugins/dependency-resolution) щодо +видимого plugin без імпорту runtime-коду чи відновлення залежностей. +Дивіться [Розв’язання залежностей Plugin](/uk/plugins/dependency-resolution) для життєвого циклу під час встановлення. -Для npm-встановлень змінні селектори, такі як `latest` або dist-tag, розв’язуються -перед установленням, а потім закріплюються на точній перевіреній версії в керованому +Для встановлень npm змінні селектори, як-от `latest` або dist-tag, розв’язуються +перед встановленням, а потім закріплюються за точною перевіреною версією в керованому npm-корені OpenClaw. Після завершення npm OpenClaw перевіряє, що встановлений -запис `package-lock.json` досі відповідає розв’язаній версії та цілісності. Якщо -npm записує інші метадані пакета, установлення завершується помилкою, а керований пакет +запис `package-lock.json` і далі відповідає розв’язаній версії та integrity. Якщо +npm записує інші метадані пакета, встановлення завершується помилкою, а керований пакет відкочується замість прийняття іншого артефакту plugin. -Вихідні checkout-и є pnpm workspaces. Якщо ви клонуєте OpenClaw, щоб працювати над вбудованими -plugins, запустіть `pnpm install`; після цього OpenClaw завантажує вбудовані plugins з -`extensions/`, тому зміни та локальні для пакета залежності використовуються напряму. -Звичайні встановлення в npm root призначені для пакетованого OpenClaw, а не для розробки -у checkout вихідного коду. +Вихідні checkout-и є pnpm workspaces. Якщо ви клонували OpenClaw, щоб працювати над bundled +plugins, запустіть `pnpm install`; після цього OpenClaw завантажуватиме bundled plugins з +`extensions/`, тож зміни й локальні для пакета залежності використовуватимуться напряму. +Звичайні npm-встановлення в корінь призначені для упакованого OpenClaw, а не для розробки +з вихідного checkout. ## Типи Plugin @@ -153,30 +153,30 @@ OpenClaw розпізнає два формати plugin: | Формат | Як це працює | Приклади | | ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ | -| **Нативний** | `openclaw.plugin.json` + runtime-модуль; виконується в процесі | Офіційні plugins, npm-пакети спільноти | -| **Bundle** | Сумісна з Codex/Claude/Cursor структура; зіставляється з функціями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | +| **Native** | `openclaw.plugin.json` + runtime-модуль; виконується в процесі | Офіційні plugins, npm-пакети спільноти | +| **Bundle** | Сумісна з Codex/Claude/Cursor структура; відображається на можливості OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | -Обидва з’являються в `openclaw plugins list`. Див. [Plugin Bundles](/uk/plugins/bundles) для подробиць про bundle. +Обидва відображаються в `openclaw plugins list`. Дивіться [Plugin Bundles](/uk/plugins/bundles) для подробиць про bundles. -Якщо ви пишете нативний plugin, почніть з [Створення Plugins](/uk/plugins/building-plugins) +Якщо ви пишете native plugin, почніть із [Створення Plugins](/uk/plugins/building-plugins) і [Огляд Plugin SDK](/uk/plugins/sdk-overview). -## Точки входу пакета +## Точки входу пакетів -Нативні npm-пакети plugin мають оголошувати `openclaw.extensions` у `package.json`. -Кожен запис має залишатися всередині каталогу пакета й розв’язуватися до читабельного -runtime-файлу або до вихідного TypeScript-файлу з виведеним зібраним JavaScript -відповідником, як-от `src/index.ts` до `dist/index.js`. -Пакетовані встановлення мають постачати цей JavaScript runtime-вивід. Резервний варіант із -вихідним TypeScript призначений для checkout-ів вихідного коду та шляхів локальної розробки, а не для -npm-пакетів, установлених у керований корінь plugin OpenClaw. +Npm-пакети native plugin мають оголошувати `openclaw.extensions` у `package.json`. +Кожен запис має лишатися всередині каталогу пакета й розв’язуватися в читабельний +runtime-файл або в вихідний TypeScript-файл із виведеним збудованим JavaScript +peer, наприклад `src/index.ts` до `dist/index.js`. +Упаковані встановлення мають постачати цей JavaScript runtime output. Fallback на TypeScript +source призначений для checkout-ів з вихідного коду та локальних шляхів розробки, а не для +npm-пакетів, установлених у керований корінь plugins OpenClaw. -Використовуйте `openclaw.runtimeExtensions`, коли опубліковані runtime-файли не розміщені за -тими самими шляхами, що й вихідні записи. Коли `runtimeExtensions` присутній, він має містити -рівно один запис для кожного запису `extensions`. Невідповідні списки провалюють встановлення та -виявлення plugin, а не тихо повертаються до вихідних шляхів. Якщо ви також -публікуєте `openclaw.setupEntry`, використовуйте `openclaw.runtimeSetupEntry` для його зібраного -JavaScript-відповідника; цей файл є обов’язковим, коли оголошений. +Використовуйте `openclaw.runtimeExtensions`, коли опубліковані runtime-файли не розташовані за +тими самими шляхами, що й source-записи. Якщо `runtimeExtensions` присутній, він має містити +рівно один запис для кожного запису `extensions`. Невідповідні списки призводять до помилки встановлення та +виявлення plugin замість тихого fallback до source-шляхів. Якщо ви також +публікуєте `openclaw.setupEntry`, використовуйте `openclaw.runtimeSetupEntry` для його збудованого +JavaScript peer; цей файл є обов’язковим, якщо оголошений. ```json { @@ -192,14 +192,14 @@ JavaScript-відповідника; цей файл є обов’язкови ### Npm-пакети, що належать OpenClaw, під час міграції -ClawHub є основним шляхом розповсюдження для більшості plugins. Поточні пакетовані -випуски OpenClaw уже містять багато офіційних plugins, тому в нормальних налаштуваннях їм не потрібні -окремі npm-встановлення. Поки кожен plugin, що належить OpenClaw, не -мігрував до ClawHub, OpenClaw і далі постачає деякі пакети plugin `@openclaw/*` в -npm для старіших/власних установлень і прямих npm-процесів. +ClawHub є основним шляхом дистрибуції для більшості plugins. Поточні упаковані +випуски OpenClaw уже bundling багато офіційних plugins, тому їм не потрібні +окремі npm-встановлення у звичайних налаштуваннях. Доки кожен plugin, що належить OpenClaw, не +мігрує до ClawHub, OpenClaw все ще постачає деякі пакети plugins `@openclaw/*` на +npm для старіших/користувацьких встановлень і прямих npm workflows. -Якщо npm повідомляє, що пакет plugin `@openclaw/*` застарілий, ця версія пакета -походить зі старішої лінійки зовнішніх пакетів. Використовуйте вбудований plugin з +Якщо npm повідомляє, що пакет plugin `@openclaw/*` deprecated, ця версія пакета +походить зі старішої зовнішньої лінії пакетів. Використовуйте bundled plugin з поточного OpenClaw або локальний checkout, доки не буде опубліковано новіший npm-пакет. | Plugin | Пакет | Документація | @@ -218,10 +218,10 @@ npm для старіших/власних установлень і прями | Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) | | Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) | -### Основні (постачаються з OpenClaw) +### Core (постачається з OpenClaw) - + `anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`, `huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`, `moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`, @@ -230,26 +230,26 @@ npm для старіших/власних установлень і прями - - `memory-core` — вбудований пошук пам’яті (типово через `plugins.slots.memory`) - - `memory-lancedb` — довгострокова пам’ять на основі LanceDB з автоматичним пригадуванням/захопленням (задайте `plugins.slots.memory = "memory-lancedb"`) + - `memory-core` — bundled memory search (типово через `plugins.slots.memory`) + - `memory-lancedb` — довготривала пам’ять на базі LanceDB з автоматичними recall/capture (встановіть `plugins.slots.memory = "memory-lancedb"`) - Див. [Memory LanceDB](/uk/plugins/memory-lancedb) щодо сумісного з OpenAI - налаштування embeddings, прикладів Ollama, обмежень пригадування та усунення несправностей. + Дивіться [Memory LanceDB](/uk/plugins/memory-lancedb) для OpenAI-сумісного + налаштування embedding, прикладів Ollama, лімітів recall і усунення несправностей. - + `elevenlabs`, `microsoft` - - - `browser` — вбудований browser plugin для інструмента browser, CLI `openclaw browser`, gateway-методу `browser.request`, browser runtime і стандартного сервісу керування browser (увімкнено типово; вимкніть перед заміною) - - `copilot-proxy` — міст VS Code Copilot Proxy (вимкнено типово) + + - `browser` — bundled browser plugin для browser tool, CLI `openclaw browser`, gateway-методу `browser.request`, browser runtime і стандартної служби керування браузером (увімкнено за замовчуванням; вимкніть перед заміною) + - `copilot-proxy` — міст VS Code Copilot Proxy (вимкнено за замовчуванням) -Шукаєте сторонні plugins? Див. [Plugins спільноти](/uk/plugins/community). +Шукаєте сторонні plugins? Дивіться [Plugins спільноти](/uk/plugins/community). ## Конфігурація @@ -267,31 +267,39 @@ npm для старіших/власних установлень і прями } ``` -| Поле | Опис | -| ---------------- | --------------------------------------------------------- | -| `enabled` | Головний перемикач (за замовчуванням: `true`) | -| `allow` | Список дозволених Plugin (необов'язково) | -| `deny` | Список заборонених Plugin (необов'язково; заборона має пріоритет) | -| `load.paths` | Додаткові файли/каталоги Plugin | -| `slots` | Ексклюзивні селектори слотів (наприклад, `memory`, `contextEngine`) | -| `entries.\` | Перемикачі та конфігурація для окремих Plugin | +| Поле | Опис | +| ------------------ | --------------------------------------------------------- | +| `enabled` | Головний перемикач (за замовчуванням: `true`) | +| `allow` | Список дозволених Plugin (необов’язково) | +| `bundledDiscovery` | Режим виявлення вбудованих Plugin (`allowlist` за замовчуванням) | +| `deny` | Список заборонених Plugin (необов’язково; заборона має пріоритет) | +| `load.paths` | Додаткові файли/каталоги Plugin | +| `slots` | Ексклюзивні селектори слотів (наприклад, `memory`, `contextEngine`) | +| `entries.\` | Перемикачі й конфігурація для окремого Plugin | `plugins.allow` є ексклюзивним. Коли він непорожній, завантажуватися -або надавати інструменти можуть лише перелічені Plugin, навіть якщо `tools.allow` містить `"*"` або конкретну назву +або надавати інструменти можуть лише перелічені plugins, навіть якщо `tools.allow` містить `"*"` або конкретну назву інструмента, що належить Plugin. Якщо список дозволених інструментів посилається на інструменти Plugin, додайте ідентифікатори Plugin-власників -до `plugins.allow` або вилучіть `plugins.allow`; `openclaw doctor` попереджає про таку +до `plugins.allow` або видаліть `plugins.allow`; `openclaw doctor` попереджає про таку форму. -Зміни конфігурації, внесені через `/plugins enable` або `/plugins disable`, запускають -перезавантаження Plugin Gateway у межах процесу. Нові ходи агента перебудовують свій список інструментів із +`plugins.bundledDiscovery` за замовчуванням має значення `"allowlist"` для нових конфігурацій, тому +обмежувальний інвентар `plugins.allow` також блокує пропущені вбудовані +plugins постачальників, зокрема виявлення постачальника вебпошуку під час виконання. Doctor позначає старіші +обмежувальні конфігурації списку дозволених як `"compat"` під час міграції, щоб оновлення зберігали +успадковану поведінку вбудованих постачальників, доки оператор не ввімкне суворіший режим. +Порожній `plugins.allow` усе ще вважається невстановленим/відкритим. + +Зміни конфігурації, зроблені через `/plugins enable` або `/plugins disable`, запускають +перезавантаження Plugin у Gateway в межах поточного процесу. Нові ходи агента перебудовують свій список інструментів із оновленого реєстру Plugin. Операції, що змінюють джерело, як-от встановлення, оновлення та видалення, усе ще перезапускають процес Gateway, оскільки вже імпортовані модулі Plugin не можна безпечно замінити на місці. `openclaw plugins list` — це локальний знімок реєстру/конфігурації Plugin. Plugin зі станом -`enabled` там означає, що збережений реєстр і поточна конфігурація дозволяють цьому +`enabled` там означає, що збережений реєстр і поточна конфігурація дозволяють Plugin брати участь. Це не доводить, що вже запущений віддалений Gateway -перезавантажився або перезапустився з тим самим кодом Plugin. У налаштуваннях VPS/контейнерів +перезавантажився або перезапустився з тим самим кодом Plugin. У середовищах VPS/контейнерів із процесами-обгортками надсилайте перезапуски або записи, що запускають перезавантаження, фактичному процесу `openclaw gateway run`, або використовуйте `openclaw gateway restart` для запущеного Gateway, коли перезавантаження повідомляє про помилку. @@ -299,88 +307,88 @@ Plugin брати участь. Це не доводить, що вже запу - **Вимкнений**: Plugin існує, але правила ввімкнення його вимкнули. Конфігурація зберігається. - **Відсутній**: конфігурація посилається на ідентифікатор Plugin, який виявлення не знайшло. - - **Недійсний**: Plugin існує, але його конфігурація не відповідає оголошеній схемі. Запуск Gateway пропускає лише цей Plugin; `openclaw doctor --fix` може помістити недійсний запис у карантин, вимкнувши його та вилучивши його конфігураційне навантаження. + - **Недійсний**: Plugin існує, але його конфігурація не відповідає оголошеній схемі. Запуск Gateway пропускає лише цей Plugin; `openclaw doctor --fix` може ізолювати недійсний запис, вимкнувши його та видаливши його конфігураційне навантаження. ## Виявлення та пріоритет -OpenClaw сканує Plugin у такому порядку (перший збіг перемагає): +OpenClaw сканує plugins у такому порядку (перший збіг перемагає): `plugins.load.paths` — явні шляхи до файлів або каталогів. Шляхи, що вказують назад на власні упаковані каталоги вбудованих Plugin OpenClaw, ігноруються; - виконайте `openclaw doctor --fix`, щоб вилучити ці застарілі псевдоніми. + запустіть `openclaw doctor --fix`, щоб видалити ці застарілі псевдоніми. - + `\/.openclaw//*.ts` і `\/.openclaw//*/index.ts`. - + `~/.openclaw//*.ts` і `~/.openclaw//*/index.ts`. - + Постачаються з OpenClaw. Багато з них увімкнені за замовчуванням (постачальники моделей, мовлення). Інші потребують явного ввімкнення. -Упаковані встановлення та образи Docker зазвичай визначають вбудовані Plugin з -скомпільованого дерева `dist/extensions`. Якщо вихідний каталог вбудованого Plugin -змонтовано поверх відповідного упакованого вихідного шляху, наприклад -`/app/extensions/synology-chat`, OpenClaw розглядає цей змонтований вихідний каталог -як вбудоване вихідне накладання та виявляє його перед упакованим -пакетом `/app/dist/extensions/synology-chat`. Це зберігає працездатність контейнерних -циклів супровідників без перемикання кожного вбудованого Plugin назад на вихідний код TypeScript. -Установіть `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, щоб примусово використовувати упаковані dist-пакети -навіть за наявності змонтованих вихідних накладань. +Упаковані встановлення та Docker-образи зазвичай розв’язують вбудовані plugins із +скомпільованого дерева `dist/extensions`. Якщо каталог вихідного коду вбудованого Plugin +змонтовано поверх відповідного упакованого шляху до вихідного коду, наприклад +`/app/extensions/synology-chat`, OpenClaw розглядає цей змонтований каталог вихідного коду +як вихідне накладання вбудованого Plugin і виявляє його перед упакованим +пакетом `/app/dist/extensions/synology-chat`. Це дає змогу підтримувати контейнерні +цикли супроводжувачів без перемикання кожного вбудованого Plugin назад на вихідний код TypeScript. +Установіть `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, щоб примусово використовувати упаковані dist-пакети, +навіть коли наявні монтування вихідних накладань. ### Правила ввімкнення -- `plugins.enabled: false` вимикає всі Plugin і пропускає роботу з виявлення/завантаження Plugin -- `plugins.deny` завжди має пріоритет над allow +- `plugins.enabled: false` вимикає всі plugins і пропускає роботу з виявлення/завантаження Plugin +- `plugins.deny` завжди має пріоритет над дозволом - `plugins.entries.\.enabled: false` вимикає цей Plugin -- Plugin з походженням із робочого простору **вимкнені за замовчуванням** (їх потрібно явно ввімкнути) -- Вбудовані Plugin дотримуються вбудованого набору ввімкнених за замовчуванням, якщо це не перевизначено +- Plugins походженням із робочого простору **вимкнені за замовчуванням** (їх потрібно явно ввімкнути) +- Вбудовані plugins дотримуються вбудованого набору увімкнених за замовчуванням, якщо це не перевизначено - Ексклюзивні слоти можуть примусово ввімкнути вибраний Plugin для цього слота -- Деякі вбудовані opt-in Plugin вмикаються автоматично, коли конфігурація називає - поверхню, що належить Plugin, як-от посилання на модель постачальника, конфігурація каналу або - runtime стенда +- Деякі вбудовані opt-in plugins вмикаються автоматично, коли конфігурація називає + поверхню, що належить Plugin, як-от посилання на модель постачальника, конфігурацію каналу або runtime + випробувального стенда - Застаріла конфігурація Plugin зберігається, доки активний `plugins.enabled: false`; - повторно ввімкніть Plugin перед запуском очищення doctor, якщо хочете вилучити застарілі ідентифікатори + повторно ввімкніть plugins перед запуском очищення doctor, якщо хочете видалити застарілі ідентифікатори - Маршрути Codex сімейства OpenAI зберігають окремі межі Plugin: - `openai-codex/*` належить OpenAI Plugin, тоді як вбудований Plugin app-server Codex + `openai-codex/*` належить до Plugin OpenAI, тоді як вбудований Plugin сервера застосунку Codex вибирається через `agentRuntime.id: "codex"` або застарілі - посилання на модель `codex/*` + посилання на моделі `codex/*` -## Усунення проблем із runtime-хуками +## Усунення неполадок runtime hooks -Якщо Plugin відображається в `plugins list`, але побічні ефекти або хуки `register(api)` -не виконуються в живому чат-трафіку, спершу перевірте це: +Якщо Plugin з’являється у `plugins list`, але побічні ефекти `register(api)` або hooks +не виконуються в живому трафіку чату, спочатку перевірте таке: -- Виконайте `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні +- Запустіть `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні URL Gateway, профіль, шлях конфігурації та процес є саме тими, які ви редагуєте. - Перезапустіть живий Gateway після змін встановлення/конфігурації/коду Plugin. У контейнерах-обгортках PID 1 може бути лише супервізором; перезапустіть або надішліть сигнал дочірньому процесу `openclaw gateway run`. -- Використайте `openclaw plugins inspect --runtime --json`, щоб підтвердити реєстрації хуків і - діагностику. Невбудованим хукам розмови, як-от `llm_input`, - `llm_output`, `before_agent_finalize` і `agent_end`, потрібен +- Використовуйте `openclaw plugins inspect --runtime --json`, щоб підтвердити реєстрації hook і + діагностику. Невбудовані conversation hooks, як-от `llm_input`, + `llm_output`, `before_agent_finalize` і `agent_end`, потребують `plugins.entries..hooks.allowConversationAccess=true`. -- Для перемикання моделей віддавайте перевагу `before_model_resolve`. Він виконується перед розв'язанням моделі +- Для перемикання моделей надавайте перевагу `before_model_resolve`. Він виконується перед розв’язанням моделі для ходів агента; `llm_output` виконується лише після того, як спроба моделі створить вивід асистента. -- Для підтвердження ефективної моделі сесії використовуйте `openclaw sessions` або - поверхні сесії/статусу Gateway, а під час налагодження навантажень постачальника запускайте +- Для доказу фактичної моделі сеансу використовуйте `openclaw sessions` або + поверхні сеансу/стану Gateway, а під час налагодження навантажень постачальника запускайте Gateway з `--raw-stream --raw-stream-path `. ### Повільне налаштування інструментів Plugin -Якщо здається, що ходи агента зависають під час підготовки інструментів, увімкніть трасувальне логування та -перевірте рядки часу виконання фабрики інструментів Plugin: +Якщо ходи агента наче зависають під час підготовки інструментів, увімкніть трасувальне журналювання та +перевірте рядки таймінгів фабрик інструментів Plugin: ```bash openclaw config set logging.level trace @@ -393,28 +401,28 @@ openclaw logs --follow [trace:plugin-tools] factory timings ... ``` -Зведення перелічує загальний час фабрики та найповільніші фабрики інструментів Plugin, -включно з ідентифікатором Plugin, оголошеними назвами інструментів, формою результату та тим, чи є інструмент -необов'язковим. Повільні рядки підвищуються до попереджень, коли одна фабрика займає -щонайменше 1 с або загальна підготовка фабрик інструментів Plugin займає щонайменше 5 с. +Зведення перелічує загальний час фабрик і найповільніші фабрики інструментів Plugin, +зокрема ідентифікатор Plugin, оголошені назви інструментів, форму результату та чи є інструмент +необов’язковим. Повільні рядки підвищуються до попереджень, коли одна фабрика триває +щонайменше 1 с або загальна підготовка фабрик інструментів Plugin триває щонайменше 5 с. -OpenClaw кешує успішні результати фабрик інструментів Plugin для повторних розв'язань -з тим самим ефективним контекстом запиту. Ключ кешу включає ефективну -runtime-конфігурацію, робочий простір, ідентифікатори агента/сесії, політику пісочниці, налаштування браузера, +OpenClaw кешує успішні результати фабрик інструментів Plugin для повторних розв’язань +із тим самим фактичним контекстом запиту. Ключ кешу містить фактичну +runtime-конфігурацію, робочий простір, ідентифікатори агента/сеансу, політику sandbox, налаштування браузера, контекст доставки, ідентичність запитувача та стан власності, тому фабрики, що -залежать від цих довірених полів, повторно виконуються, коли контекст змінюється. +залежать від цих довірених полів, запускаються повторно, коли контекст змінюється. -Якщо один Plugin домінує за часом, перевірте його runtime-реєстрації: +Якщо один Plugin домінує в таймінгу, перевірте його runtime-реєстрації: ```bash openclaw plugins inspect --runtime --json ``` Потім оновіть, перевстановіть або вимкніть цей Plugin. Автори Plugin мають переносити -дороге завантаження залежностей у шлях виконання інструмента, а не робити це +дороге завантаження залежностей за шлях виконання інструмента, а не робити це всередині фабрики інструмента. -### Дубльоване володіння каналом або інструментом +### Дублювання власності каналу або інструмента Симптоми: @@ -422,34 +430,35 @@ openclaw plugins inspect --runtime --json - `channel setup already registered: ()` - `plugin tool name conflict (): ` -Це означає, що більш ніж один увімкнений Plugin намагається володіти тим самим каналом, +Це означає, що кілька ввімкнених plugins намагаються володіти тим самим каналом, потоком налаштування або назвою інструмента. Найпоширеніша причина — зовнішній Plugin каналу, -установлений поруч із вбудованим Plugin, який тепер надає той самий ідентифікатор каналу. +встановлений поруч із вбудованим Plugin, який тепер надає той самий ідентифікатор каналу. Кроки налагодження: -- Виконайте `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений Plugin +- Запустіть `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений Plugin і його походження. -- Виконайте `openclaw plugins inspect --runtime --json` для кожного підозрюваного Plugin і - порівняйте `channels`, `channelConfigs`, `tools` та діагностику. -- Виконайте `openclaw plugins registry --refresh` після встановлення або вилучення +- Запустіть `openclaw plugins inspect --runtime --json` для кожного підозрюваного Plugin і + порівняйте `channels`, `channelConfigs`, `tools` і діагностику. +- Запустіть `openclaw plugins registry --refresh` після встановлення або видалення пакетів Plugin, щоб збережені метадані відображали поточне встановлення. - Перезапустіть Gateway після змін встановлення, реєстру або конфігурації. Варіанти виправлення: - Якщо один Plugin навмисно замінює інший для того самого ідентифікатора каналу, бажаний - Plugin має оголосити `channelConfigs..preferOver` з - ідентифікатором Plugin нижчого пріоритету. Див. [/plugins/manifest#replacing-another-channel-plugin](/uk/plugins/manifest#replacing-another-channel-plugin). + Plugin має оголосити `channelConfigs..preferOver` з ідентифікатором + Plugin нижчого пріоритету. Див. [/plugins/manifest#replacing-another-channel-plugin](/uk/plugins/manifest#replacing-another-channel-plugin). - Якщо дублювання випадкове, вимкніть один бік за допомогою - `plugins.entries..enabled: false` або вилучіть застаріле встановлення Plugin. -- Якщо ви явно ввімкнули обидва Plugin, OpenClaw зберігає цей запит і - повідомляє про конфлікт. Виберіть одного власника для каналу або перейменуйте інструменти, що належать Plugin, - щоб runtime-поверхня була однозначною. + `plugins.entries..enabled: false` або видаліть застаріле встановлення + Plugin. +- Якщо ви явно ввімкнули обидва plugins, OpenClaw зберігає цей запит і + повідомляє про конфлікт. Виберіть одного власника для каналу або перейменуйте інструменти, + що належать Plugin, щоб runtime-поверхня була однозначною. ## Слоти Plugin (ексклюзивні категорії) -Деякі категорії ексклюзивні (активною може бути лише одна одночасно): +Деякі категорії є ексклюзивними (активною може бути лише одна одночасно): ```json5 { @@ -464,10 +473,10 @@ openclaw plugins inspect --runtime --json | Слот | Що він контролює | За замовчуванням | | --------------- | --------------------- | ------------------- | -| `memory` | Активний Plugin пам'яті | `memory-core` | -| `contextEngine` | Активний рушій контексту | `legacy` (вбудований) | +| `memory` | Plugin активної пам’яті | `memory-core` | +| `contextEngine` | Активний контекстний рушій | `legacy` (вбудований) | -## Довідка CLI +## Довідник CLI ```bash openclaw plugins list # compact inventory @@ -515,82 +524,83 @@ openclaw plugins enable openclaw plugins disable ``` -Пакетні плагіни постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (наприклад -пакетні постачальники моделей, пакетні постачальники мовлення та пакетний браузерний -плагін). Інші пакетні плагіни все ще потребують `openclaw plugins enable `. +Вбудовані plugins постачаються разом з OpenClaw. Багато з них увімкнені за замовчуванням (наприклад, +вбудовані провайдери моделей, вбудовані мовленнєві провайдери та вбудований браузерний +plugin). Інші вбудовані plugins все одно потребують `openclaw plugins enable `. -`--force` перезаписує наявний установлений плагін або набір хуків на місці. Використовуйте +`--force` перезаписує наявний установлений plugin або пакет hook на місці. Використовуйте `openclaw plugins update ` для звичайних оновлень відстежуваних npm -плагінів. Він не підтримується разом із `--link`, який повторно використовує шлях до джерела замість -копіювання поверх керованої цілі встановлення. +plugins. Він не підтримується з `--link`, який повторно використовує вихідний шлях замість +копіювання до керованої цілі встановлення. Коли `plugins.allow` уже задано, `openclaw plugins install` додає -ідентифікатор установленого плагіна до цього списку дозволених перед його ввімкненням. Якщо той самий ідентифікатор плагіна -є в `plugins.deny`, встановлення видаляє цей застарілий запис заборони, щоб -явно встановлений плагін можна було завантажити одразу після перезапуску. +ідентифікатор установленого plugin до цього allowlist перед його ввімкненням. Якщо той самий ідентифікатор plugin +присутній у `plugins.deny`, установлення видаляє цей застарілий запис deny, щоб +явне встановлення можна було завантажити одразу після перезапуску. -OpenClaw зберігає постійний локальний реєстр плагінів як модель холодного читання для -інвентаризації плагінів, володіння внесками та планування запуску. Потоки встановлення, оновлення, -видалення, увімкнення та вимкнення оновлюють цей реєстр після зміни стану плагіна. -Той самий файл `plugins/installs.json` зберігає довговічні метадані встановлення у -верхньорівневому `installRecords` і відновлювані метадані маніфестів у `plugins`. Якщо +OpenClaw зберігає постійний локальний реєстр plugin як модель холодного читання для +інвентаризації plugin, володіння внесками та планування запуску. Потоки встановлення, оновлення, +видалення, ввімкнення та вимкнення оновлюють цей реєстр після зміни стану plugin. +Той самий файл `plugins/installs.json` зберігає довговічні метадані встановлення в +верхньорівневих `installRecords` і відновлювані метадані маніфесту в `plugins`. Якщо реєстр відсутній, застарілий або недійсний, `openclaw plugins registry ---refresh` перебудовує його подання маніфестів із записів встановлення, політики конфігурації та -метаданих маніфестів/пакетів без завантаження модулів середовища виконання плагінів. -`openclaw plugins update ` застосовується до відстежуваних встановлень. Передавання -специфікації npm пакета з dist-tag або точною версією зіставляє назву пакета -назад із відстежуваним записом плагіна та записує нову специфікацію для майбутніх оновлень. -Передавання назви пакета без версії повертає встановлення з точно зафіксованою версією назад до -стандартної лінії випусків реєстру. Якщо встановлений npm плагін уже відповідає +--refresh` перебудовує його подання маніфестів із записів установлення, політики конфігурації та +метаданих manifest/package без завантаження runtime-модулів plugin. +`openclaw plugins update ` застосовується до відстежуваних установлень. Передавання +специфікації npm-пакета з dist-tag або точною версією зіставляє назву пакета +назад із відстежуваним записом plugin і записує нову специфікацію для майбутніх оновлень. +Передавання назви пакета без версії повертає точно закріплене встановлення до +стандартної лінії випуску реєстру. Якщо встановлений npm plugin уже відповідає розв’язаній версії та записаній ідентичності артефакту, OpenClaw пропускає оновлення -без завантаження, перевстановлення або переписування конфігурації. +без завантаження, повторного встановлення або переписування конфігурації. Коли `openclaw update` виконується на beta-каналі, записи npm і ClawHub -плагінів стандартної лінії спершу пробують `@beta` і повертаються до default/latest, коли beta-випуску -плагіна немає. Точні версії та явні теги залишаються зафіксованими. +plugin стандартної лінії спершу пробують `@beta` і повертаються до default/latest, якщо beta-випуску +plugin не існує. Точні версії та явні теги залишаються закріпленими. -`--pin` призначений лише для npm. Він не підтримується з `--marketplace`, тому що -встановлення з маркетплейсу зберігають метадані джерела маркетплейсу замість npm специфікації. +`--pin` працює лише з npm. Він не підтримується з `--marketplace`, оскільки +marketplace-установлення зберігають метадані джерела marketplace замість npm-специфікації. -`--dangerously-force-unsafe-install` — це аварійне перевизначення для хибних -спрацьовувань вбудованого сканера небезпечного коду. Воно дозволяє встановлення -плагінів і оновлення плагінів продовжуватися попри вбудовані знахідки `critical`, але все одно -не обходить блокування політики плагінів `before_install` або блокування через помилку сканування. -Сканування під час встановлення ігнорують поширені тестові файли й каталоги, як-от `tests/`, +`--dangerously-force-unsafe-install` — аварійне перевизначення для хибних +спрацювань вбудованого сканера небезпечного коду. Воно дозволяє встановлення plugin +і оновлення plugin продовжуватися попри вбудовані знахідки `critical`, але все одно +не обходить блокування політики plugin `before_install` або блокування через збій сканування. +Сканування встановлень ігнорує поширені тестові файли та каталоги, як-от `tests/`, `__tests__/`, `*.test.*` і `*.spec.*`, щоб не блокувати запаковані тестові моки; -оголошені вхідні точки середовища виконання плагіна все одно скануються, навіть якщо вони використовують одну з +оголошені runtime-точки входу plugin все одно скануються, навіть якщо вони використовують одну з цих назв. -Цей прапорець CLI застосовується лише до потоків встановлення/оновлення плагінів. Встановлення -залежностей Skills через Gateway використовують натомість відповідне перевизначення запиту -`dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком -завантаження/встановлення Skills із ClawHub. +Цей прапорець CLI застосовується лише до потоків встановлення/оновлення plugin. Встановлення +залежностей Skills на базі Gateway натомість використовують відповідне перевизначення запиту +`dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим +потоком завантаження/встановлення Skills із ClawHub. -Якщо плагін, який ви опублікували на ClawHub, приховано або заблоковано скануванням, відкрийте -панель ClawHub або виконайте `clawhub package rescan `, щоб попросити ClawHub перевірити -його знову. `--dangerously-force-unsafe-install` впливає лише на встановлення на вашому власному -комп’ютері; він не просить ClawHub повторно просканувати плагін або зробити заблокований випуск +Якщо plugin, який ви опублікували на ClawHub, прихований або заблокований скануванням, відкрийте +панель ClawHub або запустіть `clawhub package rescan `, щоб попросити ClawHub перевірити +його знову. `--dangerously-force-unsafe-install` впливає лише на встановлення на вашій власній +машині; він не просить ClawHub повторно просканувати plugin і не робить заблокований випуск публічним. -Сумісні бандли беруть участь у тому самому потоці списку/інспектування/увімкнення/вимкнення -плагінів. Поточна підтримка середовища виконання охоплює бандлові Skills, command-skills Claude, -типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і оголошені в маніфесті -`lspServers`, command-skills Cursor і сумісні каталоги хуків Codex. +Сумісні bundles беруть участь у тому самому потоці списку/інспектування/ввімкнення/вимкнення +plugin. Поточна runtime-підтримка включає bundle Skills, command-skills Claude, +стандартні налаштування Claude `settings.json`, стандартні налаштування Claude `.lsp.json` і +оголошені в маніфесті `lspServers`, command-skills Cursor і сумісні каталоги hook +Codex. -`openclaw plugins inspect ` також повідомляє виявлені можливості бандла, а також -підтримувані або непідтримувані записи серверів MCP і LSP для плагінів на основі бандлів. +`openclaw plugins inspect ` також повідомляє виявлені можливості bundle, а також +підтримувані або непідтримувані записи серверів MCP і LSP для plugin на базі bundle. -Джерела маркетплейсу можуть бути відомою Claude назвою маркетплейсу з -`~/.claude/plugins/known_marketplaces.json`, локальним коренем маркетплейсу або шляхом до -`marketplace.json`, скороченням GitHub на кшталт `owner/repo`, URL репозиторію GitHub -або git URL. Для віддалених маркетплейсів записи плагінів мають залишатися всередині -клонованого репозиторію маркетплейсу та використовувати лише відносні джерела шляхів. +Джерелами marketplace можуть бути відома назва marketplace Claude з +`~/.claude/plugins/known_marketplaces.json`, локальний корінь marketplace або шлях +`marketplace.json`, GitHub-скорочення на кшталт `owner/repo`, URL репозиторію GitHub +або git URL. Для віддалених marketplaces записи plugin мають залишатися всередині +клонованого репозиторію marketplace і використовувати лише відносні джерела шляхів. -Повні відомості дивіться в [довіднику CLI `openclaw plugins`](/uk/cli/plugins). +Див. [довідник CLI `openclaw plugins`](/uk/cli/plugins) для повних подробиць. -## Огляд API плагінів +## Огляд API Plugin -Нативні плагіни експортують об’єкт входу, який надає `register(api)`. Старіші -плагіни все ще можуть використовувати `activate(api)` як застарілий псевдонім, але новим плагінам слід +Нативні plugins експортують об’єкт входу, який надає `register(api)`. Старіші +plugins можуть усе ще використовувати `activate(api)` як застарілий alias, але нові plugins мають використовувати `register`. ```typescript @@ -612,74 +622,74 @@ export default definePluginEntry({ ``` OpenClaw завантажує об’єкт входу та викликає `register(api)` під час -активації плагіна. Завантажувач усе ще повертається до `activate(api)` для старіших плагінів, -але пакетні плагіни та нові зовнішні плагіни мають розглядати `register` як +активації plugin. Завантажувач усе ще повертається до `activate(api)` для старіших plugins, +але вбудовані plugins і нові зовнішні plugins мають розглядати `register` як публічний контракт. -`api.registrationMode` повідомляє плагіну, чому його вхід завантажується: +`api.registrationMode` повідомляє plugin, чому завантажується його entry: | Режим | Значення | | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `full` | Активація середовища виконання. Реєструйте інструменти, хуки, служби, команди, маршрути та інші активні побічні ефекти. | -| `discovery` | Виявлення можливостей лише для читання. Реєструйте постачальників і метадані; довірений код входу плагіна може завантажуватися, але пропускайте активні побічні ефекти. | -| `setup-only` | Завантаження метаданих налаштування каналу через легкий вхід налаштування. | -| `setup-runtime` | Завантаження налаштування каналу, якому також потрібен вхід середовища виконання. | +| `full` | Runtime-активація. Реєструйте tools, hooks, services, commands, routes та інші активні побічні ефекти. | +| `discovery` | Виявлення можливостей лише для читання. Реєструйте providers і metadata; довірений entry-код plugin може завантажуватися, але пропускайте активні побічні ефекти. | +| `setup-only` | Завантаження метаданих налаштування channel через легковаговий setup entry. | +| `setup-runtime` | Завантаження налаштування channel, якому також потрібен runtime entry. | | `cli-metadata` | Лише збирання метаданих команд CLI. | -Входи плагінів, які відкривають сокети, бази даних, фонові робочі процеси або довгоживучі -клієнти, мають обмежувати ці побічні ефекти умовою `api.registrationMode === "full"`. -Завантаження виявлення кешуються окремо від активаційних завантажень і не замінюють -поточний реєстр Gateway. Виявлення є неактиваційним, але не без імпорту: -OpenClaw може виконати довірений вхід плагіна або модуль плагіна каналу, щоб побудувати -знімок. Тримайте верхні рівні модулів легкими та без побічних ефектів, а -мережеві клієнти, підпроцеси, слухачі, читання облікових даних і запуск служб -переносьте за шляхи повного середовища виконання. +Entry plugin, які відкривають sockets, databases, background workers або довгоживучі +clients, мають захищати ці побічні ефекти перевіркою `api.registrationMode === "full"`. +Завантаження discovery кешуються окремо від активаційних завантажень і не замінюють +поточний реєстр Gateway. Discovery є неактиваційним, але не import-free: +OpenClaw може виконати довірений entry plugin або module channel plugin, щоб побудувати +snapshot. Тримайте верхній рівень modules легким і без побічних ефектів, а +network clients, subprocesses, listeners, читання credentials і запуск service переносіть +за full-runtime шляхи. Поширені методи реєстрації: -| Метод | Що він реєструє | -| --------------------------------------- | --------------------------------------- | -| `registerProvider` | Постачальник моделей (LLM) | -| `registerChannel` | Канал чату | -| `registerTool` | Інструмент агента | -| `registerHook` / `on(...)` | Хуки життєвого циклу | -| `registerSpeechProvider` | Перетворення тексту на мовлення / STT | -| `registerRealtimeTranscriptionProvider` | Потоковий STT | -| `registerRealtimeVoiceProvider` | Дуплексний голос у реальному часі | -| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо | -| `registerImageGenerationProvider` | Генерація зображень | -| `registerMusicGenerationProvider` | Генерація музики | -| `registerVideoGenerationProvider` | Генерація відео | -| `registerWebFetchProvider` | Постачальник веботримання / скрейпінгу | -| `registerWebSearchProvider` | Вебпошук | -| `registerHttpRoute` | HTTP кінцева точка | -| `registerCommand` / `registerCli` | Команди CLI | -| `registerContextEngine` | Рушій контексту | -| `registerService` | Фонова служба | +| Метод | Що він реєструє | +| --------------------------------------- | ---------------------------- | +| `registerProvider` | Провайдер моделі (LLM) | +| `registerChannel` | Chat channel | +| `registerTool` | Agent tool | +| `registerHook` / `on(...)` | Lifecycle hooks | +| `registerSpeechProvider` | Text-to-speech / STT | +| `registerRealtimeTranscriptionProvider` | Потоковий STT | +| `registerRealtimeVoiceProvider` | Дуплексний realtime voice | +| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо | +| `registerImageGenerationProvider` | Генерація зображень | +| `registerMusicGenerationProvider` | Генерація музики | +| `registerVideoGenerationProvider` | Генерація відео | +| `registerWebFetchProvider` | Web fetch / scrape provider | +| `registerWebSearchProvider` | Web search | +| `registerHttpRoute` | HTTP endpoint | +| `registerCommand` / `registerCli` | Команди CLI | +| `registerContextEngine` | Context engine | +| `registerService` | Background service | -Поведінка захисту хуків для типізованих хуків життєвого циклу: +Поведінка guard для типізованих lifecycle hooks: -- `before_tool_call`: `{ block: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються. -- `before_tool_call`: `{ block: false }` є no-op і не очищує попереднє блокування. -- `before_install`: `{ block: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються. -- `before_install`: `{ block: false }` є no-op і не очищує попереднє блокування. -- `message_sending`: `{ cancel: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються. -- `message_sending`: `{ cancel: false }` є no-op і не очищує попереднє скасування. +- `before_tool_call`: `{ block: true }` є завершальним; handlers із нижчим пріоритетом пропускаються. +- `before_tool_call`: `{ block: false }` є no-op і не скасовує попереднє block. +- `before_install`: `{ block: true }` є завершальним; handlers із нижчим пріоритетом пропускаються. +- `before_install`: `{ block: false }` є no-op і не скасовує попереднє block. +- `message_sending`: `{ cancel: true }` є завершальним; handlers із нижчим пріоритетом пропускаються. +- `message_sending`: `{ cancel: false }` є no-op і не скасовує попереднє cancel. -Нативний app-server Codex мостить нативні події інструментів Codex назад у цю -поверхню хуків. Плагіни можуть блокувати нативні інструменти Codex через `before_tool_call`, -спостерігати результати через `after_tool_call` і брати участь у схваленнях Codex -`PermissionRequest`. Міст поки що не переписує аргументи нативних інструментів Codex. -Точна межа підтримки середовища виконання Codex описана в +Нативний app-server Codex прокидає нативні для Codex події tools назад у цю +поверхню hook. Plugins можуть блокувати нативні tools Codex через `before_tool_call`, +спостерігати результати через `after_tool_call` і брати участь у затвердженнях Codex +`PermissionRequest`. Bridge поки що не переписує аргументи нативних tools Codex. +Точна межа runtime-підтримки Codex описана в [контракті підтримки Codex harness v1](/uk/plugins/codex-harness#v1-support-contract). -Повну поведінку типізованих хуків дивіться в [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics). +Повну поведінку типізованих hook див. в [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics). ## Пов’язане -- [Створення плагінів](/uk/plugins/building-plugins) — створіть власний плагін -- [Бандли плагінів](/uk/plugins/bundles) — сумісність бандлів Codex/Claude/Cursor -- [Маніфест плагіна](/uk/plugins/manifest) — схема маніфесту -- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додайте інструменти агента в плагіні -- [Внутрішня архітектура плагінів](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження -- [Плагіни спільноти](/uk/plugins/community) — списки сторонніх розробників +- [Створення Plugin](/uk/plugins/building-plugins) — створіть власний Plugin +- [Пакети Plugin](/uk/plugins/bundles) — сумісність пакетів Codex/Claude/Cursor +- [Маніфест Plugin](/uk/plugins/manifest) — схема маніфесту +- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додайте інструменти агента в Plugin +- [Внутрішня архітектура Plugin](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження +- [Plugin спільноти](/uk/plugins/community) — каталоги сторонніх розробників