chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
8caebe48bf
commit
0c32bc07a6
File diff suppressed because it is too large
Load Diff
@ -1,26 +1,26 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете змінити типові моделі або переглянути стан auth провайдера
|
||||
- Ви хочете просканувати доступні моделі/провайдерів і налагодити профілі auth провайдера
|
||||
summary: Довідка CLI для `openclaw models` (status/list/set/scan, псевдоніми, резервні варіанти, auth)
|
||||
- Ви хочете змінити моделі за замовчуванням або переглянути статус автентифікації провайдера
|
||||
- Ви хочете просканувати доступні моделі/провайдерів і налагодити профілі автентифікації
|
||||
summary: Довідка CLI для `openclaw models` (status/list/set/scan, псевдоніми, резервні варіанти, автентифікація)
|
||||
title: моделі
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T06:18:27Z"
|
||||
generated_at: "2026-04-23T06:24:09Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 5b057688266bcb72fc9719837ae6a026bed9849ff04577949467363d83b6d069
|
||||
source_hash: 3bf7b864ff57af0649bc31443ce77b193d6b3dbb200c53b69ea584fa2e12cbf7
|
||||
source_path: cli/models.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# `openclaw models`
|
||||
|
||||
Виявлення, сканування та налаштування моделей (типова модель, резервні варіанти, профілі auth).
|
||||
Виявлення моделей, сканування та конфігурація (модель за замовчуванням, резервні варіанти, профілі автентифікації).
|
||||
|
||||
Пов’язано:
|
||||
Пов’язане:
|
||||
|
||||
- Провайдери + моделі: [Моделі](/uk/providers/models)
|
||||
- Налаштування auth провайдера: [Початок роботи](/uk/start/getting-started)
|
||||
- Налаштування автентифікації провайдера: [Початок роботи](/uk/start/getting-started)
|
||||
|
||||
## Поширені команди
|
||||
|
||||
@ -31,36 +31,39 @@ openclaw models set <model-or-alias>
|
||||
openclaw models scan
|
||||
```
|
||||
|
||||
`openclaw models status` показує визначені типові/резервні варіанти разом з оглядом auth.
|
||||
Коли доступні знімки використання провайдера, розділ стану OAuth/API key також містить
|
||||
`openclaw models status` показує визначені модель за замовчуванням/резервні варіанти, а також огляд автентифікації.
|
||||
Коли доступні знімки використання провайдера, розділ статусу OAuth/API-ключів містить
|
||||
вікна використання провайдера та знімки квот.
|
||||
Поточні провайдери з вікнами використання: Anthropic, GitHub Copilot, Gemini CLI, OpenAI
|
||||
Codex, MiniMax, Xiaomi і z.ai. Auth використання надходить із хуків,
|
||||
специфічних для провайдера, коли вони доступні; інакше OpenClaw повертається до зіставлення
|
||||
облікових даних OAuth/API key з профілів auth, env або config.
|
||||
У виводі `--json` `auth.providers` — це огляд провайдера з урахуванням
|
||||
env/config/store, тоді як `auth.oauth` — це лише стан профілів сховища auth.
|
||||
Додайте `--probe`, щоб виконати живі перевірки auth для кожного налаштованого профілю провайдера.
|
||||
Перевірки є реальними запитами (можуть витрачати токени й спричиняти обмеження частоти).
|
||||
Використовуйте `--agent <id>`, щоб перевірити стан моделі/auth для налаштованого агента. Якщо параметр не вказано,
|
||||
Codex, MiniMax, Xiaomi і z.ai. Дані автентифікації використання надходять із
|
||||
специфічних для провайдера хуків, коли вони доступні; інакше OpenClaw використовує резервний варіант і зіставляє облікові дані OAuth/API-ключів
|
||||
із профілів автентифікації, env або config.
|
||||
У виводі `--json` `auth.providers` — це огляд провайдерів
|
||||
з урахуванням env/config/store, а `auth.oauth` — лише стан профілів зі сховища автентифікації.
|
||||
Додайте `--probe`, щоб виконати живі перевірки автентифікації для кожного налаштованого профілю провайдера.
|
||||
Перевірки — це реальні запити (можуть споживати токени та спричиняти обмеження швидкості).
|
||||
Використовуйте `--agent <id>`, щоб переглянути стан моделі/автентифікації налаштованого агента. Якщо не вказано,
|
||||
команда використовує `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`, якщо їх задано, інакше —
|
||||
типовий налаштований агент.
|
||||
Рядки перевірок можуть походити з профілів auth, облікових даних env або `models.json`.
|
||||
налаштованого агента за замовчуванням.
|
||||
Рядки перевірок можуть походити з профілів автентифікації, облікових даних env або `models.json`.
|
||||
|
||||
Примітки:
|
||||
|
||||
- `models set <model-or-alias>` приймає `provider/model` або псевдонім.
|
||||
- `models list --all` включає рядки статичного каталогу, які належать bundled-провайдерам,
|
||||
навіть якщо ви ще не пройшли автентифікацію в цього провайдера. Такі рядки все одно
|
||||
показуються як недоступні, доки не буде налаштовано відповідний auth.
|
||||
- Посилання на моделі аналізуються розділенням за **першим** символом `/`. Якщо ID моделі містить `/` (у стилі OpenRouter), додайте префікс провайдера (приклад: `openrouter/moonshotai/kimi-k2`).
|
||||
- Якщо ви не вказали провайдера, OpenClaw спочатку визначає введення як псевдонім, потім —
|
||||
як унікальний збіг налаштованого провайдера для цього точного id моделі, і лише після цього
|
||||
повертається до типового налаштованого провайдера з попередженням про застарілість.
|
||||
Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw
|
||||
повертається до першого налаштованого провайдера/моделі замість показу
|
||||
застарілого типового значення для видаленого провайдера.
|
||||
- `models status` може показувати `marker(<value>)` у виводі auth для незасекречених заповнювачів (наприклад `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) замість маскування їх як секретів.
|
||||
- `models list --all` включає статичні рядки каталогу вбудованих провайдерів навіть
|
||||
якщо ви ще не пройшли автентифікацію в цього провайдера. Такі рядки все одно
|
||||
відображаються як недоступні, доки не буде налаштовано відповідну автентифікацію.
|
||||
- `models list --provider <id>` фільтрує за id провайдера, наприклад `moonshot` або
|
||||
`openai-codex`. Він не приймає відображувані мітки з інтерактивних
|
||||
засобів вибору провайдера, наприклад `Moonshot AI`.
|
||||
- Посилання на моделі розбираються шляхом поділу за **першим** `/`. Якщо ID моделі містить `/` (у стилі OpenRouter), додайте префікс провайдера (приклад: `openrouter/moonshotai/kimi-k2`).
|
||||
- Якщо ви не вкажете провайдера, OpenClaw спочатку визначить введення як псевдонім, потім —
|
||||
як унікальний збіг серед налаштованих провайдерів для цього точного id моделі, і лише після цього
|
||||
використає резервний варіант із налаштованим провайдером за замовчуванням із попередженням про застарілість.
|
||||
Якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw
|
||||
використовує резервний варіант і переходить до першої налаштованої пари провайдер/модель, замість того щоб показувати
|
||||
застаріле значення за замовчуванням для видаленого провайдера.
|
||||
- `models status` може показувати `marker(<value>)` у виводі автентифікації для незасекречених заповнювачів (наприклад `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) замість маскування їх як секретів.
|
||||
|
||||
### `models status`
|
||||
|
||||
@ -69,15 +72,15 @@ env/config/store, тоді як `auth.oauth` — це лише стан проф
|
||||
- `--json`
|
||||
- `--plain`
|
||||
- `--check` (код виходу 1=прострочено/відсутнє, 2=скоро спливає)
|
||||
- `--probe` (жива перевірка налаштованих профілів auth)
|
||||
- `--probe` (жива перевірка налаштованих профілів автентифікації)
|
||||
- `--probe-provider <name>` (перевірити один провайдер)
|
||||
- `--probe-profile <id>` (повторювані або перелічені через кому id профілів)
|
||||
- `--probe-profile <id>` (повторювані або id профілів, розділені комами)
|
||||
- `--probe-timeout <ms>`
|
||||
- `--probe-concurrency <n>`
|
||||
- `--probe-max-tokens <n>`
|
||||
- `--agent <id>` (id налаштованого агента; перевизначає `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`)
|
||||
|
||||
Категорії станів перевірок:
|
||||
Категорії статусу перевірок:
|
||||
|
||||
- `ok`
|
||||
- `auth`
|
||||
@ -90,13 +93,13 @@ env/config/store, тоді як `auth.oauth` — це лише стан проф
|
||||
|
||||
Варіанти detail/reason-code перевірок, яких варто очікувати:
|
||||
|
||||
- `excluded_by_auth_order`: збережений профіль існує, але явний
|
||||
`auth.order.<provider>` його пропустив, тому перевірка повідомляє про виключення замість
|
||||
спроби використання.
|
||||
- `excluded_by_auth_order`: збережений профіль існує, але явне
|
||||
`auth.order.<provider>` його пропустило, тому перевірка повідомляє про виключення, а не
|
||||
намагається його використати.
|
||||
- `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`:
|
||||
профіль наявний, але не є придатним/визначуваним.
|
||||
- `no_model`: auth провайдера існує, але OpenClaw не зміг визначити придатний
|
||||
кандидат моделі для перевірки для цього провайдера.
|
||||
профіль наявний, але не придатний/не може бути визначений.
|
||||
- `no_model`: автентифікація провайдера існує, але OpenClaw не зміг визначити
|
||||
придатний для перевірки кандидат моделі для цього провайдера.
|
||||
|
||||
## Псевдоніми + резервні варіанти
|
||||
|
||||
@ -105,7 +108,7 @@ openclaw models aliases list
|
||||
openclaw models fallbacks list
|
||||
```
|
||||
|
||||
## Профілі auth
|
||||
## Профілі автентифікації
|
||||
|
||||
```bash
|
||||
openclaw models auth add
|
||||
@ -114,11 +117,11 @@ openclaw models auth setup-token --provider <id>
|
||||
openclaw models auth paste-token
|
||||
```
|
||||
|
||||
`models auth add` — це інтерактивний помічник auth. Він може запускати потік auth провайдера
|
||||
`models auth add` — це інтерактивний помічник автентифікації. Він може запускати потік автентифікації провайдера
|
||||
(OAuth/API key) або провести вас через ручне вставлення токена, залежно від
|
||||
обраного провайдера.
|
||||
|
||||
`models auth login` запускає потік auth plugin провайдера (OAuth/API key). Використовуйте
|
||||
`models auth login` запускає потік автентифікації Plugin провайдера (OAuth/API key). Використовуйте
|
||||
`openclaw plugins list`, щоб побачити, які провайдери встановлено.
|
||||
|
||||
Приклади:
|
||||
@ -129,15 +132,15 @@ openclaw models auth login --provider openai-codex --set-default
|
||||
|
||||
Примітки:
|
||||
|
||||
- `setup-token` і `paste-token` залишаються загальними командами для токенів для провайдерів,
|
||||
які надають методи auth через токен.
|
||||
- `setup-token` потребує інтерактивного TTY і запускає метод токен-auth провайдера
|
||||
(типово — метод `setup-token` цього провайдера, якщо він його надає).
|
||||
- `paste-token` приймає рядок токена, створений деінде або автоматизацією.
|
||||
- `setup-token` і `paste-token` залишаються універсальними командами для роботи з токенами для провайдерів,
|
||||
які надають методи автентифікації токеном.
|
||||
- `setup-token` вимагає інтерактивний TTY і запускає метод токен-автентифікації провайдера
|
||||
(типово використовуючи метод `setup-token` цього провайдера, якщо він його надає).
|
||||
- `paste-token` приймає рядок токена, згенерований деінде або автоматизацією.
|
||||
- `paste-token` вимагає `--provider`, запитує значення токена та записує
|
||||
його до типового id профілю `<provider>:manual`, якщо ви не передали
|
||||
його в id профілю за замовчуванням `<provider>:manual`, якщо ви не передасте
|
||||
`--profile-id`.
|
||||
- `paste-token --expires-in <duration>` зберігає абсолютний час завершення дії токена з
|
||||
- `paste-token --expires-in <duration>` зберігає абсолютний час спливу токена на основі
|
||||
відносної тривалості, наприклад `365d` або `12h`.
|
||||
- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає повторне використання Claude CLI та використання `claude -p` дозволеними для цієї інтеграції, якщо Anthropic не опублікує нову політику.
|
||||
- `setup-token` / `paste-token` для Anthropic залишаються доступними як підтримуваний шлях токена OpenClaw, але тепер OpenClaw віддає перевагу повторному використанню Claude CLI і `claude -p`, коли це можливо.
|
||||
- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тож OpenClaw вважає повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику.
|
||||
- `setup-token` / `paste-token` для Anthropic залишаються доступними як підтримуваний шлях токенів OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, коли вони доступні.
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- Додавання або змінення CLI моделей (models list/set/scan/aliases/fallbacks)
|
||||
- Зміна поведінки резервних варіантів моделі або UX вибору
|
||||
- Зміна поведінки резервного вибору моделі або UX вибору
|
||||
- Оновлення перевірок сканування моделей (інструменти/зображення)
|
||||
summary: 'CLI моделей: список, встановлення, псевдоніми, резервні варіанти, сканування, стан'
|
||||
summary: 'CLI моделей: list, set, aliases, fallbacks, scan, status'
|
||||
title: CLI моделей
|
||||
x-i18n:
|
||||
generated_at: "2026-04-22T22:25:43Z"
|
||||
generated_at: "2026-04-23T06:24:12Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 18d915f3f761aaff5efc3bf752f5abddeb625e1a386ab3d701f46fd92244f20e
|
||||
source_hash: 46916d9600a4e4aebdb026aa42df39149d8b6d438a8a7e85a61053dfc8f76dcc
|
||||
source_path: concepts/models.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -24,34 +24,34 @@ x-i18n:
|
||||
OpenClaw вибирає моделі в такому порядку:
|
||||
|
||||
1. **Основна** модель (`agents.defaults.model.primary` або `agents.defaults.model`).
|
||||
2. **Резервні варіанти** в `agents.defaults.model.fallbacks` (по порядку).
|
||||
2. **Резервні варіанти** в `agents.defaults.model.fallbacks` (за порядком).
|
||||
3. **Резервне перемикання автентифікації провайдера** відбувається всередині провайдера перед переходом до наступної моделі.
|
||||
|
||||
Пов’язане:
|
||||
|
||||
- `agents.defaults.models` — це allowlist/каталог моделей, які OpenClaw може використовувати (разом із псевдонімами).
|
||||
- `agents.defaults.models` — це allowlist/каталог моделей, які OpenClaw може використовувати (разом з псевдонімами).
|
||||
- `agents.defaults.imageModel` використовується **лише тоді**, коли основна модель не може приймати зображення.
|
||||
- `agents.defaults.pdfModel` використовується інструментом `pdf`. Якщо його не вказано, інструмент повертається до `agents.defaults.imageModel`, а потім до визначеної моделі сесії/моделі за замовчуванням.
|
||||
- `agents.defaults.imageGenerationModel` використовується спільною можливістю генерації зображень. Якщо його не вказано, `image_generate` усе одно може визначити значення за замовчуванням провайдера з автентифікацією. Спочатку він пробує поточного провайдера за замовчуванням, а потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id. Якщо ви вказуєте конкретний provider/model, також налаштуйте автентифікацію/API key цього провайдера.
|
||||
- `agents.defaults.musicGenerationModel` використовується спільною можливістю генерації музики. Якщо його не вказано, `music_generate` усе одно може визначити значення за замовчуванням провайдера з автентифікацією. Спочатку він пробує поточного провайдера за замовчуванням, а потім решту зареєстрованих провайдерів генерації музики у порядку provider-id. Якщо ви вказуєте конкретний provider/model, також налаштуйте автентифікацію/API key цього провайдера.
|
||||
- `agents.defaults.videoGenerationModel` використовується спільною можливістю генерації відео. Якщо його не вказано, `video_generate` усе одно може визначити значення за замовчуванням провайдера з автентифікацією. Спочатку він пробує поточного провайдера за замовчуванням, а потім решту зареєстрованих провайдерів генерації відео у порядку provider-id. Якщо ви вказуєте конкретний provider/model, також налаштуйте автентифікацію/API key цього провайдера.
|
||||
- Значення за замовчуванням для окремого агента можуть перевизначати `agents.defaults.model` через `agents.list[].model` разом із прив’язками (див. [/concepts/multi-agent](/uk/concepts/multi-agent)).
|
||||
- `agents.defaults.pdfModel` використовується інструментом `pdf`. Якщо його не вказано, інструмент переходить до `agents.defaults.imageModel`, а потім до визначеної для сесії/типової моделі.
|
||||
- `agents.defaults.imageGenerationModel` використовується спільною можливістю генерації зображень. Якщо його не вказано, `image_generate` все одно може визначити типовий провайдер з автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів. Якщо ви вказуєте конкретний провайдер/модель, також налаштуйте автентифікацію/API key цього провайдера.
|
||||
- `agents.defaults.musicGenerationModel` використовується спільною можливістю генерації музики. Якщо його не вказано, `music_generate` все одно може визначити типовий провайдер з автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації музики в порядку ідентифікаторів провайдерів. Якщо ви вказуєте конкретний провайдер/модель, також налаштуйте автентифікацію/API key цього провайдера.
|
||||
- `agents.defaults.videoGenerationModel` використовується спільною можливістю генерації відео. Якщо його не вказано, `video_generate` все одно може визначити типовий провайдер з автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації відео в порядку ідентифікаторів провайдерів. Якщо ви вказуєте конкретний провайдер/модель, також налаштуйте автентифікацію/API key цього провайдера.
|
||||
- Типові значення для окремого агента можуть перевизначати `agents.defaults.model` через `agents.list[].model` разом із прив’язками (див. [/concepts/multi-agent](/uk/concepts/multi-agent)).
|
||||
|
||||
## Швидка політика моделей
|
||||
|
||||
- Встановіть основною найсильнішу модель останнього покоління, яка вам доступна.
|
||||
- Використовуйте резервні варіанти для чутливих до вартості/затримки завдань і менш критичного чату.
|
||||
- Використовуйте резервні варіанти для завдань, чутливих до вартості/затримки, і для менш критичного чату.
|
||||
- Для агентів з увімкненими інструментами або недовірених вхідних даних уникайте старіших/слабших рівнів моделей.
|
||||
|
||||
## Початкове налаштування (рекомендовано)
|
||||
## Онбординг (рекомендовано)
|
||||
|
||||
Якщо ви не хочете вручну редагувати конфігурацію, запустіть початкове налаштування:
|
||||
Якщо ви не хочете вручну редагувати конфігурацію, запустіть онбординг:
|
||||
|
||||
```bash
|
||||
openclaw onboard
|
||||
```
|
||||
|
||||
Воно може налаштувати модель + автентифікацію для поширених провайдерів, включно з підпискою **OpenAI Code (Codex)** (OAuth) і **Anthropic** (API key або Claude CLI).
|
||||
Він може налаштувати модель + автентифікацію для поширених провайдерів, зокрема **OpenAI Code (Codex) subscription** (OAuth) і **Anthropic** (API key або Claude CLI).
|
||||
|
||||
## Ключі конфігурації (огляд)
|
||||
|
||||
@ -63,36 +63,36 @@ openclaw onboard
|
||||
- `agents.defaults.models` (allowlist + псевдоніми + параметри провайдера)
|
||||
- `models.providers` (власні провайдери, записані в `models.json`)
|
||||
|
||||
Посилання на моделі нормалізуються до нижнього регістру. Псевдоніми провайдерів, такі як `z.ai/*`, нормалізуються до `zai/*`.
|
||||
Посилання на моделі нормалізуються до нижнього регістру. Псевдоніми провайдерів, як-от `z.ai/*`, нормалізуються до `zai/*`.
|
||||
|
||||
Приклади конфігурації провайдерів (включно з OpenCode) наведено в
|
||||
Приклади конфігурації провайдерів (зокрема OpenCode) наведено в
|
||||
[/providers/opencode](/uk/providers/opencode).
|
||||
|
||||
### Безпечне редагування allowlist
|
||||
|
||||
Використовуйте додаткові записи під час ручного оновлення `agents.defaults.models`:
|
||||
Використовуйте адитивний запис під час ручного оновлення `agents.defaults.models`:
|
||||
|
||||
```bash
|
||||
openclaw config set agents.defaults.models '{"openai-codex/gpt-5.4":{}}' --strict-json --merge
|
||||
```
|
||||
|
||||
`openclaw config set` захищає мапи моделей/провайдерів від випадкового перезапису. Просте присвоєння об’єкта для `agents.defaults.models`, `models.providers` або `models.providers.<id>.models` відхиляється, якщо воно видалить наявні записи. Використовуйте `--merge` для додаткових змін; використовуйте `--replace` лише тоді, коли передане значення має стати повним цільовим значенням.
|
||||
`openclaw config set` захищає мапи моделей/провайдерів від випадкового перезапису. Звичайне присвоєння об’єкта для `agents.defaults.models`, `models.providers` або `models.providers.<id>.models` відхиляється, якщо воно призведе до видалення наявних записів. Використовуйте `--merge` для адитивних змін; використовуйте `--replace` лише тоді, коли надане значення має стати повним цільовим значенням.
|
||||
|
||||
Інтерактивне налаштування провайдера та `openclaw configure --section model` також об’єднують вибрані значення в межах провайдера з наявним allowlist, тому додавання Codex, Ollama або іншого провайдера не видаляє не пов’язані записи моделей.
|
||||
Інтерактивне налаштування провайдера та `openclaw configure --section model` також зливають вибрані значення на рівні провайдера в наявний allowlist, тому додавання Codex, Ollama або іншого провайдера не видаляє не пов’язані записи моделей.
|
||||
|
||||
## "Model is not allowed" (і чому відповіді зупиняються)
|
||||
## «Model is not allowed» (і чому відповіді зупиняються)
|
||||
|
||||
Якщо встановлено `agents.defaults.models`, він стає **allowlist** для `/model` і для перевизначень сесії. Коли користувач вибирає модель, якої немає в цьому allowlist, OpenClaw повертає:
|
||||
Якщо задано `agents.defaults.models`, воно стає **allowlist** для `/model` і для перевизначень сесії. Коли користувач вибирає модель, якої немає в цьому allowlist, OpenClaw повертає:
|
||||
|
||||
```
|
||||
Model "provider/model" is not allowed. Use /model to list available models.
|
||||
```
|
||||
|
||||
Це відбувається **до** створення звичайної відповіді, тому може здаватися, що повідомлення «не отримало відповіді». Виправити це можна так:
|
||||
Це відбувається **до** формування звичайної відповіді, тому може здаватися, що повідомлення «не отримало відповіді». Виправити це можна так:
|
||||
|
||||
- Додати модель до `agents.defaults.models`, або
|
||||
- Очистити allowlist (видалити `agents.defaults.models`), або
|
||||
- Вибрати модель із `/model list`.
|
||||
- Вибрати модель з `/model list`.
|
||||
|
||||
Приклад конфігурації allowlist:
|
||||
|
||||
@ -122,26 +122,28 @@ Model "provider/model" is not allowed. Use /model to list available models.
|
||||
|
||||
Примітки:
|
||||
|
||||
- `/model` (і `/model list`) — це компактний нумерований засіб вибору (сімейство моделей + доступні провайдери).
|
||||
- У Discord `/model` і `/models` відкривають інтерактивний засіб вибору з випадними списками провайдера й моделі та кроком Submit.
|
||||
- `/models add` доступна за замовчуванням і може бути вимкнена через `commands.modelsWrite=false`.
|
||||
- Якщо команду увімкнено, `/models add <provider> <modelId>` — найшвидший шлях; проста `/models add` запускає покроковий потік із вибором провайдера спочатку, де це підтримується.
|
||||
- `/model` (і `/model list`) — це компактний нумерований вибір (сімейство моделей + доступні провайдери).
|
||||
- У Discord `/model` і `/models` відкривають інтерактивний вибір із випадними списками провайдера та моделі, а також кроком Submit.
|
||||
- `/models add` доступна типово і може бути вимкнена через `commands.modelsWrite=false`.
|
||||
- Якщо її ввімкнено, `/models add <provider> <modelId>` — це найшвидший шлях; проста команда `/models add` запускає керований сценарій «спочатку провайдер», де це підтримується.
|
||||
- Після `/models add` нова модель стає доступною в `/models` і `/model` без перезапуску Gateway.
|
||||
- `/model <#>` вибирає зі списку цього засобу вибору.
|
||||
- `/model` одразу зберігає новий вибір сесії.
|
||||
- `/model <#>` вибирає зі списку цього вибору.
|
||||
- `/model` негайно зберігає новий вибір сесії.
|
||||
- Якщо агент неактивний, наступний запуск одразу використовує нову модель.
|
||||
- Якщо запуск уже активний, OpenClaw позначає перемикання наживо як очікуване та перезапускає на нову модель лише в чистій точці повторної спроби.
|
||||
- Якщо активність інструментів або виведення відповіді вже почалися, очікуване перемикання може залишатися в черзі до пізнішої можливості повторної спроби або наступного ходу користувача.
|
||||
- Якщо запуск уже активний, OpenClaw позначає живе перемикання як відкладене й перезапускає нову модель лише в чистій точці повторної спроби.
|
||||
- Якщо активність інструментів або виведення відповіді вже почалися, відкладене перемикання може залишатися в черзі до наступної можливості повторної спроби або до наступного ходу користувача.
|
||||
- `/model status` — це докладний перегляд (кандидати автентифікації та, якщо налаштовано, `baseUrl` кінцевої точки провайдера + режим `api`).
|
||||
- Посилання на моделі розбираються шляхом поділу за **першим** `/`. Використовуйте `provider/model`, коли вводите `/model <ref>`.
|
||||
- Якщо сам model id містить `/` (у стилі OpenRouter), ви маєте вказати префікс провайдера (приклад: `/model openrouter/moonshotai/kimi-k2`).
|
||||
- Якщо ви не вказуєте провайдера, OpenClaw визначає введення в такому порядку:
|
||||
- Посилання на моделі розбираються поділом за **першим** `/`. Під час введення `/model <ref>` використовуйте `provider/model`.
|
||||
- Якщо сам ідентифікатор моделі містить `/` (у стилі OpenRouter), ви маєте вказати префікс провайдера (приклад: `/model openrouter/moonshotai/kimi-k2`).
|
||||
- Якщо ви пропускаєте провайдера, OpenClaw визначає введення в такому порядку:
|
||||
1. збіг псевдоніма
|
||||
2. унікальний збіг налаштованого провайдера для цього точного model id без префікса
|
||||
3. застарілий резервний перехід до налаштованого провайдера за замовчуванням
|
||||
Якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw замість цього переходить до першого налаштованого provider/model, щоб уникнути показу застарілого значення за замовчуванням від видаленого провайдера.
|
||||
2. збіг єдиного налаштованого провайдера для цього точного ідентифікатора моделі без префікса
|
||||
3. застарілий резервний перехід до налаштованого типового провайдера
|
||||
Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw
|
||||
натомість переходить до першого налаштованого провайдера/моделі, щоб уникнути
|
||||
показу застарілого типового значення видаленого провайдера.
|
||||
|
||||
Повна поведінка/конфігурація команди: [Slash commands](/uk/tools/slash-commands).
|
||||
Повна поведінка команд/конфігурація: [Slash commands](/uk/tools/slash-commands).
|
||||
|
||||
Приклади:
|
||||
|
||||
@ -178,26 +180,29 @@ openclaw models image-fallbacks clear
|
||||
|
||||
### `models list`
|
||||
|
||||
За замовчуванням показує налаштовані моделі. Корисні прапорці:
|
||||
Типово показує налаштовані моделі. Корисні прапорці:
|
||||
|
||||
- `--all`: повний каталог
|
||||
- `--local`: лише локальні провайдери
|
||||
- `--provider <name>`: фільтр за провайдером
|
||||
- `--provider <id>`: фільтрація за ідентифікатором провайдера, наприклад `moonshot`; мітки відображення з інтерактивних виборів не приймаються
|
||||
- `--plain`: одна модель на рядок
|
||||
- `--json`: машиночитний вивід
|
||||
|
||||
`--all` включає рядки статичного каталогу вбудованих провайдерів ще до налаштування автентифікації, тому перегляди лише для виявлення можуть показувати моделі, які недоступні, доки ви не додасте відповідні облікові дані провайдера.
|
||||
`--all` включає рядки статичного каталогу від вбудованих провайдерів ще до налаштування автентифікації, тому в режимах лише для виявлення можуть відображатися моделі, недоступні до додавання відповідних облікових даних провайдера.
|
||||
|
||||
### `models status`
|
||||
|
||||
Показує визначену основну модель, резервні варіанти, модель зображень і огляд автентифікації налаштованих провайдерів. Також відображає стан завершення дії OAuth для профілів, знайдених у сховищі автентифікації (типово попереджає в межах 24 год). `--plain` виводить лише визначену основну модель.
|
||||
Стан OAuth показується завжди (і включається у вивід `--json`). Якщо налаштований провайдер не має облікових даних, `models status` виводить розділ **Missing auth**.
|
||||
JSON включає `auth.oauth` (вікно попередження + профілі) і `auth.providers` (ефективна автентифікація для кожного провайдера, включно з обліковими даними з env). `auth.oauth` — це лише стан профілів зі сховища автентифікації; провайдери лише з env там не відображаються.
|
||||
Використовуйте `--check` для автоматизації (код виходу `1`, якщо відсутні/прострочені, `2`, якщо скоро завершаться).
|
||||
Використовуйте `--probe` для живих перевірок автентифікації; рядки перевірок можуть походити з профілів автентифікації, облікових даних env або `models.json`.
|
||||
Якщо явний `auth.order.<provider>` пропускає збережений профіль, перевірка повертає `excluded_by_auth_order` замість спроби його використати. Якщо автентифікація є, але для цього провайдера не вдається визначити модель, придатну для probe, перевірка повертає `status: no_model`.
|
||||
Показує визначену основну модель, резервні варіанти, модель зображень і огляд автентифікації налаштованих провайдерів. Також показує стан завершення строку дії OAuth для профілів, знайдених у сховищі автентифікації (типово попереджає в межах 24 год). `--plain` виводить лише визначену основну модель.
|
||||
Стан OAuth завжди показується (і включається у вивід `--json`). Якщо для налаштованого провайдера немає облікових даних, `models status` виводить розділ **Missing auth**.
|
||||
JSON містить `auth.oauth` (вікно попередження + профілі) і `auth.providers`
|
||||
(ефективна автентифікація для кожного провайдера, зокрема облікові дані з env). `auth.oauth`
|
||||
— це лише стан профілів у сховищі автентифікації; провайдери лише з env там не з’являються.
|
||||
Використовуйте `--check` для автоматизації (код виходу `1` для відсутніх/прострочених, `2` для тих, що скоро завершаться).
|
||||
Використовуйте `--probe` для живих перевірок автентифікації; рядки перевірки можуть надходити з профілів автентифікації, облікових даних env або `models.json`.
|
||||
Якщо явний `auth.order.<provider>` пропускає збережений профіль, перевірка повідомляє
|
||||
`excluded_by_auth_order` замість спроби його використати. Якщо автентифікація є, але для цього провайдера не вдається визначити модель, придатну для перевірки, перевірка повідомляє `status: no_model`.
|
||||
|
||||
Вибір автентифікації залежить від провайдера/облікового запису. Для хостів Gateway, які працюють постійно, API key зазвичай найпередбачуваніші; також підтримується повторне використання Claude CLI та наявних профілів OAuth/token Anthropic.
|
||||
Вибір автентифікації залежить від провайдера/облікового запису. Для постійно ввімкнених хостів Gateway API key зазвичай є найпередбачуванішими; також підтримується повторне використання Claude CLI та наявні профілі OAuth/token Anthropic.
|
||||
|
||||
Приклад (Claude CLI):
|
||||
|
||||
@ -208,57 +213,62 @@ openclaw models status
|
||||
|
||||
## Сканування (безкоштовні моделі OpenRouter)
|
||||
|
||||
`openclaw models scan` перевіряє **каталог безкоштовних моделей** OpenRouter і за потреби може виконувати probe моделей на підтримку інструментів і зображень.
|
||||
`openclaw models scan` перевіряє **каталог безкоштовних моделей** OpenRouter і може
|
||||
за потреби виконувати перевірку моделей на підтримку інструментів і зображень.
|
||||
|
||||
Основні прапорці:
|
||||
|
||||
- `--no-probe`: пропустити живі probe (лише метадані)
|
||||
- `--min-params <b>`: мінімальний розмір параметрів (у мільярдах)
|
||||
- `--max-age-days <days>`: пропустити старіші моделі
|
||||
- `--provider <name>`: фільтр префікса провайдера
|
||||
- `--no-probe`: пропустити живі перевірки (лише метадані)
|
||||
- `--min-params <b>`: мінімальний розмір параметрів (мільярди)
|
||||
- `--max-age-days <days>`: пропускати старіші моделі
|
||||
- `--provider <name>`: фільтр за префіксом провайдера
|
||||
- `--max-candidates <n>`: розмір списку резервних варіантів
|
||||
- `--set-default`: встановити `agents.defaults.model.primary` на перший вибір
|
||||
- `--set-image`: встановити `agents.defaults.imageModel.primary` на перший вибір зображень
|
||||
- `--set-default`: встановити `agents.defaults.model.primary` на перший вибраний варіант
|
||||
- `--set-image`: встановити `agents.defaults.imageModel.primary` на перший вибраний варіант зображень
|
||||
|
||||
Виконання probe потребує OpenRouter API key (з профілів автентифікації або `OPENROUTER_API_KEY`). Без ключа використовуйте `--no-probe`, щоб лише перелічити кандидатів.
|
||||
Для перевірок потрібен API key OpenRouter (з профілів автентифікації або
|
||||
`OPENROUTER_API_KEY`). Без ключа використовуйте `--no-probe`, щоб лише вивести список кандидатів.
|
||||
|
||||
Результати сканування ранжуються за:
|
||||
Результати сканування ранжуються за такими критеріями:
|
||||
|
||||
1. Підтримкою зображень
|
||||
2. Затримкою інструментів
|
||||
3. Розміром контексту
|
||||
4. Кількістю параметрів
|
||||
1. Підтримка зображень
|
||||
2. Затримка інструментів
|
||||
3. Розмір контексту
|
||||
4. Кількість параметрів
|
||||
|
||||
Вхідні дані
|
||||
|
||||
- Список OpenRouter `/models` (фільтр `:free`)
|
||||
- Потребує OpenRouter API key з профілів автентифікації або `OPENROUTER_API_KEY` (див. [/environment](/uk/help/environment))
|
||||
- Потрібен API key OpenRouter з профілів автентифікації або `OPENROUTER_API_KEY` (див. [/environment](/uk/help/environment))
|
||||
- Необов’язкові фільтри: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates`
|
||||
- Керування probe: `--timeout`, `--concurrency`
|
||||
- Керування перевірками: `--timeout`, `--concurrency`
|
||||
|
||||
Під час запуску в TTY ви можете інтерактивно вибрати резервні варіанти. У неінтерактивному режимі передайте `--yes`, щоб прийняти значення за замовчуванням.
|
||||
Під час запуску в TTY ви можете інтерактивно вибрати резервні варіанти. У неінтерактивному
|
||||
режимі передайте `--yes`, щоб прийняти типові значення.
|
||||
|
||||
## Реєстр моделей (`models.json`)
|
||||
|
||||
Власні провайдери в `models.providers` записуються в `models.json` у каталозі агента (типово `~/.openclaw/agents/<agentId>/agent/models.json`). Цей файл за замовчуванням об’єднується, якщо `models.mode` не встановлено в `replace`.
|
||||
Власні провайдери в `models.providers` записуються в `models.json` у каталозі
|
||||
агента (типово `~/.openclaw/agents/<agentId>/agent/models.json`). Цей файл
|
||||
типово зливається, якщо тільки `models.mode` не встановлено в `replace`.
|
||||
|
||||
Пріоритет у режимі злиття для збіжних ID провайдерів:
|
||||
Пріоритет у режимі злиття для збіжних ідентифікаторів провайдерів:
|
||||
|
||||
- Непорожній `baseUrl`, уже наявний у `models.json` агента, має пріоритет.
|
||||
- Непорожній `apiKey` у `models.json` агента має пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті конфігурації/профілю автентифікації.
|
||||
- Значення `apiKey` для провайдерів, якими керує SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань) замість збереження розкритих секретів.
|
||||
- Значення заголовків провайдера, якими керує SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань).
|
||||
- Порожні або відсутні `apiKey`/`baseUrl` агента повертаються до конфігурації `models.providers`.
|
||||
- Значення `apiKey` для провайдерів, керованих через SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для посилань на env, `secretref-managed` для посилань file/exec) замість збереження розв’язаних секретів.
|
||||
- Значення заголовків провайдера, керованих через SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для посилань на env, `secretref-managed` для посилань file/exec).
|
||||
- Порожні або відсутні `apiKey`/`baseUrl` агента переходять до конфігурації `models.providers`.
|
||||
- Інші поля провайдера оновлюються з конфігурації та нормалізованих даних каталогу.
|
||||
|
||||
Збереження маркерів є авторитетним щодо джерела: OpenClaw записує маркери з активного знімка конфігурації джерела (до розкриття значень), а не з розкритих значень секретів під час виконання.
|
||||
Це застосовується щоразу, коли OpenClaw повторно генерує `models.json`, включно зі шляхами, ініційованими командами, такими як `openclaw agent`.
|
||||
Збереження маркерів є авторитетним на рівні джерела: OpenClaw записує маркери з активного знімка конфігурації джерела (до розв’язання), а не з розв’язаних значень секретів під час виконання.
|
||||
Це застосовується щоразу, коли OpenClaw повторно генерує `models.json`, зокрема в шляхах, керованих командами, як-от `openclaw agent`.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Провайдери моделей](/uk/concepts/model-providers) — маршрутизація провайдерів і автентифікація
|
||||
- [Резервне перемикання моделей](/uk/concepts/model-failover) — ланцюжки резервних варіантів
|
||||
- [Генерація зображень](/uk/tools/image-generation) — конфігурація моделі зображень
|
||||
- [Генерація музики](/uk/tools/music-generation) — конфігурація моделі музики
|
||||
- [Генерація відео](/uk/tools/video-generation) — конфігурація моделі відео
|
||||
- [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) — ключі конфігурації моделей
|
||||
- [Model Providers](/uk/concepts/model-providers) — маршрутизація провайдерів і автентифікація
|
||||
- [Model Failover](/uk/concepts/model-failover) — ланцюжки резервного переходу
|
||||
- [Image Generation](/uk/tools/image-generation) — конфігурація моделі зображень
|
||||
- [Music Generation](/uk/tools/music-generation) — конфігурація моделі музики
|
||||
- [Video Generation](/uk/tools/video-generation) — конфігурація моделі відео
|
||||
- [Configuration Reference](/uk/gateway/configuration-reference#agent-defaults) — ключі конфігурації моделей
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,65 +1,65 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви створюєте plugin OpenClaw
|
||||
- Вам потрібно постачати схему конфігурації plugin або налагодити помилки валідації plugin
|
||||
summary: Вимоги до маніфесту Plugin + JSON schema (сувора валідація конфігурації)
|
||||
- Ви створюєте плагін OpenClaw
|
||||
- Вам потрібно постачати схему конфігурації плагіна або налагоджувати помилки валідації плагіна
|
||||
summary: Вимоги до маніфесту Plugin + схеми JSON (сувора валідація конфігурації)
|
||||
title: Маніфест Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T05:16:37Z"
|
||||
generated_at: "2026-04-23T06:24:10Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 4da8ce35aca4c12bf49a4c3e352fb7fc2b5768cb34157a00dabd247fe60b4f04
|
||||
source_hash: de71b9d556c2696d3279f202b66d57aa8014e9c89d81e3f453602744120d1675
|
||||
source_path: plugins/manifest.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Маніфест Plugin (`openclaw.plugin.json`)
|
||||
|
||||
Ця сторінка стосується лише **власного маніфесту plugin OpenClaw**.
|
||||
Ця сторінка стосується лише **власного маніфесту плагіна OpenClaw**.
|
||||
|
||||
Сумісні макети пакетів описано в [Plugin bundles](/uk/plugins/bundles).
|
||||
Сумісні компонування пакетів описано в [Пакети Plugin](/uk/plugins/bundles).
|
||||
|
||||
Сумісні формати пакетів використовують інші файли маніфесту:
|
||||
|
||||
- Пакет Codex: `.codex-plugin/plugin.json`
|
||||
- Пакет Claude: `.claude-plugin/plugin.json` або типовий макет компонента Claude без маніфесту
|
||||
- Пакет Cursor: `.cursor-plugin/plugin.json`
|
||||
- пакет Codex: `.codex-plugin/plugin.json`
|
||||
- пакет Claude: `.claude-plugin/plugin.json` або стандартне компонування компонентів Claude без маніфесту
|
||||
- пакет Cursor: `.cursor-plugin/plugin.json`
|
||||
|
||||
OpenClaw також автоматично виявляє ці макети пакетів, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут.
|
||||
OpenClaw також автоматично виявляє ці компонування пакетів, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут.
|
||||
|
||||
Для сумісних пакетів OpenClaw наразі зчитує метадані пакета, а також оголошені корені skill, корені команд Claude, типові значення `settings.json` для пакета Claude, типові значення LSP для пакета Claude та підтримувані набори hook, якщо макет відповідає очікуванням середовища виконання OpenClaw.
|
||||
Для сумісних пакетів OpenClaw наразі зчитує метадані пакета, а також оголошені корені skills, корені команд Claude, значення за замовчуванням `settings.json` пакета Claude, значення LSP за замовчуванням пакета Claude та підтримувані набори хуків, коли компонування відповідає очікуванням середовища виконання OpenClaw.
|
||||
|
||||
Кожен власний plugin OpenClaw **повинен** містити файл `openclaw.plugin.json` у **корені plugin**. OpenClaw використовує цей маніфест для валідації конфігурації **без виконання коду plugin**. Відсутні або невалідні маніфести вважаються помилками plugin і блокують валідацію конфігурації.
|
||||
Кожен власний плагін OpenClaw **повинен** містити файл `openclaw.plugin.json` у **корені плагіна**. OpenClaw використовує цей маніфест для валідації конфігурації **без виконання коду плагіна**. Відсутні або невалідні маніфести вважаються помилками плагіна й блокують валідацію конфігурації.
|
||||
|
||||
Повний посібник із системи plugin дивіться тут: [Plugins](/uk/tools/plugin).
|
||||
Для власної моделі capability та актуальних рекомендацій щодо зовнішньої сумісності:
|
||||
[Capability model](/uk/plugins/architecture#public-capability-model).
|
||||
Повний посібник із системи плагінів див. у розділі [Plugins](/uk/tools/plugin).
|
||||
Для власної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності:
|
||||
[Модель можливостей](/uk/plugins/architecture#public-capability-model).
|
||||
|
||||
## Що робить цей файл
|
||||
|
||||
`openclaw.plugin.json` — це метадані, які OpenClaw зчитує перед завантаженням коду вашого plugin.
|
||||
`openclaw.plugin.json` — це метадані, які OpenClaw зчитує перед завантаженням коду вашого плагіна.
|
||||
|
||||
Використовуйте його для:
|
||||
|
||||
- ідентичності plugin
|
||||
- ідентифікації плагіна
|
||||
- валідації конфігурації
|
||||
- метаданих auth та onboarding, які мають бути доступні без запуску середовища виконання plugin
|
||||
- недорогих підказок активації, які можуть перевіряти поверхні control-plane до завантаження середовища виконання
|
||||
- недорогих дескрипторів налаштування, які можуть перевіряти поверхні setup/onboarding до завантаження середовища виконання
|
||||
- метаданих псевдонімів та автоувімкнення, які мають визначатися до завантаження середовища виконання plugin
|
||||
- скорочених метаданих належності до сімейства моделей, які мають автоматично активувати plugin до завантаження середовища виконання
|
||||
- статичних знімків належності capability, що використовуються для вбудованого wiring сумісності та покриття контрактів
|
||||
- недорогих метаданих QA runner, які спільний хост `openclaw qa` може перевіряти до завантаження середовища виконання plugin
|
||||
- метаданих конфігурації, специфічних для channel, які мають об’єднуватися в поверхні каталогу та валідації без завантаження середовища виконання
|
||||
- підказок для UI конфігурації
|
||||
- метаданих автентифікації та онбордингу, які мають бути доступні без запуску середовища виконання плагіна
|
||||
- недорогих підказок активації, які поверхні control plane можуть перевіряти до завантаження середовища виконання
|
||||
- недорогих дескрипторів налаштування, які поверхні налаштування/онбордингу можуть перевіряти до завантаження середовища виконання
|
||||
- метаданих псевдонімів та автоувімкнення, які мають визначатися до завантаження середовища виконання плагіна
|
||||
- скорочених метаданих належності до сімейства моделей, які мають автоматично активувати плагін до завантаження середовища виконання
|
||||
- статичних знімків належності можливостей, що використовуються для вбудованої сумісної прив’язки та покриття контрактів
|
||||
- недорогих метаданих засобу запуску QA, які спільний хост `openclaw qa` може перевіряти до завантаження середовища виконання плагіна
|
||||
- метаданих конфігурації, специфічних для каналу, які мають об’єднуватися в поверхні каталогу та валідації без завантаження середовища виконання
|
||||
- підказок UI конфігурації
|
||||
|
||||
Не використовуйте його для:
|
||||
|
||||
- реєстрації поведінки середовища виконання
|
||||
- оголошення code entrypoint
|
||||
- оголошення точок входу коду
|
||||
- метаданих встановлення npm
|
||||
|
||||
Для цього призначені код вашого plugin і `package.json`.
|
||||
Це належить вашому коду плагіна та `package.json`.
|
||||
|
||||
## Мінімальний приклад
|
||||
|
||||
@ -139,65 +139,65 @@ OpenClaw також автоматично виявляє ці макети па
|
||||
|
||||
## Довідник полів верхнього рівня
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------------------------------ | ----------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | Так | `string` | Канонічний ідентифікатор plugin. Саме цей ідентифікатор використовується в `plugins.entries.<id>`. |
|
||||
| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього plugin. |
|
||||
| `enabledByDefault` | Ні | `true` | Позначає вбудований plugin як увімкнений за замовчуванням. Не вказуйте це поле або задайте будь-яке значення, відмінне від `true`, щоб plugin залишався вимкненим за замовчуванням. |
|
||||
| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора plugin. |
|
||||
| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори provider, які мають автоматично вмикати цей plugin, коли auth, конфігурація або посилання на моделі згадують їх. |
|
||||
| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип plugin, який використовується `plugins.slots.*`. |
|
||||
| `channels` | Ні | `string[]` | Ідентифікатори channel, що належать цьому plugin. Використовуються для виявлення та валідації конфігурації. |
|
||||
| `providers` | Ні | `string[]` | Ідентифікатори provider, що належать цьому plugin. |
|
||||
| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, що належать маніфесту й використовуються для автоматичного завантаження plugin до запуску середовища виконання. |
|
||||
| `providerEndpoints` | Ні | `object[]` | Метадані host/baseUrl для маршрутів provider, що належать маніфесту, які ядро має класифікувати до завантаження середовища виконання provider. |
|
||||
| `cliBackends` | Ні | `string[]` | Ідентифікатори backend CLI, що належать цьому plugin. Використовуються для автоактивації під час запуску на основі явних посилань у конфігурації. |
|
||||
| `syntheticAuthRefs` | Ні | `string[]` | Посилання на provider або backend CLI, чиї синтетичні hook auth, що належать plugin, слід перевіряти під час холодного виявлення моделей до завантаження середовища виконання. |
|
||||
| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API key, що належать вбудованому plugin і позначають несекретний локальний стан облікових даних, OAuth або ambient credentials. |
|
||||
| `commandAliases` | Ні | `object[]` | Імена команд, що належать цьому plugin і мають формувати діагностику конфігурації та CLI з урахуванням plugin до завантаження середовища виконання. |
|
||||
| `providerAuthEnvVars` | Ні | `Record<string, string[]>` | Недорогі env-метадані auth provider, які OpenClaw може перевіряти без завантаження коду plugin. |
|
||||
| `providerAuthAliases` | Ні | `Record<string, string>` | Ідентифікатори provider, які мають повторно використовувати інший ідентифікатор provider для пошуку auth, наприклад provider для кодування, який спільно використовує API key і профілі auth базового provider. |
|
||||
| `channelEnvVars` | Ні | `Record<string, string[]>` | Недорогі env-метадані channel, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для env-керованого налаштування channel або поверхонь auth, які мають бачити загальні помічники запуску/конфігурації. |
|
||||
| `providerAuthChoices` | Ні | `object[]` | Недорогі метадані варіантів auth для засобів вибору під час onboarding, визначення бажаного provider і простого зв’язування прапорців CLI. |
|
||||
| `activation` | Ні | `object` | Недорогі підказки активації для завантаження, яке запускається provider, командою, channel, маршрутом або capability. Лише метадані; фактичною поведінкою все одно керує середовище виконання plugin. |
|
||||
| `setup` | Ні | `object` | Недорогі дескриптори setup/onboarding, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання plugin. |
|
||||
| `qaRunners` | Ні | `object[]` | Недорогі дескриптори QA runner, які використовує спільний хост `openclaw qa` до завантаження середовища виконання plugin. |
|
||||
| `contracts` | Ні | `object` | Статичний знімок вбудованих capability для мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, вебпошуку та належності інструментів. |
|
||||
| `mediaUnderstandingProviderMetadata` | Ні | `Record<string, object>` | Недорогі типові значення розуміння медіа для ідентифікаторів provider, оголошених у `contracts.mediaUnderstandingProviders`. |
|
||||
| `channelConfigs` | Ні | `Record<string, object>` | Метадані конфігурації channel, що належать маніфесту й об’єднуються в поверхні виявлення та валідації до завантаження середовища виконання. |
|
||||
| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня plugin. |
|
||||
| `name` | Ні | `string` | Зрозуміла для людини назва plugin. |
|
||||
| `description` | Ні | `string` | Короткий опис, що показується в поверхнях plugin. |
|
||||
| `version` | Ні | `string` | Інформаційна версія plugin. |
|
||||
| `uiHints` | Ні | `Record<string, object>` | Мітки UI, заповнювачі та підказки чутливості для полів конфігурації. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------------------------------ | ----------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | Так | `string` | Канонічний ідентифікатор плагіна. Це ідентифікатор, який використовується в `plugins.entries.<id>`. |
|
||||
| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього плагіна. |
|
||||
| `enabledByDefault` | Ні | `true` | Позначає вбудований плагін як увімкнений за замовчуванням. Пропустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб плагін залишався вимкненим за замовчуванням. |
|
||||
| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора плагіна. |
|
||||
| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей плагін, коли автентифікація, конфігурація або посилання на моделі згадують їх. |
|
||||
| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип плагіна, який використовується `plugins.slots.*`. |
|
||||
| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей плагін. Використовується для виявлення та валідації конфігурації. |
|
||||
| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей плагін. |
|
||||
| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, якими володіє маніфест і які використовуються для автозавантаження плагіна до завантаження середовища виконання. |
|
||||
| `providerEndpoints` | Ні | `object[]` | Метадані хостів/`baseUrl` кінцевих точок, якими володіє маніфест, для маршрутів провайдерів, які ядро має класифікувати до завантаження середовища виконання провайдера. |
|
||||
| `cliBackends` | Ні | `string[]` | Ідентифікатори backend CLI inference, якими володіє цей плагін. Використовується для автоактивації під час запуску з явних посилань конфігурації. |
|
||||
| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдери або backend CLI, для яких синтетичний хук автентифікації, що належить плагіну, має перевірятися під час холодного виявлення моделей до завантаження середовища виконання. |
|
||||
| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API-ключів, що належать вбудованому плагіну й представляють не секретний локальний стан, OAuth або ambient credential state. |
|
||||
| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей плагін і які мають видавати обізнані про плагін діагностики конфігурації та CLI до завантаження середовища виконання. |
|
||||
| `providerAuthEnvVars` | Ні | `Record<string, string[]>` | Недорогі метадані env автентифікації провайдера, які OpenClaw може перевіряти без завантаження коду плагіна. |
|
||||
| `providerAuthAliases` | Ні | `Record<string, string>` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад провайдер для кодування, який спільно використовує API-ключ базового провайдера та профілі автентифікації. |
|
||||
| `channelEnvVars` | Ні | `Record<string, string[]>` | Недорогі метадані env каналу, які OpenClaw може перевіряти без завантаження коду плагіна. Використовуйте це для налаштування каналу через env або поверхонь автентифікації, які мають бути видимі загальним helper запуску/конфігурації. |
|
||||
| `providerAuthChoices` | Ні | `object[]` | Недорогі метадані вибору автентифікації для засобів вибору в онбордингу, визначення пріоритетного провайдера та простого зв’язування CLI flags. |
|
||||
| `activation` | Ні | `object` | Недорогі підказки активації для завантаження, що запускається провайдером, командою, каналом, маршрутом і можливістю. Лише метадані; фактична поведінка, як і раніше, належить середовищу виконання плагіна. |
|
||||
| `setup` | Ні | `object` | Недорогі дескриптори налаштування/онбордингу, які поверхні виявлення й налаштування можуть перевіряти без завантаження середовища виконання плагіна. |
|
||||
| `qaRunners` | Ні | `object[]` | Недорогі дескриптори засобів запуску QA, які використовуються спільним хостом `openclaw qa` до завантаження середовища виконання плагіна. |
|
||||
| `contracts` | Ні | `object` | Статичний знімок можливостей вбудованого пакета для зовнішніх хуків автентифікації, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. |
|
||||
| `mediaUnderstandingProviderMetadata` | Ні | `Record<string, object>` | Недорогі значення за замовчуванням media-understanding для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. |
|
||||
| `channelConfigs` | Ні | `Record<string, object>` | Метадані конфігурації каналу, якими володіє маніфест і які об’єднуються в поверхні виявлення та валідації до завантаження середовища виконання. |
|
||||
| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня плагіна. |
|
||||
| `name` | Ні | `string` | Людинозрозуміла назва плагіна. |
|
||||
| `description` | Ні | `string` | Короткий опис, що показується на поверхнях плагіна. |
|
||||
| `version` | Ні | `string` | Інформаційна версія плагіна. |
|
||||
| `uiHints` | Ні | `Record<string, object>` | Мітки UI, заповнювачі та підказки чутливості для полів конфігурації. |
|
||||
|
||||
## Довідник `providerAuthChoices`
|
||||
|
||||
Кожен запис `providerAuthChoices` описує один варіант onboarding або auth.
|
||||
OpenClaw зчитує це до завантаження середовища виконання provider.
|
||||
Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації.
|
||||
OpenClaw зчитує це до завантаження середовища виконання провайдера.
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| --------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| `provider` | Так | `string` | Ідентифікатор provider, якому належить цей варіант. |
|
||||
| `method` | Так | `string` | Ідентифікатор методу auth, до якого слід спрямувати. |
|
||||
| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта auth, який використовується в потоках onboarding і CLI. |
|
||||
| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw повертається до `choiceId`. |
|
||||
| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. |
|
||||
| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних засобах вибору, керованих асистентом. |
|
||||
| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант у засобах вибору асистента, але все ще дозволяє ручний вибір через CLI. |
|
||||
| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів до цього варіанта-замінника. |
|
||||
| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. |
|
||||
| `groupLabel` | Ні | `string` | Мітка цієї групи для користувача. |
|
||||
| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. |
|
||||
| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків auth з одним прапорцем. |
|
||||
| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. |
|
||||
| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key <key>`. |
|
||||
| `cliDescription` | Ні | `string` | Опис, який використовується в довідці CLI. |
|
||||
| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях onboarding має з’являтися цей варіант. Якщо не вказано, типово використовується `["text-inference"]`. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| --------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| `provider` | Так | `string` | Ідентифікатор провайдера, якому належить цей варіант. |
|
||||
| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого слід маршрутизувати. |
|
||||
| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, який використовується в потоках онбордингу та CLI. |
|
||||
| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. |
|
||||
| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. |
|
||||
| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних засобах вибору, керованих помічником. |
|
||||
| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант у засобах вибору помічника, але все ще дозволяє ручний вибір через CLI. |
|
||||
| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів до цього варіанта-замінника. |
|
||||
| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. |
|
||||
| `groupLabel` | Ні | `string` | Мітка цієї групи для користувача. |
|
||||
| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. |
|
||||
| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків автентифікації з одним флагом. |
|
||||
| `cliFlag` | Ні | `string` | Назва CLI-флага, наприклад `--openrouter-api-key`. |
|
||||
| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key <key>`. |
|
||||
| `cliDescription` | Ні | `string` | Опис, який використовується в довідці CLI. |
|
||||
| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, за замовчуванням це `["text-inference"]`. |
|
||||
|
||||
## Довідник `commandAliases`
|
||||
|
||||
Використовуйте `commandAliases`, коли plugin володіє назвою команди середовища виконання, яку користувачі можуть помилково вказати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw використовує ці метадані для діагностики без імпорту коду середовища виконання plugin.
|
||||
Використовуйте `commandAliases`, коли плагіну належить ім’я команди середовища виконання, яке користувачі можуть помилково вказати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw використовує ці метадані для діагностики без імпорту коду середовища виконання плагіна.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -211,19 +211,19 @@ OpenClaw зчитує це до завантаження середовища в
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------ | ----------- | ----------------- | -------------------------------------------------------------------------- |
|
||||
| `name` | Так | `string` | Назва команди, яка належить цьому plugin. |
|
||||
| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. |
|
||||
| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід пропонувати для операцій CLI, якщо така існує. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------ | ----------- | ----------------- | --------------------------------------------------------------------------- |
|
||||
| `name` | Так | `string` | Ім’я команди, яка належить цьому плагіну. |
|
||||
| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. |
|
||||
| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для операцій CLI, якщо вона існує. |
|
||||
|
||||
## Довідник `activation`
|
||||
|
||||
Використовуйте `activation`, коли plugin може дешево оголосити, які події control-plane мають активувати його пізніше.
|
||||
Використовуйте `activation`, коли плагін може недорого оголосити, які події control plane мають активувати його пізніше.
|
||||
|
||||
## Довідник `qaRunners`
|
||||
|
||||
Використовуйте `qaRunners`, коли plugin додає один або кілька transport runner під спільним коренем `openclaw qa`. Зберігайте ці метадані простими та статичними; фактичною реєстрацією CLI все одно керує середовище виконання plugin через легковагову поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`.
|
||||
Використовуйте `qaRunners`, коли плагін додає один або кілька транспортних засобів запуску під спільним коренем `openclaw qa`. Зберігайте ці метадані недорогими й статичними; фактична реєстрація CLI, як і раніше, належить середовищу виконання плагіна через легковагову поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -236,13 +236,13 @@ OpenClaw зчитує це до завантаження середовища в
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------- | ----------- | -------- | ------------------------------------------------------------------- |
|
||||
| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------- | ----------- | -------- | ----------------------------------------------------------------------- |
|
||||
| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. |
|
||||
| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. |
|
||||
|
||||
Цей блок містить лише метадані. Він не реєструє поведінку середовища виконання і не замінює `register(...)`, `setupEntry` чи інші entrypoint середовища виконання/plugin.
|
||||
Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням plugin, тому відсутність метаданих активації зазвичай впливає лише на продуктивність; це не повинно змінювати коректність, доки ще існують резервні механізми застарілого володіння маніфестом.
|
||||
Цей блок є лише метаданими. Він не реєструє поведінку середовища виконання і не замінює `register(...)`, `setupEntry` або інші точки входу середовища виконання/плагіна.
|
||||
Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням плагіна, тому відсутність метаданих активації зазвичай впливає лише на продуктивність; вона не має змінювати коректність, доки ще існують застарілі резервні механізми володіння маніфестом.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -256,25 +256,23 @@ OpenClaw зчитує це до завантаження середовища в
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ---------------- | ----------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
|
||||
| `onProviders` | Ні | `string[]` | Ідентифікатори provider, які мають активувати цей plugin на запит. |
|
||||
| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають активувати цей plugin. |
|
||||
| `onChannels` | Ні | `string[]` | Ідентифікатори channel, які мають активувати цей plugin. |
|
||||
| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають активувати цей plugin. |
|
||||
| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки capability, що використовуються під час планування активації control-plane. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
|
||||
| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають активувати цей плагін на запит. |
|
||||
| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають активувати цей плагін. |
|
||||
| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають активувати цей плагін. |
|
||||
| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають активувати цей плагін. |
|
||||
| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки можливостей, що використовуються під час планування активації control plane. |
|
||||
|
||||
Поточні активні споживачі:
|
||||
|
||||
- планування CLI, яке запускається командою, повертається до застарілих
|
||||
`commandAliases[].cliCommand` або `commandAliases[].name`
|
||||
- планування setup/channel, яке запускається channel, повертається до застарілого володіння `channels[]`, якщо явні метадані активації channel відсутні
|
||||
- планування setup/runtime, яке запускається provider, повертається до застарілого володіння
|
||||
`providers[]` і верхньорівневого `cliBackends[]`, якщо явні метадані активації provider відсутні
|
||||
- планування CLI, що запускається командою, повертається до застарілого `commandAliases[].cliCommand` або `commandAliases[].name`
|
||||
- планування налаштування/каналу, що запускається каналом, повертається до застарілого володіння `channels[]`, якщо явні метадані активації каналу відсутні
|
||||
- планування налаштування/середовища виконання, що запускається провайдером, повертається до застарілого володіння `providers[]` і верхньорівневого `cliBackends[]`, якщо явні метадані активації провайдера відсутні
|
||||
|
||||
## Довідник `setup`
|
||||
|
||||
Використовуйте `setup`, коли поверхням setup та onboarding потрібні дешеві метадані plugin до завантаження середовища виконання.
|
||||
Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні недорогі метадані, що належать плагіну, до завантаження середовища виконання.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -293,32 +291,32 @@ OpenClaw зчитує це до завантаження середовища в
|
||||
}
|
||||
```
|
||||
|
||||
Верхньорівневе `cliBackends` залишається валідним і надалі описує backend інференсу CLI. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для потоків control-plane/setup, які мають залишатися лише на рівні метаданих.
|
||||
Верхньорівневе `cliBackends` залишається валідним і надалі описує backend CLI inference. `setup.cliBackends` — це поверхня дескрипторів, специфічна для налаштування, для потоків control plane/налаштування, які мають залишатися лише метаданими.
|
||||
|
||||
Якщо `setup.providers` і `setup.cliBackends` присутні, вони є бажаною поверхнею пошуку setup за принципом descriptor-first. Якщо дескриптор лише звужує кандидатний plugin, а для setup усе ще потрібні багатші hook середовища виконання на етапі setup, установіть `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання.
|
||||
Якщо вони присутні, `setup.providers` і `setup.cliBackends` є пріоритетною поверхнею пошуку за принципом descriptor-first для виявлення налаштування. Якщо дескриптор лише звужує кандидатний плагін, а для налаштування все ще потрібні багатші хуки середовища виконання часу налаштування, установіть `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання.
|
||||
|
||||
Оскільки пошук setup може виконувати код `setup-api`, що належить plugin, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` повинні залишатися унікальними серед виявлених plugin. Неоднозначне володіння завершується закритою відмовою замість вибору переможця за порядком виявлення.
|
||||
Оскільки пошук налаштування може виконувати код `setup-api`, що належить плагіну, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед виявлених плагінів. Неоднозначне володіння завершується в безпечному закритому стані замість вибору переможця за порядком виявлення.
|
||||
|
||||
### Довідник `setup.providers`
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------ |
|
||||
| `id` | Так | `string` | Ідентифікатор provider, який надається під час setup або onboarding. Зберігайте нормалізовані ідентифікатори глобально унікальними. |
|
||||
| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/auth, які цей provider підтримує без завантаження повного середовища виконання. |
|
||||
| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні setup/status можуть перевіряти до завантаження середовища виконання plugin. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------- | ----------- | ---------- | -------------------------------------------------------------------------------- |
|
||||
| `id` | Так | `string` | Ідентифікатор провайдера, який відкривається під час налаштування або онбордингу. Нормалізовані ідентифікатори мають бути глобально унікальними. |
|
||||
| `authMethods` | Ні | `string[]` | Ідентифікатори методів налаштування/автентифікації, які цей провайдер підтримує без завантаження повного середовища виконання. |
|
||||
| `envVars` | Ні | `string[]` | Змінні env, які загальні поверхні налаштування/стану можуть перевіряти до завантаження середовища виконання плагіна. |
|
||||
|
||||
### Поля `setup`
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------- |
|
||||
| `providers` | Ні | `object[]` | Дескриптори setup provider, які надаються під час setup та onboarding. |
|
||||
| `cliBackends` | Ні | `string[]` | Ідентифікатори backend для етапу setup, що використовуються для пошуку setup за принципом descriptor-first. Зберігайте нормалізовані ідентифікатори глобально унікальними. |
|
||||
| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього plugin. |
|
||||
| `requiresRuntime` | Ні | `boolean` | Чи потребує setup все ще виконання `setup-api` після пошуку за дескриптором. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| `providers` | Ні | `object[]` | Дескриптори налаштування провайдерів, що відкриваються під час налаштування та онбордингу. |
|
||||
| `cliBackends` | Ні | `string[]` | Ідентифікатори backend часу налаштування, що використовуються для пошуку налаштування за принципом descriptor-first. Нормалізовані ідентифікатори мають бути глобально унікальними. |
|
||||
| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, які належать поверхні налаштування цього плагіна. |
|
||||
| `requiresRuntime` | Ні | `boolean` | Чи потребує налаштування виконання `setup-api` після пошуку за дескриптором. |
|
||||
|
||||
## Довідник `uiHints`
|
||||
|
||||
`uiHints` — це відображення імен полів конфігурації на невеликі підказки для відображення.
|
||||
`uiHints` — це відображення від назв полів конфігурації до невеликих підказок рендерингу.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -333,25 +331,26 @@ OpenClaw зчитує це до завантаження середовища в
|
||||
}
|
||||
```
|
||||
|
||||
Підказка для кожного поля може містити:
|
||||
Кожна підказка для поля може містити:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ------------- | ---------- | --------------------------------------- |
|
||||
| `label` | `string` | Мітка поля для користувача. |
|
||||
| `help` | `string` | Короткий допоміжний текст. |
|
||||
| `tags` | `string[]` | Необов’язкові теги UI. |
|
||||
| `advanced` | `boolean` | Позначає поле як розширене. |
|
||||
| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. |
|
||||
| `placeholder` | `string` | Текст-заповнювач для полів форми. |
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ------------- | ---------- | ----------------------------------------- |
|
||||
| `label` | `string` | Мітка поля для користувача. |
|
||||
| `help` | `string` | Короткий допоміжний текст. |
|
||||
| `tags` | `string[]` | Необов’язкові теги UI. |
|
||||
| `advanced` | `boolean` | Позначає поле як розширене. |
|
||||
| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. |
|
||||
| `placeholder` | `string` | Текст-заповнювач для полів форми. |
|
||||
|
||||
## Довідник `contracts`
|
||||
|
||||
Використовуйте `contracts` лише для статичних метаданих володіння capability, які OpenClaw може зчитувати без імпорту середовища виконання plugin.
|
||||
Використовуйте `contracts` лише для статичних метаданих належності можливостей, які OpenClaw може зчитати без імпорту середовища виконання плагіна.
|
||||
|
||||
```json
|
||||
{
|
||||
"contracts": {
|
||||
"embeddedExtensionFactories": ["pi"],
|
||||
"externalAuthProviders": ["acme-ai"],
|
||||
"speechProviders": ["openai"],
|
||||
"realtimeTranscriptionProviders": ["openai"],
|
||||
"realtimeVoiceProviders": ["openai"],
|
||||
@ -367,22 +366,25 @@ OpenClaw зчитує це до завантаження середовища в
|
||||
|
||||
Кожен список є необов’язковим:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| -------------------------------- | ---------- | --------------------------------------------------------------------- |
|
||||
| `embeddedExtensionFactories` | `string[]` | Ідентифікатори вбудованого середовища виконання, для яких вбудований plugin може реєструвати factory. |
|
||||
| `speechProviders` | `string[]` | Ідентифікатори speech provider, якими володіє цей plugin. |
|
||||
| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори provider транскрипції в реальному часі, якими володіє цей plugin. |
|
||||
| `realtimeVoiceProviders` | `string[]` | Ідентифікатори provider голосу в реальному часі, якими володіє цей plugin. |
|
||||
| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори provider розуміння медіа, якими володіє цей plugin. |
|
||||
| `imageGenerationProviders` | `string[]` | Ідентифікатори provider генерації зображень, якими володіє цей plugin. |
|
||||
| `videoGenerationProviders` | `string[]` | Ідентифікатори provider генерації відео, якими володіє цей plugin. |
|
||||
| `webFetchProviders` | `string[]` | Ідентифікатори provider web-fetch, якими володіє цей plugin. |
|
||||
| `webSearchProviders` | `string[]` | Ідентифікатори provider вебпошуку, якими володіє цей plugin. |
|
||||
| `tools` | `string[]` | Назви agent tool, якими володіє цей plugin для перевірок контрактів вбудованих plugin. |
|
||||
| Поле | Тип | Що воно означає |
|
||||
| -------------------------------- | ---------- | ------------------------------------------------------------------- |
|
||||
| `embeddedExtensionFactories` | `string[]` | Ідентифікатори вбудованого середовища виконання, для яких вбудований плагін може реєструвати фабрики. |
|
||||
| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, хук зовнішнього профілю автентифікації яких належить цьому плагіну. |
|
||||
| `speechProviders` | `string[]` | Ідентифікатори speech-провайдерів, які належать цьому плагіну. |
|
||||
| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів realtime transcription, які належать цьому плагіну. |
|
||||
| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів realtime voice, які належать цьому плагіну. |
|
||||
| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів media-understanding, які належать цьому плагіну. |
|
||||
| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів image generation, які належать цьому плагіну. |
|
||||
| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів video generation, які належать цьому плагіну. |
|
||||
| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, які належать цьому плагіну. |
|
||||
| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів web search, які належать цьому плагіну. |
|
||||
| `tools` | `string[]` | Назви інструментів агента, які належать цьому плагіну для перевірок контрактів вбудованих пакетів. |
|
||||
|
||||
Плагіни провайдерів, які реалізують `resolveExternalAuthProfiles`, повинні оголошувати `contracts.externalAuthProviders`. Плагіни без цього оголошення все ще працюють через застарілий резервний механізм сумісності, але він повільніший і буде видалений після завершення вікна міграції.
|
||||
|
||||
## Довідник `mediaUnderstandingProviderMetadata`
|
||||
|
||||
Використовуйте `mediaUnderstandingProviderMetadata`, коли provider розуміння медіа має типові моделі, пріоритет резервного автоauth або нативну підтримку документів, які потрібні загальним допоміжним засобам ядра до завантаження середовища виконання. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`.
|
||||
Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер media-understanding має моделі за замовчуванням, пріоритет резервної auto-auth або власну підтримку документів, які потрібні загальним helper ядра до завантаження середовища виконання. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -405,18 +407,18 @@ OpenClaw зчитує це до завантаження середовища в
|
||||
}
|
||||
```
|
||||
|
||||
Кожен запис provider може містити:
|
||||
Кожен запис провайдера може містити:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ---------------------- | ----------------------------------- | ------------------------------------------------------------------------- |
|
||||
| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіа capability, які надає цей provider. |
|
||||
| `defaultModels` | `Record<string, string>` | Типові значення зіставлення capability-модель, які використовуються, коли конфігурація не задає модель. |
|
||||
| `autoPriority` | `Record<string, number>` | Менші числа сортуються раніше для автоматичного резервного вибору provider на основі облікових даних. |
|
||||
| `nativeDocumentInputs` | `"pdf"[]` | Нативні вхідні формати документів, які підтримує provider. |
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ---------------------- | ----------------------------------- | ------------------------------------------------------------------------------ |
|
||||
| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. |
|
||||
| `defaultModels` | `Record<string, string>` | Значення моделей за замовчуванням для можливостей, що використовуються, коли конфігурація не вказує модель. |
|
||||
| `autoPriority` | `Record<string, number>` | Менші числа сортуються раніше для автоматичного резервного вибору провайдера на основі облікових даних. |
|
||||
| `nativeDocumentInputs` | `"pdf"[]` | Власні вхідні дані документів, які підтримує провайдер. |
|
||||
|
||||
## Довідник `channelConfigs`
|
||||
|
||||
Використовуйте `channelConfigs`, коли plugin channel потребує дешевих метаданих конфігурації до завантаження середовища виконання.
|
||||
Використовуйте `channelConfigs`, коли плагіну каналу потрібні недорогі метадані конфігурації до завантаження середовища виконання.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -443,19 +445,19 @@ OpenClaw зчитує це до завантаження середовища в
|
||||
}
|
||||
```
|
||||
|
||||
Кожен запис channel може містити:
|
||||
Кожен запис каналу може містити:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ------------- | ------------------------ | ----------------------------------------------------------------------------------------------- |
|
||||
| `schema` | `object` | JSON Schema для `channels.<id>`. Обов’язкове для кожного оголошеного запису конфігурації channel. |
|
||||
| `uiHints` | `Record<string, object>` | Необов’язкові мітки UI/заповнювачі/підказки чутливості для цього розділу конфігурації channel. |
|
||||
| `label` | `string` | Мітка channel, яка об’єднується в поверхні вибору та перевірки, коли метадані середовища виконання ще не готові. |
|
||||
| `description` | `string` | Короткий опис channel для поверхонь перевірки та каталогу. |
|
||||
| `preferOver` | `string[]` | Застарілі або менш пріоритетні ідентифікатори plugin, які цей channel має перевершувати в поверхнях вибору. |
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ------------- | ------------------------ | ------------------------------------------------------------------------------------------ |
|
||||
| `schema` | `object` | JSON Schema для `channels.<id>`. Обов’язкове для кожного оголошеного запису конфігурації каналу. |
|
||||
| `uiHints` | `Record<string, object>` | Необов’язкові мітки UI/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. |
|
||||
| `label` | `string` | Мітка каналу, яка об’єднується в поверхні вибору та перегляду, коли метадані середовища виконання ще не готові. |
|
||||
| `description` | `string` | Короткий опис каналу для поверхонь перегляду та каталогу. |
|
||||
| `preferOver` | `string[]` | Ідентифікатори застарілих або нижчопріоритетних плагінів, які цей канал має перевершувати на поверхнях вибору. |
|
||||
|
||||
## Довідник `modelSupport`
|
||||
|
||||
Використовуйте `modelSupport`, коли OpenClaw має визначати ваш provider plugin за скороченими ідентифікаторами моделей на кшталт `gpt-5.4` або `claude-sonnet-4.6` до завантаження середовища виконання plugin.
|
||||
Використовуйте `modelSupport`, коли OpenClaw має визначати ваш плагін провайдера за скороченими ідентифікаторами моделей на кшталт `gpt-5.4` або `claude-sonnet-4.6` до завантаження середовища виконання плагіна.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -468,74 +470,69 @@ OpenClaw зчитує це до завантаження середовища в
|
||||
|
||||
OpenClaw застосовує такий пріоритет:
|
||||
|
||||
- явні посилання `provider/model` використовують метадані маніфесту `providers`, якому належить provider
|
||||
- `modelPatterns` мають вищий пріоритет за `modelPrefixes`
|
||||
- якщо збігаються один невбудований plugin і один вбудований plugin, перемагає невбудований plugin
|
||||
- інша неоднозначність ігнорується, доки користувач або конфігурація не задасть provider
|
||||
- явні посилання `provider/model` використовують метадані маніфесту `providers`, якому належить провайдер
|
||||
- `modelPatterns` мають пріоритет над `modelPrefixes`
|
||||
- якщо збігаються один невбудований плагін і один вбудований плагін, перемагає невбудований плагін
|
||||
- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкажуть провайдера
|
||||
|
||||
Поля:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| --------------- | ---------- | ---------------------------------------------------------------------------- |
|
||||
| Поле | Тип | Що воно означає |
|
||||
| --------------- | ---------- | -------------------------------------------------------------------------------- |
|
||||
| `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. |
|
||||
| `modelPatterns` | `string[]` | Джерела regex, які зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. |
|
||||
|
||||
Застарілі верхньорівневі ключі capability більше не рекомендуються. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`,
|
||||
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
|
||||
`imageGenerationProviders`, `videoGenerationProviders`,
|
||||
`webFetchProviders` і `webSearchProviders` до `contracts`; звичайне завантаження маніфесту більше не вважає ці верхньорівневі поля володінням capability.
|
||||
Застарілі ключі можливостей верхнього рівня не рекомендуються до використання. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` до `contracts`; звичайне завантаження маніфесту більше не розглядає ці поля верхнього рівня як належність можливостей.
|
||||
|
||||
## Маніфест проти package.json
|
||||
## Маніфест versus package.json
|
||||
|
||||
Ці два файли виконують різні завдання:
|
||||
|
||||
| Файл | Для чого його використовувати |
|
||||
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів auth і підказки UI, які мають існувати до запуску коду plugin |
|
||||
| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для entrypoint, обмежень встановлення, setup або метаданих каталогу |
|
||||
| Файл | Для чого використовувати |
|
||||
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду плагіна |
|
||||
| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для точок входу, обмежень встановлення, налаштування або метаданих каталогу |
|
||||
|
||||
Якщо ви не впевнені, куди належить певний фрагмент метаданих, використовуйте таке правило:
|
||||
Якщо ви не впевнені, куди має належати певний фрагмент метаданих, використовуйте таке правило:
|
||||
|
||||
- якщо OpenClaw повинен знати це до завантаження коду plugin, помістіть це в `openclaw.plugin.json`
|
||||
- якщо це стосується пакування, файлів entrypoint або поведінки встановлення npm, помістіть це в `package.json`
|
||||
- якщо OpenClaw має знати про нього до завантаження коду плагіна, розміщуйте його в `openclaw.plugin.json`
|
||||
- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, розміщуйте це в `package.json`
|
||||
|
||||
### Поля package.json, які впливають на виявлення
|
||||
### Поля `package.json`, які впливають на виявлення
|
||||
|
||||
Деякі метадані plugin до запуску середовища виконання навмисно зберігаються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`.
|
||||
Деякі метадані плагіна до запуску середовища виконання навмисно розміщуються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`.
|
||||
|
||||
Важливі приклади:
|
||||
|
||||
| Поле | Що воно означає |
|
||||
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `openclaw.extensions` | Оголошує entrypoint власних plugin. Має залишатися в каталозі пакета plugin. |
|
||||
| `openclaw.runtimeExtensions` | Оголошує entrypoint зібраного JavaScript середовища виконання для встановлених пакетів. Має залишатися в каталозі пакета plugin. |
|
||||
| `openclaw.setupEntry` | Легковаговий entrypoint лише для setup, який використовується під час onboarding, відкладеного запуску channel і виявлення channel status/SecretRef у режимі лише читання. Має залишатися в каталозі пакета plugin. |
|
||||
| `openclaw.runtimeSetupEntry` | Оголошує entrypoint setup зібраного JavaScript для встановлених пакетів. Має залишатися в каталозі пакета plugin. |
|
||||
| `openclaw.channel` | Недорогі метадані каталогу channel, як-от мітки, шляхи до документації, псевдоніми та текст для вибору. |
|
||||
| `openclaw.channel.configuredState` | Легковагові метадані перевірки налаштованого стану, які можуть відповісти на питання «чи вже існує налаштування лише через env?» без завантаження повного середовища виконання channel. |
|
||||
| `openclaw.channel.persistedAuthState` | Легковагові метадані перевірки збереженого стану auth, які можуть відповісти на питання «чи вже виконано вхід хоч десь?» без завантаження повного середовища виконання channel. |
|
||||
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення вбудованих і зовнішньо опублікованих plugin. |
|
||||
| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. |
|
||||
| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw, із нижньою межею semver на кшталт `>=2026.3.22`. |
|
||||
| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення та оновлення перевіряють отриманий артефакт за ним. |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого plugin, коли конфігурація невалідна. |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням channel лише для setup завантажуватися до повного plugin channel під час запуску. |
|
||||
| `openclaw.extensions` | Оголошує точки входу власного плагіна. Вони мають залишатися в межах каталогу пакета плагіна. |
|
||||
| `openclaw.runtimeExtensions` | Оголошує точки входу зібраного середовища виконання JavaScript для встановлених пакетів. Вони мають залишатися в межах каталогу пакета плагіна. |
|
||||
| `openclaw.setupEntry` | Легковагова точка входу лише для налаштування, що використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef лише для читання. Вона має залишатися в межах каталогу пакета плагіна. |
|
||||
| `openclaw.runtimeSetupEntry` | Оголошує точку входу зібраного JavaScript для налаштування для встановлених пакетів. Вона має залишатися в межах каталогу пакета плагіна. |
|
||||
| `openclaw.channel` | Недорогі метадані каталогу каналу, як-от мітки, шляхи документації, псевдоніми та текст для вибору. |
|
||||
| `openclaw.channel.configuredState` | Метадані легковагового засобу перевірки налаштованого стану, який може відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного середовища виконання каналу. |
|
||||
| `openclaw.channel.persistedAuthState` | Метадані легковагового засобу перевірки збереженого стану автентифікації, який може відповісти на запитання «чи вже десь виконано вхід?» без завантаження повного середовища виконання каналу. |
|
||||
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих плагінів. |
|
||||
| `openclaw.install.defaultChoice` | Пріоритетний шлях встановлення, коли доступно кілька джерел встановлення. |
|
||||
| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw з використанням нижньої межі semver, наприклад `>=2026.3.22`. |
|
||||
| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення звіряють із ним отриманий артефакт. |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого плагіна, коли конфігурація невалідна. |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для налаштування завантажуватися під час запуску раніше, ніж повний плагін каналу. |
|
||||
|
||||
Метадані маніфесту визначають, які варіанти provider/channel/setup з’являються в onboarding до завантаження середовища виконання. `package.json#openclaw.install` повідомляє onboarding, як отримати або ввімкнути цей plugin, коли користувач вибирає один із цих варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`.
|
||||
Метадані маніфесту визначають, які варіанти провайдера/каналу/налаштування з’являються в онбордингу до завантаження середовища виконання. `package.json#openclaw.install` повідомляє онбордингу, як отримати або ввімкнути цей плагін, коли користувач обирає один із цих варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`.
|
||||
|
||||
`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають plugin на старіших хостах.
|
||||
`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають плагін на старіших хостах.
|
||||
|
||||
Точне закріплення версії npm уже задається в `npmSpec`, наприклад
|
||||
`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Поєднуйте це з
|
||||
`expectedIntegrity`, якщо хочете, щоб потоки оновлення завершувалися закритою відмовою, коли отриманий npm-артефакт більше не відповідає закріпленому релізу. Інтерактивний onboarding пропонує варіанти встановлення npm із довірених метаданих каталогу лише тоді, коли `npmSpec` є точною версією і присутній `expectedIntegrity`; інакше він повертається до локального джерела або пропуску.
|
||||
Точне закріплення версії npm вже міститься в `npmSpec`, наприклад `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Поєднуйте це з `expectedIntegrity`, якщо хочете, щоб потоки оновлення завершувалися в безпечному закритому стані, коли отриманий артефакт npm більше не відповідає закріпленому релізу. Інтерактивний онбординг пропонує варіанти встановлення npm лише з довірених метаданих каталогу, коли `npmSpec` є точною версією і присутній `expectedIntegrity`; інакше він повертається до локального джерела або пропуску.
|
||||
|
||||
Plugin channel мають надавати `openclaw.setupEntry`, коли status, список channel або сканування SecretRef мають визначати налаштовані облікові записи без завантаження повного середовища виконання. Запис setup має надавати метадані channel разом із безпечними для setup адаптерами конфігурації, status і secrets; клієнти мережі, слухачі Gateway і transport runtime слід залишати в основному entrypoint extension.
|
||||
Плагіни каналів повинні надавати `openclaw.setupEntry`, коли статус, список каналів або сканування SecretRef мають визначати налаштовані облікові записи без завантаження повного середовища виконання. Точка входу налаштування має надавати метадані каналу разом із безпечними для налаштування адаптерами конфігурації, статусу та секретів; мережеві клієнти, слухачі Gateway і середовища виконання транспорту слід залишати в основній точці входу розширення.
|
||||
|
||||
Поля entrypoint середовища виконання не скасовують перевірки меж пакета для полів source entrypoint. Наприклад, `openclaw.runtimeExtensions` не може зробити придатним до завантаження шлях `openclaw.extensions`, що виходить за межі.
|
||||
Поля точок входу середовища виконання не скасовують перевірки меж пакета для полів вихідних точок входу. Наприклад, `openclaw.runtimeExtensions` не може зробити придатним до завантаження шлях `openclaw.extensions`, що виходить за межі.
|
||||
|
||||
`openclaw.install.allowInvalidConfigRecovery` навмисно має вузьке призначення. Воно не робить довільно зламані конфігурації придатними до встановлення. Наразі воно лише дозволяє потокам встановлення відновлюватися після конкретних застарілих збоїв оновлення вбудованого plugin, наприклад відсутнього шляху до вбудованого plugin або застарілого запису `channels.<id>` для цього ж вбудованого plugin. Непов’язані помилки конфігурації все одно блокують встановлення і спрямовують операторів до `openclaw doctor --fix`.
|
||||
`openclaw.install.allowInvalidConfigRecovery` навмисно має вузьке застосування. Воно не робить довільні зламані конфігурації придатними до встановлення. Сьогодні воно лише дозволяє потокам встановлення відновлюватися після певних застарілих збоїв оновлення вбудованого плагіна, наприклад відсутнього шляху до вбудованого плагіна або застарілого запису `channels.<id>` для того самого вбудованого плагіна. Не пов’язані помилки конфігурації й далі блокують встановлення та спрямовують операторів до `openclaw doctor --fix`.
|
||||
|
||||
`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля перевірки:
|
||||
`openclaw.channel.persistedAuthState` — це метадані пакета для маленького модуля перевірки:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -551,9 +548,9 @@ Plugin channel мають надавати `openclaw.setupEntry`, коли statu
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева yes/no-перевірка auth до завантаження повного plugin channel. Цільовий експорт має бути невеликою функцією, яка читає лише збережений стан; не спрямовуйте її через повний barrel середовища виконання channel.
|
||||
Використовуйте це, коли потоки налаштування, doctor або configured-state потребують недорогої перевірки автентифікації з відповіддю так/ні до завантаження повного плагіна каналу. Цільовий експорт має бути невеликою функцією, яка лише зчитує збережений стан; не маршрутизуйте її через повний barrel середовища виконання каналу.
|
||||
|
||||
`openclaw.channel.configuredState` має таку саму форму для дешевих перевірок налаштованого стану лише через env:
|
||||
`openclaw.channel.configuredState` має ту саму форму для недорогих перевірок налаштованого стану лише через env:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -569,68 +566,62 @@ Plugin channel мають надавати `openclaw.setupEntry`, коли statu
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте це, коли channel може визначити configured-state з env або інших малих невиконуваних входів. Якщо перевірка потребує повного визначення конфігурації або справжнього середовища виконання channel, залиште цю логіку в hook `config.hasConfiguredState` plugin.
|
||||
Використовуйте це, коли канал може визначити налаштований стан за env або іншими невеликими невиконуваними в середовищі виконання вхідними даними. Якщо перевірка потребує повного визначення конфігурації або реального середовища виконання каналу, залиште цю логіку в хуку плагіна `config.hasConfiguredState`.
|
||||
|
||||
## Пріоритет виявлення (дублікати ідентифікаторів plugin)
|
||||
## Пріоритет виявлення (дубльовані ідентифікатори плагінів)
|
||||
|
||||
OpenClaw виявляє plugin із кількох коренів (вбудовані, глобальне встановлення, workspace, явно вибрані в конфігурації шляхи). Якщо два виявлення мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч.
|
||||
OpenClaw виявляє плагіни з кількох коренів (вбудовані, глобальне встановлення, робочий простір, шляхи, явно вибрані в конфігурації). Якщо два виявлені плагіни мають однаковий `id`, зберігається лише маніфест **з найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним.
|
||||
|
||||
Пріоритет від найвищого до найнижчого:
|
||||
|
||||
1. **Вибраний у конфігурації** — шлях, явно закріплений у `plugins.entries.<id>`
|
||||
2. **Вбудований** — plugin, що постачаються з OpenClaw
|
||||
3. **Глобальне встановлення** — plugin, встановлені в глобальний корінь plugin OpenClaw
|
||||
4. **Workspace** — plugin, виявлені відносно поточного workspace
|
||||
2. **Вбудований** — плагіни, що постачаються з OpenClaw
|
||||
3. **Глобальне встановлення** — плагіни, встановлені в глобальний корінь плагінів OpenClaw
|
||||
4. **Робочий простір** — плагіни, виявлені відносно поточного робочого простору
|
||||
|
||||
Наслідки:
|
||||
|
||||
- Форкнута або застаріла копія вбудованого plugin у workspace не замінить вбудовану збірку.
|
||||
- Щоб справді перевизначити вбудований plugin локальним, закріпіть його через `plugins.entries.<id>`, щоб він переміг за пріоритетом, а не покладайтесь на виявлення у workspace.
|
||||
- Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказати на відкинуту копію.
|
||||
- Форк або застаріла копія вбудованого плагіна, що лежить у робочому просторі, не перекриє вбудовану збірку.
|
||||
- Щоб справді перевизначити вбудований плагін локальним, закріпіть його через `plugins.entries.<id>`, щоб він переміг за пріоритетом, а не покладався на виявлення в робочому просторі.
|
||||
- Відкидання дублікатів записується в журнал, щоб Doctor і діагностика під час запуску могли вказати на відкинуту копію.
|
||||
|
||||
## Вимоги до JSON Schema
|
||||
|
||||
- **Кожен plugin повинен постачатися з JSON Schema**, навіть якщо він не приймає конфігурацію.
|
||||
- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`).
|
||||
- **Кожен плагін повинен містити JSON Schema**, навіть якщо він не приймає конфігурації.
|
||||
- Порожня схема є припустимою (наприклад, `{ "type": "object", "additionalProperties": false }`).
|
||||
- Схеми проходять валідацію під час читання/запису конфігурації, а не під час виконання.
|
||||
|
||||
## Поведінка валідації
|
||||
|
||||
- Невідомі ключі `channels.*` — це **помилки**, якщо тільки ідентифікатор channel не оголошений маніфестом plugin.
|
||||
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny` і `plugins.slots.*`
|
||||
повинні посилатися на **виявлювані** ідентифікатори plugin. Невідомі ідентифікатори — це **помилки**.
|
||||
- Якщо plugin встановлено, але він має зламаний або відсутній маніфест чи схему,
|
||||
валідація завершується помилкою, а Doctor повідомляє про помилку plugin.
|
||||
- Якщо конфігурація plugin існує, але plugin **вимкнений**, конфігурація зберігається і в Doctor + журналах показується **попередження**.
|
||||
- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор каналу не оголошено в маніфесті плагіна.
|
||||
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` повинні посилатися на **виявлювані** ідентифікатори плагінів. Невідомі ідентифікатори є **помилками**.
|
||||
- Якщо плагін встановлено, але він має зламаний або відсутній маніфест чи схему, валідація завершується помилкою, а Doctor повідомляє про помилку плагіна.
|
||||
- Якщо конфігурація плагіна існує, але сам плагін **вимкнено**, конфігурація зберігається, і в Doctor + журналах показується **попередження**.
|
||||
|
||||
Повну схему `plugins.*` дивіться в [Configuration reference](/uk/gateway/configuration).
|
||||
Повну схему `plugins.*` див. у [Довіднику з конфігурації](/uk/gateway/configuration).
|
||||
|
||||
## Примітки
|
||||
|
||||
- Маніфест є **обов’язковим для власних plugin OpenClaw**, включно із завантаженням із локальної файлової системи.
|
||||
- Середовище виконання все одно завантажує модуль plugin окремо; маніфест використовується лише для виявлення + валідації.
|
||||
- Власні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок допускаються, якщо кінцеве значення все ще є об’єктом.
|
||||
- Завантажувач маніфестів читає лише задокументовані поля маніфесту. Уникайте додавання тут власних верхньорівневих ключів.
|
||||
- `providerAuthEnvVars` — це дешевий шлях метаданих для перевірок auth, валідації env-marker та подібних поверхонь auth provider, які не повинні запускати середовище виконання plugin лише для перевірки назв env.
|
||||
- `providerAuthAliases` дозволяє варіантам provider повторно використовувати env vars auth, профілі auth, auth на основі конфігурації та варіант onboarding API key іншого provider без жорсткого кодування цього зв’язку в ядрі.
|
||||
- `providerEndpoints` дозволяє plugin provider володіти простими метаданими зіставлення host/baseUrl endpoint. Використовуйте це лише для класів endpoint, які ядро вже підтримує; поведінкою середовища виконання все одно володіє plugin.
|
||||
- `syntheticAuthRefs` — це дешевий шлях метаданих для синтетичних hook auth, що належать provider і мають бути видимими для холодного виявлення моделей до існування реєстру середовища виконання. Додавайте лише ті посилання, чий provider середовища виконання або backend CLI справді реалізує `resolveSyntheticAuth`.
|
||||
- `nonSecretAuthMarkers` — це дешевий шлях метаданих для значень-заповнювачів API key, що належать вбудованим plugin, наприклад маркерів локальних, OAuth або ambient credentials.
|
||||
Ядро трактує їх як несекретні для відображення auth і аудиту секретів без жорсткого кодування provider-власника.
|
||||
- `channelEnvVars` — це дешевий шлях метаданих для резервного використання shell-env, підказок setup та подібних поверхонь channel, які не повинні запускати середовище виконання plugin лише для перевірки назв env. Назви env є метаданими, а не активацією самі по собі: status, аудит, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри plugin та ефективної активації, перш ніж вважати env var налаштованим channel.
|
||||
- `providerAuthChoices` — це дешевий шлях метаданих для засобів вибору варіантів auth,
|
||||
визначення `--auth-choice`, зіставлення бажаного provider і простої реєстрації прапорців CLI onboarding до завантаження середовища виконання provider. Для метаданих wizard середовища виконання, які потребують коду provider, див.
|
||||
[Provider runtime hooks](/uk/plugins/architecture#provider-runtime-hooks).
|
||||
- Ексклюзивні типи plugin вибираються через `plugins.slots.*`.
|
||||
- Маніфест **є обов’язковим для власних плагінів OpenClaw**, включно із завантаженням із локальної файлової системи.
|
||||
- Середовище виконання все одно окремо завантажує модуль плагіна; маніфест використовується лише для виявлення + валідації.
|
||||
- Власні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок допускаються, якщо підсумкове значення все ще є об’єктом.
|
||||
- Завантажувач маніфесту зчитує лише задокументовані поля маніфесту. Уникайте додавання сюди власних ключів верхнього рівня.
|
||||
- `providerAuthEnvVars` — це недорогий шлях метаданих для перевірок автентифікації, валідації маркерів env та подібних поверхонь автентифікації провайдера, які не повинні запускати середовище виконання плагіна лише для перевірки назв env.
|
||||
- `providerAuthAliases` дозволяє варіантам провайдера повторно використовувати env vars автентифікації, профілі автентифікації, автентифікацію на основі конфігурації та варіант онбордингу API-ключа іншого провайдера без жорсткого кодування цього зв’язку в ядрі.
|
||||
- `providerEndpoints` дозволяє плагінам провайдерів володіти простими метаданими зіставлення хоста кінцевої точки/`baseUrl`. Використовуйте це лише для класів кінцевих точок, які ядро вже підтримує; поведінка середовища виконання, як і раніше, належить плагіну.
|
||||
- `syntheticAuthRefs` — це недорогий шлях метаданих для синтетичних хуків автентифікації, що належать провайдеру й мають бути видимими для холодного виявлення моделей до появи реєстру середовища виконання. Вказуйте лише ті посилання, чий провайдер середовища виконання або backend CLI справді реалізує `resolveSyntheticAuth`.
|
||||
- `nonSecretAuthMarkers` — це недорогий шлях метаданих для значень-заповнювачів API-ключів, що належать вбудованому плагіну, наприклад локальних маркерів, OAuth або маркерів ambient credential. Ядро трактує їх як не секретні для відображення автентифікації та аудиту секретів без жорсткого кодування провайдера-власника.
|
||||
- `channelEnvVars` — це недорогий шлях метаданих для резервного використання env оболонки, запитів налаштування та подібних поверхонь каналу, які не повинні запускати середовище виконання плагіна лише для перевірки назв env. Імена env є метаданими, а не активацією самі по собі: статус, аудит, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до плагіна й ефективної активації, перш ніж вважати env var налаштованим каналом.
|
||||
- `providerAuthChoices` — це недорогий шлях метаданих для засобів вибору варіантів автентифікації, визначення `--auth-choice`, зіставлення пріоритетного провайдера та простої реєстрації CLI flags онбордингу до завантаження середовища виконання провайдера. Метадані wizard середовища виконання, для яких потрібен код провайдера, див. у [Хуках середовища виконання провайдера](/uk/plugins/architecture#provider-runtime-hooks).
|
||||
- Ексклюзивні типи плагінів вибираються через `plugins.slots.*`.
|
||||
- `kind: "memory"` вибирається через `plugins.slots.memory`.
|
||||
- `kind: "context-engine"` вибирається через `plugins.slots.contextEngine`
|
||||
(типово: вбудований `legacy`).
|
||||
- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо plugin їх не потребує.
|
||||
- Якщо ваш plugin залежить від нативних модулів, задокументуйте кроки збирання та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts`
|
||||
- `kind: "context-engine"` вибирається через `plugins.slots.contextEngine` (типово: вбудований `legacy`).
|
||||
- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо плагіну вони не потрібні.
|
||||
- Якщо ваш плагін залежить від native modules, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts`
|
||||
- `pnpm rebuild <package>`).
|
||||
|
||||
## Пов’язані матеріали
|
||||
## Пов’язане
|
||||
|
||||
- [Building Plugins](/uk/plugins/building-plugins) — початок роботи з plugin
|
||||
- [Plugin Architecture](/uk/plugins/architecture) — внутрішня архітектура
|
||||
- [SDK Overview](/uk/plugins/sdk-overview) — довідник SDK Plugin
|
||||
- [Створення Plugins](/uk/plugins/building-plugins) — початок роботи з плагінами
|
||||
- [Архітектура Plugin](/uk/plugins/architecture) — внутрішня архітектура
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview) — довідник SDK Plugin
|
||||
|
||||
Loading…
Reference in New Issue
Block a user