chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
c466e0f160
commit
3d043d4eac
@ -2,26 +2,26 @@
|
||||
read_when:
|
||||
- Ви хочете читати або редагувати конфігурацію неінтерактивно
|
||||
sidebarTitle: Config
|
||||
summary: Довідка CLI для `openclaw config` (get/set/patch/unset/file/schema/validate)
|
||||
summary: Довідник CLI для `openclaw config` (get/set/patch/unset/file/schema/validate)
|
||||
title: Конфігурація
|
||||
x-i18n:
|
||||
generated_at: "2026-04-29T21:05:31Z"
|
||||
generated_at: "2026-05-03T17:11:54Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: f1f55c4b932d469cb9112d9f55b66f0ff88dbe066250651df7a0a753060a223d
|
||||
source_hash: 7be6a2ff8474fe78deb1d32dd822a4cf8a2b420dfb45306be5d7c5a1d54f0b4d
|
||||
source_path: cli/config.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Помічники конфігурації для неінтерактивних правок в `openclaw.json`: отримуйте/встановлюйте/застосовуйте patch/скидайте/виводьте файл/схему/перевіряйте значення за шляхом і друкуйте активний файл конфігурації. Запустіть без підкоманди, щоб відкрити майстер налаштування (те саме, що `openclaw configure`).
|
||||
Помічники конфігурації для неінтерактивних змін у `openclaw.json`: отримуйте/задавайте/патчте/скасовуйте/виводьте файл/схему/перевіряйте значення за шляхом і друкуйте активний файл конфігурації. Запустіть без підкоманди, щоб відкрити майстер налаштування (те саме, що `openclaw configure`).
|
||||
|
||||
## Кореневі опції
|
||||
|
||||
<ParamField path="--section <section>" type="string">
|
||||
Повторюваний фільтр розділів керованого налаштування, коли ви запускаєте `openclaw config` без підкоманди.
|
||||
Повторюваний фільтр секції керованого налаштування, коли ви запускаєте `openclaw config` без підкоманди.
|
||||
</ParamField>
|
||||
|
||||
Підтримувані керовані розділи: `workspace`, `model`, `web`, `gateway`, `daemon`, `channels`, `plugins`, `skills`, `health`.
|
||||
Підтримувані керовані секції: `workspace`, `model`, `web`, `gateway`, `daemon`, `channels`, `plugins`, `skills`, `health`.
|
||||
|
||||
## Приклади
|
||||
|
||||
@ -47,20 +47,20 @@ openclaw config validate --json
|
||||
|
||||
### `config schema`
|
||||
|
||||
Друкує згенеровану схему JSON для `openclaw.json` у stdout як JSON.
|
||||
Друкує згенеровану JSON-схему для `openclaw.json` у stdout як JSON.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Що вона містить">
|
||||
- Поточну кореневу схему конфігурації, а також кореневе рядкове поле `$schema` для інструментів редактора.
|
||||
<Accordion title="What it includes">
|
||||
- Поточна коренева схема конфігурації, а також кореневе рядкове поле `$schema` для інструментів редактора.
|
||||
- Метадані документації полів `title` і `description`, які використовує Control UI.
|
||||
- Вкладені об’єкти, wildcard-вузли (`*`) і вузли елементів масиву (`[]`) успадковують ті самі метадані `title` / `description`, коли існує відповідна документація поля.
|
||||
- Вкладені об'єкти, вузли з wildcard (`*`) і елементи масиву (`[]`) успадковують ті самі метадані `title` / `description`, коли існує відповідна документація поля.
|
||||
- Гілки `anyOf` / `oneOf` / `allOf` також успадковують ті самі метадані документації, коли існує відповідна документація поля.
|
||||
- Best-effort метадані схеми живих plugin + каналів, коли можна завантажити маніфести середовища виконання.
|
||||
- Чисту резервну схему навіть тоді, коли поточна конфігурація недійсна.
|
||||
- Найкращі доступні живі метадані схеми Plugin + каналу, коли runtime-маніфести можна завантажити.
|
||||
- Чиста резервна схема навіть тоді, коли поточна конфігурація недійсна.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Пов’язаний RPC середовища виконання">
|
||||
`config.schema.lookup` повертає один нормалізований шлях конфігурації з неглибоким вузлом схеми (`title`, `description`, `type`, `enum`, `const`, типові межі), відповідними метаданими UI-підказки й короткими описами безпосередніх дочірніх елементів. Використовуйте це для деталізації за шляхом у Control UI або власних клієнтах.
|
||||
<Accordion title="Related runtime RPC">
|
||||
`config.schema.lookup` повертає один нормалізований шлях конфігурації з поверхневим вузлом схеми (`title`, `description`, `type`, `enum`, `const`, поширені межі), відповідними метаданими підказок UI та зведеннями безпосередніх дочірніх елементів. Використовуйте це для деталізації в межах шляху в Control UI або власних клієнтах.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -83,7 +83,7 @@ openclaw config get agents.defaults.workspace
|
||||
openclaw config get agents.list[0].id
|
||||
```
|
||||
|
||||
Використовуйте індекс списку агентів, щоб націлитися на конкретного агента:
|
||||
Використовуйте індекс списку агентів, щоб вибрати конкретного агента:
|
||||
|
||||
```bash
|
||||
openclaw config get agents.list
|
||||
@ -92,7 +92,7 @@ openclaw config set agents.list[1].tools.exec.node "node-id-or-name"
|
||||
|
||||
## Значення
|
||||
|
||||
Значення розбираються як JSON5, коли це можливо; інакше вони обробляються як рядки. Використовуйте `--strict-json`, щоб вимагати розбору JSON5. `--json` залишається підтримуваним як застарілий alias.
|
||||
Значення розбираються як JSON5, коли це можливо; інакше вони розглядаються як рядки. Використовуйте `--strict-json`, щоб вимагати розбору JSON5. `--json` залишається підтримуваним як застарілий псевдонім.
|
||||
|
||||
```bash
|
||||
openclaw config set agents.defaults.heartbeat.every "0m"
|
||||
@ -100,13 +100,13 @@ openclaw config set gateway.port 19001 --strict-json
|
||||
openclaw config set channels.whatsapp.groups '["*"]' --strict-json
|
||||
```
|
||||
|
||||
`config get <path> --json` друкує необроблене значення як JSON замість тексту, відформатованого для термінала.
|
||||
`config get <path> --json` друкує сире значення як JSON замість відформатованого для термінала тексту.
|
||||
|
||||
<Note>
|
||||
Присвоєння об’єкта за замовчуванням замінює цільовий шлях. Захищені шляхи map/list, які зазвичай містять додані користувачем записи, як-от `agents.defaults.models`, `models.providers`, `models.providers.<id>.models`, `plugins.entries` і `auth.profiles`, відмовляються від замін, які вилучили б наявні записи, якщо ви не передасте `--replace`.
|
||||
Присвоєння об'єкта типово замінює цільовий шлях. Захищені шляхи мап/списків, які часто містять додані користувачем записи, як-от `agents.defaults.models`, `models.providers`, `models.providers.<id>.models`, `plugins.entries` і `auth.profiles`, відхиляють заміни, які прибрали б наявні записи, якщо не передати `--replace`.
|
||||
</Note>
|
||||
|
||||
Використовуйте `--merge`, коли додаєте записи до таких map:
|
||||
Використовуйте `--merge`, коли додаєте записи до таких мап:
|
||||
|
||||
```bash
|
||||
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
|
||||
@ -120,12 +120,12 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll
|
||||
`openclaw config set` підтримує чотири стилі присвоєння:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Режим значення">
|
||||
<Tab title="Value mode">
|
||||
```bash
|
||||
openclaw config set <path> <value>
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Режим побудовника SecretRef">
|
||||
<Tab title="SecretRef builder mode">
|
||||
```bash
|
||||
openclaw config set channels.discord.token \
|
||||
--ref-provider default \
|
||||
@ -133,8 +133,8 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll
|
||||
--ref-id DISCORD_BOT_TOKEN
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Режим побудовника provider">
|
||||
Режим побудовника provider націлюється лише на шляхи `secrets.providers.<alias>`:
|
||||
<Tab title="Provider builder mode">
|
||||
Режим конструктора провайдера націлений лише на шляхи `secrets.providers.<alias>`:
|
||||
|
||||
```bash
|
||||
openclaw config set secrets.providers.vault \
|
||||
@ -146,7 +146,7 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab title="Пакетний режим">
|
||||
<Tab title="Batch mode">
|
||||
```bash
|
||||
openclaw config set --batch-json '[
|
||||
{
|
||||
@ -168,28 +168,28 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll
|
||||
</Tabs>
|
||||
|
||||
<Warning>
|
||||
Присвоєння SecretRef відхиляються на непідтримуваних runtime-mutable поверхнях (наприклад `hooks.token`, `commands.ownerDisplaySecret`, токени Webhook прив’язки потоків Discord і JSON облікових даних WhatsApp). Див. [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface).
|
||||
Присвоєння SecretRef відхиляються на непідтримуваних runtime-змінюваних поверхнях (наприклад, `hooks.token`, `commands.ownerDisplaySecret`, токени webhook прив'язки потоків Discord і JSON облікових даних WhatsApp). Див. [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface).
|
||||
</Warning>
|
||||
|
||||
Пакетний розбір завжди використовує пакетне payload (`--batch-json`/`--batch-file`) як джерело істини. `--strict-json` / `--json` не змінюють поведінку пакетного розбору.
|
||||
Пакетний розбір завжди використовує пакетне навантаження (`--batch-json`/`--batch-file`) як джерело істини. `--strict-json` / `--json` не змінюють поведінку пакетного розбору.
|
||||
|
||||
## `config patch`
|
||||
|
||||
Використовуйте `config patch`, коли хочете вставити або передати через pipe patch у формі конфігурації замість запуску багатьох команд `config set` на основі шляхів. Вхідні дані — це об’єкт JSON5. Об’єкти рекурсивно об’єднуються, масиви й скалярні значення замінюють цільове значення, а `null` видаляє цільовий шлях.
|
||||
Використовуйте `config patch`, коли хочете вставити або передати через канал патч у формі конфігурації замість запуску багатьох команд `config set` на основі шляхів. Вхідні дані є об'єктом JSON5. Об'єкти рекурсивно об'єднуються, масиви та скалярні значення замінюють цільове значення, а `null` видаляє цільовий шлях.
|
||||
|
||||
```bash
|
||||
openclaw config patch --file ./openclaw.patch.json5 --dry-run
|
||||
openclaw config patch --file ./openclaw.patch.json5
|
||||
```
|
||||
|
||||
Також можна передати patch через stdin, що корисно для скриптів віддаленого налаштування:
|
||||
Також можна передати патч через stdin, що корисно для скриптів віддаленого налаштування:
|
||||
|
||||
```bash
|
||||
ssh openclaw-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5
|
||||
ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.json5
|
||||
```
|
||||
|
||||
Приклад patch:
|
||||
Приклад патча:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -221,15 +221,15 @@ ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.json5
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте `--replace-path <path>`, коли один об’єкт або масив має стати точно наданим значенням замість рекурсивного застосування patch:
|
||||
Використовуйте `--replace-path <path>`, коли один об'єкт або масив має стати точно наданим значенням, а не рекурсивно патчитися:
|
||||
|
||||
```bash
|
||||
openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'
|
||||
```
|
||||
|
||||
`--dry-run` запускає перевірки схеми та розв’язуваності SecretRef без запису. Exec-backed SecretRefs за замовчуванням пропускаються під час dry-run; додайте `--allow-exec`, коли ви навмисно хочете, щоб dry-run виконував команди provider.
|
||||
`--dry-run` запускає перевірки схеми та розв'язуваності SecretRef без запису. SecretRef на основі exec типово пропускаються під час dry-run; додайте `--allow-exec`, коли навмисно хочете, щоб dry-run виконував команди провайдера.
|
||||
|
||||
Режим шляху/значення JSON залишається підтримуваним як для SecretRefs, так і для providers:
|
||||
Режим JSON-шляху/значення залишається підтримуваним як для SecretRef, так і для провайдерів:
|
||||
|
||||
```bash
|
||||
openclaw config set channels.discord.token \
|
||||
@ -241,12 +241,12 @@ openclaw config set secrets.providers.vaultfile \
|
||||
--strict-json
|
||||
```
|
||||
|
||||
## Прапорці побудовника provider
|
||||
## Прапорці конструктора провайдера
|
||||
|
||||
Цілі побудовника provider мають використовувати `secrets.providers.<alias>` як шлях.
|
||||
Цілі конструктора провайдера мають використовувати `secrets.providers.<alias>` як шлях.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Спільні прапорці">
|
||||
<Accordion title="Common flags">
|
||||
- `--provider-source <env|file|exec>`
|
||||
- `--provider-timeout-ms <ms>` (`file`, `exec`)
|
||||
|
||||
@ -256,14 +256,14 @@ openclaw config set secrets.providers.vaultfile \
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="File provider (--provider-source file)">
|
||||
- `--provider-path <path>` (обов’язковий)
|
||||
- `--provider-path <path>` (обов'язково)
|
||||
- `--provider-mode <singleValue|json>`
|
||||
- `--provider-max-bytes <bytes>`
|
||||
- `--provider-allow-insecure-path`
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Exec provider (--provider-source exec)">
|
||||
- `--provider-command <path>` (обов’язковий)
|
||||
- `--provider-command <path>` (обов'язково)
|
||||
- `--provider-arg <arg>` (повторюваний)
|
||||
- `--provider-no-output-timeout-ms <ms>`
|
||||
- `--provider-max-output-bytes <bytes>`
|
||||
@ -277,7 +277,7 @@ openclaw config set secrets.providers.vaultfile \
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Приклад захищеного exec provider:
|
||||
Приклад посиленого exec-провайдера:
|
||||
|
||||
```bash
|
||||
openclaw config set secrets.providers.vault \
|
||||
@ -291,9 +291,9 @@ openclaw config set secrets.providers.vault \
|
||||
--provider-timeout-ms 5000
|
||||
```
|
||||
|
||||
## Dry run
|
||||
## Пробний запуск
|
||||
|
||||
Використовуйте `--dry-run`, щоб перевірити зміни без запису `openclaw.json`.
|
||||
Використовуйте `--dry-run`, щоб перевірити зміни без запису в `openclaw.json`.
|
||||
|
||||
```bash
|
||||
openclaw config set channels.discord.token \
|
||||
@ -318,26 +318,26 @@ openclaw config set channels.discord.token \
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Поведінка dry-run">
|
||||
- Режим побудовника: запускає перевірки розв’язуваності SecretRef для змінених refs/providers.
|
||||
- Режим JSON (`--strict-json`, `--json` або пакетний режим): запускає перевірку схеми та перевірки розв’язуваності SecretRef.
|
||||
- Перевірка політики також виконується для відомих непідтримуваних цільових поверхонь SecretRef.
|
||||
- Перевірки політики оцінюють повну конфігурацію після зміни, тому записи батьківських об’єктів (наприклад встановлення `hooks` як об’єкта) не можуть обійти перевірку непідтримуваних поверхонь.
|
||||
- Перевірки exec SecretRef за замовчуванням пропускаються під час dry-run, щоб уникнути побічних ефектів команд.
|
||||
- Використовуйте `--allow-exec` з `--dry-run`, щоб явно ввімкнути перевірки exec SecretRef (це може виконати команди provider).
|
||||
- `--allow-exec` призначений лише для dry-run і завершується помилкою, якщо використаний без `--dry-run`.
|
||||
<Accordion title="Dry-run behavior">
|
||||
- Режим конструктора: запускає перевірки розв'язуваності SecretRef для змінених refs/провайдерів.
|
||||
- Режим JSON (`--strict-json`, `--json` або пакетний режим): запускає перевірку схеми, а також перевірки розв'язуваності SecretRef.
|
||||
- Перевірка політик також виконується для відомих непідтримуваних цільових поверхонь SecretRef.
|
||||
- Перевірки політик оцінюють повну конфігурацію після зміни, тож записи батьківських об'єктів (наприклад, встановлення `hooks` як об'єкта) не можуть обійти перевірку непідтримуваної поверхні.
|
||||
- Перевірки exec SecretRef типово пропускаються під час dry-run, щоб уникнути побічних ефектів команд.
|
||||
- Використовуйте `--allow-exec` із `--dry-run`, щоб явно ввімкнути перевірки exec SecretRef (це може виконувати команди провайдера).
|
||||
- `--allow-exec` працює лише для dry-run і завершується помилкою, якщо використаний без `--dry-run`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Поля --dry-run --json">
|
||||
<Accordion title="--dry-run --json fields">
|
||||
`--dry-run --json` друкує машинозчитуваний звіт:
|
||||
|
||||
- `ok`: чи пройшов dry-run
|
||||
- `operations`: кількість оцінених присвоєнь
|
||||
- `checks`: чи виконувалися перевірки схеми/розв’язуваності
|
||||
- `checks.resolvabilityComplete`: чи перевірки розв’язуваності виконалися до завершення (false, коли exec refs пропущені)
|
||||
- `refsChecked`: кількість refs, фактично розв’язаних під час dry-run
|
||||
- `skippedExecRefs`: кількість exec refs, пропущених через те, що `--allow-exec` не було встановлено
|
||||
- `errors`: структуровані помилки схеми/розв’язуваності, коли `ok=false`
|
||||
- `checks`: чи виконувалися перевірки схеми/розв'язуваності
|
||||
- `checks.resolvabilityComplete`: чи перевірки розв'язуваності завершилися повністю (false, коли exec refs пропущено)
|
||||
- `refsChecked`: кількість refs, фактично розв'язаних під час dry-run
|
||||
- `skippedExecRefs`: кількість exec refs, пропущених через те, що `--allow-exec` не встановлено
|
||||
- `errors`: структуровані помилки схеми/розв'язуваності, коли `ok=false`
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -413,21 +413,21 @@ openclaw config set channels.discord.token \
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Якщо dry-run завершується помилкою">
|
||||
- `config schema validation failed`: форма вашої конфігурації після зміни недійсна; виправте шлях/значення або форму об’єкта provider/ref.
|
||||
- `Config policy validation failed: unsupported SecretRef usage`: перемістіть ці облікові дані назад до введення відкритим текстом/рядком і використовуйте SecretRefs лише на підтримуваних поверхнях.
|
||||
- `SecretRef assignment(s) could not be resolved`: указаний provider/ref наразі неможливо розв’язати (відсутня змінна середовища, недійсний вказівник на файл, помилка exec-провайдера або невідповідність provider/source).
|
||||
- `Dry run note: skipped <n> exec SecretRef resolvability check(s)`: dry-run пропустив exec-посилання; повторіть запуск із `--allow-exec`, якщо вам потрібна перевірка розв’язності exec.
|
||||
- Для пакетного режиму виправте записи з помилками й повторно запустіть `--dry-run` перед записом.
|
||||
- `config schema validation failed`: форма конфігурації після зміни недійсна; виправте шлях/значення або форму об’єкта провайдера/ref.
|
||||
- `Config policy validation failed: unsupported SecretRef usage`: перемістіть ці облікові дані назад у введення відкритим текстом/рядком і використовуйте SecretRefs лише на підтримуваних поверхнях.
|
||||
- `SecretRef assignment(s) could not be resolved`: посиланий provider/ref наразі неможливо розв’язати (відсутня змінна середовища, недійсний вказівник на файл, помилка exec-провайдера або невідповідність provider/source).
|
||||
- `Dry run note: skipped <n> exec SecretRef resolvability check(s)`: dry-run пропустив exec refs; запустіть повторно з `--allow-exec`, якщо потрібна перевірка розв’язності exec.
|
||||
- Для пакетного режиму виправте проблемні записи й повторно запустіть `--dry-run` перед записом.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Безпека запису
|
||||
|
||||
`openclaw config set` та інші засоби запису конфігурації, що належать OpenClaw, перевіряють повну конфігурацію після зміни перед її збереженням на диск. Якщо нове навантаження не проходить перевірку схеми або схоже на руйнівне перезаписування, активна конфігурація лишається без змін, а відхилене навантаження зберігається поруч як `openclaw.json.rejected.*`.
|
||||
`openclaw config set` та інші засоби запису конфігурації, що належать OpenClaw, перевіряють повну конфігурацію після зміни перед збереженням на диск. Якщо новий вміст не проходить перевірку схеми або виглядає як руйнівне перезаписування, активна конфігурація залишається без змін, а відхилений вміст зберігається поруч із нею як `openclaw.json.rejected.*`.
|
||||
|
||||
<Warning>
|
||||
Активний шлях конфігурації має бути звичайним файлом. Макети з `openclaw.json` як символьним посиланням не підтримуються для запису; натомість використовуйте `OPENCLAW_CONFIG_PATH`, щоб указати безпосередньо на справжній файл.
|
||||
Активний шлях конфігурації має бути звичайним файлом. Схеми з `openclaw.json` через symlink не підтримуються для запису; натомість використовуйте `OPENCLAW_CONFIG_PATH`, щоб напряму вказати на справжній файл.
|
||||
</Warning>
|
||||
|
||||
Для невеликих змін надавайте перевагу записам через CLI:
|
||||
@ -438,7 +438,7 @@ openclaw config set gateway.reload.mode hybrid
|
||||
openclaw config validate
|
||||
```
|
||||
|
||||
Якщо запис відхилено, перевірте збережене навантаження й виправте повну форму конфігурації:
|
||||
Якщо запис відхилено, перевірте збережений вміст і виправте повну форму конфігурації:
|
||||
|
||||
```bash
|
||||
CONFIG="$(openclaw config file)"
|
||||
@ -446,19 +446,19 @@ ls -lt "$CONFIG".rejected.* 2>/dev/null | head
|
||||
openclaw config validate
|
||||
```
|
||||
|
||||
Прямі зміни через редактор усе ще дозволені, але запущений Gateway вважає їх ненадійними, доки вони не пройдуть перевірку. Недійсні прямі зміни можна відновити з останньої справної резервної копії під час запуску або гарячого перезавантаження. Див. [усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config).
|
||||
Прямі записи через редактор усе ще дозволені, але запущений Gateway вважає їх ненадійними, доки вони не пройдуть перевірку. Недійсні прямі зміни призводять до помилки запуску або пропускаються під час hot reload; Gateway не перезаписує `openclaw.json`. Запустіть `openclaw doctor --fix`, щоб відновити конфігурацію з префіксом/перезаписану конфігурацію або повернути останню відому справну копію. Див. [усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-rejected-invalid-config).
|
||||
|
||||
Відновлення всього файла призначене для глобально пошкодженої конфігурації, як-от помилки розбору, помилки схеми на кореневому рівні, помилки міграції застарілої конфігурації або змішані помилки Plugin і кореня. Якщо перевірка не проходить лише під `plugins.entries.<id>...`, OpenClaw залишає активний `openclaw.json` на місці й повідомляє про локальну для Plugin проблему замість відновлення `.last-good`. Це запобігає відкату непов’язаних налаштувань користувача, таких як моделі, провайдери, профілі автентифікації, канали, експозиція gateway, інструменти, пам’ять, браузер або конфігурація cron, через зміни схеми Plugin чи розбіжність `minHostVersion`.
|
||||
Відновлення всього файлу зарезервоване для ремонту через doctor. Зміни схем Plugin або невідповідність `minHostVersion` залишаються помітними замість відкату непов’язаних користувацьких налаштувань, як-от моделей, провайдерів, профілів автентифікації, каналів, доступності Gateway, інструментів, пам’яті, браузера або конфігурації cron.
|
||||
|
||||
## Підкоманди
|
||||
|
||||
- `config file`: вивести шлях до активного файла конфігурації (розв’язаний із `OPENCLAW_CONFIG_PATH` або типового розташування). Шлях має вказувати на звичайний файл, а не на символьне посилання.
|
||||
- `config file`: Вивести шлях до активного файлу конфігурації (визначений з `OPENCLAW_CONFIG_PATH` або типового розташування). Шлях має вказувати на звичайний файл, а не на символічне посилання.
|
||||
|
||||
Перезапустіть gateway після змін.
|
||||
Перезапустіть Gateway після редагувань.
|
||||
|
||||
## Перевірка
|
||||
|
||||
Перевірте поточну конфігурацію за активною схемою без запуску gateway.
|
||||
Перевірте поточну конфігурацію за активною схемою без запуску Gateway.
|
||||
|
||||
```bash
|
||||
openclaw config validate
|
||||
@ -468,7 +468,7 @@ openclaw config validate --json
|
||||
Після успішного проходження `openclaw config validate` можна використати локальний TUI, щоб вбудований агент порівняв активну конфігурацію з документацією, поки ви перевіряєте кожну зміну з того самого термінала:
|
||||
|
||||
<Note>
|
||||
Якщо перевірка вже завершується помилкою, почніть із `openclaw configure` або `openclaw doctor --fix`. `openclaw chat` не обходить захист від недійсної конфігурації.
|
||||
Якщо перевірка вже завершується помилкою, почніть з `openclaw configure` або `openclaw doctor --fix`. `openclaw chat` не обходить захист від некоректної конфігурації.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
@ -487,16 +487,16 @@ openclaw chat
|
||||
Типовий цикл виправлення:
|
||||
|
||||
<Steps>
|
||||
<Step title="Порівняйте з документацією">
|
||||
<Step title="Compare with docs">
|
||||
Попросіть агента порівняти вашу поточну конфігурацію з відповідною сторінкою документації та запропонувати найменше виправлення.
|
||||
</Step>
|
||||
<Step title="Застосуйте цільові зміни">
|
||||
Застосуйте цільові зміни за допомогою `openclaw config set` або `openclaw configure`.
|
||||
<Step title="Apply targeted edits">
|
||||
Застосуйте цільові редагування за допомогою `openclaw config set` або `openclaw configure`.
|
||||
</Step>
|
||||
<Step title="Повторіть перевірку">
|
||||
<Step title="Re-validate">
|
||||
Повторно запускайте `openclaw config validate` після кожної зміни.
|
||||
</Step>
|
||||
<Step title="Doctor для проблем виконання">
|
||||
<Step title="Doctor for runtime issues">
|
||||
Якщо перевірка проходить, але середовище виконання все ще несправне, запустіть `openclaw doctor` або `openclaw doctor --fix`, щоб отримати допомогу з міграцією та виправленням.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
@ -1,29 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете встановити або керувати plugins Gateway чи сумісними пакетами
|
||||
- Ви хочете діагностувати збої завантаження Plugin
|
||||
- Ви хочете встановити або керувати плагінами Gateway чи сумісними пакетами
|
||||
- Ви хочете налагодити помилки завантаження Plugin
|
||||
sidebarTitle: Plugins
|
||||
summary: Довідка CLI для `openclaw plugins` (`list`, `install`, `marketplace`, `uninstall`, `enable`/`disable`, `doctor`)
|
||||
title: Плагіни
|
||||
summary: Довідник CLI для `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)
|
||||
title: Plugins
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T21:59:35Z"
|
||||
generated_at: "2026-05-03T17:12:13Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 3b077ab0739e2453ccba434aa3b02b1d441bab792b7b131216221a8048d551cd
|
||||
source_hash: f6ae613e39535ea20f9cf3dd451f110ae1b14de4586bdbe3d55d06d8e7cfd2cf
|
||||
source_path: cli/plugins.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Керуйте Gateway Plugin, пакетами hook і сумісними bundles.
|
||||
Керуйте Gateway plugins, пакетами хуків і сумісними bundles.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Система Plugin" href="/uk/tools/plugin">
|
||||
Посібник для кінцевих користувачів зі встановлення, увімкнення та усунення неполадок plugins.
|
||||
Посібник для кінцевих користувачів зі встановлення, увімкнення та усунення несправностей plugins.
|
||||
</Card>
|
||||
<Card title="Керування plugins" href="/uk/plugins/manage-plugins">
|
||||
Короткі приклади для встановлення, перегляду списку, оновлення, видалення та публікації.
|
||||
Швидкі приклади встановлення, перегляду списку, оновлення, видалення та публікації.
|
||||
</Card>
|
||||
<Card title="Plugin bundles" href="/uk/plugins/bundles">
|
||||
<Card title="Bundles Plugin" href="/uk/plugins/bundles">
|
||||
Модель сумісності bundle.
|
||||
</Card>
|
||||
<Card title="Маніфест Plugin" href="/uk/plugins/manifest">
|
||||
@ -62,16 +62,16 @@ openclaw plugins marketplace list <marketplace>
|
||||
openclaw plugins marketplace list <marketplace> --json
|
||||
```
|
||||
|
||||
Для розслідування повільного встановлення, інспектування, видалення або оновлення registry запустіть
|
||||
команду з `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Трасування записує тривалість фаз
|
||||
до stderr і зберігає JSON-вивід придатним для парсингу. Див. [Налагодження](/uk/help/debugging#plugin-lifecycle-trace).
|
||||
Для дослідження повільного встановлення, перевірки, видалення або оновлення реєстру запустіть
|
||||
команду з `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Трасування записує таймінги фаз
|
||||
у stderr і залишає JSON-вивід придатним для розбору. Див. [Налагодження](/uk/help/debugging#plugin-lifecycle-trace).
|
||||
|
||||
<Note>
|
||||
Вбудовані plugins постачаються з OpenClaw. Деякі ввімкнені за замовчуванням (наприклад, вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований браузерний plugin); інші потребують `plugins enable`.
|
||||
Вбудовані plugins постачаються з OpenClaw. Деякі ввімкнені за замовчуванням (наприклад, вбудовані провайдери моделей, вбудовані мовленнєві провайдери та вбудований browser plugin); інші потребують `plugins enable`.
|
||||
|
||||
Нативні OpenClaw plugins мають постачати `openclaw.plugin.json` із вбудованою JSON Schema (`configSchema`, навіть якщо вона порожня). Сумісні bundles натомість використовують власні маніфести bundle.
|
||||
Нативні OpenClaw plugins мають постачати `openclaw.plugin.json` з inline JSON Schema (`configSchema`, навіть якщо порожньою). Сумісні bundles натомість використовують власні маніфести bundle.
|
||||
|
||||
`plugins list` показує `Format: openclaw` або `Format: bundle`. Докладний вивід list/info також показує підтип bundle (`codex`, `claude` або `cursor`) і виявлені можливості bundle.
|
||||
`plugins list` показує `Format: openclaw` або `Format: bundle`. Докладний вивід list/info також показує підтип bundle (`codex`, `claude` або `cursor`) плюс виявлені можливості bundle.
|
||||
</Note>
|
||||
|
||||
### Встановлення
|
||||
@ -93,7 +93,7 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Голі назви пакетів встановлюються з npm за замовчуванням під час перехідного запуску. Використовуйте `clawhub:<package>` для ClawHub. Ставтеся до встановлення plugins як до запуску коду. Віддавайте перевагу закріпленим версіям.
|
||||
Під час launch cutover голі назви пакетів за замовчуванням встановлюються з npm. Використовуйте `clawhub:<package>` для ClawHub. Ставтеся до встановлення plugins як до запуску коду. Надавайте перевагу pinned-версіям.
|
||||
</Warning>
|
||||
|
||||
`plugins search` запитує ClawHub щодо доступних для встановлення пакетів plugin і виводить
|
||||
@ -101,61 +101,61 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
|
||||
а не skills. Використовуйте `openclaw skills search` для ClawHub skills.
|
||||
|
||||
<Note>
|
||||
ClawHub є основною поверхнею розповсюдження та пошуку для більшості plugins. Npm
|
||||
залишається підтримуваним запасним і прямим шляхом встановлення. Пакети plugin
|
||||
ClawHub є основною поверхнею розповсюдження й пошуку для більшості plugins. Npm
|
||||
залишається підтримуваним резервним варіантом і шляхом прямого встановлення. Пакети plugins
|
||||
`@openclaw/*`, що належать OpenClaw, знову публікуються в npm; див. поточний список
|
||||
на [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) або в
|
||||
[інвентарі plugin](/uk/plugins/plugin-inventory). Стабільні встановлення використовують `latest`.
|
||||
Встановлення й оновлення beta-каналу віддають перевагу npm dist-tag `beta`, коли цей тег
|
||||
на [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) або
|
||||
[інвентар Plugin](/uk/plugins/plugin-inventory). Стабільні встановлення використовують `latest`.
|
||||
Встановлення та оновлення beta-каналу надають перевагу npm dist-tag `beta`, коли цей tag
|
||||
доступний, а потім повертаються до `latest`.
|
||||
</Note>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Включення конфігурації та відновлення після недійсної конфігурації">
|
||||
Якщо ваш розділ `plugins` підтримується однофайловим `$include`, `plugins install/update/enable/disable/uninstall` записують зміни в цей включений файл і залишають `openclaw.json` без змін. Кореневі включення, масиви включень і включення з сусідніми перевизначеннями завершуються закрито замість сплющення. Див. [Включення конфігурації](/uk/gateway/configuration) для підтримуваних форм.
|
||||
<Accordion title="Config includes і відновлення некоректної конфігурації">
|
||||
Якщо ваш розділ `plugins` підкріплений однофайловим `$include`, `plugins install/update/enable/disable/uninstall` записують у цей included file і залишають `openclaw.json` без змін. Root includes, include arrays і includes із sibling overrides завершуються закрито, замість flattening. Див. [Config includes](/uk/gateway/configuration) для підтримуваних форм.
|
||||
|
||||
Якщо конфігурація недійсна під час встановлення, `plugins install` зазвичай завершується закрито й повідомляє, що спочатку потрібно запустити `openclaw doctor --fix`. Під час запуску Gateway недійсна конфігурація одного plugin ізолюється до цього plugin, щоб інші канали та plugins могли продовжувати роботу; `openclaw doctor --fix` може помістити недійсний запис plugin у карантин. Єдиний задокументований виняток під час встановлення — вузький шлях відновлення для вбудованих plugins, які явно погоджуються на `openclaw.install.allowInvalidConfigRecovery`.
|
||||
Якщо під час встановлення конфігурація некоректна, `plugins install` зазвичай завершується закрито й повідомляє, що спершу потрібно запустити `openclaw doctor --fix`. Під час запуску Gateway і hot reload некоректна конфігурація plugin завершується закрито, як і будь-яка інша некоректна конфігурація; `openclaw doctor --fix` може ізолювати некоректний запис plugin. Єдиний задокументований виняток під час встановлення — вузький шлях відновлення bundled-plugin для plugins, які явно opt into `openclaw.install.allowInvalidConfigRecovery`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--force і повторне встановлення проти оновлення">
|
||||
`--force` повторно використовує наявну ціль встановлення та перезаписує вже встановлений plugin або пакет hook на місці. Використовуйте його, коли ви навмисно повторно встановлюєте той самий id з нового локального шляху, архіву, пакета ClawHub або артефакта npm. Для звичайних оновлень уже відстежуваного npm plugin віддавайте перевагу `openclaw plugins update <id-or-npm-spec>`.
|
||||
<Accordion title="--force і повторне встановлення порівняно з оновленням">
|
||||
`--force` повторно використовує наявну ціль встановлення й перезаписує вже встановлений plugin або пакет хуків на місці. Використовуйте це, коли навмисно перевстановлюєте той самий id з нового локального шляху, архіву, пакета ClawHub або npm-артефакта. Для звичайних оновлень уже відстежуваного npm plugin надавайте перевагу `openclaw plugins update <id-or-npm-spec>`.
|
||||
|
||||
Якщо ви запускаєте `plugins install` для id plugin, який уже встановлено, OpenClaw зупиняється та спрямовує вас до `plugins update <id-or-npm-spec>` для звичайного оновлення або до `plugins install <package> --force`, коли ви справді хочете перезаписати поточне встановлення з іншого джерела.
|
||||
Якщо ви запускаєте `plugins install` для id plugin, який уже встановлено, OpenClaw зупиняється й спрямовує вас до `plugins update <id-or-npm-spec>` для звичайного оновлення або до `plugins install <package> --force`, коли ви справді хочете перезаписати поточне встановлення з іншого джерела.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Область дії --pin">
|
||||
`--pin` застосовується лише до встановлень npm. Він не підтримується з встановленнями `git:`; використовуйте явний git ref, наприклад `git:github.com/acme/plugin@v1.2.3`, коли вам потрібне закріплене джерело. Він не підтримується з `--marketplace`, оскільки встановлення marketplace зберігають метадані джерела marketplace замість специфікації npm.
|
||||
`--pin` застосовується лише до npm-встановлень. Він не підтримується з `git:` installs; використовуйте явний git ref, наприклад `git:github.com/acme/plugin@v1.2.3`, коли вам потрібне pinned-джерело. Він не підтримується з `--marketplace`, оскільки marketplace installs зберігають метадані джерела marketplace замість npm spec.
|
||||
</Accordion>
|
||||
<Accordion title="--dangerously-force-unsafe-install">
|
||||
`--dangerously-force-unsafe-install` — це аварійний параметр для хибних спрацьовувань у вбудованому сканері небезпечного коду. Він дозволяє встановленню продовжитися, навіть коли вбудований сканер повідомляє про знахідки `critical`, але **не** обходить блокування політики hook `before_install` plugin і **не** обходить помилки сканування.
|
||||
`--dangerously-force-unsafe-install` — це аварійна опція для хибнопозитивних спрацьовувань у вбудованому сканері небезпечного коду. Вона дозволяє встановленню продовжитися, навіть коли вбудований сканер повідомляє про знахідки `critical`, але вона **не** обходить policy blocks хуків `before_install` plugin і **не** обходить збої сканування.
|
||||
|
||||
Цей прапорець CLI застосовується до потоків встановлення/оновлення plugin. Встановлення залежностей skill, підтримувані Gateway, використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком завантаження/встановлення skill з ClawHub.
|
||||
Цей CLI-прапорець застосовується до потоків install/update plugin. Встановлення залежностей skill за підтримки Gateway використовують відповідний request override `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком завантаження/встановлення skill з ClawHub.
|
||||
|
||||
Якщо plugin, який ви опублікували на ClawHub, заблоковано скануванням registry, скористайтеся кроками для видавця в [ClawHub](/uk/tools/clawhub).
|
||||
Якщо plugin, який ви опублікували на ClawHub, заблоковано registry scan, скористайтеся кроками для видавців у [ClawHub](/uk/tools/clawhub).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Пакети hook і специфікації npm">
|
||||
`plugins install` також є поверхнею встановлення для пакетів hook, які відкривають `openclaw.hooks` у `package.json`. Використовуйте `openclaw hooks` для відфільтрованої видимості hook і ввімкнення окремих hook, а не для встановлення пакетів.
|
||||
<Accordion title="Пакети хуків і npm specs">
|
||||
`plugins install` також є поверхнею встановлення для пакетів хуків, які expose `openclaw.hooks` у `package.json`. Використовуйте `openclaw hooks` для відфільтрованої видимості хуків і ввімкнення окремих хуків, а не для встановлення пакетів.
|
||||
|
||||
Специфікації npm є **лише registry** (назва пакета + необов’язкова **точна версія** або **dist-tag**). Специфікації Git/URL/file і діапазони semver відхиляються. Встановлення залежностей виконуються локально в проєкті з `--ignore-scripts` задля безпеки, навіть якщо ваша оболонка має глобальні налаштування встановлення npm.
|
||||
Npm specs є **лише реєстровими** (назва пакета + необов’язкова **точна версія** або **dist-tag**). Git/URL/file specs і semver ranges відхиляються. Встановлення залежностей виконуються project-local з `--ignore-scripts` для безпеки, навіть коли ваша shell має глобальні налаштування npm install.
|
||||
|
||||
Використовуйте `npm:<package>`, коли хочете зробити розв’язання npm явним. Голі специфікації пакетів також встановлюються безпосередньо з npm під час перехідного запуску.
|
||||
Використовуйте `npm:<package>`, коли хочете зробити npm resolution явним. Під час launch cutover голі package specs також встановлюються напряму з npm.
|
||||
|
||||
Голі специфікації та `@latest` залишаються на стабільному треку. Якщо npm розв’язує будь-яку з них у prerelease, OpenClaw зупиняється й просить вас явно погодитися за допомогою prerelease-тега, наприклад `@beta`/`@rc`, або точної prerelease-версії, наприклад `@1.2.3-beta.4`.
|
||||
Bare specs і `@latest` залишаються на stable track. Якщо npm resolve будь-який із них до prerelease, OpenClaw зупиняється й просить вас явно opt in з prerelease tag, наприклад `@beta`/`@rc`, або з точною prerelease-версією, наприклад `@1.2.3-beta.4`.
|
||||
|
||||
Якщо гола специфікація встановлення збігається з офіційним id plugin (наприклад `diffs`), OpenClaw встановлює запис каталогу безпосередньо. Щоб встановити пакет npm з такою самою назвою, використовуйте явну scoped-специфікацію (наприклад `@scope/diffs`).
|
||||
Якщо bare install spec збігається з офіційним id plugin (наприклад, `diffs`), OpenClaw встановлює catalog entry напряму. Щоб встановити npm package з такою самою назвою, використовуйте явний scoped spec (наприклад, `@scope/diffs`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Git-репозиторії">
|
||||
Використовуйте `git:<repo>` для встановлення безпосередньо з git-репозиторію. Підтримувані форми включають `git:github.com/owner/repo`, `git:owner/repo`, повні URL клонування `https://`, `ssh://`, `git://`, `file://` і `git@host:owner/repo.git`. Додайте `@<ref>` або `#<ref>`, щоб перед встановленням перейти на гілку, тег або commit.
|
||||
Використовуйте `git:<repo>` для встановлення напряму з git repository. Підтримувані форми включають `git:github.com/owner/repo`, `git:owner/repo`, повні clone URLs `https://`, `ssh://`, `git://`, `file://` і `git@host:owner/repo.git`. Додайте `@<ref>` або `#<ref>`, щоб перед встановленням перейти на branch, tag або commit.
|
||||
|
||||
Git-встановлення клонують у тимчасову директорію, переходять на запитаний ref, якщо він є, а потім використовують звичайний інсталятор директорії plugin. Це означає, що перевірка маніфесту, сканування небезпечного коду, робота встановлення менеджера пакетів і записи встановлення поводяться як npm-встановлення. Записані git-встановлення містять вихідний URL/ref і розв’язаний commit, щоб `openclaw plugins update` міг пізніше повторно розв’язати джерело.
|
||||
Git installs клонують у тимчасовий каталог, переходять на запитаний ref, якщо він присутній, а потім використовують звичайний installer каталогу plugin. Це означає, що перевірка маніфесту, сканування небезпечного коду, робота встановлення package-manager і install records поводяться як npm installs. Записані git installs містять source URL/ref плюс resolved commit, щоб `openclaw plugins update` міг пізніше повторно resolve джерело.
|
||||
|
||||
Після встановлення з git використовуйте `openclaw plugins inspect <id> --runtime --json`, щоб перевірити runtime-реєстрації, як-от методи gateway і команди CLI. Якщо plugin зареєстрував корінь CLI через `api.registerCli`, виконайте цю команду безпосередньо через кореневий CLI OpenClaw, наприклад `openclaw demo-plugin ping`.
|
||||
Після встановлення з git використовуйте `openclaw plugins inspect <id> --runtime --json`, щоб перевірити runtime registrations, як-от gateway methods і CLI commands. Якщо plugin зареєстрував CLI root через `api.registerCli`, виконайте цю команду напряму через root CLI OpenClaw, наприклад `openclaw demo-plugin ping`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Архіви">
|
||||
Підтримувані архіви: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Архіви нативних OpenClaw plugin мають містити дійсний `openclaw.plugin.json` у витягнутому корені plugin; архіви, які містять лише `package.json`, відхиляються до того, як OpenClaw запише записи встановлення.
|
||||
Підтримувані архіви: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Архіви нативних OpenClaw plugin мають містити дійсний `openclaw.plugin.json` у витягнутому root plugin; архіви, які містять лише `package.json`, відхиляються до того, як OpenClaw запише install records.
|
||||
|
||||
Встановлення Claude marketplace також підтримуються.
|
||||
|
||||
@ -169,32 +169,32 @@ openclaw plugins install clawhub:openclaw-codex-app-server
|
||||
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
|
||||
```
|
||||
|
||||
Голі npm-безпечні специфікації plugin встановлюються з npm за замовчуванням під час перехідного запуску:
|
||||
Під час launch cutover голі npm-safe plugin specs за замовчуванням встановлюються з npm:
|
||||
|
||||
```bash
|
||||
openclaw plugins install openclaw-codex-app-server
|
||||
```
|
||||
|
||||
Використовуйте `npm:`, щоб зробити розв’язання лише через npm явним:
|
||||
Використовуйте `npm:`, щоб зробити npm-only resolution явним:
|
||||
|
||||
```bash
|
||||
openclaw plugins install npm:openclaw-codex-app-server
|
||||
openclaw plugins install npm:@scope/plugin-name@1.0.1
|
||||
```
|
||||
|
||||
OpenClaw перевіряє оголошену сумісність plugin API / мінімальну сумісність gateway перед встановленням. Коли вибрана версія ClawHub публікує артефакт ClawPack, OpenClaw завантажує версіонований npm-pack `.tgz`, перевіряє заголовок digest ClawHub і digest артефакта, а потім встановлює його через звичайний шлях архіву. Старіші версії ClawHub без метаданих ClawPack усе ще встановлюються через застарілий шлях перевірки архіву пакета. Записані встановлення зберігають свої метадані джерела ClawHub, тип артефакта, цілісність npm, shasum npm, назву tarball і факти digest ClawPack для подальших оновлень.
|
||||
Неверсіоновані встановлення ClawHub зберігають неверсіоновану записану специфікацію, щоб `openclaw plugins update` міг відстежувати новіші випуски ClawHub; явні селектори версії або тегу, такі як `clawhub:pkg@1.2.3` і `clawhub:pkg@beta`, залишаються закріпленими на цьому селекторі.
|
||||
OpenClaw перевіряє оголошений plugin API / мінімальну сумісність gateway перед встановленням. Коли вибрана версія ClawHub публікує артефакт ClawPack, OpenClaw завантажує versioned npm-pack `.tgz`, перевіряє ClawHub digest header і artifact digest, а потім встановлює його через звичайний archive path. Старіші версії ClawHub без метаданих ClawPack досі встановлюються через legacy package archive verification path. Записані встановлення зберігають метадані джерела ClawHub, artifact kind, npm integrity, npm shasum, tarball name і факти ClawPack digest для подальших оновлень.
|
||||
Неверсійовані встановлення ClawHub зберігають неверсійований recorded spec, щоб `openclaw plugins update` міг слідувати за новішими релізами ClawHub; явні селектори версії або tag, як-от `clawhub:pkg@1.2.3` і `clawhub:pkg@beta`, залишаються pinned до цього селектора.
|
||||
|
||||
#### Скорочення marketplace
|
||||
|
||||
Використовуйте скорочення `plugin@marketplace`, коли назва marketplace існує в локальному кеші registry Claude за адресою `~/.claude/plugins/known_marketplaces.json`:
|
||||
Використовуйте скорочення `plugin@marketplace`, коли назва marketplace існує в локальному registry cache Claude за адресою `~/.claude/plugins/known_marketplaces.json`:
|
||||
|
||||
```bash
|
||||
openclaw plugins marketplace list <marketplace-name>
|
||||
openclaw plugins install <plugin-name>@<marketplace-name>
|
||||
```
|
||||
|
||||
Використовуйте `--marketplace`, коли хочете передати джерело marketplace явно:
|
||||
Використовуйте `--marketplace`, коли хочете явно передати marketplace source:
|
||||
|
||||
```bash
|
||||
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
|
||||
@ -204,16 +204,16 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
|
||||
```
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Джерела marketplace">
|
||||
- назва відомого marketplace Claude з `~/.claude/plugins/known_marketplaces.json`
|
||||
- локальний корінь marketplace або шлях `marketplace.json`
|
||||
- скорочення репозиторію GitHub, як-от `owner/repo`
|
||||
- URL репозиторію GitHub, як-от `https://github.com/owner/repo`
|
||||
<Tab title="Джерела Marketplace">
|
||||
- назва відомого Marketplace Claude з `~/.claude/plugins/known_marketplaces.json`
|
||||
- локальний корінь Marketplace або шлях `marketplace.json`
|
||||
- скорочення репозиторію GitHub, наприклад `owner/repo`
|
||||
- URL репозиторію GitHub, наприклад `https://github.com/owner/repo`
|
||||
- git URL
|
||||
|
||||
</Tab>
|
||||
<Tab title="Правила віддаленого marketplace">
|
||||
Для віддалених marketplace, завантажених із GitHub або git, записи Plugin мають залишатися всередині клонованого репозиторію marketplace. OpenClaw приймає джерела з відносними шляхами з цього репозиторію та відхиляє HTTP(S), абсолютні шляхи, git, GitHub та інші не-шляхові джерела Plugin із віддалених маніфестів.
|
||||
<Tab title="Правила віддаленого Marketplace">
|
||||
Для віддалених Marketplace, завантажених із GitHub або git, записи Plugin мають залишатися всередині клонованого репозиторію Marketplace. OpenClaw приймає джерела з відносними шляхами з цього репозиторію та відхиляє HTTP(S), абсолютні шляхи, git, GitHub та інші не-шляхові джерела Plugin з віддалених маніфестів.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
@ -221,11 +221,11 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
|
||||
|
||||
- нативні Plugin OpenClaw (`openclaw.plugin.json`)
|
||||
- сумісні з Codex пакети (`.codex-plugin/plugin.json`)
|
||||
- сумісні з Claude пакети (`.claude-plugin/plugin.json` або стандартну структуру компонентів Claude)
|
||||
- сумісні з Claude пакети (`.claude-plugin/plugin.json` або типовий макет компонентів Claude)
|
||||
- сумісні з Cursor пакети (`.cursor-plugin/plugin.json`)
|
||||
|
||||
<Note>
|
||||
Сумісні пакети встановлюються у звичайний корінь Plugin і беруть участь у тому самому потоці list/info/enable/disable. Наразі підтримуються Skills пакетів, command-skills Claude, стандартні значення Claude `settings.json`, стандартні значення Claude `.lsp.json` / оголошених у маніфесті `lspServers`, command-skills Cursor і сумісні каталоги hook Codex; інші виявлені можливості пакетів показуються в діагностиці/info, але ще не підключені до виконання під час роботи.
|
||||
Сумісні пакети встановлюються у звичайний корінь Plugin і беруть участь у тому самому потоці list/info/enable/disable. Наразі підтримуються Skills пакетів, command-skills Claude, типові значення Claude `settings.json`, типові значення Claude `.lsp.json` / оголошені в маніфесті `lspServers`, command-skills Cursor і сумісні каталоги hook Codex; інші виявлені можливості пакетів показуються в діагностиці/info, але ще не підключені до виконання під час роботи.
|
||||
</Note>
|
||||
|
||||
### Список
|
||||
@ -241,50 +241,55 @@ openclaw plugins search <query> --json
|
||||
```
|
||||
|
||||
<ParamField path="--enabled" type="boolean">
|
||||
Показувати лише ввімкнені Plugin.
|
||||
Показати лише ввімкнені plugins.
|
||||
</ParamField>
|
||||
<ParamField path="--verbose" type="boolean">
|
||||
Перемкнутися з табличного подання на рядки деталей для кожного Plugin із метаданими джерела/походження/версії/активації.
|
||||
Перемкнутися з табличного подання на рядки деталей для кожного Plugin з метаданими джерела/походження/версії/активації.
|
||||
</ParamField>
|
||||
<ParamField path="--json" type="boolean">
|
||||
Машиночитний інвентар, а також діагностика реєстру й стан встановлення залежностей пакета.
|
||||
Машиночитний інвентар, а також діагностика реєстру й стан встановлення залежностей пакунків.
|
||||
</ParamField>
|
||||
|
||||
<Note>
|
||||
`plugins list` спершу читає збережений локальний реєстр Plugin, із резервним варіантом, виведеним лише з маніфестів, коли реєстр відсутній або недійсний. Це корисно, щоб перевірити, чи Plugin встановлений, увімкнений і видимий для планування холодного запуску, але це не live-зонд процесу Gateway, який уже працює. Після зміни коду Plugin, стану ввімкнення, політики hook або `plugins.load.paths` перезапустіть Gateway, який обслуговує канал, перш ніж очікувати виконання нового коду `register(api)` або hook. Для віддалених/контейнерних розгортань перевірте, що перезапускаєте фактичний дочірній процес `openclaw gateway run`, а не лише процес-обгортку.
|
||||
`plugins list` спершу читає збережений локальний реєстр Plugin, із резервним варіантом, похідним лише від маніфестів, коли реєстр відсутній або недійсний. Це корисно для перевірки, чи Plugin встановлено, увімкнено та видно для планування холодного запуску, але це не живий runtime-зонд уже запущеного процесу Gateway. Після зміни коду Plugin, увімкнення, політики hook або `plugins.load.paths` перезапустіть Gateway, який обслуговує канал, перш ніж очікувати запуску нового коду `register(api)` або hook. Для віддалених/контейнерних розгортань перевірте, що ви перезапускаєте фактичний дочірній процес `openclaw gateway run`, а не лише процес-обгортку.
|
||||
|
||||
`plugins list --json` включає `dependencyStatus` кожного Plugin з `dependencies` і `optionalDependencies` у `package.json`. OpenClaw перевіряє, чи ці назви пакетів присутні вздовж звичайного для Plugin шляху пошуку Node `node_modules`; він не імпортує runtime-код Plugin, не запускає менеджер пакетів і не виправляє відсутні залежності.
|
||||
`plugins list --json` включає `dependencyStatus` кожного Plugin з `package.json`
|
||||
`dependencies` і `optionalDependencies`. OpenClaw перевіряє, чи наявні ці назви пакунків уздовж звичайного шляху пошуку Node `node_modules` для Plugin; він не імпортує runtime-код Plugin, не запускає менеджер пакунків і не виправляє відсутні залежності.
|
||||
</Note>
|
||||
|
||||
`plugins search` — це віддалений пошук у каталозі ClawHub. Він не перевіряє локальний
|
||||
стан, не змінює конфігурацію, не встановлює пакети й не завантажує runtime-код Plugin. Результати пошуку містять назву пакета ClawHub, сімейство, канал, версію, короткий опис і підказку для встановлення, як-от `openclaw plugins install clawhub:<package>`.
|
||||
стан, не змінює конфігурацію, не встановлює пакунки й не завантажує runtime-код Plugin. Результати пошуку включають назву пакунка ClawHub, сімейство, канал, версію, короткий опис і
|
||||
підказку для встановлення, наприклад `openclaw plugins install clawhub:<package>`.
|
||||
|
||||
Для роботи з вбудованими Plugin усередині запакованого Docker-образу змонтуйте вихідний каталог Plugin поверх відповідного запакованого шляху до джерел, наприклад
|
||||
`/app/extensions/synology-chat`. OpenClaw виявить це змонтоване накладання джерел перед `/app/dist/extensions/synology-chat`; просто скопійований каталог джерел залишиться неактивним, тому звичайні запаковані встановлення й далі використовуватимуть скомпільований dist.
|
||||
Для роботи з вбудованим Plugin всередині пакетованого Docker-образу змонтуйте вихідний каталог Plugin
|
||||
поверх відповідного пакетованого вихідного шляху, наприклад
|
||||
`/app/extensions/synology-chat`. OpenClaw виявить це змонтоване вихідне
|
||||
накладання перед `/app/dist/extensions/synology-chat`; звичайний скопійований вихідний
|
||||
каталог залишиться неактивним, тому стандартні пакетовані встановлення й надалі використовуватимуть скомпільований dist.
|
||||
|
||||
Для налагодження runtime hook:
|
||||
|
||||
- `openclaw plugins inspect <id> --runtime --json` показує зареєстровані hook і діагностику з проходу інспекції із завантаженням модуля. Runtime-інспекція ніколи не встановлює залежності; використовуйте `openclaw doctor --fix`, щоб очистити застарілий стан залежностей або встановити відсутні налаштовані завантажувані Plugin.
|
||||
- `openclaw gateway status --deep --require-rpc` підтверджує доступний Gateway, підказки щодо сервісу/процесу, шлях до конфігурації та справність RPC.
|
||||
- `openclaw plugins inspect <id> --runtime --json` показує зареєстровані hook і діагностику з проходу інспекції із завантаженим модулем. Runtime-інспекція ніколи не встановлює залежності; використовуйте `openclaw doctor --fix`, щоб очистити застарілий стан залежностей або встановити відсутні налаштовані завантажувані plugins.
|
||||
- `openclaw gateway status --deep --require-rpc` підтверджує досяжний Gateway, підказки щодо сервісу/процесу, шлях конфігурації та справність RPC.
|
||||
- Невбудовані hook розмов (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) потребують `plugins.entries.<id>.hooks.allowConversationAccess=true`.
|
||||
|
||||
Використовуйте `--link`, щоб не копіювати локальний каталог (додає до `plugins.load.paths`):
|
||||
Використовуйте `--link`, щоб не копіювати локальний каталог (додає його до `plugins.load.paths`):
|
||||
|
||||
```bash
|
||||
openclaw plugins install -l ./my-plugin
|
||||
```
|
||||
|
||||
<Note>
|
||||
`--force` не підтримується з `--link`, тому що зв’язані встановлення повторно використовують шлях до джерел замість копіювання поверх керованої цілі встановлення.
|
||||
`--force` не підтримується з `--link`, оскільки пов’язані встановлення повторно використовують вихідний шлях замість копіювання поверх керованої цілі встановлення.
|
||||
|
||||
Використовуйте `--pin` для npm-встановлень, щоб зберегти вирішену точну специфікацію (`name@version`) у керованому індексі Plugin, залишаючи типову поведінку незакріпленою.
|
||||
Використовуйте `--pin` для npm-встановлень, щоб зберегти розв’язаний точний spec (`name@version`) у керованому індексі Plugin, зберігаючи типову поведінку без фіксації.
|
||||
</Note>
|
||||
|
||||
### Індекс Plugin
|
||||
|
||||
Метадані встановлення Plugin — це машинно керований стан, а не користувацька конфігурація. Встановлення й оновлення записують його до `plugins/installs.json` в активному каталозі стану OpenClaw. Його верхньорівнева мапа `installRecords` є тривалим джерелом метаданих встановлення, включно із записами для пошкоджених або відсутніх маніфестів Plugin. Масив `plugins` — це виведений із маніфестів кеш холодного реєстру. Файл містить попередження не редагувати його та використовується `openclaw plugins update`, видаленням, діагностикою й холодним реєстром Plugin.
|
||||
Метадані встановлення Plugin — це керований машиною стан, а не користувацька конфігурація. Встановлення й оновлення записують його в `plugins/installs.json` у активному каталозі стану OpenClaw. Його верхньорівнева мапа `installRecords` є довготривалим джерелом метаданих встановлення, включно із записами для зламаних або відсутніх маніфестів Plugin. Масив `plugins` — це похідний від маніфестів кеш холодного реєстру. Файл містить попередження не редагувати його та використовується `openclaw plugins update`, видаленням, діагностикою й холодним реєстром Plugin.
|
||||
|
||||
Коли OpenClaw бачить поставлені застарілі записи `plugins.installs` у конфігурації, він переносить їх до індексу Plugin і вилучає ключ конфігурації; якщо будь-який запис не вдається, записи конфігурації зберігаються, щоб метадані встановлення не були втрачені.
|
||||
Коли OpenClaw бачить поставлені застарілі записи `plugins.installs` у конфігурації, він переносить їх в індекс Plugin і видаляє ключ конфігурації; якщо будь-який запис не вдається, записи конфігурації зберігаються, щоб метадані встановлення не було втрачено.
|
||||
|
||||
### Видалення
|
||||
|
||||
@ -294,7 +299,7 @@ openclaw plugins uninstall <id> --dry-run
|
||||
openclaw plugins uninstall <id> --keep-files
|
||||
```
|
||||
|
||||
`uninstall` вилучає записи Plugin з `plugins.entries`, збереженого індексу Plugin, записів списку дозволів/заборон Plugin і пов’язаних записів `plugins.load.paths`, коли це застосовно. Якщо `--keep-files` не задано, видалення також вилучає відстежуваний керований каталог встановлення, коли він розташований усередині кореня розширень Plugin OpenClaw. Для Plugin активної пам’яті слот пам’яті скидається до `memory-core`.
|
||||
`uninstall` видаляє записи Plugin з `plugins.entries`, збереженого індексу Plugin, записів списків дозволу/заборони Plugin і пов’язаних записів `plugins.load.paths`, коли застосовно. Якщо не задано `--keep-files`, видалення також прибирає відстежуваний каталог керованого встановлення, коли він розташований усередині кореня розширень Plugin OpenClaw. Для plugins Active Memory слот пам’яті скидається до `memory-core`.
|
||||
|
||||
<Note>
|
||||
`--keep-config` підтримується як застарілий псевдонім для `--keep-files`.
|
||||
@ -313,26 +318,26 @@ openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-ins
|
||||
Оновлення застосовуються до відстежуваних встановлень Plugin у керованому індексі Plugin і відстежуваних встановлень hook-pack у `hooks.internal.installs`.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Вирішення id Plugin і npm spec">
|
||||
Коли ви передаєте id Plugin, OpenClaw повторно використовує записану специфікацію встановлення для цього Plugin. Це означає, що раніше збережені dist-tags, як-от `@beta`, і точні закріплені версії надалі використовуються під час наступних запусків `update <id>`.
|
||||
<Accordion title="Розв’язання id Plugin порівняно з npm spec">
|
||||
Коли ви передаєте id Plugin, OpenClaw повторно використовує записаний spec встановлення для цього Plugin. Це означає, що раніше збережені dist-tags, як-от `@beta`, і точні зафіксовані версії продовжують використовуватися під час наступних запусків `update <id>`.
|
||||
|
||||
Для npm-встановлень ви також можете передати явну специфікацію npm-пакета з dist-tag або точною версією. OpenClaw зіставляє цю назву пакета з відстежуваним записом Plugin, оновлює цей встановлений Plugin і записує нову npm-специфікацію для майбутніх оновлень на основі id.
|
||||
Для npm-встановлень ви також можете передати явний npm package spec із dist-tag або точною версією. OpenClaw зіставляє цю назву пакунка з відстежуваним записом Plugin, оновлює цей встановлений Plugin і записує новий npm spec для майбутніх оновлень за id.
|
||||
|
||||
Передавання назви npm-пакета без версії або тегу також зіставляється з відстежуваним записом Plugin. Використовуйте це, коли Plugin був закріплений на точній версії, а ви хочете повернути його до стандартної лінії випусків реєстру.
|
||||
Передання назви npm-пакунка без версії або тега також зіставляється з відстежуваним записом Plugin. Використовуйте це, коли Plugin було зафіксовано на точній версії й ви хочете повернути його до типової лінії випусків реєстру.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Оновлення beta-каналу">
|
||||
`openclaw plugins update` повторно використовує відстежувану специфікацію Plugin, якщо ви не передасте нову специфікацію. `openclaw update` додатково знає активний канал оновлень OpenClaw: на beta-каналі записи npm і ClawHub Plugin стандартної лінії спершу пробують `@beta`, а потім повертаються до записаної стандартної/latest специфікації, якщо beta-випуску Plugin не існує. Точні версії та явні теги залишаються закріпленими за цим селектором.
|
||||
`openclaw plugins update` повторно використовує відстежуваний spec Plugin, якщо ви не передасте новий spec. `openclaw update` додатково знає активний канал оновлень OpenClaw: на beta-каналі записи npm і ClawHub Plugin типової лінії спершу пробують `@beta`, а потім повертаються до записаного default/latest spec, якщо beta-випуску Plugin не існує. Точні версії та явні теги залишаються зафіксованими на цьому селекторі.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Перевірки версій і дрейф цілісності">
|
||||
Перед live-оновленням npm OpenClaw перевіряє встановлену версію пакета за метаданими npm-реєстру. Якщо встановлена версія й записана ідентичність артефакту вже збігаються з вирішеною ціллю, оновлення пропускається без завантаження, повторного встановлення або перезапису `openclaw.json`.
|
||||
Перед живим npm-оновленням OpenClaw перевіряє встановлену версію пакунка за метаданими npm-реєстру. Якщо встановлена версія та записана ідентичність артефакту вже відповідають розв’язаній цілі, оновлення пропускається без завантаження, перевстановлення або перезапису `openclaw.json`.
|
||||
|
||||
Коли існує збережений hash цілісності, а hash отриманого артефакту змінюється, OpenClaw трактує це як дрейф npm-артефакту. Інтерактивна команда `openclaw plugins update` друкує очікуваний і фактичний hashes та просить підтвердження перед продовженням. Неінтерактивні помічники оновлення завершуються із закритою відмовою, якщо викликач не надасть явну політику продовження.
|
||||
Коли збережений integrity hash існує, а hash отриманого артефакту змінюється, OpenClaw трактує це як дрейф npm-артефакту. Інтерактивна команда `openclaw plugins update` виводить очікуваний і фактичний hashes і просить підтвердження перед продовженням. Неінтерактивні помічники оновлення завершуються закрито, якщо викликач не надає явну політику продовження.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--dangerously-force-unsafe-install під час оновлення">
|
||||
`--dangerously-force-unsafe-install` також доступний у `plugins update` як аварійне перевизначення для хибних спрацьовувань вбудованого сканування небезпечного коду під час оновлень Plugin. Він усе одно не обходить блокування політики `before_install` Plugin або блокування через збій сканування, і застосовується лише до оновлень Plugin, а не до оновлень hook-pack.
|
||||
<Accordion title="--dangerously-force-unsafe-install під час update">
|
||||
`--dangerously-force-unsafe-install` також доступний у `plugins update` як аварійне перевизначення для хибнопозитивних спрацьовувань вбудованого сканування небезпечного коду під час оновлень Plugin. Він однаково не обходить блокування політик Plugin `before_install` або блокування через збій сканування, і застосовується лише до оновлень Plugin, а не до оновлень hook-pack.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -344,21 +349,21 @@ openclaw plugins inspect <id> --runtime
|
||||
openclaw plugins inspect <id> --json
|
||||
```
|
||||
|
||||
Inspect показує ідентичність, стан завантаження, джерело, можливості маніфесту, прапорці політики, діагностику, метадані встановлення, можливості пакетів і будь-яку виявлену підтримку серверів MCP або LSP, типово без імпорту runtime-коду Plugin. Додайте `--runtime`, щоб завантажити модуль Plugin і включити зареєстровані hook, tools, commands, services, gateway methods і HTTP routes. Runtime-інспекція прямо повідомляє про відсутні залежності Plugin; встановлення й виправлення залишаються в `openclaw plugins install`, `openclaw plugins update` і `openclaw doctor --fix`.
|
||||
Inspect показує ідентичність, стан завантаження, джерело, можливості маніфесту, прапорці політик, діагностику, метадані встановлення, можливості пакета та будь-яку виявлену підтримку серверів MCP або LSP, типово не імпортуючи runtime Plugin. Додайте `--runtime`, щоб завантажити модуль Plugin і включити зареєстровані hook, tools, commands, services, gateway methods і HTTP routes. Runtime-інспекція повідомляє про відсутні залежності Plugin безпосередньо; встановлення й виправлення залишаються в `openclaw plugins install`, `openclaw plugins update` і `openclaw doctor --fix`.
|
||||
|
||||
CLI-команди, що належать Plugin, встановлюються як кореневі групи команд `openclaw`. Після того як `inspect --runtime` покаже команду в `cliCommands`, запускайте її як `openclaw <command> ...`; наприклад, Plugin, який реєструє `demo-git`, можна перевірити за допомогою `openclaw demo-git ping`.
|
||||
|
||||
Кожен Plugin класифікується за тим, що він фактично реєструє під час роботи:
|
||||
|
||||
- **plain-capability** — один тип можливостей (наприклад, Plugin лише для provider)
|
||||
- **hybrid-capability** — кілька типів можливостей (наприклад, текст + мовлення + зображення)
|
||||
- **hook-only** — лише hook, без можливостей або surface
|
||||
- **plain-capability** — один тип можливості (наприклад, Plugin лише для provider)
|
||||
- **hybrid-capability** — кілька типів можливостей (наприклад, text + speech + images)
|
||||
- **hook-only** — лише hook, без можливостей або поверхонь
|
||||
- **non-capability** — tools/commands/services, але без можливостей
|
||||
|
||||
Докладніше про модель можливостей див. [Форми Plugin](/uk/plugins/architecture#plugin-shapes).
|
||||
|
||||
<Note>
|
||||
Прапорець `--json` виводить машиночитний звіт, придатний для скриптів і аудиту. `inspect --all` відображає таблицю для всього парку зі shape, видами можливостей, повідомленнями сумісності, можливостями пакетів і колонками зведення hook. `info` є псевдонімом для `inspect`.
|
||||
Прапорець `--json` виводить машиночитний звіт, придатний для сценаріїв і аудиту. `inspect --all` відображає таблицю для всього набору з shape, capability kinds, compatibility notices, bundle capabilities і колонками підсумку hook. `info` є псевдонімом для `inspect`.
|
||||
</Note>
|
||||
|
||||
### Doctor
|
||||
@ -367,9 +372,9 @@ CLI-команди, що належать Plugin, встановлюються
|
||||
openclaw plugins doctor
|
||||
```
|
||||
|
||||
`doctor` повідомляє про помилки завантаження Plugin, діагностику маніфесту/виявлення та повідомлення сумісності. Коли все чисто, він друкує `No plugin issues detected.`
|
||||
`doctor` повідомляє про помилки завантаження Plugin, діагностику маніфесту/виявлення та повідомлення про сумісність. Коли все чисто, він виводить `No plugin issues detected.`
|
||||
|
||||
Для збоїв форми модуля, як-от відсутні експорти `register`/`activate`, повторно запустіть із `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, щоб додати до діагностичного виводу компактне зведення форми експортів.
|
||||
Для збоїв форми модуля, як-от відсутні експорти `register`/`activate`, повторно запустіть із `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, щоб включити компактний підсумок форми експорту в діагностичний вивід.
|
||||
|
||||
### Реєстр
|
||||
|
||||
@ -379,12 +384,12 @@ openclaw plugins registry --refresh
|
||||
openclaw plugins registry --json
|
||||
```
|
||||
|
||||
Локальний реєстр Plugin — це збережена в OpenClaw холодна модель читання для ідентичності встановлених Plugin, стану ввімкнення, метаданих джерела та власності внесків. Звичайний запуск, пошук власника provider, класифікація налаштування каналу та інвентар Plugin можуть читати його без імпорту runtime-модулів Plugin.
|
||||
Локальний реєстр Plugin — це збережена OpenClaw модель холодного читання для ідентичності встановлених Plugin, увімкнення, метаданих джерела та володіння внесками. Звичайний запуск, пошук власника provider, класифікація налаштування channel і інвентар Plugin можуть читати його без імпорту runtime-модулів Plugin.
|
||||
|
||||
Використовуйте `plugins registry`, щоб перевірити, чи збережений реєстр присутній, актуальний або застарілий. Використовуйте `--refresh`, щоб перебудувати його зі збереженого індексу Plugin, політики конфігурації та метаданих маніфесту/пакета. Це шлях виправлення, а не шлях runtime-активації.
|
||||
Використовуйте `plugins registry`, щоб перевірити, чи збережений реєстр наявний, актуальний або застарілий. Використовуйте `--refresh`, щоб перебудувати його зі збереженого індексу Plugin, політики конфігурації та метаданих маніфесту/пакунка. Це шлях виправлення, а не шлях runtime-активації.
|
||||
|
||||
<Warning>
|
||||
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` — це застарілий аварійний перемикач сумісності для збоїв читання реєстру. Надавайте перевагу `plugins registry --refresh` або `openclaw doctor --fix`; резервний env-механізм призначений лише для аварійного відновлення запуску, поки міграція розгортається.
|
||||
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` — застарілий аварійний перемикач сумісності для збоїв читання реєстру. Віддавайте перевагу `plugins registry --refresh` або `openclaw doctor --fix`; резервний варіант через змінну середовища призначений лише для аварійного відновлення запуску під час розгортання міграції.
|
||||
</Warning>
|
||||
|
||||
### Маркетплейс
|
||||
@ -394,10 +399,10 @@ openclaw plugins marketplace list <source>
|
||||
openclaw plugins marketplace list <source> --json
|
||||
```
|
||||
|
||||
Список маркетплейсу приймає локальний шлях до маркетплейсу, шлях до `marketplace.json`, скорочення GitHub на кшталт `owner/repo`, URL репозиторію GitHub або git URL. `--json` виводить мітку розв’язаного джерела, а також розібраний маніфест маркетплейсу та записи Plugin.
|
||||
Список маркетплейсу приймає локальний шлях до маркетплейсу, шлях до `marketplace.json`, скорочений запис GitHub на кшталт `owner/repo`, URL репозиторію GitHub або git URL. `--json` виводить визначену мітку джерела, а також розібраний маніфест маркетплейсу й записи плагінів.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Створення Plugin](/uk/plugins/building-plugins)
|
||||
- [Створення плагінів](/uk/plugins/building-plugins)
|
||||
- [Довідник CLI](/uk/cli)
|
||||
- [Plugin спільноти](/uk/plugins/community)
|
||||
- [Плагіни спільноти](/uk/plugins/community)
|
||||
|
||||
@ -1,65 +1,85 @@
|
||||
---
|
||||
read_when:
|
||||
- Створення або запуск візуальної перевірки якості в реальному часі для помилок OpenClaw
|
||||
- Створення або запуск візуальної перевірки якості наживо для помилок OpenClaw
|
||||
- Додавання перевірки до та після для запиту на злиття
|
||||
- Додавання сценаріїв із Discord, Slack, WhatsApp або іншими реальними транспортами
|
||||
- Налагодження запусків QA, для яких потрібні знімки екрана, автоматизація браузера або доступ через VNC
|
||||
summary: Mantis — це система візуальної наскрізної перевірки для відтворення помилок OpenClaw у реальних транспортах, фіксації доказів до й після та прикріплення артефактів до PR.
|
||||
- Додавання сценаріїв із живим транспортом для Discord, Slack, WhatsApp або інших сервісів
|
||||
- Налагодження запусків QA, яким потрібні знімки екрана, автоматизація браузера або доступ VNC
|
||||
summary: Mantis — це візуальна система наскрізної перевірки для відтворення помилок OpenClaw у живих транспортах, фіксації доказів до й після та прикріплення артефактів до запитів на злиття.
|
||||
title: Богомол
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T16:48:36Z"
|
||||
generated_at: "2026-05-03T17:12:23Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 5b58934ec88a640745f7430c875c377e898f87f1b3d4a9ef03115395084664f5
|
||||
source_hash: 2a038872d2754b380a0983d81869de247d66c41b49746e1608dca215ab2096a7
|
||||
source_path: concepts/mantis.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Mantis — це система наскрізної верифікації OpenClaw для помилок, яким потрібні реальне середовище виконання, реальний транспорт і видимий доказ. Вона запускає сценарій проти відомого поганого ref, збирає докази, запускає той самий сценарій проти кандидатного ref і публікує порівняння як артефакти, які мейнтейнер може переглянути з PR або з локальної команди.
|
||||
Mantis — це система наскрізної перевірки OpenClaw для багів, яким потрібні справжнє
|
||||
середовище виконання, справжній транспорт і видимий доказ. Вона запускає сценарій на відомому
|
||||
поганому ref, збирає докази, запускає той самий сценарій на кандидатному ref і
|
||||
публікує порівняння як артефакти, які мейнтейнер може перевірити з PR або
|
||||
з локальної команди.
|
||||
|
||||
Mantis починає з Discord, бо Discord дає нам високоцінний перший напрям: справжню автентифікацію бота, реальні канали guild, реакції, треди, нативні команди й браузерний UI, де люди можуть візуально підтвердити, що показав транспорт.
|
||||
Mantis починає з Discord, тому що Discord дає нам цінну першу смугу:
|
||||
справжню автентифікацію бота, справжні канали гільдії, реакції, потоки, нативні команди та
|
||||
інтерфейс браузера, де люди можуть візуально підтвердити, що показав транспорт.
|
||||
|
||||
## Цілі
|
||||
|
||||
- Відтворити помилку з GitHub issue або PR з тією самою формою транспорту, яку бачать користувачі.
|
||||
- Відтворити баг з issue або PR на GitHub з тією самою формою транспорту, яку
|
||||
бачать користувачі.
|
||||
- Зібрати артефакт **до** на базовому ref перед застосуванням виправлення.
|
||||
- Зібрати артефакт **після** на кандидатному ref після застосування виправлення.
|
||||
- За можливості використовувати детермінований оракул, наприклад читання реакції Discord REST або перевірку транскрипту каналу.
|
||||
- Збирати знімки екрана, коли помилка має видиму поверхню UI.
|
||||
- Використовувати детермінований оракул, коли це можливо, наприклад читання реакції через REST Discord
|
||||
або перевірку транскрипту каналу.
|
||||
- Знімати скріншоти, коли баг має видиму поверхню UI.
|
||||
- Запускати локально з керованого агентом CLI і віддалено з GitHub.
|
||||
- Зберігати достатньо стану машини для VNC-порятунку, коли вхід, браузерна автоматизація або автентифікація провайдера застрягають.
|
||||
- Публікувати стислий статус в операторський канал Discord, коли запуск заблоковано, потрібна ручна допомога VNC або запуск завершено.
|
||||
- Зберігати достатньо стану машини для порятунку через VNC, коли вхід, автоматизація браузера або
|
||||
автентифікація провайдера застрягає.
|
||||
- Надсилати стислий статус в операторський канал Discord, коли запуск заблоковано,
|
||||
потрібна ручна допомога через VNC або запуск завершено.
|
||||
|
||||
## Нецілі
|
||||
|
||||
- Mantis не є заміною модульних тестів. Запуск Mantis після розуміння виправлення зазвичай має перетворюватися на менший регресійний тест.
|
||||
- Mantis не є звичайним швидким шлюзом CI. Він повільніший, використовує живі облікові дані й призначений для помилок, де живе середовище має значення.
|
||||
- Mantis не має вимагати людини для нормальної роботи. Ручний VNC — це шлях порятунку, а не штатний сценарій.
|
||||
- Mantis не зберігає сирі секрети в артефактах, журналах, знімках екрана, Markdown-звітах або коментарях PR.
|
||||
- Mantis не є заміною для модульних тестів. Запуск Mantis зазвичай має стати
|
||||
меншим регресійним тестом після того, як виправлення зрозуміле.
|
||||
- Mantis не є звичайним швидким CI-шлюзом. Він повільніший, використовує живі облікові дані та
|
||||
призначений для багів, де живе середовище має значення.
|
||||
- Mantis не повинен вимагати людину для нормальної роботи. Ручний VNC — це шлях порятунку,
|
||||
а не штатний шлях.
|
||||
- Mantis не зберігає сирі секрети в артефактах, журналах, скріншотах, Markdown-звітах
|
||||
або коментарях PR.
|
||||
|
||||
## Володіння
|
||||
## Власність
|
||||
|
||||
Mantis належить до стеку QA OpenClaw.
|
||||
Mantis живе в QA-стеку OpenClaw.
|
||||
|
||||
- OpenClaw володіє середовищем виконання сценаріїв, транспортними адаптерами, схемою доказів і локальним CLI під `pnpm openclaw qa mantis`.
|
||||
- QA Lab володіє частинами harness для живого транспорту, помічниками браузерного захоплення й записувачами артефактів.
|
||||
- OpenClaw володіє середовищем виконання сценаріїв, транспортними адаптерами, схемою доказів і
|
||||
локальним CLI під `pnpm openclaw qa mantis`.
|
||||
- QA Lab володіє компонентами живого транспортного harness, допоміжними засобами захоплення браузера та
|
||||
записувачами артефактів.
|
||||
- Crabbox володіє прогрітими Linux-машинами, коли потрібна віддалена VM.
|
||||
- GitHub Actions володіє віддаленою точкою входу workflow і збереженням артефактів.
|
||||
- ClawSweeper володіє маршрутизацією коментарів GitHub: розбором команд мейнтейнерів, dispatch workflow і публікацією фінального коментаря PR.
|
||||
- Агенти OpenClaw керують Mantis через Codex, коли сценарію потрібні агентне налаштування, налагодження або звітування про застряглий стан.
|
||||
- GitHub Actions володіє віддаленою точкою входу workflow та зберіганням артефактів.
|
||||
- ClawSweeper володіє маршрутизацією коментарів GitHub: розбором команд мейнтейнерів,
|
||||
запуском workflow і публікацією фінального коментаря PR.
|
||||
- Агенти OpenClaw керують Mantis через Codex, коли сценарію потрібні агентне налаштування,
|
||||
налагодження або звітування про застряглий стан.
|
||||
|
||||
Ця межа тримає знання про транспорт в OpenClaw, планування машин у Crabbox, а клей мейнтейнерського workflow у ClawSweeper.
|
||||
Ця межа тримає знання про транспорт в OpenClaw, планування машин у
|
||||
Crabbox, а клей мейнтейнерського workflow у ClawSweeper.
|
||||
|
||||
## Форма команди
|
||||
## Форма команд
|
||||
|
||||
Перша локальна команда перевіряє бота Discord, guild, канал, надсилання повідомлення, надсилання реакції та шлях артефактів:
|
||||
Перша локальна команда перевіряє бота Discord, гільдію, канал, надсилання повідомлення,
|
||||
надсилання реакції та шлях артефактів:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa mantis discord-smoke \
|
||||
--output-dir .artifacts/qa-e2e/mantis/discord-smoke
|
||||
```
|
||||
|
||||
Пізніший runner для до і після має приймати таку форму:
|
||||
Пізніший runner до і після має приймати таку форму:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa mantis run \
|
||||
@ -70,12 +90,17 @@ pnpm openclaw qa mantis run \
|
||||
--output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions
|
||||
```
|
||||
|
||||
Smoke workflow GitHub — це `Mantis Discord Smoke`. Workflow GitHub для до і після першого реального сценарію — це `Mantis Discord Status Reactions`. Він приймає:
|
||||
Димовий workflow GitHub — `Mantis Discord Smoke`. Workflow GitHub до і після
|
||||
для першого справжнього сценарію — `Mantis Discord Status Reactions`. Він
|
||||
приймає:
|
||||
|
||||
- `baseline_ref`: ref, на якому очікується відтворення поведінки лише queued.
|
||||
- `candidate_ref`: ref, на якому очікується показ `queued -> thinking -> done`.
|
||||
- `baseline_ref`: ref, який має відтворювати поведінку лише з queued.
|
||||
- `candidate_ref`: ref, який має показувати `queued -> thinking -> done`.
|
||||
|
||||
Він checkout-ить ref harness workflow, будує окремі worktree для baseline і candidate, запускає `discord-status-reactions-tool-only` проти кожного worktree та завантажує `baseline/`, `candidate/`, `comparison.json` і `mantis-report.md` як артефакти Actions.
|
||||
Він checkout-ить ref harness workflow, створює окремі worktree для baseline і candidate,
|
||||
запускає `discord-status-reactions-tool-only` проти кожного worktree і
|
||||
завантажує `baseline/`, `candidate/`, `comparison.json` і `mantis-report.md` як
|
||||
артефакти Actions.
|
||||
|
||||
Приклади команд ClawSweeper:
|
||||
|
||||
@ -84,7 +109,9 @@ Smoke workflow GitHub — це `Mantis Discord Smoke`. Workflow GitHub для д
|
||||
@clawsweeper verify e2e discord
|
||||
```
|
||||
|
||||
Перша команда явна й зосереджена на сценарії. Друга згодом може зіставляти PR або issue з рекомендованими сценаріями Mantis на основі міток, змінених файлів і знахідок рев’ю ClawSweeper.
|
||||
Перша команда явна й зосереджена на сценарії. Друга згодом може зіставляти PR
|
||||
або issue з рекомендованими сценаріями Mantis за мітками, зміненими файлами та
|
||||
знахідками рев’ю ClawSweeper.
|
||||
|
||||
## Життєвий цикл запуску
|
||||
|
||||
@ -92,34 +119,38 @@ Smoke workflow GitHub — це `Mantis Discord Smoke`. Workflow GitHub для д
|
||||
2. Виділити або повторно використати VM.
|
||||
3. Підготувати чистий checkout для базового ref.
|
||||
4. Встановити залежності й зібрати лише те, що потрібно сценарію.
|
||||
5. Запустити дочірній OpenClaw Gateway з ізольованим каталогом стану.
|
||||
5. Запустити дочірній OpenClaw Gateway з ізольованою директорією стану.
|
||||
6. Налаштувати живий транспорт, провайдера, модель і профіль браузера.
|
||||
7. Запустити сценарій і зібрати базові докази.
|
||||
8. Зупинити Gateway і зберегти журнали.
|
||||
9. Підготувати кандидатний ref у тій самій VM.
|
||||
10. Запустити той самий сценарій і зібрати кандидатні докази.
|
||||
11. Порівняти результати оракула й візуальні докази.
|
||||
12. Записати Markdown, JSON, журнали, знімки екрана та опціональні артефакти трасування.
|
||||
11. Порівняти результати оракула та візуальні докази.
|
||||
12. Записати Markdown, JSON, журнали, скріншоти та опційні артефакти трасування.
|
||||
13. Завантажити артефакти GitHub Actions.
|
||||
14. Опублікувати стислий статус у PR або Discord.
|
||||
|
||||
Сценарій має вміти завершуватися невдачею двома різними способами:
|
||||
Сценарій має вміти падати двома різними способами:
|
||||
|
||||
- **Помилку відтворено**: baseline впав очікуваним способом.
|
||||
- **Збій harness**: налаштування середовища, облікові дані, Discord API, браузер або провайдер впали до того, як оракул помилки став змістовним.
|
||||
- **Баг відтворено**: baseline впав очікуваним способом.
|
||||
- **Збій harness**: налаштування середовища, облікові дані, API Discord, браузер або
|
||||
провайдер впали до того, як оракул бага став змістовним.
|
||||
|
||||
Фінальний звіт має розділяти ці випадки, щоб мейнтейнери не плутали нестабільне середовище з поведінкою продукту.
|
||||
Фінальний звіт має розділяти ці випадки, щоб мейнтейнери не плутали нестабільне
|
||||
середовище з поведінкою продукту.
|
||||
|
||||
## MVP Discord
|
||||
## MVP для Discord
|
||||
|
||||
Перший сценарій має націлюватися на реакції статусу Discord у каналах guild, де режим доставки вихідної відповіді — `message_tool_only`.
|
||||
Перший сценарій має цілитися в статусні реакції Discord у каналах гільдії, де
|
||||
режим доставки відповіді джерела — `message_tool_only`.
|
||||
|
||||
Чому це хороший початковий сценарій Mantis:
|
||||
Чому це хороше зерно Mantis:
|
||||
|
||||
- Це видно в Discord як реакції на повідомлення, що запустило сценарій.
|
||||
- Він має сильний REST-оракул через стан реакцій повідомлення Discord.
|
||||
- Він перевіряє реальний OpenClaw Gateway, автентифікацію бота Discord, dispatch повідомлення, режим доставки вихідної відповіді, стан реакцій статусу та життєвий цикл ходу моделі.
|
||||
- Він достатньо вузький, щоб перша реалізація залишалася чесною.
|
||||
- Це видно в Discord як реакції на повідомлення-тригер.
|
||||
- Воно має сильний REST-оракул через стан реакцій повідомлення Discord.
|
||||
- Воно перевіряє справжній OpenClaw Gateway, автентифікацію бота Discord, диспетчеризацію повідомлень,
|
||||
режим доставки відповіді джерела, стан статусних реакцій і життєвий цикл ходу моделі.
|
||||
- Воно достатньо вузьке, щоб перша реалізація залишалася чесною.
|
||||
|
||||
Очікувана форма сценарію:
|
||||
|
||||
@ -152,7 +183,10 @@ evidence:
|
||||
screenshotMessageRow: true
|
||||
```
|
||||
|
||||
Базові докази мають показувати реакцію підтвердження queued, але без переходу життєвого циклу в режимі лише інструментів. Кандидатні докази мають показувати виконання реакцій статусу життєвого циклу, коли `messages.statusReactions.enabled` явно дорівнює `true`.
|
||||
Базові докази мають показувати реакцію підтвердження queued, але без
|
||||
переходу життєвого циклу в режимі лише інструмента. Кандидатні докази мають показувати, що статусні
|
||||
реакції життєвого циклу працюють, коли `messages.statusReactions.enabled` явно
|
||||
дорівнює true.
|
||||
|
||||
Виконуваний перший зріз — це opt-in живий QA-сценарій Discord:
|
||||
|
||||
@ -166,24 +200,34 @@ pnpm openclaw qa discord \
|
||||
--output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate
|
||||
```
|
||||
|
||||
Він налаштовує SUT із постійно ввімкненою обробкою guild, `visibleReplies:
|
||||
"message_tool"`, `ackReaction: "👀"` і явними реакціями статусу. Оракул опитує справжнє повідомлення-тригер Discord і очікує спостережувану послідовність `👀 -> 🤔 -> 👍`. Артефакти включають `discord-qa-reaction-timelines.json`, `discord-status-reactions-tool-only-timeline.html` і `discord-status-reactions-tool-only-timeline.png`.
|
||||
Він налаштовує SUT з постійно увімкненою обробкою гільдій, `visibleReplies:
|
||||
"message_tool"`, `ackReaction: "👀"` і явними статусними реакціями. Оракул
|
||||
опитує справжнє повідомлення-тригер Discord і очікує спостережувану послідовність
|
||||
`👀 -> 🤔 -> 👍`. Артефакти включають `discord-qa-reaction-timelines.json`,
|
||||
`discord-status-reactions-tool-only-timeline.html` і
|
||||
`discord-status-reactions-tool-only-timeline.png`.
|
||||
|
||||
## Наявні частини QA
|
||||
## Наявні компоненти QA
|
||||
|
||||
Mantis має будуватися на наявному приватному стеку QA замість старту з нуля:
|
||||
Mantis має будуватися на наявному приватному QA-стеку замість починати з
|
||||
нуля:
|
||||
|
||||
- `pnpm openclaw qa discord` вже запускає живий напрям Discord з ботами driver і SUT.
|
||||
- Runner живого транспорту вже записує звіти та артефакти спостережуваних повідомлень у `.artifacts/qa-e2e/`.
|
||||
- Оренди облікових даних Convex уже надають ексклюзивний доступ до спільних живих транспортних облікових даних.
|
||||
- Сервіс керування браузером уже підтримує знімки екрана, snapshots, headless керовані профілі та віддалені профілі CDP.
|
||||
- QA Lab уже має UI налагоджувача і шину для тестування у формі транспорту.
|
||||
- `pnpm openclaw qa discord` уже запускає живу смугу Discord з ботами driver і
|
||||
SUT.
|
||||
- Живий транспортний runner уже записує звіти й артефакти спостережених повідомлень
|
||||
під `.artifacts/qa-e2e/`.
|
||||
- Оренди облікових даних Convex уже надають ексклюзивний доступ до спільних живих
|
||||
транспортних облікових даних.
|
||||
- Сервіс керування браузером уже підтримує скріншоти, снапшоти,
|
||||
керовані headless-профілі та віддалені CDP-профілі.
|
||||
- QA Lab уже має UI налагоджувача і bus для тестування у формі транспорту.
|
||||
|
||||
Перша реалізація Mantis може бути тонким runner до/після поверх цих частин плюс один шар візуальних доказів.
|
||||
Перша реалізація Mantis може бути тонким runner до/після поверх цих
|
||||
компонентів плюс один шар візуальних доказів.
|
||||
|
||||
## Модель доказів
|
||||
|
||||
Кожен запуск записує стабільний каталог артефактів:
|
||||
Кожен запуск записує стабільну директорію артефактів:
|
||||
|
||||
```text
|
||||
.artifacts/qa-e2e/mantis/<run-id>/
|
||||
@ -203,63 +247,77 @@ Mantis має будуватися на наявному приватному с
|
||||
run.log
|
||||
```
|
||||
|
||||
`mantis-summary.json` має бути машинозчитуваним джерелом істини. Markdown-звіт призначений для коментарів PR і людського рев’ю.
|
||||
`mantis-summary.json` має бути машиночитним джерелом істини. Звіт
|
||||
Markdown призначений для коментарів PR і людського рев’ю.
|
||||
|
||||
Підсумок має включати:
|
||||
Зведення має включати:
|
||||
|
||||
- протестовані refs і SHA
|
||||
- транспорт і id сценарію
|
||||
- провайдера машини та id машини або id оренди
|
||||
- джерело облікових даних без секретних значень
|
||||
- джерело облікових даних без значень секретів
|
||||
- результат baseline
|
||||
- результат candidate
|
||||
- чи відтворилася помилка на baseline
|
||||
- чи candidate її виправив
|
||||
- чи відтворився баг на baseline
|
||||
- чи candidate виправив його
|
||||
- шляхи артефактів
|
||||
- очищені проблеми налаштування або очищення
|
||||
- очищені від секретів проблеми налаштування або очищення
|
||||
|
||||
Знімки екрана — це докази, а не секрети. Вони все одно потребують дисципліни редагування: можуть з’явитися назви приватних каналів, імена користувачів або вміст повідомлень. Для публічних PR віддавайте перевагу посиланням на артефакти GitHub Actions замість inline-зображень, доки історія редагування не стане сильнішою.
|
||||
Скріншоти — це докази, а не секрети. Вони все одно потребують дисципліни редагування:
|
||||
можуть з’являтися приватні назви каналів, імена користувачів або вміст повідомлень. Для публічних PR
|
||||
надавайте перевагу посиланням на артефакти GitHub Actions замість вбудованих зображень, доки історія
|
||||
редагування не стане сильнішою.
|
||||
|
||||
## Браузер і VNC
|
||||
|
||||
Браузерний напрям має два режими:
|
||||
Браузерна смуга має два режими:
|
||||
|
||||
- **Headless-автоматизація**: типово для CI. Chrome працює з увімкненим CDP, а Playwright або браузерне керування OpenClaw збирає знімки екрана.
|
||||
- **VNC-порятунок**: вмикається на тій самій VM, коли вхід, MFA, антиавтоматизація Discord або візуальне налагодження потребують людини.
|
||||
- **Headless-автоматизація**: типово для CI. Chrome запускається з увімкненим CDP, а
|
||||
Playwright або керування браузером OpenClaw збирає скріншоти.
|
||||
- **Порятунок через VNC**: вмикається на тій самій VM, коли вхід, MFA, антиавтоматизація Discord
|
||||
або візуальне налагодження потребують людини.
|
||||
|
||||
Профіль браузера-спостерігача Discord має бути достатньо persistent, щоб не входити в систему під час кожного запуску, але ізольованим від особистого стану браузера. Профіль належить пулу машин Mantis, а не ноутбуку розробника.
|
||||
Профіль браузера-спостерігача Discord має бути достатньо постійним, щоб уникати
|
||||
входу в кожному запуску, але ізольованим від особистого стану браузера. Профіль
|
||||
належить пулу машин Mantis, а не ноутбуку розробника.
|
||||
|
||||
Коли Mantis застрягає, він публікує статусне повідомлення Discord з такими даними:
|
||||
Коли Mantis застрягає, він публікує статусне повідомлення Discord з:
|
||||
|
||||
- id запуску
|
||||
- id сценарію
|
||||
- провайдер машини
|
||||
- каталог артефактів
|
||||
- інструкції підключення VNC або noVNC, якщо доступні
|
||||
- короткий текст блокера
|
||||
- провайдером машини
|
||||
- директорією артефактів
|
||||
- інструкціями підключення VNC або noVNC, якщо доступні
|
||||
- коротким текстом блокера
|
||||
|
||||
Перше приватне розгортання може публікувати ці повідомлення в наявний операторський канал і пізніше перейти до окремого каналу Mantis.
|
||||
Перше приватне розгортання може публікувати ці повідомлення в наявний операторський
|
||||
канал і перейти до виділеного каналу Mantis пізніше.
|
||||
|
||||
## Машини
|
||||
|
||||
Mantis має віддавати перевагу AWS через Crabbox для першої віддаленої реалізації. Crabbox дає нам прогріті машини, відстеження оренд, hydration, журнали, результати й очищення. Якщо місткість AWS занадто повільна або недоступна, додайте провайдера Hetzner за тим самим інтерфейсом машини.
|
||||
Mantis має надавати перевагу AWS через Crabbox для першої віддаленої реалізації.
|
||||
Crabbox дає нам прогріті машини, відстеження оренд, гідратацію, журнали, результати та
|
||||
очищення. Якщо місткість AWS надто повільна або недоступна, додайте провайдера Hetzner
|
||||
за тим самим інтерфейсом машини.
|
||||
|
||||
Мінімальні вимоги до VM:
|
||||
|
||||
- Linux з інсталяцією Chrome або Chromium, здатною працювати з робочим столом
|
||||
- доступ CDP для браузерної автоматизації
|
||||
- Linux з Chrome або Chromium, придатним для desktop
|
||||
- доступ CDP для автоматизації браузера
|
||||
- VNC або noVNC для порятунку
|
||||
- Node 22 і pnpm
|
||||
- checkout OpenClaw і кеш залежностей
|
||||
- кеш браузера Playwright Chromium, коли використовується Playwright
|
||||
- достатньо CPU і пам’яті для одного OpenClaw Gateway, одного браузера й одного запуску моделі
|
||||
- вихідний доступ до Discord, GitHub, модельних провайдерів і брокера облікових даних
|
||||
- достатньо CPU і пам’яті для одного OpenClaw Gateway, одного браузера та одного запуску моделі
|
||||
- вихідний доступ до Discord, GitHub, провайдерів моделей і брокера облікових даних
|
||||
|
||||
VM не має зберігати довгоживучі сирі секрети поза очікуваними сховищами облікових даних або профілів браузера.
|
||||
VM не повинна зберігати довгоживучі сирі секрети поза очікуваними сховищами облікових даних або
|
||||
профілів браузера.
|
||||
|
||||
## Секрети
|
||||
|
||||
Секрети живуть у секретах організації або репозиторію GitHub для віддалених запусків і в локальному контрольованому оператором файлі секретів для локальних запусків.
|
||||
Секрети живуть у секретах організації або репозиторію GitHub для віддалених запусків і в
|
||||
локальному файлі секретів, керованому оператором, для локальних запусків.
|
||||
|
||||
Рекомендовані назви секретів:
|
||||
|
||||
@ -273,9 +331,10 @@ VM не має зберігати довгоживучі сирі секрети
|
||||
- `OPENCLAW_QA_CONVEX_SITE_URL`
|
||||
- `OPENCLAW_QA_CONVEX_SECRET_CI`
|
||||
|
||||
У довгостроковій перспективі пул облікових даних Convex має залишатися звичайним джерелом для живих транспортних облікових даних. Секрети GitHub bootstrap-лять брокер і резервні напрями.
|
||||
У довгостроковій перспективі пул облікових даних Convex має залишатися звичайним джерелом для живих
|
||||
транспортних облікових даних. Секрети GitHub початково завантажують брокер і fallback-смуги.
|
||||
|
||||
Runner Mantis ніколи не має друкувати:
|
||||
Runner Mantis ніколи не повинен друкувати:
|
||||
|
||||
- токени ботів Discord
|
||||
- API-ключі провайдерів
|
||||
@ -284,15 +343,20 @@ Runner Mantis ніколи не має друкувати:
|
||||
- паролі VNC
|
||||
- сирі payload облікових даних
|
||||
|
||||
Публічні завантаження артефактів також мають редагувати цільові метадані Discord, як-от id бота, guild, каналу й повідомлення. Smoke workflow GitHub вмикає `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` саме з цієї причини.
|
||||
Публічні завантаження артефактів також мають редагувати цільові метадані Discord, як-от bot,
|
||||
guild, channel і message ids. Димовий workflow GitHub вмикає
|
||||
`OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` з цієї причини.
|
||||
|
||||
Якщо токен випадково вставлено в issue, PR, чат або журнал, ротувати його після збереження нового секрету.
|
||||
Якщо токен випадково вставлено в issue, PR, chat або log, поверніть його
|
||||
після того, як новий секрет буде збережено.
|
||||
|
||||
## Артефакти GitHub і коментарі PR
|
||||
|
||||
Робочі процеси Mantis мають завантажувати повний пакет доказів як короткочасний артефакт Actions. Коли робочий процес запускається для звіту про помилку або PR з виправленням, він також має публікувати редаговані PNG-знімки екрана в гілку `qa-artifacts` і створювати або оновлювати коментар до цієї помилки чи PR з виправленням із вбудованими знімками екрана до/після. Не публікуйте основний доказ лише в загальному PR автоматизації QA. Сирі журнали, спостережені повідомлення та інші об’ємні докази залишаються в артефакті Actions.
|
||||
У робочих процесах Mantis слід завантажувати повний пакет доказів як короткочасний артефакт Actions. Коли робочий процес запускається для звіту про помилку або PR із виправленням, він також має публікувати відредаговані PNG-знімки екрана в гілку `qa-artifacts` і оновлювати або створювати коментар у цьому звіті про помилку чи PR із виправленням з вбудованими знімками екрана до/після. Не публікуйте основний доказ лише в загальному PR автоматизації QA. Сирі журнали, спостережені повідомлення та інші об'ємні докази залишаються в артефакті Actions.
|
||||
|
||||
Коментар до PR має бути коротким і візуальним:
|
||||
Виробничі робочі процеси мають публікувати ці коментарі через Mantis GitHub App, а не через `github-actions[bot]`. Зберігайте id застосунку та приватний ключ як секрети GitHub Actions `MANTIS_GITHUB_APP_ID` і `MANTIS_GITHUB_APP_PRIVATE_KEY`. Якщо цих секретів немає, робочий процес може відступити до `github-actions[bot]` для локального запуску, але це не бажана довгострокова ідентичність.
|
||||
|
||||
Коментар у PR має бути коротким і наочним:
|
||||
|
||||
```md
|
||||
Mantis Discord Status Reactions QA
|
||||
@ -312,21 +376,21 @@ candidate showed the expected queued -> thinking -> done sequence.
|
||||
| <inline screenshot> | <inline screenshot> |
|
||||
```
|
||||
|
||||
Коли запуск завершується невдало через збій тестового стенда, у коментарі має бути сказано саме це, а не натяк, що кандидат не пройшов перевірку.
|
||||
Коли запуск завершується невдало через збій обв'язки тестування, коментар має прямо це зазначати, а не створювати враження, що кандидат не пройшов перевірку.
|
||||
|
||||
## Примітки щодо приватного розгортання
|
||||
## Нотатки щодо приватного розгортання
|
||||
|
||||
У приватному розгортанні вже може бути застосунок Mantis Discord. Повторно використайте цей застосунок замість створення іншого, якщо він має належні дозволи бота і його можна безпечно ротувати.
|
||||
У приватному розгортанні вже може бути застосунок Mantis Discord. Повторно використовуйте цей застосунок замість створення ще одного, якщо він має потрібні дозволи бота і його можна безпечно ротувати.
|
||||
|
||||
Задайте початковий канал сповіщень оператора через secrets або конфігурацію розгортання. Спершу він може вказувати на наявний канал супровідників або операційний канал, а потім перейти на окремий канал Mantis, коли він з’явиться.
|
||||
Задайте початковий канал сповіщень оператора через секрети або конфігурацію розгортання. Спершу він може вказувати на наявний канал супровідників або операційний канал, а потім перейти до виділеного каналу Mantis, коли такий з'явиться.
|
||||
|
||||
Не розміщуйте ідентифікатори гільдій, ідентифікатори каналів, токени ботів, браузерні cookie або паролі VNC у цьому документі. Зберігайте їх у GitHub secrets, брокері облікових даних або локальному сховищі секретів оператора.
|
||||
Не додавайте в цей документ id гільдій, id каналів, токени ботів, browser cookies або паролі VNC. Зберігайте їх у секретах GitHub, брокері облікових даних або локальному сховищі секретів оператора.
|
||||
|
||||
## Додавання сценарію
|
||||
|
||||
Сценарій Mantis має оголошувати:
|
||||
|
||||
- ідентифікатор і заголовок
|
||||
- id і назву
|
||||
- транспорт
|
||||
- потрібні облікові дані
|
||||
- політику baseline ref
|
||||
@ -337,35 +401,35 @@ candidate showed the expected queued -> thinking -> done sequence.
|
||||
- очікуваний оракул baseline
|
||||
- очікуваний оракул candidate
|
||||
- цілі візуального захоплення
|
||||
- бюджет часу очікування
|
||||
- бюджет таймауту
|
||||
- кроки очищення
|
||||
|
||||
Сценарії мають надавати перевагу невеликим типізованим оракулам:
|
||||
Сценаріям слід надавати перевагу невеликим типізованим оракулам:
|
||||
|
||||
- стан реакцій Discord для помилок реакцій
|
||||
- посилання на повідомлення Discord для помилок гілкування
|
||||
- thread ts Slack і стан API реакцій для помилок Slack
|
||||
- ідентифікатори повідомлень електронної пошти та заголовки для помилок електронної пошти
|
||||
- знімки екрана браузера, коли UI є єдиним надійним спостережуваним показником
|
||||
- посилання на повідомлення Discord для помилок потоків обговорення
|
||||
- Slack thread ts і стан API реакцій для помилок Slack
|
||||
- id повідомлень електронної пошти та заголовки для помилок електронної пошти
|
||||
- знімки екрана браузера, коли UI є єдиним надійним спостережуваним сигналом
|
||||
|
||||
Перевірки Vision мають бути додатковими. Якщо API платформи може довести помилку, використовуйте API як оракул pass/fail, а знімки екрана залишайте для впевненості людини.
|
||||
Перевірки Vision мають бути додатковими. Якщо API платформи може довести помилку, використовуйте API як оракул успіху/помилки, а знімки екрана залишайте для людської впевненості.
|
||||
|
||||
## Розширення провайдерів
|
||||
|
||||
Після Discord той самий runner може додати:
|
||||
|
||||
- Slack: реакції, гілки, згадки застосунку, модальні вікна, завантаження файлів.
|
||||
- Електронна пошта: автентифікація Gmail і гілкування повідомлень за допомогою `gog`, коли конекторів недостатньо.
|
||||
- WhatsApp: вхід через QR, повторна ідентифікація, доставлення повідомлень, медіа, реакції.
|
||||
- Telegram: обмеження згадок у групах, команди, реакції, де вони доступні.
|
||||
- Matrix: зашифровані кімнати, зв’язки гілок або відповідей, відновлення після перезапуску.
|
||||
- Slack: реакції, потоки обговорення, згадки застосунку, модальні вікна, завантаження файлів.
|
||||
- Електронна пошта: автентифікація Gmail і потоки повідомлень за допомогою `gog`, коли конекторів недостатньо.
|
||||
- WhatsApp: вхід через QR, повторна ідентифікація, доставка повідомлень, медіа, реакції.
|
||||
- Telegram: фільтрація згадок у групах, команди, реакції, де доступно.
|
||||
- Matrix: зашифровані кімнати, зв'язки потоків або відповідей, відновлення після перезапуску.
|
||||
|
||||
Кожен транспорт має мати один дешевий smoke-сценарій і один або більше сценаріїв класів помилок. Дорогі візуальні сценарії мають залишатися opt-in.
|
||||
Кожен транспорт повинен мати один дешевий smoke-сценарій і один або кілька сценаріїв класу помилок. Дорогі візуальні сценарії мають залишатися opt-in.
|
||||
|
||||
## Відкриті питання
|
||||
|
||||
- Який бот Discord має бути драйвером, а який SUT, коли наявний бот Mantis використовується повторно?
|
||||
- Чи має вхід спостерігача в браузері використовувати людський обліковий запис Discord, тестовий обліковий запис або лише доступні боту докази REST для першої фази?
|
||||
- Чи має вхід у браузері спостерігача використовувати людський обліковий запис Discord, тестовий обліковий запис або лише доступні боту REST-докази для першої фази?
|
||||
- Як довго GitHub має зберігати артефакти Mantis для PR?
|
||||
- Коли ClawSweeper має автоматично рекомендувати Mantis замість очікування команди супровідника?
|
||||
- Чи потрібно редагувати або обрізати знімки екрана перед завантаженням для публічних PR?
|
||||
- Чи слід редагувати або обрізати знімки екрана перед завантаженням у публічні PR?
|
||||
|
||||
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- Перше налаштування OpenClaw
|
||||
- Налаштування OpenClaw уперше
|
||||
- Пошук поширених шаблонів конфігурації
|
||||
- Перехід до певних розділів конфігурації
|
||||
summary: 'Огляд конфігурації: типові завдання, швидке налаштування та посилання на повний довідник'
|
||||
- Перехід до конкретних розділів конфігурації
|
||||
summary: 'Огляд конфігурації: поширені завдання, швидке налаштування та посилання на повний довідник'
|
||||
title: Конфігурація
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T12:47:57Z"
|
||||
generated_at: "2026-05-03T17:12:12Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: b17a72368bb8d178174ccd3ff401657c67911096efd5960e5a1aa8cf0d303c81
|
||||
source_hash: e27ef442d6375d8c22715f20194fb9ce50130204377c9ba4652c2949de28967c
|
||||
source_path: gateway/configuration.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw читає необов’язкову конфігурацію <Tooltip tip="JSON5 supports comments and trailing commas">**JSON5**</Tooltip> з `~/.openclaw/openclaw.json`.
|
||||
OpenClaw читає необов’язкову конфігурацію <Tooltip tip="JSON5 підтримує коментарі та кінцеві коми">**JSON5**</Tooltip> з `~/.openclaw/openclaw.json`.
|
||||
Активний шлях конфігурації має бути звичайним файлом. Макети `openclaw.json`
|
||||
із символьними посиланнями не підтримуються для записів, якими володіє OpenClaw; атомарний запис може замінити
|
||||
шлях замість збереження символьного посилання. Якщо ви зберігаєте конфігурацію поза
|
||||
типовим каталогом стану, укажіть `OPENCLAW_CONFIG_PATH` безпосередньо на реальний файл.
|
||||
із симлінками не підтримуються для записів, якими володіє OpenClaw; атомарний запис може замінити
|
||||
шлях замість збереження симлінка. Якщо ви зберігаєте конфігурацію поза
|
||||
стандартним каталогом стану, спрямуйте `OPENCLAW_CONFIG_PATH` безпосередньо на справжній файл.
|
||||
|
||||
Якщо файл відсутній, OpenClaw використовує безпечні стандартні значення. Поширені причини додати конфігурацію:
|
||||
Якщо файл відсутній, OpenClaw використовує безпечні значення за замовчуванням. Типові причини додати конфігурацію:
|
||||
|
||||
- Під’єднати канали й контролювати, хто може писати боту
|
||||
- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (cron, хуки)
|
||||
- Під’єднати канали та керувати тим, хто може писати боту
|
||||
- Налаштувати моделі, інструменти, sandboxing або автоматизацію (cron, hooks)
|
||||
- Налаштувати сеанси, медіа, мережу або UI
|
||||
|
||||
Див. [повний довідник](/uk/gateway/configuration-reference) для всіх доступних полів.
|
||||
|
||||
Агенти й автоматизація мають використовувати `config.schema.lookup` для точних
|
||||
документів на рівні полів перед редагуванням конфігурації. Використовуйте цю сторінку для практичних настанов і
|
||||
документів рівня окремих полів перед редагуванням конфігурації. Використовуйте цю сторінку для орієнтованих на завдання вказівок і
|
||||
[довідник конфігурації](/uk/gateway/configuration-reference) для ширшої
|
||||
карти полів і стандартних значень.
|
||||
карти полів і значень за замовчуванням.
|
||||
|
||||
<Tip>
|
||||
**Вперше налаштовуєте конфігурацію?** Почніть з `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [приклади конфігурації](/uk/gateway/configuration-examples) із повними конфігураціями для копіювання.
|
||||
**Новачок у конфігурації?** Почніть з `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) із повними конфігураціями для копіювання.
|
||||
</Tip>
|
||||
|
||||
## Мінімальна конфігурація
|
||||
@ -50,69 +50,65 @@ OpenClaw читає необов’язкову конфігурацію <Toolti
|
||||
## Редагування конфігурації
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Interactive wizard">
|
||||
<Tab title="Інтерактивний майстер">
|
||||
```bash
|
||||
openclaw onboard # full onboarding flow
|
||||
openclaw configure # config wizard
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="CLI (one-liners)">
|
||||
<Tab title="CLI (однорядкові команди)">
|
||||
```bash
|
||||
openclaw config get agents.defaults.workspace
|
||||
openclaw config set agents.defaults.heartbeat.every "2h"
|
||||
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Control UI">
|
||||
Відкрийте [http://127.0.0.1:18789](http://127.0.0.1:18789) і скористайтеся вкладкою **Config**.
|
||||
Control UI відтворює форму з живої схеми конфігурації, включно з метаданими документації
|
||||
`title` / `description` для полів, а також схемами Plugin і каналів, коли вони
|
||||
доступні, з редактором **Raw JSON** як запасним варіантом. Для деталізованих
|
||||
UI та інших інструментів gateway також надає `config.schema.lookup`, щоб
|
||||
отримати один вузол схеми, обмежений шляхом, разом зі зведеннями безпосередніх дочірніх елементів.
|
||||
<Tab title="Інтерфейс керування">
|
||||
Відкрийте [http://127.0.0.1:18789](http://127.0.0.1:18789) і скористайтеся вкладкою **Конфігурація**.
|
||||
Інтерфейс керування відображає форму з актуальної схеми конфігурації, включно з
|
||||
метаданими документації полів `title` / `description`, а також схемами plugin і каналів, коли
|
||||
вони доступні, з редактором **Raw JSON** як запасним варіантом. Для деталізованих
|
||||
UI та інших інструментів Gateway також надає `config.schema.lookup`, щоб
|
||||
отримати один вузол схеми з обмеженням за шляхом і зведення найближчих дочірніх елементів.
|
||||
</Tab>
|
||||
<Tab title="Direct edit">
|
||||
Редагуйте `~/.openclaw/openclaw.json` безпосередньо. Gateway відстежує файл і застосовує зміни автоматично (див. [гаряче перезавантаження](#config-hot-reload)).
|
||||
<Tab title="Пряме редагування">
|
||||
Редагуйте `~/.openclaw/openclaw.json` напряму. Gateway відстежує файл і застосовує зміни автоматично (див. [гаряче перезавантаження](#config-hot-reload)).
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Сувора валідація
|
||||
|
||||
<Warning>
|
||||
OpenClaw приймає лише конфігурації, які повністю відповідають схемі. Невідомі ключі, неправильно сформовані типи або недійсні значення змушують Gateway **відмовитися запускатися**. Єдиний виняток на кореневому рівні — `$schema` (рядок), щоб редактори могли додавати метадані JSON Schema.
|
||||
OpenClaw приймає лише конфігурації, що повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення змушують Gateway **відмовитися запускатися**. Єдиний виняток на кореневому рівні — `$schema` (рядок), щоб редактори могли додавати метадані JSON Schema.
|
||||
</Warning>
|
||||
|
||||
`openclaw config schema` виводить канонічну JSON Schema, яку використовують Control UI
|
||||
і валідація. `config.schema.lookup` отримує один вузол, обмежений шляхом, разом зі
|
||||
зведеннями дочірніх елементів для інструментів деталізації. Метадані документації полів `title`/`description`
|
||||
передаються через вкладені об’єкти, wildcard (`*`), елементи масиву (`[]`) і гілки `anyOf`/
|
||||
`oneOf`/`allOf`. Схеми Plugin і каналів часу виконання об’єднуються, коли
|
||||
`openclaw config schema` друкує канонічну JSON Schema, яку використовують інтерфейс керування
|
||||
і валідація. `config.schema.lookup` отримує один вузол з обмеженням за шляхом і
|
||||
зведення дочірніх елементів для інструментів деталізації. Метадані документації полів `title`/`description`
|
||||
передаються через вкладені об’єкти, wildcard (`*`), елементи масиву (`[]`) та гілки `anyOf`/
|
||||
`oneOf`/`allOf`. Схеми runtime plugin і каналів об’єднуються, коли
|
||||
завантажено реєстр маніфестів.
|
||||
|
||||
Коли валідація не проходить:
|
||||
|
||||
- Gateway не запускається
|
||||
- Gateway не завантажується
|
||||
- Працюють лише діагностичні команди (`openclaw doctor`, `openclaw logs`, `openclaw health`, `openclaw status`)
|
||||
- Запустіть `openclaw doctor`, щоб побачити точні проблеми
|
||||
- Запустіть `openclaw doctor --fix` (або `--yes`), щоб застосувати виправлення
|
||||
|
||||
Gateway зберігає довірену останню справну копію після кожного успішного запуску.
|
||||
Якщо `openclaw.json` пізніше не проходить валідацію (або втрачає `gateway.mode`, різко
|
||||
зменшується чи має випадково доданий на початку рядок журналу), OpenClaw зберігає пошкоджений файл
|
||||
як `.clobbered.*`, відновлює останню справну копію й записує причину відновлення
|
||||
до журналу. Наступний хід агента також отримує попередження системної події, щоб основний
|
||||
агент не переписав відновлену конфігурацію наосліп. Підвищення до останньої справної
|
||||
копії пропускається, коли кандидат містить відредаговані заповнювачі секретів, як-от `***`.
|
||||
Коли кожна проблема валідації обмежена `plugins.entries.<id>...`, OpenClaw
|
||||
не виконує відновлення всього файлу. Він залишає поточну конфігурацію активною й
|
||||
показує локальний збій Plugin, щоб невідповідність схеми Plugin або версії хоста
|
||||
не могла відкотити непов’язані налаштування користувача.
|
||||
Gateway зберігає довірену останню відому справну копію після кожного успішного запуску,
|
||||
але запуск і гаряче перезавантаження не відновлюють її автоматично. Якщо `openclaw.json`
|
||||
не проходить валідацію (зокрема локальну валідацію plugin), запуск Gateway завершується помилкою або
|
||||
перезавантаження пропускається, а поточний runtime зберігає останню прийняту конфігурацію.
|
||||
Запустіть `openclaw doctor --fix` (або `--yes`), щоб виправити конфігурацію з префіксами/перезаписами або
|
||||
відновити останню відому справну копію. Просування до останньої відомої справної копії пропускається, коли
|
||||
кандидат містить редаговані заповнювачі секретів, як-от `***`.
|
||||
|
||||
## Поширені завдання
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Set up a channel (WhatsApp, Telegram, Discord, etc.)">
|
||||
Кожен канал має власний розділ конфігурації в `channels.<provider>`. Див. окрему сторінку каналу для кроків налаштування:
|
||||
<Accordion title="Налаштувати канал (WhatsApp, Telegram, Discord тощо)">
|
||||
Кожен канал має власний розділ конфігурації під `channels.<provider>`. Див. спеціальну сторінку каналу для кроків налаштування:
|
||||
|
||||
- [WhatsApp](/uk/channels/whatsapp) — `channels.whatsapp`
|
||||
- [Telegram](/uk/channels/telegram) — `channels.telegram`
|
||||
@ -142,8 +138,8 @@ Gateway зберігає довірену останню справну копі
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Choose and configure models">
|
||||
Установіть основну модель і необов’язкові резервні варіанти:
|
||||
<Accordion title="Вибрати й налаштувати моделі">
|
||||
Задайте основну модель і необов’язкові резервні варіанти:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -162,31 +158,31 @@ Gateway зберігає довірену останню справну копі
|
||||
}
|
||||
```
|
||||
|
||||
- `agents.defaults.models` визначає каталог моделей і діє як allowlist для `/model`.
|
||||
- Використовуйте `openclaw config set agents.defaults.models '<json>' --strict-json --merge`, щоб додати записи allowlist без видалення наявних моделей. Звичайні заміни, які видалили б записи, відхиляються, якщо ви не передасте `--replace`.
|
||||
- `agents.defaults.models` визначає каталог моделей і працює як allowlist для `/model`.
|
||||
- Використовуйте `openclaw config set agents.defaults.models '<json>' --strict-json --merge`, щоб додавати записи allowlist без видалення наявних моделей. Прості заміни, які видалили б записи, відхиляються, якщо ви не передасте `--replace`.
|
||||
- Посилання на моделі використовують формат `provider/model` (наприклад, `anthropic/claude-opus-4-6`).
|
||||
- `agents.defaults.imageMaxDimensionPx` керує зменшенням зображень транскрипту/інструментів (стандартно `1200`); нижчі значення зазвичай зменшують використання vision-токенів у запусках із великою кількістю знімків екрана.
|
||||
- Див. [CLI моделей](/uk/concepts/models) для перемикання моделей у чаті та [резервування моделей](/uk/concepts/model-failover) для ротації автентифікації й поведінки резервних варіантів.
|
||||
- Для власних або self-hosted провайдерів див. [власні провайдери](/uk/gateway/config-tools#custom-providers-and-base-urls) у довіднику.
|
||||
- `agents.defaults.imageMaxDimensionPx` керує зменшенням зображень у стенограмі/інструментах (за замовчуванням `1200`); нижчі значення зазвичай зменшують використання vision-token у запусках із великою кількістю скриншотів.
|
||||
- Див. [CLI моделей](/uk/concepts/models) для перемикання моделей у чаті та [Відмовостійкість моделей](/uk/concepts/model-failover) для ротації автентифікації й поведінки резервних варіантів.
|
||||
- Для власних/самостійно розгорнутих провайдерів див. [Власні провайдери](/uk/gateway/config-tools#custom-providers-and-base-urls) у довіднику.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Control who can message the bot">
|
||||
Доступ до DM керується для кожного каналу через `dmPolicy`:
|
||||
<Accordion title="Керувати тим, хто може писати боту">
|
||||
Доступ DM керується окремо для кожного каналу через `dmPolicy`:
|
||||
|
||||
- `"pairing"` (стандартно): невідомі відправники отримують одноразовий код сполучення для схвалення
|
||||
- `"allowlist"`: лише відправники в `allowFrom` (або у сховищі дозволених після сполучення)
|
||||
- `"open"`: дозволити всі вхідні DM (потребує `allowFrom: ["*"]`)
|
||||
- `"pairing"` (за замовчуванням): невідомі відправники отримують одноразовий код спарювання для схвалення
|
||||
- `"allowlist"`: лише відправники в `allowFrom` (або у сховищі дозволених спарених)
|
||||
- `"open"`: дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`)
|
||||
- `"disabled"`: ігнорувати всі DM
|
||||
|
||||
Для груп використовуйте `groupPolicy` + `groupAllowFrom` або allowlist, специфічні для каналу.
|
||||
|
||||
Див. [повний довідник](/uk/gateway/config-channels#dm-and-group-access) для подробиць за каналами.
|
||||
Див. [повний довідник](/uk/gateway/config-channels#dm-and-group-access) для деталей за каналами.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Set up group chat mention gating">
|
||||
Групові повідомлення стандартно **вимагають згадки**. Налаштуйте шаблони тригерів для кожного агента й залишайте видимі відповіді в кімнаті на стандартному шляху інструмента повідомлень, якщо ви навмисно не хочете застарілих автоматичних фінальних відповідей:
|
||||
<Accordion title="Налаштувати обмеження згадок у груповому чаті">
|
||||
Групові повідомлення за замовчуванням **вимагають згадки**. Налаштуйте шаблони тригерів для кожного агента й залишайте видимі відповіді в кімнаті на стандартному шляху message-tool, якщо ви навмисно не хочете застарілі автоматичні фінальні відповіді:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -216,14 +212,14 @@ Gateway зберігає довірену останню справну копі
|
||||
|
||||
- **Згадки в метаданих**: нативні @-згадки (WhatsApp tap-to-mention, Telegram @bot тощо)
|
||||
- **Текстові шаблони**: безпечні regex-шаблони в `mentionPatterns`
|
||||
- **Видимі відповіді**: `messages.visibleReplies` може вимагати надсилання через інструмент повідомлень глобально; `messages.groupChat.visibleReplies` перевизначає це для груп/каналів.
|
||||
- Див. [повний довідник](/uk/gateway/config-channels#group-chat-mention-gating) для режимів видимих відповідей, перевизначень за каналами та режиму self-chat.
|
||||
- **Видимі відповіді**: `messages.visibleReplies` може вимагати надсилання через message-tool глобально; `messages.groupChat.visibleReplies` перевизначає це для груп/каналів.
|
||||
- Див. [повний довідник](/uk/gateway/config-channels#group-chat-mention-gating) для режимів видимих відповідей, перевизначень за каналами та режиму чату із самим собою.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Restrict skills per agent">
|
||||
Використовуйте `agents.defaults.skills` для спільної бази, а потім перевизначайте конкретних
|
||||
агентів через `agents.list[].skills`:
|
||||
<Accordion title="Обмежити Skills для кожного агента">
|
||||
Використовуйте `agents.defaults.skills` для спільної базової конфігурації, а потім перевизначайте окремих
|
||||
агентів за допомогою `agents.list[].skills`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -240,16 +236,16 @@ Gateway зберігає довірену останню справну копі
|
||||
}
|
||||
```
|
||||
|
||||
- Не вказуйте `agents.defaults.skills`, щоб Skills були необмеженими за замовчуванням.
|
||||
- Не вказуйте `agents.list[].skills`, щоб успадкувати стандартні значення.
|
||||
- Установіть `agents.list[].skills: []`, щоб вимкнути Skills.
|
||||
- Див. [Skills](/uk/tools/skills), [конфігурація Skills](/uk/tools/skills-config) і
|
||||
- Опустіть `agents.defaults.skills`, щоб Skills за замовчуванням були необмежені.
|
||||
- Опустіть `agents.list[].skills`, щоб успадкувати значення за замовчуванням.
|
||||
- Встановіть `agents.list[].skills: []`, щоб Skills не було.
|
||||
- Див. [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config) і
|
||||
[довідник конфігурації](/uk/gateway/config-agents#agents-defaults-skills).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Tune gateway channel health monitoring">
|
||||
Керуйте тим, наскільки агресивно gateway перезапускає канали, що здаються неактивними:
|
||||
<Accordion title="Налаштувати моніторинг стану каналів Gateway">
|
||||
Керуйте тим, наскільки агресивно Gateway перезапускає канали, що виглядають застарілими:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -271,16 +267,16 @@ Gateway зберігає довірену останню справну копі
|
||||
}
|
||||
```
|
||||
|
||||
- Установіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски монітора стану.
|
||||
- Встановіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски health-monitor.
|
||||
- `channelStaleEventThresholdMinutes` має бути більшим або дорівнювати інтервалу перевірки.
|
||||
- Використовуйте `channels.<provider>.healthMonitor.enabled` або `channels.<provider>.accounts.<id>.healthMonitor.enabled`, щоб вимкнути автоматичні перезапуски для одного каналу чи облікового запису без вимкнення глобального монітора.
|
||||
- Див. [перевірки стану](/uk/gateway/health) для операційного налагодження та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів.
|
||||
- Див. [Перевірки стану](/uk/gateway/health) для операційного налагодження та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Tune gateway WebSocket handshake timeout">
|
||||
Дайте локальним клієнтам більше часу завершити pre-auth WebSocket handshake на
|
||||
завантажених або малопотужних хостах:
|
||||
<Accordion title="Налаштувати тайм-аут WebSocket-рукостискання Gateway">
|
||||
Дайте локальним клієнтам більше часу на завершення pre-auth WebSocket-рукостискання на
|
||||
навантажених або малопотужних хостах:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -290,14 +286,14 @@ Gateway зберігає довірену останню справну копі
|
||||
}
|
||||
```
|
||||
|
||||
- Стандартне значення — `15000` мілісекунд.
|
||||
- За замовчуванням `15000` мілісекунд.
|
||||
- `OPENCLAW_HANDSHAKE_TIMEOUT_MS` усе ще має пріоритет для одноразових перевизначень сервісу або shell.
|
||||
- Спочатку бажано виправити зависання запуску/циклу подій; цей параметр призначений для хостів, які справні, але повільні під час прогрівання.
|
||||
- Спершу краще виправити зависання запуску/event-loop; цей регулятор призначений для хостів, які справні, але повільні під час прогрівання.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Configure sessions and resets">
|
||||
Сеанси керують безперервністю та ізоляцією розмови:
|
||||
<Accordion title="Налаштувати сеанси та скидання">
|
||||
Сеанси керують безперервністю та ізоляцією розмов:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -318,14 +314,14 @@ Gateway зберігає довірену останню справну копі
|
||||
```
|
||||
|
||||
- `dmScope`: `main` (спільний) | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
|
||||
- `threadBindings`: глобальні типові значення для маршрутизації сеансів, прив’язаних до потоків (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`).
|
||||
- Див. [Керування сеансами](/uk/concepts/session) щодо областей дії, зв’язків ідентичностей і політики надсилання.
|
||||
- `threadBindings`: глобальні значення за замовчуванням для маршрутизації сеансів, прив’язаних до гілок (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`).
|
||||
- Див. [Керування сеансами](/uk/concepts/session) для областей дії, зв’язків ідентичностей і політики надсилання.
|
||||
- Див. [повний довідник](/uk/gateway/config-agents#session) для всіх полів.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Увімкнути ізоляцію">
|
||||
Запускайте сеанси агентів в ізольованих середовищах sandbox:
|
||||
<Accordion title="Увімкнення ізоляції">
|
||||
Запускайте сеанси агентів в ізольованих середовищах виконання:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -340,14 +336,14 @@ Gateway зберігає довірену останню справну копі
|
||||
}
|
||||
```
|
||||
|
||||
Спочатку зберіть образ — з вихідного checkout виконайте `scripts/sandbox-setup.sh`, або для встановлення з npm див. вбудовану команду `docker build` у [Sandboxing § Images and setup](/uk/gateway/sandboxing#images-and-setup).
|
||||
Спочатку зберіть образ — із робочої копії джерельного коду запустіть `scripts/sandbox-setup.sh`, або для встановлення з npm дивіться вбудовану команду `docker build` у розділі [Ізоляція § Образи та налаштування](/uk/gateway/sandboxing#images-and-setup).
|
||||
|
||||
Див. [Sandboxing](/uk/gateway/sandboxing) для повного посібника та [повний довідник](/uk/gateway/config-agents#agentsdefaultssandbox) для всіх параметрів.
|
||||
Дивіться [Ізоляція](/uk/gateway/sandboxing) для повного посібника та [повний довідник](/uk/gateway/config-agents#agentsdefaultssandbox) для всіх параметрів.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Увімкнути push через ретранслятор для офіційних збірок iOS">
|
||||
Push через ретранслятор налаштовується в `openclaw.json`.
|
||||
<Accordion title="Увімкнення relay-backed push для офіційних збірок iOS">
|
||||
Relay-backed push налаштовується в `openclaw.json`.
|
||||
|
||||
Задайте це в конфігурації Gateway:
|
||||
|
||||
@ -375,35 +371,35 @@ Gateway зберігає довірену останню справну копі
|
||||
|
||||
Що це робить:
|
||||
|
||||
- Дає Gateway змогу надсилати `push.test`, сигнали пробудження та пробудження для повторного підключення через зовнішній ретранслятор.
|
||||
- Використовує дозвіл на надсилання, прив’язаний до реєстрації, який пересилає спарений застосунок iOS. Gateway не потребує токена ретранслятора для всього розгортання.
|
||||
- Прив’язує кожну реєстрацію через ретранслятор до ідентичності Gateway, з якою спарено застосунок iOS, тому інший Gateway не може повторно використати збережену реєстрацію.
|
||||
- Залишає локальні/ручні збірки iOS на прямих APNs. Надсилання через ретранслятор застосовується лише до офіційних розповсюджених збірок, які зареєструвалися через ретранслятор.
|
||||
- Має збігатися з базовим URL ретранслятора, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації й надсилання потрапляв до того самого розгортання ретранслятора.
|
||||
- Дає змогу gateway надсилати `push.test`, wake nudges і reconnect wakes через зовнішній relay.
|
||||
- Використовує scoped-to-registration дозвіл на надсилання, переданий спареним застосунком iOS. Gateway не потребує relay-токена для всього розгортання.
|
||||
- Прив’язує кожну relay-backed реєстрацію до ідентичності gateway, з яким було спарено застосунок iOS, тож інший gateway не зможе повторно використати збережену реєстрацію.
|
||||
- Залишає локальні/ручні збірки iOS на прямих APNs. Relay-backed надсилання застосовуються лише до офіційних розповсюджуваних збірок, зареєстрованих через relay.
|
||||
- Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації та надсилання потрапляв до того самого розгортання relay.
|
||||
|
||||
Наскрізний потік:
|
||||
Наскрізний процес:
|
||||
|
||||
1. Установіть офіційну/TestFlight збірку iOS, скомпільовану з тим самим базовим URL ретранслятора.
|
||||
2. Налаштуйте `gateway.push.apns.relay.baseUrl` на Gateway.
|
||||
3. Спарте застосунок iOS із Gateway і дайте підключитися сеансам вузла та оператора.
|
||||
4. Застосунок iOS отримує ідентичність Gateway, реєструється в ретрансляторі за допомогою App Attest і квитанції застосунку, а потім публікує payload `push.apns.register` через ретранслятор у спарений Gateway.
|
||||
5. Gateway зберігає handle ретранслятора й дозвіл на надсилання, а потім використовує їх для `push.test`, сигналів пробудження та пробуджень для повторного підключення.
|
||||
1. Установіть офіційну/TestFlight збірку iOS, скомпільовану з тим самим базовим URL relay.
|
||||
2. Налаштуйте `gateway.push.apns.relay.baseUrl` на gateway.
|
||||
3. Спарте застосунок iOS із gateway і дайте змогу сеансам node та оператора підключитися.
|
||||
4. Застосунок iOS отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції застосунку, а потім публікує relay-backed payload `push.apns.register` у спарений gateway.
|
||||
5. Gateway зберігає relay handle і дозвіл на надсилання, а потім використовує їх для `push.test`, wake nudges і reconnect wakes.
|
||||
|
||||
Операційні примітки:
|
||||
|
||||
- Якщо перемкнути застосунок iOS на інший Gateway, повторно підключіть застосунок, щоб він міг опублікувати нову реєстрацію ретранслятора, прив’язану до цього Gateway.
|
||||
- Якщо випустити нову збірку iOS, яка вказує на інше розгортання ретранслятора, застосунок оновлює кешовану реєстрацію ретранслятора замість повторного використання старого походження ретранслятора.
|
||||
- Якщо ви перемикаєте застосунок iOS на інший gateway, перепідключіть застосунок, щоб він міг опублікувати нову relay-реєстрацію, прив’язану до цього gateway.
|
||||
- Якщо ви постачаєте нову збірку iOS, що вказує на інше розгортання relay, застосунок оновлює свою кешовану relay-реєстрацію замість повторного використання старого relay origin.
|
||||
|
||||
Примітка щодо сумісності:
|
||||
|
||||
- `OPENCLAW_APNS_RELAY_BASE_URL` і `OPENCLAW_APNS_RELAY_TIMEOUT_MS` усе ще працюють як тимчасові перевизначення env.
|
||||
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` залишається обхідним механізмом розробки лише для local loopback; не зберігайте HTTP URL ретранслятора в конфігурації.
|
||||
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` залишається лише для розробки через loopback; не зберігайте HTTP URL relay у конфігурації.
|
||||
|
||||
Див. [Застосунок iOS](/uk/platforms/ios#relay-backed-push-for-official-builds) щодо наскрізного потоку та [Автентифікація й потік довіри](/uk/platforms/ios#authentication-and-trust-flow) щодо моделі безпеки ретранслятора.
|
||||
Дивіться [Застосунок iOS](/uk/platforms/ios#relay-backed-push-for-official-builds) для наскрізного процесу та [Потік автентифікації та довіри](/uk/platforms/ios#authentication-and-trust-flow) для моделі безпеки relay.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Налаштувати Heartbeat (періодичні перевірки)">
|
||||
<Accordion title="Налаштування heartbeat (періодичних check-ins)">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
@ -419,12 +415,12 @@ Gateway зберігає довірену останню справну копі
|
||||
|
||||
- `every`: рядок тривалості (`30m`, `2h`). Задайте `0m`, щоб вимкнути.
|
||||
- `target`: `last` | `none` | `<channel-id>` (наприклад `discord`, `matrix`, `telegram` або `whatsapp`)
|
||||
- `directPolicy`: `allow` (типово) або `block` для цілей Heartbeat у стилі DM
|
||||
- Див. [Heartbeat](/uk/gateway/heartbeat) для повного посібника.
|
||||
- `directPolicy`: `allow` (за замовчуванням) або `block` для DM-style цілей heartbeat
|
||||
- Дивіться [Heartbeat](/uk/gateway/heartbeat) для повного посібника.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Налаштувати завдання Cron">
|
||||
<Accordion title="Налаштування завдань cron">
|
||||
```json5
|
||||
{
|
||||
cron: {
|
||||
@ -439,14 +435,14 @@ Gateway зберігає довірену останню справну копі
|
||||
}
|
||||
```
|
||||
|
||||
- `sessionRetention`: очищати завершені ізольовані сеанси запусків із `sessions.json` (типово `24h`; задайте `false`, щоб вимкнути).
|
||||
- `runLog`: очищати `cron/runs/<jobId>.jsonl` за розміром і кількістю збережених рядків.
|
||||
- Див. [Завдання Cron](/uk/automation/cron-jobs) для огляду можливості та прикладів CLI.
|
||||
- `sessionRetention`: очищає завершені ізольовані сеанси запусків із `sessions.json` (за замовчуванням `24h`; задайте `false`, щоб вимкнути).
|
||||
- `runLog`: очищає `cron/runs/<jobId>.jsonl` за розміром і кількістю збережених рядків.
|
||||
- Дивіться [Завдання Cron](/uk/automation/cron-jobs) для огляду функції та прикладів CLI.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Налаштувати Webhook-и (hooks)">
|
||||
Увімкніть HTTP Webhook endpoints на Gateway:
|
||||
<Accordion title="Налаштування webhooks (hooks)">
|
||||
Увімкніть HTTP webhook endpoint-и на Gateway:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -470,20 +466,20 @@ Gateway зберігає довірену останню справну копі
|
||||
```
|
||||
|
||||
Примітка щодо безпеки:
|
||||
- Вважайте весь вміст payload hook/webhook ненадійними вхідними даними.
|
||||
- Сприймайте весь вміст payload hook/webhook як недовірені вхідні дані.
|
||||
- Використовуйте окремий `hooks.token`; не використовуйте повторно спільний токен Gateway.
|
||||
- Автентифікація hook працює лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в query string відхиляються.
|
||||
- `hooks.path` не може бути `/`; тримайте вхідний Webhook на окремому підшляху, наприклад `/hooks`.
|
||||
- Тримайте прапорці обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо не виконуєте вузько обмежене налагодження.
|
||||
- Якщо ввімкнути `hooks.allowRequestSessionKey`, також задайте `hooks.allowedSessionKeyPrefixes`, щоб обмежити ключі сеансів, вибрані викликачем.
|
||||
- Для агентів, керованих hook, віддавайте перевагу сильним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс sandboxing, де можливо).
|
||||
- `hooks.path` не може бути `/`; тримайте webhook ingress на окремому підшляху, наприклад `/hooks`.
|
||||
- Тримайте прапорці обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо не виконуєте чітко обмежене налагодження.
|
||||
- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також задайте `hooks.allowedSessionKeyPrefixes`, щоб обмежити session keys, вибрані викликачем.
|
||||
- Для агентів, керованих hooks, надавайте перевагу сильним сучасним рівням моделей і строгій політиці інструментів (наприклад, лише messaging плюс ізоляція, де це можливо).
|
||||
|
||||
Див. [повний довідник](/uk/gateway/configuration-reference#hooks) для всіх параметрів зіставлення та інтеграції Gmail.
|
||||
Дивіться [повний довідник](/uk/gateway/configuration-reference#hooks) для всіх параметрів mapping і інтеграції Gmail.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Налаштувати маршрутизацію кількох агентів">
|
||||
Запускайте кілька ізольованих агентів з окремими робочими просторами та сеансами:
|
||||
<Accordion title="Налаштування маршрутизації multi-agent">
|
||||
Запускайте кількох ізольованих агентів з окремими робочими просторами та сеансами:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -500,11 +496,11 @@ Gateway зберігає довірену останню справну копі
|
||||
}
|
||||
```
|
||||
|
||||
Див. [Multi-Agent](/uk/concepts/multi-agent) і [повний довідник](/uk/gateway/config-agents#multi-agent-routing) щодо правил прив’язки та профілів доступу для кожного агента.
|
||||
Дивіться [Multi-Agent](/uk/concepts/multi-agent) і [повний довідник](/uk/gateway/config-agents#multi-agent-routing) для правил binding і профілів доступу для окремих агентів.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Розділити конфігурацію на кілька файлів ($include)">
|
||||
<Accordion title="Поділ конфігурації на кілька файлів ($include)">
|
||||
Використовуйте `$include`, щоб упорядкувати великі конфігурації:
|
||||
|
||||
```json5
|
||||
@ -519,56 +515,51 @@ Gateway зберігає довірену останню справну копі
|
||||
```
|
||||
|
||||
- **Один файл**: замінює об’єкт, що його містить
|
||||
- **Масив файлів**: глибоко об’єднується за порядком (пізніший перемагає)
|
||||
- **Сусідні ключі**: об’єднуються після include (перевизначають включені значення)
|
||||
- **Вкладені include**: підтримуються до 10 рівнів углиб
|
||||
- **Відносні шляхи**: розв’язуються відносно файлу, що виконує include
|
||||
- **Записи, якими володіє OpenClaw**: коли запис змінює лише один розділ верхнього рівня,
|
||||
підкріплений include одного файлу, наприклад `plugins: { $include: "./plugins.json5" }`,
|
||||
- **Масив файлів**: глибоко об’єднується за порядком (пізніший має пріоритет)
|
||||
- **Сусідні ключі**: об’єднуються після includes (перевизначають включені значення)
|
||||
- **Вкладені includes**: підтримуються до 10 рівнів углиб
|
||||
- **Відносні шляхи**: розв’язуються відносно файлу, який виконує include
|
||||
- **Записи, що належать OpenClaw**: коли запис змінює лише один розділ верхнього рівня,
|
||||
підкріплений однофайловим include, наприклад `plugins: { $include: "./plugins.json5" }`,
|
||||
OpenClaw оновлює цей включений файл і залишає `openclaw.json` без змін
|
||||
- **Непідтримуваний write-through**: кореневі include, масиви include та include
|
||||
із сусідніми перевизначеннями відмовляють закрито для записів, якими володіє OpenClaw, замість
|
||||
згладжування конфігурації
|
||||
- **Непідтримуваний write-through**: кореневі includes, масиви includes і includes
|
||||
із сусідніми перевизначеннями завершуються закрито для записів, що належать OpenClaw, замість
|
||||
flattening конфігурації
|
||||
- **Обмеження**: шляхи `$include` мають розв’язуватися в межах каталогу, що містить
|
||||
`openclaw.json`. Щоб спільно використовувати дерево між машинами або користувачами, задайте
|
||||
`OPENCLAW_INCLUDE_ROOTS` як список шляхів (`:` у POSIX, `;` у Windows) до
|
||||
додаткових каталогів, на які можуть посилатися include. Симлінки розв’язуються
|
||||
і перевіряються повторно, тому шлях, який лексично перебуває в каталозі конфігурації, але реальна
|
||||
ціль якого виходить за межі кожного дозволеного кореня, усе одно відхиляється.
|
||||
- **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок розбору та циклічних include
|
||||
`OPENCLAW_INCLUDE_ROOTS` як список шляхів (`:` на POSIX, `;` на Windows) до
|
||||
додаткових каталогів, на які можуть посилатися includes. Символічні посилання розв’язуються
|
||||
й перевіряються повторно, тому шлях, який лексично розташований у каталозі конфігурації, але чия
|
||||
реальна ціль виходить за межі кожного дозволеного кореня, усе одно відхиляється.
|
||||
- **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок парсингу та циклічних includes
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Гаряче перезавантаження конфігурації
|
||||
|
||||
Gateway відстежує `~/.openclaw/openclaw.json` і застосовує зміни автоматично — для більшості налаштувань ручний перезапуск не потрібен.
|
||||
Gateway відстежує `~/.openclaw/openclaw.json` і застосовує зміни автоматично — ручний перезапуск не потрібен для більшості налаштувань.
|
||||
|
||||
Прямі редагування файлу вважаються ненадійними, доки не пройдуть перевірку. Watcher чекає,
|
||||
доки завершаться тимчасові записи/перейменування редактора, читає остаточний файл і відхиляє
|
||||
недійсні зовнішні редагування, відновлюючи останню справну конфігурацію. Записи конфігурації,
|
||||
якими володіє OpenClaw, використовують той самий schema gate перед записом; руйнівні перезаписи,
|
||||
як-от видалення `gateway.mode` або зменшення файлу більш ніж удвічі, відхиляються
|
||||
і зберігаються як `.rejected.*` для перевірки.
|
||||
Прямі редагування файлу вважаються недовіреними, доки не пройдуть валідацію. Watcher чекає,
|
||||
поки вщухне churn тимчасового запису/перейменування редактора, читає фінальний файл і відхиляє
|
||||
некоректні зовнішні редагування без переписування `openclaw.json`. Записи конфігурації, що належать OpenClaw,
|
||||
використовують той самий schema gate перед записом; руйнівні clobbers, як-от
|
||||
видалення `gateway.mode` або зменшення файлу більш ніж удвічі, відхиляються та
|
||||
зберігаються як `.rejected.*` для перевірки.
|
||||
|
||||
Помилки локальної перевірки Plugin є винятком: якщо всі проблеми перебувають під
|
||||
`plugins.entries.<id>...`, перезавантаження зберігає поточну конфігурацію й повідомляє про проблему
|
||||
Plugin замість відновлення `.last-good`.
|
||||
|
||||
Якщо в журналах ви бачите `Config auto-restored from last-known-good` або
|
||||
`config reload restored last-known-good config`, перегляньте відповідний файл
|
||||
`.clobbered.*` поруч із `openclaw.json`, виправте відхилений payload, а потім виконайте
|
||||
`openclaw config validate`. Див. [Усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config)
|
||||
для контрольного списку відновлення.
|
||||
Якщо ви бачите `config reload skipped (invalid config)` або під час запуску повідомляється `Invalid
|
||||
config`, перевірте конфігурацію, запустіть `openclaw config validate`, а потім запустіть `openclaw
|
||||
doctor --fix` для ремонту. Дивіться [Усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-rejected-invalid-config)
|
||||
для контрольного списку.
|
||||
|
||||
### Режими перезавантаження
|
||||
|
||||
| Режим | Поведінка |
|
||||
| ---------------------- | --------------------------------------------------------------------------------------- |
|
||||
| **`hybrid`** (типово) | Миттєво гаряче застосовує безпечні зміни. Автоматично перезапускається для критичних. |
|
||||
| **`hot`** | Гаряче застосовує лише безпечні зміни. Записує попередження, коли потрібен перезапуск — ви виконуєте його. |
|
||||
| **`hybrid`** (default) | Миттєво гаряче застосовує безпечні зміни. Автоматично перезапускає для критичних. |
|
||||
| **`hot`** | Гаряче застосовує лише безпечні зміни. Логує попередження, коли потрібен перезапуск — ви обробляєте це. |
|
||||
| **`restart`** | Перезапускає Gateway за будь-якої зміни конфігурації, безпечної чи ні. |
|
||||
| **`off`** | Вимикає відстеження файлів. Зміни набувають чинності під час наступного ручного перезапуску. |
|
||||
| **`off`** | Вимикає відстеження файлів. Зміни набирають чинності під час наступного ручного перезапуску. |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -580,55 +571,56 @@ Plugin замість відновлення `.last-good`.
|
||||
|
||||
### Що застосовується гаряче, а що потребує перезапуску
|
||||
|
||||
Більшість полів застосовуються гаряче без простою. У режимі `hybrid` зміни, що потребують перезапуску, обробляються автоматично.
|
||||
Більшість полів гаряче застосовуються без простою. У режимі `hybrid` зміни, що потребують перезапуску, обробляються автоматично.
|
||||
|
||||
| Категорія | Поля | Потрібен перезапуск? |
|
||||
| ------------------- | ----------------------------------------------------------------- | --------------- |
|
||||
| Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані канали та Plugin-канали | Ні |
|
||||
| Агент і моделі | `agent`, `agents`, `models`, `routing` | Ні |
|
||||
| Автоматизація | `hooks`, `cron`, `agent.heartbeat` | Ні |
|
||||
| Сеанси й повідомлення | `session`, `messages` | Ні |
|
||||
| Інструменти й медіа | `tools`, `browser`, `skills`, `mcp`, `audio`, `talk` | Ні |
|
||||
| UI та інше | `ui`, `logging`, `identity`, `bindings` | Ні |
|
||||
| Сервер Gateway | `gateway.*` (порт, прив’язка, автентифікація, tailscale, TLS, HTTP) | **Так** |
|
||||
| Інфраструктура | `discovery`, `canvasHost`, `plugins` | **Так** |
|
||||
| Категорія | Поля | Потрібен перезапуск? |
|
||||
| ------------------ | ----------------------------------------------------------------- | -------------------- |
|
||||
| Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані та plugin канали | Ні |
|
||||
| Агент і моделі | `agent`, `agents`, `models`, `routing` | Ні |
|
||||
| Автоматизація | `hooks`, `cron`, `agent.heartbeat` | Ні |
|
||||
| Сеанси й повідомлення | `session`, `messages` | Ні |
|
||||
| Інструменти й медіа | `tools`, `browser`, `skills`, `mcp`, `audio`, `talk` | Ні |
|
||||
| UI та інше | `ui`, `logging`, `identity`, `bindings` | Ні |
|
||||
| Сервер Gateway | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Так** |
|
||||
| Інфраструктура | `discovery`, `canvasHost`, `plugins` | **Так** |
|
||||
|
||||
<Note>
|
||||
`gateway.reload` і `gateway.remote` є винятками — їх зміна **не** запускає перезапуск.
|
||||
`gateway.reload` і `gateway.remote` є винятками — їхня зміна **не** запускає перезапуск.
|
||||
</Note>
|
||||
|
||||
### Планування перезавантаження
|
||||
|
||||
Коли ви редагуєте вихідний файл, на який є посилання через `$include`, OpenClaw планує
|
||||
перезавантаження з авторського макета джерела, а не зі сплощеного подання в пам’яті.
|
||||
Це зберігає передбачуваність рішень щодо гарячого перезавантаження (гаряче застосування чи перезапуск), навіть коли
|
||||
один розділ верхнього рівня міститься у власному включеному файлі, наприклад
|
||||
`plugins: { $include: "./plugins.json5" }`. Планування перезавантаження завершується закрито, якщо
|
||||
перезавантаження на основі авторського макета джерела, а не вирівняного подання в пам’яті.
|
||||
Це робить рішення щодо гарячого перезавантаження (гаряче застосування чи перезапуск)
|
||||
передбачуваними, навіть коли один верхньорівневий розділ міститься у власному включеному файлі, наприклад
|
||||
`plugins: { $include: "./plugins.json5" }`. Планування перезавантаження завершується без змін, якщо
|
||||
макет джерела неоднозначний.
|
||||
|
||||
## Config RPC (програмні оновлення)
|
||||
|
||||
Для інструментів, які записують конфігурацію через API Gateway, віддавайте перевагу такому потоку:
|
||||
Для інструментів, які записують конфігурацію через API Gateway, надавайте перевагу такому процесу:
|
||||
|
||||
- `config.schema.lookup`, щоб переглянути одне піддерево (поверхневий вузол схеми + зведення дочірніх елементів)
|
||||
- `config.schema.lookup`, щоб переглянути одне піддерево (неглибокий вузол схеми + зведення
|
||||
дочірніх елементів)
|
||||
- `config.get`, щоб отримати поточний знімок разом із `hash`
|
||||
- `config.patch` для часткових оновлень (JSON merge patch: об’єкти об’єднуються, `null`
|
||||
видаляє, масиви замінюються)
|
||||
- `config.apply` лише тоді, коли ви маєте намір замінити всю конфігурацію
|
||||
- `update.run` для явного самооновлення з перезапуском; додайте `continuationMessage`, коли після перезапуску сеанс має виконати один наступний хід
|
||||
- `update.status`, щоб переглянути останній sentinel перезапуску оновлення та перевірити запущену версію після перезапуску
|
||||
- `update.run` для явного самооновлення разом із перезапуском; додайте `continuationMessage`, коли після перезапуску сесія має виконати один наступний хід
|
||||
- `update.status`, щоб переглянути останній сторожовий маркер перезапуску після оновлення й перевірити запущену версію після перезапуску
|
||||
|
||||
Агенти мають розглядати `config.schema.lookup` як першу точку для точних
|
||||
Агенти мають розглядати `config.schema.lookup` як перше місце для точних
|
||||
документів і обмежень на рівні полів. Використовуйте [Довідник конфігурації](/uk/gateway/configuration-reference),
|
||||
коли їм потрібні ширша карта конфігурації, типові значення або посилання на окремі
|
||||
коли потрібна ширша карта конфігурації, значення за замовчуванням або посилання на окремі
|
||||
довідники підсистем.
|
||||
|
||||
<Note>
|
||||
Записи площини керування (`config.apply`, `config.patch`, `update.run`)
|
||||
обмежені частотою до 3 запитів за 60 секунд на `deviceId+clientIp`. Запити на перезапуск
|
||||
об’єднуються, а потім застосовують 30-секундне охолодження між циклами перезапуску.
|
||||
`update.status` доступний лише для читання, але обмежений адміністративною областю, бо sentinel перезапуску може
|
||||
містити зведення кроків оновлення та хвости виводу команд.
|
||||
обмежені за частотою до 3 запитів за 60 секунд на `deviceId+clientIp`. Запити на перезапуск
|
||||
об’єднуються, а потім застосовується 30-секундний період очікування між циклами перезапуску.
|
||||
`update.status` доступний лише для читання, але обмежений адміністративною областю, оскільки сторожовий маркер перезапуску може
|
||||
містити зведення кроків оновлення та кінцеві фрагменти виводу команд.
|
||||
</Note>
|
||||
|
||||
Приклад часткового патча:
|
||||
@ -642,7 +634,7 @@ openclaw gateway call config.patch --params '{
|
||||
```
|
||||
|
||||
І `config.apply`, і `config.patch` приймають `raw`, `baseHash`, `sessionKey`,
|
||||
`note` і `restartDelayMs`. `baseHash` є обов’язковим для обох методів, коли
|
||||
`note` та `restartDelayMs`. `baseHash` є обов’язковим для обох методів, коли
|
||||
конфігурація вже існує.
|
||||
|
||||
## Змінні середовища
|
||||
@ -652,7 +644,7 @@ OpenClaw читає змінні середовища з батьківсько
|
||||
- `.env` з поточного робочого каталогу (якщо є)
|
||||
- `~/.openclaw/.env` (глобальний резервний варіант)
|
||||
|
||||
Жоден із файлів не перевизначає наявні змінні середовища. Ви також можете задавати вбудовані змінні середовища в конфігурації:
|
||||
Жоден із цих файлів не перевизначає наявні змінні середовища. Ви також можете задавати вбудовані змінні середовища в конфігурації:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -663,8 +655,8 @@ OpenClaw читає змінні середовища з батьківсько
|
||||
}
|
||||
```
|
||||
|
||||
<Accordion title="Імпорт середовища оболонки (необов’язково)">
|
||||
Якщо ввімкнено й очікувані ключі не задані, OpenClaw запускає вашу оболонку входу та імпортує лише відсутні ключі:
|
||||
<Accordion title="Shell env import (optional)">
|
||||
Якщо ввімкнено і очікувані ключі не задані, OpenClaw запускає вашу login shell та імпортує лише відсутні ключі:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -677,7 +669,7 @@ OpenClaw читає змінні середовища з батьківсько
|
||||
Еквівалент змінної середовища: `OPENCLAW_LOAD_SHELL_ENV=1`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підстановка змінних середовища у значеннях конфігурації">
|
||||
<Accordion title="Env var substitution in config values">
|
||||
Посилайтеся на змінні середовища в будь-якому рядковому значенні конфігурації за допомогою `${VAR_NAME}`:
|
||||
|
||||
```json5
|
||||
@ -689,15 +681,15 @@ OpenClaw читає змінні середовища з батьківсько
|
||||
|
||||
Правила:
|
||||
|
||||
- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`
|
||||
- Збігаються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`
|
||||
- Відсутні або порожні змінні спричиняють помилку під час завантаження
|
||||
- Екрануйте через `$${VAR}` для буквального виводу
|
||||
- Екрануйте за допомогою `$${VAR}` для буквального виводу
|
||||
- Працює всередині файлів `$include`
|
||||
- Вбудована підстановка: `"${BASE}/v1"` → `"https://api.example.com/v1"`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Посилання на секрети (env, file, exec)">
|
||||
<Accordion title="Secret refs (env, file, exec)">
|
||||
Для полів, які підтримують об’єкти SecretRef, можна використовувати:
|
||||
|
||||
```json5
|
||||
@ -730,15 +722,15 @@ OpenClaw читає змінні середовища з батьківсько
|
||||
}
|
||||
```
|
||||
|
||||
Відомості про SecretRef (зокрема `secrets.providers` для `env`/`file`/`exec`) наведено в [Керуванні секретами](/uk/gateway/secrets).
|
||||
Підтримувані шляхи облікових даних наведено в [Поверхні облікових даних SecretRef](/uk/reference/secretref-credential-surface).
|
||||
Подробиці SecretRef (зокрема `secrets.providers` для `env`/`file`/`exec`) наведені в [Керуванні секретами](/uk/gateway/secrets).
|
||||
Підтримувані шляхи облікових даних перелічені в [Поверхні облікових даних SecretRef](/uk/reference/secretref-credential-surface).
|
||||
</Accordion>
|
||||
|
||||
Див. [Середовище](/uk/help/environment) для повного пріоритету та джерел.
|
||||
Див. [Середовище](/uk/help/environment), щоб дізнатися повний пріоритет і джерела.
|
||||
|
||||
## Повний довідник
|
||||
|
||||
Повний довідник по кожному полю див. у **[Довіднику конфігурації](/uk/gateway/configuration-reference)**.
|
||||
Повний довідник за всіма полями див. у **[Довіднику конфігурації](/uk/gateway/configuration-reference)**.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -1,24 +1,24 @@
|
||||
---
|
||||
read_when:
|
||||
- Центр усунення несправностей спрямував вас сюди для глибшої діагностики
|
||||
- Центр усунення несправностей скерував вас сюди для глибшої діагностики
|
||||
- Потрібні стабільні розділи операційного посібника на основі симптомів із точними командами
|
||||
sidebarTitle: Troubleshooting
|
||||
summary: Поглиблений операційний посібник з усунення несправностей для Gateway, каналів, автоматизації, вузлів і браузера
|
||||
summary: Поглиблений регламент усунення несправностей для Gateway, каналів, автоматизації, вузлів і браузера
|
||||
title: Усунення несправностей
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T20:37:53Z"
|
||||
generated_at: "2026-05-03T17:12:04Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 815fbbca4d12b4b9c65b1172e07606d0eaf4c64df7fd6ca23a8f8d104b78c2a9
|
||||
source_hash: 19422615706ca09124b19dd3e21b2c13391d6daf2b1807e01b4ce2047d02e522
|
||||
source_path: gateway/troubleshooting.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Ця сторінка є докладним операційним посібником. Почніть із [/help/troubleshooting](/uk/help/troubleshooting), якщо спершу хочете пройти швидкий процес діагностики.
|
||||
Ця сторінка — докладний runbook. Почніть із [/help/troubleshooting](/uk/help/troubleshooting), якщо спершу потрібен швидкий потік тріажу.
|
||||
|
||||
## Послідовність команд
|
||||
## Драбина команд
|
||||
|
||||
Спочатку виконайте ці команди в такому порядку:
|
||||
Спершу виконайте ці команди в такому порядку:
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -32,13 +32,13 @@ openclaw channels status --probe
|
||||
|
||||
- `openclaw gateway status` показує `Runtime: running`, `Connectivity probe: ok` і рядок `Capability: ...`.
|
||||
- `openclaw doctor` не повідомляє про блокувальні проблеми конфігурації чи служби.
|
||||
- `openclaw channels status --probe` показує актуальний статус транспорту для кожного облікового запису та, де підтримується, результати перевірки/аудиту, як-от `works` або `audit ok`.
|
||||
- `openclaw channels status --probe` показує живий стан транспорту для кожного облікового запису і, де підтримується, результати проби/аудиту, як-от `works` або `audit ok`.
|
||||
|
||||
## Розсинхронізовані інсталяції та захист від новішої конфігурації
|
||||
## Split brain-встановлення й захист від новішої конфігурації
|
||||
|
||||
Використовуйте це, коли служба Gateway несподівано зупиняється після оновлення або журнали показують, що один бінарний файл `openclaw` старіший за версію, яка востаннє записувала `openclaw.json`.
|
||||
|
||||
OpenClaw позначає записи конфігурації через `meta.lastTouchedVersion`. Команди лише для читання все ще можуть переглядати конфігурацію, записану новішою версією OpenClaw, але операції, що змінюють процеси й служби, відмовляються продовжувати роботу зі старішого бінарного файлу. Заблоковані дії включають запуск, зупинку, перезапуск і видалення служби Gateway, примусове перевстановлення служби, запуск Gateway у режимі служби та очищення порту через `gateway --force`.
|
||||
OpenClaw позначає записи конфігурації через `meta.lastTouchedVersion`. Команди лише для читання все ще можуть перевіряти конфігурацію, записану новішим OpenClaw, але мутації процесів і служб відмовляються продовжувати роботу зі старішого бінарного файла. Заблоковані дії включають запуск, зупинку, перезапуск, видалення служби Gateway, примусове перевстановлення служби, запуск Gateway у режимі служби та очищення порту через `gateway --force`.
|
||||
|
||||
```bash
|
||||
which openclaw
|
||||
@ -49,10 +49,10 @@ openclaw config get meta.lastTouchedVersion
|
||||
|
||||
<Steps>
|
||||
<Step title="Виправте PATH">
|
||||
Виправте `PATH`, щоб `openclaw` вказував на новішу інсталяцію, а потім повторно виконайте дію.
|
||||
Виправте `PATH`, щоб `openclaw` указував на новіше встановлення, а потім повторно виконайте дію.
|
||||
</Step>
|
||||
<Step title="Перевстановіть службу Gateway">
|
||||
Перевстановіть потрібну службу Gateway із новішої інсталяції:
|
||||
Перевстановіть потрібну службу Gateway із новішого встановлення:
|
||||
|
||||
```bash
|
||||
openclaw gateway install --force
|
||||
@ -61,15 +61,15 @@ openclaw config get meta.lastTouchedVersion
|
||||
|
||||
</Step>
|
||||
<Step title="Видаліть застарілі обгортки">
|
||||
Видаліть застарілий системний пакет або старі записи обгорток, які все ще вказують на старий бінарний файл `openclaw`.
|
||||
Видаліть застарілі записи системного пакета або старої обгортки, які досі вказують на старий бінарний файл `openclaw`.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
Лише для навмисного зниження версії або аварійного відновлення встановіть `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1` для однієї команди. Для нормальної роботи залишайте її невстановленою.
|
||||
Лише для навмисного відкату версії або аварійного відновлення встановіть `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1` для однієї команди. Для звичайної роботи залиште це значення невстановленим.
|
||||
</Warning>
|
||||
|
||||
## Anthropic 429: для довгого контексту потрібне додаткове використання
|
||||
## Для довгого контексту Anthropic 429 потрібне додаткове використання
|
||||
|
||||
Використовуйте це, коли журнали/помилки містять: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
|
||||
|
||||
@ -81,9 +81,9 @@ openclaw config get agents.defaults.models
|
||||
|
||||
Шукайте:
|
||||
|
||||
- Обрана модель Anthropic Opus/Sonnet має `params.context1m: true`.
|
||||
- Поточні облікові дані Anthropic не придатні для використання довгого контексту.
|
||||
- Запити завершуються помилкою лише в довгих сесіях/запусках моделей, яким потрібен beta-шлях 1M.
|
||||
- Вибрана модель Anthropic Opus/Sonnet має `params.context1m: true`.
|
||||
- Поточні облікові дані Anthropic не мають права на використання довгого контексту.
|
||||
- Запити падають лише в довгих сесіях/запусках моделі, яким потрібен beta-шлях 1M.
|
||||
|
||||
Варіанти виправлення:
|
||||
|
||||
@ -99,19 +99,19 @@ openclaw config get agents.defaults.models
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Пов’язано:
|
||||
Пов’язане:
|
||||
|
||||
- [Anthropic](/uk/providers/anthropic)
|
||||
- [Використання токенів і витрати](/uk/reference/token-use)
|
||||
- [Чому я бачу HTTP 429 від Anthropic?](/uk/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)
|
||||
|
||||
## Локальний OpenAI-сумісний бекенд проходить прямі перевірки, але запуски агента завершуються помилкою
|
||||
## Локальний OpenAI-сумісний бекенд проходить прямі проби, але запуски агента падають
|
||||
|
||||
Використовуйте це, коли:
|
||||
|
||||
- `curl ... /v1/models` працює
|
||||
- малі прямі виклики `/v1/chat/completions` працюють
|
||||
- запуски моделей OpenClaw завершуються помилкою лише під час звичайних ходів агента
|
||||
- крихітні прямі виклики `/v1/chat/completions` працюють
|
||||
- Запуски моделей OpenClaw падають лише на звичайних ходах агента
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:1234/v1/models
|
||||
@ -124,39 +124,39 @@ openclaw logs --follow
|
||||
|
||||
Шукайте:
|
||||
|
||||
- малі прямі виклики успішні, але запуски OpenClaw завершуються помилкою лише на більших промптах
|
||||
- прямі крихітні виклики успішні, але запуски OpenClaw падають лише на більших промптах
|
||||
- помилки `model_not_found` або 404, хоча прямий `/v1/chat/completions`
|
||||
працює з тим самим ідентифікатором моделі без префікса
|
||||
працює з тим самим простим ідентифікатором моделі
|
||||
- помилки бекенду про те, що `messages[].content` очікує рядок
|
||||
- періодичні попередження `incomplete turn detected ... stopReason=stop payloads=0` з OpenAI-сумісним локальним бекендом
|
||||
- збої бекенду, які з’являються лише за більшої кількості токенів промпту або повних промптів середовища виконання агента
|
||||
- падіння бекенду, які з’являються лише з більшою кількістю prompt-токенів або повними промптами runtime агента
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Поширені ознаки">
|
||||
- `model_not_found` з локальним сервером у стилі MLX/vLLM → перевірте, що `baseUrl` містить `/v1`, `api` має значення `"openai-completions"` для бекендів `/v1/chat/completions`, а `models.providers.<provider>.models[].id` є локальним ідентифікатором провайдера без префікса. Виберіть її один раз із префіксом провайдера, наприклад `mlx/mlx-community/Qwen3-30B-A3B-6bit`; залиште запис каталогу як `mlx-community/Qwen3-30B-A3B-6bit`.
|
||||
- `messages[...].content: invalid type: sequence, expected a string` → бекенд відхиляє структуровані частини вмісту Chat Completions. Виправлення: установіть `models.providers.<provider>.models[].compat.requiresStringContent: true`.
|
||||
- `incomplete turn detected ... stopReason=stop payloads=0` → бекенд завершив запит Chat Completions, але не повернув видимого користувачу тексту асистента для цього ходу. OpenClaw один раз повторює порожні OpenAI-сумісні ходи, безпечні для повторного відтворення; сталі збої зазвичай означають, що бекенд видає порожній/нетекстовий вміст або пригнічує текст фінальної відповіді.
|
||||
- малі прямі запити успішні, але запуски агента OpenClaw завершуються збоями бекенду/моделі (наприклад Gemma на деяких збірках `inferrs`) → транспорт OpenClaw, імовірно, вже налаштований правильно; бекенд не справляється з більшою формою промпту середовища виконання агента.
|
||||
- збоїв стає менше після вимкнення інструментів, але вони не зникають → схеми інструментів були частиною навантаження, але залишкова проблема все ще полягає в обмеженнях моделі/сервера вище за стеком або помилці бекенду.
|
||||
<Accordion title="Типові ознаки">
|
||||
- `model_not_found` із локальним сервером у стилі MLX/vLLM → перевірте, що `baseUrl` містить `/v1`, `api` є `"openai-completions"` для бекендів `/v1/chat/completions`, а `models.providers.<provider>.models[].id` є простим локальним ідентифікатором провайдера. Виберіть його один раз із префіксом провайдера, наприклад `mlx/mlx-community/Qwen3-30B-A3B-6bit`; запис каталогу залиште як `mlx-community/Qwen3-30B-A3B-6bit`.
|
||||
- `messages[...].content: invalid type: sequence, expected a string` → бекенд відхиляє структуровані частини вмісту Chat Completions. Виправлення: встановіть `models.providers.<provider>.models[].compat.requiresStringContent: true`.
|
||||
- `incomplete turn detected ... stopReason=stop payloads=0` → бекенд завершив запит Chat Completions, але не повернув видимого користувачу тексту асистента для цього ходу. OpenClaw один раз повторює replay-safe порожні OpenAI-сумісні ходи; сталі збої зазвичай означають, що бекенд видає порожній/нетекстовий вміст або пригнічує текст фінальної відповіді.
|
||||
- прямі крихітні запити успішні, але запуски агента OpenClaw падають через аварії бекенду/моделі (наприклад Gemma в деяких збірках `inferrs`) → транспорт OpenClaw, імовірно, уже правильний; бекенд падає на більшій формі промпта runtime агента.
|
||||
- збої зменшуються після вимкнення інструментів, але не зникають → схеми інструментів були частиною навантаження, але залишкова проблема все ще в місткості upstream-моделі/сервера або помилці бекенду.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Варіанти виправлення">
|
||||
1. Установіть `compat.requiresStringContent: true` для бекендів Chat Completions, що підтримують лише рядковий вміст.
|
||||
1. Установіть `compat.requiresStringContent: true` для бекендів Chat Completions, які приймають лише рядки.
|
||||
2. Установіть `compat.supportsTools: false` для моделей/бекендів, які не можуть надійно обробляти поверхню схем інструментів OpenClaw.
|
||||
3. Зменште навантаження промпту, де це можливо: менша початкова ініціалізація робочої області, коротша історія сесії, легша локальна модель або бекенд із кращою підтримкою довгого контексту.
|
||||
4. Якщо малі прямі запити й далі проходять, а ходи агента OpenClaw все ще падають усередині бекенду, вважайте це обмеженням upstream-сервера/моделі та подайте туди відтворення з прийнятою формою корисного навантаження.
|
||||
3. За можливості зменште навантаження промпта: менший bootstrap робочої області, коротша історія сесії, легша локальна модель або бекенд із сильнішою підтримкою довгого контексту.
|
||||
4. Якщо крихітні прямі запити й далі проходять, а ходи агента OpenClaw досі падають усередині бекенду, розглядайте це як upstream-обмеження сервера/моделі й подайте туди відтворення з прийнятою формою payload.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Пов’язано:
|
||||
Пов’язане:
|
||||
|
||||
- [Конфігурація](/uk/gateway/configuration)
|
||||
- [Локальні моделі](/uk/gateway/local-models)
|
||||
- [OpenAI-сумісні кінцеві точки](/uk/gateway/configuration-reference#openai-compatible-endpoints)
|
||||
- [OpenAI-сумісні endpoints](/uk/gateway/configuration-reference#openai-compatible-endpoints)
|
||||
|
||||
## Немає відповідей
|
||||
|
||||
Якщо канали працюють, але нічого не відповідає, перевірте маршрутизацію й політику, перш ніж щось перепідключати.
|
||||
Якщо канали працюють, але нічого не відповідає, перевірте маршрутизацію та політику, перш ніж щось перепідключати.
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -168,25 +168,25 @@ openclaw logs --follow
|
||||
|
||||
Шукайте:
|
||||
|
||||
- Очікується сполучення для відправників приватних повідомлень.
|
||||
- Обмеження групових згадок (`requireMention`, `mentionPatterns`).
|
||||
- Невідповідності списку дозволених каналів/груп.
|
||||
- Очікуване сполучення для відправників DM.
|
||||
- Обмеження згадками в групах (`requireMention`, `mentionPatterns`).
|
||||
- Невідповідності allowlist каналу/групи.
|
||||
|
||||
Поширені ознаки:
|
||||
Типові ознаки:
|
||||
|
||||
- `drop guild message (mention required` → групове повідомлення ігнорується до згадки.
|
||||
- `pairing request` → відправник потребує схвалення.
|
||||
- `blocked` / `allowlist` → відправника/канал відфільтровано політикою.
|
||||
- `pairing request` → відправнику потрібне схвалення.
|
||||
- `blocked` / `allowlist` → відправника/канал було відфільтровано політикою.
|
||||
|
||||
Пов’язано:
|
||||
Пов’язане:
|
||||
|
||||
- [Усунення несправностей каналів](/uk/channels/troubleshooting)
|
||||
- [Групи](/uk/channels/groups)
|
||||
- [Сполучення](/uk/channels/pairing)
|
||||
|
||||
## Підключення панелі керування
|
||||
## Підключення dashboard control UI
|
||||
|
||||
Коли панель або інтерфейс керування не підключається, перевірте URL, режим автентифікації та припущення щодо захищеного контексту.
|
||||
Коли dashboard/control UI не підключається, перевірте URL, режим автентифікації та припущення щодо захищеного контексту.
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
@ -198,40 +198,40 @@ openclaw gateway status --json
|
||||
|
||||
Шукайте:
|
||||
|
||||
- Правильні URL перевірки та панелі керування.
|
||||
- Невідповідність режиму автентифікації/токена між клієнтом і Gateway.
|
||||
- Правильний URL проби та URL dashboard.
|
||||
- Невідповідність режиму автентифікації/токена між клієнтом і gateway.
|
||||
- Використання HTTP там, де потрібна ідентичність пристрою.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Ознаки підключення / автентифікації">
|
||||
- `device identity required` → незахищений контекст або відсутня автентифікація пристрою.
|
||||
- `origin not allowed` → браузерний `Origin` відсутній у `gateway.controlUi.allowedOrigins` (або ви підключаєтеся з браузерного origin не через loopback без явного списку дозволених).
|
||||
- `device nonce required` / `device nonce mismatch` → клієнт не завершує процес автентифікації пристрою на основі перевірочного виклику (`connect.challenge` + `device.nonce`).
|
||||
- `device signature invalid` / `device signature expired` → клієнт підписав неправильне корисне навантаження (або застарілу часову мітку) для поточного узгодження.
|
||||
- `origin not allowed` → браузерний `Origin` відсутній у `gateway.controlUi.allowedOrigins` (або ви підключаєтеся з не-loopback походження браузера без явного allowlist).
|
||||
- `device nonce required` / `device nonce mismatch` → клієнт не завершує challenge-based потік автентифікації пристрою (`connect.challenge` + `device.nonce`).
|
||||
- `device signature invalid` / `device signature expired` → клієнт підписав неправильний payload (або застарілу часову мітку) для поточного handshake.
|
||||
- `AUTH_TOKEN_MISMATCH` з `canRetryWithDeviceToken=true` → клієнт може виконати одну довірену повторну спробу з кешованим токеном пристрою.
|
||||
- Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений зі сполученим токеном пристрою. Викликачі з явним `deviceToken` / явними `scopes` натомість зберігають запитаний набір scope.
|
||||
- Поза цим шляхом повторної спроби пріоритет автентифікації connect такий: спершу явний спільний токен/пароль, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap-токен.
|
||||
- На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, ip}` серіалізуються до того, як обмежувач зафіксує збій. Тому дві невдалі одночасні повторні спроби від одного клієнта можуть показати `retry later` на другій спробі замість двох звичайних невідповідностей.
|
||||
- `too many failed authentication attempts (retry later)` від loopback-клієнта з браузерним origin → повторні збої з того самого нормалізованого `Origin` тимчасово блокуються; інший localhost origin використовує окремий лімітний сегмент.
|
||||
- повторювані `unauthorized` після цієї повторної спроби → розсинхронізація спільного токена/токена пристрою; оновіть конфігурацію токена та за потреби повторно схваліть/ротуйту токен пристрою.
|
||||
- `gateway connect failed:` → неправильна ціль хоста/порту/URL.
|
||||
- Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений разом зі сполученим токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` натомість зберігають запитаний набір scope.
|
||||
- За межами цього шляху повторної спроби пріоритет автентифікації connect такий: спочатку явний спільний токен/пароль, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap-токен.
|
||||
- На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, ip}` серіалізуються до того, як обмежувач записує збій. Тому дві погані одночасні повторні спроби від того самого клієнта можуть показати `retry later` на другій спробі замість двох простих невідповідностей.
|
||||
- `too many failed authentication attempts (retry later)` від browser-origin loopback-клієнта → повторні збої від того самого нормалізованого `Origin` тимчасово заблоковані; інше localhost-походження використовує окремий bucket.
|
||||
- повторні `unauthorized` після цієї повторної спроби → розходження спільного токена/токена пристрою; оновіть конфігурацію токена й за потреби повторно схваліть/ротируйте токен пристрою.
|
||||
- `gateway connect failed:` → неправильний хост/порт/url-ціль.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Швидка мапа кодів деталей автентифікації
|
||||
### Швидка мапа detail-кодів автентифікації
|
||||
|
||||
Використовуйте `error.details.code` з невдалої відповіді `connect`, щоб вибрати наступну дію:
|
||||
Використайте `error.details.code` з невдалої відповіді `connect`, щоб вибрати наступну дію:
|
||||
|
||||
| Код подробиць | Значення | Рекомендована дія |
|
||||
| Код деталі | Значення | Рекомендована дія |
|
||||
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `AUTH_TOKEN_MISSING` | Клієнт не надіслав обов’язковий спільний токен. | Вставте/задайте токен у клієнті та повторіть спробу. Для шляхів панелі: `openclaw config get gateway.auth.token`, потім вставте його в налаштування Control UI. |
|
||||
| `AUTH_TOKEN_MISMATCH` | Спільний токен не збігся з auth-токеном gateway. | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим токеном повторно використовують збережені схвалені scopes; виклики з явними `deviceToken` / `scopes` зберігають запитані scopes. Якщо помилка лишається, виконайте [контрольний список відновлення після дрейфу токена](/uk/cli/devices#token-drift-recovery-checklist). |
|
||||
| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований токен окремого пристрою застарів або був відкликаний. | Ротуйте/повторно схваліть токен пристрою за допомогою [CLI пристроїв](/uk/cli/devices), потім під’єднайтеся знову. |
|
||||
| `PAIRING_REQUIRED` | Ідентичність пристрою потребує схвалення. Перевірте `error.details.reason` на `not-paired`, `scope-upgrade`, `role-upgrade` або `metadata-upgrade` і використовуйте `requestId` / `remediationHint`, якщо вони є. | Схваліть запит, що очікує: `openclaw devices list`, потім `openclaw devices approve <requestId>`. Оновлення scope/ролі використовують той самий потік після того, як ви переглянете запитаний доступ. |
|
||||
| `AUTH_TOKEN_MISSING` | Клієнт не надіслав потрібний спільний токен. | Вставте/задайте токен у клієнті та повторіть спробу. Для шляхів dashboard: `openclaw config get gateway.auth.token`, потім вставте в налаштування Control UI. |
|
||||
| `AUTH_TOKEN_MISMATCH` | Спільний токен не збігся з токеном автентифікації Gateway. | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим токеном повторно використовують збережені схвалені області доступу; явні виклики з `deviceToken` / `scopes` зберігають запитані області доступу. Якщо помилка не зникає, виконайте [контрольний список відновлення після розсинхронізації токена](/uk/cli/devices#token-drift-recovery-checklist). |
|
||||
| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований токен для окремого пристрою застарів або був відкликаний. | Ротуйте/повторно схваліть токен пристрою за допомогою [CLI пристроїв](/uk/cli/devices), потім підключіться знову. |
|
||||
| `PAIRING_REQUIRED` | Ідентичність пристрою потребує схвалення. Перевірте `error.details.reason` на `not-paired`, `scope-upgrade`, `role-upgrade` або `metadata-upgrade`, і використовуйте `requestId` / `remediationHint`, коли вони присутні. | Схваліть очікуваний запит: `openclaw devices list`, потім `openclaw devices approve <requestId>`. Оновлення областей доступу/ролей використовують той самий потік після перегляду запитаного доступу. |
|
||||
|
||||
<Note>
|
||||
Прямі backend RPC через loopback, автентифіковані спільним токеном/паролем gateway, не мають залежати від базової лінії scope для спареного пристрою в CLI. Якщо subagents або інші внутрішні виклики все ще завершуються помилкою `scope-upgrade`, перевірте, що виклик використовує `client.id: "gateway-client"` і `client.mode: "backend"` та не примусово задає явний `deviceIdentity` або токен пристрою.
|
||||
Прямі loopback RPC бекенду, автентифіковані спільним токеном/паролем Gateway, не повинні залежати від базової лінії областей доступу сполученого пристрою CLI. Якщо subagents або інші внутрішні виклики все ще завершуються помилкою `scope-upgrade`, перевірте, що виклик використовує `client.id: "gateway-client"` і `client.mode: "backend"` та не примусово задає явний `deviceIdentity` або токен пристрою.
|
||||
</Note>
|
||||
|
||||
Перевірка міграції автентифікації пристроїв v2:
|
||||
@ -242,36 +242,36 @@ openclaw doctor
|
||||
openclaw gateway status
|
||||
```
|
||||
|
||||
Якщо журнали показують помилки nonce/signature, оновіть клієнт, що під’єднується, і перевірте його:
|
||||
Якщо журнали показують помилки nonce/підпису, оновіть клієнт, що підключається, і перевірте його:
|
||||
|
||||
<Steps>
|
||||
<Step title="Дочекайтеся connect.challenge">
|
||||
Клієнт чекає на виданий gateway `connect.challenge`.
|
||||
Клієнт чекає на виданий Gateway `connect.challenge`.
|
||||
</Step>
|
||||
<Step title="Підпишіть payload">
|
||||
Клієнт підписує payload, прив’язаний до challenge.
|
||||
</Step>
|
||||
<Step title="Надішліть nonce пристрою">
|
||||
Клієнт надсилає `connect.params.device.nonce` з тим самим nonce challenge.
|
||||
Клієнт надсилає `connect.params.device.nonce` з тим самим challenge nonce.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Якщо `openclaw devices rotate` / `revoke` / `remove` неочікувано відхилено:
|
||||
Якщо `openclaw devices rotate` / `revoke` / `remove` несподівано відхилено:
|
||||
|
||||
- сесії з токеном спареного пристрою можуть керувати лише **своїм власним** пристроєм, якщо виклик також не має `operator.admin`
|
||||
- `openclaw devices rotate --scope ...` може запитувати лише scopes оператора, які сесія виклику вже має
|
||||
- сесії з токеном сполученого пристрою можуть керувати лише **своїм власним** пристроєм, якщо виклик також не має `operator.admin`
|
||||
- `openclaw devices rotate --scope ...` може запитувати лише операторські області доступу, які вже має сесія виклику
|
||||
|
||||
Пов’язано:
|
||||
|
||||
- [Конфігурація](/uk/gateway/configuration) (режими автентифікації gateway)
|
||||
- [Конфігурація](/uk/gateway/configuration) (режими автентифікації Gateway)
|
||||
- [Control UI](/uk/web/control-ui)
|
||||
- [Пристрої](/uk/cli/devices)
|
||||
- [Віддалений доступ](/uk/gateway/remote)
|
||||
- [Автентифікація довіреного проксі](/uk/gateway/trusted-proxy-auth)
|
||||
|
||||
## Служба Gateway не працює
|
||||
## Сервіс Gateway не запущено
|
||||
|
||||
Використовуйте це, коли службу встановлено, але процес не залишається запущеним.
|
||||
Використовуйте це, коли сервіс установлено, але процес не залишається запущеним.
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
@ -283,33 +283,34 @@ openclaw gateway status --deep # also scan system-level services
|
||||
|
||||
Шукайте:
|
||||
|
||||
- `Runtime: stopped` з підказками щодо виходу.
|
||||
- Невідповідність конфігурації служби (`Config (cli)` проти `Config (service)`).
|
||||
- Конфлікти порту/listener.
|
||||
- `Runtime: stopped` із підказками щодо виходу.
|
||||
- Невідповідність конфігурації сервісу (`Config (cli)` проти `Config (service)`).
|
||||
- Конфлікти порту/слухача.
|
||||
- Додаткові встановлення launchd/systemd/schtasks, коли використовується `--deep`.
|
||||
- Підказки очищення `Other gateway-like services detected (best effort)`.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Поширені сигнатури">
|
||||
- `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → режим локального gateway не ввімкнено, або файл конфігурації було перезаписано й він втратив `gateway.mode`. Виправлення: задайте `gateway.mode="local"` у конфігурації або повторно запустіть `openclaw onboard --mode local` / `openclaw setup`, щоб повторно проставити очікувану конфігурацію local-mode. Якщо ви запускаєте OpenClaw через Podman, типовий шлях конфігурації — `~/.openclaw/openclaw.json`.
|
||||
- `refusing to bind gateway ... without auth` → прив’язування не до loopback без дійсного шляху автентифікації gateway (token/password або trusted-proxy, де налаштовано).
|
||||
- `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → локальний режим Gateway не ввімкнено, або файл конфігурації було перезаписано й він утратив `gateway.mode`. Виправлення: задайте `gateway.mode="local"` у своїй конфігурації або повторно запустіть `openclaw onboard --mode local` / `openclaw setup`, щоб повторно проставити очікувану конфігурацію локального режиму. Якщо ви запускаєте OpenClaw через Podman, типовий шлях конфігурації: `~/.openclaw/openclaw.json`.
|
||||
- `refusing to bind gateway ... without auth` → прив’язка не до loopback без чинного шляху автентифікації Gateway (токен/пароль або trusted-proxy, де налаштовано).
|
||||
- `another gateway instance is already listening` / `EADDRINUSE` → конфлікт порту.
|
||||
- `Other gateway-like services detected (best effort)` → існують застарілі або паралельні units launchd/systemd/schtasks. У більшості налаштувань має бути один gateway на машину; якщо вам справді потрібно більше одного, ізолюйте порти + конфігурацію/стан/workspace. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host).
|
||||
- `System-level OpenClaw gateway service detected` від doctor → існує systemd system unit, тоді як служба рівня користувача відсутня. Видаліть або вимкніть дублікат, перш ніж дозволити doctor встановити користувацьку службу, або задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, якщо system unit є запланованим супервізором.
|
||||
- `Gateway service port does not match current gateway config` → встановлений supervisor досі закріплює старий `--port`. Запустіть `openclaw doctor --fix` або `openclaw gateway install --force`, потім перезапустіть службу gateway.
|
||||
- `Other gateway-like services detected (best effort)` → існують застарілі або паралельні юніти launchd/systemd/schtasks. Більшість налаштувань має тримати один Gateway на машину; якщо вам потрібно більше ніж один, ізолюйте порти + конфігурацію/стан/робочий простір. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host).
|
||||
- `System-level OpenClaw gateway service detected` від doctor → існує системний юніт systemd, тоді як сервіс рівня користувача відсутній. Видаліть або вимкніть дублікат перед тим, як дозволити doctor установити користувацький сервіс, або задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, якщо системний юніт є потрібним supervisor.
|
||||
- `Gateway service port does not match current gateway config` → установлений supervisor усе ще фіксує старий `--port`. Запустіть `openclaw doctor --fix` або `openclaw gateway install --force`, потім перезапустіть сервіс Gateway.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Пов’язано:
|
||||
|
||||
- [Фоновий exec і process tool](/uk/gateway/background-process)
|
||||
- [Фонове виконання та process tool](/uk/gateway/background-process)
|
||||
- [Конфігурація](/uk/gateway/configuration)
|
||||
- [Doctor](/uk/gateway/doctor)
|
||||
|
||||
## Gateway відновив останню відому справну конфігурацію
|
||||
## Gateway відхилив недійсну конфігурацію
|
||||
|
||||
Використовуйте це, коли Gateway запускається, але журнали кажуть, що він відновив `openclaw.json`.
|
||||
Використовуйте це, коли запуск Gateway завершується помилкою `Invalid config` або журнали гарячого перезавантаження кажуть,
|
||||
що недійсну зміну пропущено.
|
||||
|
||||
```bash
|
||||
openclaw logs --follow
|
||||
@ -320,19 +321,19 @@ openclaw doctor
|
||||
|
||||
Шукайте:
|
||||
|
||||
- `Config auto-restored from last-known-good`
|
||||
- `gateway: invalid config was restored from last-known-good backup`
|
||||
- `config reload restored last-known-good config after invalid-config`
|
||||
- Файл `openclaw.json.clobbered.*` з часовою міткою поруч з активною конфігурацією
|
||||
- Системну подію main-agent, що починається з `Config recovery warning`
|
||||
- `Invalid config at ...`
|
||||
- `config reload skipped (invalid config): ...`
|
||||
- `Config write rejected: ...`
|
||||
- Файл `openclaw.json.rejected.*` із позначкою часу поруч з активною конфігурацією
|
||||
- Файл `openclaw.json.clobbered.*` із позначкою часу, якщо `doctor --fix` відремонтував зламане пряме редагування
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Що сталося">
|
||||
- Відхилена конфігурація не пройшла валідацію під час запуску або гарячого перезавантаження.
|
||||
- OpenClaw зберіг відхилений payload як `.clobbered.*`.
|
||||
- Активну конфігурацію було відновлено з останньої валідованої копії last-known-good.
|
||||
- Наступний хід main-agent отримує попередження не переписувати відхилену конфігурацію наосліп.
|
||||
- Якщо всі проблеми валідації були під `plugins.entries.<id>...`, OpenClaw не відновлював би весь файл. Локальні збої Plugin лишаються помітними, тоді як непов’язані користувацькі налаштування залишаються в активній конфігурації.
|
||||
- Конфігурація не пройшла валідацію під час запуску, гарячого перезавантаження або запису, яким володіє OpenClaw.
|
||||
- Запуск Gateway завершується закрито замість переписування `openclaw.json`.
|
||||
- Гаряче перезавантаження пропускає недійсні зовнішні редагування та залишає поточну runtime-конфігурацію активною.
|
||||
- Записи, якими володіє OpenClaw, відхиляють недійсні/руйнівні payload перед commit і зберігають `.rejected.*`.
|
||||
- `openclaw doctor --fix` володіє ремонтом. Він може видалити не-JSON префікси або відновити останню відому справну копію, зберігаючи відхилений payload як `.clobbered.*`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Перевірка та ремонт">
|
||||
@ -345,16 +346,17 @@ openclaw doctor
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Поширені сигнатури">
|
||||
- `.clobbered.*` існує → зовнішнє пряме редагування або читання під час запуску було відновлено.
|
||||
- `.rejected.*` існує → запис конфігурації, керований OpenClaw, не пройшов перевірки схеми або clobber перед комітом.
|
||||
- `Config write rejected:` → запис намагався видалити обов’язкову форму, різко зменшити файл або зберегти недійсну конфігурацію.
|
||||
- `Rejected validation details:` → журнал відновлення або повідомлення main-agent містить шлях схеми, що спричинив відновлення, наприклад `agents.defaults.execution` або `gateway.auth.password.source`.
|
||||
- `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good` або `size-drop-vs-last-good:*` → запуск обробив поточний файл як clobbered, бо він втратив поля або розмір порівняно з резервною копією last-known-good.
|
||||
- `Config last-known-good promotion skipped` → кандидат містив відредаговані placeholder-и секретів, як-от `***`.
|
||||
- `.clobbered.*` існує → doctor зберіг зламане зовнішнє редагування під час ремонту активної конфігурації.
|
||||
- `.rejected.*` існує → запис конфігурації, яким володіє OpenClaw, не пройшов перевірки схеми або clobber перед commit.
|
||||
- `Config write rejected:` → запис намагався прибрати потрібну структуру, різко зменшити файл або зберегти недійсну конфігурацію.
|
||||
- `config reload skipped (invalid config):` → пряме редагування не пройшло валідацію та було проігнороване запущеним Gateway.
|
||||
- `Invalid config at ...` → запуск завершився помилкою до завантаження сервісів Gateway.
|
||||
- `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good` або `size-drop-vs-last-good:*` → запис, яким володіє OpenClaw, було відхилено, бо він утратив поля або розмір порівняно з останньою відомою справною резервною копією.
|
||||
- `Config last-known-good promotion skipped` → кандидат містив замасковані placeholders секретів, як-от `***`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Варіанти виправлення">
|
||||
1. Залиште відновлену активну конфігурацію, якщо вона правильна.
|
||||
1. Запустіть `openclaw doctor --fix`, щоб doctor відремонтував конфігурацію з префіксом/clobbered або відновив останню відому справну.
|
||||
2. Скопіюйте лише потрібні ключі з `.clobbered.*` або `.rejected.*`, потім застосуйте їх за допомогою `openclaw config set` або `config.patch`.
|
||||
3. Запустіть `openclaw config validate` перед перезапуском.
|
||||
4. Якщо редагуєте вручну, зберігайте повну конфігурацію JSON5, а не лише частковий об’єкт, який хотіли змінити.
|
||||
@ -368,9 +370,9 @@ openclaw doctor
|
||||
- [Конфігурація: сувора валідація](/uk/gateway/configuration#strict-validation)
|
||||
- [Doctor](/uk/gateway/doctor)
|
||||
|
||||
## Попередження probe для Gateway
|
||||
## Попередження probe Gateway
|
||||
|
||||
Використовуйте це, коли `openclaw gateway probe` досягає чогось, але все ще друкує блок попередження.
|
||||
Використовуйте це, коли `openclaw gateway probe` досягає чогось, але все одно друкує блок попереджень.
|
||||
|
||||
```bash
|
||||
openclaw gateway probe
|
||||
@ -380,27 +382,27 @@ openclaw gateway probe --ssh user@gateway-host
|
||||
|
||||
Шукайте:
|
||||
|
||||
- `warnings[].code` і `primaryTargetId` у JSON-виводі.
|
||||
- Чи стосується попередження SSH fallback, кількох gateways, відсутніх scopes або нерозв’язаних auth refs.
|
||||
- `warnings[].code` і `primaryTargetId` у виводі JSON.
|
||||
- Чи стосується попередження fallback SSH, кількох Gateway, відсутніх областей доступу або нерозв’язаних посилань автентифікації.
|
||||
|
||||
Поширені сигнатури:
|
||||
|
||||
- `SSH tunnel failed to start; falling back to direct probes.` → налаштування SSH не вдалося, але команда все одно спробувала прямі налаштовані/loopback targets.
|
||||
- `multiple reachable gateways detected` → відповіло більше ніж одне target. Зазвичай це означає навмисне налаштування multi-gateway або застарілі/дубльовані listeners.
|
||||
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → підключення спрацювало, але detail RPC обмежено scope; спаруйте ідентичність пристрою або використайте credentials з `operator.read`.
|
||||
- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → підключення спрацювало, але повний набір діагностичних RPC вичерпав час очікування або завершився помилкою. Вважайте це досяжним Gateway з погіршеною діагностикою; порівняйте `connect.ok` і `connect.rpcOk` у виводі `--json`.
|
||||
- `Capability: pairing-pending` або `gateway closed (1008): pairing required` → gateway відповів, але цьому клієнту ще потрібне pairing/approval перед звичайним операторським доступом.
|
||||
- нерозв’язаний текст попередження `gateway.auth.*` / `gateway.remote.*` SecretRef → auth material був недоступний у цьому шляху команди для target, що зазнав збою.
|
||||
- `SSH tunnel failed to start; falling back to direct probes.` → налаштування SSH не вдалося, але команда все одно спробувала прямі налаштовані/loopback цілі.
|
||||
- `multiple reachable gateways detected` → відповіло більше ніж одна ціль. Зазвичай це означає навмисне налаштування з кількома Gateway або застарілі/дубльовані слухачі.
|
||||
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → підключення спрацювало, але detail RPC обмежений областями доступу; сполучіть ідентичність пристрою або використайте облікові дані з `operator.read`.
|
||||
- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → підключення спрацювало, але повний набір діагностичних RPC перевищив час очікування або завершився помилкою. Розглядайте це як досяжний Gateway із деградованою діагностикою; порівняйте `connect.ok` і `connect.rpcOk` у виводі `--json`.
|
||||
- `Capability: pairing-pending` або `gateway closed (1008): pairing required` → Gateway відповів, але цьому клієнту все ще потрібне сполучення/схвалення перед звичайним операторським доступом.
|
||||
- нерозв’язаний текст попередження SecretRef `gateway.auth.*` / `gateway.remote.*` → матеріал автентифікації був недоступний у цьому шляху команди для невдалої цілі.
|
||||
|
||||
Пов’язано:
|
||||
|
||||
- [Gateway](/uk/cli/gateway)
|
||||
- [Кілька gateways на одному хості](/uk/gateway#multiple-gateways-same-host)
|
||||
- [Кілька Gateway на одному хості](/uk/gateway#multiple-gateways-same-host)
|
||||
- [Віддалений доступ](/uk/gateway/remote)
|
||||
|
||||
## Канал під’єднано, повідомлення не передаються
|
||||
## Канал підключено, повідомлення не надходять
|
||||
|
||||
Якщо стан каналу — під’єднано, але потік повідомлень не працює, зосередьтеся на політиці, дозволах і правилах доставки, специфічних для каналу.
|
||||
Якщо стан каналу підключено, але потік повідомлень не працює, зосередьтеся на політиках, дозволах і правилах доставки, специфічних для каналу.
|
||||
|
||||
```bash
|
||||
openclaw channels status --probe
|
||||
@ -413,14 +415,14 @@ openclaw config get channels
|
||||
Шукайте:
|
||||
|
||||
- Політика DM (`pairing`, `allowlist`, `open`, `disabled`).
|
||||
- Allowlist груп і вимоги до згадок.
|
||||
- Allowlist груп і вимоги щодо згадок.
|
||||
- Відсутні дозволи/області доступу API каналу.
|
||||
|
||||
Поширені сигнатури:
|
||||
|
||||
- `mention required` → повідомлення проігноровано політикою згадок у групі.
|
||||
- `pairing` / трасування очікування схвалення → відправника не схвалено.
|
||||
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → проблема з автентифікацією/дозволами каналу.
|
||||
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → проблема автентифікації/дозволів каналу.
|
||||
|
||||
Пов’язано:
|
||||
|
||||
@ -431,7 +433,7 @@ openclaw config get channels
|
||||
|
||||
## Доставка Cron і Heartbeat
|
||||
|
||||
Якщо Cron або Heartbeat не запустився чи не доставив повідомлення, спочатку перевірте стан планувальника, а потім ціль доставки.
|
||||
Якщо Cron або Heartbeat не запустився чи не виконав доставку, спочатку перевірте стан планувальника, а потім ціль доставки.
|
||||
|
||||
```bash
|
||||
openclaw cron status
|
||||
@ -443,19 +445,19 @@ openclaw logs --follow
|
||||
|
||||
Шукайте:
|
||||
|
||||
- Cron увімкнено, і є наступне пробудження.
|
||||
- Статус історії запусків завдання (`ok`, `skipped`, `error`).
|
||||
- Cron увімкнено, і наявне наступне пробудження.
|
||||
- Стан історії запусків завдання (`ok`, `skipped`, `error`).
|
||||
- Причини пропуску Heartbeat (`quiet-hours`, `requests-in-flight`, `cron-in-progress`, `lanes-busy`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Поширені сигнатури">
|
||||
- `cron: scheduler disabled; jobs will not run automatically` → Cron вимкнено.
|
||||
- `cron: timer tick failed` → збій такту планувальника; перевірте помилки файлів/журналів/середовища виконання.
|
||||
- `heartbeat skipped` with `reason=quiet-hours` → поза вікном активних годин.
|
||||
- `heartbeat skipped` with `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожні рядки / заголовки markdown, тому OpenClaw пропускає виклик моделі.
|
||||
- `heartbeat skipped` with `reason=no-tasks-due` → `HEARTBEAT.md` містить блок `tasks:`, але жодне із завдань не має виконуватися під час цього такту.
|
||||
- `heartbeat: unknown accountId` → недійсний id облікового запису для цілі доставки Heartbeat.
|
||||
- `heartbeat skipped` with `reason=dm-blocked` → ціль Heartbeat визначено як призначення типу DM, тоді як `agents.defaults.heartbeat.directPolicy` (або перевизначення для окремого агента) встановлено на `block`.
|
||||
- `heartbeat skipped` з `reason=quiet-hours` → поза вікном активних годин.
|
||||
- `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожні рядки / markdown-заголовки, тому OpenClaw пропускає виклик моделі.
|
||||
- `heartbeat skipped` з `reason=no-tasks-due` → `HEARTBEAT.md` містить блок `tasks:`, але жодне із завдань не має виконуватися на цьому такті.
|
||||
- `heartbeat: unknown accountId` → недійсний ідентифікатор облікового запису для цілі доставки Heartbeat.
|
||||
- `heartbeat skipped` з `reason=dm-blocked` → ціль Heartbeat визначено як призначення в стилі DM, тоді як `agents.defaults.heartbeat.directPolicy` (або перевизначення для агента) встановлено в `block`.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -468,7 +470,7 @@ openclaw logs --follow
|
||||
|
||||
## Node спарено, інструмент не працює
|
||||
|
||||
Якщо Node спарено, але інструменти не працюють, ізолюйте стан переднього плану, дозволів і схвалень.
|
||||
Якщо Node спарено, але інструменти не працюють, ізолюйте стан переднього плану, дозволів і схвалення.
|
||||
|
||||
```bash
|
||||
openclaw nodes status
|
||||
@ -481,25 +483,25 @@ openclaw status
|
||||
Шукайте:
|
||||
|
||||
- Node онлайн з очікуваними можливостями.
|
||||
- Надання дозволів ОС для камери/мікрофона/геолокації/екрана.
|
||||
- Схвалення exec і стан allowlist.
|
||||
- Надані дозволи ОС для камери/мікрофона/геолокації/екрана.
|
||||
- Схвалення виконання й стан allowlist.
|
||||
|
||||
Поширені сигнатури:
|
||||
|
||||
- `NODE_BACKGROUND_UNAVAILABLE` → застосунок Node має бути на передньому плані.
|
||||
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → відсутній дозвіл ОС.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec.
|
||||
- `SYSTEM_RUN_DENIED: allowlist miss` → команда заблокована allowlist.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → очікується схвалення виконання.
|
||||
- `SYSTEM_RUN_DENIED: allowlist miss` → команду заблоковано allowlist.
|
||||
|
||||
Пов’язано:
|
||||
|
||||
- [Схвалення exec](/uk/tools/exec-approvals)
|
||||
- [Схвалення виконання](/uk/tools/exec-approvals)
|
||||
- [Усунення несправностей Node](/uk/nodes/troubleshooting)
|
||||
- [Nodes](/uk/nodes/index)
|
||||
|
||||
## Інструмент браузера не працює
|
||||
## Не працює інструмент браузера
|
||||
|
||||
Використовуйте це, коли дії інструмента браузера не вдаються, хоча сам Gateway справний.
|
||||
Використовуйте це, коли дії інструмента браузера не працюють, хоча сам Gateway справний.
|
||||
|
||||
```bash
|
||||
openclaw browser status
|
||||
@ -511,39 +513,39 @@ openclaw doctor
|
||||
|
||||
Шукайте:
|
||||
|
||||
- Чи встановлено `plugins.allow` і чи включає він `browser`.
|
||||
- Чи встановлено `plugins.allow` і чи містить воно `browser`.
|
||||
- Дійсний шлях до виконуваного файлу браузера.
|
||||
- Досяжність профілю CDP.
|
||||
- Доступність локального Chrome для профілів `existing-session` / `user`.
|
||||
- Наявність локального Chrome для профілів `existing-session` / `user`.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Сигнатури Plugin / виконуваного файлу">
|
||||
- `unknown command "browser"` або `unknown command 'browser'` → вбудований Plugin браузера виключено через `plugins.allow`.
|
||||
- інструмент браузера відсутній / недоступний, коли `browser.enabled=true` → `plugins.allow` виключає `browser`, тому Plugin ніколи не завантажився.
|
||||
- інструмент браузера відсутній / недоступний, хоча `browser.enabled=true` → `plugins.allow` виключає `browser`, тому Plugin ніколи не завантажився.
|
||||
- `Failed to start Chrome CDP on port` → процес браузера не вдалося запустити.
|
||||
- `browser.executablePath not found` → налаштований шлях недійсний.
|
||||
- `browser.cdpUrl must be http(s) or ws(s)` → налаштований URL CDP використовує непідтримувану схему, наприклад `file:` або `ftp:`.
|
||||
- `browser.cdpUrl has invalid port` → налаштований URL CDP має неправильний порт або порт поза діапазоном.
|
||||
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → поточна інсталяція Gateway не має основної залежності середовища виконання браузера; перевстановіть або оновіть OpenClaw, а потім перезапустіть Gateway. Знімки ARIA та базові знімки сторінок усе ще можуть працювати, але навігація, AI-знімки, знімки елементів за CSS-селектором і експорт PDF залишаються недоступними.
|
||||
- `browser.cdpUrl must be http(s) or ws(s)` → налаштована CDP URL-адреса використовує непідтримувану схему, як-от `file:` або `ftp:`.
|
||||
- `browser.cdpUrl has invalid port` → налаштована CDP URL-адреса має неправильний порт або порт поза допустимим діапазоном.
|
||||
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → у поточному встановленні Gateway бракує основної залежності середовища виконання браузера; перевстановіть або оновіть OpenClaw, а потім перезапустіть Gateway. ARIA-знімки й базові знімки сторінок усе ще можуть працювати, але навігація, AI-знімки, знімки елементів за CSS-селектором і експорт PDF залишаються недоступними.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Сигнатури Chrome MCP / existing-session">
|
||||
- `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session ще не зміг під’єднатися до вибраного каталогу даних браузера. Відкрийте сторінку інспектування браузера, увімкніть віддалене налагодження, залиште браузер відкритим, схваліть перший запит на під’єднання, а потім повторіть спробу. Якщо стан входу не потрібен, віддайте перевагу керованому профілю `openclaw`.
|
||||
- `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session ще не зміг під’єднатися до вибраного каталогу даних браузера. Відкрийте сторінку інспектування браузера, увімкніть віддалене налагодження, тримайте браузер відкритим, схваліть перший запит на під’єднання, а потім повторіть спробу. Якщо стан входу не потрібен, надайте перевагу керованому профілю `openclaw`.
|
||||
- `No Chrome tabs found for profile="user"` → профіль під’єднання Chrome MCP не має відкритих локальних вкладок Chrome.
|
||||
- `Remote CDP for profile "<name>" is not reachable` → налаштована віддалена кінцева точка CDP недосяжна з хоста Gateway.
|
||||
- `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль лише для під’єднання не має досяжної цілі, або HTTP-кінцева точка відповіла, але WebSocket CDP усе одно не вдалося відкрити.
|
||||
- `Remote CDP for profile "<name>" is not reachable` → налаштована віддалена CDP-крапка недосяжна з хоста Gateway.
|
||||
- `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль лише для під’єднання не має досяжної цілі, або HTTP-крапка відповіла, але CDP WebSocket все одно не вдалося відкрити.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Сигнатури елемента / знімка екрана / завантаження">
|
||||
- `fullPage is not supported for element screenshots` → запит знімка екрана змішав `--full-page` з `--ref` або `--element`.
|
||||
- `fullPage is not supported for element screenshots` → запит знімка екрана поєднав `--full-page` з `--ref` або `--element`.
|
||||
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → виклики знімків екрана Chrome MCP / `existing-session` мають використовувати захоплення сторінки або `--ref` зі знімка, а не CSS `--element`.
|
||||
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → хукам завантаження Chrome MCP потрібні refs зі знімків, а не CSS-селектори.
|
||||
- `existing-session file uploads currently support one file at a time.` → надсилайте по одному завантаженню за виклик у профілях Chrome MCP.
|
||||
- `existing-session dialog handling does not support timeoutMs.` → хуки діалогів у профілях Chrome MCP не підтримують перевизначення часу очікування.
|
||||
- `existing-session type does not support timeoutMs overrides.` → опустіть `timeoutMs` для `act:type` у профілях `profile="user"` / Chrome MCP existing-session або використовуйте керований/CDP-профіль браузера, коли потрібен власний час очікування.
|
||||
- `existing-session evaluate does not support timeoutMs overrides.` → опустіть `timeoutMs` для `act:evaluate` у профілях `profile="user"` / Chrome MCP existing-session або використовуйте керований/CDP-профіль браузера, коли потрібен власний час очікування.
|
||||
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → хукам завантаження Chrome MCP потрібні посилання зі знімка, а не CSS-селектори.
|
||||
- `existing-session file uploads currently support one file at a time.` → надсилайте одне завантаження за виклик у профілях Chrome MCP.
|
||||
- `existing-session dialog handling does not support timeoutMs.` → хуки діалогів у профілях Chrome MCP не підтримують перевизначення тайм-ауту.
|
||||
- `existing-session type does not support timeoutMs overrides.` → пропустіть `timeoutMs` для `act:type` у профілях `profile="user"` / Chrome MCP existing-session або використовуйте керований/CDP-профіль браузера, коли потрібен власний тайм-аут.
|
||||
- `existing-session evaluate does not support timeoutMs overrides.` → пропустіть `timeoutMs` для `act:evaluate` у профілях `profile="user"` / Chrome MCP existing-session або використовуйте керований/CDP-профіль браузера, коли потрібен власний тайм-аут.
|
||||
- `response body is not supported for existing-session profiles yet.` → `responsebody` усе ще потребує керованого браузера або сирого CDP-профілю.
|
||||
- застарілі перевизначення viewport / темного режиму / locale / офлайн-режиму в профілях лише для під’єднання або віддалених CDP-профілях → запустіть `openclaw browser stop --browser-profile <name>`, щоб закрити активний сеанс керування й звільнити стан емуляції Playwright/CDP без перезапуску всього Gateway.
|
||||
- застарілі перевизначення viewport / темного режиму / локалі / офлайн-режиму в attach-only або віддалених CDP-профілях → виконайте `openclaw browser stop --browser-profile <name>`, щоб закрити активний сеанс керування та звільнити стан емуляції Playwright/CDP без перезапуску всього Gateway.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -555,7 +557,7 @@ openclaw doctor
|
||||
|
||||
## Якщо ви оновилися, і щось раптово зламалося
|
||||
|
||||
Більшість збоїв після оновлення спричинені розбіжностями конфігурації або суворішими стандартними налаштуваннями, які тепер застосовуються.
|
||||
Більшість збоїв після оновлення спричинені дрейфом конфігурації або суворішими типовими параметрами, які тепер застосовуються.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="1. Поведінка автентифікації та перевизначення URL змінилася">
|
||||
@ -568,8 +570,8 @@ openclaw doctor
|
||||
|
||||
Що перевірити:
|
||||
|
||||
- Якщо `gateway.mode=remote`, виклики CLI можуть націлюватися на віддалений сервіс, тоді як ваш локальний сервіс працює нормально.
|
||||
- Явні виклики `--url` не повертаються до збережених облікових даних.
|
||||
- Якщо `gateway.mode=remote`, виклики CLI можуть спрямовуватися на віддалений сервіс, тоді як ваш локальний сервіс працює нормально.
|
||||
- Явні виклики з `--url` не повертаються до збережених облікових даних.
|
||||
|
||||
Поширені сигнатури:
|
||||
|
||||
@ -577,7 +579,7 @@ openclaw doctor
|
||||
- `unauthorized` → кінцева точка досяжна, але автентифікація неправильна.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2. Обмеження bind і автентифікації стали суворішими">
|
||||
<Accordion title="2. Обмеження прив’язування й автентифікації стали суворішими">
|
||||
```bash
|
||||
openclaw config get gateway.bind
|
||||
openclaw config get gateway.auth.mode
|
||||
@ -588,16 +590,16 @@ openclaw doctor
|
||||
|
||||
Що перевірити:
|
||||
|
||||
- Прив’язки не до loopback (`lan`, `tailnet`, `custom`) потребують дійсного шляху автентифікації Gateway: автентифікації спільним токеном/паролем або правильно налаштованого розгортання `trusted-proxy` не для loopback.
|
||||
- Прив’язування не до loopback (`lan`, `tailnet`, `custom`) потребують дійсного шляху автентифікації Gateway: автентифікації за спільним токеном/паролем або правильно налаштованого розгортання `trusted-proxy` не через loopback.
|
||||
- Старі ключі на кшталт `gateway.token` не замінюють `gateway.auth.token`.
|
||||
|
||||
Поширені сигнатури:
|
||||
|
||||
- `refusing to bind gateway ... without auth` → прив’язка не до loopback без дійсного шляху автентифікації Gateway.
|
||||
- `Connectivity probe: failed`, коли середовище виконання працює → Gateway живий, але недоступний з поточною автентифікацією/url.
|
||||
- `refusing to bind gateway ... without auth` → прив’язування не до loopback без дійсного шляху автентифікації Gateway.
|
||||
- `Connectivity probe: failed`, коли середовище виконання працює → Gateway активний, але недоступний з поточною автентифікацією/URL.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3. Стан pairing і ідентичності пристрою змінився">
|
||||
<Accordion title="3. Стан спарення та ідентичності пристрою змінився">
|
||||
```bash
|
||||
openclaw devices list
|
||||
openclaw pairing list --channel <channel> [--account <id>]
|
||||
@ -607,18 +609,18 @@ openclaw doctor
|
||||
|
||||
Що перевірити:
|
||||
|
||||
- Очікувані схвалення пристроїв для панелі керування/Nodes.
|
||||
- Очікувані схвалення DM pairing після змін політики або ідентичності.
|
||||
- Очікувані схвалення пристроїв для панелі керування/nodes.
|
||||
- Очікувані схвалення спарення DM після змін політики або ідентичності.
|
||||
|
||||
Поширені сигнатури:
|
||||
|
||||
- `device identity required` → автентифікацію пристрою не задоволено.
|
||||
- `pairing required` → відправника/пристрій має бути схвалено.
|
||||
- `device identity required` → автентифікація пристрою не задоволена.
|
||||
- `pairing required` → відправника/пристрій потрібно схвалити.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Якщо конфігурація сервісу й середовище виконання після перевірок усе ще не збігаються, перевстановіть метадані сервісу з того самого профілю/каталогу стану:
|
||||
Якщо конфігурація сервісу й середовище виконання все ще не збігаються після перевірок, перевстановіть метадані сервісу з того самого профілю/каталогу стану:
|
||||
|
||||
```bash
|
||||
openclaw gateway install --force
|
||||
@ -628,8 +630,8 @@ openclaw gateway restart
|
||||
Пов’язано:
|
||||
|
||||
- [Автентифікація](/uk/gateway/authentication)
|
||||
- [Фоновий exec і інструмент процесу](/uk/gateway/background-process)
|
||||
- [Pairing, керований Gateway](/uk/gateway/pairing)
|
||||
- [Фонове виконання та інструмент процесів](/uk/gateway/background-process)
|
||||
- [Спарення, кероване Gateway](/uk/gateway/pairing)
|
||||
|
||||
## Пов’язано
|
||||
|
||||
|
||||
1075
docs/uk/help/faq.md
1075
docs/uk/help/faq.md
File diff suppressed because it is too large
Load Diff
@ -4,38 +4,38 @@ read_when:
|
||||
- Розуміння правил виявлення та завантаження Plugin
|
||||
- Робота з пакетами Plugin, сумісними з Codex/Claude
|
||||
sidebarTitle: Install and Configure
|
||||
summary: Встановлюйте, налаштовуйте та керуйте плагінами OpenClaw
|
||||
summary: Встановлення, налаштування й керування плагінами OpenClaw
|
||||
title: Plugins
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T15:53:33Z"
|
||||
generated_at: "2026-05-03T17:12:20Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 937623bf3bfd7832680264b28deaef58970b35fdae7cfa0e5731c097eccc38e6
|
||||
source_hash: 30e3cffc15c5c52dd539e21103c207c9e38955f9fd3acd561a52964eefafb8f0
|
||||
source_path: tools/plugin.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Плагіни розширюють OpenClaw новими можливостями: канали, постачальники моделей,
|
||||
оболонки агентів, інструменти, Skills, мовлення, транскрипція в реальному часі, голос у реальному часі,
|
||||
розуміння медіа, генерація зображень, генерація відео, отримання вебвмісту, вебпошук
|
||||
та інше. Деякі плагіни є **core** (постачаються з OpenClaw), інші
|
||||
є **зовнішніми**. Більшість зовнішніх плагінів публікуються та знаходяться через
|
||||
[ClawHub](/uk/tools/clawhub). Npm залишається підтримуваним для прямих встановлень і для
|
||||
тимчасового набору пакетів плагінів, що належать OpenClaw, доки ця міграція завершується.
|
||||
Plugins розширюють OpenClaw новими можливостями: канали, постачальники моделей,
|
||||
середовища агентів, інструменти, Skills, мовлення, транскрипція в реальному часі,
|
||||
голос у реальному часі, розуміння медіа, генерація зображень, генерація відео, веботримання, вебпошук
|
||||
та інше. Деякі plugins є **основними** (постачаються з OpenClaw), інші
|
||||
є **зовнішніми**. Більшість зовнішніх plugins публікуються й виявляються через
|
||||
[ClawHub](/uk/tools/clawhub). Npm і далі підтримується для прямих установлень і для
|
||||
тимчасового набору пакетів plugins, що належать OpenClaw, поки ця міграція завершується.
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
Приклади встановлення, перегляду списку, видалення, оновлення та публікації для копіювання дивіться в
|
||||
[Керування плагінами](/uk/plugins/manage-plugins).
|
||||
Приклади встановлення, перегляду списку, видалення, оновлення та публікації для копіювання і вставлення див.
|
||||
[Керування plugins](/uk/plugins/manage-plugins).
|
||||
|
||||
<Steps>
|
||||
<Step title="Перегляньте, що завантажено">
|
||||
<Step title="See what is loaded">
|
||||
```bash
|
||||
openclaw plugins list
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Встановіть плагін">
|
||||
<Step title="Install a plugin">
|
||||
```bash
|
||||
# Search ClawHub plugins
|
||||
openclaw plugins search "calendar"
|
||||
@ -56,7 +56,7 @@ x-i18n:
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Перезапустіть Gateway">
|
||||
<Step title="Restart the Gateway">
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
```
|
||||
@ -65,17 +65,17 @@ x-i18n:
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Керування в чаті">
|
||||
У запущеному Gateway команди лише для власника `/plugins enable` і `/plugins disable`
|
||||
запускають перезавантажувач конфігурації Gateway. Gateway перезавантажує runtime-поверхні плагінів
|
||||
у процесі, а нові ходи агента перебудовують список інструментів із
|
||||
оновленого реєстру. `/plugins install` змінює вихідний код плагіна, тому
|
||||
Gateway запитує перезапуск, замість удавати, що поточний процес може
|
||||
<Step title="Chat-native management">
|
||||
У запущеному Gateway доступні лише власнику `/plugins enable` і `/plugins disable`
|
||||
запускають перезавантажувач конфігурації Gateway. Gateway перезавантажує runtime-поверхні
|
||||
plugin у поточному процесі, а нові ходи агента перебудовують свій список інструментів з
|
||||
оновленого реєстру. `/plugins install` змінює вихідний код plugin, тому
|
||||
Gateway запитує перезапуск замість того, щоб удавати, ніби поточний процес може
|
||||
безпечно перезавантажити вже імпортовані модулі.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Перевірте плагін">
|
||||
<Step title="Verify the plugin">
|
||||
```bash
|
||||
openclaw plugins inspect <plugin-id> --runtime --json
|
||||
|
||||
@ -83,14 +83,14 @@ x-i18n:
|
||||
openclaw <plugin-command> --help
|
||||
```
|
||||
|
||||
Використовуйте `--runtime`, коли потрібно довести зареєстровані інструменти, сервіси, методи Gateway,
|
||||
hooks або CLI-команди, що належать плагіну. Звичайний `inspect` є холодною
|
||||
перевіркою маніфесту/реєстру й навмисно уникає імпорту runtime плагіна.
|
||||
Використовуйте `--runtime`, коли потрібно довести зареєстровані інструменти, сервіси, методи gateway,
|
||||
хуки або CLI-команди, що належать plugin. Звичайний `inspect` є холодною
|
||||
перевіркою маніфесту/реєстру й навмисно уникає імпорту runtime plugin.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Якщо ви віддаєте перевагу керуванню в чаті, увімкніть `commands.plugins: true` і використовуйте:
|
||||
Якщо ви віддаєте перевагу керуванню безпосередньо з чату, увімкніть `commands.plugins: true` і використовуйте:
|
||||
|
||||
```text
|
||||
/plugin install clawhub:<package>
|
||||
@ -98,86 +98,85 @@ x-i18n:
|
||||
/plugin enable <plugin-id>
|
||||
```
|
||||
|
||||
Шлях встановлення використовує той самий розв’язувач, що й CLI: локальний шлях/архів, явний
|
||||
Шлях встановлення використовує той самий резолвер, що й CLI: локальний шлях/архів, явний
|
||||
`clawhub:<pkg>`, явний `npm:<pkg>`, явний `git:<repo>` або проста специфікація пакета
|
||||
через npm.
|
||||
|
||||
Якщо конфігурація недійсна, встановлення зазвичай завершується закритою відмовою й спрямовує вас до
|
||||
`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях перевстановлення bundled-плагіна
|
||||
для плагінів, які явно вмикають
|
||||
Якщо конфігурація недійсна, встановлення зазвичай відмовляє закрито й спрямовує вас до
|
||||
`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях перевстановлення
|
||||
вбудованого plugin для plugins, які явно обирають
|
||||
`openclaw.install.allowInvalidConfigRecovery`.
|
||||
Під час запуску Gateway недійсна конфігурація одного плагіна ізолюється до цього плагіна:
|
||||
запуск записує проблему `plugins.entries.<id>.config`, пропускає цей плагін під час
|
||||
завантаження та залишає інші плагіни й канали онлайн. Запустіть `openclaw doctor --fix`,
|
||||
щоб ізолювати погану конфігурацію плагіна, вимкнувши цей запис плагіна та видаливши
|
||||
його недійсне конфігураційне навантаження; звичайна резервна копія конфігурації зберігає попередні значення.
|
||||
Коли конфігурація каналу посилається на плагін, який більше не можна знайти, але той самий
|
||||
застарілий id плагіна залишається в конфігурації плагіна або записах встановлення, запуск Gateway
|
||||
записує попередження та пропускає цей канал замість блокування всіх інших каналів.
|
||||
Запустіть `openclaw doctor --fix`, щоб видалити застарілі записи каналу/плагіна; невідомі
|
||||
ключі каналів без доказів застарілого плагіна все одно не проходять валідацію, щоб помилки введення залишалися
|
||||
видимими.
|
||||
Якщо встановлено `plugins.enabled: false`, застарілі посилання на плагіни вважаються інертними:
|
||||
запуск Gateway пропускає виявлення/завантаження плагінів, а `openclaw doctor` зберігає
|
||||
вимкнену конфігурацію плагіна замість автоматичного видалення. Повторно увімкніть плагіни перед
|
||||
запуском очищення doctor, якщо хочете видалити застарілі id плагінів.
|
||||
Під час запуску Gateway недійсна конфігурація plugin відмовляє закрито, як і будь-яка інша недійсна
|
||||
конфігурація. Запустіть `openclaw doctor --fix`, щоб ізолювати погану конфігурацію plugin,
|
||||
вимкнувши цей запис plugin і видаливши його недійсне корисне навантаження конфігурації; звичайна
|
||||
резервна копія конфігурації зберігає попередні значення.
|
||||
Коли конфігурація каналу посилається на plugin, який більше не виявляється, але той самий
|
||||
застарілий id plugin лишається в конфігурації plugin або записах установлення, запуск Gateway
|
||||
записує попередження в журнали й пропускає цей канал замість блокування всіх інших каналів.
|
||||
Запустіть `openclaw doctor --fix`, щоб видалити застарілі записи каналу/plugin; невідомі
|
||||
ключі каналів без доказів застарілого plugin і далі не проходять валідацію, щоб помилки друку залишались
|
||||
помітними.
|
||||
Якщо задано `plugins.enabled: false`, застарілі посилання на plugin трактуються як інертні:
|
||||
запуск Gateway пропускає роботу з виявлення/завантаження plugin, а `openclaw doctor` зберігає
|
||||
вимкнену конфігурацію plugin замість автоматичного видалення. Повторно ввімкніть plugins перед
|
||||
запуском очищення doctor, якщо хочете видалити застарілі id plugin.
|
||||
|
||||
Встановлення залежностей плагіна відбувається лише під час явних потоків встановлення/оновлення або
|
||||
ремонту doctor. Запуск Gateway, перезавантаження конфігурації та runtime-інспекція
|
||||
не запускають менеджери пакетів і не ремонтують дерева залежностей. Локальні плагіни вже мають
|
||||
мати встановлені залежності, тоді як npm-, git- і ClawHub-плагіни
|
||||
встановлюються в керовані корені плагінів OpenClaw. Залежності npm можуть бути hoisted
|
||||
у межах керованого npm-кореня OpenClaw; встановлення/оновлення сканує цей керований корінь перед
|
||||
довірою, а видалення прибирає npm-керовані пакети через npm. Зовнішні плагіни
|
||||
та власні шляхи завантаження все одно потрібно встановлювати через `openclaw plugins install`.
|
||||
Установлення залежностей plugin відбувається лише під час явних потоків install/update або
|
||||
виправлення doctor. Запуск Gateway, перезавантаження конфігурації та інспекція runtime не
|
||||
запускають менеджери пакетів і не відновлюють дерева залежностей. Локальні plugins вже повинні
|
||||
мати встановлені залежності, тоді як npm, git і ClawHub plugins встановлюються
|
||||
в керовані корені plugin OpenClaw. Залежності npm можуть бути підняті
|
||||
в межах керованого npm-кореня OpenClaw; install/update сканує цей керований корінь перед
|
||||
довірою, а uninstall видаляє керовані npm пакети через npm. Зовнішні plugins
|
||||
і власні шляхи завантаження все одно мають бути встановлені через `openclaw plugins install`.
|
||||
Використовуйте `openclaw plugins list --json`, щоб побачити статичний `dependencyStatus` для кожного
|
||||
видимого плагіна без імпорту runtime-коду або ремонту залежностей.
|
||||
Дивіться [Розв’язання залежностей Plugin](/uk/plugins/dependency-resolution) щодо життєвого циклу
|
||||
під час встановлення.
|
||||
видимого plugin без імпорту runtime-коду або відновлення залежностей.
|
||||
Див. [Розв’язання залежностей Plugin](/uk/plugins/dependency-resolution) щодо
|
||||
життєвого циклу під час встановлення.
|
||||
|
||||
Для npm-встановлень змінні селектори, як-от `latest` або dist-tag, розв’язуються
|
||||
перед встановленням, а потім закріплюються за точною перевіреною версією в керованому
|
||||
Для npm-встановлень змінні селектори, такі як `latest` або dist-tag, розв’язуються
|
||||
перед установленням, а потім закріплюються на точній перевіреній версії в керованому
|
||||
npm-корені OpenClaw. Після завершення npm OpenClaw перевіряє, що встановлений
|
||||
запис `package-lock.json` усе ще відповідає розв’язаній версії та integrity. Якщо
|
||||
npm записує інші метадані пакета, встановлення завершується помилкою, а керований пакет
|
||||
відкочується замість прийняття іншого артефакту плагіна.
|
||||
запис `package-lock.json` досі відповідає розв’язаній версії та цілісності. Якщо
|
||||
npm записує інші метадані пакета, установлення завершується помилкою, а керований пакет
|
||||
відкочується замість прийняття іншого артефакту plugin.
|
||||
|
||||
Вихідні checkout-и є pnpm-робочими просторами. Якщо ви клонуєте OpenClaw, щоб працювати над bundled
|
||||
плагінами, запустіть `pnpm install`; тоді OpenClaw завантажує bundled плагіни з
|
||||
`extensions/<id>`, тож правки й пакетно-локальні залежності використовуються напряму.
|
||||
Звичайні встановлення кореня npm призначені для пакетованого OpenClaw, а не для розробки
|
||||
з вихідного checkout-а.
|
||||
Вихідні checkout-и є pnpm workspaces. Якщо ви клонуєте OpenClaw, щоб працювати над вбудованими
|
||||
plugins, запустіть `pnpm install`; після цього OpenClaw завантажує вбудовані plugins з
|
||||
`extensions/<id>`, тому зміни та локальні для пакета залежності використовуються напряму.
|
||||
Звичайні встановлення в npm root призначені для пакетованого OpenClaw, а не для розробки
|
||||
у checkout вихідного коду.
|
||||
|
||||
## Типи плагінів
|
||||
## Типи Plugin
|
||||
|
||||
OpenClaw розпізнає два формати плагінів:
|
||||
OpenClaw розпізнає два формати plugin:
|
||||
|
||||
| Формат | Як це працює | Приклади |
|
||||
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
|
||||
| **Нативний** | `openclaw.plugin.json` + runtime-модуль; виконується в процесі | Офіційні плагіни, спільнотні npm-пакети |
|
||||
| **Bundle** | Codex/Claude/Cursor-сумісна структура; відображається на можливості OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
|
||||
| **Нативний** | `openclaw.plugin.json` + runtime-модуль; виконується в процесі | Офіційні plugins, npm-пакети спільноти |
|
||||
| **Bundle** | Сумісна з Codex/Claude/Cursor структура; зіставляється з функціями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
|
||||
|
||||
Обидва відображаються в `openclaw plugins list`. Дивіться [Plugin Bundles](/uk/plugins/bundles) для деталей bundle.
|
||||
Обидва з’являються в `openclaw plugins list`. Див. [Plugin Bundles](/uk/plugins/bundles) для подробиць про bundle.
|
||||
|
||||
Якщо ви пишете нативний плагін, почніть із [Створення Plugins](/uk/plugins/building-plugins)
|
||||
та [Огляду Plugin SDK](/uk/plugins/sdk-overview).
|
||||
Якщо ви пишете нативний plugin, почніть з [Створення Plugins](/uk/plugins/building-plugins)
|
||||
і [Огляд Plugin SDK](/uk/plugins/sdk-overview).
|
||||
|
||||
## Точки входу пакетів
|
||||
## Точки входу пакета
|
||||
|
||||
Нативні npm-пакети плагінів мають оголошувати `openclaw.extensions` у `package.json`.
|
||||
Кожен запис має залишатися всередині каталогу пакета й розв’язуватися в читабельний
|
||||
runtime-файл або у вихідний файл TypeScript з виведеним збудованим JavaScript
|
||||
аналогом, наприклад `src/index.ts` до `dist/index.js`.
|
||||
Пакетовані встановлення мають постачати цей JavaScript runtime-вивід. Резервний варіант
|
||||
вихідного TypeScript призначений для вихідних checkout-ів і локальних шляхів розробки, а не для
|
||||
npm-пакетів, встановлених у керований корінь плагінів OpenClaw.
|
||||
Нативні npm-пакети plugin мають оголошувати `openclaw.extensions` у `package.json`.
|
||||
Кожен запис має залишатися всередині каталогу пакета й розв’язуватися до читабельного
|
||||
runtime-файлу або до вихідного TypeScript-файлу з виведеним зібраним JavaScript
|
||||
відповідником, як-от `src/index.ts` до `dist/index.js`.
|
||||
Пакетовані встановлення мають постачати цей JavaScript runtime-вивід. Резервний варіант із
|
||||
вихідним TypeScript призначений для checkout-ів вихідного коду та шляхів локальної розробки, а не для
|
||||
npm-пакетів, установлених у керований корінь plugin OpenClaw.
|
||||
|
||||
Використовуйте `openclaw.runtimeExtensions`, коли опубліковані runtime-файли не розташовані за
|
||||
тими самими шляхами, що й вихідні записи. Якщо присутній, `runtimeExtensions` має містити
|
||||
Використовуйте `openclaw.runtimeExtensions`, коли опубліковані runtime-файли не розміщені за
|
||||
тими самими шляхами, що й вихідні записи. Коли `runtimeExtensions` присутній, він має містити
|
||||
рівно один запис для кожного запису `extensions`. Невідповідні списки провалюють встановлення та
|
||||
виявлення плагінів замість тихого повернення до вихідних шляхів. Якщо ви також
|
||||
публікуєте `openclaw.setupEntry`, використовуйте `openclaw.runtimeSetupEntry` для його збудованого
|
||||
JavaScript-аналога; цей файл обов’язковий, коли оголошений.
|
||||
виявлення plugin, а не тихо повертаються до вихідних шляхів. Якщо ви також
|
||||
публікуєте `openclaw.setupEntry`, використовуйте `openclaw.runtimeSetupEntry` для його зібраного
|
||||
JavaScript-відповідника; цей файл є обов’язковим, коли оголошений.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -189,21 +188,21 @@ JavaScript-аналога; цей файл обов’язковий, коли
|
||||
}
|
||||
```
|
||||
|
||||
## Офіційні плагіни
|
||||
## Офіційні plugins
|
||||
|
||||
### npm-пакети, що належать OpenClaw, під час міграції
|
||||
### Npm-пакети, що належать OpenClaw, під час міграції
|
||||
|
||||
ClawHub є основним шляхом розповсюдження для більшості плагінів. Поточні пакетовані
|
||||
випуски OpenClaw уже містять багато офіційних плагінів, тому вони не потребують
|
||||
окремих npm-встановлень у звичайних налаштуваннях. Доки кожен плагін, що належить OpenClaw,
|
||||
не мігрує до ClawHub, OpenClaw усе ще постачає деякі пакети плагінів `@openclaw/*`
|
||||
на npm для старіших/власних встановлень і прямих npm-процесів.
|
||||
ClawHub є основним шляхом розповсюдження для більшості plugins. Поточні пакетовані
|
||||
випуски OpenClaw уже містять багато офіційних plugins, тому в нормальних налаштуваннях їм не потрібні
|
||||
окремі npm-встановлення. Поки кожен plugin, що належить OpenClaw, не
|
||||
мігрував до ClawHub, OpenClaw і далі постачає деякі пакети plugin `@openclaw/*` в
|
||||
npm для старіших/власних установлень і прямих npm-процесів.
|
||||
|
||||
Якщо npm повідомляє, що пакет плагіна `@openclaw/*` застарілий, ця версія пакета
|
||||
походить зі старішої зовнішньої лінійки пакетів. Використовуйте bundled плагін із
|
||||
Якщо npm повідомляє, що пакет plugin `@openclaw/*` застарілий, ця версія пакета
|
||||
походить зі старішої лінійки зовнішніх пакетів. Використовуйте вбудований plugin з
|
||||
поточного OpenClaw або локальний checkout, доки не буде опубліковано новіший npm-пакет.
|
||||
|
||||
| Плагін | Пакет | Документація |
|
||||
| Plugin | Пакет | Документація |
|
||||
| --------------- | -------------------------- | ------------------------------------------ |
|
||||
| BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/uk/channels/bluebubbles) |
|
||||
| Discord | `@openclaw/discord` | [Discord](/uk/channels/discord) |
|
||||
@ -219,10 +218,10 @@ ClawHub є основним шляхом розповсюдження для б
|
||||
| Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) |
|
||||
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) |
|
||||
|
||||
### Core (постачається з OpenClaw)
|
||||
### Основні (постачаються з OpenClaw)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Постачальники моделей (увімкнено за замовчуванням)">
|
||||
<Accordion title="Model providers (enabled by default)">
|
||||
`anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`,
|
||||
`huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`,
|
||||
`moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`,
|
||||
@ -230,27 +229,27 @@ ClawHub є основним шляхом розповсюдження для б
|
||||
`vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Плагіни пам’яті">
|
||||
- `memory-core` — bundled пошук пам’яті (за замовчуванням через `plugins.slots.memory`)
|
||||
- `memory-lancedb` — довготривала пам’ять на базі LanceDB з автоматичним згадуванням/захопленням (встановіть `plugins.slots.memory = "memory-lancedb"`)
|
||||
<Accordion title="Memory plugins">
|
||||
- `memory-core` — вбудований пошук пам’яті (типово через `plugins.slots.memory`)
|
||||
- `memory-lancedb` — довгострокова пам’ять на основі LanceDB з автоматичним пригадуванням/захопленням (задайте `plugins.slots.memory = "memory-lancedb"`)
|
||||
|
||||
Дивіться [Memory LanceDB](/uk/plugins/memory-lancedb) щодо налаштування embeddings, сумісних з OpenAI,
|
||||
прикладів Ollama, лімітів згадування та усунення несправностей.
|
||||
Див. [Memory LanceDB](/uk/plugins/memory-lancedb) щодо сумісного з OpenAI
|
||||
налаштування embeddings, прикладів Ollama, обмежень пригадування та усунення несправностей.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Постачальники мовлення (увімкнено за замовчуванням)">
|
||||
<Accordion title="Speech providers (enabled by default)">
|
||||
`elevenlabs`, `microsoft`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Інше">
|
||||
- `browser` — bundled плагін браузера для інструмента браузера, CLI `openclaw browser`, методу gateway `browser.request`, runtime браузера та стандартного сервісу керування браузером (увімкнено за замовчуванням; вимкніть перед заміною)
|
||||
- `copilot-proxy` — міст VS Code Copilot Proxy (вимкнено за замовчуванням)
|
||||
<Accordion title="Other">
|
||||
- `browser` — вбудований browser plugin для інструмента browser, CLI `openclaw browser`, gateway-методу `browser.request`, browser runtime і стандартного сервісу керування browser (увімкнено типово; вимкніть перед заміною)
|
||||
- `copilot-proxy` — міст VS Code Copilot Proxy (вимкнено типово)
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Шукаєте сторонні плагіни? Дивіться [Плагіни спільноти](/uk/plugins/community).
|
||||
Шукаєте сторонні plugins? Див. [Plugins спільноти](/uk/plugins/community).
|
||||
|
||||
## Конфігурація
|
||||
|
||||
@ -268,124 +267,120 @@ ClawHub є основним шляхом розповсюдження для б
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Опис |
|
||||
| Поле | Опис |
|
||||
| ---------------- | --------------------------------------------------------- |
|
||||
| `enabled` | Головний перемикач (типово: `true`) |
|
||||
| `allow` | Список дозволених Plugin (необов’язково) |
|
||||
| `deny` | Список заборонених Plugin (необов’язково; deny перемагає) |
|
||||
| `load.paths` | Додаткові файли/каталоги plugin |
|
||||
| `enabled` | Головний перемикач (за замовчуванням: `true`) |
|
||||
| `allow` | Список дозволених Plugin (необов'язково) |
|
||||
| `deny` | Список заборонених Plugin (необов'язково; заборона має пріоритет) |
|
||||
| `load.paths` | Додаткові файли/каталоги Plugin |
|
||||
| `slots` | Ексклюзивні селектори слотів (наприклад, `memory`, `contextEngine`) |
|
||||
| `entries.\<id\>` | Перемикачі + конфігурація для окремого plugin |
|
||||
| `entries.\<id\>` | Перемикачі та конфігурація для окремих Plugin |
|
||||
|
||||
`plugins.allow` є ексклюзивним. Коли він непорожній, завантажуватися або
|
||||
надавати інструменти можуть лише перелічені plugins, навіть якщо `tools.allow`
|
||||
містить `"*"` або конкретну назву інструмента, що належить plugin. Якщо список
|
||||
дозволених інструментів посилається на інструменти plugin, додайте ідентифікатори
|
||||
відповідних plugins до `plugins.allow` або приберіть `plugins.allow`; `openclaw doctor`
|
||||
попереджає про таку структуру.
|
||||
`plugins.allow` є ексклюзивним. Коли він непорожній, завантажуватися
|
||||
або надавати інструменти можуть лише перелічені Plugin, навіть якщо `tools.allow` містить `"*"` або конкретну назву
|
||||
інструмента, що належить Plugin. Якщо список дозволених інструментів посилається на інструменти Plugin, додайте ідентифікатори Plugin-власників
|
||||
до `plugins.allow` або вилучіть `plugins.allow`; `openclaw doctor` попереджає про таку
|
||||
форму.
|
||||
|
||||
Зміни конфігурації, внесені через `/plugins enable` або `/plugins disable`,
|
||||
запускають перезавантаження plugins Gateway у поточному процесі. Нові ходи агента
|
||||
перебудовують свій список інструментів з оновленого реєстру plugins. Операції,
|
||||
що змінюють джерела, як-от встановлення, оновлення та видалення, і далі
|
||||
перезапускають процес Gateway, бо вже імпортовані модулі plugin неможливо
|
||||
безпечно замінити на місці.
|
||||
Зміни конфігурації, внесені через `/plugins enable` або `/plugins disable`, запускають
|
||||
перезавантаження Plugin Gateway у межах процесу. Нові ходи агента перебудовують свій список інструментів із
|
||||
оновленого реєстру Plugin. Операції, що змінюють джерело, як-от встановлення,
|
||||
оновлення та видалення, усе ще перезапускають процес Gateway, оскільки вже імпортовані
|
||||
модулі Plugin не можна безпечно замінити на місці.
|
||||
|
||||
`openclaw plugins list` — це локальний знімок реєстру/config plugins. Plugin
|
||||
зі станом `enabled` там означає, що збережений реєстр і поточна config дозволяють
|
||||
plugin брати участь. Це не доводить, що вже запущений віддалений Gateway
|
||||
перезавантажився або перезапустився з тим самим кодом plugin. У налаштуваннях
|
||||
VPS/контейнерів із процесами-обгортками надсилайте перезапуски або записи, що
|
||||
запускають перезавантаження, до фактичного процесу `openclaw gateway run`, або
|
||||
використовуйте `openclaw gateway restart` для запущеного Gateway, коли
|
||||
перезавантаження повідомляє про помилку.
|
||||
`openclaw plugins list` — це локальний знімок реєстру/конфігурації Plugin. Plugin зі станом
|
||||
`enabled` там означає, що збережений реєстр і поточна конфігурація дозволяють цьому
|
||||
Plugin брати участь. Це не доводить, що вже запущений віддалений Gateway
|
||||
перезавантажився або перезапустився з тим самим кодом Plugin. У налаштуваннях VPS/контейнерів
|
||||
із процесами-обгортками надсилайте перезапуски або записи, що запускають перезавантаження, фактичному
|
||||
процесу `openclaw gateway run`, або використовуйте `openclaw gateway restart` для
|
||||
запущеного Gateway, коли перезавантаження повідомляє про помилку.
|
||||
|
||||
<Accordion title="Стани Plugin: вимкнений, відсутній, недійсний">
|
||||
- **Вимкнений**: plugin існує, але правила ввімкнення вимкнули його. Config збережено.
|
||||
- **Відсутній**: config посилається на ідентифікатор plugin, якого не знайшло виявлення.
|
||||
- **Недійсний**: plugin існує, але його config не відповідає оголошеній схемі. Запуск Gateway пропускає лише цей plugin; `openclaw doctor --fix` може ізолювати недійсний запис, вимкнувши його та вилучивши його config payload.
|
||||
- **Вимкнений**: Plugin існує, але правила ввімкнення його вимкнули. Конфігурація зберігається.
|
||||
- **Відсутній**: конфігурація посилається на ідентифікатор Plugin, який виявлення не знайшло.
|
||||
- **Недійсний**: Plugin існує, але його конфігурація не відповідає оголошеній схемі. Запуск Gateway пропускає лише цей Plugin; `openclaw doctor --fix` може помістити недійсний запис у карантин, вимкнувши його та вилучивши його конфігураційне навантаження.
|
||||
|
||||
</Accordion>
|
||||
|
||||
## Виявлення та пріоритет
|
||||
|
||||
OpenClaw сканує plugins у такому порядку (перший збіг перемагає):
|
||||
OpenClaw сканує Plugin у такому порядку (перший збіг перемагає):
|
||||
|
||||
<Steps>
|
||||
<Step title="Шляхи config">
|
||||
<Step title="Шляхи конфігурації">
|
||||
`plugins.load.paths` — явні шляхи до файлів або каталогів. Шляхи, що вказують
|
||||
назад на власні паковані каталоги bundled plugins OpenClaw, ігноруються;
|
||||
запустіть `openclaw doctor --fix`, щоб прибрати ці застарілі aliases.
|
||||
назад на власні упаковані каталоги вбудованих Plugin OpenClaw, ігноруються;
|
||||
виконайте `openclaw doctor --fix`, щоб вилучити ці застарілі псевдоніми.
|
||||
</Step>
|
||||
|
||||
<Step title="Plugins робочої області">
|
||||
<Step title="Plugin робочого простору">
|
||||
`\<workspace\>/.openclaw/<plugin-root>/*.ts` і `\<workspace\>/.openclaw/<plugin-root>/*/index.ts`.
|
||||
</Step>
|
||||
|
||||
<Step title="Глобальні plugins">
|
||||
<Step title="Глобальні Plugin">
|
||||
`~/.openclaw/<plugin-root>/*.ts` і `~/.openclaw/<plugin-root>/*/index.ts`.
|
||||
</Step>
|
||||
|
||||
<Step title="Bundled plugins">
|
||||
Постачаються з OpenClaw. Багато з них увімкнені типово (провайдери моделей, мовлення).
|
||||
<Step title="Вбудовані Plugin">
|
||||
Постачаються з OpenClaw. Багато з них увімкнені за замовчуванням (постачальники моделей, мовлення).
|
||||
Інші потребують явного ввімкнення.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Паковані встановлення та Docker-образи зазвичай розв’язують bundled plugins з
|
||||
скомпільованого дерева `dist/extensions`. Якщо вихідний каталог bundled plugin
|
||||
примонтовано поверх відповідного пакованого шляху джерел, наприклад
|
||||
`/app/extensions/synology-chat`, OpenClaw розглядає цей примонтований каталог
|
||||
джерел як overlay джерел bundled plugin і виявляє його перед пакованим bundle
|
||||
`/app/dist/extensions/synology-chat`. Це зберігає працездатність контейнерних
|
||||
циклів мейнтейнерів без перемикання кожного bundled plugin назад на джерела
|
||||
TypeScript. Установіть `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, щоб
|
||||
примусово використовувати паковані dist bundles, навіть коли присутні монтування
|
||||
source overlay.
|
||||
Упаковані встановлення та образи Docker зазвичай визначають вбудовані Plugin з
|
||||
скомпільованого дерева `dist/extensions`. Якщо вихідний каталог вбудованого Plugin
|
||||
змонтовано поверх відповідного упакованого вихідного шляху, наприклад
|
||||
`/app/extensions/synology-chat`, OpenClaw розглядає цей змонтований вихідний каталог
|
||||
як вбудоване вихідне накладання та виявляє його перед упакованим
|
||||
пакетом `/app/dist/extensions/synology-chat`. Це зберігає працездатність контейнерних
|
||||
циклів супровідників без перемикання кожного вбудованого Plugin назад на вихідний код TypeScript.
|
||||
Установіть `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, щоб примусово використовувати упаковані dist-пакети
|
||||
навіть за наявності змонтованих вихідних накладань.
|
||||
|
||||
### Правила ввімкнення
|
||||
|
||||
- `plugins.enabled: false` вимикає всі plugins і пропускає роботу з виявлення/завантаження plugins
|
||||
- `plugins.deny` завжди перемагає allow
|
||||
- `plugins.entries.\<id\>.enabled: false` вимикає цей plugin
|
||||
- Plugins з робочої області **типово вимкнені** (їх потрібно явно ввімкнути)
|
||||
- Bundled plugins дотримуються вбудованого набору default-on, якщо його не перевизначено
|
||||
- Ексклюзивні слоти можуть примусово ввімкнути вибраний plugin для цього слота
|
||||
- Деякі bundled opt-in plugins вмикаються автоматично, коли config називає
|
||||
поверхню, що належить plugin, як-от provider model ref, channel config або harness
|
||||
runtime
|
||||
- Застаріла config plugin зберігається, поки активний `plugins.enabled: false`;
|
||||
повторно ввімкніть plugins перед запуском очищення doctor, якщо хочете вилучити застарілі ids
|
||||
- Маршрути Codex сімейства OpenAI зберігають окремі межі plugin:
|
||||
`openai-codex/*` належить OpenAI plugin, тоді як bundled Codex
|
||||
app-server plugin вибирається через `agentRuntime.id: "codex"` або застарілі
|
||||
model refs `codex/*`
|
||||
- `plugins.enabled: false` вимикає всі Plugin і пропускає роботу з виявлення/завантаження Plugin
|
||||
- `plugins.deny` завжди має пріоритет над allow
|
||||
- `plugins.entries.\<id\>.enabled: false` вимикає цей Plugin
|
||||
- Plugin з походженням із робочого простору **вимкнені за замовчуванням** (їх потрібно явно ввімкнути)
|
||||
- Вбудовані Plugin дотримуються вбудованого набору ввімкнених за замовчуванням, якщо це не перевизначено
|
||||
- Ексклюзивні слоти можуть примусово ввімкнути вибраний Plugin для цього слота
|
||||
- Деякі вбудовані opt-in Plugin вмикаються автоматично, коли конфігурація називає
|
||||
поверхню, що належить Plugin, як-от посилання на модель постачальника, конфігурація каналу або
|
||||
runtime стенда
|
||||
- Застаріла конфігурація Plugin зберігається, доки активний `plugins.enabled: false`;
|
||||
повторно ввімкніть Plugin перед запуском очищення doctor, якщо хочете вилучити застарілі ідентифікатори
|
||||
- Маршрути Codex сімейства OpenAI зберігають окремі межі Plugin:
|
||||
`openai-codex/*` належить OpenAI Plugin, тоді як вбудований Plugin app-server Codex
|
||||
вибирається через `agentRuntime.id: "codex"` або застарілі
|
||||
посилання на модель `codex/*`
|
||||
|
||||
## Усунення проблем runtime hooks
|
||||
## Усунення проблем із runtime-хуками
|
||||
|
||||
Якщо plugin відображається в `plugins list`, але побічні ефекти або hooks
|
||||
`register(api)` не виконуються в live chat traffic, спершу перевірте це:
|
||||
Якщо Plugin відображається в `plugins list`, але побічні ефекти або хуки `register(api)`
|
||||
не виконуються в живому чат-трафіку, спершу перевірте це:
|
||||
|
||||
- Запустіть `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні
|
||||
URL Gateway, профіль, шлях config і процес саме ті, які ви редагуєте.
|
||||
- Перезапустіть live Gateway після змін встановлення/config/коду plugin. У
|
||||
контейнерах-обгортках PID 1 може бути лише supervisor; перезапустіть або
|
||||
надішліть сигнал дочірньому процесу `openclaw gateway run`.
|
||||
- Використайте `openclaw plugins inspect <id> --runtime --json`, щоб підтвердити реєстрації hooks і
|
||||
діагностику. Небандлові conversation hooks, як-от `llm_input`,
|
||||
`llm_output`, `before_agent_finalize` і `agent_end`, потребують
|
||||
- Виконайте `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні
|
||||
URL Gateway, профіль, шлях конфігурації та процес є саме тими, які ви редагуєте.
|
||||
- Перезапустіть живий Gateway після змін встановлення/конфігурації/коду Plugin. У контейнерах-обгортках
|
||||
PID 1 може бути лише супервізором; перезапустіть або надішліть сигнал дочірньому
|
||||
процесу `openclaw gateway run`.
|
||||
- Використайте `openclaw plugins inspect <id> --runtime --json`, щоб підтвердити реєстрації хуків і
|
||||
діагностику. Невбудованим хукам розмови, як-от `llm_input`,
|
||||
`llm_output`, `before_agent_finalize` і `agent_end`, потрібен
|
||||
`plugins.entries.<id>.hooks.allowConversationAccess=true`.
|
||||
- Для перемикання моделей надавайте перевагу `before_model_resolve`. Він виконується до
|
||||
розв’язання моделі для ходів агента; `llm_output` виконується лише після того, як спроба моделі
|
||||
створить assistant output.
|
||||
- Для доказу ефективної моделі сесії використовуйте `openclaw sessions` або
|
||||
поверхні session/status Gateway, а під час налагодження provider payloads запускайте
|
||||
- Для перемикання моделей віддавайте перевагу `before_model_resolve`. Він виконується перед розв'язанням моделі
|
||||
для ходів агента; `llm_output` виконується лише після того, як спроба моделі
|
||||
створить вивід асистента.
|
||||
- Для підтвердження ефективної моделі сесії використовуйте `openclaw sessions` або
|
||||
поверхні сесії/статусу Gateway, а під час налагодження навантажень постачальника запускайте
|
||||
Gateway з `--raw-stream --raw-stream-path <path>`.
|
||||
|
||||
### Повільне налаштування інструментів plugin
|
||||
### Повільне налаштування інструментів Plugin
|
||||
|
||||
Якщо ходи агента, схоже, зависають під час підготовки інструментів, увімкніть trace logging і
|
||||
перевірте рядки таймінгів фабрик інструментів plugin:
|
||||
Якщо здається, що ходи агента зависають під час підготовки інструментів, увімкніть трасувальне логування та
|
||||
перевірте рядки часу виконання фабрики інструментів Plugin:
|
||||
|
||||
```bash
|
||||
openclaw config set logging.level trace
|
||||
@ -398,25 +393,25 @@ openclaw logs --follow
|
||||
[trace:plugin-tools] factory timings ...
|
||||
```
|
||||
|
||||
Підсумок перелічує загальний час фабрик і найповільніші фабрики інструментів plugin,
|
||||
зокрема plugin id, оголошені назви інструментів, форму результату та чи є інструмент
|
||||
необов’язковим. Повільні рядки підвищуються до warnings, коли одна фабрика займає
|
||||
щонайменше 1 с або загальна підготовка фабрик інструментів plugin займає щонайменше 5 с.
|
||||
Зведення перелічує загальний час фабрики та найповільніші фабрики інструментів Plugin,
|
||||
включно з ідентифікатором Plugin, оголошеними назвами інструментів, формою результату та тим, чи є інструмент
|
||||
необов'язковим. Повільні рядки підвищуються до попереджень, коли одна фабрика займає
|
||||
щонайменше 1 с або загальна підготовка фабрик інструментів Plugin займає щонайменше 5 с.
|
||||
|
||||
OpenClaw кешує успішні результати фабрик інструментів plugin для повторних розв’язань
|
||||
OpenClaw кешує успішні результати фабрик інструментів Plugin для повторних розв'язань
|
||||
з тим самим ефективним контекстом запиту. Ключ кешу включає ефективну
|
||||
runtime config, workspace, agent/session ids, sandbox policy, browser settings,
|
||||
delivery context, requester identity і ownership state, тому фабрики, що
|
||||
залежать від цих довірених полів, запускаються повторно, коли контекст змінюється.
|
||||
runtime-конфігурацію, робочий простір, ідентифікатори агента/сесії, політику пісочниці, налаштування браузера,
|
||||
контекст доставки, ідентичність запитувача та стан власності, тому фабрики, що
|
||||
залежать від цих довірених полів, повторно виконуються, коли контекст змінюється.
|
||||
|
||||
Якщо один plugin домінує в таймінгах, перевірте його runtime registrations:
|
||||
Якщо один Plugin домінує за часом, перевірте його runtime-реєстрації:
|
||||
|
||||
```bash
|
||||
openclaw plugins inspect <plugin-id> --runtime --json
|
||||
```
|
||||
|
||||
Потім оновіть, перевстановіть або вимкніть цей plugin. Авторам plugins слід переносити
|
||||
дороге завантаження залежностей за шлях виконання інструмента, а не робити це
|
||||
Потім оновіть, перевстановіть або вимкніть цей Plugin. Автори Plugin мають переносити
|
||||
дороге завантаження залежностей у шлях виконання інструмента, а не робити це
|
||||
всередині фабрики інструмента.
|
||||
|
||||
### Дубльоване володіння каналом або інструментом
|
||||
@ -427,35 +422,34 @@ openclaw plugins inspect <plugin-id> --runtime --json
|
||||
- `channel setup already registered: <channel-id> (<plugin-id>)`
|
||||
- `plugin tool name conflict (<plugin-id>): <tool-name>`
|
||||
|
||||
Це означає, що кілька ввімкнених plugins намагаються володіти тим самим каналом,
|
||||
потоком налаштування або назвою інструмента. Найпоширеніша причина — зовнішній
|
||||
channel plugin, встановлений поруч із bundled plugin, який тепер надає той самий channel id.
|
||||
Це означає, що більш ніж один увімкнений Plugin намагається володіти тим самим каналом,
|
||||
потоком налаштування або назвою інструмента. Найпоширеніша причина — зовнішній Plugin каналу,
|
||||
установлений поруч із вбудованим Plugin, який тепер надає той самий ідентифікатор каналу.
|
||||
|
||||
Кроки налагодження:
|
||||
|
||||
- Запустіть `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений plugin
|
||||
і походження.
|
||||
- Запустіть `openclaw plugins inspect <id> --runtime --json` для кожного підозрюваного plugin і
|
||||
порівняйте `channels`, `channelConfigs`, `tools` і діагностику.
|
||||
- Запустіть `openclaw plugins registry --refresh` після встановлення або видалення
|
||||
packages plugin, щоб збережені metadata відображали поточне встановлення.
|
||||
- Перезапустіть Gateway після змін встановлення, реєстру або config.
|
||||
- Виконайте `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений Plugin
|
||||
і його походження.
|
||||
- Виконайте `openclaw plugins inspect <id> --runtime --json` для кожного підозрюваного Plugin і
|
||||
порівняйте `channels`, `channelConfigs`, `tools` та діагностику.
|
||||
- Виконайте `openclaw plugins registry --refresh` після встановлення або вилучення
|
||||
пакетів Plugin, щоб збережені метадані відображали поточне встановлення.
|
||||
- Перезапустіть Gateway після змін встановлення, реєстру або конфігурації.
|
||||
|
||||
Варіанти виправлення:
|
||||
|
||||
- Якщо один plugin навмисно замінює інший для того самого channel id, бажаний
|
||||
plugin має оголосити `channelConfigs.<channel-id>.preferOver` з ідентифікатором
|
||||
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 була однозначною.
|
||||
- Якщо один Plugin навмисно замінює інший для того самого ідентифікатора каналу, бажаний
|
||||
Plugin має оголосити `channelConfigs.<channel-id>.preferOver` з
|
||||
ідентифікатором Plugin нижчого пріоритету. Див. [/plugins/manifest#replacing-another-channel-plugin](/uk/plugins/manifest#replacing-another-channel-plugin).
|
||||
- Якщо дублювання випадкове, вимкніть один бік за допомогою
|
||||
`plugins.entries.<plugin-id>.enabled: false` або вилучіть застаріле встановлення Plugin.
|
||||
- Якщо ви явно ввімкнули обидва Plugin, OpenClaw зберігає цей запит і
|
||||
повідомляє про конфлікт. Виберіть одного власника для каналу або перейменуйте інструменти, що належать Plugin,
|
||||
щоб runtime-поверхня була однозначною.
|
||||
|
||||
## Слоти Plugin (ексклюзивні категорії)
|
||||
|
||||
Деякі категорії ексклюзивні (лише одна активна одночасно):
|
||||
Деякі категорії ексклюзивні (активною може бути лише одна одночасно):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -468,12 +462,12 @@ channel plugin, встановлений поруч із bundled plugin, яки
|
||||
}
|
||||
```
|
||||
|
||||
| Слот | Що контролює | Типово |
|
||||
| Слот | Що він контролює | За замовчуванням |
|
||||
| --------------- | --------------------- | ------------------- |
|
||||
| `memory` | Plugin активної пам’яті | `memory-core` |
|
||||
| `contextEngine` | Активний context engine | `legacy` (вбудований) |
|
||||
| `memory` | Активний Plugin пам'яті | `memory-core` |
|
||||
| `contextEngine` | Активний рушій контексту | `legacy` (вбудований) |
|
||||
|
||||
## Довідник CLI
|
||||
## Довідка CLI
|
||||
|
||||
```bash
|
||||
openclaw plugins list # compact inventory
|
||||
@ -521,82 +515,82 @@ openclaw plugins enable <id>
|
||||
openclaw plugins disable <id>
|
||||
```
|
||||
|
||||
Комплектні plugins постачаються з OpenClaw. Багато з них увімкнені за замовчуванням (наприклад
|
||||
комплектні постачальники моделей, комплектні постачальники мовлення та комплектний браузерний
|
||||
plugin). Інші комплектні plugins усе ще потребують `openclaw plugins enable <id>`.
|
||||
Пакетні плагіни постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (наприклад
|
||||
пакетні постачальники моделей, пакетні постачальники мовлення та пакетний браузерний
|
||||
плагін). Інші пакетні плагіни все ще потребують `openclaw plugins enable <id>`.
|
||||
|
||||
`--force` перезаписує наявний встановлений plugin або пакет хуків на місці. Використовуйте
|
||||
`--force` перезаписує наявний установлений плагін або набір хуків на місці. Використовуйте
|
||||
`openclaw plugins update <id-or-npm-spec>` для звичайних оновлень відстежуваних npm
|
||||
plugins. Це не підтримується з `--link`, який повторно використовує шлях до джерела замість
|
||||
плагінів. Він не підтримується разом із `--link`, який повторно використовує шлях до джерела замість
|
||||
копіювання поверх керованої цілі встановлення.
|
||||
|
||||
Коли `plugins.allow` уже задано, `openclaw plugins install` додає id
|
||||
встановленого plugin до цього списку дозволів перед його ввімкненням. Якщо той самий id plugin
|
||||
наявний у `plugins.deny`, встановлення видаляє цей застарілий запис заборони, щоб
|
||||
явно встановлений plugin можна було завантажити одразу після перезапуску.
|
||||
Коли `plugins.allow` уже задано, `openclaw plugins install` додає
|
||||
ідентифікатор установленого плагіна до цього списку дозволених перед його ввімкненням. Якщо той самий ідентифікатор плагіна
|
||||
є в `plugins.deny`, встановлення видаляє цей застарілий запис заборони, щоб
|
||||
явно встановлений плагін можна було завантажити одразу після перезапуску.
|
||||
|
||||
OpenClaw зберігає сталий локальний реєстр plugins як модель холодного читання для
|
||||
інвентаризації plugins, володіння внесками та планування запуску. Потоки встановлення, оновлення,
|
||||
видалення, ввімкнення та вимкнення оновлюють цей реєстр після зміни стану plugin.
|
||||
OpenClaw зберігає постійний локальний реєстр плагінів як модель холодного читання для
|
||||
інвентаризації плагінів, володіння внесками та планування запуску. Потоки встановлення, оновлення,
|
||||
видалення, увімкнення та вимкнення оновлюють цей реєстр після зміни стану плагіна.
|
||||
Той самий файл `plugins/installs.json` зберігає довговічні метадані встановлення у
|
||||
верхньорівневому `installRecords` і відновлювані метадані маніфесту в `plugins`. Якщо
|
||||
верхньорівневому `installRecords` і відновлювані метадані маніфестів у `plugins`. Якщо
|
||||
реєстр відсутній, застарілий або недійсний, `openclaw plugins registry
|
||||
--refresh` перебудовує його подання маніфестів із записів встановлення, політики конфігурації та
|
||||
метаданих маніфесту/пакета без завантаження модулів runtime plugin.
|
||||
метаданих маніфестів/пакетів без завантаження модулів середовища виконання плагінів.
|
||||
`openclaw plugins update <id-or-npm-spec>` застосовується до відстежуваних встановлень. Передавання
|
||||
специфікації npm-пакета з dist-tag або точною версією зіставляє назву пакета
|
||||
назад із відстежуваним записом plugin і записує нову специфікацію для майбутніх оновлень.
|
||||
Передавання назви пакета без версії переміщує встановлення з точно зафіксованою версією назад до
|
||||
типової лінії випусків реєстру. Якщо встановлений npm plugin уже відповідає
|
||||
специфікації npm пакета з dist-tag або точною версією зіставляє назву пакета
|
||||
назад із відстежуваним записом плагіна та записує нову специфікацію для майбутніх оновлень.
|
||||
Передавання назви пакета без версії повертає встановлення з точно зафіксованою версією назад до
|
||||
стандартної лінії випусків реєстру. Якщо встановлений npm плагін уже відповідає
|
||||
розв’язаній версії та записаній ідентичності артефакту, OpenClaw пропускає оновлення
|
||||
без завантаження, перевстановлення або переписування конфігурації.
|
||||
Коли `openclaw update` запускається на beta-каналі, записи plugins npm і ClawHub
|
||||
типової лінії спочатку пробують `@beta` і повертаються до default/latest, коли beta-випуску plugin
|
||||
не існує. Точні версії та явні теги залишаються зафіксованими.
|
||||
Коли `openclaw update` виконується на beta-каналі, записи npm і ClawHub
|
||||
плагінів стандартної лінії спершу пробують `@beta` і повертаються до default/latest, коли beta-випуску
|
||||
плагіна немає. Точні версії та явні теги залишаються зафіксованими.
|
||||
|
||||
`--pin` призначений лише для npm. Він не підтримується з `--marketplace`, оскільки
|
||||
marketplace-встановлення зберігають метадані джерела marketplace замість npm-специфікації.
|
||||
`--pin` призначений лише для npm. Він не підтримується з `--marketplace`, тому що
|
||||
встановлення з маркетплейсу зберігають метадані джерела маркетплейсу замість npm специфікації.
|
||||
|
||||
`--dangerously-force-unsafe-install` — це аварійне перевизначення для хибних
|
||||
спрацьовувань вбудованого сканера небезпечного коду. Воно дозволяє встановлення plugins
|
||||
і оновлення plugins продовжувати після вбудованих знахідок `critical`, але все одно
|
||||
не обходить блокування політики plugin `before_install` або блокування через збій сканування.
|
||||
Сканування встановлення ігнорують поширені тестові файли та каталоги, як-от `tests/`,
|
||||
`__tests__/`, `*.test.*` і `*.spec.*`, щоб не блокувати запаковані тестові mocks;
|
||||
оголошені runtime-точки входу plugin усе одно скануються, навіть якщо вони використовують одну з
|
||||
спрацьовувань вбудованого сканера небезпечного коду. Воно дозволяє встановлення
|
||||
плагінів і оновлення плагінів продовжуватися попри вбудовані знахідки `critical`, але все одно
|
||||
не обходить блокування політики плагінів `before_install` або блокування через помилку сканування.
|
||||
Сканування під час встановлення ігнорують поширені тестові файли й каталоги, як-от `tests/`,
|
||||
`__tests__/`, `*.test.*` і `*.spec.*`, щоб не блокувати запаковані тестові моки;
|
||||
оголошені вхідні точки середовища виконання плагіна все одно скануються, навіть якщо вони використовують одну з
|
||||
цих назв.
|
||||
|
||||
Цей прапорець CLI застосовується лише до потоків встановлення/оновлення plugin. Встановлення
|
||||
залежностей Skills на базі Gateway натомість використовують відповідне перевизначення запиту
|
||||
Цей прапорець CLI застосовується лише до потоків встановлення/оновлення плагінів. Встановлення
|
||||
залежностей Skills через Gateway використовують натомість відповідне перевизначення запиту
|
||||
`dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком
|
||||
завантаження/встановлення Skills із ClawHub.
|
||||
|
||||
Якщо plugin, який ви опублікували на ClawHub, приховано або заблоковано скануванням, відкрийте
|
||||
панель керування ClawHub або запустіть `clawhub package rescan <name>`, щоб попросити ClawHub
|
||||
перевірити його знову. `--dangerously-force-unsafe-install` впливає лише на встановлення на вашій
|
||||
власній машині; він не просить ClawHub повторно сканувати plugin і не робить заблокований випуск
|
||||
Якщо плагін, який ви опублікували на ClawHub, приховано або заблоковано скануванням, відкрийте
|
||||
панель ClawHub або виконайте `clawhub package rescan <name>`, щоб попросити ClawHub перевірити
|
||||
його знову. `--dangerously-force-unsafe-install` впливає лише на встановлення на вашому власному
|
||||
комп’ютері; він не просить ClawHub повторно просканувати плагін або зробити заблокований випуск
|
||||
публічним.
|
||||
|
||||
Сумісні bundles беруть участь у тому самому потоці списку/інспектування/ввімкнення/вимкнення
|
||||
plugins. Поточна підтримка runtime охоплює bundle Skills, command-skills Claude,
|
||||
типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і
|
||||
оголошені в маніфесті `lspServers`, command-skills Cursor і сумісні каталоги хуків Codex.
|
||||
Сумісні бандли беруть участь у тому самому потоці списку/інспектування/увімкнення/вимкнення
|
||||
плагінів. Поточна підтримка середовища виконання охоплює бандлові Skills, command-skills Claude,
|
||||
типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і оголошені в маніфесті
|
||||
`lspServers`, command-skills Cursor і сумісні каталоги хуків Codex.
|
||||
|
||||
`openclaw plugins inspect <id>` також повідомляє виявлені можливості bundle, а також
|
||||
підтримувані або непідтримувані записи серверів MCP і LSP для plugins на базі bundle.
|
||||
`openclaw plugins inspect <id>` також повідомляє виявлені можливості бандла, а також
|
||||
підтримувані або непідтримувані записи серверів MCP і LSP для плагінів на основі бандлів.
|
||||
|
||||
Джерела marketplace можуть бути назвою відомого marketplace Claude з
|
||||
`~/.claude/plugins/known_marketplaces.json`, локальним коренем marketplace або
|
||||
шляхом `marketplace.json`, скороченням GitHub на кшталт `owner/repo`, URL репозиторію GitHub
|
||||
або git URL. Для віддалених marketplaces записи plugins мають залишатися всередині
|
||||
клонованого репозиторію marketplace і використовувати лише відносні джерела шляхів.
|
||||
Джерела маркетплейсу можуть бути відомою Claude назвою маркетплейсу з
|
||||
`~/.claude/plugins/known_marketplaces.json`, локальним коренем маркетплейсу або шляхом до
|
||||
`marketplace.json`, скороченням GitHub на кшталт `owner/repo`, URL репозиторію GitHub
|
||||
або git URL. Для віддалених маркетплейсів записи плагінів мають залишатися всередині
|
||||
клонованого репозиторію маркетплейсу та використовувати лише відносні джерела шляхів.
|
||||
|
||||
Див. [довідник CLI `openclaw plugins`](/uk/cli/plugins) для повної інформації.
|
||||
Повні відомості дивіться в [довіднику CLI `openclaw plugins`](/uk/cli/plugins).
|
||||
|
||||
## Огляд API Plugin
|
||||
## Огляд API плагінів
|
||||
|
||||
Нативні plugins експортують об’єкт входу, який відкриває `register(api)`. Старіші
|
||||
plugins усе ще можуть використовувати `activate(api)` як застарілий alias, але нові plugins мають
|
||||
Нативні плагіни експортують об’єкт входу, який надає `register(api)`. Старіші
|
||||
плагіни все ще можуть використовувати `activate(api)` як застарілий псевдонім, але новим плагінам слід
|
||||
використовувати `register`.
|
||||
|
||||
```typescript
|
||||
@ -618,74 +612,74 @@ export default definePluginEntry({
|
||||
```
|
||||
|
||||
OpenClaw завантажує об’єкт входу та викликає `register(api)` під час
|
||||
активації plugin. Завантажувач усе ще повертається до `activate(api)` для старіших plugins,
|
||||
але комплектні plugins і нові зовнішні plugins мають вважати `register`
|
||||
публічним контрактом.
|
||||
активації плагіна. Завантажувач усе ще повертається до `activate(api)` для старіших плагінів,
|
||||
але пакетні плагіни та нові зовнішні плагіни мають розглядати `register` як
|
||||
публічний контракт.
|
||||
|
||||
`api.registrationMode` повідомляє plugin, чому його точку входу завантажують:
|
||||
`api.registrationMode` повідомляє плагіну, чому його вхід завантажується:
|
||||
|
||||
| Режим | Значення |
|
||||
| Режим | Значення |
|
||||
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `full` | Runtime-активація. Реєструйте інструменти, хуки, служби, команди, маршрути та інші активні побічні ефекти. |
|
||||
| `discovery` | Виявлення можливостей лише для читання. Реєструйте постачальників і метадані; довірений код точки входу plugin може завантажуватися, але пропускайте активні побічні ефекти. |
|
||||
| `setup-only` | Завантаження метаданих налаштування каналу через легку точку входу налаштування. |
|
||||
| `setup-runtime` | Завантаження налаштування каналу, якому також потрібна runtime-точка входу. |
|
||||
| `cli-metadata` | Лише збирання метаданих команд CLI. |
|
||||
| `full` | Активація середовища виконання. Реєструйте інструменти, хуки, служби, команди, маршрути та інші активні побічні ефекти. |
|
||||
| `discovery` | Виявлення можливостей лише для читання. Реєструйте постачальників і метадані; довірений код входу плагіна може завантажуватися, але пропускайте активні побічні ефекти. |
|
||||
| `setup-only` | Завантаження метаданих налаштування каналу через легкий вхід налаштування. |
|
||||
| `setup-runtime` | Завантаження налаштування каналу, якому також потрібен вхід середовища виконання. |
|
||||
| `cli-metadata` | Лише збирання метаданих команд CLI. |
|
||||
|
||||
Точки входу plugins, які відкривають сокети, бази даних, фонові workers або довготривалі
|
||||
clients, мають захищати ці побічні ефекти через `api.registrationMode === "full"`.
|
||||
Завантаження discovery кешуються окремо від активаційних завантажень і не замінюють
|
||||
поточний реєстр Gateway. Discovery не активує, але не є вільним від імпорту:
|
||||
OpenClaw може виконати довірену точку входу plugin або модуль channel plugin, щоб побудувати
|
||||
snapshot. Тримайте верхні рівні модулів легкими та без побічних ефектів, а мережеві
|
||||
clients, subprocesses, listeners, читання облікових даних і запуск служб перемістіть
|
||||
за шляхи full-runtime.
|
||||
Входи плагінів, які відкривають сокети, бази даних, фонові робочі процеси або довгоживучі
|
||||
клієнти, мають обмежувати ці побічні ефекти умовою `api.registrationMode === "full"`.
|
||||
Завантаження виявлення кешуються окремо від активаційних завантажень і не замінюють
|
||||
поточний реєстр Gateway. Виявлення є неактиваційним, але не без імпорту:
|
||||
OpenClaw може виконати довірений вхід плагіна або модуль плагіна каналу, щоб побудувати
|
||||
знімок. Тримайте верхні рівні модулів легкими та без побічних ефектів, а
|
||||
мережеві клієнти, підпроцеси, слухачі, читання облікових даних і запуск служб
|
||||
переносьте за шляхи повного середовища виконання.
|
||||
|
||||
Поширені методи реєстрації:
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| --------------------------------------- | --------------------------- |
|
||||
| `registerProvider` | Постачальник моделей (LLM) |
|
||||
| `registerChannel` | Канал чату |
|
||||
| `registerTool` | Інструмент агента |
|
||||
| `registerHook` / `on(...)` | Хуки життєвого циклу |
|
||||
| `registerSpeechProvider` | Text-to-speech / STT |
|
||||
| `registerRealtimeTranscriptionProvider` | Streaming STT |
|
||||
| `registerRealtimeVoiceProvider` | Duplex realtime voice |
|
||||
| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо |
|
||||
| `registerImageGenerationProvider` | Генерація зображень |
|
||||
| `registerMusicGenerationProvider` | Генерація музики |
|
||||
| `registerVideoGenerationProvider` | Генерація відео |
|
||||
| `registerWebFetchProvider` | Постачальник web fetch / scrape |
|
||||
| `registerWebSearchProvider` | Вебпошук |
|
||||
| `registerHttpRoute` | HTTP endpoint |
|
||||
| `registerCommand` / `registerCli` | Команди CLI |
|
||||
| `registerContextEngine` | Context engine |
|
||||
| `registerService` | Фонова служба |
|
||||
| Метод | Що він реєструє |
|
||||
| --------------------------------------- | --------------------------------------- |
|
||||
| `registerProvider` | Постачальник моделей (LLM) |
|
||||
| `registerChannel` | Канал чату |
|
||||
| `registerTool` | Інструмент агента |
|
||||
| `registerHook` / `on(...)` | Хуки життєвого циклу |
|
||||
| `registerSpeechProvider` | Перетворення тексту на мовлення / STT |
|
||||
| `registerRealtimeTranscriptionProvider` | Потоковий STT |
|
||||
| `registerRealtimeVoiceProvider` | Дуплексний голос у реальному часі |
|
||||
| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо |
|
||||
| `registerImageGenerationProvider` | Генерація зображень |
|
||||
| `registerMusicGenerationProvider` | Генерація музики |
|
||||
| `registerVideoGenerationProvider` | Генерація відео |
|
||||
| `registerWebFetchProvider` | Постачальник веботримання / скрейпінгу |
|
||||
| `registerWebSearchProvider` | Вебпошук |
|
||||
| `registerHttpRoute` | HTTP кінцева точка |
|
||||
| `registerCommand` / `registerCli` | Команди CLI |
|
||||
| `registerContextEngine` | Рушій контексту |
|
||||
| `registerService` | Фонова служба |
|
||||
|
||||
Поведінка guard для типізованих хуків життєвого циклу:
|
||||
Поведінка захисту хуків для типізованих хуків життєвого циклу:
|
||||
|
||||
- `before_tool_call`: `{ block: true }` є кінцевим; handlers із нижчим пріоритетом пропускаються.
|
||||
- `before_tool_call`: `{ block: false }` не виконує дії й не очищує попередній block.
|
||||
- `before_install`: `{ block: true }` є кінцевим; handlers із нижчим пріоритетом пропускаються.
|
||||
- `before_install`: `{ block: false }` не виконує дії й не очищує попередній block.
|
||||
- `message_sending`: `{ cancel: true }` є кінцевим; handlers із нижчим пріоритетом пропускаються.
|
||||
- `message_sending`: `{ cancel: false }` не виконує дії й не очищує попередній cancel.
|
||||
- `before_tool_call`: `{ block: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_tool_call`: `{ block: false }` є no-op і не очищує попереднє блокування.
|
||||
- `before_install`: `{ block: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_install`: `{ block: false }` є no-op і не очищує попереднє блокування.
|
||||
- `message_sending`: `{ cancel: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються.
|
||||
- `message_sending`: `{ cancel: false }` є no-op і не очищує попереднє скасування.
|
||||
|
||||
Нативний app-server Codex проводить події нативних інструментів Codex назад у цю
|
||||
поверхню хуків. Plugins можуть блокувати нативні інструменти Codex через `before_tool_call`,
|
||||
Нативний app-server Codex мостить нативні події інструментів Codex назад у цю
|
||||
поверхню хуків. Плагіни можуть блокувати нативні інструменти Codex через `before_tool_call`,
|
||||
спостерігати результати через `after_tool_call` і брати участь у схваленнях Codex
|
||||
`PermissionRequest`. Bridge ще не переписує аргументи нативних інструментів Codex.
|
||||
Точна межа підтримки runtime Codex описана в
|
||||
`PermissionRequest`. Міст поки що не переписує аргументи нативних інструментів Codex.
|
||||
Точна межа підтримки середовища виконання Codex описана в
|
||||
[контракті підтримки Codex harness v1](/uk/plugins/codex-harness#v1-support-contract).
|
||||
|
||||
Повну поведінку типізованих хуків див. в [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics).
|
||||
Повну поведінку типізованих хуків дивіться в [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics).
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Створення plugins](/uk/plugins/building-plugins) — створіть власний plugin
|
||||
- [Plugin bundles](/uk/plugins/bundles) — сумісність bundles Codex/Claude/Cursor
|
||||
- [Маніфест Plugin](/uk/plugins/manifest) — схема маніфесту
|
||||
- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додайте інструменти агента в plugin
|
||||
- [Внутрішня архітектура Plugin](/uk/plugins/architecture) — модель можливостей і pipeline завантаження
|
||||
- [Спільнотні 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