From 8d141b9b7b894f41dce92ca4bd5790c0e719d1cf Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 27 Apr 2026 22:26:34 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/cli/infer.md | 99 ++-- docs/uk/gateway/configuration-reference.md | 635 +++++++++++---------- docs/uk/gateway/doctor.md | 367 ++++++------ docs/uk/gateway/trusted-proxy-auth.md | 163 +++--- docs/uk/plugins/sdk-subpaths.md | 388 ++++++------- docs/uk/plugins/sdk-testing.md | 139 +++-- 6 files changed, 899 insertions(+), 892 deletions(-) diff --git a/docs/uk/cli/infer.md b/docs/uk/cli/infer.md index a65e791f4..e0645a2f4 100644 --- a/docs/uk/cli/infer.md +++ b/docs/uk/cli/infer.md @@ -1,21 +1,21 @@ --- read_when: - Додавання або змінення команд `openclaw infer` - - Проєктування стабільної автоматизації можливостей без графічного інтерфейсу -summary: CLI з визначенням передусім для робочих процесів із моделями, зображеннями, аудіо, TTS, відео, вебом і ембедингами на основі провайдера + - Проєктування стабільної автоматизації headless-можливостей +summary: CLI з автоматичним визначенням спочатку для робочих процесів моделей, зображень, аудіо, TTS, відео, вебу та ембедингів, що використовують провайдерів title: CLI для інференсу x-i18n: - generated_at: "2026-04-27T22:06:12Z" + generated_at: "2026-04-27T22:22:41Z" model: gpt-5.4 provider: openai - source_hash: 704f9ea60adb1b509f0b4f74ae79ffb70f12915a7e8a45d43ca28f5ac7d70af1 + source_hash: 5f9dc003af66692fe85d11c74ef952b72668aa7c715090b92ca5511f680a963d source_path: cli/infer.md workflow: 15 --- -`openclaw infer` — це канонічна безграфічна поверхня для робочих процесів інференсу на основі провайдера. +`openclaw infer` — це канонічна headless-поверхня для робочих процесів інференсу, що використовують провайдерів. -Вона навмисно надає сімейства можливостей, а не сирі назви Gateway RPC і не сирі ідентифікатори інструментів агента. +Вона навмисно відкриває сімейства можливостей, а не сирі назви Gateway RPC і не сирі ідентифікатори інструментів агента. ## Перетворення infer на skill @@ -28,9 +28,9 @@ Focus on model runs, image generation, video generation, audio transcription, TT Хороший skill на основі infer має: -- зіставляти поширені наміри користувача з правильною підкомандою infer +- зіставляти поширені наміри користувача з правильним підкомандним рядком infer - містити кілька канонічних прикладів infer для робочих процесів, які він охоплює -- надавати перевагу `openclaw infer ...` у прикладах і рекомендаціях +- віддавати перевагу `openclaw infer ...` у прикладах і підказках - уникати повторного документування всієї поверхні infer всередині тіла skill Типове охоплення skill, зосередженого на infer: @@ -42,19 +42,19 @@ Focus on model runs, image generation, video generation, audio transcription, TT - `openclaw infer web search` - `openclaw infer embedding create` -## Чому варто використовувати infer +## Навіщо використовувати infer -`openclaw infer` надає єдиний узгоджений CLI для завдань інференсу на основі провайдера всередині OpenClaw. +`openclaw infer` надає єдиний узгоджений CLI для завдань інференсу, що використовують провайдерів, всередині OpenClaw. Переваги: - Використовуйте провайдерів і моделі, уже налаштовані в OpenClaw, замість створення одноразових обгорток для кожного бекенда. -- Тримайте робочі процеси для моделей, зображень, транскрибування аудіо, TTS, відео, вебу та ембедингів в одному дереві команд. +- Тримайте робочі процеси моделей, зображень, транскрибування аудіо, TTS, відео, вебу та ембедингів під одним деревом команд. - Використовуйте стабільну форму виводу `--json` для скриптів, автоматизації та робочих процесів, керованих агентом. -- Надавайте перевагу першорядній поверхні OpenClaw, коли завдання за своєю суттю полягає в тому, щоб «виконати інференс». +- Віддавайте перевагу first-party поверхні OpenClaw, коли завдання по суті полягає в тому, щоб «виконати інференс». - Використовуйте звичайний локальний шлях без потреби в Gateway для більшості команд infer. -Для наскрізних перевірок провайдера надавайте перевагу `openclaw infer ...`, коли тести провайдера нижчого рівня вже зелені. Це перевіряє постачений CLI, завантаження конфігурації, визначення агента за замовчуванням, активацію вбудованих плагінів, відновлення залежностей середовища виконання та спільне середовище виконання можливостей до того, як буде зроблено запит до провайдера. +Для наскрізних перевірок провайдерів віддавайте перевагу `openclaw infer ...`, коли нижчорівневі тести провайдерів уже зелені. Це перевіряє поставлений CLI, завантаження конфігурації, визначення агента за замовчуванням, активацію вбудованих Plugin, відновлення залежностей середовища виконання та спільне середовище можливостей до виконання запиту до провайдера. ## Дерево команд @@ -113,33 +113,33 @@ Focus on model runs, image generation, video generation, audio transcription, TT | Завдання | Команда | Примітки | | ----------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------- | -| Запустити текстовий/модельний запит | `openclaw infer model run --prompt "..." --json` | За замовчуванням використовує звичайний локальний шлях | -| Згенерувати зображення | `openclaw infer image generate --prompt "..." --json` | Використовуйте `image edit`, якщо починаєте з наявного файлу | -| Описати файл зображення | `openclaw infer image describe --file ./image.png --json` | `--model` має бути зображувально-сумісним `` | -| Транскрибувати аудіо | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` має бути `` | +| Виконати текстовий/модельний запит | `openclaw infer model run --prompt "..." --json` | За замовчуванням використовує звичайний локальний шлях | +| Згенерувати зображення | `openclaw infer image generate --prompt "..." --json` | Використовуйте `image edit`, якщо починаєте з наявного файла | +| Описати файл зображення | `openclaw infer image describe --file ./image.png --json` | `--model` має бути image-capable у форматі `` | +| Транскрибувати аудіо | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` має бути у форматі `` | | Синтезувати мовлення | `openclaw infer tts convert --text "..." --output ./speech.mp3 --json` | `tts status` орієнтовано на gateway | -| Згенерувати відео | `openclaw infer video generate --prompt "..." --json` | Підтримує підказки провайдера, такі як `--resolution` | -| Описати відеофайл | `openclaw infer video describe --file ./clip.mp4 --json` | `--model` має бути `` | -| Шукати у вебі | `openclaw infer web search --query "..." --json` | | +| Згенерувати відео | `openclaw infer video generate --prompt "..." --json` | Підтримує підказки для провайдерів, такі як `--resolution` | +| Описати відеофайл | `openclaw infer video describe --file ./clip.mp4 --json` | `--model` має бути у форматі `` | +| Виконати пошук у вебі | `openclaw infer web search --query "..." --json` | | | Отримати вебсторінку | `openclaw infer web fetch --url https://example.com --json` | | | Створити ембединги | `openclaw infer embedding create --text "..." --json` | | ## Поведінка -- `openclaw infer ...` є основною поверхнею CLI для цих робочих процесів. -- Використовуйте `--json`, коли вивід буде споживатися іншою командою або скриптом. +- `openclaw infer ...` — основна CLI-поверхня для цих робочих процесів. +- Використовуйте `--json`, коли вивід споживатиметься іншою командою або скриптом. - Використовуйте `--provider` або `--model provider/model`, коли потрібен конкретний бекенд. - Для `image describe`, `audio transcribe` і `video describe` параметр `--model` має використовувати форму ``. -- Для `image describe` явний `--model` запускає цей provider/model безпосередньо. Модель має підтримувати зображення в каталозі моделей або конфігурації провайдера. `codex/` запускає обмежений хід розуміння зображень через сервер застосунку Codex; `openai-codex/` використовує шлях провайдера OpenAI Codex OAuth. -- Команди безстанового виконання за замовчуванням локальні. -- Команди керованого Gateway стану за замовчуванням використовують gateway. -- Звичайний локальний шлях не вимагає, щоб Gateway був запущений. -- Локальний `model run` — це легковагове одноразове завершення через провайдера. Він визначає налаштовану модель агента й автентифікацію, але не запускає хід chat-агента, не завантажує інструменти і не відкриває вбудовані MCP-сервери. -- `model run --gateway` усе ще використовує середовище виконання агента Gateway, тому може перевіряти той самий маршрутований шлях виконання, що й звичайний хід із підтримкою Gateway. MCP-сервери, відкриті через це середовище виконання, виводяться з експлуатації після відповіді, тож повторні виклики зі скриптів не залишають stdio MCP дочірні процеси активними. +- Для `image describe` явний `--model` запускає цей provider/model безпосередньо. Модель має підтримувати роботу із зображеннями в каталозі моделей або конфігурації провайдера. `codex/` запускає обмежений поворот app-server Codex для розуміння зображень; `openai-codex/` використовує шлях провайдера OpenAI Codex OAuth. +- Команди stateless-виконання за замовчуванням локальні. +- Команди стану, керованого Gateway, за замовчуванням використовують gateway. +- Звичайний локальний шлях не вимагає, щоб gateway був запущений. +- Локальний `model run` — це легкий одноразовий provider completion. Він визначає налаштовану модель агента та auth, але не запускає поворот chat-agent, не завантажує інструменти й не відкриває вбудовані MCP-сервери. +- `model run --gateway` усе одно використовує середовище агента Gateway, щоб перевіряти той самий маршрутизований шлях виконання, що й звичайний поворот із підтримкою Gateway. MCP-сервери, відкриті через це середовище виконання, завершуються після відповіді, тому повторні скриптові виклики не залишають stdio MCP дочірні процеси активними. ## Model -Використовуйте `model` для текстового інференсу на основі провайдера та перевірки моделей/провайдерів. +Використовуйте `model` для текстового інференсу через провайдерів та перевірки моделей/провайдерів. ```bash openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json @@ -148,7 +148,7 @@ openclaw infer model providers --json openclaw infer model inspect --name gpt-5.5 --json ``` -Використовуйте повні посилання ``, щоб перевірити конкретного провайдера без запуску Gateway або завантаження всієї поверхні інструментів агента: +Використовуйте повні посилання ``, щоб виконати smoke-тест конкретного провайдера без запуску Gateway або завантаження повної поверхні інструментів агента: ```bash openclaw infer model run --local --model anthropic/claude-sonnet-4-6 --prompt "Reply with exactly: pong" --json @@ -161,13 +161,14 @@ openclaw infer model run --local --model openai/gpt-4.1 --prompt "Reply with exa Примітки: -- Локальний `model run` — це найвужча CLI-перевірка працездатності провайдера/моделі/автентифікації, оскільки він надсилає вибраній моделі лише наданий запит. -- Використовуйте `model run --gateway`, коли потрібно перевірити маршрутизацію Gateway, налаштування середовища виконання агента або стан провайдера, керований Gateway, замість спрощеного локального шляху завершення. -- `model auth login`, `model auth logout` і `model auth status` керують збереженим станом автентифікації провайдера. +- Локальний `model run` — це найвужчий CLI smoke для перевірки стану провайдера/моделі/auth, оскільки він надсилає вибраній моделі лише переданий запит. +- Локальний `model run` завершується з ненульовим кодом, коли провайдер не повертає текстовий результат, щоб недоступні локальні провайдери та порожні completion не виглядали як успішні перевірки. +- Використовуйте `model run --gateway`, коли потрібно протестувати маршрутизацію Gateway, налаштування середовища агента або стан провайдера, керований Gateway, а не легкий локальний шлях completion. +- `model auth login`, `model auth logout` і `model auth status` керують збереженим станом auth провайдера. ## Image -Використовуйте `image` для генерації, редагування й опису. +Використовуйте `image` для генерації, редагування та опису. ```bash openclaw infer image generate --prompt "friendly lobster illustration" --json @@ -184,10 +185,10 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --j Примітки: - Використовуйте `image edit`, якщо починаєте з наявних вхідних файлів. -- Використовуйте `--size`, `--aspect-ratio` або `--resolution` з `image edit` для провайдерів/моделей, які підтримують підказки геометрії під час редагування еталонних зображень. -- Використовуйте `--output-format png --background transparent` з `--model openai/gpt-image-1.5` для PNG-виводу OpenAI із прозорим тлом; `--openai-background` лишається доступним як OpenAI-специфічний псевдонім. Провайдери, які не оголошують підтримку тла, повідомляють про цю підказку як про проігнороване перевизначення. -- Використовуйте `image providers --json`, щоб перевірити, які вбудовані провайдери зображень можна виявити, налаштовано, вибрано, а також які можливості генерації/редагування надає кожен провайдер. -- Використовуйте `image generate --model --json` як найвужчу живу CLI-перевірку для змін генерації зображень. Приклад: +- Використовуйте `--size`, `--aspect-ratio` або `--resolution` з `image edit` для провайдерів/моделей, які підтримують підказки геометрії під час редагування за еталонним зображенням. +- Використовуйте `--output-format png --background transparent` з `--model openai/gpt-image-1.5` для прозорого фону в PNG-виводі OpenAI; `--openai-background` залишається доступним як OpenAI-специфічний псевдонім. Провайдери, які не декларують підтримку фону, повідомляють про цю підказку як про проігнороване перевизначення. +- Використовуйте `image providers --json`, щоб перевірити, які вбудовані провайдери зображень можна виявити, які налаштовано, які вибрано та які можливості генерації/редагування надає кожен провайдер. +- Використовуйте `image generate --model --json` як найвужчий live CLI smoke для змін у генерації зображень. Приклад: ```bash openclaw infer image providers --json @@ -198,10 +199,10 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --j --json ``` - JSON-відповідь повідомляє `ok`, `provider`, `model`, `attempts` і шляхи записаних вихідних файлів. Якщо встановлено `--output`, фінальне розширення може відповідати MIME-типу, поверненому провайдером. + Відповідь JSON повідомляє `ok`, `provider`, `model`, `attempts` і шляхи записаного виводу. Якщо встановлено `--output`, остаточне розширення може відповідати MIME-типу, повернутому провайдером. -- Для `image describe` параметр `--model` має бути зображувально-сумісним ``. -- Для локальних візуальних моделей Ollama спочатку завантажте модель і встановіть `OLLAMA_API_KEY` на будь-яке значення-заповнювач, наприклад `ollama-local`. Див. [Ollama](/uk/providers/ollama#vision-and-image-description). +- Для `image describe` параметр `--model` має бути image-capable у форматі ``. +- Для локальних vision-моделей Ollama спочатку завантажте модель і встановіть `OLLAMA_API_KEY` у будь-яке заповнювальне значення, наприклад `ollama-local`. Див. [Ollama](/uk/providers/ollama#vision-and-image-description). ## Audio @@ -216,11 +217,11 @@ openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --jso Примітки: - `audio transcribe` призначено для транскрибування файлів, а не для керування сеансами в реальному часі. -- `--model` має бути ``. +- `--model` має бути у форматі ``. ## TTS -Використовуйте `tts` для синтезу мовлення та стану провайдера TTS. +Використовуйте `tts` для синтезу мовлення та стану TTS-провайдера. ```bash openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --json @@ -232,11 +233,11 @@ openclaw infer tts status --json Примітки: - `tts status` за замовчуванням використовує gateway, оскільки відображає стан TTS, керований gateway. -- Використовуйте `tts providers`, `tts voices` і `tts set-provider`, щоб перевіряти та налаштовувати поведінку TTS. +- Використовуйте `tts providers`, `tts voices` і `tts set-provider` для перевірки та налаштування поведінки TTS. ## Video -Використовуйте `video` для генерації й опису. +Використовуйте `video` для генерації та опису. ```bash openclaw infer video generate --prompt "cinematic sunset over the ocean" --json @@ -248,11 +249,11 @@ openclaw infer video describe --file ./clip.mp4 --model openai/gpt-4.1-mini --js Примітки: - `video generate` приймає `--size`, `--aspect-ratio`, `--resolution`, `--duration`, `--audio`, `--watermark` і `--timeout-ms` та передає їх у середовище виконання генерації відео. -- Для `video describe` параметр `--model` має бути ``. +- Для `video describe` параметр `--model` має бути у форматі ``. ## Web -Використовуйте `web` для робочих процесів пошуку та отримання даних. +Використовуйте `web` для робочих процесів пошуку та отримання вмісту. ```bash openclaw infer web search --query "OpenClaw docs" --json @@ -302,7 +303,7 @@ openclaw infer embedding providers --json - `outputs` - `error` -Для команд генерації медіа `outputs` містить файли, записані OpenClaw. Використовуйте `path`, `mimeType`, `size` і будь-які специфічні для медіа розміри в цьому масиві для автоматизації замість аналізу придатного для читання людиною stdout. +Для команд генерації медіа `outputs` містить файли, записані OpenClaw. Використовуйте `path`, `mimeType`, `size` і будь-які специфічні для медіа розміри в цьому масиві для автоматизації замість розбору людиночитного stdout. ## Поширені помилки @@ -326,7 +327,7 @@ openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --jso - `openclaw capability ...` є псевдонімом для `openclaw infer ...`. -## Пов’язане +## Пов’язані матеріали - [Довідник CLI](/uk/cli) - [Моделі](/uk/concepts/models) diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index f5af7c9c7..6f905c316 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -1,70 +1,72 @@ --- read_when: - - Вам потрібні точні семантики конфігурації на рівні полів або типові значення + - Вам потрібні точні семантики полів конфігурації або значення за замовчуванням - Ви перевіряєте блоки конфігурації каналу, моделі, Gateway або інструмента -summary: Довідник конфігурації Gateway для основних ключів OpenClaw, типових значень і посилань на окремі довідники підсистем -title: Довідник конфігурації +summary: Довідник з конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем +title: Довідник з конфігурації x-i18n: - generated_at: "2026-04-27T12:49:55Z" + generated_at: "2026-04-27T22:22:44Z" model: gpt-5.4 provider: openai - source_hash: d3c9d69ac5fe9c32a19bb92e05927a3ec919c3d4112b809f9d886a83746d37c8 + source_hash: 08e5302ef65a8464dcb1babb9fa01d3084bc1a622632b60f144997266cf174af source_path: gateway/configuration-reference.md workflow: 15 --- -Основний довідник конфігурації для `~/.openclaw/openclaw.json`. Огляд, орієнтований на завдання, див. у [Configuration](/uk/gateway/configuration). +Довідник з основної конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration). -Охоплює основні поверхні конфігурації OpenClaw і містить посилання назовні, коли підсистема має власний глибший довідник. Каталоги команд, що належать каналам і плагінам, а також глибокі параметри пам’яті/QMD розміщені на окремих сторінках, а не тут. +Охоплює основні поверхні конфігурації OpenClaw і містить посилання назовні, коли підсистема має власний детальніший довідник. Каталоги команд, що належать каналам і Plugin, а також глибокі параметри пам’яті/QMD винесені на окремі сторінки, а не описані тут. Джерело істини в коді: -- `openclaw config schema` виводить актуальну JSON Schema, що використовується для валідації та Control UI, із злитими метаданими вбудованих плагінів/каналів, коли вони доступні -- `config.schema.lookup` повертає один вузол схеми для заданого шляху для інструментів детального перегляду -- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий геш документації конфігурації щодо поточної поверхні схеми +- `openclaw config schema` виводить актуальну JSON Schema, що використовується для валідації та Control UI, із доданими метаданими bundled/Plugin/каналів, коли вони доступні +- `config.schema.lookup` повертає один вузол схеми для конкретного шляху для інструментів деталізованого перегляду +- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш документації конфігурації щодо поточної поверхні схеми Шлях пошуку для агента: використовуйте дію інструмента `gateway` `config.schema.lookup` для -точної документації на рівні полів і обмежень перед редагуванням. Використовуйте +точної документації на рівні полів і обмежень перед внесенням змін. Використовуйте [Configuration](/uk/gateway/configuration) для вказівок, орієнтованих на завдання, а цю сторінку — -для ширшої карти полів, типових значень і посилань на довідники підсистем. +для ширшої карти полів, значень за замовчуванням і посилань на довідники підсистем. -Окремі глибокі довідники: +Окремі детальні довідники: - [Memory configuration reference](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації Dreaming у `plugins.entries.memory-core.config.dreaming` -- [Slash commands](/uk/tools/slash-commands) для поточного каталогу вбудованих + комплектних команд -- сторінки відповідних каналів/плагінів для поверхонь команд, специфічних для каналів +- [Slash commands](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд +- сторінки каналу/Plugin-власника для поверхонь команд, специфічних для каналу -Формат конфігурації — **JSON5** (дозволені коментарі та завершальні коми). Усі поля необов’язкові — OpenClaw використовує безпечні типові значення, якщо їх не вказано. +Формат конфігурації — **JSON5** (дозволені коментарі та завершальні коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх не вказано. --- ## Канали -Ключі конфігурації для окремих каналів перенесено на окрему сторінку — див. +Ключі конфігурації для кожного каналу перенесено на окрему сторінку — див. [Configuration — channels](/uk/gateway/config-channels) для `channels.*`, -включно зі Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та іншими -вбудованими каналами (автентифікація, контроль доступу, кілька облікових записів, обмеження згадок). +зокрема Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та інших +bundled каналів (автентифікація, контроль доступу, мультиакаунтність, згадування). -## Типові параметри агента, мультиагентність, сесії та повідомлення +## Значення агентів за замовчуванням, мультиагентність, сесії та повідомлення -Перенесено на окрему сторінку — див. [Configuration — agents](/uk/gateway/config-agents) для: +Перенесено на окрему сторінку — див. +[Configuration — agents](/uk/gateway/config-agents) для: -- `agents.defaults.*` (робочий простір, модель, thinking, Heartbeat, пам’ять, медіа, Skills, sandbox) +- `agents.defaults.*` (робочий простір, модель, thinking, heartbeat, пам’ять, медіа, skills, sandbox) - `multiAgent.*` (маршрутизація та прив’язки мультиагентності) - `session.*` (життєвий цикл сесії, Compaction, очищення) - `messages.*` (доставка повідомлень, TTS, рендеринг markdown) - `talk.*` (режим Talk) - `talk.speechLocale`: необов’язковий ідентифікатор локалі BCP 47 для розпізнавання мовлення Talk на iOS/macOS - - `talk.silenceTimeoutMs`: якщо не задано, Talk зберігає типове для платформи вікно паузи перед надсиланням транскрипту (`700 ms на macOS і Android, 900 ms на iOS`) + - `talk.silenceTimeoutMs`: якщо не задано, Talk зберігає стандартне для платформи вікно паузи перед надсиланням транскрипту (`700 ms на macOS і Android, 900 ms на iOS`) -## Інструменти та користувацькі провайдери +## Інструменти та власні провайдери -Політика інструментів, експериментальні перемикачі, конфігурація інструментів на основі провайдерів і налаштування користувацьких провайдерів / базових URL перенесені на окрему сторінку — див. +Політика інструментів, experimental-перемикачі, конфігурація інструментів із підтримкою провайдерів і налаштування +власних провайдерів / базових URL перенесені на окрему сторінку — див. [Configuration — tools and custom providers](/uk/gateway/config-tools). ## MCP -Визначення серверів MCP під керуванням OpenClaw розміщуються в `mcp.servers` і +Визначення MCP-серверів, керованих OpenClaw, знаходяться в `mcp.servers` і використовуються вбудованим Pi та іншими адаптерами середовища виконання. Команди `openclaw mcp list`, `show`, `set` і `unset` керують цим блоком без підключення до цільового сервера під час редагування конфігурації. @@ -72,7 +74,7 @@ x-i18n: ```json5 { mcp: { - // Необов’язково. Типове значення: 600000 ms (10 хвилин). Установіть 0, щоб вимкнути видалення під час простою. + // Optional. Default: 600000 ms (10 minutes). Set 0 to disable idle eviction. sessionIdleTtlMs: 600000, servers: { docs: { @@ -91,20 +93,20 @@ x-i18n: } ``` -- `mcp.servers`: іменовані визначення stdio або віддалених серверів MCP для середовищ виконання, які - надають налаштовані інструменти MCP. +- `mcp.servers`: іменовані визначення stdio або віддалених MCP-серверів для середовищ виконання, які + відкривають налаштовані інструменти MCP. Віддалені записи використовують `transport: "streamable-http"` або `transport: "sse"`; - `type: "http"` — це рідний для CLI псевдонім, який `openclaw mcp set` і - `openclaw doctor --fix` нормалізують у канонічне поле `transport`. -- `mcp.sessionIdleTtlMs`: TTL простою для комплектних середовищ MCP, прив’язаних до сесії. - Одноразові вбудовані запуски запитують очищення після завершення запуску; цей TTL є - страховкою для довготривалих сесій і майбутніх викликачів. -- Зміни в `mcp.*` застосовуються на гарячу через знищення кешованих середовищ MCP сесії. - Наступне виявлення/використання інструмента відтворює їх із нової конфігурації, тож вилучені - записи `mcp.servers` прибираються негайно, а не чекають TTL простою. + `type: "http"` — це псевдонім на рівні CLI, який `openclaw mcp set` і + `openclaw doctor --fix` нормалізують до канонічного поля `transport`. +- `mcp.sessionIdleTtlMs`: TTL бездіяльності для прив’язаних до сесії bundled MCP runtime. + Одноразові вбудовані запуски запитують очищення після завершення виконання; цей TTL є резервним механізмом для + довготривалих сесій і майбутніх викликів. +- Зміни в `mcp.*` застосовуються гарячим способом через вивільнення кешованих session MCP runtime. + Наступне виявлення/використання інструмента відтворює їх із нової конфігурації, тому вилучені записи + `mcp.servers` прибираються негайно замість очікування TTL бездіяльності. Див. [MCP](/uk/cli/mcp#openclaw-as-an-mcp-client-registry) і -[CLI backends](/uk/gateway/cli-backends#bundle-mcp-overlays) для поведінки середовища виконання. +[CLI backends](/uk/gateway/cli-backends#bundle-mcp-overlays) щодо поведінки середовища виконання. ## Skills @@ -121,7 +123,7 @@ x-i18n: }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // або plaintext string + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -131,18 +133,18 @@ x-i18n: } ``` -- `allowBundled`: необов’язковий список дозволу лише для комплектних Skills (керовані/робочі Skills не зачіпаються). -- `load.extraDirs`: додаткові спільні корені Skills (найнижчий пріоритет). -- `install.preferBrew`: якщо `true`, віддавати перевагу інсталяторам Homebrew, коли `brew` +- `allowBundled`: необов’язковий список дозволу лише для bundled skills (на керовані/workspace skills не впливає). +- `load.extraDirs`: додаткові спільні кореневі каталоги skills (найнижчий пріоритет). +- `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, навіть якщо він комплектний/встановлений. -- `entries..apiKey`: зручне поле для Skills, які оголошують основну змінну середовища (рядок відкритого тексту або об’єкт SecretRef). +- `entries..enabled: false` вимикає skill, навіть якщо він bundled/встановлений. +- `entries..apiKey`: зручне поле для skills, які оголошують основну змінну середовища (простий рядок або об’єкт SecretRef). --- -## Плагіни +## Plugins ```json5 { @@ -167,40 +169,40 @@ x-i18n: ``` - Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. -- Виявлення приймає нативні плагіни OpenClaw, а також сумісні комплектні пакети Codex і Claude, включно з комплектами Claude стандартного макета без маніфесту. -- **Зміни конфігурації потребують перезапуску gateway.** -- `allow`: необов’язковий список дозволу (завантажуються лише перелічені плагіни). `deny` має пріоритет. -- `plugins.entries..apiKey`: зручне поле API-ключа на рівні плагіна (коли підтримується плагіном). -- `plugins.entries..env`: мапа змінних середовища на рівні плагіна. -- `plugins.entries..hooks.allowPromptInjection`: коли `false`, ядро блокує `before_prompt_build` і ігнорує поля, що змінюють prompt, із застарілого `before_agent_start`, зберігаючи застарілі `modelOverride` і `providerOverride`. Застосовується до нативних hook-ів плагінів і підтримуваних каталогів hook-ів, наданих комплектами. -- `plugins.entries..hooks.allowConversationAccess`: коли `true`, довірені некомплектні плагіни можуть читати сирий вміст розмов із типізованих hook-ів, таких як `llm_input`, `llm_output`, `before_agent_finalize` та `agent_end`. -- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому плагіну запитувати перевизначення `provider` і `model` для окремого запуску фонових підлеглих агентів. -- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволу канонічних цілей `provider/model` для довірених перевизначень підлеглих агентів. Використовуйте `"*"`, лише якщо навмисно хочете дозволити будь-яку модель. -- `plugins.entries..config`: об’єкт конфігурації, визначений плагіном (перевіряється схемою нативного плагіна OpenClaw, якщо доступна). -- Налаштування облікового запису/середовища виконання для каналів плагінів розміщуються в `channels.` і мають описуватися метаданими `channelConfigs` у маніфесті відповідного плагіна, а не центральним реєстром параметрів OpenClaw. -- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера веб-отримання Firecrawl. - - `apiKey`: API-ключ Firecrawl (приймає SecretRef). Використовує як резерв `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілий `tools.web.fetch.firecrawl.apiKey` або змінну середовища `FIRECRAWL_API_KEY`. +- Виявлення приймає нативні Plugin OpenClaw, а також сумісні пакети Codex і Claude, зокрема пакети Claude стандартного макета без маніфесту. +- **Зміни конфігурації потребують перезапуску Gateway.** +- `allow`: необов’язковий список дозволу (завантажуються лише перелічені Plugin). `deny` має пріоритет. +- `plugins.entries..apiKey`: зручне поле API-ключа на рівні Plugin (коли Plugin це підтримує). +- `plugins.entries..env`: мапа змінних середовища в межах Plugin. +- `plugins.entries..hooks.allowPromptInjection`: коли `false`, ядро блокує `before_prompt_build` та ігнорує поля зі зміною prompt із застарілого `before_agent_start`, водночас зберігаючи застарілі `modelOverride` і `providerOverride`. Застосовується до нативних hook-ів Plugin і підтримуваних каталогів hook-ів, наданих пакетами. +- `plugins.entries..hooks.allowConversationAccess`: коли `true`, довірені небандловані Plugin можуть читати необроблений вміст розмови з типізованих hook-ів, таких як `llm_input`, `llm_output`, `before_agent_finalize` і `agent_end`. +- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для кожного запуску фонових підагентів. +- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволу канонічних цілей `provider/model` для довірених перевизначень підагента. Використовуйте `"*"` лише тоді, коли ви свідомо хочете дозволити будь-яку модель. +- `plugins.entries..config`: визначений Plugin об’єкт конфігурації (валідується за схемою нативного Plugin OpenClaw, якщо вона доступна). +- Налаштування акаунта/runtime для Plugin-каналів знаходяться в `channels.` і мають описуватися метаданими `channelConfigs` маніфесту Plugin-власника, а не центральним реєстром параметрів OpenClaw. +- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера web-fetch Firecrawl. + - `apiKey`: API-ключ Firecrawl (приймає SecretRef). Використовує `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілий `tools.web.fetch.firecrawl.apiKey` або змінну середовища `FIRECRAWL_API_KEY`, якщо основне значення відсутнє. - `baseUrl`: базовий URL API Firecrawl (типово: `https://api.firecrawl.dev`). - - `onlyMainContent`: витягувати лише основний вміст сторінок (типово: `true`). + - `onlyMainContent`: витягувати лише основний вміст зі сторінок (типово: `true`). - `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні). - - `timeoutSeconds`: тайм-аут запиту скрейпінгу в секундах (типово: `60`). + - `timeoutSeconds`: тайм-аут запиту на збирання в секундах (типово: `60`). - `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (вебпошук Grok). - - `enabled`: увімкнути провайдера X Search. + - `enabled`: увімкнути провайдер X Search. - `model`: модель Grok для пошуку (наприклад, `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: налаштування Dreaming для пам’яті. Див. [Dreaming](/uk/concepts/dreaming) для фаз і порогів. - - `enabled`: головний перемикач Dreaming (типово `false`). - - `frequency`: Cron-ритм для кожного повного проходу Dreaming (типово `"0 3 * * *"`). - - `model`: необов’язкове перевизначення моделі підлеглого агента Dream Diary. Потребує `plugins.entries.memory-core.subagent.allowModelOverride: true`; поєднуйте з `allowedModels`, щоб обмежити цілі. +- `plugins.entries.memory-core.config.dreaming`: налаштування dreaming пам’яті. Див. [Dreaming](/uk/concepts/dreaming) щодо фаз і порогів. + - `enabled`: головний перемикач dreaming (типово `false`). + - `frequency`: Cron-частота для кожного повного проходу dreaming (типово `"0 3 * * *"`). + - `model`: необов’язкове перевизначення моделі підагента Dream Diary. Потребує `plugins.entries.memory-core.subagent.allowModelOverride: true`; поєднуйте з `allowedModels`, щоб обмежити цілі. - політика фаз і пороги є деталями реалізації (не користувацькими ключами конфігурації). -- Повна конфігурація пам’яті міститься в [Memory configuration reference](/uk/reference/memory-config): +- Повна конфігурація пам’яті наведена в [Memory configuration reference](/uk/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Увімкнені комплектні плагіни Claude також можуть додавати типові значення вбудованого Pi з `settings.json`; OpenClaw застосовує їх як санітизовані налаштування агента, а не як сирі патчі конфігурації OpenClaw. -- `plugins.slots.memory`: вибрати ідентифікатор активного плагіна пам’яті або `"none"`, щоб вимкнути плагіни пам’яті. -- `plugins.slots.contextEngine`: вибрати ідентифікатор активного плагіна рушія контексту; типово `"legacy"`, якщо ви не встановите й не виберете інший рушій. +- Увімкнені Plugin-пакети Claude також можуть додавати вбудовані значення Pi за замовчуванням із `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як сирі патчі конфігурації OpenClaw. +- `plugins.slots.memory`: вибрати ідентифікатор активного Plugin пам’яті або `"none"`, щоб вимкнути Plugin пам’яті. +- `plugins.slots.contextEngine`: вибрати ідентифікатор активного Plugin рушія контексту; типово `"legacy"`, якщо ви не встановили й не вибрали інший рушій. Див. [Plugins](/uk/tools/plugin). @@ -215,8 +217,8 @@ x-i18n: evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // вмикайте лише для довіреного доступу до приватної мережі - // allowPrivateNetwork: true, // застарілий псевдонім + // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access + // allowPrivateNetwork: true, // legacy alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -253,48 +255,48 @@ x-i18n: ``` - `evaluateEnabled: false` вимикає `act:evaluate` і `wait --fn`. -- `tabCleanup` очищає відстежувані вкладки основного агента після простою або коли +- `tabCleanup` звільняє відстежувані вкладки основного агента після періоду простою або коли сесія перевищує свій ліміт. Установіть `idleMinutes: 0` або `maxTabsPerSession: 0`, щоб вимкнути ці окремі режими очищення. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тож навігація браузера за типових налаштувань залишається суворо обмеженою. -- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації браузера до приватної мережі. -- У суворому режимі віддалені кінцеві точки профілів CDP (`profiles.*.cdpUrl`) підпадають під те саме блокування приватної мережі під час перевірок доступності/виявлення. -- `ssrfPolicy.allowPrivateNetwork` і надалі підтримується як застарілий псевдонім. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому навігація браузера типово залишається суворо обмеженою. +- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації браузера в приватній мережі. +- У суворому режимі віддалені кінцеві точки профілів CDP (`profiles.*.cdpUrl`) підлягають тому самому блокуванню приватної мережі під час перевірок доступності/виявлення. +- `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім. - У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків. -- Віддалені профілі працюють лише в режимі підключення (запуск/зупинка/скидання вимкнено). +- Віддалені профілі працюють лише в режимі підключення (start/stop/reset вимкнено). - `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`. - Використовуйте HTTP(S), якщо хочете, щоб OpenClaw виявляв `/json/version`; використовуйте WS(S), - коли ваш провайдер надає вам прямий URL WebSocket DevTools. -- `remoteCdpTimeoutMs` і `remoteCdpHandshakeTimeoutMs` застосовуються до перевірки доступності віддаленого й - `attachOnly` CDP, а також до запитів на відкриття вкладок. Керовані loopback- - профілі зберігають типові локальні значення CDP. + Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявив `/json/version`; використовуйте WS(S), + коли ваш провайдер надає прямий URL DevTools WebSocket. +- `remoteCdpTimeoutMs` і `remoteCdpHandshakeTimeoutMs` застосовуються до віддаленої та + `attachOnly`-доступності CDP, а також до запитів на відкриття вкладок. Керовані loopback-профілі + зберігають локальні значення CDP за замовчуванням. - Якщо зовнішньо керований сервіс CDP доступний через loopback, установіть для цього - профілю `attachOnly: true`; інакше OpenClaw вважатиме порт loopback - локальним керованим профілем браузера й може повідомляти про помилки володіння локальним портом. -- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися до - вибраного хоста або через підключений вузол браузера. -- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний + профілю `attachOnly: true`; інакше OpenClaw трактуватиме loopback-порт як + локальний керований профіль браузера й може повідомляти про помилки володіння локальним портом. +- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися на + вибраному хості або через підключений вузол браузера. +- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлюватися на конкретний профіль браузера на базі Chromium, наприклад Brave або Edge. - Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP: - дії на основі snapshot/ref замість націлювання через CSS-селектори, однофайлові hook-и завантаження, - відсутність перевизначення тайм-аутів діалогів, відсутність `wait --load networkidle`, а також + дії на основі snapshot/ref замість таргетингу через CSS-селектори, hook-и завантаження одного файлу, + без перевизначення тайм-ауту діалогів, без `wait --load networkidle`, а також без `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій. - Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно задавайте `cdpUrl` лише для віддаленого CDP. - Локальні керовані профілі можуть задавати `executablePath`, щоб перевизначити глобальний `browser.executablePath` для цього профілю. Використовуйте це, щоб запускати один профіль у - Chrome, а інший — у Brave. + 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` + готовності CDP websocket після запуску. Збільшуйте їх на повільніших хостах, де Chrome + запускається успішно, але перевірки готовності випереджають завершення старту. Обидва значення мають бути + додатними цілими числами до `120000` ms; недійсні значення конфігурації відхиляються. +- Порядок автовиявлення: браузер за замовчуванням, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- `browser.executablePath` і `browser.profiles..executablePath` обидва приймають `~` і `~/...` для домашнього каталогу вашої ОС перед запуском Chromium. - `userDataDir` для профілів `existing-session` на рівні профілю також розгортається з тильдою. -- Служба керування: лише loopback (порт визначається з `gateway.port`, типово `18791`). -- `extraArgs` додає додаткові прапорці запуску до локального запуску Chromium (наприклад, + Для `userDataDir` у профілях `existing-session` також виконується розгортання тильди. +- Сервіс керування: лише loopback (порт визначається з `gateway.port`, типово `18791`). +- `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад, `--disable-gpu`, розмір вікна або прапорці налагодження). --- @@ -313,8 +315,8 @@ x-i18n: } ``` -- `seamColor`: акцентний колір для chrome нативного UI застосунку (відтінок бульбашки режиму Talk тощо). -- `assistant`: перевизначення ідентичності для Control UI. Використовує ідентичність активного агента як резервну. +- `seamColor`: колір акценту для chrome інтерфейсу нативного застосунку (відтінок бульбашки режиму Talk тощо). +- `assistant`: перевизначення ідентичності для Control UI. Якщо не задано, використовується ідентичність активного агента. --- @@ -389,73 +391,73 @@ x-i18n: } ``` - + - `mode`: `local` (запустити gateway) або `remote` (підключитися до віддаленого gateway). Gateway відмовляється запускатися, якщо не `local`. - `port`: єдиний мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (типово), `lan` (`0.0.0.0`), `tailnet` (лише IP Tailscale) або `custom`. - **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хоста (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Примітка щодо Docker**: типове прив’язування `loopback` слухає `127.0.0.1` всередині контейнера. За мостової мережі Docker (`-p 18789:18789`) трафік надходить на `eth0`, тому gateway недосяжний. Використовуйте `--network host` або задайте `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. -- **Auth**: за типових налаштувань обов’язкова. Прив’язки не до loopback вимагають автентифікації gateway. На практиці це означає спільний токен/пароль або reverse proxy з контролем ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер первинного налаштування типово генерує токен. -- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно задайте `gateway.auth.mode` як `token` або `password`. Запуск і потоки встановлення/відновлення служби завершуються помилкою, коли задано обидва, а режим не вказано. -- `gateway.auth.mode: "none"`: явний режим без автентифікації. Використовуйте лише для довірених локальних конфігурацій local loopback; цей варіант навмисно не пропонується в підказках первинного налаштування. -- `gateway.auth.mode: "trusted-proxy"`: делегувати автентифікацію reverse proxy з контролем ідентичності й довіряти заголовкам ідентичності з `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; reverse proxy на loopback на тому самому хості не задовольняють автентифікацію 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-адреси клієнта та для кожної області автентифікації (спільний секрет і токен пристрою відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`. - - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому паралельні хибні спроби від того самого клієнта можуть спрацювати на обмежувачі на другому запиті, а не обидві пройти як звичайні невідповідності. - - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; задайте `false`, якщо ви свідомо хочете також обмежувати localhost-трафік (для тестових конфігурацій або суворих розгортань із proxy). -- Спроби WS-автентифікації з походження браузера завжди обмежуються з вимкненим винятком для loopback (додатковий захист від brute force до localhost із браузера). -- На loopback ці блокування за походженням браузера ізолюються за нормалізованим - значенням `Origin`, тому повторні невдалі спроби з одного localhost-origin не +- **Примітка щодо Docker**: bind `loopback` за замовчуванням слухає `127.0.0.1` усередині контейнера. Із bridge-мережею Docker (`-p 18789:18789`) трафік надходить через `eth0`, тому gateway недосяжний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. +- **Автентифікація**: типово обов’язкова. Binds не на loopback потребують автентифікації gateway. На практиці це означає спільний token/password або reverse proxy з контролем ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер початкового налаштування типово генерує token. +- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (зокрема через SecretRef), явно задайте `gateway.auth.mode` як `token` або `password`. Під час запуску та в потоках встановлення/відновлення сервісу стається помилка, якщо налаштовано обидва, а mode не задано. +- `gateway.auth.mode: "none"`: явний режим без автентифікації. Використовуйте лише для довірених локальних конфігурацій local loopback; цей варіант навмисно не пропонується в запитах початкового налаштування. +- `gateway.auth.mode: "trusted-proxy"`: делегує автентифікацію браузера/користувача reverse proxy з контролем ідентичності та довіряє заголовкам ідентичності від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; reverse proxy на тому самому хості через loopback не задовольняють вимоги trusted-proxy для автентифікації ідентичності. Внутрішні виклики на тому самому хості можуть використовувати `gateway.auth.password` як локальний прямий резервний варіант; `gateway.auth.token` і далі взаємовиключний із режимом trusted-proxy. +- `gateway.auth.allowTailscale`: коли `true`, заголовки ідентичності Tailscale Serve можуть задовольняти автентифікацію Control UI/WebSocket (перевіряється через `tailscale whois`). Кінцеві точки HTTP API **не** використовують цю автентифікацію заголовками Tailscale; натомість вони дотримуються звичайного режиму HTTP-автентифікації gateway. Цей потік без token припускає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб автентифікації. Застосовується для кожного IP клієнта та для кожної області автентифікації (спільний секрет і token пристрою відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`. + - В асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому одночасні хибні спроби від того самого клієнта можуть спровокувати спрацювання обмежувача на другому запиті, замість того щоб обидві одночасно пройти як звичайні невідповідності. + - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; установіть `false`, коли ви свідомо хочете, щоб трафік localhost теж підлягав rate limiting (для тестових конфігурацій або суворих розгортань через proxy). +- Спроби автентифікації WS із браузерного origin завжди обмежуються без винятку для loopback (додатковий захист від brute force localhost із браузера). +- На loopback ці блокування для браузерних origin ізолюються за нормалізованим + значенням `Origin`, тому повторні невдалі спроби з одного localhost origin не блокують автоматично інший origin. -- `tailscale.mode`: `serve` (лише tailnet, прив’язка loopback) або `funnel` (публічно, вимагає auth). -- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються клієнти браузера з origin не-loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає резервне визначення origin за заголовком Host для розгортань, що свідомо покладаються на політику origin за Host-заголовком. -- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` `remote.url` має бути `ws://` або `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: аварійне перевизначення - середовища процесу на боці клієнта, яке дозволяє plaintext `ws://` до довірених IP - приватної мережі; типово plaintext, як і раніше, дозволено лише для loopback. Еквівалента в `openclaw.json` - немає, а конфігурація приватної мережі браузера, наприклад - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, не впливає на клієнти - Gateway WebSocket. -- `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують auth gateway. -- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL зовнішнього APNs relay, який використовують офіційні/TestFlight-збірки iOS після того, як вони публікують у gateway реєстрації на основі relay. Цей URL має збігатися з URL relay, скомпільованим у збірці iOS. -- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання gateway-to-relay у мілісекундах. Типове значення — `10000`. -- Реєстрації на основі relay делегуються конкретній ідентичності gateway. Спарений застосунок iOS отримує `gateway.identity.get`, включає цю ідентичність до реєстрації relay і передає до gateway дозвіл на надсилання в межах реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові перевизначення середовища для наведеної вище конфігурації relay. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний варіант лише для розробки для loopback HTTP URL relay. URL relay у продакшені мають залишатися на HTTPS. -- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналів у хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски монітора стану. Типове значення: `5`. -- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета у хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типове значення: `30`. -- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітора стану на канал/обліковий запис у ковзній годині. Типове значення: `10`. -- `channels..healthMonitor.enabled`: вимкнення перезапусків монітора стану для окремого каналу зі збереженням глобального монітора увімкненим. -- `channels..accounts..healthMonitor.enabled`: перевизначення на рівні облікового запису для каналів із кількома обліковими записами. Якщо задано, має пріоритет над перевизначенням на рівні каналу. -- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резерв лише тоді, коли `gateway.auth.*` не задано. -- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не вдається розв’язати, розв’язання завершується із закритою відмовою (без маскування резервним віддаленим варіантом). -- `trustedProxies`: IP-адреси reverse proxy, які завершують TLS або вставляють заголовки пересланого клієнта. Указуйте лише proxy, які ви контролюєте. Записи loopback усе ще дійсні для конфігурацій із proxy на тому самому хості/локальним виявленням (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. Типове значення `false` для поведінки fail-closed. -- `gateway.nodes.pairing.autoApproveCidrs`: необов’язковий список дозволених CIDR/IP для автоматичного схвалення першого спарювання вузла пристрою без запитаних областей доступу. Якщо не задано, вимкнено. Це не виконує автоматичне схвалення pairing для operator/browser/Control UI/WebChat і не схвалює автоматично оновлення ролі, області доступу, метаданих або публічного ключа. -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування allow/deny для оголошених команд вузлів після pairing та оцінки списку дозволу. -- `gateway.tools.deny`: додаткові імена інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список deny). -- `gateway.tools.allow`: прибирає імена інструментів із типового списку deny. +- `tailscale.mode`: `serve` (лише tailnet, bind на loopback) або `funnel` (публічний доступ, потрібна автентифікація). +- `controlUi.allowedOrigins`: явний allowlist browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються браузерні клієнти з origin не на loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає fallback origin через заголовок Host для розгортань, що навмисно покладаються на політику origin на основі заголовка Host. +- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: аварійний override через + змінну середовища клієнтського процесу, який дозволяє незашифрований `ws://` до довірених IP + приватної мережі; типово незашифрований трафік, як і раніше, дозволено лише для loopback. Еквівалента в `openclaw.json` + немає, а конфігурація приватної мережі браузера, така як + `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, не впливає на + клієнти Gateway WebSocket. +- `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують автентифікацію gateway. +- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL для зовнішнього relay APNs, який використовують офіційні/TestFlight-збірки iOS після публікації relay-backed реєстрацій у gateway. Цей URL має збігатися з URL relay, вбудованим у збірку iOS. +- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до relay у мілісекундах. Типово `10000`. +- Реєстрації через relay делегуються конкретній ідентичності gateway. Спарений застосунок iOS отримує `gateway.identity.get`, включає цю ідентичність у реєстрацію relay і пересилає gateway дозвіл на надсилання в межах цієї реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові override через змінні середовища для наведеної вище конфігурації relay. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний виняток лише для розробки для URL relay через loopback HTTP. URL relay у production мають залишатися на HTTPS. +- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналу в хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски монітора стану. Типово: `5`. +- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`. +- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітора стану на канал/акаунт за ковзну годину. Типово: `10`. +- `channels..healthMonitor.enabled`: відмова на рівні каналу від перезапусків монітора стану за збереження глобального монітора ввімкненим. +- `channels..accounts..healthMonitor.enabled`: перевизначення для конкретного акаунта в мультиакаунтних каналах. Якщо задано, має пріоритет над перевизначенням на рівні каналу. +- Локальні шляхи викликів gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано. +- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і його не вдається розв’язати, розв’язання завершується з fail-closed (без маскування резервним remote fallback). +- `trustedProxies`: IP reverse proxy, які завершують TLS або додають заголовки перенаправленого клієнта. Вказуйте лише proxy, які ви контролюєте. Записи loopback усе ще дійсні для конфігурацій proxy/локального виявлення на тому самому хості (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. Типово `false` для поведінки fail-closed. +- `gateway.nodes.pairing.autoApproveCidrs`: необов’язковий allowlist CIDR/IP для автоматичного схвалення першого спарювання пристрою вузла без запитаних scope. Якщо не задано, вимкнено. Це не схвалює автоматично спарювання operator/browser/Control UI/WebChat і не схвалює автоматично оновлення ролі, scope, metadata або публічного ключа. +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування allow/deny для оголошених команд вузла після спарювання та перевірки allowlist. +- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий deny list). +- `gateway.tools.allow`: прибирає назви інструментів із типового HTTP deny list. -### OpenAI-compatible endpoints +### Кінцеві точки, сумісні з OpenAI - Chat Completions: типово вимкнено. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`. -- Responses API: `gateway.http.endpoints.responses.enabled`. -- Захист URL-входів Responses: +- API Responses: `gateway.http.endpoints.responses.enabled`. +- Посилення захисту URL-входів Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Порожні списки дозволу трактуються як незадані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` - і/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. -- Необов’язковий заголовок захисту відповіді: - - `gateway.http.securityHeaders.strictTransportSecurity` (задавайте лише для HTTPS-origin, які ви контролюєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + Порожні allowlist трактуються як незадані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` + та/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. +- Необов’язковий заголовок посиленого захисту відповіді: + - `gateway.http.securityHeaders.strictTransportSecurity` (задавайте лише для HTTPS origin, які ви контролюєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) ### Ізоляція кількох екземплярів -Запускайте кілька gateway на одному хості з унікальними портами й каталогами стану: +Запускайте кілька gateway на одному хості з унікальними портами та каталогами стану: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -484,10 +486,10 @@ openclaw gateway --port 19001 ``` - `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типово: `false`). -- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовано; лише для локального/dev використання. -- `certPath`: шлях файлової системи до файла TLS-сертифіката. -- `keyPath`: шлях файлової системи до файла приватного ключа TLS; зберігайте з обмеженими дозволами. -- `caPath`: необов’язковий шлях до пакета CA для перевірки клієнтів або користувацьких ланцюгів довіри. +- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, якщо явні файли не налаштовані; лише для локального/dev використання. +- `certPath`: шлях у файловій системі до файлу сертифіката TLS. +- `keyPath`: шлях у файловій системі до файлу приватного ключа TLS; обмежте доступ до нього правами. +- `caPath`: необов’язковий шлях до пакета CA для перевірки клієнта або власних ланцюжків довіри. ### `gateway.reload` @@ -504,16 +506,16 @@ openclaw gateway --port 19001 ``` - `mode`: керує тим, як зміни конфігурації застосовуються під час виконання. - - `"off"`: ігнорувати живі редагування; зміни вимагають явного перезапуску. + - `"off"`: ігнорувати живі зміни; зміни потребують явного перезапуску. - `"restart"`: завжди перезапускати процес gateway при зміні конфігурації. - `"hot"`: застосовувати зміни в процесі без перезапуску. - - `"hybrid"` (типово): спочатку спробувати гаряче перезавантаження; за потреби перейти до перезапуску. + - `"hybrid"` (типово): спочатку спробувати hot reload; за потреби перейти до перезапуску. - `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число). -- `deferralTimeoutMs`: необов’язковий максимальний час у мс очікування завершення поточних операцій перед примусовим перезапуском. Пропустіть його або встановіть `0`, щоб чекати безстроково й періодично журналювати попередження про те, що щось усе ще очікує завершення. +- `deferralTimeoutMs`: необов’язковий максимальний час у мс очікування завершення операцій у польоті перед примусовим перезапуском. Не вказуйте його або встановіть `0`, щоб чекати безстроково й періодично журналювати попередження про те, що ще є незавершені операції. --- -## Hooks +## Hook-и ```json5 { @@ -546,16 +548,16 @@ openclaw gateway --port 19001 } ``` -Auth: `Authorization: Bearer ` або `x-openclaw-token: `. -Токени hook у рядку запиту відхиляються. +Автентифікація: `Authorization: Bearer ` або `x-openclaw-token: `. +Hook token у рядку запиту відхиляються. Примітки щодо валідації та безпеки: -- `hooks.enabled=true` вимагає непорожнього `hooks.token`. -- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання токена Gateway відхиляється. -- `hooks.path` не може бути `/`; використовуйте виділений підшлях, наприклад `/hooks`. +- `hooks.enabled=true` потребує непорожнього `hooks.token`. +- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання token Gateway відхиляється. +- `hooks.path` не може бути `/`; використовуйте окремий підшлях, наприклад `/hooks`. - Якщо `hooks.allowRequestSessionKey=true`, обмежте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). -- Якщо mapping або preset використовує шаблонізований `sessionKey`, задайте `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не вимагають цього явного дозволу. +- Якщо mapping або preset використовує шаблонізований `sessionKey`, задайте `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не потребують цього opt-in. **Кінцеві точки:** @@ -563,21 +565,21 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - `sessionKey` із тіла запиту приймається лише тоді, коли `hooks.allowRequestSessionKey=true` (типово: `false`). - `POST /hooks/` → розв’язується через `hooks.mappings` - - Значення `sessionKey` у mapping, згенеровані шаблоном, вважаються зовнішньо переданими й також вимагають `hooks.allowRequestSessionKey=true`. + - Значення `sessionKey` у mapping, згенеровані шаблоном, вважаються зовнішньо наданими й також потребують `hooks.allowRequestSessionKey=true`. - + -- `match.path` зіставляється з підшляхом після `/hooks` (наприклад, `/hooks/gmail` → `gmail`). -- `match.source` зіставляється з полем payload для загальних шляхів. -- Шаблони на кшталт `{{messages[0].subject}}` читаються з payload. -- `transform` може вказувати на модуль JS/TS, який повертає дію hook. +- `match.path` відповідає підшляху після `/hooks` (наприклад, `/hooks/gmail` → `gmail`). +- `match.source` відповідає полю payload для загальних шляхів. +- Шаблони на кшталт `{{messages[0].subject}}` читають дані з payload. +- `transform` може вказувати на JS/TS-модуль, який повертає дію hook. - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та traversal відхиляються). -- `agentId` маршрутизує до конкретного агента; невідомі ідентифікатори повертаються до типового. -- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити всі, `[]` = заборонити всі). +- `agentId` маршрутизує до конкретного агента; невідомі ID повертаються до типового. +- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або не задано = дозволити все, `[]` = заборонити все). - `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook-агента без явного `sessionKey`. -- `allowRequestSessionKey`: дозволити викликачам `/hooks/agent` і ключам сесії mapping на основі шаблонів задавати `sessionKey` (типово: `false`). -- `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Стає обов’язковим, коли будь-який mapping або preset використовує шаблонізований `sessionKey`. -- `deliver: true` надсилає фінальну відповідь у канал; `channel` типово дорівнює `last`. +- `allowRequestSessionKey`: дозволяє викликам `/hooks/agent` і ключам сесії mapping, керованим шаблонами, задавати `sessionKey` (типово: `false`). +- `allowedSessionKeyPrefixes`: необов’язковий prefix allowlist для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Стає обов’язковим, коли будь-який mapping або preset використовує шаблонізований `sessionKey`. +- `deliver: true` надсилає фінальну відповідь до каналу; `channel` типово дорівнює `last`. - `model` перевизначає LLM для цього запуску hook (має бути дозволена, якщо задано каталог моделей). @@ -585,8 +587,8 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ### Інтеграція Gmail - Вбудований preset Gmail використовує `sessionKey: "hook:gmail:{{messages[0].id}}"`. -- Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, задайте `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes` так, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. -- Якщо вам потрібне `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість типового шаблонізованого. +- Якщо ви зберігаєте таку маршрутизацію за кожним повідомленням, установіть `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes` так, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. +- Якщо вам потрібне `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість шаблонного значення за замовчуванням. ```json5 { @@ -609,7 +611,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, коли це налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути. +- Gateway автоматично запускає `gog gmail watch serve` під час старту, коли це налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути. - Не запускайте окремий `gog gmail watch serve` паралельно з Gateway. --- @@ -629,15 +631,15 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - Обслуговує HTML/CSS/JS, які агент може редагувати, і A2UI через HTTP на порту Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- Лише локально: зберігайте `gateway.bind: "loopback"` (типово). -- Прив’язки не до loopback: маршрути canvas вимагають auth Gateway (token/password/trusted-proxy), так само як і інші HTTP-поверхні Gateway. -- Node WebView зазвичай не надсилають заголовки auth; після pairing і підключення вузла Gateway оголошує URL можливостей у межах вузла для доступу до canvas/A2UI. +- Лише локально: залишайте `gateway.bind: "loopback"` (типово). +- Для bind не на loopback: маршрути canvas потребують автентифікації Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway. +- Node WebView зазвичай не надсилають заголовки автентифікації; після спарювання та підключення вузла Gateway рекламує URL можливостей у межах вузла для доступу до canvas/A2UI. - URL можливостей прив’язані до активної WS-сесії вузла й швидко спливають. Резервний варіант на основі IP не використовується. -- Впроваджує клієнт live-reload у HTML, що обслуговується. +- Впроваджує клієнт live reload у HTML, що обслуговується. - Автоматично створює стартовий `index.html`, якщо каталог порожній. - Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`. -- Зміни вимагають перезапуску gateway. -- Вимкніть live reload для великих каталогів або за помилок `EMFILE`. +- Зміни потребують перезапуску gateway. +- Вимкніть live reload для великих каталогів або у разі помилок `EMFILE`. --- @@ -655,9 +657,9 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `minimal` (типово): пропускає `cliPath` + `sshPort` із TXT-записів. -- `full`: включає `cliPath` + `sshPort`. -- Ім’я хоста типово дорівнює системному імені хоста, якщо воно є дійсною DNS-міткою, інакше використовується `openclaw`. Перевизначте через `OPENCLAW_MDNS_HOSTNAME`. +- `minimal` (типово): не включає `cliPath` і `sshPort` до TXT-записів. +- `full`: включає `cliPath` і `sshPort`. +- Ім’я хоста типово береться із системного імені хоста, якщо це дійсна DNS-мітка, інакше використовується `openclaw`. Для перевизначення використовуйте `OPENCLAW_MDNS_HOSTNAME`. ### Wide-area (DNS-SD) @@ -669,7 +671,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + Tailscale split DNS. +Записує unicast-зону DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте це з DNS-сервером (рекомендовано CoreDNS) і split DNS у Tailscale. Налаштування: `openclaw dns setup --apply`. @@ -677,7 +679,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ## Середовище -### `env` (вбудовані env vars) +### `env` (вбудовані змінні середовища) ```json5 { @@ -694,14 +696,14 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Вбудовані env vars застосовуються лише тоді, коли в env процесу відсутній ключ. +- Вбудовані змінні середовища застосовуються лише тоді, коли в середовищі процесу відсутній ключ. - Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). - `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell. -- Повний порядок пріоритетів див. у [Environment](/uk/help/environment). +- Повний порядок пріоритету див. у [Environment](/uk/help/environment). -### Підстановка env var +### Підстановка змінних середовища -Посилайтеся на env vars у будь-якому рядку конфігурації через `${VAR_NAME}`: +Посилайтеся на змінні середовища в будь-якому рядку конфігурації через `${VAR_NAME}`: ```json5 { @@ -711,16 +713,16 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. +- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. - Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації. -- Екрануйте через `$${VAR}` для літерального `${VAR}`. +- Екрануйте через `$${VAR}` для буквального `${VAR}`. - Працює з `$include`. --- ## Секрети -Посилання на секрети є адитивними: значення у відкритому тексті, як і раніше, працюють. +Посилання на секрети є адитивними: прості текстові значення й надалі працюють. ### `SecretRef` @@ -734,15 +736,15 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - шаблон `provider`: `^[a-z][a-z0-9_-]{0,63}$` - шаблон `id` для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` -- `id` для `source: "file"`: абсолютний JSON pointer (наприклад, `"/providers/openai/apiKey"`) +- `id` для `source: "file"`: абсолютний вказівник JSON (наприклад `"/providers/openai/apiKey"`) - шаблон `id` для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `id` для `source: "exec"` не мають містити сегментів шляху `.` або `..`, розділених `/` (наприклад, `a/../b` відхиляється) +- `id` для `source: "exec"` не повинен містити slash-delimited сегментів шляху `.` або `..` (наприклад, `a/../b` відхиляється) ### Підтримувана поверхня облікових даних - Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface) - `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`. -- Посилання в `auth-profiles.json` включено до покриття розв’язання під час виконання та аудиту. +- Посилання в `auth-profiles.json` включено до runtime-розв’язання та покриття аудиту. ### Конфігурація провайдерів секретів @@ -774,18 +776,18 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. Примітки: -- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue `id` має бути `"value"`). -- Шляхи провайдерів file і exec завершуються з відмовою за закритим принципом, коли перевірка ACL Windows недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. -- Провайдер `exec` вимагає абсолютний шлях `command` і використовує payload протоколу через stdin/stdout. -- Типово шляхи команд через symlink відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи symlink із перевіркою розв’язаного цільового шляху. -- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до розв’язаного цільового шляху. -- Середовище дочірнього процесу `exec` типово мінімальне; передавайте потрібні змінні явно через `passEnv`. -- Посилання на секрети розв’язуються під час активації в моментальний знімок у пам’яті, після чого шляхи запитів читають лише цей знімок. -- Під час активації застосовується фільтрація активної поверхні: нерозв’язані посилання на увімкнених поверхнях призводять до помилки запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. +- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue значення `id` має бути `"value"`). +- Шляхи провайдерів file і exec завершуються fail-closed, якщо перевірка Windows ACL недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. +- Провайдер `exec` потребує абсолютного шляху `command` і використовує протокольні payload у stdin/stdout. +- Типово шляхи команд-симлінків відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-симлінки з перевіркою розв’язаного цільового шляху. +- Якщо налаштовано `trustedDirs`, перевірка trusted-dir застосовується до розв’язаного цільового шляху. +- Дочірнє середовище `exec` типово мінімальне; явно передавайте потрібні змінні через `passEnv`. +- Посилання на секрети розв’язуються під час активації в знімок у пам’яті, після чого шляхи запитів читають лише цей знімок. +- Під час активації застосовується фільтрація активної поверхні: нерозв’язані посилання на ввімкнених поверхнях спричиняють помилку запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. --- -## Сховище auth +## Сховище автентифікації ```json5 { @@ -803,13 +805,13 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Профілі для окремих агентів зберігаються в `/auth-profiles.json`. -- `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних. -- Профілі режиму OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілю auth на основі SecretRef. -- Статичні облікові дані середовища виконання надходять із розв’язаних моментальних знімків у пам’яті; застарілі статичні записи `auth.json` очищаються при виявленні. -- Застарілий імпорт OAuth — з `~/.openclaw/credentials/oauth.json`. +- Профілі для кожного агента зберігаються в `/auth-profiles.json`. +- `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для режимів статичних облікових даних. +- Профілі в режимі OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілю автентифікації на основі SecretRef. +- Статичні runtime-облікові дані надходять із розв’язаних знімків у пам’яті; застарілі статичні записи `auth.json` очищаються при виявленні. +- Застарілий імпорт OAuth виконується з `~/.openclaw/credentials/oauth.json`. - Див. [OAuth](/uk/concepts/oauth). -- Поведінка секретів під час виконання та інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). +- Runtime-поведінка секретів та інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). ### `auth.cooldowns` @@ -831,20 +833,21 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `billingBackoffHours`: базовий backoff у годинах, коли профіль завершується помилкою через справжні +- `billingBackoffHours`: базовий backoff у годинах, коли профіль зазнає невдачі через справжні помилки білінгу/недостатнього кредиту (типово: `5`). Явний текст про білінг - усе ще може потрапити сюди навіть у відповідях `401`/`403`, але зіставлення - тексту, специфічного для провайдера, залишається в межах провайдера, якому воно належить (наприклад OpenRouter - `Key limit exceeded`). Повторювані повідомлення HTTP `402` про usage-window або - ліміти витрат організації/робочого простору залишаються в шляху `rate_limit`. -- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин backoff для білінгу за провайдером. + усе ще може потрапляти сюди навіть у відповідях `401`/`403`, але + зіставлювачі тексту, специфічні для провайдера, залишаються прив’язаними до + провайдера, якому вони належать (наприклад, OpenRouter + `Key limit exceeded`). Повідомлення retryable HTTP `402` про usage-window або + spend-limit організації/робочого простору натомість залишаються в шляху `rate_limit`. +- `billingBackoffHoursByProvider`: необов’язкові перевизначення backoff у годинах для окремих провайдерів. - `billingMaxHours`: межа в годинах для експоненційного зростання billing backoff (типово: `24`). -- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для високовпевнених збоїв `auth_permanent` (типово: `10`). +- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для збоїв `auth_permanent` із високою впевненістю (типово: `10`). - `authPermanentMaxMinutes`: межа в хвилинах для зростання backoff `auth_permanent` (типово: `60`). -- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників backoff (типово: `24`). -- `overloadedProfileRotations`: максимальна кількість ротацій auth-профілю в межах того самого провайдера для перевантажених помилок перед переходом на резервну модель (типово: `1`). Сюди потрапляють форми зайнятості провайдера, такі як `ModelNotReadyException`. +- `failureWindowHours`: ковзне вікно в годинах, що використовується для лічильників backoff (типово: `24`). +- `overloadedProfileRotations`: максимальна кількість ротацій auth-профілю в межах того самого провайдера для помилок перевантаження перед переходом до резервної моделі (типово: `1`). Сюди потрапляють форми зайнятості провайдера, такі як `ModelNotReadyException`. - `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`). -- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-профілю в межах того самого провайдера для помилок rate-limit перед переходом на резервну модель (типово: `1`). Цей кошик rate-limit включає текстові форми провайдерів на кшталт `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. +- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-профілю в межах того самого провайдера для помилок rate limit перед переходом до резервної моделі (типово: `1`). Цей bucket rate limit включає текстові форми провайдера на кшталт `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. --- @@ -864,10 +867,10 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. -- Задайте `logging.file` для стабільного шляху. -- `consoleLevel` підвищується до `debug`, коли використовується `--verbose`. -- `maxFileBytes`: максимальний розмір активного файла журналу в байтах перед ротацією (додатне ціле число; типово: `104857600` = 100 MB). OpenClaw зберігає до п’яти нумерованих архівів поруч з активним файлом. -- `redactSensitive` / `redactPatterns`: маскування best-effort для виводу в консоль, файлів журналу, записів журналу OTLP і збереженого тексту транскрипту сесії. +- Установіть `logging.file` для стабільного шляху. +- `consoleLevel` підвищується до `debug` за `--verbose`. +- `maxFileBytes`: максимальний розмір активного файлу журналу в байтах перед ротацією (додатне ціле число; типово: `104857600` = 100 MB). OpenClaw зберігає до п’яти нумерованих архівів поруч з активним файлом. +- `redactSensitive` / `redactPatterns`: маскування за принципом best-effort для виводу в консоль, файлів журналів, записів журналів OTLP і збереженого тексту транскрипту сесії. --- @@ -916,24 +919,24 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - `enabled`: головний перемикач для виводу інструментування (типово: `true`). -- `flags`: масив рядків прапорців, що вмикають цільовий вивід журналів (підтримує шаблони з підстановками, як-от `"telegram.*"` або `"*"`). -- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислі сесії, поки сесія залишається у стані обробки. +- `flags`: масив рядків-прапорців, що вмикають цільовий вивід журналу (підтримує шаблони з wildcard, як-от `"telegram.*"` або `"*"`). +- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про застряглу сесію, поки сесія залишається в стані обробки. - `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). Повну конфігурацію, каталог сигналів і модель приватності див. у [OpenTelemetry export](/uk/gateway/opentelemetry). - `otel.endpoint`: URL колектора для експорту OTel. -- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: необов’язкові OTLP-кінцеві точки для окремих сигналів. Якщо задано, вони перевизначають `otel.endpoint` лише для відповідного сигналу. +- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: необов’язкові OTLP endpoint для конкретних сигналів. Якщо задано, вони перевизначають `otel.endpoint` лише для відповідного сигналу. - `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`. - `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються із запитами експорту OTel. -- `otel.serviceName`: назва служби для атрибутів ресурсу. -- `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт трасувань, метрик або журналів. -- `otel.sampleRate`: частота вибірки трасувань `0`–`1`. +- `otel.serviceName`: ім’я сервісу для атрибутів ресурсу. +- `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт trace, metrics або logs. +- `otel.sampleRate`: частота семплювання trace `0`–`1`. - `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в мс. -- `otel.captureContent`: явний дозвіл на захоплення сирого вмісту для атрибутів span OTEL. Типово вимкнено. Логічне значення `true` захоплює вміст повідомлень/інструментів, окрім system; форма об’єкта дозволяє явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`. -- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: перемикач середовища для найновіших експериментальних атрибутів провайдера span GenAI. Типово spans зберігають застарілий атрибут `gen_ai.system` для сумісності; метрики GenAI використовують обмежені семантичні атрибути. -- `OPENCLAW_OTEL_PRELOADED=1`: перемикач середовища для хостів, які вже зареєстрували глобальний SDK OpenTelemetry. У такому разі OpenClaw пропускає запуск/завершення SDK, що належить плагіну, зберігаючи активними діагностичні слухачі. -- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` і `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: змінні середовища для окремих сигналів, які використовуються, коли відповідний ключ конфігурації не задано. +- `otel.captureContent`: opt-in захоплення сирого вмісту для атрибутів span OTEL. Типово вимкнено. Булеве значення `true` захоплює вміст повідомлень/інструментів, крім системного; форма об’єкта дає змогу явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`. +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: перемикач середовища для найновіших експериментальних атрибутів провайдера span GenAI. Типово span зберігають застарілий атрибут `gen_ai.system` для сумісності; метрики GenAI використовують обмежені семантичні атрибути. +- `OPENCLAW_OTEL_PRELOADED=1`: перемикач середовища для хостів, які вже зареєстрували глобальний SDK OpenTelemetry. Тоді OpenClaw пропускає запуск/завершення SDK, що належить Plugin, зберігаючи активними слухачі діагностики. +- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` і `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: змінні середовища endpoint для конкретних сигналів, які використовуються, коли відповідний ключ конфігурації не задано. - `cacheTrace.enabled`: журналювати знімки трасування кешу для вбудованих запусків (типово: `false`). - `cacheTrace.filePath`: шлях виводу для JSONL трасування кешу (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід трасування кешу (усі типово: `true`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід трасування кешу (усе типово: `true`). --- @@ -955,12 +958,12 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `channel`: канал випуску для інсталяцій npm/git — `"stable"`, `"beta"` або `"dev"`. +- `channel`: канал релізів для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`. - `checkOnStart`: перевіряти оновлення npm під час запуску gateway (типово: `true`). -- `auto.enabled`: увімкнути фонове автооновлення для пакетних інсталяцій (типово: `false`). -- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням stable-каналу (типово: `6`; максимум: `168`). -- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable-каналу в годинах (типово: `12`; максимум: `168`). -- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу, у годинах (типово: `1`; максимум: `24`). +- `auto.enabled`: увімкнути фонове автооновлення для встановлень пакетів (типово: `false`). +- `auto.stableDelayHours`: мінімальна затримка в годинах перед авто застосуванням stable-каналу (типово: `6`; макс.: `168`). +- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable-каналу в годинах (типово: `12`; макс.: `168`). +- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу в годинах (типово: `1`; макс.: `24`). --- @@ -993,23 +996,23 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `enabled`: глобальний перемикач функції ACP (типово: `true`; установіть `false`, щоб приховати можливості dispatch і spawn ACP). -- `dispatch.enabled`: незалежний перемикач для dispatch ходів сесій ACP (типово: `true`). Установіть `false`, щоб зберегти доступність команд ACP, але заблокувати виконання. -- `backend`: ідентифікатор типового backend середовища виконання ACP (має відповідати зареєстрованому плагіну середовища виконання ACP). - Якщо задано `plugins.allow`, включіть ідентифікатор backend-плагіна (наприклад `acpx`), інакше комплектний типовий плагін не завантажиться. -- `defaultAgent`: резервний ідентифікатор цільового агента ACP, коли spawns не задають явну ціль. -- `allowedAgents`: список дозволу ідентифікаторів агентів, дозволених для сесій середовища виконання ACP; порожній означає відсутність додаткових обмежень. +- `enabled`: глобальний feature gate ACP (типово: `true`; установіть `false`, щоб приховати можливості dispatch і spawn ACP). +- `dispatch.enabled`: незалежний перемикач для dispatch ходів сесії ACP (типово: `true`). Установіть `false`, щоб залишити команди ACP доступними, але заблокувати виконання. +- `backend`: ідентифікатор типового backend runtime ACP (має відповідати зареєстрованому runtime Plugin ACP). + Якщо задано `plugins.allow`, включіть id backend Plugin (наприклад `acpx`), інакше bundled Plugin за замовчуванням не завантажиться. +- `defaultAgent`: резервний id цільового агента ACP, коли spawn не задає явну ціль. +- `allowedAgents`: allowlist id агентів, дозволених для runtime-сесій ACP; порожнє значення означає відсутність додаткового обмеження. - `maxConcurrentSessions`: максимальна кількість одночасно активних сесій ACP. - `stream.coalesceIdleMs`: вікно idle flush у мс для потокового тексту. -- `stream.maxChunkChars`: максимальний розмір фрагмента перед розбиттям проєкції потокового блока. -- `stream.repeatSuppression`: придушувати повторювані рядки status/tool на хід (типово: `true`). +- `stream.maxChunkChars`: максимальний розмір чанка перед розбиттям проєкції потокового блоку. +- `stream.repeatSuppression`: придушувати повторні рядки status/tool на кожен хід (типово: `true`). - `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до термінальних подій ходу. - `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (типово: `"paragraph"`). -- `stream.maxOutputChars`: максимальна кількість символів виводу помічника, що проєктується за один хід ACP. -- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлень ACP. -- `stream.tagVisibility`: запис назв тегів у логічні перевизначення видимості для потокових подій. -- `runtime.ttlMinutes`: idle TTL у хвилинах для воркерів сесій ACP до можливого очищення. -- `runtime.installCommand`: необов’язкова команда інсталяції, яку слід виконати під час bootstrap середовища виконання ACP. +- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, проєктованих на хід ACP. +- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків status/update ACP. +- `stream.tagVisibility`: запис імен тегів у булеві перевизначення видимості для потокових подій. +- `runtime.ttlMinutes`: idle TTL у хвилинах для worker сесій ACP до моменту, коли можливе очищення. +- `runtime.installCommand`: необов’язкова команда встановлення для запуску під час bootstrap середовища runtime ACP. --- @@ -1025,11 +1028,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `cli.banner.taglineMode` керує стилем tagline банера: - - `"random"` (типово): ротаційні кумедні/сезонні tagline. - - `"default"`: фіксований нейтральний tagline (`All your chats, one OpenClaw.`). - - `"off"`: без тексту tagline (заголовок/версія банера все одно показуються). -- Щоб приховати весь банер (а не лише tagline), задайте env `OPENCLAW_HIDE_BANNER=1`. +- `cli.banner.taglineMode` керує стилем слогана банера: + - `"random"` (типово): ротаційні кумедні/сезонні слогани. + - `"default"`: фіксований нейтральний слоган (`Усі ваші чати, один OpenClaw.`). + - `"off"`: без тексту слогана (назва/версія банера все одно показується). +- Щоб приховати весь банер (а не лише слогани), установіть змінну середовища `OPENCLAW_HIDE_BANNER=1`. --- @@ -1057,9 +1060,9 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. --- -## Bridge (застаріле, вилучено) +## Bridge (застарілий, видалений) -Поточні збірки більше не містять TCP bridge. Nodes підключаються через Gateway WebSocket. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не вилучено; `openclaw doctor --fix` може прибрати невідомі ключі). +Поточні збірки більше не містять TCP bridge. Nodes підключаються через Gateway WebSocket. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). @@ -1099,11 +1102,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `sessionRetention`: як довго зберігати завершені сесії ізольованих запусків cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів cron. Типове значення: `24h`; установіть `false`, щоб вимкнути. -- `runLog.maxBytes`: максимальний розмір файла журналу одного запуску (`cron/runs/.jsonl`) перед очищенням. Типове значення: `2_000_000` байтів. -- `runLog.keepLines`: кількість найновіших рядків, які зберігаються під час очищення журналу запуску. Типове значення: `2000`. -- `webhookToken`: bearer-токен, що використовується для доставки POST до cron Webhook (`delivery.mode = "webhook"`); якщо пропущено, заголовок auth не надсилається. -- `webhook`: застарілий резервний URL Webhook (http/https), який використовується лише для збережених завдань, у яких усе ще є `notify: true`. +- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів cron. Типово: `24h`; установіть `false`, щоб вимкнути. +- `runLog.maxBytes`: максимальний розмір на файл журналу запуску (`cron/runs/.jsonl`) перед очищенням. Типово: `2_000_000` байтів. +- `runLog.keepLines`: кількість найновіших рядків, що зберігаються, коли спрацьовує очищення журналу запуску. Типово: `2000`. +- `webhookToken`: bearer token, який використовується для POST-доставки Webhook cron (`delivery.mode = "webhook"`); якщо не задано, заголовок автентифікації не надсилається. +- `webhook`: застарілий резервний URL Webhook (http/https), який використовується лише для збережених завдань, що все ще мають `notify: true`. ### `cron.retry` @@ -1119,11 +1122,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань при тимчасових помилках (типово: `3`; діапазон: `0`–`10`). +- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань у разі тимчасових помилок (типово: `3`; діапазон: `0`–`10`). - `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів). -- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати всі тимчасові типи. +- `retryOn`: типи помилок, що запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Не вказуйте, щоб повторювати всі тимчасові типи. -Застосовується лише до одноразових cron-завдань. Періодичні завдання використовують окрему обробку помилок. +Застосовується лише до одноразових завдань cron. Для повторюваних завдань використовується окрема обробка збоїв. ### `cron.failureAlert` @@ -1142,12 +1145,12 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `enabled`: увімкнути сповіщення про збої для cron-завдань (типово: `false`). -- `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мінімум: `1`). -- `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число). -- `includeSkipped`: враховувати послідовні пропущені запуски в поріг сповіщення (типово: `false`). Пропущені запуски відстежуються окремо й не впливають на backoff помилок виконання. -- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` надсилає POST на налаштований Webhook. -- `accountId`: необов’язковий ідентифікатор облікового запису або каналу для обмеження доставки сповіщень. +- `enabled`: увімкнути сповіщення про збої для завдань cron (типово: `false`). +- `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мін.: `1`). +- `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для одного завдання (невід’ємне ціле число). +- `includeSkipped`: зараховувати послідовні пропущені запуски до порога сповіщення (типово: `false`). Пропущені запуски відстежуються окремо й не впливають на backoff помилок виконання. +- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` виконує POST до налаштованого Webhook. +- `accountId`: необов’язковий id акаунта або каналу для обмеження доставки сповіщень. ### `cron.failureDestination` @@ -1164,13 +1167,13 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Типове місце призначення для сповіщень про збої cron для всіх завдань. -- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо даних цілі. +- Типова ціль для сповіщень про збої cron для всіх завдань. +- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо цільових даних. - `channel`: перевизначення каналу для доставки announce. `"last"` повторно використовує останній відомий канал доставки. -- `to`: явна ціль announce або URL Webhook. Обов’язкове для режиму webhook. -- `accountId`: необов’язкове перевизначення облікового запису для доставки. -- `delivery.failureDestination` на рівні завдання перевизначає це глобальне типове значення. -- Якщо не задано ні глобальне, ні конкретне для завдання місце призначення збою, завдання, які вже доставляють через `announce`, у разі збою повертаються до цієї основної цілі announce. +- `to`: явна ціль announce або URL Webhook. Обов’язково для режиму webhook. +- `accountId`: необов’язкове перевизначення акаунта для доставки. +- `delivery.failureDestination` для конкретного завдання перевизначає це глобальне типове значення. +- Коли не задано ні глобальну, ні для конкретного завдання ціль збоїв, завдання, які вже доставляють через `announce`, у разі збою повертаються до цієї основної announce-цілі. - `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` завдання не дорівнює `"webhook"`. Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [background tasks](/uk/automation/tasks). @@ -1179,34 +1182,34 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ## Змінні шаблону моделі медіа -Заповнювачі шаблону, що розгортаються в `tools.media.models[].args`: +Заповнювачі шаблонів, що розгортаються в `tools.media.models[].args`: -| Змінна | Опис | -| ----------------- | ------------------------------------------------- | -| `{{Body}}` | Повне тіло вхідного повідомлення | -| `{{RawBody}}` | Сире тіло (без обгорток історії/відправника) | -| `{{BodyStripped}}`| Тіло без згадок групи | -| `{{From}}` | Ідентифікатор відправника | -| `{{To}}` | Ідентифікатор призначення | -| `{{MessageSid}}` | Ідентифікатор повідомлення каналу | -| `{{SessionId}}` | UUID поточної сесії | -| `{{IsNewSession}}`| `"true"`, коли створено нову сесію | -| `{{MediaUrl}}` | Псевдо-URL вхідного медіа | -| `{{MediaPath}}` | Локальний шлях до медіа | -| `{{MediaType}}` | Тип медіа (image/audio/document/…) | -| `{{Transcript}}` | Транскрипт аудіо | -| `{{Prompt}}` | Розв’язаний prompt медіа для записів CLI | -| `{{MaxChars}}` | Розв’язана максимальна кількість символів виводу для записів CLI | -| `{{ChatType}}` | `"direct"` або `"group"` | -| `{{GroupSubject}}`| Тема групи (best effort) | -| `{{GroupMembers}}`| Попередній перегляд учасників групи (best effort) | -| `{{SenderName}}` | Відображуване ім’я відправника (best effort) | -| `{{SenderE164}}` | Номер телефону відправника (best effort) | -| `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) | +| Змінна | Опис | +| ------------------ | --------------------------------------------------- | +| `{{Body}}` | Повний текст вхідного повідомлення | +| `{{RawBody}}` | Сирий текст (без обгорток історії/відправника) | +| `{{BodyStripped}}` | Текст без згадувань у групі | +| `{{From}}` | Ідентифікатор відправника | +| `{{To}}` | Ідентифікатор призначення | +| `{{MessageSid}}` | Ідентифікатор повідомлення каналу | +| `{{SessionId}}` | UUID поточної сесії | +| `{{IsNewSession}}` | `"true"`, коли створено нову сесію | +| `{{MediaUrl}}` | Псевдо-URL вхідного медіа | +| `{{MediaPath}}` | Локальний шлях до медіа | +| `{{MediaType}}` | Тип медіа (image/audio/document/…) | +| `{{Transcript}}` | Транскрипт аудіо | +| `{{Prompt}}` | Розв’язаний медіа-prompt для записів CLI | +| `{{MaxChars}}` | Розв’язаний максимум символів виводу для записів CLI | +| `{{ChatType}}` | `"direct"` або `"group"` | +| `{{GroupSubject}}` | Тема групи (best effort) | +| `{{GroupMembers}}` | Попередній список учасників групи (best effort) | +| `{{SenderName}}` | Відображуване ім’я відправника (best effort) | +| `{{SenderE164}}` | Номер телефону відправника (best effort) | +| `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) | --- -## Включення конфігурації (`$include`) +## Include конфігурації (`$include`) Розділяйте конфігурацію на кілька файлів: @@ -1224,13 +1227,13 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. **Поведінка злиття:** - Один файл: замінює об’єкт-контейнер. -- Масив файлів: глибоко зливається за порядком (пізніші перевизначають попередні). -- Сусідні ключі: зливаються після включень (перевизначають включені значення). -- Вкладені включення: до 10 рівнів углиб. -- Шляхи: розв’язуються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли після розв’язання вони все одно залишаються в межах цієї межі. -- Записи під керуванням OpenClaw, які змінюють лише один розділ верхнього рівня, підтриманий включенням одного файла, записуються безпосередньо в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` недоторканим. -- Кореневі включення, масиви включень і включення з сусідніми перевизначеннями доступні лише для читання для записів під керуванням OpenClaw; такі записи завершуються із закритою відмовою замість сплощення конфігурації. -- Помилки: зрозумілі повідомлення для відсутніх файлів, помилок розбору та циклічних включень. +- Масив файлів: deep merge у вказаному порядку (пізніші перевизначають раніші). +- Сусідні ключі: зливаються після include (перевизначають включені значення). +- Вкладені include: до 10 рівнів глибини. +- Шляхи: розв’язуються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли після розв’язання вони все одно залишаються в межах цього обмеження. +- Записи, керовані OpenClaw, які змінюють лише один верхньорівневий розділ, підкріплений include одного файла, записуються безпосередньо в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін. +- Кореневі include, масиви include та include із сусідніми перевизначеннями є read-only для записів, керованих OpenClaw; такі записи завершуються fail-closed замість сплющення конфігурації. +- Помилки: чіткі повідомлення про відсутні файли, помилки розбору та циклічні include. --- diff --git a/docs/uk/gateway/doctor.md b/docs/uk/gateway/doctor.md index 5e0045cbb..3911b829f 100644 --- a/docs/uk/gateway/doctor.md +++ b/docs/uk/gateway/doctor.md @@ -1,28 +1,28 @@ --- read_when: - - Додавання або змінення міграцій Doctor + - Додавання або змінення міграцій doctor - Запровадження несумісних змін конфігурації sidebarTitle: Doctor -summary: 'Команда Doctor: перевірки стану, міграції конфігурації та кроки відновлення' +summary: 'Команда doctor: перевірки стану, міграції конфігурації та кроки відновлення' title: Doctor x-i18n: - generated_at: "2026-04-27T14:18:20Z" + generated_at: "2026-04-27T22:22:40Z" model: gpt-5.4 provider: openai - source_hash: 1f3a009131c28a0574ce2bb055beecbb321e1664d1ab5b611c64c3f548cda1c6 + source_hash: 5af15cf2f9616286d601518872b736c9e07d5aabb4943c483bd35aa9e3bdc77a source_path: gateway/doctor.md workflow: 15 --- -`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілу конфігурацію/стан, перевіряє стан системи та надає практичні кроки для відновлення. +`openclaw doctor` — це інструмент відновлення + міграції для OpenClaw. Він виправляє застарілу конфігурацію/стан, перевіряє стан системи та надає практичні кроки для відновлення. -## Швидкий старт +## Швидкий початок ```bash openclaw doctor ``` -### Режими без взаємодії та автоматизації +### Безголовий режим і режими автоматизації @@ -30,7 +30,7 @@ openclaw doctor openclaw doctor --yes ``` - Прийняти типові значення без запитів (зокрема кроки відновлення перезапуску/служби/sandbox, коли це застосовно). + Прийняти значення за замовчуванням без запитів (зокрема кроки відновлення для перезапуску/служб/пісочниці, якщо застосовно). @@ -46,7 +46,7 @@ openclaw doctor openclaw doctor --repair --force ``` - Також застосувати агресивні виправлення (перезаписує власні конфігурації supervisor). + Також застосувати агресивні виправлення (перезаписує користувацькі конфігурації supervisor). @@ -54,7 +54,7 @@ openclaw doctor openclaw doctor --non-interactive ``` - Запустити без запитів і застосувати лише безпечні міграції (нормалізація конфігурації + перенесення стану на диску). Пропускає дії з перезапуском/службами/sandbox, які потребують підтвердження людини. Міграції застарілого стану запускаються автоматично, якщо їх виявлено. + Запуск без запитів і застосування лише безпечних міграцій (нормалізація конфігурації + переміщення стану на диску). Пропускає дії перезапуску/служб/пісочниці, які потребують підтвердження людиною. Міграції застарілого стану автоматично виконуються, якщо їх виявлено. @@ -62,7 +62,7 @@ openclaw doctor openclaw doctor --deep ``` - Сканувати системні служби на наявність додаткових встановлень Gateway (launchd/systemd/schtasks). + Просканувати системні служби на наявність додаткових встановлень Gateway (launchd/systemd/schtasks). @@ -79,101 +79,101 @@ cat ~/.openclaw/openclaw.json - Необов’язкове попереднє оновлення для git-встановлень (лише в інтерактивному режимі). - Перевірка актуальності протоколу UI (перебудовує Control UI, якщо схема протоколу новіша). - - Перевірка стану системи + запит на перезапуск. - - Зведення стану Skills (доступні/відсутні/заблоковані) та стану Plugin. + - Перевірка стану + запит на перезапуск. + - Підсумок стану Skills (доступні/відсутні/заблоковані) і стану plugin. - Нормалізація конфігурації для застарілих значень. - - Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.`. - - Перевірки міграції browser для застарілих конфігурацій розширення Chrome і готовності Chrome MCP. + - Міграція конфігурації 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. - - Міграція застарілого стану на диску (сесії/каталог агента/автентифікація WhatsApp). - - Міграція ключів контракту маніфеста застарілого Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). - - Міграція сховища застарілого Cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, `provider` у payload, прості fallback-завдання Webhook із `notify: true`). - - Міграція застарілої runtime-policy агента до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`. + - Попередження про перекриття Codex OAuth (`models.providers.openai-codex`). + - Перевірка TLS-передумов OAuth для профілів OpenAI Codex OAuth. + - Міграція застарілого стану на диску (sessions/каталог agent/автентифікація WhatsApp). + - Міграція ключів контрактів маніфесту застарілого plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). + - Міграція сховища застарілого Cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, `provider` у payload, прості резервні Webhook-завдання `notify: true`). + - Міграція застарілої політики виконання agent до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`. - Перевірка файлів блокування сесій і очищення застарілих блокувань. - - Відновлення транскриптів сесій для дубльованих гілок prompt-rewrite, створених у вразливих збірках 2026.4.24. - - Перевірки цілісності стану та прав доступу (сесії, транскрипти, каталог стану). - - Перевірки прав доступу до файлу конфігурації (`chmod 600`) під час локального запуску. - - Стан автентифікації моделей: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє про стани cooldown/disabled профілю автентифікації. + - Відновлення транскриптів сесій для дубльованих гілок переписування промптів, створених у вразливих збірках 2026.4.24. + - Перевірки цілісності стану та дозволів (sessions, transcripts, каталог стану). + - Перевірки дозволів файла конфігурації (chmod 600) під час локального запуску. + - Стан автентифікації моделей: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє про стани cooldown/disabled для auth-profile. - Виявлення додаткового каталогу робочого простору (`~/openclaw`). - - Відновлення образу sandbox, коли sandboxing увімкнено. + - Відновлення образу пісочниці, коли пісочниця ввімкнена. - Міграція застарілих служб і виявлення додаткових Gateway. - Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`). - - Перевірки runtime Gateway (службу встановлено, але не запущено; кешована мітка launchd). - - Попередження про стан каналу (перевіряються з запущеного Gateway). - - Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим виправленням. - - Очищення змінних середовища вбудованого proxy для служб Gateway, які підхопили значення оболонки `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час встановлення або оновлення. - - Перевірки рекомендованих практик runtime Gateway (Node проти Bun, шляхи менеджера версій). - - Діагностика конфліктів портів Gateway (типово `18789`). + - Перевірки середовища виконання Gateway (службу встановлено, але не запущено; кешована мітка launchd). + - Попередження про стан каналів (перевіряються через запущений Gateway). + - Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим відновленням. + - Очищення змінних середовища вбудованого проксі для служб Gateway, які підхопили значення оболонки `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час встановлення або оновлення. + - Перевірки найкращих практик середовища виконання Gateway (Node проти Bun, шляхи менеджера версій). + - Діагностика конфліктів порту Gateway (типово `18789`). - Попередження безпеки для відкритих політик DM. - - Перевірки автентифікації Gateway для локального режиму токена (пропонує згенерувати токен, якщо джерело токена відсутнє; не перезаписує конфігурації token SecretRef). - - Виявлення проблем зі сполученням пристроїв (очікувані перші запити на сполучення, очікувані оновлення ролі/обсягу доступу, застарілий дрейф локального кешу токенів пристрою та дрейф автентифікації запису сполучення). + - Перевірки автентифікації Gateway для режиму локального токена (пропонує згенерувати токен, якщо джерело токена відсутнє; не перезаписує конфігурації token SecretRef). + - Виявлення проблем зі сполученням пристроїв (очікувані запити на перше сполучення, очікувані оновлення ролей/областей дії, застарілий дрейф локального кешу токенів пристрою та дрейф автентифікації запису сполучення). - Перевірка systemd linger у Linux. - - Перевірка розміру bootstrap-файлу робочого простору (попередження про обрізання/наближення до ліміту для контекстних файлів). - - Перевірка стану completion оболонки та автоматичне встановлення/оновлення. - - Перевірка готовності провайдера вбудовувань для пошуку в пам’яті (локальна модель, ключ віддаленого API або двійковий файл QMD). - - Перевірки source-встановлення (невідповідність робочого простору pnpm, відсутні assets UI, відсутній двійковий файл tsx). - - Записує оновлену конфігурацію та метадані wizard. + - Перевірка розміру файлів bootstrap робочого простору (попередження про обрізання/наближення до ліміту для контекстних файлів). + - Перевірка стану shell completion і автоматичне встановлення/оновлення. + - Перевірка готовності провайдера embedding для пошуку в пам’яті (локальна модель, віддалений API key або двійковий файл QMD). + - Перевірки source-встановлення (невідповідність робочого простору pnpm, відсутні ресурси UI, відсутній двійковий файл tsx). + - Записує оновлену конфігурацію + метадані майстра. ## Зворотне заповнення та скидання Dreams UI -Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для робочого процесу grounded Dreaming. Ці дії використовують RPC-методи у стилі doctor для Gateway, але вони **не** є частиною відновлення/міграції CLI `openclaw doctor`. +Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для робочого процесу grounded dreaming. Ці дії використовують RPC-методи в стилі doctor для Gateway, але вони **не** є частиною відновлення/міграції CLI `openclaw doctor`. Що вони роблять: -- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному робочому просторі, запускає grounded REM diary pass і записує зворотні записи backfill у `DREAMS.md`. -- **Reset** видаляє з `DREAMS.md` лише ті записи щоденника backfill, що мають відповідну позначку. -- **Clear Grounded** видаляє лише staged short-term записи, призначені тільки для grounded, які походять з історичного відтворення і ще не накопичили live recall або щоденної підтримки. +- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному робочому просторі, запускає grounded REM diary pass і записує оборотні записи зворотного заповнення в `DREAMS.md`. +- **Reset** видаляє з `DREAMS.md` лише ті позначені записи щоденника зворотного заповнення. +- **Clear Grounded** видаляє лише staged grounded-only short-term entries, які надійшли з історичного відтворення і ще не накопичили live recall або daily support. Чого вони самі по собі **не** роблять: - вони не редагують `MEMORY.md` - вони не запускають повні міграції doctor -- вони не переносять автоматично grounded candidates у live short-term promotion store, якщо ви явно не запустите спочатку staged CLI path +- вони не переводять автоматично grounded candidates до live short-term promotion store, якщо ви явно не запустите спочатку staged CLI path -Якщо ви хочете, щоб grounded historical replay впливало на звичайний deep promotion lane, натомість використовуйте потік CLI: +Якщо ви хочете, щоб grounded historical replay вплинув на звичайний deep promotion lane, натомість використовуйте CLI-процес: ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -Це переносить grounded durable candidates у short-term dreaming store, залишаючи `DREAMS.md` як поверхню для перегляду. +Це переводить grounded durable candidates до short-term dreaming store, зберігаючи `DREAMS.md` як поверхню для перегляду. ## Детальна поведінка та обґрунтування - Якщо це git checkout і doctor запущено в інтерактивному режимі, він пропонує оновити систему (fetch/rebase/build) перед запуском doctor. + Якщо це git checkout і doctor запущено в інтерактивному режимі, він пропонує оновитися (fetch/rebase/build) перед запуском doctor. Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без перевизначення для конкретного каналу), doctor нормалізує їх до поточної схеми. - Це також охоплює застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у мапу провайдерів. + Це також включає застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у карту провайдера. - Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися і просять виконати `openclaw doctor`. + Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися і просять вас виконати `openclaw doctor`. - Doctor виконає таке: + Doctor: - Пояснить, які застарілі ключі було знайдено. - - Покажe міграцію, яку він застосував. + - Покажe міграцію, яку було застосовано. - Перезапише `~/.openclaw/openclaw.json` з оновленою схемою. - Gateway також автоматично запускає міграції doctor під час старту, коли виявляє застарілий формат конфігурації, тож застарілі конфігурації виправляються без ручного втручання. Міграції сховища завдань Cron обробляються командою `openclaw doctor --fix`. + Gateway також автоматично запускає міграції doctor під час старту, коли виявляє застарілий формат конфігурації, тож застарілі конфігурації виправляються без ручного втручання. Міграції сховища Cron обробляються командою `openclaw doctor --fix`. Поточні міграції: @@ -182,7 +182,7 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit` - `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns` - `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` @@ -198,87 +198,87 @@ 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 може зберегти наявну відповідну ціль named/default) - `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` для тайм-аутів повільних провайдерів/моделей + - видалити `agents.defaults.llm`; для тайм-аутів повільних провайдерів/моделей використовуйте `models.providers..timeoutSeconds` - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` - - видалити `browser.relayBindHost` (застаріле налаштування relay для розширення) - - застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (під час старту Gateway також пропускає провайдерів, чий `api` має майбутнє або невідоме enum-значення, замість того щоб аварійно завершувати роботу) + - видалити `browser.relayBindHost` (застарілий параметр relay розширення) + - застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (під час старту Gateway також пропускає провайдерів, у яких `api` встановлено на майбутнє або невідоме значення enum, замість повної відмови) - Попередження doctor також містять рекомендації щодо типового облікового запису для багатокористувацьких каналів: + Попередження doctor також містять рекомендації щодо облікового запису за замовчуванням для багатoоблікових каналів: - - Якщо налаштовано два або більше записи в `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що fallback-маршрутизація може вибрати неочікуваний обліковий запис. - - Якщо `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 + вартість для кожної моделі. - - Якщо ваша конфігурація browser досі вказує на вилучений шлях розширення Chrome, doctor нормалізує її до поточної моделі підключення host-local Chrome MCP: + + Якщо конфігурація браузера все ще вказує на вилучений шлях розширення Chrome, doctor нормалізує її до поточної моделі підключення Chrome MCP на локальному хості: - `browser.profiles.*.driver: "extension"` стає `"existing-session"` - `browser.relayBindHost` видаляється - Doctor також перевіряє шлях host-local Chrome MCP, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`: + Doctor також перевіряє шлях Chrome MCP на локальному хості, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`: - - перевіряє, чи встановлено Google Chrome на тому самому хості для типових профілів автопідключення + - перевіряє, чи встановлено Google Chrome на тому самому хості для профілів автоматичного підключення за замовчуванням - перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144 - - нагадує увімкнути remote debugging на сторінці inspect браузера (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`) + - нагадує ввімкнути remote debugging на сторінці інспектування браузера (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`) - Doctor не може увімкнути це налаштування на боці Chrome за вас. Host-local Chrome MCP усе ще вимагає: + Doctor не може ввімкнути цей параметр у Chrome за вас. Chrome MCP на локальному хості все ще вимагає: - - браузер на основі Chromium 144+ на хості gateway/node - - щоб браузер працював локально + - браузер на базі Chromium 144+ на хості gateway/node + - локально запущений браузер - увімкнений remote debugging у цьому браузері - - схвалення першого запиту згоди на attach у браузері + - підтвердження першого запиту на згоду підключення в браузері - Готовність тут стосується лише передумов локального attach. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, усе ще потребують керованого browser або raw CDP profile. + Готовність тут стосується лише передумов для локального підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, усе ще вимагають керованого браузера або профілю raw CDP. - Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших headless-потоків. Вони й надалі використовують raw CDP. + Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших безголових сценаріїв. Вони й надалі використовують raw CDP. - - Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє endpoint авторизації OpenAI, щоб переконатися, що локальний стек TLS Node/OpenSSL може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або self-signed cert), doctor виводить платформо-специфічні вказівки щодо виправлення. На macOS із Node, встановленим через Homebrew, виправленням зазвичай є `brew postinstall ca-certificates`. Із `--deep` перевірка виконується навіть тоді, коли Gateway справний. + + Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє кінцеву точку авторизації OpenAI, щоб упевнитися, що локальний стек TLS Node/OpenSSL може валідувати ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або self-signed cert), doctor виводить інструкції з виправлення для конкретної платформи. На macOS з Homebrew Node виправленням зазвичай є `brew postinstall ca-certificates`. З `--deep` перевірка виконується навіть якщо Gateway у нормальному стані. - Якщо ви раніше додавали застарілі параметри транспорту OpenAI у `models.providers.openai-codex`, вони можуть затіняти вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі параметри транспорту разом із Codex OAuth, щоб ви могли видалити або переписати застаріле перевизначення транспорту й повернути вбудовану поведінку маршрутизації/fallback. Власні proxy та перевизначення лише заголовків усе ще підтримуються і не викликають це попередження. + Якщо ви раніше додали застарілі параметри транспорту OpenAI у `models.providers.openai-codex`, вони можуть перекривати шлях вбудованого провайдера Codex OAuth, який новіші релізи використовують автоматично. Doctor попереджає, коли бачить ці старі параметри транспорту поруч із Codex OAuth, щоб ви могли прибрати або переписати застаріле перевизначення транспорту та повернути вбудовану поведінку маршрутизації/резервного переходу. Користувацькі проксі та перевизначення лише заголовків, як і раніше, підтримуються та не викликають цього попередження. - - Коли вбудований Plugin Codex увімкнено, doctor також перевіряє, чи посилання на основну модель `openai-codex/*` усе ще розв’язуються через типовий раннер PI. Така комбінація допустима, якщо ви хочете автентифікацію Codex OAuth/subscription через PI, але її легко сплутати з власною app-server harness Codex. Doctor попереджає про це й указує на явну форму app-server: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`. + + Коли ввімкнено bundled plugin Codex, doctor також перевіряє, чи первинні посилання на моделі `openai-codex/*` і далі розв’язуються через стандартний PI runner. Така комбінація є коректною, якщо ви хочете використовувати автентифікацію Codex OAuth/subscription через PI, але її легко сплутати з нативним app-server harness Codex. Doctor попереджає про це і вказує на явну форму app-server: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`. - Doctor не виправляє це автоматично, тому що обидва маршрути є дійсними: + Doctor не виправляє це автоматично, оскільки обидва маршрути є коректними: - - `openai-codex/*` + PI означає "використовувати автентифікацію Codex OAuth/subscription через звичайний раннер OpenClaw." - - `openai/*` + `runtime: "codex"` означає "запускати вбудований хід через власний app-server Codex." - - `/codex ...` означає "керувати або прив’язати власну розмову Codex із чату." - - `/acp ...` або `runtime: "acp"` означає "використовувати зовнішній адаптер ACP/acpx." + - `openai-codex/*` + PI означає «використовувати автентифікацію Codex OAuth/subscription через звичайний runner OpenClaw». + - `openai/*` + `runtime: "codex"` означає «запустити вбудований turn через нативний app-server Codex». + - `/codex ...` означає «керувати нативною розмовою Codex з чату або прив’язати її». + - `/acp ...` або `runtime: "acp"` означає «використовувати зовнішній адаптер ACP/acpx». - Якщо з’являється це попередження, виберіть маршрут, який ви мали на увазі, і відредагуйте конфігурацію вручну. Залишайте попередження як є, якщо PI Codex OAuth задумано навмисно. + Якщо з’являється це попередження, виберіть маршрут, який ви мали на увазі, і відредагуйте конфігурацію вручну. Залиште попередження без змін, якщо PI Codex OAuth використовується навмисно. - Doctor може переносити старіші структури на диску до поточної структури: + Doctor може мігрувати старіші структури на диску до поточної: - Сховище сесій + транскрипти: - з `~/.openclaw/sessions/` до `~/.openclaw/agents//sessions/` - - Каталог агента: + - Каталог agent: - з `~/.openclaw/agent/` до `~/.openclaw/agents//agent/` - Стан автентифікації WhatsApp (Baileys): - - із застарілого `~/.openclaw/credentials/*.json` (крім `oauth.json`) + - зі старих `~/.openclaw/credentials/*.json` (крім `oauth.json`) - до `~/.openclaw/credentials/whatsapp//...` (типовий ID облікового запису: `default`) - Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor виводить попередження, якщо залишає будь-які застарілі каталоги як резервні копії. Gateway/CLI також автоматично переносить застарілі сесії + каталог агента під час старту, тож історія/автентифікація/моделі потрапляють у шлях конкретного агента без ручного запуску doctor. Автентифікація WhatsApp навмисно переноситься лише через `openclaw doctor`. Нормалізація Talk provider/provider-map тепер порівнює за структурною рівністю, тож відмінності лише в порядку ключів більше не спричиняють повторні no-op зміни `doctor --fix`. + Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor виведе попередження, якщо залишить якісь застарілі каталоги як резервні копії. Gateway/CLI також автоматично мігрує застарілі сесії + каталог agent під час запуску, тож історія/автентифікація/моделі потрапляють до шляху конкретного agent без ручного запуску doctor. Автентифікація WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація провайдера/карти провайдерів Talk тепер порівнюється за структурною рівністю, тому відмінності лише в порядку ключів більше не спричиняють повторних порожніх змін `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`, якщо його перевизначено) на наявність старих форм завдань, які scheduler досі приймає для сумісності. + Doctor також перевіряє сховище завдань Cron (`~/.openclaw/cron/jobs.json` за замовчуванням або `cron.store`, якщо його перевизначено) на старі форми завдань, які планувальник усе ще приймає для сумісності. Поточні очищення Cron включають: @@ -287,194 +287,197 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - поля payload верхнього рівня (`message`, `model`, `thinking`, ...) → `payload` - поля delivery верхнього рівня (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` - псевдоніми delivery `provider` у payload → явний `delivery.channel` - - прості застарілі fallback-завдання Webhook з `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook` + - прості застарілі резервні Webhook-завдання `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook` - Doctor автоматично переносить завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий fallback notify з наявним режимом delivery, відмінним від Webhook, doctor попереджає про це і залишає таке завдання для ручної перевірки. + Doctor автоматично мігрує завдання `notify: true` лише тоді, коли це можна зробити без зміни поведінки. Якщо завдання поєднує застарілий резервний notify з наявним режимом delivery не через webhook, doctor попереджає й залишає це завдання для ручної перевірки. - Doctor сканує каталог сесій кожного агента на наявність застарілих файлів блокування запису — файлів, що залишилися після аварійного завершення сесії. Для кожного знайденого файлу блокування він повідомляє: шлях, PID, чи PID усе ще активний, вік блокування та чи вважається воно застарілим (мертвий PID або старше 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше виводить примітку та радить запустити команду повторно з `--fix`. + Doctor сканує каталог сесій кожного agent на наявність застарілих write-lock файлів — файлів, що залишилися після аварійного завершення сесії. Для кожного знайденого файла блокування він повідомляє: шлях, PID, чи цей PID ще активний, вік блокування та чи вважається воно застарілим (мертвий PID або старше 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше виводить примітку та пропонує повторно запустити з `--fix`. - Doctor сканує JSONL-файли сесій агента на наявність дубльованої форми гілок, створеної багом переписування prompt transcript у версії 2026.4.24: покинутий хід користувача з внутрішнім runtime context OpenClaw плюс активний сусідній запис із тим самим видимим запитом користувача. У режимі `--fix` / `--repair` doctor створює резервну копію кожного ураженого файлу поруч з оригіналом і переписує транскрипт на активну гілку, щоб історія Gateway та читачі пам’яті більше не бачили дубльованих ходів. + Doctor сканує JSONL-файли сесій agent на наявність дубльованої форми гілок, створеної багом переписування транскриптів промптів у версії 2026.4.24: покинутий user turn із внутрішнім контекстом виконання OpenClaw плюс активний sibling з тим самим видимим user prompt. У режимі `--fix` / `--repair` doctor створює резервну копію кожного ураженого файла поруч з оригіналом і переписує транскрипт до активної гілки, щоб історія gateway і читачі пам’яті більше не бачили дубльованих turn. - Каталог стану — це операційний стовбур системи. Якщо він зникне, ви втратите сесії, облікові дані, журнали та конфігурацію (якщо у вас немає резервних копій в іншому місці). + Каталог стану — це операційний стовбур мозку. Якщо він зникне, ви втратите сесії, облікові дані, журнали та конфігурацію (якщо не маєте резервних копій в іншому місці). Doctor перевіряє: - - **Каталог стану відсутній**: попереджає про катастрофічну втрату стану, пропонує відновити каталог і нагадує, що не може відновити відсутні дані. - - **Права доступу до каталогу стану**: перевіряє можливість запису; пропонує виправити права доступу (і виводить підказку `chown`, якщо виявлено невідповідність власника/групи). - - **Каталог стану macOS, синхронізований із хмарою**: попереджає, коли стан розміщується в iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, оскільки шляхи із синхронізацією можуть спричиняти повільніше I/O та конфлікти блокувань/синхронізації. - - **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розміщується на джерелі монтування `mmcblk*`, оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час запису сесій та облікових даних. + - **Каталог стану відсутній**: попереджає про катастрофічну втрату стану, пропонує створити каталог заново та нагадує, що не може відновити відсутні дані. + - **Дозволи каталогу стану**: перевіряє можливість запису; пропонує виправити дозволи (і виводить підказку `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` вказує в інше місце (історія може розділитися між встановленнями). + - **Нагадування про remote mode**: якщо `gateway.mode=remote`, doctor нагадує запускати його на віддаленому хості (саме там живе стан). + - **Дозволи файла конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групою/усіма, і пропонує посилити їх до `600`. - Doctor перевіряє OAuth-профілі у сховищі автентифікації, попереджає, коли строк дії токенів спливає або вже сплив, і може оновити їх, коли це безпечно. Якщо профіль Anthropic OAuth/token застарів, він пропонує Anthropic API key або шлях setup-token Anthropic. Запити на оновлення з’являються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення. + Doctor перевіряє профілі OAuth у сховищі автентифікації, попереджає, коли токени прострочуються/прострочені, і може оновити їх, коли це безпечно. Якщо профіль Anthropic OAuth/token застарів, він пропонує Anthropic API key або шлях Anthropic setup-token. Запити на оновлення з’являються лише в інтерактивному режимі (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-періоди (обмеження швидкості/тайм-аути/збої автентифікації) - - довші вимкнення (помилки білінгу/кредитів) + - короткі cooldown-и (обмеження швидкості/тайм-аути/помилки автентифікації) + - довші відключення (помилки білінгу/кредитів) - Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на модель за каталогом і allowlist та попереджає, коли воно не розв’язується або заборонене. + Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на модель за каталогом і allowlist та попереджає, якщо воно не розв’язується або не дозволене. - Коли sandboxing увімкнено, doctor перевіряє Docker image і пропонує зібрати його або перемкнутися на застарілі імена, якщо поточний образ відсутній. + Коли sandboxing увімкнено, doctor перевіряє Docker-образи та пропонує зібрати їх або перейти на застарілі назви, якщо поточний образ відсутній. - - Doctor перевіряє runtime-залежності лише для вбудованих Plugin, які активні в поточній конфігурації або ввімкнені типовим значенням у своєму вбудованому маніфесті, наприклад `plugins.entries.discord.enabled: true`, застаріле `channels.discord.enabled: true` або типовий увімкнений вбудований провайдер. Якщо чогось бракує, doctor повідомляє про пакунки й установлює їх у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Зовнішні Plugin, як і раніше, використовують `openclaw plugins install` / `openclaw plugins update`; doctor не встановлює залежності для довільних шляхів Plugin. + + Doctor перевіряє залежності середовища виконання лише для bundled plugin, які активні в поточній конфігурації або ввімкнені типовим значенням їх bundled manifest, наприклад `plugins.entries.discord.enabled: true`, застаріле `channels.discord.enabled: true` або bundled provider, увімкнений за замовчуванням. Якщо чогось бракує, doctor повідомляє про пакунки та встановлює їх у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Зовнішні plugin, як і раніше, використовують `openclaw plugins install` / `openclaw plugins update`; doctor не встановлює залежності для довільних шляхів plugin. - Під час відновлення doctor npm-встановлення runtime-залежностей вбудованих пакетів показують прогрес через spinner у TTY-сеансах і періодичний построковий прогрес у piped/headless-виводі. Gateway і локальний CLI також можуть за потреби відновлювати runtime-залежності активних вбудованих Plugin перед імпортом вбудованого Plugin. Ці встановлення обмежені коренем встановлення runtime Plugin, виконуються з вимкненими scripts, не записують package lock і захищені блокуванням install-root, щоб одночасні запуски CLI або Gateway не змінювали те саме дерево `node_modules` одночасно. + Під час відновлення doctor встановлення npm-залежностей середовища виконання bundled plugin показують прогрес через spinner у TTY-сеансах і періодичний построковий прогрес у конвеєрному/безголовому виводі. Gateway і локальний CLI також можуть за потреби відновлювати активні залежності середовища виконання bundled plugin перед імпортом bundled plugin. Ці встановлення обмежуються коренем встановлення середовища виконання plugin, виконуються з вимкненими скриптами, не записують package lock і захищені блокуванням кореня встановлення, щоб одночасні запуски CLI або Gateway не змінювали те саме дерево `node_modules` одночасно. - - Doctor виявляє застарілі служби gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити службу OpenClaw з використанням поточного порту gateway. Він також може сканувати додаткові служби, схожі на gateway, і виводити підказки з очищення. Іменовані за профілем служби gateway OpenClaw вважаються повноцінними і не позначаються як "додаткові". + + Doctor виявляє застарілі служби gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити службу OpenClaw з поточним портом gateway. Він також може сканувати додаткові служби, схожі на gateway, і виводити підказки з очищення. Іменовані за профілем служби gateway OpenClaw вважаються повноцінними й не позначаються як «додаткові». - У Linux, якщо служба gateway на рівні користувача відсутня, але існує системна служба gateway OpenClaw, doctor не встановлює автоматично другу службу на рівні користувача. Перевірте через `openclaw gateway status --deep` або `openclaw doctor --deep`, потім видаліть дублікат або встановіть `OPENCLAW_SERVICE_REPAIR_POLICY=external`, якщо життєвим циклом gateway керує зовнішній supervisor. + У Linux, якщо користувацька служба gateway відсутня, але існує системна служба gateway OpenClaw, doctor не встановлює автоматично другу користувацьку службу. Перевірте через `openclaw gateway status --deep` або `openclaw doctor --deep`, а потім видаліть дублікат або встановіть `OPENCLAW_SERVICE_REPAIR_POLICY=external`, якщо життєвим циклом gateway керує системний supervisor. - - Коли обліковий запис каналу Matrix має очікувану або застосовну міграцію застарілого стану, doctor (у режимі `--fix` / `--repair`) створює знімок стану до міграції, а потім запускає best-effort кроки міграції: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки записуються в журнал, а запуск триває. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається. + + Якщо обліковий запис каналу Matrix має очікувану або застосовну міграцію застарілого стану, doctor (у режимі `--fix` / `--repair`) створює знімок стану перед міграцією, а потім виконує кроки міграції за принципом best-effort: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки логуються, а запуск триває. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається. - Тепер Doctor перевіряє стан сполучення пристроїв як частину звичайного проходу перевірки стану системи. + Doctor тепер перевіряє стан сполучення пристроїв у межах звичайного проходу перевірки стану. Що він повідомляє: - очікувані запити на перше сполучення - - очікувані підвищення ролі для вже сполучених пристроїв - - очікувані підвищення scope для вже сполучених пристроїв - - виправлення невідповідності public key, коли ID пристрою ще збігається, але ідентичність пристрою більше не збігається зі схваленим записом + - очікувані оновлення ролей для вже сполучених пристроїв + - очікувані оновлення областей дії для вже сполучених пристроїв + - відновлення невідповідності відкритого ключа, коли ID пристрою все ще збігається, але ідентичність пристрою більше не збігається зі схваленим записом - сполучені записи без активного токена для схваленої ролі - - сполучені токени, scope яких вийшли за межі схваленої базової лінії сполучення - - локальні кешовані записи токенів пристрою для поточної машини, які передують ротації токена на боці gateway або містять застарілі метадані scope + - сполучені токени, чиї області дії відхилилися від базового схваленого рівня сполучення + - локальні кешовані записи токенів пристрою для поточної машини, які передують ротації токена на боці gateway або містять застарілі метадані області дії - Doctor не схвалює запити на сполучення автоматично і не виконує автоматичну ротацію токенів пристрою. Натомість він виводить точні наступні кроки: + Doctor не схвалює автоматично запити на сполучення і не виконує автоматично ротацію токенів пристрою. Натомість він виводить точні наступні кроки: - переглянути очікувані запити через `openclaw devices list` - - схвалити конкретний запит через `openclaw devices approve ` + - схвалити точний запит через `openclaw devices approve ` - виконати ротацію нового токена через `openclaw devices rotate --device --role ` - видалити застарілий запис і схвалити його знову через `openclaw devices remove ` - Це закриває поширену проблему "пристрій уже сполучено, але все одно з’являється вимога сполучення": тепер doctor розрізняє перше сполучення, очікувані підвищення ролі/scope та дрейф застарілого токена/ідентичності пристрою. + Це закриває поширену проблему «вже сполучено, але все одно вимагається сполучення»: тепер doctor розрізняє перше сполучення, очікувані оновлення ролі/області дії та дрейф застарілого токена/ідентичності пристрою. Doctor виводить попередження, коли провайдер відкритий для DM без allowlist або коли політику налаштовано небезпечним чином. - Якщо запуск відбувається як користувацька служба systemd, doctor переконується, що lingering увімкнено, щоб gateway залишався активним після виходу з системи. + Якщо запуск виконується як користувацька служба systemd, doctor перевіряє, що lingering увімкнено, щоб gateway залишався активним після виходу з системи. - - Doctor виводить зведення стану робочого простору для типового агента: + + Doctor виводить підсумок стану робочого простору для agent за замовчуванням: - - **Стан Skills**: кількість доступних, тих, де бракує вимог, і Skills, заблокованих allowlist. - - **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору існують поруч із поточним робочим простором. - - **Стан Plugin**: підраховує ввімкнені/вимкнені/помилкові Plugin; перелічує ID Plugin для всіх помилок; повідомляє про можливості bundle Plugin. - - **Попередження сумісності Plugin**: позначає Plugin, які мають проблеми сумісності з поточним runtime. - - **Діагностика Plugin**: показує всі попередження або помилки під час завантаження, які видає реєстр Plugin. + - **Стан Skills**: кількість доступних, таких, яким бракує вимог, і заблокованих allowlist skills. + - **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору існують поряд із поточним робочим простором. + - **Стан plugin**: рахує ввімкнені/вимкнені/plugin з помилками; перелічує ID plugin для всіх помилок; повідомляє про можливості bundle plugin. + - **Попередження про сумісність plugin**: позначає plugin, які мають проблеми сумісності з поточним середовищем виконання. + - **Діагностика plugin**: показує всі попередження або помилки під час завантаження, які видає реєстр plugin. - - Doctor перевіряє, чи наближаються bootstrap-файли робочого простору (наприклад, `AGENTS.md`, `CLAUDE.md` або інші injected context files) до налаштованого ліміту символів або перевищують його. Він повідомляє для кожного файлу кількість сирих і вставлених символів, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість вставлених символів як частку від загального ліміту. Коли файли обрізаються або наближаються до ліміту, doctor виводить поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. + + Doctor перевіряє, чи bootstrap-файли робочого простору (наприклад, `AGENTS.md`, `CLAUDE.md` або інші вбудовані контекстні файли) наближаються до налаштованого ліміту символів або перевищують його. Він повідомляє для кожного файла необроблену й вбудовану кількість символів, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість вбудованих символів як частку від загального бюджету. Коли файли обрізаються або наближаються до ліміту, doctor виводить поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. - - Коли `openclaw doctor --fix` видаляє відсутній Plugin каналу, він також видаляє завислу конфігурацію рівня каналу, яка посилалася на цей Plugin: записи `channels.`, цілі Heartbeat, у яких згадувався канал, і перевизначення `agents.*.models["/*"]`. Це запобігає циклам завантаження Gateway, коли runtime каналу вже немає, але конфігурація все ще наказує gateway прив’язатися до нього. + + Коли `openclaw doctor --fix` видаляє відсутній channel plugin, він також видаляє завислу конфігурацію рівня каналу, яка посилалася на цей plugin: записи `channels.`, цілі heartbeat, що вказували на канал, і перевизначення `agents.*.models["/*"]`. Це запобігає циклам перезапуску Gateway, коли середовище виконання каналу зникло, але конфігурація все ще вимагає від gateway прив’язатися до нього. - - Doctor перевіряє, чи встановлено completion за Tab для поточної оболонки (zsh, bash, fish або PowerShell): + + Doctor перевіряє, чи встановлено tab completion для поточної оболонки (zsh, bash, fish або PowerShell): - - Якщо профіль оболонки використовує повільний шаблон динамічного completion (`source <(openclaw completion ...)`), doctor оновлює його до швидшого варіанта з кешованим файлом. - - Якщо completion налаштовано в профілі, але файл кешу відсутній, doctor автоматично відновлює кеш. + - Якщо профіль оболонки використовує повільну динамічну схему completion (`source <(openclaw completion ...)`), doctor оновлює її до швидшого варіанта з кешованим файлом. + - Якщо completion налаштовано в профілі, але кешований файл відсутній, doctor автоматично регенерує кеш. - Якщо completion взагалі не налаштовано, doctor пропонує встановити його (лише в інтерактивному режимі; пропускається з `--non-interactive`). - Виконайте `openclaw completion --write-state`, щоб вручну перевідтворити кеш. + Виконайте `openclaw completion --write-state`, щоб вручну регенерувати кеш. Doctor перевіряє готовність автентифікації локального токена gateway. - - Якщо в режимі токена потрібен токен і жодного джерела токена немає, doctor пропонує згенерувати його. + - Якщо режим токена потребує токен, а джерела токена немає, doctor пропонує згенерувати його. - Якщо `gateway.auth.token` керується через SecretRef, але недоступний, doctor попереджає і не перезаписує його відкритим текстом. - `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано token SecretRef. - - Деякі потоки виправлення потребують перевірки налаштованих облікових даних без послаблення поведінки runtime fail-fast. + + Деякі сценарії відновлення потребують перевірки налаштованих облікових даних без послаблення поведінки fail-fast під час виконання. - - `openclaw doctor --fix` тепер використовує ту саму модель зведення SecretRef у режимі лише читання, що й команди сімейства status, для цільових виправлень конфігурації. - - Приклад: виправлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані облікові дані бота, якщо вони доступні. - - Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху виконання команди, doctor повідомляє, що облікові дані налаштовано, але вони недоступні, і пропускає авторозв’язання замість збою або хибного повідомлення, що токен відсутній. + - `openclaw doctor --fix` тепер використовує ту саму модель підсумку SecretRef лише для читання, що й команди сімейства status, для цільового відновлення конфігурації. + - Приклад: відновлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані облікові дані бота, якщо вони доступні. + - Якщо токен Telegram-бота налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає авторозв’язання замість аварійного завершення або хибного повідомлення про відсутність токена. - Doctor виконує перевірку стану системи і пропонує перезапустити gateway, якщо він виглядає несправним. + Doctor виконує перевірку стану і пропонує перезапустити gateway, якщо той виглядає несправним. - Doctor перевіряє, чи готовий налаштований провайдер embedding для пошуку в пам’яті для типового агента. Поведінка залежить від налаштованого backend і провайдера: + Doctor перевіряє, чи готовий налаштований провайдер embedding для пошуку в пам’яті для agent за замовчуванням. Поведінка залежить від налаштованого бекенда і провайдера: - - **QMD backend**: перевіряє, чи доступний і чи запускається двійковий файл `qmd`. Якщо ні, виводить вказівки щодо виправлення, зокрема npm-пакунок і варіант ручного шляху до двійкового файла. - - **Явний локальний провайдер**: перевіряє наявність локального файлу моделі або розпізнаного URL віддаленої/завантажуваної моделі. Якщо його немає, пропонує перейти на віддаленого провайдера. - - **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи є API key у середовищі або сховищі автентифікації. Якщо немає, виводить практичні підказки щодо виправлення. - - **Автоматичний провайдер**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого провайдера в порядку автовору. + - **Бекенд QMD**: перевіряє, чи двійковий файл `qmd` доступний і може запускатися. Якщо ні — виводить інструкції з виправлення, зокрема npm-пакет і варіант ручного шляху до двійкового файла. + - **Явний локальний провайдер**: перевіряє наявність локального файла моделі або розпізнаного віддаленого/завантажуваного URL моделі. Якщо його немає, пропонує перейти на віддалений провайдер. + - **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи наявний API key у середовищі або сховищі автентифікації. Якщо його немає, виводить практичні підказки з виправлення. + - **Автоматичний провайдер**: спочатку перевіряє доступність локальної моделі, а потім пробує кожен віддалений провайдер у порядку автоматичного вибору. - Коли доступний кешований результат перевірки gateway (gateway був справний на момент перевірки), doctor звіряє його результат із конфігурацією, видимою CLI, і зазначає будь-які розбіжності. Doctor не запускає нову перевірку embedding за типовим шляхом; використовуйте команду deep status для пам’яті, коли потрібна жива перевірка провайдера. + Коли доступний кешований результат перевірки gateway (на момент перевірки gateway був у нормальному стані), doctor звіряє його результат із конфігурацією, видимою CLI, і зазначає будь-які розбіжності. Doctor не запускає нову перевірку embedding на стандартному шляху; використовуйте команду глибокого статусу пам’яті, якщо хочете живу перевірку провайдера. - Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час runtime. + Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час виконання. - - Якщо gateway справний, doctor виконує перевірку стану каналу і повідомляє про попередження з рекомендованими виправленнями. + + Якщо gateway у нормальному стані, doctor виконує перевірку стану каналів і повідомляє про попередження з рекомендованими виправленнями. - - Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на відсутні або застарілі типові значення (наприклад, залежності systemd від network-online і затримка перезапуску). Коли він знаходить невідповідність, то рекомендує оновлення і може переписати файл служби/завдання відповідно до поточних типових значень. + + Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на наявність відсутніх або застарілих значень за замовчуванням (наприклад, залежностей systemd від network-online і затримки перезапуску). Коли він виявляє невідповідність, то рекомендує оновлення і може переписати файл служби/завдання відповідно до поточних значень за замовчуванням. Примітки: - `openclaw doctor` запитує підтвердження перед переписуванням конфігурації supervisor. - - `openclaw doctor --yes` приймає типові запити на виправлення. + - `openclaw doctor --yes` приймає типові запити на відновлення. - `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів. - - `openclaw doctor --repair --force` перезаписує власні конфігурації supervisor. - - `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу служби gateway. Він усе ще повідомляє про стан служби і запускає виправлення, не пов’язані зі службами, але пропускає встановлення/запуск/перезапуск/bootstrap служби, переписування конфігурації supervisor і очищення застарілих служб, оскільки цим життєвим циклом керує зовнішній supervisor. - - Якщо для автентифікації токеном потрібен токен і `gateway.auth.token` керується через SecretRef, під час встановлення/виправлення служби doctor перевіряє SecretRef, але не зберігає розв’язані значення токена відкритим текстом у метаданих середовища служби supervisor. - - Doctor виявляє керовані `.env`/підтримувані SecretRef значення середовища служби, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудовували inline, і переписує метадані служби так, щоб ці значення завантажувалися з джерела runtime, а не з визначення supervisor. + - `openclaw doctor --repair --force` перезаписує користувацькі конфігурації supervisor. + - `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу служби gateway. Він усе ще повідомляє про стан служби та виконує відновлення, не пов’язані зі службою, але пропускає встановлення/запуск/перезапуск/bootstrap служби, переписування конфігурації supervisor і очищення застарілих служб, оскільки цим життєвим циклом керує зовнішній supervisor. + - Якщо автентифікація токеном вимагає токен, а `gateway.auth.token` керується через SecretRef, встановлення/відновлення служби doctor перевіряє SecretRef, але не зберігає розв’язані значення токенів відкритим текстом у метаданих середовища служби supervisor. + - Doctor виявляє керовані `.env`/підкріплені SecretRef значення середовища служби, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудовували inline, і переписує метадані служби так, щоб ці значення завантажувалися з джерела середовища виконання, а не з визначення supervisor. - Doctor виявляє, коли команда служби все ще фіксує старий `--port` після зміни `gateway.port`, і переписує метадані служби на поточний порт. - - Якщо для автентифікації токеном потрібен токен і налаштований token SecretRef не розв’язується, doctor блокує шлях встановлення/виправлення та надає практичні вказівки. - - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не встановлено, doctor блокує встановлення/виправлення, доки режим не буде задано явно. + - Якщо автентифікація токеном вимагає токен, а налаштований token SecretRef не розв’язано, doctor блокує шлях встановлення/відновлення та виводить практичні інструкції. + - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не встановлено, doctor блокує встановлення/відновлення, доки режим не буде явно задано. - Для користувацьких unit systemd у Linux перевірки дрейфу токена в doctor тепер охоплюють і джерела `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації служби. - - Виправлення служб doctor відмовляються переписувати, зупиняти або перезапускати службу gateway зі старішого двійкового файла OpenClaw, якщо конфігурацію востаннє було записано новішою версією. Див. [Усунення несправностей Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). + - 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 перевіряє середовище виконання служби (PID, останній статус завершення) і попереджає, якщо службу встановлено, але вона фактично не запущена. Він також перевіряє конфлікти на порту gateway (типово `18789`) і повідомляє про ймовірні причини (gateway уже запущений, SSH-тунель). - - Doctor попереджає, коли служба gateway працює на Bun або на шляху Node, керованому менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp і Telegram потребують Node, а шляхи менеджера версій можуть ламатися після оновлень, оскільки служба не завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системне встановлення Node, якщо воно доступне (Homebrew/apt/choco). - - - Doctor зберігає всі зміни конфігурації та проставляє метадані wizard, щоб зафіксувати запуск doctor. - - - Doctor пропонує систему пам’яті робочого простору, якщо вона відсутня, і виводить пораду щодо резервного копіювання, якщо робочий простір ще не перебуває під git. + + Doctor попереджає, коли служба gateway працює на Bun або через шлях Node, керований менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджерів версій можуть ламатися після оновлень, тому що служба не завантажує вашу ініціалізацію оболонки. Doctor пропонує міграцію на системне встановлення Node, якщо воно доступне (Homebrew/apt/choco). - Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace) для повного посібника зі структури робочого простору та резервного копіювання через git (рекомендовано приватний GitHub або GitLab). + Нещодавно встановлені або відновлені служби зберігають явні корені середовища (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) і стабільні каталоги user-bin, але резервні каталоги менеджерів версій, визначені евристично, записуються в PATH служби лише тоді, коли ці каталоги існують на диску. Це узгоджує згенерований PATH supervisor з тим самим аудитом мінімального PATH, який doctor виконує пізніше. + + + + Doctor зберігає всі зміни конфігурації та проставляє метадані майстра, щоб зафіксувати запуск doctor. + + + Doctor пропонує систему пам’яті робочого простору, якщо її немає, і виводить пораду щодо резервного копіювання, якщо робочий простір ще не перебуває під git. + + Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб ознайомитися з повним посібником зі структури робочого простору та резервного копіювання через git (рекомендовано приватний GitHub або GitLab). ## Пов’язане -- [Інструкція для Gateway](/uk/gateway) -- [Усунення несправностей Gateway](/uk/gateway/troubleshooting) +- [Інструкція з експлуатації Gateway](/uk/gateway) +- [Усунення проблем Gateway](/uk/gateway/troubleshooting) diff --git a/docs/uk/gateway/trusted-proxy-auth.md b/docs/uk/gateway/trusted-proxy-auth.md index d8c5c489c..2fd6d5a5e 100644 --- a/docs/uk/gateway/trusted-proxy-auth.md +++ b/docs/uk/gateway/trusted-proxy-auth.md @@ -1,40 +1,40 @@ --- read_when: - - Запуск OpenClaw за проксі з підтримкою ідентифікації + - Запуск OpenClaw за identity-aware проксі - Налаштування Pomerium, Caddy або nginx з OAuth перед OpenClaw - - Виправлення помилок WebSocket 1008 «неавторизовано» у конфігураціях зі зворотним проксі - - Визначення місця налаштування HSTS та інших заголовків HTTP для посилення безпеки + - Усунення помилок WebSocket 1008 «несанкціоновано» у конфігураціях зі зворотним проксі + - Визначення, де встановлювати HSTS та інші заголовки посилення безпеки HTTP sidebarTitle: Trusted proxy auth summary: Делегуйте автентифікацію Gateway довіреному зворотному проксі (Pomerium, Caddy, nginx + OAuth) -title: Автентифікація довіреного проксі +title: Автентифікація через довірений проксі x-i18n: - generated_at: "2026-04-26T08:15:43Z" + generated_at: "2026-04-27T22:22:43Z" model: gpt-5.4 provider: openai - source_hash: 64e0f4dee942aedec548135f0408e7773e7b498f8262af13a4d0eff262cae646 + source_hash: 863a448f84d1bc5bf2a5a07a894bcc1bb7e724826ba9cec3fa135338af8dd3eb source_path: gateway/trusted-proxy-auth.md workflow: 15 --- -**Функція, чутлива до безпеки.** У цьому режимі автентифікація повністю делегується вашому зворотному проксі. Неправильна конфігурація може відкрити ваш Gateway для несанкціонованого доступу. Уважно прочитайте цю сторінку перед увімкненням. +**Функція, чутлива до безпеки.** У цьому режимі автентифікація повністю делегується вашому зворотному проксі. Помилкова конфігурація може відкрити ваш Gateway для несанкціонованого доступу. Уважно прочитайте цю сторінку перед увімкненням. ## Коли використовувати Використовуйте режим автентифікації `trusted-proxy`, коли: -- Ви запускаєте OpenClaw за **проксі з підтримкою ідентифікації** (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth). -- Ваш проксі виконує всю автентифікацію та передає ідентичність користувача через заголовки. -- Ви працюєте в середовищі Kubernetes або контейнерному середовищі, де проксі є єдиним шляхом до Gateway. -- Ви стикаєтеся з помилками WebSocket `1008 unauthorized`, тому що браузери не можуть передавати токени в корисному навантаженні WS. +- Ви запускаєте OpenClaw за **identity-aware проксі** (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth). +- Ваш проксі обробляє всю автентифікацію та передає ідентичність користувача через заголовки. +- Ви перебуваєте в середовищі Kubernetes або контейнерному середовищі, де проксі є єдиним шляхом до Gateway. +- Ви стикаєтеся з помилками WebSocket `1008 unauthorized`, тому що браузери не можуть передавати токени в WS payload. -## Коли НЕ використовувати +## Коли НЕ слід використовувати - Якщо ваш проксі не автентифікує користувачів (лише завершує TLS або є балансувальником навантаження). - Якщо існує будь-який шлях до Gateway в обхід проксі (дірки у фаєрволі, доступ із внутрішньої мережі). -- Якщо ви не впевнені, що ваш проксі правильно видаляє/перезаписує переслані заголовки. -- Якщо вам потрібен лише персональний доступ для одного користувача (розгляньте Tailscale Serve + loopback для простішого налаштування). +- Якщо ви не впевнені, що ваш проксі правильно видаляє/перезаписує forwarded headers. +- Якщо вам потрібен лише персональний доступ для одного користувача (для простішого налаштування розгляньте Tailscale Serve + local loopback). ## Як це працює @@ -46,25 +46,25 @@ x-i18n: Проксі додає заголовок з ідентичністю автентифікованого користувача (наприклад, `x-forwarded-user: nick@example.com`). - OpenClaw перевіряє, що запит надійшов від **довіреної IP-адреси проксі** (налаштованої в `gateway.trustedProxies`). + OpenClaw перевіряє, що запит надійшов із **довіреної IP-адреси проксі** (налаштованої в `gateway.trustedProxies`). OpenClaw витягує ідентичність користувача з налаштованого заголовка. - Якщо все гаразд, запит авторизується. + Якщо все перевірено успішно, запит авторизується. -## Поведінка сполучення Control UI +## Поведінка сполучення з Control UI Коли `gateway.auth.mode = "trusted-proxy"` активний і запит проходить перевірки trusted-proxy, сеанси WebSocket Control UI можуть підключатися без ідентичності сполучення пристрою. Наслідки: -- Сполучення більше не є основним бар’єром для доступу до Control UI в цьому режимі. +- Сполучення більше не є основним бар’єром доступу до Control UI в цьому режимі. - Політика автентифікації вашого зворотного проксі та `allowUsers` стають фактичним контролем доступу. -- Тримайте вхідний доступ до gateway заблокованим лише для IP-адрес довіреного проксі (`gateway.trustedProxies` + фаєрвол). +- Тримайте вхідний доступ до Gateway заблокованим лише для довірених IP-адрес проксі (`gateway.trustedProxies` + фаєрвол). ## Конфігурація @@ -83,10 +83,10 @@ x-i18n: // Заголовок, що містить ідентичність автентифікованого користувача (обов’язково) userHeader: "x-forwarded-user", - // Необов’язково: заголовки, які ОБОВ’ЯЗКОВО мають бути присутні (перевірка проксі) + // Необов’язково: заголовки, які ОБОВ’ЯЗКОВО мають бути присутніми (перевірка проксі) requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"], - // Необов’язково: обмеження до конкретних користувачів (порожньо = дозволити всіх) + // Необов’язково: обмежити конкретними користувачами (порожньо = дозволити всіх) allowUsers: ["nick@example.com", "admin@company.org"], }, }, @@ -95,19 +95,19 @@ x-i18n: ``` -**Важливі правила під час виконання** +**Важливі правила часу виконання** - Автентифікація trusted-proxy відхиляє запити з loopback-джерела (`127.0.0.1`, `::1`, loopback CIDR). -- Зворотні проксі loopback на тому самому хості **не** задовольняють вимоги автентифікації trusted-proxy. -- Для конфігурацій із loopback-проксі на тому самому хості використовуйте натомість автентифікацію за токеном/паролем або маршрутизуйте через не-loopback адресу довіреного проксі, яку OpenClaw може перевірити. -- Розгортання Control UI поза loopback усе одно потребують явного `gateway.controlUi.allowedOrigins`. -- **Докази з пересланих заголовків мають пріоритет над loopback-локальністю.** Якщо запит надходить через loopback, але містить заголовки `X-Forwarded-For` / `X-Forwarded-Host` / `X-Forwarded-Proto`, що вказують на не-локальне джерело, ці докази спростовують твердження про loopback-локальність. Такий запит вважається віддаленим для сполучення, автентифікації trusted-proxy та контролю ідентичності пристрою в Control UI. Це запобігає тому, щоб loopback-проксі на тому самому хості «відмивав» ідентичність із пересланих заголовків у trusted-proxy автентифікацію. +- Зворотні проксі на loopback на тому самому хості **не** відповідають вимогам trusted-proxy auth. +- Для конфігурацій проксі на loopback на тому самому хості натомість використовуйте автентифікацію токеном/паролем або маршрутизуйте через не-loopback адресу довіреного проксі, яку OpenClaw може перевірити. +- Для не-loopback розгортань Control UI усе одно потрібен явний `gateway.controlUi.allowedOrigins`. +- **Докази через forwarded headers мають пріоритет над loopback-локальністю.** Якщо запит надходить через loopback, але містить заголовки `X-Forwarded-For` / `X-Forwarded-Host` / `X-Forwarded-Proto`, що вказують на нелокальне джерело, ці докази скасовують твердження про loopback-локальність. Запит вважається віддаленим для сполучення, trusted-proxy auth і контролю ідентичності пристрою в Control UI. Це запобігає тому, щоб проксі на loopback на тому самому хості «відмивав» ідентичність із forwarded headers у trusted-proxy auth. -### Довідник конфігурації +### Довідник із конфігурації - Масив IP-адрес проксі, яким можна довіряти. Запити з інших IP-адрес відхиляються. + Масив IP-адрес проксі, яким слід довіряти. Запити з інших IP-адрес відхиляються. Має бути `"trusted-proxy"`. @@ -116,10 +116,10 @@ x-i18n: Назва заголовка, що містить ідентичність автентифікованого користувача. - Додаткові заголовки, які мають бути присутні, щоб запит вважався довіреним. + Додаткові заголовки, які мають бути присутніми, щоб запит вважався довіреним. - Список дозволених ідентичностей користувачів. Порожньо означає дозволити всіх автентифікованих користувачів. + Список дозволених ідентичностей користувачів. Порожнє значення означає дозвіл для всіх автентифікованих користувачів. ## Завершення TLS і HSTS @@ -128,7 +128,7 @@ x-i18n: - Коли ваш зворотний проксі обробляє HTTPS для `https://control.example.com`, налаштуйте `Strict-Transport-Security` на проксі для цього домену. + Коли ваш зворотний проксі обробляє HTTPS для `https://control.example.com`, встановіть `Strict-Transport-Security` на проксі для цього домену. - Добре підходить для розгортань, доступних з інтернету. - Зберігає сертифікати та політику посилення безпеки HTTP в одному місці. @@ -142,7 +142,7 @@ x-i18n: - Якщо сам OpenClaw напряму обслуговує HTTPS (без проксі, що завершує TLS), налаштуйте: + Якщо OpenClaw сам безпосередньо обслуговує HTTPS (без проксі, що завершує TLS), установіть: ```json5 { @@ -162,13 +162,13 @@ x-i18n: -### Рекомендації щодо поетапного впровадження +### Рекомендації щодо розгортання - Спочатку використовуйте короткий max age (наприклад, `max-age=300`) під час перевірки трафіку. -- Збільшуйте до довготривалих значень (наприклад, `max-age=31536000`) лише після того, як будете повністю впевнені. +- Переходьте до довгострокових значень (наприклад, `max-age=31536000`) лише після того, як матимете високу впевненість. - Додавайте `includeSubDomains` лише якщо кожен піддомен готовий до HTTPS. - Використовуйте preload лише якщо ви навмисно виконуєте вимоги preload для всього набору ваших доменів. -- Локальна розробка лише на loopback не отримує переваг від HSTS. +- Для суто локальної розробки лише на loopback HSTS не дає переваг. ## Приклади налаштування проксі @@ -208,13 +208,13 @@ x-i18n: - Caddy з Plugin `caddy-security` може автентифікувати користувачів і передавати заголовки ідентичності. + Caddy з плагіном `caddy-security` може автентифікувати користувачів і передавати заголовки ідентичності. ```json5 { gateway: { bind: "lan", - trustedProxies: ["10.0.0.1"], // IP-адреса Caddy/sidecar proxy + trustedProxies: ["10.0.0.1"], // IP-адреса Caddy/sidecar-проксі auth: { mode: "trusted-proxy", trustedProxy: { @@ -293,18 +293,18 @@ x-i18n: ## Змішана конфігурація токенів -OpenClaw відхиляє неоднозначні конфігурації, у яких одночасно активні `gateway.auth.token` (або `OPENCLAW_GATEWAY_TOKEN`) і режим `trusted-proxy`. Змішані конфігурації токенів можуть призвести до того, що loopback-запити мовчки автентифікуватимуться неправильним шляхом автентифікації. +OpenClaw відхиляє неоднозначні конфігурації, у яких одночасно активні і `gateway.auth.token` (або `OPENCLAW_GATEWAY_TOKEN`), і режим `trusted-proxy`. Змішані конфігурації токенів можуть призводити до того, що loopback-запити тихо автентифікуються неправильним шляхом автентифікації. Якщо під час запуску ви бачите помилку `mixed_trusted_proxy_token`: -- Видаліть спільний токен, якщо використовуєте режим trusted-proxy, або -- Змініть `gateway.auth.mode` на `"token"`, якщо ви маєте намір використовувати автентифікацію на основі токена. +- Видаліть спільний токен при використанні режиму trusted-proxy, або +- Перемкніть `gateway.auth.mode` на `"token"`, якщо ви маєте намір використовувати автентифікацію на основі токена. -Loopback trusted-proxy автентифікація також працює за принципом fail closed: виклики з того самого хоста мають передавати налаштовані заголовки ідентичності через довірений проксі, а не автентифікуватися мовчки. +Заголовки ідентичності trusted-proxy для loopback усе одно відмовляють у закритому режимі: виклики з того самого хоста не автентифікуються непомітно як користувачі проксі. Внутрішні виклики OpenClaw, які обходять проксі, натомість можуть автентифікуватися через `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`. Резервний перехід на токен навмисно не підтримується в режимі trusted-proxy. -## Заголовок областей операторів +## Заголовок областей оператора -Автентифікація trusted-proxy — це HTTP-режим, **що несе ідентичність**, тому виклики можуть за бажанням оголошувати області операторів через `x-openclaw-scopes`. +Автентифікація trusted-proxy — це HTTP-режим, **що несе ідентичність**, тому викликачі за бажанням можуть оголошувати області оператора через `x-openclaw-scopes`. Приклади: @@ -315,43 +315,44 @@ Loopback trusted-proxy автентифікація також працює за Поведінка: - Коли заголовок присутній, OpenClaw враховує оголошений набір областей. -- Коли заголовок присутній, але порожній, запит оголошує **жодних** областей операторів. -- Коли заголовок відсутній, звичайні HTTP API, що несуть ідентичність, повертаються до стандартного набору областей операторів за замовчуванням. -- **HTTP-маршрути Plugin** з gateway-auth за замовчуванням вужчі: коли `x-openclaw-scopes` відсутній, їхня область виконання повертається до `operator.write`. -- HTTP-запити з браузера все одно мають проходити `gateway.controlUi.allowedOrigins` (або навмисний резервний режим Host-заголовка), навіть після успішної trusted-proxy автентифікації. +- Коли заголовок присутній, але порожній, запит не оголошує **жодних** областей оператора. +- Коли заголовок відсутній, звичайні HTTP API, що несуть ідентичність, повертаються до стандартного набору областей оператора за замовчуванням. +- **HTTP-маршрути Plugin** з автентифікацією Gateway за замовчуванням вужчі: коли `x-openclaw-scopes` відсутній, їхня область часу виконання повертається до `operator.write`. +- HTTP-запити з браузера все одно мають пройти `gateway.controlUi.allowedOrigins` (або навмисний резервний режим заголовка Host) навіть після успішної trusted-proxy auth. -Практичне правило: надсилайте `x-openclaw-scopes` явно, коли хочете, щоб trusted-proxy запит мав вужчі області, ніж типові значення за замовчуванням, або коли маршруту Plugin з gateway-auth потрібне щось сильніше за область write. +Практичне правило: надсилайте `x-openclaw-scopes` явно, коли хочете, щоб trusted-proxy запит був вужчим за значення за замовчуванням, або коли маршруту plugin з автентифікацією Gateway потрібне щось сильніше за область write. ## Контрольний список безпеки -Перш ніж увімкнути автентифікацію trusted-proxy, перевірте: +Перш ніж увімкнути trusted-proxy auth, переконайтеся, що: -- [ ] **Проксі є єдиним шляхом**: Порт Gateway захищений фаєрволом від усього, окрім вашого проксі. +- [ ] **Проксі — єдиний шлях**: Порт Gateway закритий фаєрволом для всіх, окрім вашого проксі. - [ ] **trustedProxies мінімальний**: Лише фактичні IP-адреси вашого проксі, а не цілі підмережі. -- [ ] **Немає loopback-джерела проксі**: автентифікація trusted-proxy працює за принципом fail closed для запитів із loopback-джерела. -- [ ] **Проксі видаляє заголовки**: Ваш проксі перезаписує (а не додає) заголовки `x-forwarded-*`, отримані від клієнтів. +- [ ] **Немає loopback-джерела проксі**: trusted-proxy auth відмовляє в закритому режимі для запитів із loopback-джерела. +- [ ] **Проксі очищує заголовки**: Ваш проксі перезаписує (а не додає) заголовки `x-forwarded-*`, що надходять від клієнтів. - [ ] **Завершення TLS**: Ваш проксі обробляє TLS; користувачі підключаються через HTTPS. -- [ ] **allowedOrigins явний**: Control UI поза loopback використовує явний `gateway.controlUi.allowedOrigins`. -- [ ] **allowUsers налаштовано** (рекомендовано): Обмежуйте доступ відомими користувачами, а не дозволяйте будь-кому, хто пройшов автентифікацію. -- [ ] **Немає змішаної конфігурації токена**: Не налаштовуйте одночасно `gateway.auth.token` і `gateway.auth.mode: "trusted-proxy"`. +- [ ] **allowedOrigins задано явно**: Для не-loopback Control UI використовується явний `gateway.controlUi.allowedOrigins`. +- [ ] **allowUsers задано** (рекомендовано): Обмежте доступ відомими користувачами, а не дозволяйте його будь-кому, хто автентифікувався. +- [ ] **Немає змішаної конфігурації токенів**: Не встановлюйте одночасно `gateway.auth.token` і `gateway.auth.mode: "trusted-proxy"`. +- [ ] **Локальний резервний пароль є приватним**: Якщо ви налаштовуєте `gateway.auth.password` для внутрішніх прямих викликачів, тримайте порт Gateway закритим фаєрволом, щоб віддалені клієнти не через проксі не могли напряму до нього підключитися. ## Аудит безпеки -`openclaw security audit` позначить автентифікацію trusted-proxy як проблему з рівнем серйозності **critical**. Це навмисно — це нагадування про те, що ви делегуєте безпеку вашій конфігурації проксі. +`openclaw security audit` позначить автентифікацію trusted-proxy як проблему з рівнем серйозності **critical**. Це зроблено навмисно — як нагадування, що ви делегуєте безпеку конфігурації свого проксі. Аудит перевіряє: -- Базове попередження/нагадування warning/critical для `gateway.trusted_proxy_auth` -- Відсутня конфігурація `trustedProxies` -- Відсутня конфігурація `userHeader` +- Базове попередження/критичне нагадування `gateway.trusted_proxy_auth` +- Відсутню конфігурацію `trustedProxies` +- Відсутню конфігурацію `userHeader` - Порожній `allowUsers` (дозволяє будь-якого автентифікованого користувача) -- Політика browser-origin із wildcard або її відсутність на відкритих поверхнях Control UI +- Політику browser-origin із wildcard або її відсутність на відкритих поверхнях Control UI ## Усунення несправностей - Запит не надійшов з IP-адреси, вказаної в `gateway.trustedProxies`. Перевірте: + Запит надійшов не з IP-адреси в `gateway.trustedProxies`. Перевірте: - Чи правильна IP-адреса проксі? (IP-адреси контейнерів Docker можуть змінюватися.) - Чи є балансувальник навантаження перед вашим проксі? @@ -364,18 +365,18 @@ Loopback trusted-proxy автентифікація також працює за Перевірте: - Чи підключається проксі з `127.0.0.1` / `::1`? - - Чи намагаєтеся ви використовувати trusted-proxy автентифікацію зі зворотним loopback-проксі на тому самому хості? + - Чи намагаєтеся ви використовувати trusted-proxy auth зі зворотним проксі на loopback на тому самому хості? Виправлення: - - Використовуйте автентифікацію за токеном/паролем для конфігурацій із loopback-проксі на тому самому хості, або - - Маршрутизуйте через не-loopback адресу довіреного проксі та збережіть цю IP-адресу в `gateway.trustedProxies`. + - Використовуйте автентифікацію токеном/паролем для конфігурацій проксі на loopback на тому самому хості, або + - Маршрутизуйте через не-loopback адресу довіреного проксі та тримайте цю IP-адресу в `gateway.trustedProxies`. - Заголовок користувача був порожній або відсутній. Перевірте: + Заголовок користувача був порожнім або відсутнім. Перевірте: - - Чи налаштований ваш проксі на передавання заголовків ідентичності? + - Чи налаштовано ваш проксі на передавання заголовків ідентичності? - Чи правильна назва заголовка? (регістр не має значення, але написання має) - Чи користувач справді автентифікований на проксі? @@ -388,47 +389,47 @@ Loopback trusted-proxy автентифікація також працює за - Користувач автентифікований, але його немає в `allowUsers`. Або додайте його, або видаліть список дозволених. + Користувач автентифікований, але його немає в `allowUsers`. Або додайте його, або приберіть список дозволених. - Trusted-proxy автентифікація пройшла успішно, але заголовок браузера `Origin` не пройшов перевірки походження Control UI. + Автентифікація trusted-proxy пройшла успішно, але заголовок браузера `Origin` не пройшов перевірки походження Control UI. Перевірте: - `gateway.controlUi.allowedOrigins` містить точне browser origin. - - Ви не покладаєтеся на wildcard origins, якщо тільки навмисно не хочете поведінку «дозволити все». - - Якщо ви навмисно використовуєте резервний режим Host-заголовка, `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` налаштовано свідомо. + - Ви не покладаєтеся на wildcard origins, якщо тільки свідомо не хочете поведінку «дозволити все». + - Якщо ви навмисно використовуєте резервний режим заголовка Host, `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` задано свідомо. - + Переконайтеся, що ваш проксі: - Підтримує оновлення WebSocket (`Upgrade: websocket`, `Connection: upgrade`). - - Передає заголовки ідентичності в запитах на оновлення WebSocket (а не лише для HTTP). - - Не має окремого шляху автентифікації для з’єднань WebSocket. + - Передає заголовки ідентичності в запитах оновлення WebSocket (а не лише HTTP). + - Не має окремого шляху автентифікації для підключень WebSocket. -## Міграція з автентифікації за токеном +## Міграція з автентифікації токеном -Якщо ви переходите з автентифікації за токеном на trusted-proxy: +Якщо ви переходите з автентифікації токеном на trusted-proxy: - Налаштуйте ваш проксі на автентифікацію користувачів і передавання заголовків. + Налаштуйте свій проксі на автентифікацію користувачів і передавання заголовків. Окремо протестуйте налаштування проксі (`curl` із заголовками). - Оновіть конфігурацію OpenClaw для trusted-proxy автентифікації. + Оновіть конфігурацію OpenClaw для trusted-proxy auth. Перезапустіть Gateway. - - Перевірте з’єднання WebSocket з Control UI. + + Протестуйте WebSocket-підключення з Control UI. Запустіть `openclaw security audit` і перегляньте результати. @@ -437,7 +438,7 @@ Loopback trusted-proxy автентифікація також працює за ## Пов’язане -- [Конфігурація](/uk/gateway/configuration) — довідник конфігурації +- [Конфігурація](/uk/gateway/configuration) — довідник із конфігурації - [Віддалений доступ](/uk/gateway/remote) — інші шаблони віддаленого доступу - [Безпека](/uk/gateway/security) — повний посібник із безпеки -- [Tailscale](/uk/gateway/tailscale) — простіша альтернатива для доступу лише в межах tailnet +- [Tailscale](/uk/gateway/tailscale) — простіша альтернатива для доступу лише в tailnet diff --git a/docs/uk/plugins/sdk-subpaths.md b/docs/uk/plugins/sdk-subpaths.md index 04e6de2a9..834b239e0 100644 --- a/docs/uk/plugins/sdk-subpaths.md +++ b/docs/uk/plugins/sdk-subpaths.md @@ -1,312 +1,312 @@ --- read_when: - - Вибір правильного підшляху plugin-sdk для імпорту Plugin + - Вибір правильного підшляху plugin-sdk для імпорту plugin - Аудит підшляхів bundled-plugin і допоміжних поверхонь summary: 'Каталог підшляхів Plugin SDK: які імпорти де розміщені, згруповано за областями' title: Підшляхи Plugin SDK x-i18n: - generated_at: "2026-04-27T21:58:46Z" + generated_at: "2026-04-27T22:22:42Z" model: gpt-5.4 provider: openai - source_hash: c0a164b1e967c1e794c6f03f5a2ff42ec2b8121dd7e4b1232c8ede10d97a7ebb + source_hash: 56f76f2371500ab77dc791ba862cb628daec596059f1f9def7227fecb2826347 source_path: plugins/sdk-subpaths.md workflow: 15 --- - Plugin SDK доступний як набір вузьких підшляхів у `openclaw/plugin-sdk/`. - На цій сторінці каталогізовано найуживаніші підшляхи, згруповані за призначенням. Згенерований + Plugin SDK представлений як набір вузьких підшляхів у `openclaw/plugin-sdk/`. + На цій сторінці наведено каталог поширено вживаних підшляхів, згрупованих за призначенням. Згенерований повний список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`; зарезервовані допоміжні підшляхи bundled-plugin також наведені там, але є деталями - реалізації, якщо лише сторінка документації явно не рекомендує їх. + реалізації, якщо лише сторінка документації явно не просуває їх. - Посібник з розробки Plugin дивіться в [Огляд Plugin SDK](/uk/plugins/sdk-overview). + Посібник з розробки plugin див. у [Огляд Plugin SDK](/uk/plugins/sdk-overview). - ## Точка входу Plugin + ## Точка входу plugin - | Підшлях | Основні експорти | - | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | - | `plugin-sdk/plugin-entry` | `definePluginEntry` | - | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | - | `plugin-sdk/config-schema` | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/migration` | Допоміжні елементи постачальника міграцій, такі як `createMigrationItem`, константи причин, маркери статусу елементів, допоміжні засоби редагування та `summarizeMigrationItems` | - | `plugin-sdk/migration-runtime` | Допоміжні засоби міграції під час виконання, такі як `copyMigrationFileItem` і `writeMigrationReport` | + | Subpath | Основні експорти | + | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `plugin-sdk/plugin-entry` | `definePluginEntry` | + | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | + | `plugin-sdk/config-schema` | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | + | `plugin-sdk/migration` | Допоміжні засоби елементів провайдера міграції, такі як `createMigrationItem`, константи причин, маркери статусу елементів, засоби редагування та `summarizeMigrationItems` | + | `plugin-sdk/migration-runtime` | Допоміжні засоби міграції під час виконання, такі як `copyMigrationFileItem` і `writeMigrationReport` | - | Підшлях | Основні експорти | + | Subpath | Основні експорти | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | Експорт кореневої схеми Zod для `openclaw.json` (`OpenClawSchema`) | + | `plugin-sdk/config-schema` | Експорт кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, підказки списку дозволених, побудовники статусу налаштування | + | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, підказки allowlist, побудовники статусу налаштування | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Допоміжні засоби для конфігурації кількох облікових записів і шлюзування дій, допоміжні засоби резервного переходу до облікового запису за замовчуванням | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації ідентифікатора облікового запису | - | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису та резервного переходу до значення за замовчуванням | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списку облікових записів і дій над обліковими записами | + | `plugin-sdk/account-core` | Допоміжні засоби багатокористувацького конфігу/керування шлюзами дій, допоміжні засоби резервного переходу до типового облікового запису | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації account-id | + | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису + резервного переходу до типового | + | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списків облікових записів/дій з обліковими записами | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Спільні примітиви схеми конфігурації каналу та універсальний побудовник | - | `plugin-sdk/channel-config-schema-legacy` | Застарілі схеми конфігурації bundled-channel лише для сумісності з bundled | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервною сумісністю з bundled-контрактом | + | `plugin-sdk/channel-config-schema` | Спільні примітиви схеми конфігу каналу та узагальнений побудовник | + | `plugin-sdk/channel-config-schema-legacy` | Застарілі схеми конфігу bundled-channel лише для сумісності з вбудованими компонентами | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервною сумісністю з bundled-contract | | `plugin-sdk/command-gating` | Вузькі допоміжні засоби шлюзу авторизації команд | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/завершення чернеткового потоку | - | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби маршрутизації вхідних повідомлень і побудови конверта | - | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису та диспетчеризації вхідних повідомлень | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/фіналізації потоку чернеток | + | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби побудови вхідних маршрутів і envelope | + | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису й диспетчеризації вхідних повідомлень | | `plugin-sdk/messaging-targets` | Допоміжні засоби розбору/зіставлення цілей | | `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження вихідних медіа | - | `plugin-sdk/outbound-send-deps` | Легковаговий пошук залежностей надсилання вихідних повідомлень для адаптерів каналів | - | `plugin-sdk/outbound-runtime` | Допоміжні засоби доставки вихідних повідомлень, ідентифікації, делегата надсилання, сесії, форматування та планування корисного навантаження | + | `plugin-sdk/outbound-send-deps` | Полегшений пошук залежностей вихідного надсилання для адаптерів каналів | + | `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідної доставки, ідентичності, делегата надсилання, сесій, форматування та планування payload | | `plugin-sdk/poll-runtime` | Вузькі допоміжні засоби нормалізації опитувань | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу прив’язок потоків і адаптерів | - | `plugin-sdk/agent-media-payload` | Застарілий побудовник медіакорисного навантаження агента | - | `plugin-sdk/conversation-runtime` | Допоміжні засоби прив’язки розмов/потоків, pairинг і налаштованих прив’язок | + | `plugin-sdk/thread-bindings-runtime` | Життєвий цикл прив’язок потоків та допоміжні засоби адаптерів | + | `plugin-sdk/agent-media-payload` | Застарілий побудовник agent media payload | + | `plugin-sdk/conversation-runtime` | Допоміжні засоби для прив’язки розмов/потоків, pairинг і налаштованих прив’язок | | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб знімка конфігурації під час виконання | - | `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення групової політики під час виконання | + | `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення групових політик під час виконання | | `plugin-sdk/channel-status` | Спільні допоміжні засоби знімка/підсумку стану каналу | - | `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації каналу | - | `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти Plugin каналу | - | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації списку дозволених | - | `plugin-sdk/group-access` | Спільні допоміжні засоби прийняття рішень щодо групового доступу | + | `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігу каналу | + | `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігу каналу | + | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти plugin каналу | + | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації allowlist | + | `plugin-sdk/group-access` | Спільні допоміжні засоби для рішень щодо групового доступу | | `plugin-sdk/direct-dm` | Спільні допоміжні засоби авторизації/захисту прямих DM | | `plugin-sdk/interactive-runtime` | Семантичне представлення повідомлень, доставка та застарілі допоміжні засоби інтерактивних відповідей. Див. [Представлення повідомлень](/uk/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | Barrel сумісності для debounce вхідних повідомлень, зіставлення згадок, допоміжних засобів політики згадок і допоміжних засобів конверта | + | `plugin-sdk/channel-inbound` | Сумісний barrel для debounce вхідних повідомлень, зіставлення згадок, допоміжних засобів політики згадок та допоміжних засобів envelope | | `plugin-sdk/channel-inbound-debounce` | Вузькі допоміжні засоби debounce для вхідних повідомлень | - | `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби політики згадок, маркерів згадок і тексту згадок без ширшої поверхні середовища виконання вхідних повідомлень | - | `plugin-sdk/channel-envelope` | Вузькі допоміжні засоби форматування конверта вхідних повідомлень | + | `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби політики згадок, маркерів згадок і тексту згадок без ширшої поверхні inbound runtime | + | `plugin-sdk/channel-envelope` | Вузькі допоміжні засоби форматування вхідних envelope | | `plugin-sdk/channel-location` | Допоміжні засоби контексту розташування каналу та форматування | - | `plugin-sdk/channel-logging` | Допоміжні засоби журналювання каналу для відкинутих вхідних повідомлень і помилок typing/ack | + | `plugin-sdk/channel-logging` | Допоміжні засоби журналювання каналу для відкинутих вхідних повідомлень і збоїв typing/ack | | `plugin-sdk/channel-send-result` | Типи результатів відповіді | - | `plugin-sdk/channel-actions` | Допоміжні засоби дій із повідомленнями каналу, а також застарілі допоміжні засоби нативної схеми, збережені для сумісності Plugin | + | `plugin-sdk/channel-actions` | Допоміжні засоби дій із повідомленнями каналу, а також застарілі рідні допоміжні засоби схем, збережені для сумісності plugin | | `plugin-sdk/channel-targets` | Допоміжні засоби розбору/зіставлення цілей | | `plugin-sdk/channel-contract` | Типи контрактів каналу | - | `plugin-sdk/channel-feedback` | Підключення відгуків/реакцій | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби контракту секретів, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей секретів | + | `plugin-sdk/channel-feedback` | Підключення зворотного зв’язку/реакцій | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби контрактів секретів, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей секретів | - - | Підшлях | Основні експорти | + + | Subpath | Основні експорти | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/lmstudio` | Підтримуваний фасад постачальника LM Studio для налаштування, виявлення каталогу та підготовки моделі під час виконання | - | `plugin-sdk/lmstudio-runtime` | Підтримуваний фасад середовища виконання LM Studio для типових значень локального сервера, виявлення моделей, заголовків запитів і допоміжних засобів для завантажених моделей | - | `plugin-sdk/provider-setup` | Кураторовані допоміжні засоби налаштування локальних/самостійно розміщених постачальників | - | `plugin-sdk/self-hosted-provider-setup` | Цільові допоміжні засоби налаштування самостійно розміщених постачальників, сумісних з OpenAI | - | `plugin-sdk/cli-backend` | Типові значення бекенда CLI та константи watchdog | - | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-ключа під час виконання для Plugin постачальників | - | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу API-ключа/запису профілю, такі як `upsertApiKeyProfile` | + | `plugin-sdk/lmstudio` | Підтримуваний фасад провайдера LM Studio для налаштування, виявлення каталогу та підготовки моделей під час виконання | + | `plugin-sdk/lmstudio-runtime` | Підтримуваний runtime-фасад LM Studio для типових локальних серверів, виявлення моделей, заголовків запитів і допоміжних засобів завантажених моделей | + | `plugin-sdk/provider-setup` | Кураторський набір допоміжних засобів налаштування локальних/self-hosted провайдерів | + | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted провайдерів, сумісних з OpenAI | + | `plugin-sdk/cli-backend` | Типові значення CLI backend + константи watchdog | + | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-ключа під час виконання для plugin провайдерів | + | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу API-ключів/запису профілів, такі як `upsertApiKeyProfile` | | `plugin-sdk/provider-auth-result` | Стандартний побудовник результату OAuth-автентифікації | - | `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для Plugin постачальників | - | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env var для автентифікації постачальників | + | `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для plugin провайдерів | + | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env vars для автентифікації провайдерів | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники політик повторного відтворення, допоміжні засоби кінцевих точок постачальників і допоміжні засоби нормалізації ідентифікаторів моделей, такі як `normalizeNativeXaiModelId` | - | `plugin-sdk/provider-catalog-runtime` | Хук середовища виконання каталогу постачальників і шви реєстру postачальників Plugin для тестів контрактів | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники політик повтору, допоміжні засоби endpoint провайдерів і допоміжні засоби нормалізації model-id, такі як `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-catalog-runtime` | Хуки runtime каталогу провайдерів і шви реєстру plugin-провайдерів для тестів контрактів | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Універсальні допоміжні засоби HTTP/можливостей кінцевих точок постачальників, HTTP-помилки постачальників і допоміжні засоби multipart form для транскрипції аудіо | - | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту конфігурації/вибору web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування постачальників web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби конфігурації/облікових даних web-search для постачальників, яким не потрібне підключення увімкнення Plugin | - | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setters/getters облікових даних | - | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/середовища виконання постачальників web-search | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini та діагностика, а також допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/endpoint-можливостей провайдерів, помилки HTTP провайдерів і допоміжні засоби multipart form для аудіотранскрипції | + | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контрактів конфігурації/вибору web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування провайдерів web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби конфігурації/облікових даних web-search для провайдерів, яким не потрібне підключення увімкнення plugin | + | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контрактів конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter для облікових даних | + | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime для провайдерів web-search | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика та допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібні | | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоків і спільні допоміжні засоби обгорток для Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-transport-runtime` | Нативні допоміжні засоби транспорту постачальників, такі як guarded fetch, трансформації транспортних повідомлень і потоки подій транспорту з можливістю запису | - | `plugin-sdk/provider-onboard` | Допоміжні засоби виправлення конфігурації онбордингу | + | `plugin-sdk/provider-transport-runtime` | Власні допоміжні засоби транспортного рівня провайдерів, такі як guarded fetch, перетворення транспортних повідомлень і записувані потоки транспортних подій | + | `plugin-sdk/provider-onboard` | Допоміжні засоби патчів конфігурації онбордингу | | `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache | | `plugin-sdk/group-activation` | Вузькі допоміжні засоби режиму активації груп і розбору команд | - | Підшлях | Основні експорти | + | Subpath | Основні експорти | | --- | --- | | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, включно з форматуванням меню динамічних аргументів, допоміжні засоби авторизації відправника | | `plugin-sdk/command-status` | Побудовники повідомлень команд/довідки, такі як `buildCommandsMessagePaginated` і `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення затверджувача та автентифікації дій у тому самому чаті | - | `plugin-sdk/approval-client-runtime` | Нативні допоміжні засоби профілю/фільтра затвердження exec | - | `plugin-sdk/approval-delivery-runtime` | Нативні адаптери можливостей/доставки затвердження | - | `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення Gateway затвердження | - | `plugin-sdk/approval-handler-adapter-runtime` | Легковагові допоміжні засоби завантаження нативного адаптера затвердження для гарячих точок входу каналів | - | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби середовища виконання обробника затвердження; віддавайте перевагу вужчим adapter/gateway seams, якщо їх достатньо | - | `plugin-sdk/approval-native-runtime` | Нативні допоміжні засоби цілей затвердження та прив’язки облікових записів | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби корисного навантаження відповіді затвердження exec/plugin | - | `plugin-sdk/approval-runtime` | Допоміжні засоби корисного навантаження затвердження exec/plugin, нативні допоміжні засоби маршрутизації/середовища виконання затвердження та допоміжні засоби структурованого відображення затвердження, такі як `formatApprovalDisplayPath` | + | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення затверджувача та автентифікації дій у тому ж чаті | + | `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра native exec approval | + | `plugin-sdk/approval-delivery-runtime` | Native-адаптери можливостей/доставки approval | + | `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення gateway для approval | + | `plugin-sdk/approval-handler-adapter-runtime` | Полегшені допоміжні засоби завантаження native-адаптерів approval для гарячих точок входу каналів | + | `plugin-sdk/approval-handler-runtime` | Ширші runtime-допоміжні засоби для approval; віддавайте перевагу вужчим адаптерним/Gateway-швам, коли їх достатньо | + | `plugin-sdk/approval-native-runtime` | Допоміжні засоби native approval target + прив’язки облікових записів | + | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповідей для exec/plugin approval | + | `plugin-sdk/approval-runtime` | Допоміжні засоби payload для exec/plugin approval, native-допоміжні засоби маршрутизації/runtime approval і допоміжні засоби структурованого відображення approval, такі як `formatApprovalDisplayPath` | | `plugin-sdk/reply-dedupe` | Вузькі допоміжні засоби скидання дедуплікації вхідних відповідей | - | `plugin-sdk/channel-contract-testing` | Вузькі допоміжні засоби тестування контракту каналу без широкого testing barrel | - | `plugin-sdk/command-auth-native` | Нативні допоміжні засоби автентифікації команд, форматування меню динамічних аргументів і нативні допоміжні засоби цілей сесії | + | `plugin-sdk/channel-contract-testing` | Вузькі допоміжні засоби тестування контрактів каналів без широкого testing barrel | + | `plugin-sdk/command-auth-native` | Native-автентифікація команд, форматування меню динамічних аргументів і native-допоміжні засоби цілей сесій | | `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд | - | `plugin-sdk/command-primitives-runtime` | Легковагові предикати тексту команд для гарячих шляхів каналів | - | `plugin-sdk/command-surface` | Нормалізація тіла команди та допоміжні засоби command-surface | + | `plugin-sdk/command-primitives-runtime` | Полегшені предикати тексту команд для гарячих шляхів каналів | + | `plugin-sdk/command-surface` | Нормалізація тіла команд і допоміжні засоби поверхні команд | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання secret-contract для поверхонь секретів channel/plugin | - | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для парсингу secret-contract/config | - | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, шлюзування DM, зовнішнього вмісту, редагування чутливого тексту, порівняння секретів за сталий час і збирання секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні засоби allowlist хостів і політики SSRF для приватних мереж | - | `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned-dispatcher без широкої поверхні infra runtime | - | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом SSRF, помилки SSRF і політики SSRF | - | `plugin-sdk/secret-input` | Допоміжні засоби парсингу введення секретів | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання секретних контрактів для поверхонь секретів channel/plugin | + | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для розбору секретних контрактів/конфігурації | + | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, DM gating, зовнішнього вмісту, редагування чутливого тексту, порівняння секретів у сталий час і збирання секретів | + | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для allowlist хостів і приватних мереж | + | `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned-dispatcher без широкої infra runtime-поверхні | + | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом SSRF, помилка SSRF і допоміжні засоби політики SSRF | + | `plugin-sdk/secret-input` | Допоміжні засоби розбору секретного введення | | `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів/цілей Webhook і приведення raw websocket/body | - | `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру тіла запиту/тайм-ауту | + | `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру тіла запиту/тайм-аутів | - - | Підшлях | Основні експорти | + + | Subpath | Основні експорти | | --- | --- | - | `plugin-sdk/runtime` | Широкі допоміжні засоби середовища виконання/журналювання/резервного копіювання/встановлення plugin | - | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби env середовища виконання, logger, timeout, retry і backoff | - | `plugin-sdk/browser-config` | Підтримуваний фасад конфігурації браузера для нормалізованого профілю/типових значень, парсингу URL CDP та допоміжних засобів автентифікації керування браузером | - | `plugin-sdk/channel-runtime-context` | Універсальні допоміжні засоби реєстрації та пошуку контексту середовища виконання каналу | + | `plugin-sdk/runtime` | Широкі runtime/логування/резервного копіювання/встановлення plugin допоміжні засоби | + | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби runtime env, logger, timeout, retry і backoff | + | `plugin-sdk/browser-config` | Підтримуваний фасад конфігурації браузера для нормалізованого профілю/типових значень, розбору CDP URL і допоміжних засобів автентифікації browser-control | + | `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби реєстрації та пошуку runtime-context каналу | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/хуків/http/інтерактивності plugin | - | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline Webhook/внутрішніх хуків | - | `plugin-sdk/lazy-runtime` | Допоміжні засоби ледачого імпорту/прив’язки runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Допоміжні засоби exec процесів | - | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування, версій, виклику аргументів і ледачих груп команд | - | `plugin-sdk/gateway-runtime` | Клієнт Gateway, CLI RPC Gateway, помилки протоколу Gateway та допоміжні засоби patch статусу каналу | - | `plugin-sdk/config-types` | Поверхня конфігурації лише для типів для форм конфігурації plugin, таких як `OpenClawConfig`, і типів конфігурації каналів/постачальників | - | `plugin-sdk/plugin-config-runtime` | Допоміжні засоби пошуку конфігурації plugin під час виконання, такі як `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби command/hook/http/interactive для plugin | + | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline Webhook/internal hook | + | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy runtime import/binding, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Допоміжні засоби виконання процесів | + | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування, версій, виклику аргументів і lazy command-group | + | `plugin-sdk/gateway-runtime` | Допоміжні засоби Gateway client, Gateway CLI RPC, помилок протоколу Gateway і патчів статусу каналу | + | `plugin-sdk/config-types` | Поверхня конфігурації лише для типів для форм конфігурації plugin, таких як `OpenClawConfig` і типи конфігурації каналів/провайдерів | + | `plugin-sdk/plugin-config-runtime` | Runtime-допоміжні засоби пошуку plugin-config, такі як `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` | | `plugin-sdk/config-mutation` | Допоміжні засоби транзакційної мутації конфігурації, такі як `mutateConfigFile`, `replaceConfigFile` і `logConfigUpdated` | - | `plugin-sdk/runtime-config-snapshot` | Допоміжні засоби знімка конфігурації поточного процесу, такі як `getRuntimeConfig`, `getRuntimeConfigSnapshot` і setters тестових знімків | - | `plugin-sdk/telegram-command-config` | Нормалізація назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня bundled-контракту Telegram недоступна | - | `plugin-sdk/text-autolink-runtime` | Виявлення автопосилань на файлові посилання без широкого text-runtime barrel | - | `plugin-sdk/approval-runtime` | Допоміжні засоби затвердження exec/plugin, побудовники можливостей затвердження, допоміжні засоби auth/profile, нативні допоміжні засоби маршрутизації/середовища виконання та форматування шляху структурованого відображення затвердження | - | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби середовища виконання вхідних повідомлень/відповідей, chunking, dispatch, Heartbeat, планувальник відповідей | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize відповідей і допоміжні засоби міток розмов | - | `plugin-sdk/reply-history` | Спільні допоміжні засоби коротковіконної історії відповідей і маркери, такі як `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/runtime-config-snapshot` | Допоміжні засоби знімка конфігурації поточного процесу, такі як `getRuntimeConfig`, `getRuntimeConfigSnapshot` і setter-и тестових знімків | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня контракту bundled Telegram недоступна | + | `plugin-sdk/text-autolink-runtime` | Виявлення autolink посилань на файли без широкого text-runtime barrel | + | `plugin-sdk/approval-runtime` | Допоміжні засоби exec/plugin approval, побудовники можливостей approval, допоміжні засоби auth/profile, native-допоміжні засоби routing/runtime і форматування шляху структурованого відображення approval | + | `plugin-sdk/reply-runtime` | Спільні runtime-допоміжні засоби inbound/reply, розбиття на частини, диспетчеризація, Heartbeat, планувальник відповідей | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби диспетчеризації/фіналізації відповідей і міток розмов | + | `plugin-sdk/reply-history` | Спільні допоміжні засоби short-window history відповідей і маркери, такі як `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/Markdown | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища сесій, ключа сесії, updated-at і мутації сховища | + | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/markdown | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища сесій, ключа сесії, updated-at і мутацій сховища | | `plugin-sdk/cron-store-runtime` | Допоміжні засоби шляху/завантаження/збереження сховища Cron | - | `plugin-sdk/state-paths` | Допоміжні засоби шляхів каталогів state/OAuth | - | `plugin-sdk/routing` | Допоміжні засоби маршруту/ключа сесії/прив’язки облікового запису, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку статусу каналу/облікового запису, типові значення стану середовища виконання та допоміжні засоби метаданих проблем | + | `plugin-sdk/state-paths` | Допоміжні засоби шляхів директорій state/OAuth | + | `plugin-sdk/routing` | Допоміжні засоби маршрутизації/ключа сесії/прив’язки облікових записів, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку стану каналу/облікового запису, типові значення runtime-state і допоміжні засоби метаданих проблем | | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби визначення цілей | | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації slug/рядків | - | `plugin-sdk/request-url` | Витягування рядкових URL з fetch/request-подібних вхідних даних | - | `plugin-sdk/run-command` | Виконавець команд із тайм-аутом із нормалізованими результатами stdout/stderr | - | `plugin-sdk/param-readers` | Стандартні читачі параметрів tool/CLI | - | `plugin-sdk/tool-payload` | Витягування нормалізованих payload із об’єктів результатів tool | + | `plugin-sdk/request-url` | Витягування рядкових URL з fetch/request-подібних входів | + | `plugin-sdk/run-command` | Запускач команд із таймуванням і нормалізованими результатами stdout/stderr | + | `plugin-sdk/param-readers` | Поширені зчитувачі параметрів tool/CLI | + | `plugin-sdk/tool-payload` | Витягування нормалізованих payload з об’єктів результатів tool | | `plugin-sdk/tool-send` | Витягування канонічних полів цілі надсилання з аргументів tool | | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів тимчасового завантаження | | `plugin-sdk/logging-core` | Допоміжні засоби logger підсистем і редагування | | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму таблиць Markdown і перетворення | - | `plugin-sdk/model-session-runtime` | Допоміжні засоби перевизначення моделі/сесії, такі як `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` | - | `plugin-sdk/talk-config-runtime` | Допоміжні засоби визначення конфігурації постачальника talk | - | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису стану JSON | - | `plugin-sdk/file-lock` | Допоміжні засоби повторно вхідного file-lock | - | `plugin-sdk/persistent-dedupe` | Допоміжні засоби кешу дедуплікації з backing на диску | - | `plugin-sdk/acp-runtime` | Допоміжні засоби середовища виконання/сесії ACP і dispatch відповідей | - | `plugin-sdk/acp-binding-resolve-runtime` | Розв’язання прив’язок ACP лише для читання без імпортів запуску життєвого циклу | - | `plugin-sdk/agent-config-primitives` | Вузькі примітиви config-schema runtime агента | - | `plugin-sdk/boolean-param` | Читач нестрогих boolean-параметрів | + | `plugin-sdk/model-session-runtime` | Допоміжні засоби перевизначення model/session, такі як `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` | + | `plugin-sdk/talk-config-runtime` | Допоміжні засоби визначення конфігурації talk provider | + | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису JSON state | + | `plugin-sdk/file-lock` | Допоміжні засоби реентерабельного file-lock | + | `plugin-sdk/persistent-dedupe` | Допоміжні засоби дедуплікаційного кешу зберігання на диску | + | `plugin-sdk/acp-runtime` | Допоміжні засоби ACP runtime/session і диспетчеризації відповідей | + | `plugin-sdk/acp-binding-resolve-runtime` | Розв’язання прив’язки ACP лише для читання без імпортів запуску життєвого циклу | + | `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації agent runtime | + | `plugin-sdk/boolean-param` | Нестрогий зчитувач булевих параметрів | | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення збігів небезпечних назв | - | `plugin-sdk/device-bootstrap` | Допоміжні засоби початкового налаштування пристрою та токенів pairing | + | `plugin-sdk/device-bootstrap` | Допоміжні засоби початкового налаштування пристрою та pairing token | | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів passive-channel, status і ambient proxy | - | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповіді команди `/models`/постачальника | - | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби списку команд Skills | - | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/побудови/серіалізації нативних команд | - | `plugin-sdk/agent-harness` | Експериментальна trusted-plugin поверхня для низькорівневих harness агента: типи harness, допоміжні засоби steer/abort активного запуску, допоміжні засоби мосту tool OpenClaw, допоміжні засоби політики tool плану runtime, класифікація результатів terminal, допоміжні засоби форматування/деталізації прогресу tool і утиліти результатів спроб | - | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення кінцевих точок Z.A.I | - | `plugin-sdk/async-lock-runtime` | Допоміжний засіб process-local async lock для невеликих файлів стану runtime | + | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповідей команди `/models`/провайдера | + | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби переліку команд Skills | + | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/build/serialize native-команд | + | `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих harness agent: типи harness, допоміжні засоби steer/abort активного запуску, допоміжні засоби мосту OpenClaw tool, допоміжні засоби політики runtime-plan tool, класифікація результатів terminal, допоміжні засоби форматування/деталізації прогресу tool і утиліти результатів спроб | + | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.AI | + | `plugin-sdk/async-lock-runtime` | Допоміжний засіб process-local async lock для невеликих runtime state-файлів | | `plugin-sdk/channel-activity-runtime` | Допоміжний засіб телеметрії активності каналу | - | `plugin-sdk/concurrency-runtime` | Допоміжний засіб обмеженої конкурентності асинхронних завдань | + | `plugin-sdk/concurrency-runtime` | Допоміжний засіб обмеженої конкурентності async-завдань | | `plugin-sdk/dedupe-runtime` | Допоміжні засоби кешу дедуплікації в пам’яті | - | `plugin-sdk/delivery-queue-runtime` | Допоміжний засіб дренування черги очікуваної вихідної доставки | - | `plugin-sdk/file-access-runtime` | Допоміжні засоби безпечних шляхів локальних файлів і джерел медіа | + | `plugin-sdk/delivery-queue-runtime` | Допоміжний засіб очищення черги очікуваної вихідної доставки | + | `plugin-sdk/file-access-runtime` | Допоміжні засоби безпечних шляхів до локальних файлів і джерел медіа | | `plugin-sdk/heartbeat-runtime` | Допоміжні засоби подій і видимості Heartbeat | | `plugin-sdk/number-runtime` | Допоміжний засіб приведення чисел | | `plugin-sdk/secure-random-runtime` | Допоміжні засоби безпечних токенів/UUID | | `plugin-sdk/system-event-runtime` | Допоміжні засоби черги системних подій | | `plugin-sdk/transport-ready-runtime` | Допоміжний засіб очікування готовності транспорту | - | `plugin-sdk/infra-runtime` | Застарілий shim сумісності; використовуйте цільові підшляхи runtime вище | + | `plugin-sdk/infra-runtime` | Застарілий shim сумісності; використовуйте сфокусовані runtime-підшляхи вище | | `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби обмеженого кешу | - | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби прапорців, подій і trace-context діагностики | + | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичних прапорців, подій і trace-context | | `plugin-sdk/error-runtime` | Допоміжні засоби графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` | | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch, proxy і pinned lookup | | `plugin-sdk/runtime-fetch` | Runtime fetch з урахуванням dispatcher без імпортів proxy/guarded-fetch | - | `plugin-sdk/response-limit-runtime` | Читач обмеженого тіла відповіді без широкої поверхні media runtime | - | `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки розмови без маршрутизації налаштованих прив’язок або сховищ pairing | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби сховища сесій без широких імпортів запису/обслуговування конфігурації | - | `plugin-sdk/context-visibility-runtime` | Розв’язання видимості контексту та фільтрація додаткового контексту без широких імпортів config/security | + | `plugin-sdk/response-limit-runtime` | Допоміжний засіб читання обмеженого response-body без широкої media runtime-поверхні | + | `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки розмови без routing налаштованих прив’язок або pairing stores | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби session-store без широких імпортів запису/обслуговування конфігурації | + | `plugin-sdk/context-visibility-runtime` | Визначення видимості контексту та фільтрація додаткового контексту без широких імпортів config/security | | `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні засоби приведення та нормалізації primitive record/string без імпортів markdown/logging | | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і SCP host | - | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і виконавця retry | - | `plugin-sdk/agent-runtime` | Допоміжні засоби каталогу/ідентичності/робочого простору агента | - | `plugin-sdk/directory-runtime` | Запит/dedup каталогу з backing у конфігурації | + | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і запуску retry | + | `plugin-sdk/agent-runtime` | Допоміжні засоби директорії/ідентичності/робочого простору agent | + | `plugin-sdk/directory-runtime` | Запит/дедуплікація директорій на основі конфігурації | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - | Підшлях | Основні експорти | + | Subpath | Основні експорти | | --- | --- | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа, а також побудовники корисного навантаження медіа | + | `plugin-sdk/media-runtime` | Спільні допоміжні засоби отримання/перетворення/збереження медіа, а також побудовники media payload | | `plugin-sdk/media-store` | Вузькі допоміжні засоби сховища медіа, такі як `saveMediaBuffer` | | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover для генерації медіа, вибір кандидатів і повідомлення про відсутню модель | - | `plugin-sdk/media-understanding` | Типи постачальників розуміння медіа, а також експорти допоміжних засобів для зображень/аудіо, орієнтовані на постачальників | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/Markdown/logging, такі як вилучення тексту, видимого асистенту, допоміжні засоби рендерингу/chunking/таблиць Markdown, допоміжні засоби редагування, допоміжні засоби тегів директив і утиліти безпечного тексту | + | `plugin-sdk/media-understanding` | Типи провайдерів розуміння медіа, а також експорти image/audio helper для провайдерів | + | `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/markdown/logging, такі як видалення assistant-visible-text, допоміжні засоби render/chunking/table для markdown, допоміжні засоби редагування, допоміжні засоби тегів директив і утиліти safe-text | | `plugin-sdk/text-chunking` | Допоміжний засіб chunking вихідного тексту | - | `plugin-sdk/speech` | Типи постачальників speech, а також експорти директив, реєстру, валідації та допоміжних засобів speech, орієнтовані на постачальників | - | `plugin-sdk/speech-core` | Спільні типи постачальників speech, а також експорти реєстру, директив, нормалізації та допоміжних засобів speech | - | `plugin-sdk/realtime-transcription` | Типи постачальників транскрипції в реальному часі, допоміжні засоби реєстру та спільний допоміжний засіб сесії WebSocket | - | `plugin-sdk/realtime-voice` | Типи постачальників голосу в реальному часі та допоміжні засоби реєстру | - | `plugin-sdk/image-generation` | Типи постачальників генерації зображень | - | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, допоміжні засоби failover, auth і реєстру | - | `plugin-sdk/music-generation` | Типи постачальників/запитів/результатів генерації музики | - | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, пошук постачальника та парсинг model-ref | - | `plugin-sdk/video-generation` | Типи постачальників/запитів/результатів генерації відео | - | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, пошук постачальника та парсинг model-ref | + | `plugin-sdk/speech` | Типи speech provider, а також експорти directive, registry, validation і speech helper для провайдерів | + | `plugin-sdk/speech-core` | Спільні типи speech provider, registry, directive, normalization і експорти speech helper | + | `plugin-sdk/realtime-transcription` | Типи провайдерів транскрипції в реальному часі, допоміжні засоби registry і спільний допоміжний засіб WebSocket session | + | `plugin-sdk/realtime-voice` | Типи провайдерів голосу в реальному часі та допоміжні засоби registry | + | `plugin-sdk/image-generation` | Типи провайдерів генерації зображень | + | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, допоміжні засоби failover, auth і registry | + | `plugin-sdk/music-generation` | Типи провайдерів/запитів/результатів генерації музики | + | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, пошук провайдерів і розбір model-ref | + | `plugin-sdk/video-generation` | Типи провайдерів/запитів/результатів генерації відео | + | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, пошук провайдерів і розбір model-ref | | `plugin-sdk/webhook-targets` | Допоміжні засоби реєстру цілей Webhook і встановлення маршрутів | | `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляху Webhook | | `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів plugin SDK | - | `plugin-sdk/testing` | Публічні допоміжні засоби тестування extension, включно з моками реєстру/runtime plugin, допоміжними засобами schema/media/live-test, `installCommonResolveTargetErrorCases`, `writeSkill`, `createTestRegistry` і завантаженням env для live generation. Допоміжні засоби extension `*.test-support.ts` мають залишатися тут або на цільових підшляхах SDK, а не у внутрішніх компонентах core | + | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK | + | `plugin-sdk/testing` | Публічні допоміжні засоби тестування extensions, включно з mock-об’єктами registry/runtime plugin, fetch/env/temp fixtures, допоміжними засобами schema/media/live-test, `installCommonResolveTargetErrorCases`, `writeSkill`, `createTestRegistry` і завантаженням env для live generation. Допоміжні засоби Extension `*.test-support.ts` мають залишатися тут або у сфокусованих підшляхах SDK, а не у внутрішніх компонентах core | - | Підшлях | Основні експорти | + | Subpath | Основні експорти | | --- | --- | - | `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для менеджера/конфігурації/файлів/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime індексації/пошуку пам’яті | - | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста пам’яті, доступ до реєстру, локальний постачальник і універсальні допоміжні засоби batch/remote | - | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста пам’яті | - | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста пам’яті | - | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті | - | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті | - | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | - | `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби runtime CLI хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-core` | Основні допоміжні засоби runtime хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-core` | Нейтральний до постачальника псевдонім для основних допоміжних засобів runtime хоста пам’яті | - | `plugin-sdk/memory-host-events` | Нейтральний до постачальника псевдонім для допоміжних засобів журналу подій хоста пам’яті | - | `plugin-sdk/memory-host-files` | Нейтральний до постачальника псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби керованого Markdown для plugin, суміжних із пам’яттю | - | `plugin-sdk/memory-host-search` | Фасад runtime Active Memory для доступу до менеджера пошуку | - | `plugin-sdk/memory-host-status` | Нейтральний до постачальника псевдонім для допоміжних засобів статусу хоста пам’яті | + | `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для manager/config/file/CLI helper | + | `plugin-sdk/memory-core-engine-runtime` | Runtime-фасад індексу/пошуку пам’яті | + | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine host-а пам’яті | + | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding host-а пам’яті, доступ до registry, локальний провайдер і загальні пакетні/віддалені helper | + | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine host-а пам’яті | + | `plugin-sdk/memory-core-host-engine-storage` | Експорти engine сховища host-а пам’яті | + | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні helper host-а пам’яті | + | `plugin-sdk/memory-core-host-query` | Helper запитів host-а пам’яті | + | `plugin-sdk/memory-core-host-secret` | Helper секретів host-а пам’яті | + | `plugin-sdk/memory-core-host-events` | Helper журналу подій host-а пам’яті | + | `plugin-sdk/memory-core-host-status` | Helper статусу host-а пам’яті | + | `plugin-sdk/memory-core-host-runtime-cli` | Runtime helper CLI host-а пам’яті | + | `plugin-sdk/memory-core-host-runtime-core` | Core runtime helper host-а пам’яті | + | `plugin-sdk/memory-core-host-runtime-files` | File/runtime helper host-а пам’яті | + | `plugin-sdk/memory-host-core` | Нейтральний до вендора псевдонім для core runtime helper host-а пам’яті | + | `plugin-sdk/memory-host-events` | Нейтральний до вендора псевдонім для helper журналу подій host-а пам’яті | + | `plugin-sdk/memory-host-files` | Нейтральний до вендора псевдонім для file/runtime helper host-а пам’яті | + | `plugin-sdk/memory-host-markdown` | Спільні helper керованого markdown для plugin, суміжних із пам’яттю | + | `plugin-sdk/memory-host-search` | Runtime-фасад Active Memory для доступу до менеджера пошуку | + | `plugin-sdk/memory-host-status` | Нейтральний до вендора псевдонім для helper статусу host-а пам’яті | | `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів bundled memory-lancedb | - | Сімейство | Поточні підшляхи | Призначення | + | Family | Поточні підшляхи | Призначення | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки bundled browser plugin. `browser-profiles` експортує `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile` і `ResolvedBrowserTabCleanupConfig` для нормалізованої форми `browser.tabCleanup`. `browser-support` залишається barrel сумісності. | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня допоміжних засобів/runtime bundled Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних засобів/runtime bundled LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних засобів bundled IRC | - | Допоміжні засоби, специфічні для каналів | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | Застарілі шви сумісності/допоміжних засобів bundled channel. Нові plugins мають імпортувати універсальні підшляхи SDK або локальні barrel-файли plugin. | - | Допоміжні засоби, специфічні для auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви допоміжних засобів bundled feature/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки bundled browser plugin. `browser-profiles` експортує `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile` і `ResolvedBrowserTabCleanupConfig` для нормалізованої форми `browser.tabCleanup`. `browser-support` залишається compatibility barrel. | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня helper/runtime bundled Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня helper/runtime bundled LINE | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня helper bundled IRC | + | Специфічні для каналів helper | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | Застарілі шви сумісності/helper для bundled channel. Нові plugins повинні імпортувати загальні підшляхи SDK або plugin-local barrel. | + | Helper автентифікації/специфічні для plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви helper для bundled feature/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | -## Пов’язані матеріали +## Пов’язане - [Огляд Plugin SDK](/uk/plugins/sdk-overview) - [Налаштування Plugin SDK](/uk/plugins/sdk-setup) diff --git a/docs/uk/plugins/sdk-testing.md b/docs/uk/plugins/sdk-testing.md index 4efca909e..d41634b84 100644 --- a/docs/uk/plugins/sdk-testing.md +++ b/docs/uk/plugins/sdk-testing.md @@ -2,25 +2,25 @@ read_when: - Ви пишете тести для Plugin - Вам потрібні утиліти тестування з SDK Plugin - - Ви хочете зрозуміти контрактні тести для bundled Plugin + - Ви хочете зрозуміти контрактні тести для вбудованих Plugin sidebarTitle: Testing -summary: Утиліти тестування та шаблони для Plugin OpenClaw +summary: Утиліти та шаблони тестування для Plugin OpenClaw title: Тестування Plugin x-i18n: - generated_at: "2026-04-27T12:53:51Z" + generated_at: "2026-04-27T22:22:43Z" model: gpt-5.4 provider: openai - source_hash: 3030e2a838b641433da2882270ef2b332284a7fc2f16037681b51536de42998e + source_hash: 358a1e76d6a8e78ad503b040d49bab7f66fa8bfb2f1fe7dcb6088ef932e56860 source_path: plugins/sdk-testing.md workflow: 15 --- -Довідник з утиліт тестування, шаблонів і lint-контролю для Plugin OpenClaw. +Довідник з утиліт тестування, шаблонів і забезпечення правил lint для Plugin OpenClaw. - **Шукаєте приклади тестів?** У how-to посібниках є готові приклади тестів: - [Тести Plugin каналів](/uk/plugins/sdk-channel-plugins#step-6-test) і - [Тести Plugin провайдерів](/uk/plugins/sdk-provider-plugins#step-6-test). + **Шукаєте приклади тестів?** Практичні посібники містять готові приклади тестів: + [Тести Channel Plugin](/uk/plugins/sdk-channel-plugins#step-6-test) і + [Тести Provider Plugin](/uk/plugins/sdk-provider-plugins#step-6-test). ## Утиліти тестування @@ -39,11 +39,22 @@ import { ### Доступні експорти -| Експорт | Призначення | -| -------------------------------------- | ----------------------------------------------------- | -| `installCommonResolveTargetErrorCases` | Спільні тестові випадки для обробки помилок визначення цілі | -| `shouldAckReaction` | Перевірити, чи має канал додавати ack reaction | -| `removeAckReactionAfterReply` | Видалити ack reaction після доставки відповіді | +| Export | Purpose | +| -------------------------------------- | ------------------------------------------------- | +| `installCommonResolveTargetErrorCases` | Спільні тестові випадки для обробки помилок під час визначення цілі | +| `shouldAckReaction` | Перевіряє, чи повинен канал додавати реакцію-підтвердження | +| `removeAckReactionAfterReply` | Видаляє реакцію-підтвердження після доставки відповіді | +| `createTestRegistry` | Створює фікстуру реєстру Channel Plugin | +| `createEmptyPluginRegistry` | Створює порожню фікстуру реєстру Plugin | +| `setActivePluginRegistry` | Встановлює фікстуру реєстру для runtime-тестів Plugin | +| `createRequestCaptureJsonFetch` | Перехоплює JSON fetch-запити в тестах медіадопоміжників | +| `withFetchPreconnect` | Запускає fetch-тести зі встановленими хуками preconnect | +| `withEnv` / `withEnvAsync` | Тимчасово підміняє змінні середовища | +| `createTempHomeEnv` / `withTempDir` | Створює ізольовані файлові фікстури для тестів | +| `createMockServerResponse` | Створює мінімальний mock-відповідь HTTP-сервера | +| `registerSingleProviderPlugin` | Реєструє один Provider Plugin у smoke-тестах завантажувача | +| `createRuntimeTaskFlow` | Створює ізольований стан runtime TaskFlow | +| `typedCases` | Зберігає literal-типи для табличних тестів | ### Типи @@ -62,24 +73,23 @@ import type { ## Тестування визначення цілі -Використовуйте `installCommonResolveTargetErrorCases`, щоб додати стандартні випадки помилок для -визначення цілей каналу: +Використовуйте `installCommonResolveTargetErrorCases`, щоб додати стандартні випадки помилок для визначення цілі каналу: ```typescript import { describe } from "vitest"; import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/testing"; -describe("визначення цілі my-channel", () => { +describe("my-channel target resolution", () => { installCommonResolveTargetErrorCases({ resolveTarget: ({ to, mode, allowFrom }) => { - // Логіка визначення цілі вашого каналу + // Your channel's target resolution logic return myChannelResolveTarget({ to, mode, allowFrom }); }, implicitAllowFrom: ["user1", "user2"], }); - // Додайте тестові випадки, специфічні для каналу - it("має визначати цілі @username", () => { + // Add channel-specific test cases + it("should resolve @username targets", () => { // ... }); }); @@ -89,31 +99,21 @@ describe("визначення цілі my-channel", () => { ### Тестування контрактів реєстрації -Юніт-тести, які передають написаний вручну mock `api` у `register(api)`, не перевіряють -шлюзи прийняття завантажувача OpenClaw. Додайте принаймні один smoke-тест на основі loader -для кожної поверхні реєстрації, від якої залежить ваш Plugin, особливо для hooks і -ексклюзивних можливостей, таких як memory. +Юніт-тести, які передають вручну написаний mock `api` до `register(api)`, не перевіряють acceptance gate завантажувача OpenClaw. Додайте щонайменше один smoke-тест на основі завантажувача для кожної поверхні реєстрації, від якої залежить ваш Plugin, особливо для hook і ексклюзивних можливостей, таких як memory. -Справжній loader відхиляє реєстрацію Plugin, коли відсутні потрібні метадані або -Plugin викликає API можливості, якою не володіє. Наприклад, -`api.registerHook(...)` вимагає ім’я hook, а -`api.registerMemoryCapability(...)` вимагає, щоб manifest Plugin або експортований -entry оголошував `kind: "memory"`. +Справжній завантажувач відхиляє реєстрацію Plugin, якщо бракує обов’язкових метаданих або якщо Plugin викликає API можливості, якою він не володіє. Наприклад, `api.registerHook(...)` вимагає назву hook, а `api.registerMemoryCapability(...)` вимагає, щоб маніфест Plugin або експортована точка входу оголошували `kind: "memory"`. -### Тестування доступу до конфігурації runtime +### Тестування доступу до runtime-конфігурації -Під час тестування bundled Plugin надавайте перевагу спільному mock runtime Plugin із допоміжних засобів тестування репозиторію. Його застарілі mock `runtime.config.loadConfig()` і -`runtime.config.writeConfigFile(...)` за замовчуванням викидають помилку, щоб тести виявляли нове -використання API сумісності. Перевизначайте ці mocks лише тоді, коли тест -явно покриває застарілу поведінку сумісності. +Під час тестування вбудованих Plugin віддавайте перевагу спільному mock runtime Plugin із допоміжних засобів тестування репозиторію. Його застарілі mock `runtime.config.loadConfig()` і `runtime.config.writeConfigFile(...)` за замовчуванням викидають помилку, щоб тести виявляли нове використання API сумісності. Перевизначайте ці mock лише тоді, коли тест явно перевіряє застарілу поведінку сумісності. -### Юніт-тестування Plugin каналу +### Юніт-тестування Channel Plugin ```typescript import { describe, it, expect, vi } from "vitest"; -describe("plugin my-channel", () => { - it("має визначати обліковий запис із конфігурації", () => { +describe("my-channel plugin", () => { + it("should resolve account from config", () => { const cfg = { channels: { "my-channel": { @@ -127,7 +127,7 @@ describe("plugin my-channel", () => { expect(account.token).toBe("test-token"); }); - it("має перевіряти обліковий запис без materializing секретів", () => { + it("should inspect account without materializing secrets", () => { const cfg = { channels: { "my-channel": { token: "test-token" }, @@ -137,22 +137,22 @@ describe("plugin my-channel", () => { const inspection = myPlugin.setup.inspectAccount(cfg, undefined); expect(inspection.configured).toBe(true); expect(inspection.tokenStatus).toBe("available"); - // Значення токена не розкривається + // No token value exposed expect(inspection).not.toHaveProperty("token"); }); }); ``` -### Юніт-тестування Plugin провайдера +### Юніт-тестування Provider Plugin ```typescript import { describe, it, expect } from "vitest"; -describe("plugin my-provider", () => { - it("має визначати динамічні моделі", () => { +describe("my-provider plugin", () => { + it("should resolve dynamic models", () => { const model = myProvider.resolveDynamicModel({ modelId: "custom-model-v2", - // ... контекст + // ... context }); expect(model.id).toBe("custom-model-v2"); @@ -160,10 +160,10 @@ describe("plugin my-provider", () => { expect(model.api).toBe("openai-completions"); }); - it("має повертати каталог, коли доступний API key", async () => { + it("should return catalog when API key is available", async () => { const result = await myProvider.catalog.run({ resolveProviderApiKey: () => ({ apiKey: "test-key" }), - // ... контекст + // ... context }); expect(result?.provider?.models).toHaveLength(2); @@ -171,9 +171,9 @@ describe("plugin my-provider", () => { }); ``` -### Mock runtime Plugin +### Мокування runtime Plugin -Для коду, який використовує `createPluginRuntimeStore`, mock runtime у тестах має виглядати так: +Для коду, який використовує `createPluginRuntimeStore`, мокайте runtime у тестах: ```typescript import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; @@ -184,42 +184,42 @@ const store = createPluginRuntimeStore({ errorMessage: "test runtime not set", }); -// У налаштуванні тесту +// In test setup const mockRuntime = { agent: { resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"), - // ... інші mocks + // ... other mocks }, config: { current: vi.fn(() => ({}) as const), mutateConfigFile: vi.fn(), replaceConfigFile: vi.fn(), }, - // ... інші простори імен + // ... other namespaces } as unknown as PluginRuntime; store.setRuntime(mockRuntime); -// Після тестів +// After tests store.clearRuntime(); ``` -### Тестування зі stub для окремих екземплярів +### Тестування зі стабами на рівні екземпляра -Надавайте перевагу stub для окремих екземплярів замість мутації prototype: +Віддавайте перевагу стабам на рівні екземпляра замість мутації прототипу: ```typescript -// Бажано: stub для окремого екземпляра +// Preferred: per-instance stub const client = new MyChannelClient(); client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); -// Уникайте: мутація prototype +// Avoid: prototype mutation // MyChannelClient.prototype.sendMessage = vi.fn(); ``` ## Контрактні тести (Plugin у репозиторії) -Bundled Plugin мають контрактні тести, які перевіряють право власності на реєстрацію: +Вбудовані Plugin мають контрактні тести, які перевіряють володіння реєстрацією: ```bash pnpm test -- src/plugins/contracts/ @@ -228,11 +228,11 @@ pnpm test -- src/plugins/contracts/ Ці тести перевіряють: - Які Plugin реєструють які провайдери -- Які Plugin реєструють які speech providers +- Які Plugin реєструють які мовленнєві провайдери - Коректність форми реєстрації - Відповідність runtime-контракту -### Запуск тестів з обмеженням області +### Запуск тестів з обмеженою областю Для конкретного Plugin: @@ -240,7 +240,7 @@ pnpm test -- src/plugins/contracts/ pnpm test -- /my-channel/ ``` -Лише контрактні тести: +Лише для контрактних тестів: ```bash pnpm test -- src/plugins/contracts/shape.contract.test.ts @@ -248,32 +248,31 @@ pnpm test -- src/plugins/contracts/auth.contract.test.ts pnpm test -- src/plugins/contracts/runtime.contract.test.ts ``` -## Lint-контроль (Plugin у репозиторії) +## Забезпечення правил lint (Plugin у репозиторії) `pnpm check` застосовує три правила для Plugin у репозиторії: -1. **Без монолітних імпортів з кореня** -- кореневий barrel `openclaw/plugin-sdk` відхиляється +1. **Без монолітних імпортів із кореня** -- кореневий barrel `openclaw/plugin-sdk` відхиляється 2. **Без прямих імпортів `src/`** -- Plugin не можуть напряму імпортувати `../../src/` -3. **Без self-imports** -- Plugin не можуть імпортувати власний підшлях `plugin-sdk/` +3. **Без самоімпортів** -- Plugin не можуть імпортувати власний підшлях `plugin-sdk/` -Зовнішні Plugin не підпадають під ці lint-правила, але дотримуватися тих самих -шаблонів рекомендується. +На зовнішні Plugin ці правила lint не поширюються, але дотримуватися тих самих шаблонів рекомендовано. ## Конфігурація тестування OpenClaw використовує Vitest із порогами покриття V8. Для тестів Plugin: ```bash -# Запустити всі тести +# Run all tests pnpm test -# Запустити тести конкретного Plugin +# Run specific plugin tests pnpm test -- /my-channel/src/channel.test.ts -# Запустити з фільтром за конкретною назвою тесту +# Run with a specific test name filter pnpm test -- /my-channel/ -t "resolves account" -# Запустити з coverage +# Run with coverage pnpm test:coverage ``` @@ -283,9 +282,9 @@ pnpm test:coverage OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test ``` -## Пов’язані теми +## Пов’язане - [Огляд SDK](/uk/plugins/sdk-overview) -- правила імпорту -- [SDK Plugin каналів](/uk/plugins/sdk-channel-plugins) -- інтерфейс Plugin каналу -- [SDK Plugin провайдерів](/uk/plugins/sdk-provider-plugins) -- hooks Plugin провайдера +- [SDK Channel Plugins](/uk/plugins/sdk-channel-plugins) -- інтерфейс Channel Plugin +- [SDK Provider Plugins](/uk/plugins/sdk-provider-plugins) -- hook Provider Plugin - [Створення Plugin](/uk/plugins/building-plugins) -- посібник для початку роботи