chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
b89b9f1d20
commit
b9ffe605be
@ -1,20 +1,20 @@
|
||||
---
|
||||
read_when:
|
||||
- Додавання або змінення міграцій doctor
|
||||
- Внесення несумісних змін до конфігурації
|
||||
- Додавання або зміна міграцій doctor
|
||||
- Запровадження несумісних змін конфігурації
|
||||
sidebarTitle: Doctor
|
||||
summary: 'Команда doctor: перевірки стану, міграції конфігурації та кроки відновлення'
|
||||
summary: 'Команда діагностики: перевірки справності, міграції конфігурації та кроки відновлення'
|
||||
title: Діагностика
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T13:47:35Z"
|
||||
generated_at: "2026-05-01T04:39:10Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 89150fe2b2848f1f168b42ca6b240bc0e6a0edee4f1bcad7f79d297face9c95e
|
||||
source_hash: 52183eaf6024eface20089f9d11143ef1e952d2488eee766dc154512f5d3c6b4
|
||||
source_path: gateway/doctor.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілі конфігурацію й стан, перевіряє справність і надає практичні кроки для відновлення.
|
||||
`openclaw doctor` — це інструмент відновлення й міграції для OpenClaw. Він виправляє застарілі конфігурації/стан, перевіряє справність і надає дієві кроки відновлення.
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
@ -30,7 +30,7 @@ openclaw doctor
|
||||
openclaw doctor --yes
|
||||
```
|
||||
|
||||
Прийняти типові значення без запитів (зокрема кроки відновлення перезапуску/служби/пісочниці, коли застосовно).
|
||||
Прийняти типові значення без запитів (включно з кроками перезапуску/служби/відновлення пісочниці, коли застосовно).
|
||||
|
||||
</Tab>
|
||||
<Tab title="--repair">
|
||||
@ -46,7 +46,7 @@ openclaw doctor
|
||||
openclaw doctor --repair --force
|
||||
```
|
||||
|
||||
Застосувати також агресивні відновлення (перезаписує користувацькі конфігурації супервізора).
|
||||
Також застосувати агресивні відновлення (перезаписує користувацькі конфігурації супервізора).
|
||||
|
||||
</Tab>
|
||||
<Tab title="--non-interactive">
|
||||
@ -54,7 +54,7 @@ openclaw doctor
|
||||
openclaw doctor --non-interactive
|
||||
```
|
||||
|
||||
Запустити без запитів і застосувати лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії з перезапуском/службою/пісочницею, які потребують підтвердження людини. Застарілі міграції стану запускаються автоматично, коли їх виявлено.
|
||||
Запустити без запитів і застосувати лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії перезапуску/служби/пісочниці, які потребують підтвердження людини. Застарілі міграції стану виконуються автоматично, коли їх виявлено.
|
||||
|
||||
</Tab>
|
||||
<Tab title="--deep">
|
||||
@ -62,126 +62,131 @@ openclaw doctor
|
||||
openclaw doctor --deep
|
||||
```
|
||||
|
||||
Просканувати системні служби на наявність додаткових інсталяцій Gateway (launchd/systemd/schtasks).
|
||||
Просканувати системні служби на наявність додаткових встановлень Gateway (launchd/systemd/schtasks).
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Якщо хочете переглянути зміни перед записом, спершу відкрийте файл конфігурації:
|
||||
Якщо ви хочете переглянути зміни перед записом, спершу відкрийте файл конфігурації:
|
||||
|
||||
```bash
|
||||
cat ~/.openclaw/openclaw.json
|
||||
```
|
||||
|
||||
## Що він робить (зведення)
|
||||
## Що він робить (коротко)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Справність, UI та оновлення">
|
||||
- Необов’язкове попереднє оновлення для git-інсталяцій (лише в інтерактивному режимі).
|
||||
- Перевірка актуальності протоколу UI (перезбирає Control UI, коли схема протоколу новіша).
|
||||
- Необов’язкове попереднє оновлення для git-встановлень (лише інтерактивно).
|
||||
- Перевірка актуальності протоколу UI (перебудовує Control UI, коли схема протоколу новіша).
|
||||
- Перевірка справності + запит на перезапуск.
|
||||
- Зведення стану Skills (придатні/відсутні/заблоковані) і стан Plugin.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Конфігурація та міграції">
|
||||
- Нормалізація конфігурації для застарілих значень.
|
||||
- Міграція конфігурації Talk із застарілих пласких полів `talk.*` у `talk.provider` + `talk.providers.<provider>`.
|
||||
- Перевірки міграції браузера для застарілих конфігурацій Chrome extension і готовності Chrome MCP.
|
||||
- Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.<provider>`.
|
||||
- Перевірки міграції браузера для застарілих конфігурацій розширення Chrome і готовності Chrome MCP.
|
||||
- Попередження про перевизначення провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
|
||||
- Попередження про затінення Codex OAuth (`models.providers.openai-codex`).
|
||||
- Перевірка передумов OAuth TLS для профілів OpenAI Codex OAuth.
|
||||
- Міграція застарілого стану на диску (сеанси/каталог агентів/автентифікація WhatsApp).
|
||||
- Попередження allowlist Plugin/інструментів, коли `plugins.allow` є обмежувальним, але політика інструментів усе ще запитує wildcard або інструменти, що належать Plugin.
|
||||
- Міграція застарілого стану на диску (sessions/agent dir/автентифікація WhatsApp).
|
||||
- Міграція застарілих ключів контракту маніфесту Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
|
||||
- Міграція застарілого сховища cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, payload `provider`, прості резервні завдання webhook `notify: true`).
|
||||
- Міграція застарілого сховища cron (`jobId`, `schedule.cron`, поля доставки/payload верхнього рівня, payload `provider`, прості резервні webhook-завдання `notify: true`).
|
||||
- Міграція застарілої runtime-політики агента до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`.
|
||||
- Очищення застарілої конфігурації Plugin, коли plugins увімкнені; коли `plugins.enabled=false`, застарілі посилання на plugins розглядаються як інертна конфігурація ізоляції та зберігаються.
|
||||
- Очищення застарілої конфігурації Plugin, коли plugins увімкнено; коли `plugins.enabled=false`, застарілі посилання на Plugin вважаються інертною containment-конфігурацією та зберігаються.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Стан і цілісність">
|
||||
- Перевірка файлів блокування сеансів і очищення застарілих блокувань.
|
||||
- Відновлення транскриптів сеансів для дубльованих гілок переписування промптів, створених ураженими збірками 2026.4.24.
|
||||
- Виявлення tombstone для restart-recovery завислих субагентів із підтримкою `--fix` для очищення застарілих прапорців перерваного відновлення, щоб під час запуску дочірній процес не продовжував трактуватися як перерваний перезапуском.
|
||||
- Перевірки цілісності стану та дозволів (сеанси, транскрипти, каталог стану).
|
||||
- Перевірка файлів блокування сесій і очищення застарілих блокувань.
|
||||
- Відновлення transcript сесій для дубльованих гілок переписування prompt, створених ураженими збірками 2026.4.24.
|
||||
- Виявлення tombstone для відновлення після перезапуску завислого subagent, з підтримкою `--fix` для очищення застарілих прапорців перерваного відновлення, щоб запуск не продовжував трактувати дочірній процес як перерваний під час перезапуску.
|
||||
- Перевірки цілісності стану та дозволів (sessions, transcripts, state dir).
|
||||
- Перевірки дозволів файлу конфігурації (chmod 600) під час локального запуску.
|
||||
- Справність автентифікації моделей: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє про стани cooldown/disabled auth-profile.
|
||||
- Виявлення додаткового каталогу робочого простору (`~/openclaw`).
|
||||
- Справність автентифікації моделі: перевіряє завершення OAuth, може оновлювати токени, термін дії яких спливає, і повідомляє про стани cooldown/disabled auth-profile.
|
||||
- Виявлення додаткової директорії робочого простору (`~/openclaw`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Gateway, служби та супервізори">
|
||||
- Відновлення образу пісочниці, коли пісочницю ввімкнено.
|
||||
- Міграція застарілих служб і виявлення додаткового Gateway.
|
||||
- Відновлення образу пісочниці, коли sandboxing увімкнено.
|
||||
- Міграція застарілих служб і виявлення додаткових Gateway.
|
||||
- Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`).
|
||||
- Перевірки виконання Gateway (службу встановлено, але не запущено; кешована мітка launchd).
|
||||
- Попередження про стан каналу (перевіряються з активного Gateway).
|
||||
- Аудит конфігурації супервізора (launchd/systemd/schtasks) із необов’язковим відновленням.
|
||||
- Очищення середовища вбудованого проксі для служб Gateway, які захопили значення shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час інсталяції або оновлення.
|
||||
- Перевірки найкращих практик виконання Gateway (Node проти Bun, шляхи менеджера версій).
|
||||
- Діагностика конфліктів порту Gateway (типовий `18789`).
|
||||
- Перевірки runtime Gateway (служба встановлена, але не запущена; кешована мітка launchd).
|
||||
- Попередження про стан каналів (перевірено з запущеного Gateway).
|
||||
- Аудит конфігурації супервізора (launchd/systemd/schtasks) з необов’язковим відновленням.
|
||||
- Очищення середовища вбудованого proxy для служб Gateway, які захопили значення shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час встановлення або оновлення.
|
||||
- Перевірки найкращих практик runtime Gateway (Node vs Bun, шляхи version-manager).
|
||||
- Діагностика конфліктів портів Gateway (типовий `18789`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Автентифікація, безпека та сполучення">
|
||||
- Попередження безпеки для відкритих політик DM.
|
||||
- Перевірки автентифікації Gateway для режиму локального токена (пропонує генерацію токена, коли джерела токена не існує; не перезаписує конфігурації токена SecretRef).
|
||||
- Виявлення проблем зі сполученням пристроїв (очікувані перші запити на сполучення, очікувані оновлення ролі/області дії, дрейф застарілого локального кешу device-token і дрейф автентифікації paired-record).
|
||||
<Accordion title="Автентифікація, безпека та pairing">
|
||||
- Попередження безпеки для відкритих DM-політик.
|
||||
- Перевірки автентифікації Gateway для режиму локального токена (пропонує генерацію токена, коли немає джерела токена; не перезаписує конфігурації токена SecretRef).
|
||||
- Виявлення проблем pairing пристрою (очікувані перші запити pairing, очікувані підвищення ролі/обсягу, drift застарілого кешу локального device-token і drift автентифікації paired-record).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Робочий простір і shell">
|
||||
- Перевірка systemd linger у Linux.
|
||||
- Перевірка розміру bootstrap-файлу робочого простору (попередження про обрізання/наближення до ліміту для контекстних файлів).
|
||||
- Перевірка стану shell completion і автоматична інсталяція/оновлення.
|
||||
- Перевірка готовності провайдера embedding для пошуку пам’яті (локальна модель, ключ віддаленого API або бінарний файл QMD).
|
||||
- Перевірки інсталяції з вихідного коду (невідповідність pnpm workspace, відсутні UI-ресурси, відсутній бінарний файл tsx).
|
||||
- Записує оновлену конфігурацію + метадані майстра.
|
||||
- Перевірка розміру bootstrap-файлу робочого простору (попередження про обрізання/наближення до ліміту для context-файлів).
|
||||
- Перевірка стану shell completion і автоматичне встановлення/оновлення.
|
||||
- Перевірка готовності провайдера embedding для пошуку пам’яті (локальна модель, віддалений API key або binary QMD).
|
||||
- Перевірки source install (невідповідність pnpm workspace, відсутні UI assets, відсутній binary tsx).
|
||||
- Записує оновлену конфігурацію + метадані wizard.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Зворотне заповнення і скидання Dreams UI
|
||||
## Backfill і reset для Dreams UI
|
||||
|
||||
Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для workflow grounded dreaming. Ці дії використовують RPC-методи Gateway у стилі doctor, але вони **не** є частиною CLI-відновлення/міграції `openclaw doctor`.
|
||||
Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для grounded dreaming workflow. Ці дії використовують RPC-методи в стилі gateway doctor, але вони **не** є частиною CLI-відновлення/міграції `openclaw doctor`.
|
||||
|
||||
Що вони роблять:
|
||||
|
||||
- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному робочому просторі, запускає grounded REM diary pass і записує оборотні записи зворотного заповнення в `DREAMS.md`.
|
||||
- **Reset** видаляє з `DREAMS.md` лише ці позначені записи щоденника зворотного заповнення.
|
||||
- **Clear Grounded** видаляє лише підготовлені короткострокові записи, призначені тільки для grounded, які походять з історичного відтворення й ще не накопичили live recall або daily support.
|
||||
- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному робочому просторі, запускає grounded REM diary pass і записує оборотні backfill-записи в `DREAMS.md`.
|
||||
- **Reset** видаляє лише ці позначені backfill diary entries з `DREAMS.md`.
|
||||
- **Clear Grounded** видаляє лише підготовлені grounded-only short-term entries, що походять з historical replay і ще не накопичили live recall або daily support.
|
||||
|
||||
Чого вони самі по собі **не** роблять:
|
||||
Чого вони **не** роблять самі по собі:
|
||||
|
||||
- вони не редагують `MEMORY.md`
|
||||
- вони не запускають повні міграції doctor
|
||||
- вони не готують автоматично grounded-кандидатів у live-сховище короткострокового просування, якщо ви спершу явно не запустите staged CLI path
|
||||
- вони не додають автоматично grounded candidates до live short-term promotion store, якщо ви явно спершу не запустите staged CLI path
|
||||
|
||||
Якщо хочете, щоб grounded historical replay впливав на звичайну lane глибокого просування, натомість використовуйте CLI-потік:
|
||||
Якщо ви хочете, щоб grounded historical replay впливав на звичайну deep promotion lane, натомість використайте CLI-потік:
|
||||
|
||||
```bash
|
||||
openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
```
|
||||
|
||||
Це готує grounded durable candidates у сховище short-term dreaming, залишаючи `DREAMS.md` поверхнею для перегляду.
|
||||
Це додає grounded durable candidates до short-term dreaming store, залишаючи `DREAMS.md` поверхнею для перегляду.
|
||||
|
||||
## Детальна поведінка та обґрунтування
|
||||
## Докладна поведінка й обґрунтування
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="0. Необов’язкове оновлення (git-інсталяції)">
|
||||
<Accordion title="0. Необов’язкове оновлення (git-встановлення)">
|
||||
Якщо це git checkout і doctor працює інтерактивно, він пропонує оновитися (fetch/rebase/build) перед запуском doctor.
|
||||
</Accordion>
|
||||
<Accordion title="1. Нормалізація конфігурації">
|
||||
Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без перевизначення для конкретного каналу), doctor нормалізує їх до поточної схеми.
|
||||
Якщо конфігурація містить застарілі форми значень (наприклад `messages.ackReaction` без перевизначення для конкретного каналу), doctor нормалізує їх до поточної схеми.
|
||||
|
||||
Це включає застарілі пласкі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.<provider>`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у мапу провайдерів.
|
||||
Це включає застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.<provider>`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у map провайдера.
|
||||
|
||||
Doctor також попереджає, коли `plugins.allow` не порожній, а політика інструментів використовує
|
||||
wildcard або записи інструментів, що належать Plugin. `tools.allow: ["*"]` відповідає лише інструментам
|
||||
із plugins, які фактично завантажуються; він не обходить ексклюзивний allowlist Plugin.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2. Міграції застарілих ключів конфігурації">
|
||||
Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися й просять запустити `openclaw doctor`.
|
||||
Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися й просять вас виконати `openclaw doctor`.
|
||||
|
||||
Doctor:
|
||||
|
||||
- Пояснить, які застарілі ключі знайдено.
|
||||
- Покаже застосовану міграцію.
|
||||
- Перепише `~/.openclaw/openclaw.json` з оновленою схемою.
|
||||
- Перезапише `~/.openclaw/openclaw.json` з оновленою схемою.
|
||||
|
||||
Gateway також автоматично запускає міграції doctor під час запуску, коли виявляє застарілий формат конфігурації, тож застарілі конфігурації відновлюються без ручного втручання. Міграції сховища завдань Cron обробляються через `openclaw doctor --fix`.
|
||||
Gateway також автоматично запускає міграції doctor під час старту, коли виявляє застарілий формат конфігурації, тому застарілі конфігурації відновлюються без ручного втручання. Міграції сховища cron jobs обробляються командою `openclaw doctor --fix`.
|
||||
|
||||
Поточні міграції:
|
||||
|
||||
@ -190,7 +195,7 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
|
||||
- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
|
||||
- `routing.queue` → `messages.queue`
|
||||
- `routing.bindings` → top-level `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.<provider>`
|
||||
- `routing.agentToAgent` → `tools.agentToAgent`
|
||||
@ -206,280 +211,280 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
|
||||
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
|
||||
- `bindings[].match.accountID` → `bindings[].match.accountId`
|
||||
- Для каналів з іменованими `accounts`, але залишковими значеннями каналу верхнього рівня для одного акаунта, перемістити ці значення в області акаунта до підвищеного акаунта, вибраного для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/типову ціль)
|
||||
- Для каналів з іменованими `accounts`, але із залишковими верхньорівневими значеннями каналу для одного облікового запису, перемістіть ці значення, прив’язані до облікового запису, у підвищений обліковий запис, вибраний для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/типову ціль)
|
||||
- `identity` → `agents.list[].identity`
|
||||
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
|
||||
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
|
||||
- видалити `agents.defaults.llm`; використовуйте `models.providers.<id>.timeoutSeconds` для тайм-аутів повільних провайдерів/моделей
|
||||
- видаліть `agents.defaults.llm`; використовуйте `models.providers.<id>.timeoutSeconds` для повільних тайм-аутів провайдера/моделі
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
|
||||
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
|
||||
- видалити `browser.relayBindHost` (застаріле налаштування relay extension)
|
||||
- застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (запуск gateway також пропускає провайдерів, у яких `api` встановлено на майбутнє або невідоме значення enum, замість того щоб завершуватися з помилкою)
|
||||
- видаліть `browser.relayBindHost` (застаріле налаштування ретрансляції розширення)
|
||||
- застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (запуск gateway також пропускає провайдерів, чиє `api` встановлено в майбутнє або невідоме значення enum, замість аварійного завершення за закритою політикою)
|
||||
|
||||
Попередження Doctor також містять рекомендації щодо типового акаунта для багатоакаунтних каналів:
|
||||
Попередження doctor також містять настанови щодо типового облікового запису для багатооблікових каналів:
|
||||
|
||||
- Якщо налаштовано два або більше записів `channels.<channel>.accounts` без `channels.<channel>.defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис.
|
||||
- Якщо `channels.<channel>.defaultAccount` встановлено на невідомий ID облікового запису, doctor попереджає про це й перелічує налаштовані ID облікових записів.
|
||||
- Якщо `channels.<channel>.defaultAccount` задано як невідомий ID облікового запису, doctor попереджає і перелічує налаштовані ID облікових записів.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2b. Перевизначення провайдера OpenCode">
|
||||
Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. Це може змусити моделі використовувати неправильний API або обнулити витрати. Doctor попереджає, щоб ви могли вилучити перевизначення й відновити маршрутизацію API та витрати для кожної моделі.
|
||||
Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. Це може примусово спрямувати моделі на неправильний API або занулити витрати. Doctor попереджає, щоб ви могли видалити перевизначення і відновити маршрутизацію API та витрати для кожної моделі.
|
||||
</Accordion>
|
||||
<Accordion title="2c. Міграція браузера та готовність Chrome MCP">
|
||||
Якщо ваша конфігурація браузера все ще вказує на вилучений шлях розширення Chrome, doctor нормалізує її до поточної моделі підключення Chrome MCP на локальному хості:
|
||||
<Accordion title="2c. Міграція браузера і готовність Chrome MCP">
|
||||
Якщо конфігурація браузера досі вказує на видалений шлях розширення Chrome, doctor нормалізує її до поточної моделі підключення Chrome MCP на локальному хості:
|
||||
|
||||
- `browser.profiles.*.driver: "extension"` стає `"existing-session"`
|
||||
- `browser.relayBindHost` вилучається
|
||||
- `browser.relayBindHost` видаляється
|
||||
|
||||
Doctor також перевіряє шлях Chrome MCP на локальному хості, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`:
|
||||
|
||||
- перевіряє, чи встановлено Google Chrome на тому самому хості для типових профілів автопідключення
|
||||
- перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144
|
||||
- нагадує ввімкнути віддалене налагодження на сторінці інспектування браузера (наприклад `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`)
|
||||
- перевіряє, чи Google Chrome встановлено на тому самому хості для типових профілів автоматичного підключення
|
||||
- перевіряє виявлену версію Chrome і попереджає, коли вона нижча за Chrome 144
|
||||
- нагадує ввімкнути віддалене налагодження на сторінці інспектування браузера (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`)
|
||||
|
||||
Doctor не може ввімкнути налаштування на боці Chrome замість вас. Chrome MCP на локальному хості все ще потребує:
|
||||
Doctor не може ввімкнути налаштування на боці Chrome за вас. Chrome MCP на локальному хості все ще потребує:
|
||||
|
||||
- браузера на основі Chromium версії 144+ на хості Gateway/Node
|
||||
- браузера на основі Chromium 144+ на хості gateway/node
|
||||
- локально запущеного браузера
|
||||
- увімкненого віддаленого налагодження в цьому браузері
|
||||
- схвалення першого запиту згоди на підключення в браузері
|
||||
|
||||
Готовність тут стосується лише передумов локального підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, усе ще потребують керованого браузера або сирого профілю CDP.
|
||||
Готовність тут стосується лише передумов локального підключення. Existing-session зберігає поточні обмеження маршруту Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, усе ще потребують керованого браузера або сирого профілю CDP.
|
||||
|
||||
Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших headless-потоків. Вони й надалі використовують сирий CDP.
|
||||
Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших headless-процесів. Вони й надалі використовують сирий CDP.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2d. Передумови OAuth TLS">
|
||||
Коли налаштовано OAuth-профіль OpenAI Codex, doctor перевіряє кінцеву точку авторизації OpenAI, щоб переконатися, що локальний стек TLS Node/OpenSSL може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, протермінований сертифікат або самопідписаний сертифікат), doctor виводить рекомендації з виправлення для конкретної платформи. На macOS із Homebrew Node виправлення зазвичай таке: `brew postinstall ca-certificates`. З `--deep` перевірка виконується навіть тоді, коли gateway справний.
|
||||
Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє кінцеву точку авторизації OpenAI, щоб переконатися, що локальний стек Node/OpenSSL TLS може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, протермінований сертифікат або самопідписаний сертифікат), doctor виводить настанови з виправлення для конкретної платформи. На macOS із Homebrew Node виправленням зазвичай є `brew postinstall ca-certificates`. З `--deep` перевірка запускається навіть тоді, коли gateway справний.
|
||||
</Accordion>
|
||||
<Accordion title="2e. Перевизначення провайдера Codex OAuth">
|
||||
Якщо раніше ви додали застарілі налаштування транспорту OpenAI у `models.providers.openai-codex`, вони можуть затіняти вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі налаштування транспорту поруч із Codex OAuth, щоб ви могли вилучити або переписати застаріле перевизначення транспорту й повернути вбудовану поведінку маршрутизації/резервування. Користувацькі проксі та перевизначення лише заголовків усе ще підтримуються й не спричиняють це попередження.
|
||||
Якщо раніше ви додали застарілі налаштування транспорту OpenAI у `models.providers.openai-codex`, вони можуть затінити вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі налаштування транспорту разом із Codex OAuth, щоб ви могли видалити або переписати застаріле перевизначення транспорту і повернути вбудовану маршрутизацію/резервну поведінку. Користувацькі проксі та перевизначення лише заголовків усе ще підтримуються й не викликають це попередження.
|
||||
</Accordion>
|
||||
<Accordion title="2f. Попередження маршрутів Plugin Codex">
|
||||
Коли ввімкнено bundled Plugin Codex, doctor також перевіряє, чи основні посилання на моделі `openai-codex/*` досі розв’язуються через типовий запуск PI. Таке поєднання чинне, коли ви хочете використовувати автентифікацію Codex OAuth/підписки через PI, але його легко сплутати з нативним app-server harness Codex. Doctor попереджає й указує на явну форму app-server: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`.
|
||||
Коли увімкнено вбудований Codex Plugin, doctor також перевіряє, чи посилання первинної моделі `openai-codex/*` усе ще розв’язуються через типовий runner PI. Ця комбінація чинна, коли ви хочете автентифікацію Codex OAuth/підписки через PI, але її легко сплутати з нативним harness сервера застосунку Codex. Doctor попереджає і вказує на явну форму сервера застосунку: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`.
|
||||
|
||||
Doctor не виправляє це автоматично, бо обидва маршрути чинні:
|
||||
|
||||
- `openai-codex/*` + PI означає "використовувати автентифікацію Codex OAuth/підписки через звичайний runner OpenClaw."
|
||||
- `openai/*` + `runtime: "codex"` означає "запустити вбудований turn через нативний app-server Codex."
|
||||
- `/codex ...` означає "керувати або прив’язати нативну розмову Codex із чату."
|
||||
- `/acp ...` або `runtime: "acp"` означає "використовувати зовнішній адаптер ACP/acpx."
|
||||
- `openai-codex/*` + PI означає «використовувати автентифікацію Codex OAuth/підписки через звичайний runner OpenClaw».
|
||||
- `openai/*` + `runtime: "codex"` означає «запустити вбудований turn через нативний сервер застосунку Codex».
|
||||
- `/codex ...` означає «керувати або прив’язати нативну розмову Codex із чату».
|
||||
- `/acp ...` або `runtime: "acp"` означає «використовувати зовнішній адаптер ACP/acpx».
|
||||
|
||||
Якщо з’являється попередження, виберіть потрібний маршрут і відредагуйте конфігурацію вручну. Залиште попередження як є, коли PI Codex OAuth є навмисним.
|
||||
Якщо з’являється попередження, виберіть задуманий маршрут і відредагуйте конфігурацію вручну. Залиште попередження без змін, коли PI Codex OAuth є навмисним.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3. Міграції застарілого стану (розкладка на диску)">
|
||||
Doctor може мігрувати старіші розкладки на диску в поточну структуру:
|
||||
<Accordion title="3. Міграції застарілого стану (структура диска)">
|
||||
Doctor може мігрувати старіші структури на диску в поточну структуру:
|
||||
|
||||
- Сховище сесій + транскрипти:
|
||||
- Сховище сеансів + транскрипти:
|
||||
- з `~/.openclaw/sessions/` до `~/.openclaw/agents/<agentId>/sessions/`
|
||||
- Каталог агента:
|
||||
- з `~/.openclaw/agent/` до `~/.openclaw/agents/<agentId>/agent/`
|
||||
- Стан автентифікації WhatsApp (Baileys):
|
||||
- із застарілих `~/.openclaw/credentials/*.json` (крім `oauth.json`)
|
||||
- до `~/.openclaw/credentials/whatsapp/<accountId>/...` (ID типового облікового запису: `default`)
|
||||
- до `~/.openclaw/credentials/whatsapp/<accountId>/...` (типовий id облікового запису: `default`)
|
||||
|
||||
Ці міграції виконуються за принципом найкращого зусилля й є ідемпотентними; doctor видаватиме попередження, коли залишатиме будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сесії + каталог агента під час запуску, щоб історія/автентифікація/моделі потрапили в шлях для конкретного агента без ручного запуску doctor. Нормалізація провайдера розмови/мапи провайдерів тепер порівнює за структурною рівністю, тож відмінності лише в порядку ключів більше не спричиняють повторні no-op зміни `doctor --fix`.
|
||||
Ці міграції виконуються за принципом найкращої спроби та є ідемпотентними; doctor виведе попередження, коли залишить будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сеанси + каталог агента під час запуску, щоб історія/автентифікація/моделі потрапляли в шлях для конкретного агента без ручного запуску doctor. Нормалізація провайдера talk/карти провайдерів тепер порівнює за структурною рівністю, тому відмінності лише в порядку ключів більше не спричиняють повторні no-op зміни `doctor --fix`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3a. Міграції застарілих маніфестів Plugin">
|
||||
Doctor сканує всі встановлені маніфести Plugin на наявність застарілих ключів можливостей верхнього рівня (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Коли їх знайдено, він пропонує перемістити їх в об’єкт `contracts` і переписати файл маніфесту на місці. Ця міграція ідемпотентна; якщо ключ `contracts` уже має ті самі значення, застарілий ключ вилучається без дублювання даних.
|
||||
Doctor сканує всі встановлені маніфести Plugin на застарілі верхньорівневі ключі можливостей (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Коли їх знайдено, він пропонує перемістити їх в об’єкт `contracts` і переписати файл маніфесту на місці. Ця міграція ідемпотентна; якщо ключ `contracts` уже має ті самі значення, застарілий ключ видаляється без дублювання даних.
|
||||
</Accordion>
|
||||
<Accordion title="3b. Міграції застарілого сховища Cron">
|
||||
Doctor також перевіряє сховище завдань Cron (`~/.openclaw/cron/jobs.json` за замовчуванням або `cron.store`, коли перевизначено) на наявність старих форм завдань, які планувальник досі приймає для сумісності.
|
||||
Doctor також перевіряє сховище завдань cron (`~/.openclaw/cron/jobs.json` за замовчуванням або `cron.store`, коли перевизначено) на старі форми завдань, які планувальник усе ще приймає для сумісності.
|
||||
|
||||
Поточні очищення Cron включають:
|
||||
Поточні очищення cron включають:
|
||||
|
||||
- `jobId` → `id`
|
||||
- `schedule.cron` → `schedule.expr`
|
||||
- поля payload верхнього рівня (`message`, `model`, `thinking`, ...) → `payload`
|
||||
- поля delivery верхнього рівня (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
|
||||
- псевдоніми delivery `provider` у payload → явний `delivery.channel`
|
||||
- прості застарілі резервні webhook-завдання `notify: true` → явний `delivery.mode="webhook"` із `delivery.to=cron.webhook`
|
||||
- верхньорівневі поля payload (`message`, `model`, `thinking`, ...) → `payload`
|
||||
- верхньорівневі поля delivery (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
|
||||
- псевдоніми доставки `provider` у payload → явний `delivery.channel`
|
||||
- прості застарілі резервні завдання Webhook `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook`
|
||||
|
||||
Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий резервний notify з наявним режимом доставки, що не є webhook, doctor попереджає й залишає це завдання для ручного перегляду.
|
||||
Doctor автоматично мігрує завдання `notify: true` лише тоді, коли це можна зробити без зміни поведінки. Якщо завдання поєднує застарілий резерв notify з наявним режимом доставки не через Webhook, doctor попереджає і залишає це завдання для ручного перегляду.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3c. Очищення блокувань сесій">
|
||||
Doctor сканує кожен каталог сесій агента на застарілі файли блокування запису — файли, що залишилися після аварійного завершення сесії. Для кожного знайденого файла блокування він повідомляє: шлях, PID, чи PID усе ще активний, вік блокування та чи вважається воно застарілим (мертвий PID або старше 30 хвилин). У режимі `--fix` / `--repair` він автоматично вилучає застарілі файли блокування; інакше друкує примітку й указує повторно запустити з `--fix`.
|
||||
<Accordion title="3c. Очищення блокувань сеансів">
|
||||
Doctor сканує кожен каталог сеансів агента на застарілі файли блокування запису — файли, що залишилися після аварійного завершення сеансу. Для кожного знайденого файлу блокування він повідомляє: шлях, PID, чи PID досі активний, вік блокування і чи вважається воно застарілим (мертвий PID або старіше за 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше виводить примітку й інструктує повторно запустити з `--fix`.
|
||||
</Accordion>
|
||||
<Accordion title="3d. Виправлення гілок транскриптів сесій">
|
||||
Doctor сканує JSONL-файли сесій агента на дубльовану форму гілки, створену помилкою переписування prompt-транскриптів 2026.4.24: покинутий user turn із внутрішнім runtime-контекстом OpenClaw плюс активний sibling із тим самим видимим user prompt. У режимі `--fix` / `--repair` doctor створює резервну копію кожного ураженого файла поруч з оригіналом і переписує транскрипт до активної гілки, щоб gateway-історія та зчитувачі пам’яті більше не бачили дубльовані turns.
|
||||
<Accordion title="3d. Виправлення гілки транскрипта сеансу">
|
||||
Doctor сканує JSONL-файли сеансів агента на дубльовану форму гілки, створену помилкою переписування транскрипта prompt від 2026.4.24: покинутий user turn із внутрішнім runtime-контекстом OpenClaw плюс активний sibling, що містить той самий видимий user prompt. У режимі `--fix` / `--repair` doctor створює резервну копію кожного ураженого файлу поруч з оригіналом і переписує транскрипт до активної гілки, щоб історія gateway і reader-и memory більше не бачили дубльовані turn-и.
|
||||
</Accordion>
|
||||
<Accordion title="4. Перевірки цілісності стану (збереження сесій, маршрутизація та безпека)">
|
||||
Каталог стану — це операційний стовбур мозку. Якщо він зникне, ви втратите сесії, облікові дані, журнали й конфігурацію (якщо не маєте резервних копій деінде).
|
||||
<Accordion title="4. Перевірки цілісності стану (збереження сеансів, маршрутизація і безпека)">
|
||||
Каталог стану — це операційний мозковий стовбур. Якщо він зникне, ви втратите сеанси, облікові дані, журнали й конфігурацію (якщо не маєте резервних копій деінде).
|
||||
|
||||
Doctor перевіряє:
|
||||
|
||||
- **Каталог стану відсутній**: попереджає про катастрофічну втрату стану, пропонує повторно створити каталог і нагадує, що не може відновити відсутні дані.
|
||||
- **Дозволи каталогу стану**: перевіряє можливість запису; пропонує виправити дозволи (і видає підказку `chown`, коли виявлено невідповідність власника/групи).
|
||||
- **Каталог стану macOS, синхронізований із хмарою**: попереджає, коли стан розв’язується під iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, бо шляхи з синхронізацією можуть спричиняти повільніший I/O та перегони блокування/синхронізації.
|
||||
- **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розв’язується до джерела монтування `mmcblk*`, бо випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час записів сесій та облікових даних.
|
||||
- **Каталоги сесій відсутні**: `sessions/` і каталог сховища сесій потрібні для збереження історії та уникнення аварій `ENOENT`.
|
||||
- **Невідповідність транскриптів**: попереджає, коли в нещодавніх записах сесій відсутні файли транскриптів.
|
||||
- **Основна сесія "1-line JSONL"**: позначає випадки, коли основний транскрипт має лише один рядок (історія не накопичується).
|
||||
- **Кілька каталогів стану**: попереджає, коли кілька папок `~/.openclaw` існують у різних домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може розділитися між встановленнями).
|
||||
- **Каталог стану відсутній**: попереджає про катастрофічну втрату стану, пропонує повторно створити каталог і нагадує, що відновити відсутні дані неможливо.
|
||||
- **Дозволи каталогу стану**: перевіряє можливість запису; пропонує виправити дозволи (і виводить підказку `chown`, коли виявлено невідповідність власника/групи).
|
||||
- **Синхронізований із хмарою каталог стану macOS**: попереджає, коли стан визначається в iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, бо шляхи з підтримкою синхронізації можуть спричиняти повільніше I/O та перегони блокувань/синхронізації.
|
||||
- **Каталог стану Linux на SD або eMMC**: попереджає, коли стан визначається на джерелі монтування `mmcblk*`, бо випадкове I/O на SD або eMMC може бути повільнішим і швидше зношуватися під час записів сеансів і облікових даних.
|
||||
- **Каталоги сеансів відсутні**: `sessions/` і каталог сховища сеансів потрібні для збереження історії та уникнення збоїв `ENOENT`.
|
||||
- **Невідповідність стенограми**: попереджає, коли в нещодавніх записах сеансів відсутні файли стенограм.
|
||||
- **Головний сеанс "1-line JSONL"**: позначає випадок, коли головна стенограма має лише один рядок (історія не накопичується).
|
||||
- **Кілька каталогів стану**: попереджає, коли кілька папок `~/.openclaw` існують у різних домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може розділятися між інсталяціями).
|
||||
- **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запустити його на віддаленому хості (стан зберігається там).
|
||||
- **Дозволи файла конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групі/всім, і пропонує посилити дозволи до `600`.
|
||||
- **Дозволи файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групі/усім, і пропонує обмежити до `600`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="5. Стан автентифікації моделі (закінчення OAuth)">
|
||||
Doctor перевіряє OAuth-профілі в сховищі автентифікації, попереджає, коли токени невдовзі закінчуються або вже закінчилися, і може оновити їх, коли це безпечно. Якщо профіль Anthropic OAuth/токена застарів, він пропонує API-ключ Anthropic або шлях setup-token Anthropic. Запити на оновлення з’являються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення.
|
||||
<Accordion title="5. Model auth health (OAuth expiry)">
|
||||
Doctor перевіряє профілі OAuth у сховищі автентифікації, попереджає, коли токени скоро завершаться або вже завершилися, і може оновити їх, коли це безпечно. Якщо профіль Anthropic OAuth/токена застарів, він пропонує ключ Anthropic API або шлях 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 також повідомляє про профілі автентифікації, які тимчасово непридатні через:
|
||||
|
||||
- короткі cooldowns (обмеження швидкості/тайм-аути/помилки автентифікації)
|
||||
- довші вимкнення (помилки білінгу/кредитів)
|
||||
- короткі періоди очікування (ліміти швидкості/тайм-аути/збої автентифікації)
|
||||
- триваліші вимкнення (збої оплати/кредитів)
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="6. Перевірка моделі hooks">
|
||||
Якщо `hooks.gmail.model` задано, doctor перевіряє посилання на модель за каталогом і allowlist та попереджає, коли його не вдасться розв’язати або воно заборонене.
|
||||
<Accordion title="6. Hooks model validation">
|
||||
Якщо задано `hooks.gmail.model`, doctor перевіряє посилання на модель за каталогом і allowlist та попереджає, коли воно не розв'яжеться або заборонене.
|
||||
</Accordion>
|
||||
<Accordion title="7. Відновлення образу sandbox">
|
||||
Коли sandboxing увімкнено, doctor перевіряє Docker-образи й пропонує зібрати їх або перейти на застарілі назви, якщо поточний образ відсутній.
|
||||
<Accordion title="7. Sandbox image repair">
|
||||
Коли пісочницю ввімкнено, doctor перевіряє образи Docker і пропонує зібрати або перейти на застарілі назви, якщо поточний образ відсутній.
|
||||
</Accordion>
|
||||
<Accordion title="7b. Runtime-залежності вбудованих plugins">
|
||||
Doctor перевіряє runtime-залежності лише для вбудованих plugins, активних у поточній конфігурації або ввімкнених за замовчуванням у їхньому вбудованому manifest, наприклад `plugins.entries.discord.enabled: true`, застарілий `channels.discord.enabled: true`, налаштовані `models.providers.*` / посилання на моделі агентів або вбудований plugin, увімкнений за замовчуванням, без прив’язки до провайдера. Якщо чогось бракує, doctor повідомляє про пакети та встановлює їх у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Зовнішні plugins і далі використовують `openclaw plugins install` / `openclaw plugins update`; doctor не встановлює залежності для довільних шляхів plugins.
|
||||
<Accordion title="7b. Bundled plugin runtime deps">
|
||||
Doctor перевіряє runtime-залежності лише для вбудованих plugins, активних у поточній конфігурації або ввімкнених за замовчуванням їхнього вбудованого маніфесту, наприклад `plugins.entries.discord.enabled: true`, застаріле `channels.discord.enabled: true`, налаштовані `models.providers.*` / посилання на моделі agent або вбудований plugin, увімкнений за замовчуванням, без належності провайдеру. Якщо якісь відсутні, doctor повідомляє пакети та встановлює їх у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Зовнішні plugins і далі використовують `openclaw plugins install` / `openclaw plugins update`; doctor не встановлює залежності для довільних шляхів plugins.
|
||||
|
||||
Під час відновлення doctor встановлення npm runtime-залежностей вбудованих plugins показує перебіг через spinner у TTY-сесіях і періодичний рядковий прогрес у piped/headless-виводі. Gateway і локальний CLI також можуть на вимогу відновлювати runtime-залежності активних вбудованих plugins перед імпортом вбудованого plugin. Ці встановлення обмежені коренем встановлення runtime plugin, виконуються з вимкненими scripts, не записують package lock і захищені блокуванням кореня встановлення, щоб паралельні запуски CLI або Gateway не змінювали те саме дерево `node_modules` одночасно.
|
||||
Під час відновлення doctor встановлення npm runtime-залежностей вбудованих plugins показують прогрес spinner у сеансах TTY і періодичний рядковий прогрес у конвеєрному/headless виводі. Gateway і локальний CLI також можуть відновлювати runtime-залежності активних вбудованих plugins на вимогу перед імпортом вбудованого plugin. Ці встановлення обмежені коренем інсталяції runtime plugin, запускаються з вимкненими скриптами, не записують package lock і захищені блокуванням кореня інсталяції, щоб одночасні запуски CLI або Gateway не змінювали те саме дерево `node_modules` одночасно.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="8. Міграції сервісу Gateway і підказки з очищення">
|
||||
Doctor виявляє застарілі сервіси gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити сервіс OpenClaw з поточним портом gateway. Він також може сканувати додаткові сервіси, схожі на gateway, і виводити підказки з очищення. Сервіси gateway OpenClaw, названі за профілем, вважаються повноцінними й не позначаються як "зайві."
|
||||
<Accordion title="8. Gateway service migrations and cleanup hints">
|
||||
Doctor виявляє застарілі служби gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити службу OpenClaw з використанням поточного порту gateway. Він також може сканувати додаткові gateway-подібні служби й друкувати підказки з очищення. Служби gateway OpenClaw з іменами профілів вважаються повноцінними та не позначаються як "додаткові".
|
||||
|
||||
На Linux, якщо сервіс gateway рівня користувача відсутній, але існує сервіс gateway OpenClaw системного рівня, doctor не встановлює автоматично другий сервіс рівня користувача. Перевірте за допомогою `openclaw gateway status --deep` або `openclaw doctor --deep`, а потім видаліть дублікат або задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли системний supervisor керує життєвим циклом gateway.
|
||||
У Linux, якщо служба gateway рівня користувача відсутня, але існує служба gateway OpenClaw системного рівня, doctor не встановлює другу службу рівня користувача автоматично. Перевірте за допомогою `openclaw gateway status --deep` або `openclaw doctor --deep`, потім видаліть дублікат або задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли життєвим циклом gateway керує системний supervisor.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="8b. Міграція Startup Matrix">
|
||||
Коли обліковий запис каналу Matrix має очікувану або придатну до виконання міграцію застарілого стану, doctor (у режимі `--fix` / `--repair`) створює знімок перед міграцією, а потім запускає best-effort кроки міграції: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки записуються в журнал, а startup триває. У режимі лише для читання (`openclaw doctor` без `--fix`) цю перевірку повністю пропускають.
|
||||
<Accordion title="8b. Startup Matrix migration">
|
||||
Коли обліковий запис каналу Matrix має очікувану або доступну до дії міграцію застарілого стану, doctor (у режимі `--fix` / `--repair`) створює знімок перед міграцією, а потім виконує кроки міграції best-effort: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки записуються в журнал, а запуск продовжується. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається.
|
||||
</Accordion>
|
||||
<Accordion title="8c. Сполучення пристрою та розбіжність auth">
|
||||
Doctor тепер перевіряє стан device-pairing у межах звичайного проходу перевірки справності.
|
||||
<Accordion title="8c. Device pairing and auth drift">
|
||||
Doctor тепер перевіряє стан сполучення пристроїв як частину звичайної перевірки справності.
|
||||
|
||||
Що він повідомляє:
|
||||
|
||||
- очікувані запити першого сполучення
|
||||
- очікувані підвищення ролей для вже сполучених пристроїв
|
||||
- очікувані розширення scopes для вже сполучених пристроїв
|
||||
- відновлення невідповідності public-key, коли device id усе ще збігається, але ідентичність пристрою більше не відповідає схваленому запису
|
||||
- сполучені записи, яким бракує активного токена для схваленої ролі
|
||||
- сполучені токени, чиї scopes відхилилися від схваленого базового рівня сполучення
|
||||
- локальні кешовані записи device-token для поточної машини, що передують ротації токена на боці gateway або містять застарілі metadata scopes
|
||||
- очікувані підвищення scope для вже сполучених пристроїв
|
||||
- виправлення невідповідності публічного ключа, коли ідентифікатор пристрою все ще збігається, але ідентичність пристрою більше не відповідає затвердженому запису
|
||||
- сполучені записи, у яких відсутній активний токен для затвердженої ролі
|
||||
- сполучені токени, чиї scope відхилилися від затвердженої бази сполучення
|
||||
- локальні кешовані записи токенів пристрою для поточної машини, які передують ротації токена на боці gateway або містять застарілі метадані scope
|
||||
|
||||
Doctor не схвалює автоматично запити сполучення і не ротуватиме device tokens автоматично. Натомість він виводить точні наступні кроки:
|
||||
Doctor не затверджує автоматично запити сполучення й не ротує автоматично токени пристроїв. Натомість він друкує точні наступні кроки:
|
||||
|
||||
- перегляньте очікувані запити за допомогою `openclaw devices list`
|
||||
- схваліть точний запит за допомогою `openclaw devices approve <requestId>`
|
||||
- затвердьте точний запит за допомогою `openclaw devices approve <requestId>`
|
||||
- згенеруйте свіжий токен ротацією за допомогою `openclaw devices rotate --device <deviceId> --role <role>`
|
||||
- видаліть і повторно схваліть застарілий запис за допомогою `openclaw devices remove <deviceId>`
|
||||
- видаліть і повторно затвердьте застарілий запис за допомогою `openclaw devices remove <deviceId>`
|
||||
|
||||
Це закриває поширену прогалину "уже сполучено, але все ще потрібне сполучення": doctor тепер відрізняє перше сполучення від очікуваних підвищень ролі/scope та від застарілого token/device-identity drift.
|
||||
Це закриває типову прогалину "already paired but still getting pairing required": doctor тепер відрізняє перше сполучення від очікуваних підвищень ролі/scope і від застарілого токена/відхилення ідентичності пристрою.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="9. Попередження безпеки">
|
||||
Doctor видає попередження, коли provider відкритий для DM без allowlist або коли policy налаштовано небезпечним способом.
|
||||
<Accordion title="9. Security warnings">
|
||||
Doctor виводить попередження, коли провайдер відкритий для DM без allowlist або коли політику налаштовано небезпечно.
|
||||
</Accordion>
|
||||
<Accordion title="10. systemd linger (Linux)">
|
||||
Якщо виконується як systemd user service, doctor гарантує, що lingering увімкнено, щоб gateway залишався активним після logout.
|
||||
Якщо запущено як службу користувача systemd, doctor забезпечує ввімкнення lingering, щоб gateway залишався активним після виходу.
|
||||
</Accordion>
|
||||
<Accordion title="11. Стан workspace (skills, plugins і застарілі каталоги)">
|
||||
Doctor виводить підсумок стану workspace для стандартного агента:
|
||||
<Accordion title="11. Workspace status (skills, plugins, and legacy dirs)">
|
||||
Doctor друкує підсумок стану workspace для agent за замовчуванням:
|
||||
|
||||
- **Стан Skills**: кількість eligible, missing-requirements і allowlist-blocked skills.
|
||||
- **Застарілі workspace dirs**: попереджає, коли `~/openclaw` або інші застарілі workspace directories існують поряд із поточним workspace.
|
||||
- **Стан Plugin**: кількість увімкнених/вимкнених/помилкових plugins; перелік ідентифікаторів plugins для будь-яких помилок; повідомляє про можливості bundle plugin.
|
||||
- **Попередження сумісності Plugin**: позначає plugins, що мають проблеми сумісності з поточним runtime.
|
||||
- **Діагностика Plugin**: показує будь-які попередження або помилки під час завантаження, видані registry plugin.
|
||||
- **Стан Skills**: рахує придатні Skills, Skills із відсутніми вимогами та Skills, заблоковані allowlist.
|
||||
- **Застарілі каталоги workspace**: попереджає, коли `~/openclaw` або інші застарілі каталоги workspace існують поруч із поточним workspace.
|
||||
- **Стан Plugin**: рахує ввімкнені/вимкнені/помилкові plugins; перелічує ідентифікатори plugins для будь-яких помилок; повідомляє можливості bundle plugin.
|
||||
- **Попередження сумісності Plugin**: позначає plugins, які мають проблеми сумісності з поточним runtime.
|
||||
- **Діагностика Plugin**: показує будь-які попередження або помилки часу завантаження, виведені registry plugin.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="11b. Розмір bootstrap-файлу">
|
||||
Doctor перевіряє, чи bootstrap-файли workspace (наприклад `AGENTS.md`, `CLAUDE.md` або інші injected context files) близькі до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файлу raw vs. injected кількість символів, відсоток truncation, причину truncation (`max/file` або `max/total`) і загальну кількість injected characters як частку загального бюджету. Коли файли truncated або близькі до ліміту, doctor виводить поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`.
|
||||
<Accordion title="11b. Bootstrap file size">
|
||||
Doctor перевіряє, чи файли bootstrap workspace (наприклад `AGENTS.md`, `CLAUDE.md` або інші впроваджені файли контексту) близькі до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файлу кількість символів raw проти injected, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість injected символів як частку від загального бюджету. Коли файли обрізані або близькі до ліміту, doctor друкує поради для налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`.
|
||||
</Accordion>
|
||||
<Accordion title="11d. Очищення застарілого plugin каналу">
|
||||
Коли `openclaw doctor --fix` видаляє відсутній plugin каналу, він також видаляє dangling channel-scoped config, що посилалася на цей plugin: записи `channels.<id>`, heartbeat targets, які називали канал, і перевизначення `agents.*.models["<channel>/*"]`. Це запобігає boot loops Gateway, коли runtime каналу зник, але config усе ще просить gateway прив’язатися до нього.
|
||||
<Accordion title="11d. Stale channel plugin cleanup">
|
||||
Коли `openclaw doctor --fix` видаляє відсутній channel plugin, він також видаляє висячі channel-scoped налаштування, які посилалися на цей plugin: записи `channels.<id>`, цілі heartbeat, що називали channel, і перевизначення `agents.*.models["<channel>/*"]`. Це запобігає циклам запуску Gateway, коли runtime channel зник, але конфігурація все ще просить gateway прив'язатися до нього.
|
||||
</Accordion>
|
||||
<Accordion title="11c. Shell completion">
|
||||
Doctor перевіряє, чи встановлено tab completion для поточного shell (zsh, bash, fish або PowerShell):
|
||||
Doctor перевіряє, чи встановлено автодоповнення tab для поточної оболонки (zsh, bash, fish або PowerShell):
|
||||
|
||||
- Якщо profile shell використовує повільний dynamic completion pattern (`source <(openclaw completion ...)`), doctor оновлює його до швидшого варіанта cached file.
|
||||
- Якщо completion налаштовано в profile, але cache file відсутній, doctor автоматично регенерує cache.
|
||||
- Якщо completion взагалі не налаштовано, doctor пропонує встановити його (лише interactive mode; пропускається з `--non-interactive`).
|
||||
- Якщо профіль оболонки використовує повільний шаблон динамічного доповнення (`source <(openclaw completion ...)`), doctor оновлює його до швидшого варіанту кешованого файлу.
|
||||
- Якщо доповнення налаштовано в профілі, але файл кешу відсутній, doctor автоматично регенерує кеш.
|
||||
- Якщо доповнення взагалі не налаштовано, doctor пропонує встановити його (лише інтерактивний режим; пропускається з `--non-interactive`).
|
||||
|
||||
Запустіть `openclaw completion --write-state`, щоб вручну регенерувати cache.
|
||||
Запустіть `openclaw completion --write-state`, щоб регенерувати кеш вручну.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="12. Перевірки auth Gateway (локальний токен)">
|
||||
Doctor перевіряє готовність локального token auth gateway.
|
||||
<Accordion title="12. Gateway auth checks (local token)">
|
||||
Doctor перевіряє готовність локальної автентифікації токена gateway.
|
||||
|
||||
- Якщо token mode потребує token і джерела token не існує, doctor пропонує згенерувати його.
|
||||
- Якщо `gateway.auth.token` керується SecretRef, але недоступний, doctor попереджає і не перезаписує його plaintext.
|
||||
- `openclaw doctor --generate-gateway-token` примусово генерує token лише тоді, коли token SecretRef не налаштовано.
|
||||
- Якщо режим токена потребує токена, а джерела токена немає, doctor пропонує згенерувати його.
|
||||
- Якщо `gateway.auth.token` керується SecretRef, але недоступний, doctor попереджає й не перезаписує його відкритим текстом.
|
||||
- `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано SecretRef токена.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="12b. Відновлення з урахуванням SecretRef у режимі лише для читання">
|
||||
Деяким repair flows потрібно перевіряти налаштовані credentials без послаблення runtime fail-fast behavior.
|
||||
<Accordion title="12b. Read-only SecretRef-aware repairs">
|
||||
Деякі потоки відновлення мають перевіряти налаштовані облікові дані, не послаблюючи fail-fast поведінку runtime.
|
||||
|
||||
- `openclaw doctor --fix` тепер використовує ту саму read-only SecretRef summary model, що й status-family commands, для targeted config repairs.
|
||||
- Приклад: відновлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані bot credentials, коли вони доступні.
|
||||
- Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному command path, doctor повідомляє, що credential configured-but-unavailable, і пропускає auto-resolution замість crash або помилкового повідомлення, що token відсутній.
|
||||
- `openclaw doctor --fix` тепер використовує ту саму read-only модель підсумку SecretRef, що й команди сімейства status, для цільових виправлень конфігурації.
|
||||
- Приклад: виправлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані облікові дані bot, коли вони доступні.
|
||||
- Якщо токен Telegram bot налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані-але-недоступні, і пропускає автоматичне розв'язання замість збою або помилкового повідомлення, що токен відсутній.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="13. Перевірка справності Gateway + restart">
|
||||
Doctor запускає health check і пропонує restart gateway, коли він виглядає unhealthy.
|
||||
<Accordion title="13. Gateway health check + restart">
|
||||
Doctor виконує перевірку справності й пропонує перезапустити gateway, коли він виглядає несправним.
|
||||
</Accordion>
|
||||
<Accordion title="13b. Готовність пошуку пам’яті">
|
||||
Doctor перевіряє, чи налаштований embedding provider для memory search готовий для стандартного агента. Поведінка залежить від налаштованого backend і provider:
|
||||
<Accordion title="13b. Memory search readiness">
|
||||
Doctor перевіряє, чи налаштований провайдер embeddings для пошуку в пам'яті готовий для agent за замовчуванням. Поведінка залежить від налаштованого backend і провайдера:
|
||||
|
||||
- **QMD backend**: перевіряє, чи доступний і придатний до запуску binary `qmd`. Якщо ні, виводить інструкції з виправлення, зокрема npm package і можливість указати manual binary path.
|
||||
- **Явний local provider**: перевіряє local model file або розпізнаний remote/downloadable model URL. Якщо відсутній, пропонує перейти на remote provider.
|
||||
- **Явний remote provider** (`openai`, `voyage` тощо): перевіряє, чи API key присутній в environment або auth store. Якщо відсутній, виводить actionable fix hints.
|
||||
- **Auto provider**: спершу перевіряє доступність local model, а потім пробує кожен remote provider у порядку auto-selection.
|
||||
- **Backend QMD**: перевіряє, чи двійковий файл `qmd` доступний і може бути запущений. Якщо ні, друкує вказівки з виправлення, включно з пакетом npm і варіантом ручного шляху до двійкового файлу.
|
||||
- **Явний локальний провайдер**: перевіряє наявність локального файлу моделі або розпізнаної віддаленої/завантажуваної URL моделі. Якщо відсутній, пропонує перейти на віддаленого провайдера.
|
||||
- **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, що ключ API присутній у середовищі або сховищі автентифікації. Друкує дієві підказки з виправлення, якщо він відсутній.
|
||||
- **Автоматичний провайдер**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого провайдера в порядку автоматичного вибору.
|
||||
|
||||
Коли доступний cached gateway probe result (gateway був healthy на момент перевірки), doctor зіставляє його результат із config, видимою для CLI, і зазначає будь-які розбіжності. Doctor не запускає свіжий embedding ping на стандартному path; використовуйте deep memory status command, коли потрібна live provider check.
|
||||
Коли доступний кешований результат перевірки Gateway (Gateway був справним на момент перевірки), doctor зіставляє його результат із видимою для CLI конфігурацією та зазначає будь-яку невідповідність. Doctor не запускає новий embedding ping у стандартному шляху; використовуйте команду глибокого статусу пам’яті, коли потрібна жива перевірка провайдера.
|
||||
|
||||
Використовуйте `openclaw memory status --deep`, щоб перевірити embedding readiness під час runtime.
|
||||
Використайте `openclaw memory status --deep`, щоб перевірити готовність embedding під час виконання.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="14. Попередження стану каналу">
|
||||
Якщо gateway healthy, doctor запускає channel status probe і повідомляє попередження із запропонованими виправленнями.
|
||||
<Accordion title="14. Попередження про статус каналу">
|
||||
Якщо Gateway справний, doctor виконує перевірку статусу каналу й повідомляє попередження із запропонованими виправленнями.
|
||||
</Accordion>
|
||||
<Accordion title="15. Аудит конфігурації supervisor + відновлення">
|
||||
Doctor перевіряє встановлену supervisor config (launchd/systemd/schtasks) на відсутні або застарілі defaults (наприклад, systemd network-online dependencies і restart delay). Коли він знаходить невідповідність, рекомендує update і може переписати service file/task до поточних defaults.
|
||||
<Accordion title="15. Аудит і відновлення конфігурації супервізора">
|
||||
Doctor перевіряє встановлену конфігурацію супервізора (launchd/systemd/schtasks) на відсутні або застарілі стандартні параметри (наприклад, залежності systemd від network-online і затримку перезапуску). Коли він знаходить невідповідність, він рекомендує оновлення й може переписати файл служби/завдання до поточних стандартних параметрів.
|
||||
|
||||
Примітки:
|
||||
|
||||
- `openclaw doctor` запитує підтвердження перед перезаписом конфігурації супервізора.
|
||||
- `openclaw doctor --yes` приймає типові запити на виправлення.
|
||||
- `openclaw doctor` запитує підтвердження перед переписуванням конфігурації супервізора.
|
||||
- `openclaw doctor --yes` приймає стандартні запити на відновлення.
|
||||
- `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів.
|
||||
- `openclaw doctor --repair --force` перезаписує власні конфігурації супервізора.
|
||||
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу сервісу Gateway. Він усе ще повідомляє про стан сервісу й виконує виправлення, не пов’язані із сервісом, але пропускає встановлення/запуск/перезапуск/bootstrap сервісу, перезаписи конфігурації супервізора та очищення застарілих сервісів, оскільки цим життєвим циклом керує зовнішній супервізор.
|
||||
- У Linux doctor не перезаписує метадані команди/точки входу, доки відповідний systemd-unit Gateway активний. Він також ігнорує неактивні додаткові gateway-подібні unit-файли, які не є застарілими, під час сканування дублікатів сервісів, щоб супутні файли сервісів не створювали зайвого шуму очищення.
|
||||
- Якщо автентифікація токеном потребує токена, а `gateway.auth.token` керується SecretRef, встановлення/виправлення сервісу doctor перевіряє SecretRef, але не зберігає розв’язані значення токена відкритим текстом у метадані середовища сервісу супервізора.
|
||||
- Doctor виявляє керовані значення середовища сервісу на основі `.env`/SecretRef, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудовували inline, і перезаписує метадані сервісу так, щоб ці значення завантажувалися з джерела runtime замість визначення супервізора.
|
||||
- Doctor виявляє, коли команда сервісу все ще фіксує старий `--port` після зміни `gateway.port`, і перезаписує метадані сервісу на поточний порт.
|
||||
- Якщо автентифікація токеном потребує токена, а налаштований SecretRef токена не розв’язано, doctor блокує шлях встановлення/виправлення з практичними вказівками.
|
||||
- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/виправлення, доки режим не буде задано явно.
|
||||
- Для Linux user-systemd units перевірки розбіжності токена doctor тепер включають джерела і `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації сервісу.
|
||||
- Виправлення сервісу doctor відмовляються перезаписувати, зупиняти або перезапускати сервіс Gateway зі старішого бінарного файла OpenClaw, коли конфігурацію востаннє записала новіша версія. Див. [Усунення несправностей Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
|
||||
- Ви завжди можете примусово виконати повний перезапис через `openclaw gateway install --force`.
|
||||
- `openclaw doctor --repair --force` перезаписує користувацькі конфігурації супервізора.
|
||||
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу служби Gateway. Він усе ще повідомляє про стан служби й виконує відновлення, не пов’язані зі службою, але пропускає встановлення/запуск/перезапуск/bootstrap служби, переписування конфігурації супервізора та очищення застарілих служб, оскільки цим життєвим циклом керує зовнішній супервізор.
|
||||
- У Linux doctor не переписує метадані команди/точки входу, доки відповідний systemd-модуль Gateway активний. Він також ігнорує неактивні додаткові не застарілі модулі, схожі на Gateway, під час пошуку дубльованих служб, щоб супутні файли служб не створювали зайвого шуму очищення.
|
||||
- Якщо автентифікація токеном вимагає токен і `gateway.auth.token` керується через SecretRef, встановлення/відновлення служби doctor перевіряє SecretRef, але не зберігає розв’язані значення токена у відкритому тексті в метаданих середовища служби супервізора.
|
||||
- Doctor виявляє керовані значення середовища служби на основі `.env`/SecretRef, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудовували inline, і переписує метадані служби так, щоб ці значення завантажувалися з runtime-джерела, а не з визначення супервізора.
|
||||
- Doctor виявляє, коли команда служби все ще фіксує старий `--port` після зміни `gateway.port`, і переписує метадані служби на поточний порт.
|
||||
- Якщо автентифікація токеном вимагає токен, а налаштований SecretRef токена не розв’язується, doctor блокує шлях встановлення/відновлення з практичними вказівками.
|
||||
- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/відновлення, доки режим не буде задано явно.
|
||||
- Для Linux user-systemd-модулів перевірки розбіжності токена doctor тепер включають джерела `Environment=` і `EnvironmentFile=` під час порівняння метаданих автентифікації служби.
|
||||
- Відновлення служби doctor відмовляються переписувати, зупиняти або перезапускати службу Gateway зі старішого бінарного файлу OpenClaw, коли конфігурацію востаннє було записано новішою версією. Див. [усунення проблем Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
|
||||
- Ви завжди можете примусово виконати повне переписування через `openclaw gateway install --force`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="16. Діагностика середовища виконання Gateway + порту">
|
||||
Doctor перевіряє runtime сервісу (PID, останній стан виходу) і попереджає, коли сервіс установлено, але фактично він не працює. Він також перевіряє конфлікти портів на порту Gateway (типово `18789`) і повідомляє ймовірні причини (Gateway уже запущено, SSH-тунель).
|
||||
<Accordion title="16. Діагностика runtime Gateway і порту">
|
||||
Doctor перевіряє runtime служби (PID, останній статус виходу) і попереджає, коли служба встановлена, але фактично не працює. Він також перевіряє конфлікти портів на порту Gateway (стандартно `18789`) і повідомляє ймовірні причини (Gateway уже запущено, SSH-тунель).
|
||||
</Accordion>
|
||||
<Accordion title="17. Рекомендовані практики середовища виконання Gateway">
|
||||
Doctor попереджає, коли сервіс Gateway працює на Bun або за керованим версіями шляхом Node (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджерів версій можуть ламатися після оновлень, бо сервіс не завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системне встановлення Node, коли воно доступне (Homebrew/apt/choco).
|
||||
<Accordion title="17. Найкращі практики runtime Gateway">
|
||||
Doctor попереджає, коли служба Gateway працює на Bun або шляху Node, керованому менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджера версій можуть ламатися після оновлень, оскільки служба не завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системне встановлення Node, коли воно доступне (Homebrew/apt/choco).
|
||||
|
||||
Нововстановлені або виправлені сервіси зберігають явні корені середовища (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) і стабільні користувацькі bin-каталоги, але вгадані fallback-каталоги менеджерів версій записуються до service PATH лише тоді, коли ці каталоги існують на диску. Це тримає згенерований supervisor PATH узгодженим із тим самим аудитом мінімального PATH, який doctor запускає пізніше.
|
||||
Нововстановлені або відновлені служби зберігають явні корені середовища (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) і стабільні каталоги user-bin, але припущені резервні каталоги менеджера версій записуються до service PATH лише тоді, коли ці каталоги існують на диску. Це тримає згенерований supervisor PATH узгодженим із тим самим аудитом мінімального PATH, який doctor запускає пізніше.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="18. Запис конфігурації + метадані майстра">
|
||||
Doctor зберігає всі зміни конфігурації та ставить мітку метаданих майстра, щоб зафіксувати запуск doctor.
|
||||
<Accordion title="18. Запис конфігурації та метадані майстра">
|
||||
Doctor зберігає будь-які зміни конфігурації та ставить мітку метаданих майстра, щоб зафіксувати запуск doctor.
|
||||
</Accordion>
|
||||
<Accordion title="19. Поради щодо робочого простору (резервна копія + система пам’яті)">
|
||||
Doctor пропонує систему пам’яті робочого простору, якщо її немає, і виводить пораду щодо резервного копіювання, якщо робочий простір ще не перебуває під git.
|
||||
Doctor пропонує систему пам’яті робочого простору, коли її бракує, і друкує пораду щодо резервного копіювання, якщо робочий простір ще не перебуває під git.
|
||||
|
||||
Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб отримати повний посібник зі структури робочого простору та резервного копіювання git (рекомендовано приватний GitHub або GitLab).
|
||||
|
||||
@ -489,4 +494,4 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
## Пов’язане
|
||||
|
||||
- [Runbook Gateway](/uk/gateway)
|
||||
- [Усунення несправностей Gateway](/uk/gateway/troubleshooting)
|
||||
- [Усунення проблем Gateway](/uk/gateway/troubleshooting)
|
||||
|
||||
@ -1,38 +1,36 @@
|
||||
---
|
||||
read_when:
|
||||
- Встановлення або налаштування Pluginів
|
||||
- Розуміння правил виявлення та завантаження Plugin
|
||||
- Встановлення або налаштування плагінів
|
||||
- Розуміння правил виявлення та завантаження плагінів
|
||||
- Робота з пакетами Plugin, сумісними з Codex/Claude
|
||||
sidebarTitle: Install and Configure
|
||||
summary: Установлення, налаштування та керування Plugin-и OpenClaw
|
||||
summary: Встановлюйте, налаштовуйте та керуйте плагінами OpenClaw
|
||||
title: Plugins
|
||||
x-i18n:
|
||||
generated_at: "2026-04-29T05:41:50Z"
|
||||
generated_at: "2026-05-01T04:39:26Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 7a12d158053c13b47a56d8d6b382818962e9b5109fdf8ededd3ecf92b83089e6
|
||||
source_hash: 69f876df0c2ed3ff356ada9462b56f2b5a65a662b64b328ecc97d8b463036934
|
||||
source_path: tools/plugin.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Плагіни розширюють OpenClaw новими можливостями: каналами, постачальниками моделей,
|
||||
обв’язками агентів, інструментами, skills, мовленням, realtime-транскрипцією, realtime-
|
||||
голосом, розумінням медіа, генерацією зображень, генерацією відео, web fetch, web
|
||||
search тощо. Деякі плагіни є **core** (постачаються з OpenClaw), інші
|
||||
Плагіни розширюють OpenClaw новими можливостями: канали, провайдери моделей,
|
||||
агентні середовища, інструменти, Skills, мовлення, транскрипція в реальному часі, голос у реальному часі, розуміння медіа, генерація зображень, генерація відео, веб-отримання, веб-пошук тощо. Деякі плагіни є **основними** (постачаються з OpenClaw), інші
|
||||
є **зовнішніми**. Більшість зовнішніх плагінів публікуються й знаходяться через
|
||||
[ClawHub](/uk/tools/clawhub). Npm залишається підтримуваним для прямих встановлень і для
|
||||
тимчасового набору пакетів Plugin, що належать OpenClaw, доки ця міграція завершується.
|
||||
[ClawHub](/uk/tools/clawhub). Npm і надалі підтримується для прямих встановлень і для
|
||||
тимчасового набору пакетів плагінів, що належать OpenClaw, доки ця міграція завершується.
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
<Steps>
|
||||
<Step title="Подивіться, що завантажено">
|
||||
<Step title="Перегляньте, що завантажено">
|
||||
```bash
|
||||
openclaw plugins list
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Встановіть Plugin">
|
||||
<Step title="Установіть плагін">
|
||||
```bash
|
||||
# From npm
|
||||
openclaw plugins install npm:@acme/openclaw-plugin
|
||||
@ -54,7 +52,7 @@ search тощо. Деякі плагіни є **core** (постачаються
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Якщо ви віддаєте перевагу керуванню, вбудованому в чат, увімкніть `commands.plugins: true` і використовуйте:
|
||||
Якщо ви віддаєте перевагу керуванню, природному для чату, увімкніть `commands.plugins: true` і використовуйте:
|
||||
|
||||
```text
|
||||
/plugin install clawhub:<package>
|
||||
@ -62,70 +60,70 @@ search тощо. Деякі плагіни є **core** (постачаються
|
||||
/plugin enable <plugin-id>
|
||||
```
|
||||
|
||||
Шлях встановлення використовує той самий резолвер, що й CLI: локальний шлях/архів, явний
|
||||
`clawhub:<pkg>`, явний `npm:<pkg>` або проста специфікація пакета (спочатку ClawHub, потім
|
||||
Шлях установлення використовує той самий резолвер, що й CLI: локальний шлях/архів, явний
|
||||
`clawhub:<pkg>`, явний `npm:<pkg>` або специфікація пакета без префікса (спочатку ClawHub, потім
|
||||
резервний npm).
|
||||
|
||||
Якщо конфігурація недійсна, встановлення зазвичай відмовляється виконуватися безпечно й спрямовує вас до
|
||||
`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях перевстановлення
|
||||
вбудованого Plugin для плагінів, які явно вмикають
|
||||
Якщо конфігурація недійсна, установлення зазвичай завершується закрито й указує на
|
||||
`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях перевстановлення вбудованого плагіна
|
||||
для плагінів, які явно вмикають
|
||||
`openclaw.install.allowInvalidConfigRecovery`.
|
||||
Під час запуску Gateway недійсна конфігурація одного Plugin ізолюється до цього Plugin:
|
||||
запуск записує проблему `plugins.entries.<id>.config` у журнали, пропускає цей Plugin під час
|
||||
завантаження та залишає інші плагіни й канали онлайн. Запустіть `openclaw doctor --fix`,
|
||||
щоб помістити погану конфігурацію Plugin у карантин, вимкнувши цей запис Plugin і видаливши
|
||||
його недійсне корисне навантаження конфігурації; звичайна резервна копія конфігурації зберігає попередні значення.
|
||||
Коли конфігурація каналу посилається на Plugin, який більше неможливо знайти, але той самий
|
||||
застарілий id Plugin залишається в конфігурації Plugin або записах встановлення, запуск Gateway
|
||||
Під час запуску Gateway недійсна конфігурація одного плагіна ізолюється лише до цього плагіна:
|
||||
запуск записує в журнал проблему `plugins.entries.<id>.config`, пропускає цей плагін під час
|
||||
завантаження й залишає інші плагіни та канали онлайн. Запустіть `openclaw doctor --fix`,
|
||||
щоб помістити погану конфігурацію плагіна в карантин, вимкнувши цей запис плагіна та видаливши
|
||||
його недійсне конфігураційне навантаження; звичайна резервна копія конфігурації зберігає попередні значення.
|
||||
Коли конфігурація каналу посилається на плагін, який більше неможливо знайти, але той самий
|
||||
застарілий ідентифікатор плагіна залишається в конфігурації плагінів або записах установлення, запуск Gateway
|
||||
записує попередження й пропускає цей канал замість блокування всіх інших каналів.
|
||||
Запустіть `openclaw doctor --fix`, щоб видалити застарілі записи каналу/Plugin; невідомі
|
||||
ключі каналів без ознак застарілого Plugin все ще не проходять валідацію, щоб друкарські помилки залишалися
|
||||
Запустіть `openclaw doctor --fix`, щоб видалити застарілі записи каналів/плагінів; невідомі
|
||||
ключі каналів без доказів застарілого плагіна все одно не проходять валідацію, щоб помилки друку залишалися
|
||||
видимими.
|
||||
Якщо встановлено `plugins.enabled: false`, застарілі посилання на Plugin розглядаються як інертні:
|
||||
запуск Gateway пропускає роботу з виявлення/завантаження Plugin, а `openclaw doctor` зберігає
|
||||
вимкнену конфігурацію Plugin замість її автоматичного видалення. Знову ввімкніть плагіни перед
|
||||
очищенням через doctor, якщо хочете видалити застарілі id Plugin.
|
||||
Якщо встановлено `plugins.enabled: false`, застарілі посилання на плагіни розглядаються як неактивні:
|
||||
запуск Gateway пропускає виявлення/завантаження плагінів, а `openclaw doctor` зберігає
|
||||
вимкнену конфігурацію плагінів замість автоматичного видалення її. Знову ввімкніть плагіни перед
|
||||
запуском очищення doctor, якщо хочете видалити застарілі ідентифікатори плагінів.
|
||||
|
||||
Пакетні встановлення OpenClaw не встановлюють завчасно дерево runtime-залежностей кожного
|
||||
вбудованого Plugin. Коли вбудований Plugin, що належить OpenClaw, активний із
|
||||
конфігурації Plugin, застарілої конфігурації каналу або типово ввімкненого маніфесту, запуск
|
||||
відновлює лише оголошені runtime-залежності цього Plugin перед його імпортом.
|
||||
Пакетовані встановлення OpenClaw не встановлюють наперед усе дерево runtime-залежностей кожного вбудованого плагіна.
|
||||
Коли вбудований плагін, що належить OpenClaw, активний із
|
||||
конфігурації плагінів, застарілої конфігурації каналу або маніфесту, увімкненого за замовчуванням, запуск
|
||||
відновлює лише runtime-залежності, оголошені цим плагіном, перед його імпортом.
|
||||
Сам лише збережений стан автентифікації каналу не активує вбудований канал для
|
||||
відновлення runtime-залежностей під час запуску Gateway.
|
||||
Явне вимкнення усе ще має пріоритет: `plugins.entries.<id>.enabled: false`,
|
||||
`plugins.deny`, `plugins.enabled: false` і `channels.<id>.enabled: false`
|
||||
запобігають автоматичному відновленню вбудованих runtime-залежностей для цього Plugin/каналу.
|
||||
Непорожній `plugins.allow` також обмежує відновлення типово ввімкнених вбудованих runtime-залежностей;
|
||||
явне ввімкнення вбудованого каналу (`channels.<id>.enabled: true`) все ще може
|
||||
відновити залежності Plugin цього каналу.
|
||||
Зовнішні плагіни й користувацькі шляхи завантаження все ще потрібно встановлювати через
|
||||
запобігають автоматичному відновленню вбудованих runtime-залежностей для цього плагіна/каналу.
|
||||
Непорожній `plugins.allow` також обмежує відновлення вбудованих runtime-залежностей,
|
||||
увімкнених за замовчуванням; явне ввімкнення вбудованого каналу (`channels.<id>.enabled: true`) усе ще може
|
||||
відновити залежності плагіна цього каналу.
|
||||
Зовнішні плагіни й користувацькі шляхи завантаження все одно мають бути встановлені через
|
||||
`openclaw plugins install`.
|
||||
|
||||
## Типи Plugin
|
||||
|
||||
OpenClaw розпізнає два формати Plugin:
|
||||
OpenClaw розпізнає два формати плагінів:
|
||||
|
||||
| Формат | Як це працює | Приклади |
|
||||
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
|
||||
| **Native** | `openclaw.plugin.json` + runtime-модуль; виконується в процесі | Офіційні плагіни, спільнотні npm-пакети |
|
||||
| **Bundle** | Сумісна з Codex/Claude/Cursor структура; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
|
||||
| **Нативний** | `openclaw.plugin.json` + runtime-модуль; виконується в процесі | Офіційні плагіни, npm-пакети спільноти |
|
||||
| **Bundle** | Макет, сумісний із Codex/Claude/Cursor; зіставляється з функціями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
|
||||
|
||||
Обидва відображаються в `openclaw plugins list`. Див. [Пакети Plugin](/uk/plugins/bundles), щоб дізнатися подробиці про bundle.
|
||||
Обидва відображаються в `openclaw plugins list`. Див. [Plugin Bundles](/uk/plugins/bundles) для деталей про bundle.
|
||||
|
||||
Якщо ви пишете native Plugin, почніть із [Створення Plugin](/uk/plugins/building-plugins)
|
||||
та [Огляду Plugin SDK](/uk/plugins/sdk-overview).
|
||||
Якщо ви пишете нативний плагін, почніть із [Створення плагінів](/uk/plugins/building-plugins)
|
||||
і [Огляду Plugin SDK](/uk/plugins/sdk-overview).
|
||||
|
||||
## Точки входу пакета
|
||||
|
||||
Npm-пакети native Plugin мають оголошувати `openclaw.extensions` у `package.json`.
|
||||
Кожен запис має залишатися всередині директорії пакета й резолвитися до придатного для читання
|
||||
runtime-файла або до вихідного TypeScript-файла з виведеним побудованим JavaScript-
|
||||
відповідником, наприклад `src/index.ts` до `dist/index.js`.
|
||||
Нативні npm-пакети плагінів мають оголошувати `openclaw.extensions` у `package.json`.
|
||||
Кожен запис має залишатися всередині директорії пакета й резолвитися в читабельний
|
||||
runtime-файл або у TypeScript-файл вихідного коду з виведеним зібраним JavaScript-
|
||||
аналогом, наприклад `src/index.ts` до `dist/index.js`.
|
||||
|
||||
Використовуйте `openclaw.runtimeExtensions`, коли опубліковані runtime-файли не розташовані за
|
||||
тими самими шляхами, що й вихідні записи. Якщо `runtimeExtensions` присутній, він має містити
|
||||
рівно один запис для кожного запису `extensions`. Невідповідні списки призводять до помилки встановлення й
|
||||
виявлення Plugin замість мовчазного повернення до вихідних шляхів.
|
||||
тими самими шляхами, що й записи вихідного коду. Якщо `runtimeExtensions` присутній, він має містити
|
||||
рівно один запис для кожного запису `extensions`. Невідповідні списки призводять до помилки встановлення та
|
||||
виявлення плагінів, замість тихого резервного повернення до шляхів вихідного коду.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -141,14 +139,14 @@ runtime-файла або до вихідного TypeScript-файла з ви
|
||||
|
||||
### Npm-пакети, що належать OpenClaw, під час міграції
|
||||
|
||||
ClawHub є основним шляхом розповсюдження для більшості плагінів. Поточні пакетні
|
||||
випуски OpenClaw уже містять багато офіційних плагінів, тож вони не потребують
|
||||
окремих npm-встановлень у звичайних налаштуваннях. Доки кожен Plugin, що належить OpenClaw, не
|
||||
мігрує до ClawHub, OpenClaw все ще постачає деякі пакети Plugin `@openclaw/*` в
|
||||
ClawHub є основним шляхом розповсюдження для більшості плагінів. Поточні пакетовані
|
||||
релізи OpenClaw уже містять багато офіційних плагінів, тому вони не потребують
|
||||
окремих npm-встановлень у звичайних налаштуваннях. Доки кожен плагін, що належить OpenClaw,
|
||||
не мігрує до ClawHub, OpenClaw і надалі постачає деякі пакети плагінів `@openclaw/*` на
|
||||
npm для старіших/користувацьких встановлень і прямих npm-процесів.
|
||||
|
||||
Якщо npm повідомляє про пакет Plugin `@openclaw/*` як застарілий, ця версія пакета
|
||||
походить зі старішої зовнішньої лінійки пакетів. Використовуйте вбудований Plugin із
|
||||
Якщо npm повідомляє, що пакет плагіна `@openclaw/*` застарілий, ця версія пакета
|
||||
походить зі старішої лінійки зовнішніх пакетів. Використовуйте вбудований плагін із
|
||||
поточного OpenClaw або локальний checkout, доки не буде опубліковано новіший npm-пакет.
|
||||
|
||||
| Plugin | Пакет | Документація |
|
||||
@ -170,7 +168,7 @@ npm для старіших/користувацьких встановлень
|
||||
### Core (постачається з OpenClaw)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Постачальники моделей (увімкнені за замовчуванням)">
|
||||
<Accordion title="Провайдери моделей (увімкнено за замовчуванням)">
|
||||
`anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`,
|
||||
`huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`,
|
||||
`moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`,
|
||||
@ -179,21 +177,21 @@ npm для старіших/користувацьких встановлень
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Плагіни пам’яті">
|
||||
- `memory-core` — вбудований пошук пам’яті (типово через `plugins.slots.memory`)
|
||||
- `memory-lancedb` — довготривала пам’ять, що встановлюється на вимогу, з автоматичним recall/capture (встановіть `plugins.slots.memory = "memory-lancedb"`)
|
||||
- `memory-core` — вбудований пошук пам’яті (за замовчуванням через `plugins.slots.memory`)
|
||||
- `memory-lancedb` — довготривала пам’ять, що встановлюється на вимогу, з автоматичним пригадуванням/захопленням (установіть `plugins.slots.memory = "memory-lancedb"`)
|
||||
|
||||
Див. [Memory LanceDB](/uk/plugins/memory-lancedb), щоб налаштувати OpenAI-сумісні
|
||||
embeddings, приклади Ollama, обмеження recall і усунення несправностей.
|
||||
Див. [Memory LanceDB](/uk/plugins/memory-lancedb) для налаштування embeddings, сумісних з OpenAI,
|
||||
прикладів Ollama, обмежень пригадування та усунення несправностей.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Постачальники мовлення (увімкнені за замовчуванням)">
|
||||
<Accordion title="Провайдери мовлення (увімкнено за замовчуванням)">
|
||||
`elevenlabs`, `microsoft`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Інше">
|
||||
- `browser` — вбудований browser Plugin для інструмента browser, CLI `openclaw browser`, gateway-методу `browser.request`, browser runtime і типового сервісу керування браузером (увімкнений за замовчуванням; вимкніть перед заміною)
|
||||
- `copilot-proxy` — міст VS Code Copilot Proxy (вимкнений за замовчуванням)
|
||||
- `browser` — вбудований плагін браузера для browser tool, CLI `openclaw browser`, gateway-методу `browser.request`, browser runtime і сервісу керування браузером за замовчуванням (увімкнено за замовчуванням; вимкніть перед заміною)
|
||||
- `copilot-proxy` — міст VS Code Copilot Proxy (вимкнено за замовчуванням)
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -218,32 +216,38 @@ npm для старіших/користувацьких встановлень
|
||||
|
||||
| Поле | Опис |
|
||||
| ---------------- | --------------------------------------------------------- |
|
||||
| `enabled` | Головний перемикач (типово: `true`) |
|
||||
| `allow` | Список дозволених Plugin (необов’язково) |
|
||||
| `deny` | Список заборонених Plugin (необов’язково; deny має пріоритет) |
|
||||
| `load.paths` | Додаткові файли/директорії Plugin |
|
||||
| `enabled` | Головний перемикач (за замовчуванням: `true`) |
|
||||
| `allow` | Список дозволених плагінів (необов’язково) |
|
||||
| `deny` | Список заборонених плагінів (необов’язково; заборона має пріоритет) |
|
||||
| `load.paths` | Додаткові файли/директорії плагінів |
|
||||
| `slots` | Ексклюзивні селектори слотів (наприклад, `memory`, `contextEngine`) |
|
||||
| `entries.\<id\>` | Перемикачі й конфігурація для окремого Plugin |
|
||||
| `entries.\<id\>` | Перемикачі + конфігурація для окремого плагіна |
|
||||
|
||||
Зміни конфігурації **вимагають перезапуску gateway**. Якщо Gateway працює з увімкненим
|
||||
спостереженням за конфігурацією + перезапуском у процесі (типовий шлях `openclaw gateway`), цей
|
||||
перезапуск зазвичай виконується автоматично за мить після запису конфігурації.
|
||||
Немає підтримуваного шляху hot-reload для runtime-коду native Plugin або lifecycle-
|
||||
хуків; перезапустіть процес Gateway, який обслуговує живий канал, перш ніж
|
||||
очікувати, що оновлений код `register(api)`, хуки `api.on(...)`, інструменти, сервіси або
|
||||
provider/runtime-хуки будуть виконуватися.
|
||||
`plugins.allow` є ексклюзивним. Коли він непорожній, завантажуватися
|
||||
або надавати інструменти можуть лише перелічені плагіни, навіть якщо `tools.allow` містить `"*"` або конкретну
|
||||
назву інструмента, що належить плагіну. Якщо список дозволених інструментів посилається на інструменти плагінів, додайте ідентифікатори плагінів-власників
|
||||
до `plugins.allow` або видаліть `plugins.allow`; `openclaw doctor` попереджає про таку
|
||||
форму.
|
||||
|
||||
`openclaw plugins list` — це локальний знімок реєстру/конфігурації Plugin. `enabled`
|
||||
Plugin там означає, що збережений реєстр і поточна конфігурація дозволяють
|
||||
Plugin брати участь. Це не доводить, що вже запущений віддалений дочірній Gateway
|
||||
перезапустився з тим самим кодом Plugin. У налаштуваннях VPS/контейнера з
|
||||
процесами-обгортками надсилайте перезапуски до фактичного процесу `openclaw gateway run`
|
||||
або використовуйте `openclaw gateway restart` проти запущеного Gateway.
|
||||
Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway працює з відстеженням конфігурації
|
||||
та ввімкненим перезапуском у процесі (стандартний шлях `openclaw gateway`), цей
|
||||
перезапуск зазвичай виконується автоматично через мить після запису конфігурації.
|
||||
Немає підтримуваного шляху hot-reload для runtime-коду нативного плагіна або lifecycle
|
||||
hooks; перезапустіть процес Gateway, який обслуговує live-канал, перш ніж
|
||||
очікувати виконання оновленого коду `register(api)`, hooks `api.on(...)`, інструментів, сервісів або
|
||||
provider/runtime hooks.
|
||||
|
||||
<Accordion title="Стани Plugin: вимкнений vs відсутній vs недійсний">
|
||||
- **Вимкнений**: Plugin існує, але правила ввімкнення його вимкнули. Конфігурація зберігається.
|
||||
- **Відсутній**: конфігурація посилається на id Plugin, який виявлення не знайшло.
|
||||
- **Недійсний**: Plugin існує, але його конфігурація не відповідає оголошеній схемі. Запуск Gateway пропускає лише цей Plugin; `openclaw doctor --fix` може помістити недійсний запис у карантин, вимкнувши його й видаливши його корисне навантаження конфігурації.
|
||||
`openclaw plugins list` — це локальний знімок реєстру/конфігурації плагінів. Плагін
|
||||
`enabled` там означає, що збережений реєстр і поточна конфігурація дозволяють
|
||||
плагіну брати участь. Це не доводить, що вже запущений віддалений дочірній процес Gateway
|
||||
перезапустився в той самий код плагіна. У налаштуваннях VPS/container із
|
||||
wrapper-процесами надсилайте перезапуски до фактичного процесу `openclaw gateway run`
|
||||
або використовуйте `openclaw gateway restart` щодо запущеного Gateway.
|
||||
|
||||
<Accordion title="Стани плагіна: вимкнений, відсутній, недійсний">
|
||||
- **Вимкнений**: плагін існує, але правила ввімкнення вимкнули його. Конфігурація зберігається.
|
||||
- **Відсутній**: конфігурація посилається на ідентифікатор плагіна, який виявлення не знайшло.
|
||||
- **Недійсний**: плагін існує, але його конфігурація не відповідає оголошеній схемі. Запуск Gateway пропускає лише цей плагін; `openclaw doctor --fix` може помістити недійсний запис у карантин, вимкнувши його та видаливши його конфігураційне навантаження.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -253,76 +257,76 @@ OpenClaw сканує плагіни в такому порядку (перши
|
||||
|
||||
<Steps>
|
||||
<Step title="Шляхи конфігурації">
|
||||
`plugins.load.paths` — явні шляхи до файлів або директорій. Шляхи, що вказують
|
||||
назад на власні пакетні директорії вбудованих Plugin OpenClaw, ігноруються;
|
||||
запустіть `openclaw doctor --fix`, щоб видалити ці застарілі псевдоніми.
|
||||
`plugins.load.paths` — явні шляхи до файлів або каталогів. Шляхи, що вказують
|
||||
назад на власні упаковані каталоги вбудованих Plugin OpenClaw, ігноруються;
|
||||
запустіть `openclaw doctor --fix`, щоб прибрати ці застарілі псевдоніми.
|
||||
</Step>
|
||||
|
||||
<Step title="Плагіни робочого простору">
|
||||
<Step title="Plugin робочої області">
|
||||
`\<workspace\>/.openclaw/<plugin-root>/*.ts` і `\<workspace\>/.openclaw/<plugin-root>/*/index.ts`.
|
||||
</Step>
|
||||
|
||||
<Step title="Глобальні плагіни">
|
||||
<Step title="Глобальні Plugin">
|
||||
`~/.openclaw/<plugin-root>/*.ts` і `~/.openclaw/<plugin-root>/*/index.ts`.
|
||||
</Step>
|
||||
|
||||
<Step title="Bundled plugins">
|
||||
<Step title="Вбудовані Plugin">
|
||||
Постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (провайдери моделей, мовлення).
|
||||
Інші потребують явного ввімкнення.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Пакетні інсталяції та Docker-образи зазвичай розв’язують bundled plugins із
|
||||
скомпільованого дерева `dist/extensions`. Якщо вихідний каталог bundled plugin
|
||||
змонтовано поверх відповідного пакетного шляху до вихідного коду, наприклад
|
||||
Упаковані встановлення та образи Docker зазвичай вирішують вбудовані Plugin з
|
||||
скомпільованого дерева `dist/extensions`. Якщо вихідний каталог вбудованого Plugin
|
||||
змонтовано поверх відповідного упакованого шляху до джерел, наприклад
|
||||
`/app/extensions/synology-chat`, OpenClaw розглядає цей змонтований вихідний каталог
|
||||
як bundled source overlay і виявляє його перед пакетним бандлом
|
||||
`/app/dist/extensions/synology-chat`. Це зберігає працездатність контейнерних
|
||||
циклів для мейнтейнерів без потреби перемикати кожен bundled plugin назад на
|
||||
вихідний код TypeScript. Встановіть `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`,
|
||||
щоб примусово використовувати пакетні dist-бандли навіть за наявності змонтованих
|
||||
source overlay.
|
||||
як накладку джерел вбудованого Plugin і виявляє його перед упакованим
|
||||
бандлом `/app/dist/extensions/synology-chat`. Це зберігає працездатність
|
||||
контейнерних циклів супровідників без перемикання кожного вбудованого Plugin
|
||||
назад на джерела TypeScript. Установіть `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`,
|
||||
щоб примусово використовувати упаковані бандли dist навіть за наявності
|
||||
змонтованих накладок джерел.
|
||||
|
||||
### Правила ввімкнення
|
||||
|
||||
- `plugins.enabled: false` вимикає всі plugins і пропускає роботу з виявлення/завантаження plugins
|
||||
- `plugins.enabled: false` вимикає всі Plugin і пропускає роботу з виявлення/завантаження Plugin
|
||||
- `plugins.deny` завжди має перевагу над allow
|
||||
- `plugins.entries.\<id\>.enabled: false` вимикає цей plugin
|
||||
- Plugins із походженням workspace **вимкнені за замовчуванням** (їх потрібно явно ввімкнути)
|
||||
- Bundled plugins дотримуються вбудованого набору, увімкненого за замовчуванням, якщо це не перевизначено
|
||||
- Ексклюзивні слоти можуть примусово ввімкнути вибраний plugin для цього слота
|
||||
- Деякі bundled opt-in plugins вмикаються автоматично, коли конфігурація називає
|
||||
поверхню, що належить plugin, як-от посилання на модель провайдера, конфігурацію каналу або
|
||||
runtime harness
|
||||
- Застаріла конфігурація plugin зберігається, доки активний `plugins.enabled: false`;
|
||||
повторно ввімкніть plugins перед запуском очищення doctor, якщо хочете видалити застарілі id
|
||||
- Маршрути Codex родини OpenAI зберігають окремі межі plugins:
|
||||
`openai-codex/*` належить OpenAI plugin, тоді як bundled Codex
|
||||
app-server plugin вибирається через `agentRuntime.id: "codex"` або застарілі
|
||||
- `plugins.entries.\<id\>.enabled: false` вимикає цей Plugin
|
||||
- Plugin з робочої області **вимкнені за замовчуванням** (їх потрібно явно ввімкнути)
|
||||
- Вбудовані Plugin дотримуються вбудованого набору, увімкненого за замовчуванням, якщо це не перевизначено
|
||||
- Ексклюзивні слоти можуть примусово ввімкнути вибраний Plugin для цього слота
|
||||
- Деякі вбудовані opt-in Plugin вмикаються автоматично, коли конфігурація називає
|
||||
поверхню, що належить Plugin, як-от посилання на модель провайдера, конфігурацію каналу або
|
||||
середовище виконання harness
|
||||
- Застаріла конфігурація Plugin зберігається, доки активне `plugins.enabled: false`;
|
||||
повторно ввімкніть Plugin перед запуском очищення doctor, якщо хочете видалити застарілі id
|
||||
- Маршрути Codex родини OpenAI зберігають окремі межі Plugin:
|
||||
`openai-codex/*` належить Plugin OpenAI, тоді як вбудований Plugin сервера застосунку Codex
|
||||
вибирається через `agentRuntime.id: "codex"` або застарілі
|
||||
посилання на моделі `codex/*`
|
||||
|
||||
## Усунення проблем із runtime hooks
|
||||
|
||||
Якщо plugin з’являється в `plugins list`, але побічні ефекти `register(api)` або hooks
|
||||
не виконуються в живому чат-трафіку, спершу перевірте це:
|
||||
Якщо Plugin відображається в `plugins list`, але побічні ефекти або hooks
|
||||
`register(api)` не виконуються в живому трафіку чату, спершу перевірте таке:
|
||||
|
||||
- Запустіть `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні
|
||||
URL Gateway, профіль, шлях до конфігурації та процес є саме тими, які ви редагуєте.
|
||||
- Перезапустіть живий Gateway після змін встановлення/config/code plugin. У wrapper
|
||||
containers PID 1 може бути лише supervisor; перезапустіть або надішліть сигнал дочірньому
|
||||
URL Gateway, профіль, шлях конфігурації та процес є тими, які ви редагуєте.
|
||||
- Перезапустіть живий Gateway після змін встановлення/конфігурації/коду Plugin. У wrapper
|
||||
контейнерах PID 1 може бути лише supervisor; перезапустіть або надішліть сигнал дочірньому
|
||||
процесу `openclaw gateway run`.
|
||||
- Використайте `openclaw plugins inspect <id> --json`, щоб підтвердити реєстрації hooks і
|
||||
діагностику. Небандлованим conversation hooks, таким як `llm_input`,
|
||||
`llm_output`, `before_agent_finalize` і `agent_end`, потрібен
|
||||
- Використовуйте `openclaw plugins inspect <id> --json`, щоб підтвердити реєстрації hooks і
|
||||
діагностику. Невбудовані conversation hooks, як-от `llm_input`,
|
||||
`llm_output`, `before_agent_finalize` і `agent_end`, потребують
|
||||
`plugins.entries.<id>.hooks.allowConversationAccess=true`.
|
||||
- Для перемикання моделей віддавайте перевагу `before_model_resolve`. Він виконується перед
|
||||
розв’язанням моделі для ходів агента; `llm_output` виконується лише після того, як спроба моделі
|
||||
вирішенням моделі для ходів агента; `llm_output` виконується лише після того, як спроба моделі
|
||||
створить відповідь асистента.
|
||||
- Для доказу ефективної моделі сесії використовуйте `openclaw sessions` або
|
||||
поверхні Gateway session/status і, під час налагодження provider payloads, запускайте
|
||||
- Для підтвердження ефективної моделі сесії використовуйте `openclaw sessions` або
|
||||
поверхні сесії/статусу Gateway, а під час налагодження payload провайдера запускайте
|
||||
Gateway з `--raw-stream --raw-stream-path <path>`.
|
||||
|
||||
### Дублювання власності каналу або інструмента
|
||||
### Дублювання володіння каналом або інструментом
|
||||
|
||||
Симптоми:
|
||||
|
||||
@ -330,34 +334,34 @@ source overlay.
|
||||
- `channel setup already registered: <channel-id> (<plugin-id>)`
|
||||
- `plugin tool name conflict (<plugin-id>): <tool-name>`
|
||||
|
||||
Це означає, що більш ніж один увімкнений plugin намагається володіти тим самим каналом,
|
||||
setup flow або назвою інструмента. Найпоширеніша причина — зовнішній channel plugin,
|
||||
встановлений поряд із bundled plugin, який тепер надає той самий channel id.
|
||||
Це означає, що кілька ввімкнених Plugin намагаються володіти тим самим каналом,
|
||||
потоком налаштування або назвою інструмента. Найпоширеніша причина — зовнішній Plugin каналу,
|
||||
встановлений поруч із вбудованим Plugin, який тепер надає той самий id каналу.
|
||||
|
||||
Кроки налагодження:
|
||||
|
||||
- Запустіть `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений plugin
|
||||
- Запустіть `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений Plugin
|
||||
і його походження.
|
||||
- Запустіть `openclaw plugins inspect <id> --json` для кожного підозрюваного plugin і
|
||||
- Запустіть `openclaw plugins inspect <id> --json` для кожного підозрюваного Plugin і
|
||||
порівняйте `channels`, `channelConfigs`, `tools` і діагностику.
|
||||
- Запустіть `openclaw plugins registry --refresh` після встановлення або видалення
|
||||
plugin packages, щоб збережені метадані відображали поточну інсталяцію.
|
||||
- Перезапустіть Gateway після змін встановлення, registry або config.
|
||||
пакетів Plugin, щоб збережені метадані відображали поточне встановлення.
|
||||
- Перезапустіть Gateway після змін встановлення, реєстру або конфігурації.
|
||||
|
||||
Варіанти виправлення:
|
||||
|
||||
- Якщо один plugin навмисно замінює інший для того самого channel id, бажаний
|
||||
plugin має оголосити `channelConfigs.<channel-id>.preferOver` із
|
||||
plugin id нижчого пріоритету. Див. [/plugins/manifest#replacing-another-channel-plugin](/uk/plugins/manifest#replacing-another-channel-plugin).
|
||||
- Якщо один Plugin навмисно замінює інший для того самого id каналу, бажаний
|
||||
Plugin має оголосити `channelConfigs.<channel-id>.preferOver` з
|
||||
id Plugin нижчого пріоритету. Див. [/plugins/manifest#replacing-another-channel-plugin](/uk/plugins/manifest#replacing-another-channel-plugin).
|
||||
- Якщо дублювання випадкове, вимкніть одну сторону за допомогою
|
||||
`plugins.entries.<plugin-id>.enabled: false` або видаліть застарілу інсталяцію plugin.
|
||||
- Якщо ви явно ввімкнули обидва plugins, OpenClaw зберігає цей запит і
|
||||
повідомляє про конфлікт. Виберіть одного власника каналу або перейменуйте інструменти,
|
||||
що належать plugin, щоб runtime surface була однозначною.
|
||||
`plugins.entries.<plugin-id>.enabled: false` або видаліть застаріле встановлення Plugin.
|
||||
- Якщо ви явно ввімкнули обидва Plugin, OpenClaw зберігає цей запит і
|
||||
повідомляє про конфлікт. Виберіть одного власника для каналу або перейменуйте інструменти,
|
||||
що належать Plugin, щоб runtime-поверхня була однозначною.
|
||||
|
||||
## Слоти plugins (ексклюзивні категорії)
|
||||
## Слоти Plugin (ексклюзивні категорії)
|
||||
|
||||
Деякі категорії є ексклюзивними (одночасно активна лише одна):
|
||||
Деякі категорії є ексклюзивними (активна лише одна за раз):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -370,10 +374,10 @@ setup flow або назвою інструмента. Найпоширеніш
|
||||
}
|
||||
```
|
||||
|
||||
| Слот | Що він контролює | Значення за замовчуванням |
|
||||
| --------------- | --------------------- | ------------------------- |
|
||||
| `memory` | Active memory plugin | `memory-core` |
|
||||
| `contextEngine` | Активний context engine | `legacy` (вбудований) |
|
||||
| Слот | Що він контролює | За замовчуванням |
|
||||
| --------------- | --------------------- | ------------------- |
|
||||
| `memory` | Plugin активної пам'яті | `memory-core` |
|
||||
| `contextEngine` | Активний рушій контексту | `legacy` (вбудований) |
|
||||
|
||||
## Довідник CLI
|
||||
|
||||
@ -413,79 +417,79 @@ openclaw plugins enable <id>
|
||||
openclaw plugins disable <id>
|
||||
```
|
||||
|
||||
Bundled plugins постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (наприклад
|
||||
bundled model providers, bundled speech providers і bundled browser
|
||||
plugin). Інші bundled plugins все ще потребують `openclaw plugins enable <id>`.
|
||||
Вбудовані Plugin постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (наприклад,
|
||||
вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований браузерний
|
||||
Plugin). Інші вбудовані Plugin усе ще потребують `openclaw plugins enable <id>`.
|
||||
|
||||
`--force` перезаписує наявний встановлений plugin або hook pack на місці. Використовуйте
|
||||
`--force` перезаписує наявний установлений Plugin або hook pack на місці. Використовуйте
|
||||
`openclaw plugins update <id-or-npm-spec>` для звичайних оновлень відстежуваних npm
|
||||
plugins. Це не підтримується з `--link`, який повторно використовує вихідний шлях замість
|
||||
копіювання в керовану ціль інсталяції.
|
||||
Plugin. Це не підтримується з `--link`, який повторно використовує вихідний шлях замість
|
||||
копіювання до керованої цілі встановлення.
|
||||
|
||||
Коли `plugins.allow` уже задано, `openclaw plugins install` додає
|
||||
id встановленого plugin до цього allowlist перед його ввімкненням. Якщо той самий plugin id
|
||||
присутній у `plugins.deny`, install видаляє цей застарілий deny-запис, щоб
|
||||
явно встановлений plugin можна було одразу завантажити після перезапуску.
|
||||
id установленого Plugin до цього allowlist перед його ввімкненням. Якщо той самий id Plugin
|
||||
наявний у `plugins.deny`, install видаляє цей застарілий запис deny, щоб
|
||||
явне встановлення можна було завантажити відразу після перезапуску.
|
||||
|
||||
OpenClaw зберігає локальний registry plugins як cold read model для
|
||||
інвентаризації plugins, власності внесків і планування запуску. Потоки install, update,
|
||||
uninstall, enable і disable оновлюють цей registry після зміни стану plugin.
|
||||
Той самий файл `plugins/installs.json` зберігає тривкі install metadata у
|
||||
верхньорівневому `installRecords` і перебудовувані manifest metadata у `plugins`. Якщо
|
||||
registry відсутній, застарілий або недійсний, `openclaw plugins registry
|
||||
--refresh` перебудовує його manifest view із install records, config policy і
|
||||
metadata manifest/package без завантаження runtime modules plugin.
|
||||
`openclaw plugins update <id-or-npm-spec>` застосовується до відстежуваних інсталяцій. Передавання
|
||||
npm package spec із dist-tag або точною версією розв’язує назву package
|
||||
назад до відстежуваного запису plugin і записує новий spec для майбутніх оновлень.
|
||||
Передавання назви package без версії повертає точну pinned install назад до
|
||||
типової release line registry. Якщо встановлений npm plugin уже відповідає
|
||||
розв’язаній версії та записаній artifact identity, OpenClaw пропускає оновлення
|
||||
без завантаження, перевстановлення або переписування config.
|
||||
OpenClaw зберігає постійний локальний реєстр Plugin як модель холодного читання для
|
||||
інвентаризації Plugin, володіння внесками та планування запуску. Потоки install, update,
|
||||
uninstall, enable і disable оновлюють цей реєстр після зміни стану Plugin.
|
||||
Той самий файл `plugins/installs.json` зберігає довговічні метадані встановлення у
|
||||
верхньорівневому `installRecords` і перебудовувані метадані manifest у `plugins`. Якщо
|
||||
реєстр відсутній, застарілий або недійсний, `openclaw plugins registry
|
||||
--refresh` перебудовує його представлення manifest із записів встановлення, політики конфігурації та
|
||||
метаданих manifest/package без завантаження runtime-модулів Plugin.
|
||||
`openclaw plugins update <id-or-npm-spec>` застосовується до відстежуваних встановлень. Передавання
|
||||
специфікації npm-пакета з dist-tag або точною версією зіставляє назву пакета
|
||||
назад із відстежуваним записом Plugin і записує нову специфікацію для майбутніх оновлень.
|
||||
Передавання назви пакета без версії повертає точно закріплене встановлення до
|
||||
стандартної release line реєстру. Якщо встановлений npm Plugin уже відповідає
|
||||
вирішеній версії та записаній ідентичності артефакту, OpenClaw пропускає оновлення
|
||||
без завантаження, перевстановлення або переписування конфігурації.
|
||||
|
||||
`--pin` працює лише для npm. Він не підтримується з `--marketplace`, тому що
|
||||
marketplace installs зберігають metadata джерела marketplace замість npm spec.
|
||||
`--pin` призначений лише для npm. Він не підтримується з `--marketplace`, тому що
|
||||
marketplace-встановлення зберігають метадані джерела marketplace замість npm-специфікації.
|
||||
|
||||
`--dangerously-force-unsafe-install` — break-glass перевизначення для хибних
|
||||
спрацювань вбудованого dangerous-code scanner. Воно дозволяє встановлення plugins
|
||||
і оновлення plugins продовжуватися після вбудованих знахідок `critical`, але все одно
|
||||
не обходить блокування plugin `before_install` policy або блокування через scan failure.
|
||||
Install scans ігнорують поширені тестові файли й каталоги, як-от `tests/`,
|
||||
`__tests__/`, `*.test.*` і `*.spec.*`, щоб не блокувати пакетні test mocks;
|
||||
оголошені runtime entrypoints plugin все одно скануються, навіть якщо використовують одну з
|
||||
`--dangerously-force-unsafe-install` — це аварійне перевизначення для хибних
|
||||
спрацьовувань вбудованого сканера небезпечного коду. Воно дозволяє встановленням Plugin
|
||||
і оновленням Plugin продовжуватися попри вбудовані findings рівня `critical`, але все одно
|
||||
не обходить блокування політики Plugin `before_install` або блокування через збій сканування.
|
||||
Сканування встановлення ігнорують поширені тестові файли та каталоги, як-от `tests/`,
|
||||
`__tests__/`, `*.test.*` і `*.spec.*`, щоб не блокувати упаковані тестові mocks;
|
||||
оголошені runtime entrypoints Plugin усе одно скануються, навіть якщо використовують одну з
|
||||
цих назв.
|
||||
|
||||
Цей прапорець CLI застосовується лише до потоків install/update plugin. Встановлення залежностей
|
||||
Skills на базі Gateway натомість використовують відповідне перевизначення запиту
|
||||
`dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` лишається окремим
|
||||
потоком завантаження/встановлення Skills із ClawHub.
|
||||
Цей прапорець CLI застосовується лише до потоків встановлення/оновлення Plugin. Встановлення
|
||||
залежностей Skills на базі Gateway натомість використовують відповідне перевизначення запиту
|
||||
`dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком
|
||||
завантаження/встановлення Skills з ClawHub.
|
||||
|
||||
Якщо plugin, який ви опублікували на ClawHub, приховано або заблоковано скануванням, відкрийте
|
||||
панель ClawHub або запустіть `clawhub package rescan <name>`, щоб попросити ClawHub перевірити
|
||||
його знову. `--dangerously-force-unsafe-install` впливає лише на встановлення на вашій власній
|
||||
машині; він не просить ClawHub пересканувати plugin і не робить заблокований release
|
||||
публічним.
|
||||
Якщо Plugin, який ви опублікували на ClawHub, приховано або заблоковано скануванням, відкрийте
|
||||
панель ClawHub або запустіть `clawhub package rescan <name>`, щоб попросити ClawHub
|
||||
перевірити його знову. `--dangerously-force-unsafe-install` впливає лише на встановлення на вашому
|
||||
власному комп'ютері; він не просить ClawHub повторно сканувати Plugin або робити заблокований
|
||||
реліз публічним.
|
||||
|
||||
Сумісні bundles беруть участь у тому самому потоці list/inspect/enable/disable plugins.
|
||||
Поточна підтримка runtime включає bundle skills, Claude command-skills,
|
||||
типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і оголошені в manifest
|
||||
`lspServers`, Cursor command-skills і сумісні каталоги Codex hook.
|
||||
Сумісні бандли беруть участь у тому самому потоці list/inspect/enable/disable для Plugin.
|
||||
Поточна підтримка runtime включає bundle skills, command-skills Claude,
|
||||
стандартні значення Claude `settings.json`, стандартні значення Claude `.lsp.json` і оголошені в manifest
|
||||
`lspServers`, command-skills Cursor і сумісні каталоги hooks Codex.
|
||||
|
||||
`openclaw plugins inspect <id>` також повідомляє про виявлені bundle capabilities, а також
|
||||
підтримувані або непідтримувані записи MCP і LSP server для plugins на основі bundle.
|
||||
`openclaw plugins inspect <id>` також повідомляє виявлені можливості бандла, а також
|
||||
підтримувані або непідтримувані записи серверів MCP і LSP для Plugin на основі бандлів.
|
||||
|
||||
Джерелами marketplace можуть бути відома назва marketplace Claude з
|
||||
`~/.claude/plugins/known_marketplaces.json`, локальний корінь marketplace або
|
||||
шлях `marketplace.json`, GitHub shorthand на кшталт `owner/repo`, URL GitHub repo
|
||||
або git URL. Для віддалених marketplaces записи plugins мають залишатися всередині
|
||||
клонованого marketplace repo і використовувати лише відносні path sources.
|
||||
Джерела marketplace можуть бути відомою назвою marketplace Claude з
|
||||
`~/.claude/plugins/known_marketplaces.json`, локальним коренем marketplace або шляхом
|
||||
`marketplace.json`, скороченням GitHub на кшталт `owner/repo`, URL репозиторію GitHub
|
||||
або git URL. Для віддалених marketplace записи Plugin мають залишатися всередині
|
||||
клонованого репозиторію marketplace і використовувати лише відносні джерела шляхів.
|
||||
|
||||
Повні подробиці див. у [довіднику CLI `openclaw plugins`](/uk/cli/plugins).
|
||||
Див. [довідник CLI `openclaw plugins`](/uk/cli/plugins) для повних подробиць.
|
||||
|
||||
## Огляд Plugin API
|
||||
## Огляд API Plugin
|
||||
|
||||
Native plugins експортують entry object, який надає `register(api)`. Старіші
|
||||
plugins можуть усе ще використовувати `activate(api)` як legacy alias, але нові plugins мають
|
||||
Нативні Plugin експортують об'єкт entry, який надає `register(api)`. Старіші
|
||||
Plugin усе ще можуть використовувати `activate(api)` як застарілий псевдонім, але нові Plugin мають
|
||||
використовувати `register`.
|
||||
|
||||
```typescript
|
||||
@ -506,65 +510,65 @@ export default definePluginEntry({
|
||||
});
|
||||
```
|
||||
|
||||
OpenClaw завантажує entry object і викликає `register(api)` під час активації plugin.
|
||||
Loader усе ще повертається до `activate(api)` для старіших plugins,
|
||||
але bundled plugins і нові external plugins мають розглядати `register` як
|
||||
публічний contract.
|
||||
OpenClaw завантажує об’єкт входу та викликає `register(api)` під час
|
||||
активації плагіна. Завантажувач досі повертається до `activate(api)` для старіших плагінів,
|
||||
але вбудовані плагіни та нові зовнішні плагіни мають вважати `register`
|
||||
публічним контрактом.
|
||||
|
||||
`api.registrationMode` повідомляє plugin, чому його entry завантажується:
|
||||
`api.registrationMode` повідомляє плагіну, чому завантажується його вхід:
|
||||
|
||||
| Режим | Значення |
|
||||
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `full` | Активація під час виконання. Реєструє інструменти, хуки, служби, команди, маршрути й інші активні побічні ефекти. |
|
||||
| `discovery` | Виявлення можливостей лише для читання. Реєструє провайдерів і метадані; код довіреної точки входу Plugin може завантажуватися, але активні побічні ефекти пропускаються. |
|
||||
| `setup-only` | Завантаження метаданих налаштування каналу через легку точку входу налаштування. |
|
||||
| `setup-runtime` | Завантаження налаштування каналу, якому також потрібна точка входу середовища виконання. |
|
||||
| `cli-metadata` | Лише збирання метаданих команд CLI. |
|
||||
| Режим | Значення |
|
||||
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `full` | Активація під час виконання. Реєструйте інструменти, хуки, сервіси, команди, маршрути та інші активні побічні ефекти. |
|
||||
| `discovery` | Виявлення можливостей лише для читання. Реєструйте провайдерів і метадані; довірений код входу плагіна може завантажуватися, але пропускайте активні побічні ефекти. |
|
||||
| `setup-only` | Завантаження метаданих налаштування каналу через полегшений вхід налаштування. |
|
||||
| `setup-runtime` | Завантаження налаштування каналу, якому також потрібен вхід середовища виконання. |
|
||||
| `cli-metadata` | Лише збирання метаданих команд CLI. |
|
||||
|
||||
Точки входу Plugin, які відкривають сокети, бази даних, фонові робочі процеси або довгоживучі
|
||||
клієнти, мають захищати ці побічні ефекти за допомогою `api.registrationMode === "full"`.
|
||||
Завантаження для виявлення кешуються окремо від завантажень для активації та не замінюють
|
||||
запущений реєстр Gateway. Виявлення не активує, але не є вільним від імпорту:
|
||||
OpenClaw може виконати довірену точку входу Plugin або модуль Plugin каналу, щоб побудувати
|
||||
знімок. Тримайте верхні рівні модулів легкими й без побічних ефектів, а мережеві
|
||||
клієнти, підпроцеси, слухачі, читання облікових даних і запуск служб переносіть
|
||||
Входи плагінів, які відкривають сокети, бази даних, фонові воркери або довгоживучі
|
||||
клієнти, мають захищати ці побічні ефекти умовою `api.registrationMode === "full"`.
|
||||
Завантаження для виявлення кешуються окремо від завантажень активації та не замінюють
|
||||
поточний реєстр Gateway. Виявлення не активує, але не є вільним від імпортів:
|
||||
OpenClaw може виконати довірений вхід плагіна або модуль плагіна каналу, щоб побудувати
|
||||
знімок. Тримайте верхній рівень модулів легким і без побічних ефектів, а мережеві
|
||||
клієнти, підпроцеси, слухачі, читання облікових даних і запуск сервісів переносіть
|
||||
за шляхи повного середовища виконання.
|
||||
|
||||
Поширені методи реєстрації:
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| --------------------------------------- | ---------------------------------- |
|
||||
| `registerProvider` | Провайдер моделі (LLM) |
|
||||
| `registerChannel` | Канал чату |
|
||||
| `registerTool` | Інструмент агента |
|
||||
| `registerHook` / `on(...)` | Хуки життєвого циклу |
|
||||
| Метод | Що він реєструє |
|
||||
| --------------------------------------- | ------------------------------------- |
|
||||
| `registerProvider` | Провайдер моделі (LLM) |
|
||||
| `registerChannel` | Канал чату |
|
||||
| `registerTool` | Інструмент агента |
|
||||
| `registerHook` / `on(...)` | Хуки життєвого циклу |
|
||||
| `registerSpeechProvider` | Перетворення тексту на мовлення / STT |
|
||||
| `registerRealtimeTranscriptionProvider` | Потокове STT |
|
||||
| `registerRealtimeVoiceProvider` | Дуплексний голос у реальному часі |
|
||||
| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо |
|
||||
| `registerImageGenerationProvider` | Генерація зображень |
|
||||
| `registerMusicGenerationProvider` | Генерація музики |
|
||||
| `registerVideoGenerationProvider` | Генерація відео |
|
||||
| `registerWebFetchProvider` | Провайдер отримання вебданих / скрейпінгу |
|
||||
| `registerWebSearchProvider` | Вебпошук |
|
||||
| `registerHttpRoute` | HTTP-ендпоінт |
|
||||
| `registerCommand` / `registerCli` | Команди CLI |
|
||||
| `registerContextEngine` | Рушій контексту |
|
||||
| `registerService` | Фонова служба |
|
||||
| `registerRealtimeTranscriptionProvider` | Потокове STT |
|
||||
| `registerRealtimeVoiceProvider` | Дуплексний голос у реальному часі |
|
||||
| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо |
|
||||
| `registerImageGenerationProvider` | Генерація зображень |
|
||||
| `registerMusicGenerationProvider` | Генерація музики |
|
||||
| `registerVideoGenerationProvider` | Генерація відео |
|
||||
| `registerWebFetchProvider` | Провайдер веботримання / скрейпінгу |
|
||||
| `registerWebSearchProvider` | Вебпошук |
|
||||
| `registerHttpRoute` | HTTP-ендпойнт |
|
||||
| `registerCommand` / `registerCli` | Команди CLI |
|
||||
| `registerContextEngine` | Рушій контексту |
|
||||
| `registerService` | Фоновий сервіс |
|
||||
|
||||
Поведінка захисту хуків для типізованих хуків життєвого циклу:
|
||||
|
||||
- `before_tool_call`: `{ block: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_tool_call`: `{ block: false }` нічого не робить і не скидає попереднє блокування.
|
||||
- `before_install`: `{ block: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_install`: `{ block: false }` нічого не робить і не скидає попереднє блокування.
|
||||
- `message_sending`: `{ cancel: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються.
|
||||
- `message_sending`: `{ cancel: false }` нічого не робить і не скидає попереднє скасування.
|
||||
- `before_tool_call`: `{ block: true }` є термінальним; обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_tool_call`: `{ block: false }` нічого не робить і не скасовує попереднє блокування.
|
||||
- `before_install`: `{ block: true }` є термінальним; обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_install`: `{ block: false }` нічого не робить і не скасовує попереднє блокування.
|
||||
- `message_sending`: `{ cancel: true }` є термінальним; обробники з нижчим пріоритетом пропускаються.
|
||||
- `message_sending`: `{ cancel: false }` нічого не робить і не скасовує попереднє скасування.
|
||||
|
||||
Власний app-server Codex запускає події інструментів, нативні для Codex, через міст назад у цю
|
||||
поверхню хуків. Plugins можуть блокувати нативні інструменти Codex через `before_tool_call`,
|
||||
Запуски нативного app-server Codex передають події нативних інструментів Codex назад у цю
|
||||
поверхню хуків. Плагіни можуть блокувати нативні інструменти Codex через `before_tool_call`,
|
||||
спостерігати результати через `after_tool_call` і брати участь у схваленнях Codex
|
||||
`PermissionRequest`. Міст поки не переписує аргументи інструментів, нативних для Codex.
|
||||
`PermissionRequest`. Міст ще не переписує аргументи нативних інструментів Codex.
|
||||
Точна межа підтримки середовища виконання Codex описана в
|
||||
[контракті підтримки Codex harness v1](/uk/plugins/codex-harness#v1-support-contract).
|
||||
|
||||
@ -572,9 +576,9 @@ OpenClaw може виконати довірену точку входу Plugin
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Створення Plugins](/uk/plugins/building-plugins) — створення власного Plugin
|
||||
- [Пакети Plugin](/uk/plugins/bundles) — сумісність пакетів Codex/Claude/Cursor
|
||||
- [Маніфест Plugin](/uk/plugins/manifest) — схема маніфесту
|
||||
- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додавання інструментів агента в Plugin
|
||||
- [Внутрішня будова Plugin](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження
|
||||
- [Спільнотні Plugins](/uk/plugins/community) — сторонні списки
|
||||
- [Створення плагінів](/uk/plugins/building-plugins) — створіть власний плагін
|
||||
- [Пакети плагінів](/uk/plugins/bundles) — сумісність пакетів Codex/Claude/Cursor
|
||||
- [Маніфест плагіна](/uk/plugins/manifest) — схема маніфесту
|
||||
- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додайте інструменти агента в плагіні
|
||||
- [Внутрішня архітектура плагінів](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження
|
||||
- [Плагіни спільноти](/uk/plugins/community) — списки сторонніх плагінів
|
||||
|
||||
Loading…
Reference in New Issue
Block a user