diff --git a/docs/uk/gateway/doctor.md b/docs/uk/gateway/doctor.md index deb364fb6..aabd4aabf 100644 --- a/docs/uk/gateway/doctor.md +++ b/docs/uk/gateway/doctor.md @@ -1,21 +1,21 @@ --- read_when: - - Додавання або зміна міграцій doctor + - Додавання або змінення міграцій doctor - Запровадження несумісних змін конфігурації summary: 'Команда doctor: перевірки стану, міграції конфігурації та кроки відновлення' -title: Doctor +title: doctor x-i18n: - generated_at: "2026-04-20T06:08:07Z" + generated_at: "2026-04-20T16:49:57Z" model: gpt-5.4 provider: openai - source_hash: 61a5e01a306058c49be6095f7c8082d779a55d63cf3b5f4c4096173943faf51b + source_hash: 6460fe657e7cf0d938bfbb77e1cc0355c1b67830327d441878e48375de52a46f source_path: gateway/doctor.md workflow: 15 --- # Doctor -`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілі конфігурації/стан, перевіряє стан системи та надає практичні кроки для відновлення. +`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілий конфіг/стан, перевіряє стан системи та надає практичні кроки для відновлення. ## Швидкий старт @@ -23,38 +23,38 @@ x-i18n: openclaw doctor ``` -### Headless / автоматизація +### Без інтерфейсу / автоматизація ```bash openclaw doctor --yes ``` -Прийняти типові значення без запитів (зокрема кроки відновлення перезапуску/служб/sandbox, якщо застосовно). +Приймає значення за замовчуванням без запитів (зокрема кроки відновлення перезапуску/сервісу/sandbox, коли це застосовно). ```bash openclaw doctor --repair ``` -Застосувати рекомендовані виправлення без запитів (виправлення + перезапуски, де це безпечно). +Застосовує рекомендовані виправлення без запитів (виправлення + перезапуски, де це безпечно). ```bash openclaw doctor --repair --force ``` -Застосувати також агресивні виправлення (перезаписує користувацькі конфігурації supervisor). +Також застосовує агресивні виправлення (перезаписує користувацькі конфігурації supervisor). ```bash openclaw doctor --non-interactive ``` -Запустити без запитів і застосувати лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії з перезапуском/службами/sandbox, які потребують підтвердження людини. -Міграції застарілого стану виконуються автоматично, якщо їх виявлено. +Запускається без запитів і застосовує лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії перезапуску/сервісу/sandbox, які потребують підтвердження людини. +Міграції застарілого стану запускаються автоматично, якщо їх виявлено. ```bash openclaw doctor --deep ``` -Сканувати системні служби на наявність додаткових інсталяцій gateway (`launchd/systemd/schtasks`). +Сканує системні сервіси на наявність додаткових установок Gateway (launchd/systemd/schtasks). Якщо ви хочете переглянути зміни перед записом, спочатку відкрийте файл конфігурації: @@ -64,99 +64,95 @@ cat ~/.openclaw/openclaw.json ## Що він робить (коротко) -- Необов’язкове попереднє оновлення для git-інсталяцій (лише в інтерактивному режимі). -- Перевірка актуальності протоколу UI (перебудовує Control UI, якщо схема протоколу новіша). +- Необов’язкове попереднє оновлення для git-установок (лише в інтерактивному режимі). +- Перевірка актуальності протоколу UI (перезбирає Control UI, якщо схема протоколу новіша). - Перевірка стану + запит на перезапуск. -- Підсумок стану Skills (доступні/відсутні/заблоковані) і стану plugin. +- Зведення стану Skills (доступні/відсутні/заблоковані) і стану plugin. - Нормалізація конфігурації для застарілих значень. - Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.`. -- Перевірки міграції browser для застарілих конфігурацій розширення Chrome і готовності Chrome MCP. +- Перевірки міграції браузера для застарілих конфігурацій Chrome extension і готовності Chrome MCP. - Попередження про перевизначення провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). - Попередження про затінення OAuth Codex (`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`). +- Міграція застарілих ключів контракту маніфесту plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). +- Міграція сховища застарілих Cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, `provider` у payload, прості fallback-завдання Webhook з `notify: true`). - Перевірка файлів блокування сесій і очищення застарілих блокувань. -- Перевірки цілісності стану та прав доступу (sessions, transcripts, каталог state). -- Перевірка прав доступу до файлу конфігурації (`chmod 600`) під час локального запуску. +- Перевірки цілісності стану та прав доступу (sessions, transcripts, каталог стану). +- Перевірки прав доступу до файла конфігурації (`chmod 600`) під час локального запуску. - Стан автентифікації моделей: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє про стани cooldown/disabled профілю автентифікації. -- Виявлення додаткового робочого каталогу (`~/openclaw`). +- Виявлення додаткового каталогу workspace (`~/openclaw`). - Відновлення образу sandbox, коли sandboxing увімкнено. -- Міграція застарілих служб і виявлення додаткових gateway. +- Міграція застарілого сервісу та виявлення додаткових Gateway. - Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`). -- Перевірки середовища виконання gateway (службу встановлено, але не запущено; кешований label `launchd`). -- Попередження про стан каналів (зондуються із запущеного gateway). -- Аудит конфігурації supervisor (`launchd/systemd/schtasks`) з необов’язковим відновленням. -- Перевірки рекомендованих практик для середовища виконання gateway (Node vs Bun, шляхи менеджера версій). -- Діагностика конфліктів порту gateway (типово `18789`). +- Перевірки середовища виконання Gateway (сервіс встановлено, але не запущено; кешований label launchd). +- Попередження про стан каналів (перевіряються через запущений Gateway). +- Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим відновленням. +- Перевірки найкращих практик середовища виконання Gateway (Node проти Bun, шляхи менеджера версій). +- Діагностика конфліктів порту Gateway (типово `18789`). - Попередження безпеки для відкритих політик DM. -- Перевірки автентифікації gateway для режиму локального токена (пропонує згенерувати токен, якщо джерело токена відсутнє; не перезаписує конфігурації токенів SecretRef). -- Виявлення проблем із pairing пристроїв (очікувані перші запити на pairing, очікувані підвищення ролі/області дії, застарілий дрейф локального кешу токенів пристрою та дрейф автентифікації записів paired). -- Перевірка `systemd linger` на Linux. -- Перевірка розміру файлів bootstrap робочого простору (попередження про обрізання/наближення до ліміту для контекстних файлів). -- Перевірка стану shell completion та автоматичне встановлення/оновлення. -- Перевірка готовності провайдера embedding для пошуку в пам’яті (локальна модель, віддалений ключ API або бінарний файл QMD). -- Перевірки інсталяції з вихідного коду (невідповідність робочого простору pnpm, відсутні ресурси UI, відсутній бінарний файл tsx). -- Записує оновлену конфігурацію та метадані wizard. +- Перевірки автентифікації Gateway для режиму локального токена (пропонує згенерувати токен, якщо немає джерела токена; не перезаписує конфігурації token SecretRef). +- Виявлення проблем зі спарюванням пристроїв (очікування запитів на перше спарювання, очікування оновлень ролі/області дії, застарілий дрейф локального кешу токенів пристроїв і дрейф автентифікації paired-record). +- Перевірка linger systemd у Linux. +- Перевірка розміру bootstrap-файлів workspace (попередження про обрізання/наближення до ліміту для контекстних файлів). +- Перевірка стану shell completion і автоматичне встановлення/оновлення. +- Перевірка готовності провайдера embedding для пошуку в пам’яті (локальна модель, віддалений API-ключ або бінарний файл QMD). +- Перевірки source-установки (невідповідність workspace pnpm, відсутні ресурси UI, відсутній бінарний файл tsx). +- Записує оновлений конфіг + метадані wizard. -## Заповнення Dreams UI і скидання +## Backfill і reset у 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-прохід щоденника та записує оборотні записи backfill у `DREAMS.md`. -- **Reset** видаляє з `DREAMS.md` лише ті записи щоденника backfill, що мають відповідну позначку. +- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному workspace, запускає grounded-прохід щоденника REM і записує зворотні записи backfill у `DREAMS.md`. +- **Reset** видаляє з `DREAMS.md` лише ті записи щоденника backfill, які позначені. - **Clear Grounded** видаляє лише staged grounded-only короткострокові записи, що походять з історичного відтворення і ще не накопичили live recall або щоденну підтримку. -Чого вони самі по собі **не** роблять: +Що вони **не** роблять самі по собі: - вони не редагують `MEMORY.md` - вони не запускають повні міграції doctor -- вони не переводять автоматично grounded candidates до живого сховища підвищення short-term, якщо ви явно не запустили staged CLI-шлях раніше +- вони не додають grounded-кандидатів автоматично до live short-term promotion store, якщо ви явно не запустите staged CLI-шлях спочатку -Якщо ви хочете, щоб grounded historical replay впливав на звичайний шлях deep promotion, використовуйте натомість CLI-процес: +Якщо ви хочете, щоб grounded historical replay впливав на звичайний шлях глибокого просування, використовуйте натомість CLI-процес: ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -Це переводить grounded durable candidates до сховища short-term dreaming, зберігаючи `DREAMS.md` як поверхню перегляду. +Це додає grounded durable candidates до short-term dreaming store, залишаючи `DREAMS.md` поверхнею для перегляду. -## Докладна поведінка та обґрунтування +## Детальна поведінка та обґрунтування -### 0) Необов’язкове оновлення (git-інсталяції) +### 0) Необов’язкове оновлення (git-установки) -Якщо це git checkout і doctor запущено в інтерактивному режимі, він запропонує -оновитися (fetch/rebase/build) перед запуском doctor. +Якщо це git checkout і doctor запущено в інтерактивному режимі, він пропонує оновлення (fetch/rebase/build) перед запуском doctor. ### 1) Нормалізація конфігурації -Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` -без channel-specific перевизначення), doctor нормалізує їх до поточної -схеми. +Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без перевизначення для конкретного каналу), doctor нормалізує їх до поточної схеми. Це також включає застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — -це `talk.provider` + `talk.providers.`. Doctor переписує старі -форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / +`talk.provider` + `talk.providers.`. Doctor переписує старі форми +`talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у мапу провайдерів. ### 2) Міграції застарілих ключів конфігурації -Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися і просять -вас виконати `openclaw doctor`. +Коли конфігурація містить застарілі ключі, інші команди відмовляються виконуватися і просять +запустити `openclaw doctor`. Doctor виконає таке: -- Пояснить, які застарілі ключі було знайдено. -- Покажe міграцію, яку він застосував. -- Перезапише `~/.openclaw/openclaw.json` з оновленою схемою. +- Пояснить, які застарілі ключі знайдено. +- Покажe міграцію, яку було застосовано. +- Перезапише `~/.openclaw/openclaw.json` оновленою схемою. Gateway також автоматично запускає міграції doctor під час старту, коли виявляє -застарілий формат конфігурації, тож застарілі конфігурації виправляються без ручного втручання. -Міграції сховища Cron обробляються командою `openclaw doctor --fix`. +застарілий формат конфігурації, тому застарілі конфігурації виправляються без ручного втручання. +Міграції сховища завдань Cron обробляються через `openclaw doctor --fix`. Поточні міграції: @@ -165,7 +161,7 @@ Gateway також автоматично запускає міграції doct - `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` @@ -180,79 +176,68 @@ Gateway також автоматично запускає міграції doct - `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 може зберегти наявну відповідну ціль named/default) +- Для каналів з іменованими `accounts`, але із залишеними однокористувацькими значеннями каналу верхнього рівня, перемістити ці значення рівня акаунта в обраний підвищений акаунт для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/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` - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` -- видалити `browser.relayBindHost` (застарілий параметр relay для extension) +- видалити `browser.relayBindHost` (застаріле налаштування relay для extension) -Попередження doctor також містять рекомендації щодо default account для багатокористувацьких каналів: +Попередження doctor також містять рекомендації щодо акаунта за замовчуванням для багатoакаунтних каналів: -- Якщо налаштовано два або більше записи `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис. -- Якщо `channels..defaultAccount` встановлено на невідомий ідентифікатор облікового запису, doctor попереджає та перелічує налаштовані ідентифікатори облікових записів. +- Якщо налаштовано два або більше записи `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що fallback-маршрутизація може вибрати неочікуваний акаунт. +- Якщо `channels..defaultAccount` встановлено на невідомий ID акаунта, doctor попереджає та перелічує налаштовані ID акаунтів. ### 2b) Перевизначення провайдера OpenCode Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. -Це може змусити моделі використовувати неправильний API або обнулити вартість. Doctor попереджає про це, щоб ви -могли видалити перевизначення і відновити маршрутизацію API та вартість для кожної моделі. +Це може примусово направити моделі на неправильний API або обнулити вартість. Doctor попереджає про це, щоб ви могли прибрати перевизначення й відновити маршрутизацію API та вартість для кожної моделі. -### 2c) Міграція browser і готовність Chrome MCP +### 2c) Міграція браузера та готовність Chrome MCP -Якщо ваша конфігурація browser усе ще вказує на видалений шлях розширення Chrome, doctor +Якщо ваша конфігурація браузера досі вказує на видалений шлях Chrome extension, doctor нормалізує її до поточної моделі підключення host-local Chrome MCP: - `browser.profiles.*.driver: "extension"` стає `"existing-session"` - `browser.relayBindHost` видаляється -Doctor також перевіряє шлях host-local Chrome MCP, коли ви використовуєте `defaultProfile: +Doctor також перевіряє host-local шлях Chrome MCP, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`: -- перевіряє, чи встановлено Google Chrome на тому самому хості для типових - профілів з автоматичним підключенням +- перевіряє, чи встановлено Google Chrome на тому самому хості для профілів авто-підключення за замовчуванням - перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144 -- нагадує увімкнути remote debugging на сторінці inspect браузера (наприклад - `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, +- нагадує ввімкнути remote debugging на сторінці inspect браузера (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, або `edge://inspect/#remote-debugging`) -Doctor не може увімкнути цей параметр на стороні Chrome за вас. Host-local Chrome MCP +Doctor не може ввімкнути це налаштування на боці Chrome за вас. Host-local Chrome MCP досі потребує: -- браузер на основі Chromium 144+ на хості gateway/node +- браузер на базі Chromium 144+ на хості Gateway/node - локально запущений браузер - увімкнений remote debugging у цьому браузері -- підтвердження першого запиту на attach consent у браузері +- підтвердження першого запиту на згоду для attach у браузері -Готовність тут стосується лише передумов локального attach. Existing-session зберігає -поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, -перехоплення завантажень та пакетні дії, як і раніше, потребують керованого -browser або сирого профілю CDP. +Готовність тут стосується лише передумов для локального attach. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, як і раніше, потребують керованого браузера або профілю raw CDP. -Ця перевірка **не** застосовується до Docker, sandbox, remote-browser чи інших -headless-сценаріїв. Вони й надалі використовують сирий CDP. +Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших headless-процесів. Вони й надалі використовують raw CDP. ### 2d) TLS-передумови OAuth -Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє endpoint авторизації OpenAI, щоб переконатися, що локальний стек TLS Node/OpenSSL може -перевірити ланцюжок сертифікатів. Якщо перевірка не проходить через помилку сертифіката (наприклад, -`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), -doctor виводить специфічні для платформи рекомендації щодо виправлення. На macOS з Node від Homebrew -виправленням зазвичай є `brew postinstall ca-certificates`. З `--deep` перевірка виконується -навіть якщо gateway у справному стані. +Коли налаштовано профіль 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 у справному стані. ### 2c) Перевизначення провайдера Codex OAuth -Якщо ви раніше додали застарілі параметри транспорту OpenAI у +Якщо ви раніше додали застарілі налаштування транспорту OpenAI у `models.providers.openai-codex`, вони можуть затіняти вбудований шлях -провайдера Codex OAuth, який новіші релізи використовують автоматично. Doctor попереджає, коли бачить -ці старі параметри транспорту разом із Codex OAuth, щоб ви могли видалити або переписати -застаріле перевизначення транспорту й повернути вбудовану поведінку -маршрутизації/резервного перемикання. Користувацькі проксі та перевизначення лише заголовків, як і раніше, підтримуються й не -викликають цього попередження. +провайдера Codex OAuth, який новіші релізи використовують автоматично. Doctor +попереджає, коли бачить ці старі налаштування транспорту поруч із Codex OAuth, +щоб ви могли видалити або переписати застаріле перевизначення транспорту і +повернути вбудовану поведінку маршрутизації/fallback. Користувацькі проксі та +перевизначення лише заголовків, як і раніше, підтримуються і не спричиняють +цього попередження. ### 3) Міграції застарілого стану (структура на диску) @@ -264,32 +249,26 @@ Doctor може мігрувати старіші структури на дис - з `~/.openclaw/agent/` до `~/.openclaw/agents//agent/` - Стан автентифікації WhatsApp (Baileys): - із застарілих `~/.openclaw/credentials/*.json` (крім `oauth.json`) - - до `~/.openclaw/credentials/whatsapp//...` (типовий id облікового запису: `default`) + - до `~/.openclaw/credentials/whatsapp//...` (ID акаунта за замовчуванням: `default`) -Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor виводить попередження, коли -залишає будь-які застарілі каталоги як резервні копії. Gateway/CLI також автоматично мігрує -застарілі sessions + каталог agent під час запуску, тож історія/автентифікація/моделі потрапляють у шлях -для конкретного agent без ручного запуску doctor. Автентифікація WhatsApp навмисно -мігрується лише через `openclaw doctor`. Нормалізація Talk provider/provider-map тепер -порівнює за структурною рівністю, тож відмінності лише в порядку ключів більше не викликають -повторних порожніх змін у `doctor --fix`. +Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor виведе попередження, якщо залишить будь-які застарілі каталоги як резервні копії. Gateway/CLI також автоматично мігрує застарілі sessions + каталог agent під час старту, тому history/auth/models потрапляють у шлях для конкретного agent без ручного запуску doctor. Автентифікація WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація провайдера/мапи провайдерів Talk тепер порівнює за структурною рівністю, тому відмінності лише в порядку ключів більше не спричиняють повторних no-op змін у `doctor --fix`. ### 3a) Міграції застарілих маніфестів plugin -Doctor сканує всі встановлені маніфести plugin на наявність застарілих capability-ключів -верхнього рівня (`speechProviders`, `realtimeTranscriptionProviders`, +Doctor сканує всі встановлені маніфести plugin на наявність застарілих ключів +можливостей верхнього рівня (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, -`webSearchProviders`). Якщо їх знайдено, він пропонує перемістити їх в об’єкт `contracts` -і переписати файл маніфесту на місці. Ця міграція є ідемпотентною; +`webSearchProviders`). Якщо їх знайдено, він пропонує перемістити їх до об’єкта +`contracts` і переписати файл маніфесту на місці. Ця міграція є ідемпотентною; якщо ключ `contracts` уже містить ті самі значення, застарілий ключ видаляється без дублювання даних. ### 3b) Міграції застарілого сховища Cron -Doctor також перевіряє сховище завдань Cron (`~/.openclaw/cron/jobs.json` типово, -або `cron.store`, якщо його перевизначено) на наявність старих форм завдань, які планувальник -досі приймає для сумісності. +Doctor також перевіряє сховище завдань Cron (`~/.openclaw/cron/jobs.json` за замовчуванням, +або `cron.store`, якщо його перевизначено) на наявність старих форм завдань, +які планувальник досі приймає для сумісності. Поточні очищення Cron включають: @@ -297,167 +276,171 @@ Doctor також перевіряє сховище завдань Cron (`~/.ope - `schedule.cron` → `schedule.expr` - поля payload верхнього рівня (`message`, `model`, `thinking`, ...) → `payload` - поля delivery верхнього рівня (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` -- псевдоніми доставки payload `provider` → явний `delivery.channel` -- прості застарілі резервні Webhook-завдання `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook` +- псевдоніми delivery `provider` у payload → явний `delivery.channel` +- прості застарілі fallback-завдання Webhook з `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook` -Doctor автоматично мігрує завдання `notify: true`, лише коли може зробити це -без зміни поведінки. Якщо завдання поєднує застарілий резервний notify із вже наявним -режимом доставки не через webhook, doctor попереджає і залишає це завдання для ручної перевірки. +Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити +це без зміни поведінки. Якщо завдання поєднує застарілий fallback notify з +наявним режимом delivery не-Webhook, doctor попереджає і залишає це завдання +для ручної перевірки. ### 3c) Очищення блокувань сесій -Doctor сканує каталог сесій кожного agent на наявність застарілих файлів блокування запису — -файлів, що залишилися після аварійного завершення сесії. Для кожного знайденого файлу блокування він повідомляє: -шлях, PID, чи активний цей PID, вік блокування та чи -вважається воно застарілим (мертвий PID або старше 30 хвилин). У режимі `--fix` / `--repair` -він автоматично видаляє застарілі файли блокування; інакше лише виводить примітку та -пропонує перезапустити з `--fix`. +Doctor сканує кожен каталог sessions agent на наявність застарілих файлів +блокування запису — файлів, що залишилися після аварійного завершення сесії. +Для кожного знайденого файла блокування він повідомляє: +шлях, PID, чи PID досі активний, вік блокування та чи вважається воно +застарілим (PID неактивний або старший за 30 хвилин). У режимі `--fix` / `--repair` +він автоматично видаляє застарілі файли блокування; інакше друкує примітку та +просить перезапустити з `--fix`. -### 4) Перевірки цілісності стану (збереження сесії, маршрутизація та безпека) +### 4) Перевірки цілісності стану (збереження сесій, маршрутизація та безпека) -Каталог стану — це операційний стовбур системи. Якщо він зникне, ви втратите -sessions, credentials, logs і config (якщо тільки в вас немає резервних копій в іншому місці). +Каталог стану — це операційний стовбур мозку. Якщо він зникне, ви втратите +sessions, credentials, logs і config (якщо не маєте резервних копій деінде). Doctor перевіряє: -- **Відсутній каталог стану**: попереджає про катастрофічну втрату стану, пропонує повторно створити - каталог і нагадує, що не може відновити відсутні дані. -- **Права доступу до каталогу стану**: перевіряє можливість запису; пропонує відновити права доступу - (і виводить підказку `chown`, якщо виявлено невідповідність власника/групи). -- **Каталог стану macOS, синхронізований із хмарою**: попереджає, коли стан розміщено в iCloud Drive +- **Відсутній каталог стану**: попереджає про катастрофічну втрату стану, пропонує відновити + каталог і нагадує, що не може відновити втрачені дані. +- **Права доступу до каталогу стану**: перевіряє можливість запису; пропонує виправити права + (і виводить підказку `chown`, якщо виявлено невідповідність owner/group). +- **Каталог стану в macOS із хмарною синхронізацією**: попереджає, коли стан розташовано в iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, оскільки шляхи із синхронізацією можуть спричиняти повільніший I/O - і перегони блокування/синхронізації. -- **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розміщено на джерелі монтування `mmcblk*`, + та гонки блокувань/синхронізації. +- **Каталог стану Linux на SD або eMMC**: попереджає, коли стан знаходиться на джерелі монтування `mmcblk*`, оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час запису sessions і credentials. -- **Відсутні каталоги sessions**: `sessions/` і каталог сховища сесій - потрібні для збереження історії та уникнення аварій `ENOENT`. -- **Невідповідність transcript**: попереджає, коли в недавніх записах сесії відсутні +- **Відсутні каталоги sessions**: `sessions/` і каталог сховища sessions + потрібні для збереження history і уникнення аварій `ENOENT`. +- **Невідповідність transcript**: попереджає, коли в нещодавніх записах sessions відсутні файли transcript. -- **Основна сесія “1-line JSONL”**: позначає випадки, коли основний transcript містить лише один - рядок (історія не накопичується). -- **Кілька каталогів стану**: попереджає, коли існує кілька каталогів `~/.openclaw` у різних - домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може - розділятися між інсталяціями). -- **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує виконати - його на віддаленому хості (там розміщується стан). -- **Права доступу до файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` - доступний для читання групі/усім, і пропонує обмежити права до `600`. +- **Основна сесія “1-line JSONL”**: позначає ситуацію, коли головний transcript має лише один + рядок (history не накопичується). +- **Кілька каталогів стану**: попереджає, коли існує кілька папок `~/.openclaw` у різних + домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (history може + розділятися між установками). +- **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запускати + його на віддаленому хості (стан зберігається там). +- **Права доступу до файла конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` є + читабельним для group/world, і пропонує обмежити права до `600`. ### 5) Стан автентифікації моделей (строк дії OAuth) Doctor перевіряє профілі OAuth у сховищі автентифікації, попереджає, коли токени -спливають/уже спливли, і може оновлювати їх, коли це безпечно. Якщо профіль -OAuth/token Anthropic застарів, він пропонує ключ Anthropic API або -шлях Anthropic setup-token. -Запити на оновлення з’являються лише в інтерактивному режимі (TTY); `--non-interactive` +ось-ось спливуть або вже спливли, і може оновити їх, коли це безпечно. Якщо профіль +OAuth/token Anthropic застарів, він пропонує API-ключ Anthropic або шлях +setup-token Anthropic. +Запити на оновлення з’являються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення. -Коли оновлення OAuth остаточно не вдається (наприклад, `refresh_token_reused`, -`invalid_grant` або коли провайдер каже увійти знову), doctor повідомляє, -що потрібна повторна автентифікація, і виводить точну команду `openclaw models auth login --provider ...`, -яку потрібно виконати. +Коли оновлення OAuth остаточно завершується невдачею (наприклад `refresh_token_reused`, +`invalid_grant` або коли провайдер повідомляє, що потрібно знову ввійти), doctor повідомляє, +що потрібна повторна автентифікація, і виводить точну команду +`openclaw models auth login --provider ...`, яку потрібно виконати. -Doctor також повідомляє про профілі автентифікації, які тимчасово непридатні до використання через: +Doctor також повідомляє про профілі автентифікації, які тимчасово непридатні через: -- короткі періоди cooldown (обмеження швидкості/тайм-аути/помилки автентифікації) -- довші вимкнення (помилки білінгу/кредитів) +- короткі cooldown-и (обмеження швидкості/тайм-аути/збої автентифікації) +- довші вимкнення (збої білінгу/кредитів) ### 6) Перевірка моделі hooks -Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на модель щодо -каталогу та allowlist і попереджає, якщо воно не буде дозволене або не може бути знайдене. +Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на модель за +каталогом та allowlist і попереджає, якщо її не буде розв’язано або вона не дозволена. ### 7) Відновлення образу sandbox -Коли sandboxing увімкнено, doctor перевіряє образи Docker і пропонує зібрати їх або -перейти на застарілі назви, якщо поточний образ відсутній. +Коли sandboxing увімкнено, doctor перевіряє Docker-образи та пропонує зібрати їх +або переключитися на застарілі назви, якщо поточний образ відсутній. -### 7b) Runtime-залежності bundled plugin +### 7b) Залежності runtime для вбудованих plugin -Doctor перевіряє, що runtime-залежності bundled plugin (наприклад, -runtime-пакети plugin Discord) присутні в корені інсталяції OpenClaw. -Якщо чогось бракує, doctor повідомляє про пакети й установлює їх у режимі -`openclaw doctor --fix` / `openclaw doctor --repair`. +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. -### 8) Міграції служб gateway і підказки з очищення +### 8) Міграції сервісу Gateway та підказки з очищення -Doctor виявляє застарілі служби gateway (`launchd/systemd/schtasks`) і -пропонує видалити їх та встановити службу OpenClaw з використанням поточного -порту gateway. Він також може сканувати наявність додаткових служб, схожих на gateway, і виводити підказки з очищення. -Іменовані за профілем служби OpenClaw gateway вважаються повноцінними й не -позначаються як "зайві". +Doctor виявляє застарілі сервіси gateway (launchd/systemd/schtasks) і +пропонує видалити їх та встановити сервіс OpenClaw з поточним портом gateway. +Він також може сканувати наявність додаткових сервісів, схожих на gateway, і виводити підказки з очищення. +Іменовані за профілем сервіси gateway OpenClaw вважаються першокласними й не +позначаються як "додаткові". ### 8b) Стартова міграція Matrix -Коли обліковий запис каналу Matrix має очікувану або придатну до виконання міграцію застарілого стану, -doctor (у режимі `--fix` / `--repair`) створює знімок до міграції, а потім -виконує кроки міграції за принципом best-effort: міграцію застарілого стану Matrix -та підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, а -запуск триває. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка +Коли акаунт каналу Matrix має очікувану або придатну до виконання міграцію +застарілого стану, doctor (у режимі `--fix` / `--repair`) створює знімок стану до міграції, а потім +запускає кроки міграції за принципом best-effort: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки логуються, а +запуск продовжується. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається. -### 8c) Pairing пристроїв і дрейф автентифікації +### 8c) Спарювання пристроїв і дрейф автентифікації -Doctor тепер перевіряє стан pairing пристроїв як частину звичайної перевірки стану. +Doctor тепер перевіряє стан спарювання пристроїв як частину звичайної перевірки стану. Що він повідомляє: -- очікувані запити на pairing уперше -- очікувані підвищення ролей для вже paired пристроїв -- очікувані підвищення scope для вже paired пристроїв -- відновлення невідповідностей публічного ключа, коли id пристрою все ще збігається, але - ідентичність пристрою більше не збігається зі схваленим записом -- paired-записи без активного токена для схваленої ролі -- paired-токени, чиї scope відхиляються від затвердженої базової лінії pairing +- очікувані запити на перше спарювання +- очікувані оновлення ролей для вже спарених пристроїв +- очікувані оновлення області дії для вже спарених пристроїв +- виправлення невідповідності публічного ключа, коли ID пристрою все ще збігається, але + ідентичність пристрою більше не відповідає схваленому запису +- спарені записи без активного токена для схваленої ролі +- спарені токени, області дії яких відхилилися від затвердженого базового рівня спарювання - локальні кешовані записи токенів пристрою для поточної машини, які передують - ротації токена на боці gateway або містять застарілі метадані scope + ротації токена на боці gateway або містять застарілі метадані області дії -Doctor не схвалює запити на pairing автоматично й не виконує автоматичну ротацію токенів пристрою. Натомість +Doctor не схвалює запити на спарювання автоматично і не виконує автоматичну ротацію токенів пристроїв. Натомість він виводить точні наступні кроки: -- перегляньте очікувані запити за допомогою `openclaw devices list` -- схваліть точний запит за допомогою `openclaw devices approve ` -- виконайте ротацію нового токена за допомогою `openclaw devices rotate --device --role ` -- видаліть застарілий запис і повторно схваліть його за допомогою `openclaw devices remove ` +- переглянути очікувані запити за допомогою `openclaw devices list` +- схвалити конкретний запит за допомогою `openclaw devices approve ` +- ротувати новий токен за допомогою `openclaw devices rotate --device --role ` +- видалити застарілий запис і повторно схвалити його через `openclaw devices remove ` -Це закриває типову прогалину "вже paired, але все ще отримує pairing required": -doctor тепер розрізняє pairing уперше, очікувані підвищення ролі/scope -та дрейф застарілого токена/ідентичності пристрою. +Це закриває поширену проблему "вже спарено, але все одно вимагається pairing": +doctor тепер відрізняє перше спарювання від очікуваних оновлень ролі/області дії +і від застарілого дрейфу токена/ідентичності пристрою. ### 9) Попередження безпеки Doctor виводить попередження, коли провайдер відкритий для DM без allowlist, або -коли політику налаштовано небезпечним чином. +коли політику налаштовано небезпечно. -### 10) `systemd linger` (Linux) +### 10) systemd linger (Linux) -Якщо запуск відбувається як користувацька служба systemd, doctor перевіряє, що linger увімкнено, щоб +Якщо запущено як користувацький сервіс systemd, doctor перевіряє, що lingering увімкнено, щоб gateway залишався активним після виходу з системи. -### 11) Стан робочого простору (skills, plugins і застарілі каталоги) +### 11) Стан workspace (skills, plugins і застарілі каталоги) -Doctor виводить підсумок стану робочого простору для типового agent: +Doctor виводить зведення стану workspace для agent за замовчуванням: -- **Стан Skills**: кількість доступних skills, skills із відсутніми вимогами та skills, заблокованих allowlist. -- **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору - існують поруч із поточним робочим простором. -- **Стан plugin**: кількість завантажених/вимкнених/plugin з помилками; перелічує ID plugin для всіх - помилок; повідомляє про можливості bundled plugin. -- **Попередження сумісності plugin**: позначає plugins, які мають проблеми сумісності з +- **Стан Skills**: кількість доступних, missing-requirements і allowlist-blocked skills. +- **Застарілі каталоги workspace**: попереджає, коли `~/openclaw` або інші застарілі каталоги workspace + існують поруч із поточним workspace. +- **Стан plugin**: кількість loaded/disabled/errored plugins; перелічує ID plugin для будь-яких + помилок; повідомляє про можливості bundle plugin. +- **Попередження сумісності plugin**: позначає plugins, що мають проблеми сумісності з поточним runtime. -- **Діагностика plugin**: показує всі попередження або помилки під час завантаження, які видав - реєстр plugin. +- **Діагностика plugin**: показує будь-які попередження або помилки під час завантаження, які + виводить реєстр plugin. -### 11b) Розмір bootstrap-файлів +### 11b) Розмір bootstrap-файла -Doctor перевіряє, чи bootstrap-файли робочого простору (наприклад `AGENTS.md`, -`CLAUDE.md` або інші ін’єктовані контекстні файли) наближаються до налаштованого -ліміту символів або перевищують його. Він повідомляє для кожного файлу кількість сирих та ін’єктованих символів, відсоток обрізання, -причину обрізання (`max/file` або `max/total`) і загальну кількість ін’єктованих -символів як частку від загального бюджету. Коли файли обрізаються або наближаються до -ліміту, doctor виводить поради з налаштування `agents.defaults.bootstrapMaxChars` +Doctor перевіряє, чи не наближаються bootstrap-файли workspace (наприклад `AGENTS.md`, +`CLAUDE.md` або інші вбудовані контекстні файли) до налаштованого +бюджету символів або чи не перевищують його. Він повідомляє для кожного файла співвідношення raw та injected символів, відсоток обрізання, +причину обрізання (`max/file` або `max/total`) і загальну кількість injected +символів як частку від загального бюджету. Коли файли обрізано або вони близькі до +ліміту, doctor виводить поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. ### 11c) Shell completion @@ -465,68 +448,68 @@ Doctor перевіряє, чи bootstrap-файли робочого прост Doctor перевіряє, чи встановлено tab completion для поточної оболонки (zsh, bash, fish або PowerShell): -- Якщо профіль оболонки використовує повільний динамічний шаблон completion +- Якщо профіль оболонки використовує повільний шаблон dynamic completion (`source <(openclaw completion ...)`), doctor оновлює його до швидшого - варіанту з кешованим файлом. + варіанта з кешованим файлом. - Якщо completion налаштовано в профілі, але файл кешу відсутній, - doctor автоматично перебудовує кеш. + doctor автоматично відтворює кеш. - Якщо completion взагалі не налаштовано, doctor пропонує встановити його (лише в інтерактивному режимі; пропускається з `--non-interactive`). -Виконайте `openclaw completion --write-state`, щоб вручну перебудувати кеш. +Запустіть `openclaw completion --write-state`, щоб вручну відтворити кеш. -### 12) Перевірки автентифікації gateway (локальний токен) +### 12) Перевірки автентифікації Gateway (локальний токен) -Doctor перевіряє готовність автентифікації локального токена gateway. +Doctor перевіряє готовність локальної токен-автентифікації gateway. -- Якщо режим токена потребує токен, а джерело токена відсутнє, doctor пропонує згенерувати його. +- Якщо режим токена потребує токен і джерела токена немає, doctor пропонує його згенерувати. - Якщо `gateway.auth.token` керується через SecretRef, але недоступний, doctor попереджає і не перезаписує його відкритим текстом. -- `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано токен SecretRef. +- `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано token SecretRef. -### 12b) Відновлення в режимі лише читання з урахуванням SecretRef +### 12b) Відновлення лише для читання з урахуванням SecretRef -Деякі сценарії відновлення потребують перевірки налаштованих credentials без послаблення поведінки runtime fail-fast. +Деякі сценарії відновлення потребують перевірки налаштованих credentials без послаблення fail-fast поведінки runtime. -- `openclaw doctor --fix` тепер використовує ту саму модель підсумку SecretRef лише для читання, що й команди сімейства status, для цільового відновлення конфігурації. -- Приклад: відновлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані credentials бота, якщо вони доступні. -- Якщо токен Telegram-бота налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що credential налаштовано, але недоступний, і пропускає автоматичне визначення замість аварійного завершення або помилкового повідомлення, що токен відсутній. +- `openclaw doctor --fix` тепер використовує ту саму read-only модель зведення SecretRef, що й команди сімейства status, для цільових виправлень конфігурації. +- Приклад: виправлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані credentials бота, якщо вони доступні. +- Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що credential налаштовано, але він недоступний, і пропускає автоматичне розв’язання замість аварійного завершення або хибного повідомлення, що токен відсутній. -### 13) Перевірка стану gateway + перезапуск +### 13) Перевірка стану Gateway + перезапуск -Doctor виконує перевірку стану і пропонує перезапустити gateway, якщо він виглядає -несправним. +Doctor виконує перевірку стану і пропонує перезапустити gateway, якщо той +виглядає несправним. -### 13b) Готовність пошуку в пам’яті +### 13b) Готовність memory search -Doctor перевіряє, чи готовий налаштований провайдер embedding для пошуку в пам’яті -для типового agent. Поведінка залежить від налаштованого бекенда та провайдера: +Doctor перевіряє, чи готовий налаштований провайдер embedding для memory search +для agent за замовчуванням. Поведінка залежить від налаштованого бекенда і провайдера: -- **Бекенд QMD**: перевіряє, чи бінарний файл `qmd` доступний і може запускатися. - Якщо ні, виводить підказки щодо виправлення, зокрема npm-пакет і варіант ручного шляху до бінарного файла. -- **Явно заданий локальний провайдер**: перевіряє наявність локального файла моделі або розпізнаного - URL віддаленої/завантажуваної моделі. Якщо відсутній, пропонує перейти на віддаленого провайдера. -- **Явно заданий віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи присутній API-ключ - у середовищі або сховищі автентифікації. Якщо ключ відсутній, виводить практичні підказки щодо виправлення. -- **Автоматичний провайдер**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого +- **Бекенд QMD**: перевіряє, чи доступний і чи можна запустити бінарний файл `qmd`. + Якщо ні, виводить рекомендації з виправлення, включно з npm-пакетом і варіантом ручного шляху до бінарного файла. +- **Явний локальний провайдер**: перевіряє наявність локального файла моделі або розпізнаваного + URL віддаленої/завантажуваної моделі. Якщо його немає, пропонує переключитися на віддаленого провайдера. +- **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи є API-ключ + у середовищі або в сховищі автентифікації. Якщо його немає, виводить практичні підказки з виправлення. +- **Автопровайдер**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого провайдера в порядку автоматичного вибору. -Коли результат probe gateway доступний (gateway був справний на момент -перевірки), doctor звіряє цей результат із конфігурацією, видимою CLI, і зазначає -будь-які розбіжності. +Коли доступний результат перевірки gateway (gateway був справним на момент +перевірки), doctor звіряє його результат із видимою для CLI конфігурацією та +зазначає будь-які розбіжності. -Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час виконання. +Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час runtime. ### 14) Попередження про стан каналів -Якщо gateway справний, doctor запускає probe стану каналів і повідомляє -попередження разом із запропонованими виправленнями. +Якщо gateway справний, doctor виконує перевірку стану каналів і повідомляє +попередження разом із рекомендованими виправленнями. ### 15) Аудит конфігурації supervisor + відновлення -Doctor перевіряє встановлену конфігурацію supervisor (`launchd/systemd/schtasks`) на -відсутні або застарілі типові значення (наприклад, залежності `network-online` у systemd та +Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на +відсутні або застарілі значення за замовчуванням (наприклад, залежності systemd network-online і затримку перезапуску). Коли він знаходить невідповідність, то рекомендує оновлення і може -переписати файл служби/завдання відповідно до поточних типових значень. +переписати файл сервісу/завдання відповідно до поточних значень за замовчуванням. Примітки: @@ -534,36 +517,35 @@ Doctor перевіряє встановлену конфігурацію superv - `openclaw doctor --yes` приймає типові запити на відновлення. - `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів. - `openclaw doctor --repair --force` перезаписує користувацькі конфігурації supervisor. -- Якщо автентифікація токеном потребує токен, а `gateway.auth.token` керується через SecretRef, встановлення/відновлення служби doctor перевіряє SecretRef, але не зберігає розв’язані plaintext-значення токена в метаданих середовища служби supervisor. -- Якщо автентифікація токеном потребує токен, а налаштований токен SecretRef не розв’язано, doctor блокує шлях встановлення/відновлення і надає практичні вказівки. -- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/відновлення, доки режим не буде явно встановлено. -- Для користувацьких модулів user-systemd у Linux перевірки дрейфу токена в doctor тепер охоплюють і джерела `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації служби. +- Якщо токен-автентифікація потребує токен, а `gateway.auth.token` керується через SecretRef, doctor під час встановлення/відновлення сервісу перевіряє SecretRef, але не зберігає розв’язані plaintext-значення токена в метаданих середовища сервісу supervisor. +- Якщо токен-автентифікація потребує токен, а налаштований token SecretRef не розв’язано, doctor блокує шлях встановлення/відновлення і надає практичні рекомендації. +- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не встановлено, doctor блокує встановлення/відновлення, доки режим не буде явно задано. +- Для user-systemd unit у Linux перевірки дрейфу токена в doctor тепер включають і джерела `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації сервісу. - Ви завжди можете примусово виконати повний перезапис через `openclaw gateway install --force`. -### 16) Діагностика середовища виконання gateway + порту +### 16) Діагностика runtime і порту Gateway -Doctor перевіряє середовище виконання служби (PID, останній статус виходу) і попереджає, якщо -службу встановлено, але вона фактично не запущена. Він також перевіряє конфлікти портів +Doctor перевіряє runtime сервісу (PID, останній статус завершення) і попереджає, коли +сервіс встановлено, але фактично не запущено. Він також перевіряє конфлікти портів на порту gateway (типово `18789`) і повідомляє ймовірні причини (gateway уже запущено, SSH-тунель). -### 17) Рекомендовані практики для середовища виконання gateway +### 17) Найкращі практики runtime Gateway -Doctor попереджає, коли служба gateway працює на Bun або на шляху Node, керованому менеджером версій -(`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, -а шляхи менеджера версій можуть ламатися після оновлень, оскільки служба не -завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системну інсталяцію Node, якщо +Doctor попереджає, коли сервіс gateway працює на Bun або через шлях Node, керований менеджером версій +(`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp і Telegram потребують Node, +а шляхи менеджерів версій можуть ламатися після оновлень, оскільки сервіс не +завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системну інсталяцію Node, коли вона доступна (Homebrew/apt/choco). ### 18) Запис конфігурації + метадані wizard -Doctor зберігає будь-які зміни конфігурації та проставляє метадані wizard, щоб зафіксувати -запуск doctor. +Doctor зберігає будь-які зміни конфігурації та проставляє метадані wizard, щоб зафіксувати запуск doctor. -### 19) Поради щодо робочого простору (резервне копіювання + система пам’яті) +### 19) Поради щодо workspace (резервне копіювання + система пам’яті) -Doctor пропонує систему пам’яті робочого простору, якщо вона відсутня, і виводить пораду щодо резервного копіювання, -якщо робочий простір ще не перебуває під git. +Doctor пропонує систему пам’яті workspace, якщо її немає, і виводить пораду щодо резервного копіювання, +якщо workspace ще не перебуває під git. -Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб ознайомитися з повним посібником щодо -структури робочого простору та резервного копіювання через git (рекомендовано приватний GitHub або GitLab). +Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб отримати повний посібник зі +структури workspace та резервного копіювання через git (рекомендовано приватний GitHub або GitLab). diff --git a/docs/uk/plugins/sdk-setup.md b/docs/uk/plugins/sdk-setup.md index a83142d32..e92a371fe 100644 --- a/docs/uk/plugins/sdk-setup.md +++ b/docs/uk/plugins/sdk-setup.md @@ -1,34 +1,34 @@ --- read_when: - Ви додаєте майстер налаштування до Plugin - - Вам потрібно зрозуміти різницю між setup-entry.ts і index.ts - - Ви визначаєте схеми конфігурації Plugin або метадані openclaw у package.json + - Вам потрібно зрозуміти різницю між `setup-entry.ts` і `index.ts` + - Ви визначаєте схеми конфігурації Plugin або метадані `openclaw` у `package.json` sidebarTitle: Setup and Config -summary: Майстри налаштування, setup-entry.ts, схеми конфігурації та метадані package.json -title: Налаштування Plugin та конфігурація +summary: Майстри налаштування, `setup-entry.ts`, схеми конфігурації та метадані `package.json` +title: Налаштування Plugin і конфігурація x-i18n: - generated_at: "2026-04-15T16:36:55Z" + generated_at: "2026-04-20T16:49:59Z" model: gpt-5.4 provider: openai - source_hash: ddf28e25e381a4a38ac478e531586f59612e1a278732597375f87c2eeefc521b + source_hash: 5de51b55c04b4f05947bc2d4de9c34e24a26e4ca8b3ff9b1711288a8e5b63273 source_path: plugins/sdk-setup.md workflow: 15 --- -# Налаштування Plugin та конфігурація +# Налаштування Plugin і конфігурація -Довідка щодо пакування plugin (`package.json` metadata), маніфестів +Довідник щодо пакування plugin (`package.json` metadata), маніфестів (`openclaw.plugin.json`), записів налаштування та схем конфігурації. - **Шукаєте покроковий приклад?** Практичні посібники охоплюють пакування в контексті: + **Шукаєте покрокову інструкцію?** Практичні посібники розглядають пакування в контексті: [Channel Plugins](/uk/plugins/sdk-channel-plugins#step-1-package-and-manifest) і [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-1-package-and-manifest). -## Метадані пакунка +## Метадані пакета -Ваш `package.json` має містити поле `openclaw`, яке повідомляє системі plugin, що саме +Ваш `package.json` має містити поле `openclaw`, яке повідомляє системі plugin, що надає ваш plugin: **Channel plugin:** @@ -50,7 +50,7 @@ x-i18n: } ``` -**Provider plugin / базовий шаблон публікації ClawHub:** +**Provider plugin / базовий варіант для публікації ClawHub:** ```json openclaw-clawhub-package.json { @@ -72,46 +72,46 @@ x-i18n: ``` Якщо ви публікуєте plugin зовнішньо в ClawHub, поля `compat` і `build` -є обов’язковими. Канонічні фрагменти для публікації знаходяться в +є обов’язковими. Канонічні фрагменти для публікації містяться в `docs/snippets/plugin-publish/`. ### Поля `openclaw` -| Поле | Тип | Опис | -| ------------ | ---------- | ------------------------------------------------------------------------------------------------------ | -| `extensions` | `string[]` | Файли точок входу (відносно кореня пакунка) | -| `setupEntry` | `string` | Полегшена точка входу лише для налаштування (необов’язково) | -| `channel` | `object` | Метадані каталогу channel для налаштування, вибору, швидкого старту та поверхонь статусу | -| `providers` | `string[]` | Ідентифікатори provider, зареєстрованих цим plugin | -| `install` | `object` | Підказки встановлення: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `allowInvalidConfigRecovery` | -| `startup` | `object` | Прапори поведінки під час запуску | +| Поле | Тип | Опис | +| ------------ | ---------- | -------------------------------------------------------------------------------------------------------------- | +| `extensions` | `string[]` | Файли точок входу (відносно кореня пакета) | +| `setupEntry` | `string` | Легка точка входу лише для налаштування (необов’язково) | +| `channel` | `object` | Метадані каталогу channel для налаштування, вибору, quickstart і поверхонь статусу | +| `providers` | `string[]` | Ідентифікатори provider, які реєструє цей plugin | +| `install` | `object` | Підказки для встановлення: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `allowInvalidConfigRecovery` | +| `startup` | `object` | Прапорці поведінки під час запуску | ### `openclaw.channel` -`openclaw.channel` — це недорогі метадані пакунка для виявлення channel і поверхонь -налаштування до завантаження runtime. +`openclaw.channel` — це недорогі метадані пакета для виявлення channel і +поверхонь налаштування до завантаження runtime. -| Поле | Тип | Що це означає | +| Поле | Тип | Що воно означає | | -------------------------------------- | ---------- | ---------------------------------------------------------------------------- | | `id` | `string` | Канонічний ідентифікатор channel. | | `label` | `string` | Основна мітка channel. | -| `selectionLabel` | `string` | Мітка у виборі/налаштуванні, якщо вона має відрізнятися від `label`. | -| `detailLabel` | `string` | Додаткова детальна мітка для багатших каталогів channel і поверхонь статусу. | -| `docsPath` | `string` | Шлях до документації для посилань у налаштуванні та виборі. | +| `selectionLabel` | `string` | Мітка для picker/налаштування, якщо вона має відрізнятися від `label`. | +| `detailLabel` | `string` | Вторинна мітка деталей для багатших каталогів channel і поверхонь статусу. | +| `docsPath` | `string` | Шлях до документації для посилань налаштування та вибору. | | `docsLabel` | `string` | Перевизначення мітки для посилань на документацію, якщо вона має відрізнятися від ідентифікатора channel. | | `blurb` | `string` | Короткий опис для онбордингу/каталогу. | | `order` | `number` | Порядок сортування в каталогах channel. | -| `aliases` | `string[]` | Додаткові псевдоніми для пошуку під час вибору channel. | +| `aliases` | `string[]` | Додаткові псевдоніми пошуку для вибору channel. | | `preferOver` | `string[]` | Ідентифікатори plugin/channel з нижчим пріоритетом, які цей channel має випереджати. | -| `systemImage` | `string` | Необов’язкова назва піктограми/system-image для каталогів UI channel. | +| `systemImage` | `string` | Необов’язкова назва icon/system-image для каталогів UI channel. | | `selectionDocsPrefix` | `string` | Текст-префікс перед посиланнями на документацію в поверхнях вибору. | -| `selectionDocsOmitLabel` | `boolean` | Показувати шлях документації безпосередньо замість підписаного посилання в тексті вибору. | +| `selectionDocsOmitLabel` | `boolean` | Показувати шлях до документації безпосередньо замість іменованого посилання в тексті вибору. | | `selectionExtras` | `string[]` | Додаткові короткі рядки, що додаються в тексті вибору. | -| `markdownCapable` | `boolean` | Позначає channel як сумісний з markdown для рішень щодо вихідного форматування. | +| `markdownCapable` | `boolean` | Позначає channel як сумісний із markdown для рішень щодо вихідного форматування. | | `exposure` | `object` | Керування видимістю channel для налаштування, списків налаштованих елементів і поверхонь документації. | | `quickstartAllowFrom` | `boolean` | Додає цей channel до стандартного потоку налаштування quickstart `allowFrom`. | -| `forceAccountBinding` | `boolean` | Вимагає явної прив’язки облікового запису, навіть якщо існує лише один обліковий запис. | -| `preferSessionLookupForAnnounceTarget` | `boolean` | Віддавати перевагу пошуку сесії під час визначення цілей announce для цього channel. | +| `forceAccountBinding` | `boolean` | Вимагає явного прив’язування облікового запису, навіть якщо існує лише один обліковий запис. | +| `preferSessionLookupForAnnounceTarget` | `boolean` | Надає перевагу пошуку session під час визначення цілей announce для цього channel. | Приклад: @@ -145,37 +145,37 @@ x-i18n: `exposure` підтримує: -- `configured`: включати channel у поверхні списків налаштованих елементів/статусів -- `setup`: включати channel в інтерактивні засоби вибору налаштування/конфігурації -- `docs`: позначати channel як публічно видимий у поверхнях документації/навігації +- `configured`: включати channel до поверхонь списків у стилі configured/status +- `setup`: включати channel до інтерактивних picker налаштування/конфігурації +- `docs`: позначати channel як публічно доступний на поверхнях документації/навігації -`showConfigured` і `showInSetup` залишаються підтримуваними як застарілі псевдоніми. Рекомендовано +`showConfigured` і `showInSetup` як і раніше підтримуються як застарілі псевдоніми. Рекомендовано використовувати `exposure`. ### `openclaw.install` -`openclaw.install` — це метадані пакунка, а не метадані маніфесту. +`openclaw.install` — це метадані пакета, а не метадані маніфесту. -| Поле | Тип | Що це означає | -| ---------------------------- | -------------------- | ------------------------------------------------------------------------------- | -| `npmSpec` | `string` | Канонічний npm spec для потоків встановлення/оновлення. | -| `localPath` | `string` | Локальний шлях встановлення для розробки або вбудованого пакета. | -| `defaultChoice` | `"npm"` \| `"local"` | Бажане джерело встановлення, коли доступні обидва варіанти. | -| `minHostVersion` | `string` | Мінімально підтримувана версія OpenClaw у форматі `>=x.y.z`. | -| `allowInvalidConfigRecovery` | `boolean` | Дозволяє потокам перевстановлення вбудованого plugin відновлюватися після окремих збоїв через застарілу конфігурацію. | +| Поле | Тип | Що воно означає | +| ---------------------------- | -------------------- | ------------------------------------------------------------------------------ | +| `npmSpec` | `string` | Канонічна npm-специфікація для потоків встановлення/оновлення. | +| `localPath` | `string` | Локальний шлях для розробки або вбудованого встановлення. | +| `defaultChoice` | `"npm"` \| `"local"` | Бажане джерело встановлення, коли доступні обидва варіанти. | +| `minHostVersion` | `string` | Мінімально підтримувана версія OpenClaw у форматі `>=x.y.z`. | +| `allowInvalidConfigRecovery` | `boolean` | Дозволяє потокам перевстановлення вбудованих plugin відновлюватися після певних збоїв через застарілу конфігурацію. | Якщо задано `minHostVersion`, і встановлення, і завантаження реєстру маніфестів -застосовують цю перевірку. Старіші хости пропускають plugin; некоректні рядки версій відхиляються. +застосовують цю вимогу. Старіші host пропускають plugin; недійсні рядки версій відхиляються. -`allowInvalidConfigRecovery` не є загальним обходом для зламаних конфігурацій. Воно -призначене лише для вузького сценарію відновлення вбудованого plugin, щоб перевстановлення/налаштування -могли виправити відомі залишки після оновлення, як-от відсутній шлях до вбудованого plugin або застарілий запис `channels.` -для цього самого plugin. Якщо конфігурація зламана з інших причин, встановлення -усе одно завершується з відмовою і пропонує оператору виконати `openclaw doctor --fix`. +`allowInvalidConfigRecovery` — це не загальний обхід для зламаних конфігурацій. Він призначений +лише для вузького сценарію відновлення вбудованих plugin, щоб перевстановлення/налаштування могли виправити +відомі залишки після оновлення, наприклад відсутній шлях до вбудованого plugin або застарілий запис `channels.` +для цього самого plugin. Якщо конфігурація зламана з не пов’язаних причин, встановлення +усе одно завершується без поблажок і повідомляє оператору виконати `openclaw doctor --fix`. ### Відкладене повне завантаження -Channel plugins можуть увімкнути відкладене завантаження так: +Channel plugins можуть увімкнути відкладене завантаження за допомогою: ```json { @@ -189,26 +189,26 @@ Channel plugins можуть увімкнути відкладене заван } ``` -Коли це ввімкнено, OpenClaw завантажує лише `setupEntry` під час фази запуску до -початку прослуховування, навіть для вже налаштованих channel. Повна точка входу завантажується після того, -як Gateway починає прослуховування. +Коли це увімкнено, OpenClaw завантажує лише `setupEntry` під час фази запуску до listen, +навіть для вже налаштованих channel. Повна точка входу завантажується після того, як Gateway +починає прослуховування. - Увімкнюйте відкладене завантаження лише тоді, коли ваш `setupEntry` реєструє все, - що Gateway потрібно до початку прослуховування (реєстрація channel, HTTP-маршрути, - методи Gateway). Якщо повна точка входу володіє потрібними можливостями запуску, залиште + Вмикайте відкладене завантаження лише тоді, коли ваш `setupEntry` реєструє все, що + потрібно Gateway до початку прослуховування (реєстрація channel, HTTP-маршрути, + методи Gateway). Якщо повна точка входу володіє необхідними можливостями запуску, залишайте поведінку за замовчуванням. -Якщо ваш запис налаштування/повний запис реєструє методи Gateway RPC, використовуйте для них -префікс, специфічний для plugin. Зарезервовані простори імен основного адміністратора (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються під керуванням core і завжди зіставляються -з `operator.admin`. +Якщо ваш запис налаштування/повний запис реєструє методи RPC Gateway, залишайте їх на +префіксі, специфічному для plugin. Зарезервовані простори імен core admin (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) залишаються у власності core і завжди визначаються +як `operator.admin`. ## Маніфест Plugin -Кожен native plugin має постачати `openclaw.plugin.json` у корені пакунка. -OpenClaw використовує це для перевірки конфігурації без виконання коду plugin. +Кожен нативний plugin має постачатися з `openclaw.plugin.json` у корені пакета. +OpenClaw використовує це для валідації конфігурації без виконання коду plugin. ```json { @@ -243,7 +243,7 @@ OpenClaw використовує це для перевірки конфігу } ``` -Навіть plugins без конфігурації мають постачати схему. Порожня схема є валідною: +Навіть plugins без конфігурації мають постачатися зі схемою. Порожня схема є коректною: ```json { @@ -255,23 +255,23 @@ OpenClaw використовує це для перевірки конфігу } ``` -Див. [Plugin Manifest](/uk/plugins/manifest) для повної довідки щодо схеми. +Див. [Plugin Manifest](/uk/plugins/manifest), щоб ознайомитися з повним довідником щодо схеми. -## Публікація в ClawHub +## Публікація ClawHub -Для пакунків plugin використовуйте команду ClawHub, специфічну для пакунків: +Для пакетів plugin використовуйте команду ClawHub, специфічну для пакета: ```bash clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -Застарілий псевдонім публікації лише для Skills призначений для skills. Пакунки plugin +Застарілий псевдонім публікації лише для skill призначений для skills. Пакети plugin завжди мають використовувати `clawhub package publish`. -## Точка входу налаштування +## Запис налаштування -Файл `setup-entry.ts` — це полегшена альтернатива `index.ts`, яку +Файл `setup-entry.ts` — це легка альтернатива `index.ts`, яку OpenClaw завантажує, коли йому потрібні лише поверхні налаштування (онбординг, відновлення конфігурації, перевірка вимкненого channel). @@ -283,81 +283,82 @@ import { myChannelPlugin } from "./src/channel.js"; export default defineSetupPluginEntry(myChannelPlugin); ``` -Це дає змогу уникнути завантаження важкого runtime-коду (криптографічних бібліотек, реєстрацій CLI, -фонових сервісів) під час потоків налаштування. +Це дозволяє уникнути завантаження важкого runtime-коду (криптобібліотеки, реєстрації CLI, +фонові служби) під час потоків налаштування. -Вбудовані workspace channel, які тримають безпечні для налаштування експорти в sidecar-модулях, можуть +Вбудовані workspace channel, які зберігають безпечні для налаштування експорти в sidecar-модулях, можуть використовувати `defineBundledChannelSetupEntry(...)` з `openclaw/plugin-sdk/channel-entry-contract` замість -`defineSetupPluginEntry(...)`. Цей вбудований контракт також підтримує необов’язковий експорт -`runtime`, щоб підключення runtime під час налаштування залишалося полегшеним і явним. +`defineSetupPluginEntry(...)`. Цей контракт для вбудованих елементів також підтримує необов’язковий +експорт `runtime`, щоб налаштування runtime під час етапу налаштування залишалося легким і явним. **Коли OpenClaw використовує `setupEntry` замість повної точки входу:** -- Channel вимкнено, але потрібні поверхні налаштування/онбордингу -- Channel увімкнено, але не налаштовано +- Channel вимкнений, але потребує поверхонь налаштування/онбордингу +- Channel увімкнений, але не налаштований - Увімкнено відкладене завантаження (`deferConfiguredChannelFullLoadUntilAfterListen`) **Що має реєструвати `setupEntry`:** - Об’єкт channel plugin (через `defineSetupPluginEntry`) -- Будь-які HTTP-маршрути, потрібні до початку прослуховування Gateway +- Будь-які HTTP-маршрути, потрібні до початку listen Gateway - Будь-які методи Gateway, потрібні під час запуску -Ці методи Gateway для запуску все одно мають уникати зарезервованих +Ці методи Gateway для запуску однаково мають уникати зарезервованих просторів імен core admin, таких як `config.*` або `update.*`. **Що НЕ має містити `setupEntry`:** - Реєстрації CLI -- Фонові сервіси -- Важкі імпорти runtime (crypto, SDKs) +- Фонові служби +- Важкі імпорти runtime (crypto, SDK) - Методи Gateway, потрібні лише після запуску ### Вузькі імпорти допоміжних засобів налаштування -Для гарячих шляхів лише для налаштування надавайте перевагу вузьким швам допоміжних засобів налаштування замість ширшого -парасолькового `plugin-sdk/setup`, коли вам потрібна лише частина поверхні налаштування: +Для гарячих шляхів лише для налаштування віддавайте перевагу вузьким швам допоміжних засобів налаштування замість ширшого +пакета `plugin-sdk/setup`, якщо вам потрібна лише частина поверхні налаштування: -| Шлях імпорту | Для чого використовувати | Ключові експорти | -| --------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/setup-runtime` | допоміжні засоби runtime під час налаштування, які лишаються доступними в `setupEntry` / відкладеному запуску channel | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | -| `plugin-sdk/setup-adapter-runtime` | адаптери налаштування облікових записів з урахуванням середовища | `createEnvPatchedAccountSetupAdapter` | -| `plugin-sdk/setup-tools` | допоміжні засоби CLI/архіву/документації для налаштування та встановлення | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | +| Шлях імпорту | Використовуйте для | Ключові експорти | +| --------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `plugin-sdk/setup-runtime` | допоміжні засоби runtime під час налаштування, які залишаються доступними в `setupEntry` / відкладеному запуску channel | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | +| `plugin-sdk/setup-adapter-runtime` | адаптери налаштування облікових записів з урахуванням середовища | `createEnvPatchedAccountSetupAdapter` | +| `plugin-sdk/setup-tools` | допоміжні засоби CLI/архіву/документації для налаштування/встановлення | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | Використовуйте ширший шов `plugin-sdk/setup`, коли вам потрібен повний спільний -набір інструментів для налаштування, включно з допоміжними засобами patch для конфігурації, такими як +набір засобів налаштування, включно з допоміжними засобами patch конфігурації, такими як `moveSingleAccountChannelSectionToDefaultAccount(...)`. Адаптери patch для налаштування залишаються безпечними для гарячого шляху під час імпорту. Їхній вбудований -ледачий пошук поверхні контракту для просування одного облікового запису є відкладеним, тому імпорт -`plugin-sdk/setup-runtime` не завантажує завчасно виявлення поверхні вбудованого контракту до фактичного використання адаптера. +пошук поверхні контракту для просування одного облікового запису є лінивим, тому імпорт +`plugin-sdk/setup-runtime` не завантажує завчасно виявлення поверхні вбудованого контракту +до моменту фактичного використання адаптера. -### Просування одного облікового запису, що належить channel +### Просування одного облікового запису на боці channel -Коли channel оновлюється з верхньорівневої конфігурації одного облікового запису до -`channels..accounts.*`, типова спільна поведінка полягає в переміщенні значень, -що належать області облікового запису, до `accounts.default`. +Коли channel оновлюється з конфігурації верхнього рівня для одного облікового запису до +`channels..accounts.*`, типова спільна поведінка — перемістити значення на рівні облікового запису, що просуваються, +до `accounts.default`. Вбудовані channels можуть звузити або перевизначити це просування через свою поверхню контракту налаштування: -- `singleAccountKeysToMove`: додаткові верхньорівневі ключі, які потрібно перемістити до +- `singleAccountKeysToMove`: додаткові ключі верхнього рівня, які слід перемістити до просунутого облікового запису - `namedAccountPromotionKeys`: якщо іменовані облікові записи вже існують, лише ці ключі переміщуються до просунутого облікового запису; спільні ключі policy/delivery залишаються в корені channel -- `resolveSingleAccountPromotionTarget(...)`: вибір наявного облікового запису, який - отримає просунуті значення +- `resolveSingleAccountPromotionTarget(...)`: вибір існуючого облікового запису, + який отримає просунуті значення -Matrix — поточний вбудований приклад. Якщо вже існує рівно один іменований обліковий запис Matrix, -або якщо `defaultAccount` вказує на наявний неканонічний ключ -на кшталт `Ops`, просування зберігає цей обліковий запис замість створення нового -запису `accounts.default`. +Поточний вбудований приклад — Matrix. Якщо вже існує рівно один іменований обліковий запис Matrix, +або якщо `defaultAccount` вказує на наявний неканонічний ключ, +такий як `Ops`, просування зберігає цей обліковий запис замість створення нового запису +`accounts.default`. ## Схема конфігурації -Конфігурація plugin проходить перевірку за JSON Schema у вашому маніфесті. Користувачі +Конфігурація Plugin перевіряється за JSON Schema у вашому маніфесті. Користувачі налаштовують plugins через: ```json5 @@ -446,17 +447,17 @@ const setupWizard: ChannelSetupWizard = { Тип `ChannelSetupWizard` підтримує `credentials`, `textInputs`, `dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize` тощо. -Повні приклади дивіться у вбудованих пакунках plugin (наприклад, у plugin Discord `src/channel.setup.ts`). +Повні приклади дивіться у вбудованих пакетах plugin (наприклад, plugin Discord `src/channel.setup.ts`). -Для запитів allowlist у DM, яким потрібен лише стандартний -потік `note -> prompt -> parse -> merge -> patch`, надавайте перевагу спільним допоміжним засобам налаштування +Для запитів списку дозволених DM, яким потрібен лише стандартний +потік `note -> prompt -> parse -> merge -> patch`, віддавайте перевагу спільним допоміжним засобам налаштування з `openclaw/plugin-sdk/setup`: `createPromptParsedAllowFromForAccount(...)`, `createTopLevelChannelParsedAllowFromPrompt(...)` і `createNestedChannelParsedAllowFromPrompt(...)`. -Для блоків статусу налаштування channel, які відрізняються лише мітками, оцінками та необов’язковими -додатковими рядками, надавайте перевагу `createStandardChannelSetupStatus(...)` з -`openclaw/plugin-sdk/setup` замість ручного створення того самого об’єкта `status` у +Для блоків статусу налаштування channel, які відрізняються лише мітками, оцінками й необов’язковими +додатковими рядками, віддавайте перевагу `createStandardChannelSetupStatus(...)` з +`openclaw/plugin-sdk/setup` замість ручного створення однакового об’єкта `status` у кожному plugin. Для необов’язкових поверхонь налаштування, які мають з’являтися лише в певних контекстах, використовуйте @@ -471,34 +472,34 @@ const setupSurface = createOptionalChannelSetupSurface({ npmSpec: "@myorg/openclaw-my-channel", docsPath: "/channels/my-channel", }); -// Returns { setupAdapter, setupWizard } +// Повертає { setupAdapter, setupWizard } ``` -`plugin-sdk/channel-setup` також надає низькорівневі -конструктори `createOptionalChannelSetupAdapter(...)` і +`plugin-sdk/channel-setup` також надає низькорівневіші конструктори +`createOptionalChannelSetupAdapter(...)` і `createOptionalChannelSetupWizard(...)`, коли вам потрібна лише одна половина -цієї необов’язкової поверхні встановлення. +цієї поверхні необов’язкового встановлення. -Згенеровані необов’язкові adapter/wizard завершуються з відмовою для реальних записів конфігурації. Вони +Згенеровані необов’язкові адаптер/майстер завершуються без поблажок під час реальних записів конфігурації. Вони повторно використовують одне повідомлення про обов’язковість встановлення в `validateInput`, -`applyAccountConfig` і `finalize`, а також додають посилання на документацію, якщо задано `docsPath`. +`applyAccountConfig` і `finalize`, а також додають посилання на документацію, коли задано `docsPath`. -Для UI налаштування, що спираються на двійкові файли, надавайте перевагу спільним делегованим допоміжним засобам замість -копіювання однакового glue-коду для binary/status у кожен channel: +Для UI налаштування, що працюють через бінарні файли, віддавайте перевагу спільним делегованим допоміжним засобам замість +копіювання однакової логіки бінарних файлів/статусу в кожен channel: -- `createDetectedBinaryStatus(...)` для блоків статусу, що відрізняються лише мітками, - підказками, оцінками та виявленням двійкового файла -- `createCliPathTextInput(...)` для текстових полів, прив’язаних до шляху +- `createDetectedBinaryStatus(...)` для блоків статусу, які відрізняються лише мітками, + підказками, оцінками та виявленням бінарного файла +- `createCliPathTextInput(...)` для текстових полів на основі шляху - `createDelegatedSetupWizardStatusResolvers(...)`, `createDelegatedPrepare(...)`, `createDelegatedFinalize(...)` і - `createDelegatedResolveConfigured(...)`, коли `setupEntry` має ледачо пересилати до + `createDelegatedResolveConfigured(...)`, коли `setupEntry` має ліниво перенаправляти до важчого повного майстра -- `createDelegatedTextInputShouldPrompt(...)`, коли `setupEntry` потрібно лише +- `createDelegatedTextInputShouldPrompt(...)`, коли `setupEntry` має лише делегувати рішення `textInputs[*].shouldPrompt` ## Публікація та встановлення -**Зовнішні plugins:** публікуйте в [ClawHub](/uk/tools/clawhub) або npm, а потім встановлюйте: +**Зовнішні plugins:** опублікуйте в [ClawHub](/uk/tools/clawhub) або npm, а потім встановіть: ```bash openclaw plugins install @myorg/openclaw-my-plugin @@ -508,11 +509,11 @@ OpenClaw спочатку пробує ClawHub і автоматично пер явно примусово використати ClawHub: ```bash -openclaw plugins install clawhub:@myorg/openclaw-my-plugin # лише ClawHub +openclaw plugins install clawhub:@myorg/openclaw-my-plugin # Лише ClawHub ``` -Відповідного перевизначення `npm:` не існує. Використовуйте звичайний npm package spec, коли -потрібен шлях npm після fallback із ClawHub: +Відповідного перевизначення `npm:` немає. Використовуйте звичайну специфікацію пакета npm, коли +хочете шлях npm після резервного переходу з ClawHub: ```bash openclaw plugins install @myorg/openclaw-my-plugin @@ -528,13 +529,19 @@ openclaw plugins install ``` - Для встановлень із npm `openclaw plugins install` виконує - `npm install --ignore-scripts` (без lifecycle scripts). Зберігайте дерева залежностей plugin - чистими JS/TS і уникайте пакунків, які потребують збірки через `postinstall`. + Для встановлень із джерелом npm `openclaw plugins install` виконує + `npm install --ignore-scripts` (без lifecycle-скриптів). Зберігайте дерева залежностей plugin + чистими JS/TS і уникайте пакетів, які потребують збірок `postinstall`. +Вбудовані plugins, що належать OpenClaw, — єдиний виняток для відновлення під час запуску: коли +пакетне встановлення бачить один із них увімкненим через конфігурацію plugin, застарілу конфігурацію channel або +його вбудований маніфест із увімкненням за замовчуванням, запуск установлює відсутні +залежності runtime цього plugin перед імпортом. Сторонні plugins не повинні покладатися на встановлення під час запуску; +продовжуйте використовувати явний інсталятор plugin. + ## Пов’язане - [SDK Entry Points](/uk/plugins/sdk-entrypoints) -- `definePluginEntry` і `defineChannelPluginEntry` -- [Plugin Manifest](/uk/plugins/manifest) -- повна довідка щодо схеми маніфесту +- [Plugin Manifest](/uk/plugins/manifest) -- повний довідник щодо схеми маніфесту - [Building Plugins](/uk/plugins/building-plugins) -- покроковий посібник для початку роботи diff --git a/docs/uk/tools/plugin.md b/docs/uk/tools/plugin.md index d9529415e..a0253cbb5 100644 --- a/docs/uk/tools/plugin.md +++ b/docs/uk/tools/plugin.md @@ -1,32 +1,32 @@ --- read_when: - - Установлення або налаштування плагінів + - Встановлення або налаштування плагінів - Розуміння правил виявлення та завантаження плагінів - - Робота з пакетами плагінів, сумісними з Codex/Claude + - Робота з сумісними з Codex/Claude наборами плагінів sidebarTitle: Install and Configure -summary: Установлення, налаштування та керування плагінами OpenClaw +summary: Встановлюйте, налаштовуйте та керуйте плагінами OpenClaw title: Плагіни x-i18n: - generated_at: "2026-04-06T00:53:45Z" + generated_at: "2026-04-20T16:49:55Z" model: gpt-5.4 provider: openai - source_hash: 9e2472a3023f3c1c6ee05b0cdc228f6b713cc226a08695b327de8a3ad6973c83 + source_hash: a34995fe8a27b7c96fb2abd9ef55bea38ea7ba2ff4e867977683e09f799e9e8f source_path: tools/plugin.md workflow: 15 --- # Плагіни -Плагіни розширюють OpenClaw новими можливостями: канали, провайдери моделей, -інструменти, Skills, мовлення, транскрибування в реальному часі, голос у реальному часі, -розуміння медіа, генерація зображень, генерація відео, отримання даних із вебу, вебпошук -тощо. Деякі плагіни є **core** (постачаються з OpenClaw), інші — -**external** (публікуються спільнотою на npm). +Плагіни розширюють OpenClaw новими можливостями: канали, постачальники моделей, +інструменти, Skills, мовлення, транскрипція в реальному часі, голос у реальному часі, +розуміння медіа, генерація зображень, генерація відео, отримання даних з вебу, вебпошук +та інше. Деякі плагіни є **core** (постачаються разом з OpenClaw), інші +є **external** (публікуються спільнотою в npm). -## Швидкий старт +## Швидкий початок - + ```bash openclaw plugins list ``` @@ -54,7 +54,7 @@ x-i18n: -Якщо ви надаєте перевагу керуванню безпосередньо в чаті, увімкніть `commands.plugins: true` і використовуйте: +Якщо ви віддаєте перевагу керуванню безпосередньо в чаті, увімкніть `commands.plugins: true` і використовуйте: ```text /plugin install clawhub:@openclaw/voice-call @@ -62,46 +62,52 @@ x-i18n: /plugin enable voice-call ``` -Шлях установлення використовує той самий механізм розв’язання, що й CLI: локальний -шлях/архів, явний `clawhub:` або специфікація пакета без префікса -(спочатку ClawHub, потім запасний варіант npm). +Шлях установлення використовує той самий механізм визначення, що й CLI: локальний +шлях/архів, явний `clawhub:` або звичайна специфікація пакета (спочатку ClawHub, потім резервний варіант npm). -Якщо конфігурація недійсна, установлення зазвичай безпечно завершується помилкою і вказує на -`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях +Якщо конфігурація недійсна, інсталяція зазвичай завершується без виконання змін і вказує вам на +`openclaw doctor --fix`. Єдиний виняток для відновлення — це вузький шлях перевстановлення вбудованого плагіна для плагінів, які підтримують `openclaw.install.allowInvalidConfigRecovery`. +Пакетні інсталяції OpenClaw не встановлюють завчасно все дерево залежностей середовища виконання +для кожного вбудованого плагіна. Коли вбудований плагін, що належить OpenClaw, активний через +конфігурацію плагінів, застарілу конфігурацію каналу або маніфест, увімкнений за замовчуванням, +під час запуску відновлюються лише оголошені залежності середовища виконання +цього плагіна перед його імпортом. External плагіни та власні шляхи завантаження +усе ще потрібно встановлювати через `openclaw plugins install`. + ## Типи плагінів OpenClaw розпізнає два формати плагінів: | Формат | Як це працює | Приклади | | ---------- | ---------------------------------------------------------------- | ------------------------------------------------------ | -| **Native** | `openclaw.plugin.json` + runtime-модуль; виконується в процесі | Офіційні плагіни, пакети npm від спільноти | -| **Bundle** | Макет, сумісний із Codex/Claude/Cursor; відображається на можливості OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | +| **Native** | `openclaw.plugin.json` + модуль середовища виконання; виконується в межах процесу | Офіційні плагіни, пакети npm від спільноти | +| **Bundle** | Макет, сумісний з Codex/Claude/Cursor; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | -Обидва відображаються в `openclaw plugins list`. Докладніше про пакети див. в [Пакети плагінів](/uk/plugins/bundles). +Обидва відображаються в `openclaw plugins list`. Докладніше про набори дивіться в [Набори плагінів](/uk/plugins/bundles). -Якщо ви пишете native-плагін, почніть із [Створення плагінів](/uk/plugins/building-plugins) -та [Огляду Plugin SDK](/uk/plugins/sdk-overview). +Якщо ви пишете Native плагін, почніть із [Створення плагінів](/uk/plugins/building-plugins) +та [Огляд Plugin SDK](/uk/plugins/sdk-overview). ## Офіційні плагіни ### Доступні для встановлення (npm) -| Плагін | Пакет | Документація | -| --------------- | --------------------- | ----------------------------------- | -| Matrix | `@openclaw/matrix` | [Matrix](/uk/channels/matrix) | -| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/uk/channels/msteams) | -| Nostr | `@openclaw/nostr` | [Nostr](/uk/channels/nostr) | -| Voice Call | `@openclaw/voice-call` | [Voice Call](/uk/plugins/voice-call) | -| Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) | -| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) | +| Плагін | Пакет | Документація | +| --------------- | --------------------- | ------------------------------------ | +| Matrix | `@openclaw/matrix` | [Matrix](/uk/channels/matrix) | +| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/uk/channels/msteams) | +| Nostr | `@openclaw/nostr` | [Nostr](/uk/channels/nostr) | +| Voice Call | `@openclaw/voice-call` | [Voice Call](/uk/plugins/voice-call) | +| Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) | +| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) | -### Core (постачаються з OpenClaw) +### Core (постачаються разом з OpenClaw) - + `anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`, `huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`, `moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`, @@ -110,16 +116,16 @@ OpenClaw розпізнає два формати плагінів: - - `memory-core` — вбудований пошук у пам’яті (за замовчуванням через `plugins.slots.memory`) - - `memory-lancedb` — довготривала пам’ять з автоматичним пригадуванням/збереженням, що встановлюється за потреби (установіть `plugins.slots.memory = "memory-lancedb"`) + - `memory-core` — вбудований пошук у пам’яті (типово через `plugins.slots.memory`) + - `memory-lancedb` — довготривала пам’ять із встановленням на вимогу з автоматичним відновленням/захопленням (установіть `plugins.slots.memory = "memory-lancedb"`) - + `elevenlabs`, `microsoft` - - `browser` — вбудований плагін браузера для інструмента браузера, CLI `openclaw browser`, методу gateway `browser.request`, runtime браузера та стандартного сервісу керування браузером (увімкнений за замовчуванням; вимкніть його перед заміною) + - `browser` — вбудований browser Plugin для інструмента browser, CLI `openclaw browser`, методу Gateway `browser.request`, середовища виконання browser і служби керування browser за замовчуванням (увімкнений за замовчуванням; вимкніть його перед заміною) - `copilot-proxy` — міст VS Code Copilot Proxy (вимкнений за замовчуванням) @@ -144,29 +150,29 @@ OpenClaw розпізнає два формати плагінів: | Поле | Опис | | ---------------- | --------------------------------------------------------- | -| `enabled` | Головний перемикач (за замовчуванням: `true`) | -| `allow` | Allowlist плагінів (необов’язково) | -| `deny` | Denylist плагінів (необов’язково; deny має пріоритет) | +| `enabled` | Головний перемикач (типово: `true`) | +| `allow` | Список дозволених плагінів (необов’язково) | +| `deny` | Список заборонених плагінів (необов’язково; заборона має пріоритет) | | `load.paths` | Додаткові файли/каталоги плагінів | -| `slots` | Вибір ексклюзивних слотів (наприклад, `memory`, `contextEngine`) | -| `entries.\` | Перемикачі та конфігурація для окремих плагінів | +| `slots` | Селектори ексклюзивних слотів (наприклад, `memory`, `contextEngine`) | +| `entries.\` | Перемикачі та конфігурація для окремого плагіна | -Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway запущено з -відстеженням конфігурації та внутрішньопроцесним перезапуском (типовий шлях `openclaw gateway`), -цей перезапуск зазвичай виконується автоматично невдовзі після запису конфігурації. +Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway запущено з відстеженням +конфігурації та увімкненим перезапуском у межах процесу (типовий шлях `openclaw gateway`), +цей перезапуск зазвичай виконується автоматично невдовзі після запису змін у конфігурацію. - + - **Вимкнений**: плагін існує, але правила ввімкнення його вимкнули. Конфігурація зберігається. - - **Відсутній**: конфігурація посилається на ідентифікатор плагіна, який не знайдено під час виявлення. + - **Відсутній**: конфігурація посилається на ідентифікатор плагіна, який не було знайдено під час виявлення. - **Недійсний**: плагін існує, але його конфігурація не відповідає оголошеній схемі. ## Виявлення та пріоритет -OpenClaw сканує плагіни в такому порядку (перше збігання перемагає): +OpenClaw сканує плагіни в такому порядку (перше знайдене збігом і використовується): - + `plugins.load.paths` — явні шляхи до файлів або каталогів. @@ -179,8 +185,8 @@ OpenClaw сканує плагіни в такому порядку (перше - Постачаються з OpenClaw. Багато з них увімкнені за замовчуванням (провайдери моделей, мовлення). - Інші потрібно вмикати явно. + Постачаються разом з OpenClaw. Багато з них увімкнені за замовчуванням (постачальники моделей, мовлення). + Інші потребують явного ввімкнення. @@ -189,13 +195,13 @@ OpenClaw сканує плагіни в такому порядку (перше - `plugins.enabled: false` вимикає всі плагіни - `plugins.deny` завжди має пріоритет над allow - `plugins.entries.\.enabled: false` вимикає цей плагін -- Плагіни з робочого простору **вимкнені за замовчуванням** (їх потрібно явно ввімкнути) +- Плагіни з джерелом із робочого простору **типово вимкнені** (їх потрібно явно ввімкнути) - Вбудовані плагіни дотримуються вбудованого набору, увімкненого за замовчуванням, якщо це не перевизначено - Ексклюзивні слоти можуть примусово ввімкнути вибраний плагін для цього слота ## Слоти плагінів (ексклюзивні категорії) -Деякі категорії є ексклюзивними (одночасно активний лише один варіант): +Деякі категорії є ексклюзивними (одночасно може бути активним лише один): ```json5 { @@ -208,20 +214,20 @@ OpenClaw сканує плагіни в такому порядку (перше } ``` -| Слот | Що він контролює | За замовчуванням | -| --------------- | ----------------------- | -------------------- | -| `memory` | Активний плагін пам’яті | `memory-core` | -| `contextEngine` | Активний рушій контексту | `legacy` (вбудований) | +| Слот | Що він керує | Типове значення | +| --------------- | -------------------------- | ------------------- | +| `memory` | Active Memory плагін | `memory-core` | +| `contextEngine` | Активний рушій контексту | `legacy` (вбудований) | ## Довідка CLI ```bash -openclaw plugins list # компактний перелік +openclaw plugins list # стислий перелік openclaw plugins list --enabled # лише завантажені плагіни -openclaw plugins list --verbose # деталі по кожному плагіну -openclaw plugins list --json # машиночитний перелік -openclaw plugins inspect # розгорнута інформація -openclaw plugins inspect --json # машиночитний формат +openclaw plugins list --verbose # рядки з детальною інформацією про кожен плагін +openclaw plugins list --json # машиночитаний перелік +openclaw plugins inspect # детальна інформація +openclaw plugins inspect --json # машиночитаний формат openclaw plugins inspect --all # таблиця для всього набору openclaw plugins info # псевдонім inspect openclaw plugins doctor # діагностика @@ -230,15 +236,15 @@ openclaw plugins install # установлення (споч openclaw plugins install clawhub: # установлення лише з ClawHub openclaw plugins install --force # перезаписати наявне встановлення openclaw plugins install # установлення з локального шляху -openclaw plugins install -l # прив’язати (без копіювання) для розробки +openclaw plugins install -l # зв’язати (без копіювання) для розробки openclaw plugins install --marketplace openclaw plugins install --marketplace https://github.com// -openclaw plugins install --pin # записати точну розв’язану npm-специфікацію +openclaw plugins install --pin # записати точну розв’язану специфікацію npm openclaw plugins install --dangerously-force-unsafe-install openclaw plugins update # оновити один плагін openclaw plugins update --dangerously-force-unsafe-install -openclaw plugins update --all # оновити всі -openclaw plugins uninstall # видалити записи конфігурації/встановлення +openclaw plugins update --all # оновити все +openclaw plugins uninstall # видалити записи конфігурації/установлення openclaw plugins uninstall --keep-files openclaw plugins marketplace list openclaw plugins marketplace list --json @@ -248,45 +254,44 @@ openclaw plugins disable ``` Вбудовані плагіни постачаються разом з OpenClaw. Багато з них увімкнені за замовчуванням (наприклад, -вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований плагін -браузера). Інші вбудовані плагіни все ще потребують `openclaw plugins enable `. +вбудовані постачальники моделей, вбудовані постачальники мовлення та вбудований +browser Plugin). Інші вбудовані плагіни все одно потребують `openclaw plugins enable `. -`--force` перезаписує наявний встановлений плагін або набір хуків на місці. -Його не підтримано разом з `--link`, який повторно використовує вихідний шлях -замість копіювання в керовану ціль установлення. +`--force` перезаписує наявний установлений плагін або пакет хуків на місці. +Він не підтримується разом із `--link`, який повторно використовує вихідний шлях +замість копіювання в керовану ціль інсталяції. -`--pin` працює лише для npm. Його не підтримано з `--marketplace`, оскільки -установлення з marketplace зберігає метадані джерела marketplace замість npm-специфікації. +`--pin` працює лише з npm. Він не підтримується з `--marketplace`, оскільки +установлення з marketplace зберігають метадані джерела marketplace, а не специфікацію npm. -`--dangerously-force-unsafe-install` — це аварійне перевизначення для хибно -позитивних спрацювань вбудованого сканера небезпечного коду. Воно дозволяє -продовжувати встановлення та оновлення плагінів попри вбудовані результати рівня `critical`, але -все одно не обходить блокування політики плагіна `before_install` або блокування через помилки сканування. +`--dangerously-force-unsafe-install` — це аварійне перевизначення для хибнопозитивних +спрацьовувань вбудованого сканера небезпечного коду. Воно дозволяє інсталяції та оновлення +плагінів продовжуватися попри вбудовані результати рівня `critical`, але все одно +не обходить блокування політики плагіна `before_install` або блокування через помилку сканування. -Цей прапорець CLI застосовується лише до потоків встановлення/оновлення плагінів. Установлення залежностей Skills через gateway -замість цього використовує відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` -залишається окремим потоком завантаження/встановлення Skills із ClawHub. +Цей прапорець CLI застосовується лише до потоків інсталяції/оновлення плагінів. Установлення залежностей +Skills через Gateway натомість використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком завантаження/установлення Skills через ClawHub. -Сумісні пакети беруть участь у тому самому потоці list/inspect/enable/disable -для плагінів. Поточна підтримка runtime включає bundle Skills, command-skills Claude, -значення за замовчуванням у Claude `settings.json`, значення за замовчуванням для Claude `.lsp.json` та оголошених у маніфесті +Сумісні набори беруть участь у тих самих потоках list/inspect/enable/disable для плагінів. +Поточна підтримка середовища виконання включає bundle Skills, command-skills Claude, +типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і оголошені в маніфесті `lspServers`, command-skills Cursor і сумісні каталоги хуків Codex. -`openclaw plugins inspect ` також показує виявлені можливості bundle, а також -підтримувані чи непідтримувані записи серверів MCP і LSP для плагінів на основі bundle. +`openclaw plugins inspect ` також повідомляє про виявлені можливості набору, а також +підтримувані або непідтримувані записи серверів MCP і LSP для плагінів на основі наборів. Джерелами marketplace можуть бути відома назва marketplace Claude з `~/.claude/plugins/known_marketplaces.json`, локальний корінь marketplace або шлях `marketplace.json`, скорочений запис GitHub на кшталт `owner/repo`, URL репозиторію GitHub -або git URL. Для віддалених marketplace записи плагінів мають залишатися в межах -клонованого репозиторію marketplace і використовувати лише відносні шляхи джерел. +або URL git. Для віддалених marketplace записи плагінів мають залишатися всередині +клонованого репозиторію marketplace і використовувати лише відносні джерела шляхів. -Детальніше див. в [`openclaw plugins` довідці CLI](/cli/plugins). +Повні відомості дивіться в [довідці CLI `openclaw plugins`](/cli/plugins). ## Огляд API плагінів -Native-плагіни експортують об’єкт entry, який надає `register(api)`. Старіші -плагіни все ще можуть використовувати `activate(api)` як застарілий псевдонім, але нові плагіни повинні +Native плагіни експортують об’єкт entry, який надає `register(api)`. Старіші +плагіни все ще можуть використовувати `activate(api)` як застарілий псевдонім, але для нових плагінів слід використовувати `register`. ```typescript @@ -308,48 +313,48 @@ export default definePluginEntry({ ``` OpenClaw завантажує об’єкт entry і викликає `register(api)` під час -активації плагіна. Завантажувач усе ще повертається до `activate(api)` для старіших плагінів, -але вбудовані плагіни й нові зовнішні плагіни мають розглядати `register` як +активації плагіна. Завантажувач і далі використовує `activate(api)` як резервний варіант для старіших плагінів, +але вбудовані плагіни та нові external плагіни повинні розглядати `register` як публічний контракт. Поширені методи реєстрації: -| Метод | Що він реєструє | -| -------------------------------------- | ----------------------------- | -| `registerProvider` | Провайдер моделей (LLM) | -| `registerChannel` | Канал чату | -| `registerTool` | Інструмент агента | -| `registerHook` / `on(...)` | Хуки життєвого циклу | -| `registerSpeechProvider` | Text-to-speech / STT | -| `registerRealtimeTranscriptionProvider` | Streaming STT | -| `registerRealtimeVoiceProvider` | Двобічний голос у реальному часі | -| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо | -| `registerImageGenerationProvider` | Генерація зображень | -| `registerMusicGenerationProvider` | Генерація музики | -| `registerVideoGenerationProvider` | Генерація відео | -| `registerWebFetchProvider` | Провайдер отримання/скрейпінгу вебданих | -| `registerWebSearchProvider` | Вебпошук | -| `registerHttpRoute` | HTTP-ендпойнт | -| `registerCommand` / `registerCli` | Команди CLI | -| `registerContextEngine` | Рушій контексту | -| `registerService` | Фоновий сервіс | +| Метод | Що він реєструє | +| --------------------------------------- | -------------------------- | +| `registerProvider` | Постачальник моделей (LLM) | +| `registerChannel` | Канал чату | +| `registerTool` | Інструмент агента | +| `registerHook` / `on(...)` | Хуки життєвого циклу | +| `registerSpeechProvider` | Перетворення тексту на мовлення / STT | +| `registerRealtimeTranscriptionProvider` | Потоковий STT | +| `registerRealtimeVoiceProvider` | Двобічний голос у реальному часі | +| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо | +| `registerImageGenerationProvider` | Генерація зображень | +| `registerMusicGenerationProvider` | Генерація музики | +| `registerVideoGenerationProvider` | Генерація відео | +| `registerWebFetchProvider` | Постачальник отримання / збирання даних з вебу | +| `registerWebSearchProvider` | Вебпошук | +| `registerHttpRoute` | HTTP endpoint | +| `registerCommand` / `registerCli` | Команди CLI | +| `registerContextEngine` | Рушій контексту | +| `registerService` | Фонова служба | -Поведінка guard для типізованих хуків життєвого циклу: +Поведінка guard-хуків для типізованих хуків життєвого циклу: - `before_tool_call`: `{ block: true }` є термінальним; обробники з нижчим пріоритетом пропускаються. -- `before_tool_call`: `{ block: false }` нічого не робить і не скасовує раніше встановлений блок. +- `before_tool_call`: `{ block: false }` не виконує дій і не скасовує попереднє блокування. - `before_install`: `{ block: true }` є термінальним; обробники з нижчим пріоритетом пропускаються. -- `before_install`: `{ block: false }` нічого не робить і не скасовує раніше встановлений блок. +- `before_install`: `{ block: false }` не виконує дій і не скасовує попереднє блокування. - `message_sending`: `{ cancel: true }` є термінальним; обробники з нижчим пріоритетом пропускаються. -- `message_sending`: `{ cancel: false }` нічого не робить і не скасовує раніше встановлене скасування. +- `message_sending`: `{ cancel: false }` не виконує дій і не скасовує попереднє скасування. -Повну поведінку типізованих хуків див. в [Огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics). +Повну типізовану поведінку хуків дивіться в [Огляд SDK](/uk/plugins/sdk-overview#hook-decision-semantics). ## Пов’язане - [Створення плагінів](/uk/plugins/building-plugins) — створіть власний плагін -- [Пакети плагінів](/uk/plugins/bundles) — сумісність пакетів Codex/Claude/Cursor +- [Набори плагінів](/uk/plugins/bundles) — сумісність наборів Codex/Claude/Cursor - [Маніфест плагіна](/uk/plugins/manifest) — схема маніфесту -- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додавання інструментів агента в плагін -- [Внутрішня будова плагінів](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження -- [Плагіни спільноти](/uk/plugins/community) — сторонні переліки +- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додайте інструменти агента в плагін +- [Внутрішня архітектура плагінів](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження +- [Плагіни спільноти](/uk/plugins/community) — сторонні добірки