chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
cf23bc0038
commit
8d141b9b7b
@ -1,21 +1,21 @@
|
||||
---
|
||||
read_when:
|
||||
- Додавання або змінення команд `openclaw infer`
|
||||
- Проєктування стабільної автоматизації можливостей без графічного інтерфейсу
|
||||
summary: CLI з визначенням передусім для робочих процесів із моделями, зображеннями, аудіо, TTS, відео, вебом і ембедингами на основі провайдера
|
||||
- Проєктування стабільної автоматизації headless-можливостей
|
||||
summary: CLI з автоматичним визначенням спочатку для робочих процесів моделей, зображень, аудіо, TTS, відео, вебу та ембедингів, що використовують провайдерів
|
||||
title: CLI для інференсу
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T22:06:12Z"
|
||||
generated_at: "2026-04-27T22:22:41Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 704f9ea60adb1b509f0b4f74ae79ffb70f12915a7e8a45d43ca28f5ac7d70af1
|
||||
source_hash: 5f9dc003af66692fe85d11c74ef952b72668aa7c715090b92ca5511f680a963d
|
||||
source_path: cli/infer.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
`openclaw infer` — це канонічна безграфічна поверхня для робочих процесів інференсу на основі провайдера.
|
||||
`openclaw infer` — це канонічна headless-поверхня для робочих процесів інференсу, що використовують провайдерів.
|
||||
|
||||
Вона навмисно надає сімейства можливостей, а не сирі назви Gateway RPC і не сирі ідентифікатори інструментів агента.
|
||||
Вона навмисно відкриває сімейства можливостей, а не сирі назви Gateway RPC і не сирі ідентифікатори інструментів агента.
|
||||
|
||||
## Перетворення infer на skill
|
||||
|
||||
@ -28,9 +28,9 @@ Focus on model runs, image generation, video generation, audio transcription, TT
|
||||
|
||||
Хороший skill на основі infer має:
|
||||
|
||||
- зіставляти поширені наміри користувача з правильною підкомандою infer
|
||||
- зіставляти поширені наміри користувача з правильним підкомандним рядком infer
|
||||
- містити кілька канонічних прикладів infer для робочих процесів, які він охоплює
|
||||
- надавати перевагу `openclaw infer ...` у прикладах і рекомендаціях
|
||||
- віддавати перевагу `openclaw infer ...` у прикладах і підказках
|
||||
- уникати повторного документування всієї поверхні infer всередині тіла skill
|
||||
|
||||
Типове охоплення skill, зосередженого на infer:
|
||||
@ -42,19 +42,19 @@ Focus on model runs, image generation, video generation, audio transcription, TT
|
||||
- `openclaw infer web search`
|
||||
- `openclaw infer embedding create`
|
||||
|
||||
## Чому варто використовувати infer
|
||||
## Навіщо використовувати infer
|
||||
|
||||
`openclaw infer` надає єдиний узгоджений CLI для завдань інференсу на основі провайдера всередині OpenClaw.
|
||||
`openclaw infer` надає єдиний узгоджений CLI для завдань інференсу, що використовують провайдерів, всередині OpenClaw.
|
||||
|
||||
Переваги:
|
||||
|
||||
- Використовуйте провайдерів і моделі, уже налаштовані в OpenClaw, замість створення одноразових обгорток для кожного бекенда.
|
||||
- Тримайте робочі процеси для моделей, зображень, транскрибування аудіо, TTS, відео, вебу та ембедингів в одному дереві команд.
|
||||
- Тримайте робочі процеси моделей, зображень, транскрибування аудіо, TTS, відео, вебу та ембедингів під одним деревом команд.
|
||||
- Використовуйте стабільну форму виводу `--json` для скриптів, автоматизації та робочих процесів, керованих агентом.
|
||||
- Надавайте перевагу першорядній поверхні OpenClaw, коли завдання за своєю суттю полягає в тому, щоб «виконати інференс».
|
||||
- Віддавайте перевагу first-party поверхні OpenClaw, коли завдання по суті полягає в тому, щоб «виконати інференс».
|
||||
- Використовуйте звичайний локальний шлях без потреби в Gateway для більшості команд infer.
|
||||
|
||||
Для наскрізних перевірок провайдера надавайте перевагу `openclaw infer ...`, коли тести провайдера нижчого рівня вже зелені. Це перевіряє постачений CLI, завантаження конфігурації, визначення агента за замовчуванням, активацію вбудованих плагінів, відновлення залежностей середовища виконання та спільне середовище виконання можливостей до того, як буде зроблено запит до провайдера.
|
||||
Для наскрізних перевірок провайдерів віддавайте перевагу `openclaw infer ...`, коли нижчорівневі тести провайдерів уже зелені. Це перевіряє поставлений CLI, завантаження конфігурації, визначення агента за замовчуванням, активацію вбудованих Plugin, відновлення залежностей середовища виконання та спільне середовище можливостей до виконання запиту до провайдера.
|
||||
|
||||
## Дерево команд
|
||||
|
||||
@ -113,33 +113,33 @@ Focus on model runs, image generation, video generation, audio transcription, TT
|
||||
|
||||
| Завдання | Команда | Примітки |
|
||||
| ----------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------- |
|
||||
| Запустити текстовий/модельний запит | `openclaw infer model run --prompt "..." --json` | За замовчуванням використовує звичайний локальний шлях |
|
||||
| Згенерувати зображення | `openclaw infer image generate --prompt "..." --json` | Використовуйте `image edit`, якщо починаєте з наявного файлу |
|
||||
| Описати файл зображення | `openclaw infer image describe --file ./image.png --json` | `--model` має бути зображувально-сумісним `<provider/model>` |
|
||||
| Транскрибувати аудіо | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` має бути `<provider/model>` |
|
||||
| Виконати текстовий/модельний запит | `openclaw infer model run --prompt "..." --json` | За замовчуванням використовує звичайний локальний шлях |
|
||||
| Згенерувати зображення | `openclaw infer image generate --prompt "..." --json` | Використовуйте `image edit`, якщо починаєте з наявного файла |
|
||||
| Описати файл зображення | `openclaw infer image describe --file ./image.png --json` | `--model` має бути image-capable у форматі `<provider/model>` |
|
||||
| Транскрибувати аудіо | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` має бути у форматі `<provider/model>` |
|
||||
| Синтезувати мовлення | `openclaw infer tts convert --text "..." --output ./speech.mp3 --json` | `tts status` орієнтовано на gateway |
|
||||
| Згенерувати відео | `openclaw infer video generate --prompt "..." --json` | Підтримує підказки провайдера, такі як `--resolution` |
|
||||
| Описати відеофайл | `openclaw infer video describe --file ./clip.mp4 --json` | `--model` має бути `<provider/model>` |
|
||||
| Шукати у вебі | `openclaw infer web search --query "..." --json` | |
|
||||
| Згенерувати відео | `openclaw infer video generate --prompt "..." --json` | Підтримує підказки для провайдерів, такі як `--resolution` |
|
||||
| Описати відеофайл | `openclaw infer video describe --file ./clip.mp4 --json` | `--model` має бути у форматі `<provider/model>` |
|
||||
| Виконати пошук у вебі | `openclaw infer web search --query "..." --json` | |
|
||||
| Отримати вебсторінку | `openclaw infer web fetch --url https://example.com --json` | |
|
||||
| Створити ембединги | `openclaw infer embedding create --text "..." --json` | |
|
||||
|
||||
## Поведінка
|
||||
|
||||
- `openclaw infer ...` є основною поверхнею CLI для цих робочих процесів.
|
||||
- Використовуйте `--json`, коли вивід буде споживатися іншою командою або скриптом.
|
||||
- `openclaw infer ...` — основна CLI-поверхня для цих робочих процесів.
|
||||
- Використовуйте `--json`, коли вивід споживатиметься іншою командою або скриптом.
|
||||
- Використовуйте `--provider` або `--model provider/model`, коли потрібен конкретний бекенд.
|
||||
- Для `image describe`, `audio transcribe` і `video describe` параметр `--model` має використовувати форму `<provider/model>`.
|
||||
- Для `image describe` явний `--model` запускає цей provider/model безпосередньо. Модель має підтримувати зображення в каталозі моделей або конфігурації провайдера. `codex/<model>` запускає обмежений хід розуміння зображень через сервер застосунку Codex; `openai-codex/<model>` використовує шлях провайдера OpenAI Codex OAuth.
|
||||
- Команди безстанового виконання за замовчуванням локальні.
|
||||
- Команди керованого Gateway стану за замовчуванням використовують gateway.
|
||||
- Звичайний локальний шлях не вимагає, щоб Gateway був запущений.
|
||||
- Локальний `model run` — це легковагове одноразове завершення через провайдера. Він визначає налаштовану модель агента й автентифікацію, але не запускає хід chat-агента, не завантажує інструменти і не відкриває вбудовані MCP-сервери.
|
||||
- `model run --gateway` усе ще використовує середовище виконання агента Gateway, тому може перевіряти той самий маршрутований шлях виконання, що й звичайний хід із підтримкою Gateway. MCP-сервери, відкриті через це середовище виконання, виводяться з експлуатації після відповіді, тож повторні виклики зі скриптів не залишають stdio MCP дочірні процеси активними.
|
||||
- Для `image describe` явний `--model` запускає цей provider/model безпосередньо. Модель має підтримувати роботу із зображеннями в каталозі моделей або конфігурації провайдера. `codex/<model>` запускає обмежений поворот app-server Codex для розуміння зображень; `openai-codex/<model>` використовує шлях провайдера OpenAI Codex OAuth.
|
||||
- Команди stateless-виконання за замовчуванням локальні.
|
||||
- Команди стану, керованого Gateway, за замовчуванням використовують gateway.
|
||||
- Звичайний локальний шлях не вимагає, щоб gateway був запущений.
|
||||
- Локальний `model run` — це легкий одноразовий provider completion. Він визначає налаштовану модель агента та auth, але не запускає поворот chat-agent, не завантажує інструменти й не відкриває вбудовані MCP-сервери.
|
||||
- `model run --gateway` усе одно використовує середовище агента Gateway, щоб перевіряти той самий маршрутизований шлях виконання, що й звичайний поворот із підтримкою Gateway. MCP-сервери, відкриті через це середовище виконання, завершуються після відповіді, тому повторні скриптові виклики не залишають stdio MCP дочірні процеси активними.
|
||||
|
||||
## Model
|
||||
|
||||
Використовуйте `model` для текстового інференсу на основі провайдера та перевірки моделей/провайдерів.
|
||||
Використовуйте `model` для текстового інференсу через провайдерів та перевірки моделей/провайдерів.
|
||||
|
||||
```bash
|
||||
openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json
|
||||
@ -148,7 +148,7 @@ openclaw infer model providers --json
|
||||
openclaw infer model inspect --name gpt-5.5 --json
|
||||
```
|
||||
|
||||
Використовуйте повні посилання `<provider/model>`, щоб перевірити конкретного провайдера без запуску Gateway або завантаження всієї поверхні інструментів агента:
|
||||
Використовуйте повні посилання `<provider/model>`, щоб виконати smoke-тест конкретного провайдера без запуску Gateway або завантаження повної поверхні інструментів агента:
|
||||
|
||||
```bash
|
||||
openclaw infer model run --local --model anthropic/claude-sonnet-4-6 --prompt "Reply with exactly: pong" --json
|
||||
@ -161,13 +161,14 @@ openclaw infer model run --local --model openai/gpt-4.1 --prompt "Reply with exa
|
||||
|
||||
Примітки:
|
||||
|
||||
- Локальний `model run` — це найвужча CLI-перевірка працездатності провайдера/моделі/автентифікації, оскільки він надсилає вибраній моделі лише наданий запит.
|
||||
- Використовуйте `model run --gateway`, коли потрібно перевірити маршрутизацію Gateway, налаштування середовища виконання агента або стан провайдера, керований Gateway, замість спрощеного локального шляху завершення.
|
||||
- `model auth login`, `model auth logout` і `model auth status` керують збереженим станом автентифікації провайдера.
|
||||
- Локальний `model run` — це найвужчий CLI smoke для перевірки стану провайдера/моделі/auth, оскільки він надсилає вибраній моделі лише переданий запит.
|
||||
- Локальний `model run` завершується з ненульовим кодом, коли провайдер не повертає текстовий результат, щоб недоступні локальні провайдери та порожні completion не виглядали як успішні перевірки.
|
||||
- Використовуйте `model run --gateway`, коли потрібно протестувати маршрутизацію Gateway, налаштування середовища агента або стан провайдера, керований Gateway, а не легкий локальний шлях completion.
|
||||
- `model auth login`, `model auth logout` і `model auth status` керують збереженим станом auth провайдера.
|
||||
|
||||
## Image
|
||||
|
||||
Використовуйте `image` для генерації, редагування й опису.
|
||||
Використовуйте `image` для генерації, редагування та опису.
|
||||
|
||||
```bash
|
||||
openclaw infer image generate --prompt "friendly lobster illustration" --json
|
||||
@ -184,10 +185,10 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --j
|
||||
Примітки:
|
||||
|
||||
- Використовуйте `image edit`, якщо починаєте з наявних вхідних файлів.
|
||||
- Використовуйте `--size`, `--aspect-ratio` або `--resolution` з `image edit` для провайдерів/моделей, які підтримують підказки геометрії під час редагування еталонних зображень.
|
||||
- Використовуйте `--output-format png --background transparent` з `--model openai/gpt-image-1.5` для PNG-виводу OpenAI із прозорим тлом; `--openai-background` лишається доступним як OpenAI-специфічний псевдонім. Провайдери, які не оголошують підтримку тла, повідомляють про цю підказку як про проігнороване перевизначення.
|
||||
- Використовуйте `image providers --json`, щоб перевірити, які вбудовані провайдери зображень можна виявити, налаштовано, вибрано, а також які можливості генерації/редагування надає кожен провайдер.
|
||||
- Використовуйте `image generate --model <provider/model> --json` як найвужчу живу CLI-перевірку для змін генерації зображень. Приклад:
|
||||
- Використовуйте `--size`, `--aspect-ratio` або `--resolution` з `image edit` для провайдерів/моделей, які підтримують підказки геометрії під час редагування за еталонним зображенням.
|
||||
- Використовуйте `--output-format png --background transparent` з `--model openai/gpt-image-1.5` для прозорого фону в PNG-виводі OpenAI; `--openai-background` залишається доступним як OpenAI-специфічний псевдонім. Провайдери, які не декларують підтримку фону, повідомляють про цю підказку як про проігнороване перевизначення.
|
||||
- Використовуйте `image providers --json`, щоб перевірити, які вбудовані провайдери зображень можна виявити, які налаштовано, які вибрано та які можливості генерації/редагування надає кожен провайдер.
|
||||
- Використовуйте `image generate --model <provider/model> --json` як найвужчий live CLI smoke для змін у генерації зображень. Приклад:
|
||||
|
||||
```bash
|
||||
openclaw infer image providers --json
|
||||
@ -198,10 +199,10 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --j
|
||||
--json
|
||||
```
|
||||
|
||||
JSON-відповідь повідомляє `ok`, `provider`, `model`, `attempts` і шляхи записаних вихідних файлів. Якщо встановлено `--output`, фінальне розширення може відповідати MIME-типу, поверненому провайдером.
|
||||
Відповідь JSON повідомляє `ok`, `provider`, `model`, `attempts` і шляхи записаного виводу. Якщо встановлено `--output`, остаточне розширення може відповідати MIME-типу, повернутому провайдером.
|
||||
|
||||
- Для `image describe` параметр `--model` має бути зображувально-сумісним `<provider/model>`.
|
||||
- Для локальних візуальних моделей Ollama спочатку завантажте модель і встановіть `OLLAMA_API_KEY` на будь-яке значення-заповнювач, наприклад `ollama-local`. Див. [Ollama](/uk/providers/ollama#vision-and-image-description).
|
||||
- Для `image describe` параметр `--model` має бути image-capable у форматі `<provider/model>`.
|
||||
- Для локальних vision-моделей Ollama спочатку завантажте модель і встановіть `OLLAMA_API_KEY` у будь-яке заповнювальне значення, наприклад `ollama-local`. Див. [Ollama](/uk/providers/ollama#vision-and-image-description).
|
||||
|
||||
## Audio
|
||||
|
||||
@ -216,11 +217,11 @@ openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --jso
|
||||
Примітки:
|
||||
|
||||
- `audio transcribe` призначено для транскрибування файлів, а не для керування сеансами в реальному часі.
|
||||
- `--model` має бути `<provider/model>`.
|
||||
- `--model` має бути у форматі `<provider/model>`.
|
||||
|
||||
## TTS
|
||||
|
||||
Використовуйте `tts` для синтезу мовлення та стану провайдера TTS.
|
||||
Використовуйте `tts` для синтезу мовлення та стану TTS-провайдера.
|
||||
|
||||
```bash
|
||||
openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --json
|
||||
@ -232,11 +233,11 @@ openclaw infer tts status --json
|
||||
Примітки:
|
||||
|
||||
- `tts status` за замовчуванням використовує gateway, оскільки відображає стан TTS, керований gateway.
|
||||
- Використовуйте `tts providers`, `tts voices` і `tts set-provider`, щоб перевіряти та налаштовувати поведінку TTS.
|
||||
- Використовуйте `tts providers`, `tts voices` і `tts set-provider` для перевірки та налаштування поведінки TTS.
|
||||
|
||||
## Video
|
||||
|
||||
Використовуйте `video` для генерації й опису.
|
||||
Використовуйте `video` для генерації та опису.
|
||||
|
||||
```bash
|
||||
openclaw infer video generate --prompt "cinematic sunset over the ocean" --json
|
||||
@ -248,11 +249,11 @@ openclaw infer video describe --file ./clip.mp4 --model openai/gpt-4.1-mini --js
|
||||
Примітки:
|
||||
|
||||
- `video generate` приймає `--size`, `--aspect-ratio`, `--resolution`, `--duration`, `--audio`, `--watermark` і `--timeout-ms` та передає їх у середовище виконання генерації відео.
|
||||
- Для `video describe` параметр `--model` має бути `<provider/model>`.
|
||||
- Для `video describe` параметр `--model` має бути у форматі `<provider/model>`.
|
||||
|
||||
## Web
|
||||
|
||||
Використовуйте `web` для робочих процесів пошуку та отримання даних.
|
||||
Використовуйте `web` для робочих процесів пошуку та отримання вмісту.
|
||||
|
||||
```bash
|
||||
openclaw infer web search --query "OpenClaw docs" --json
|
||||
@ -302,7 +303,7 @@ openclaw infer embedding providers --json
|
||||
- `outputs`
|
||||
- `error`
|
||||
|
||||
Для команд генерації медіа `outputs` містить файли, записані OpenClaw. Використовуйте `path`, `mimeType`, `size` і будь-які специфічні для медіа розміри в цьому масиві для автоматизації замість аналізу придатного для читання людиною stdout.
|
||||
Для команд генерації медіа `outputs` містить файли, записані OpenClaw. Використовуйте `path`, `mimeType`, `size` і будь-які специфічні для медіа розміри в цьому масиві для автоматизації замість розбору людиночитного stdout.
|
||||
|
||||
## Поширені помилки
|
||||
|
||||
@ -326,7 +327,7 @@ openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --jso
|
||||
|
||||
- `openclaw capability ...` є псевдонімом для `openclaw infer ...`.
|
||||
|
||||
## Пов’язане
|
||||
## Пов’язані матеріали
|
||||
|
||||
- [Довідник CLI](/uk/cli)
|
||||
- [Моделі](/uk/concepts/models)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- Додавання або змінення міграцій Doctor
|
||||
- Додавання або змінення міграцій doctor
|
||||
- Запровадження несумісних змін конфігурації
|
||||
sidebarTitle: Doctor
|
||||
summary: 'Команда Doctor: перевірки стану, міграції конфігурації та кроки відновлення'
|
||||
summary: 'Команда doctor: перевірки стану, міграції конфігурації та кроки відновлення'
|
||||
title: Doctor
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T14:18:20Z"
|
||||
generated_at: "2026-04-27T22:22:40Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 1f3a009131c28a0574ce2bb055beecbb321e1664d1ab5b611c64c3f548cda1c6
|
||||
source_hash: 5af15cf2f9616286d601518872b736c9e07d5aabb4943c483bd35aa9e3bdc77a
|
||||
source_path: gateway/doctor.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілу конфігурацію/стан, перевіряє стан системи та надає практичні кроки для відновлення.
|
||||
`openclaw doctor` — це інструмент відновлення + міграції для OpenClaw. Він виправляє застарілу конфігурацію/стан, перевіряє стан системи та надає практичні кроки для відновлення.
|
||||
|
||||
## Швидкий старт
|
||||
## Швидкий початок
|
||||
|
||||
```bash
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
### Режими без взаємодії та автоматизації
|
||||
### Безголовий режим і режими автоматизації
|
||||
|
||||
<Tabs>
|
||||
<Tab title="--yes">
|
||||
@ -30,7 +30,7 @@ openclaw doctor
|
||||
openclaw doctor --yes
|
||||
```
|
||||
|
||||
Прийняти типові значення без запитів (зокрема кроки відновлення перезапуску/служби/sandbox, коли це застосовно).
|
||||
Прийняти значення за замовчуванням без запитів (зокрема кроки відновлення для перезапуску/служб/пісочниці, якщо застосовно).
|
||||
|
||||
</Tab>
|
||||
<Tab title="--repair">
|
||||
@ -46,7 +46,7 @@ openclaw doctor
|
||||
openclaw doctor --repair --force
|
||||
```
|
||||
|
||||
Також застосувати агресивні виправлення (перезаписує власні конфігурації supervisor).
|
||||
Також застосувати агресивні виправлення (перезаписує користувацькі конфігурації supervisor).
|
||||
|
||||
</Tab>
|
||||
<Tab title="--non-interactive">
|
||||
@ -54,7 +54,7 @@ openclaw doctor
|
||||
openclaw doctor --non-interactive
|
||||
```
|
||||
|
||||
Запустити без запитів і застосувати лише безпечні міграції (нормалізація конфігурації + перенесення стану на диску). Пропускає дії з перезапуском/службами/sandbox, які потребують підтвердження людини. Міграції застарілого стану запускаються автоматично, якщо їх виявлено.
|
||||
Запуск без запитів і застосування лише безпечних міграцій (нормалізація конфігурації + переміщення стану на диску). Пропускає дії перезапуску/служб/пісочниці, які потребують підтвердження людиною. Міграції застарілого стану автоматично виконуються, якщо їх виявлено.
|
||||
|
||||
</Tab>
|
||||
<Tab title="--deep">
|
||||
@ -62,7 +62,7 @@ openclaw doctor
|
||||
openclaw doctor --deep
|
||||
```
|
||||
|
||||
Сканувати системні служби на наявність додаткових встановлень Gateway (launchd/systemd/schtasks).
|
||||
Просканувати системні служби на наявність додаткових встановлень Gateway (launchd/systemd/schtasks).
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@ -79,101 +79,101 @@ cat ~/.openclaw/openclaw.json
|
||||
<Accordion title="Стан системи, UI та оновлення">
|
||||
- Необов’язкове попереднє оновлення для git-встановлень (лише в інтерактивному режимі).
|
||||
- Перевірка актуальності протоколу UI (перебудовує Control UI, якщо схема протоколу новіша).
|
||||
- Перевірка стану системи + запит на перезапуск.
|
||||
- Зведення стану Skills (доступні/відсутні/заблоковані) та стану Plugin.
|
||||
- Перевірка стану + запит на перезапуск.
|
||||
- Підсумок стану Skills (доступні/відсутні/заблоковані) і стану plugin.
|
||||
</Accordion>
|
||||
<Accordion title="Конфігурація та міграції">
|
||||
- Нормалізація конфігурації для застарілих значень.
|
||||
- Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.<provider>`.
|
||||
- Перевірки міграції browser для застарілих конфігурацій розширення Chrome і готовності Chrome MCP.
|
||||
- Міграція конфігурації Talk зі старих плоских полів `talk.*` у `talk.provider` + `talk.providers.<provider>`.
|
||||
- Перевірки міграції браузера для застарілих конфігурацій розширення Chrome та готовності Chrome MCP.
|
||||
- Попередження про перевизначення провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
|
||||
- Попередження про затінення Codex OAuth (`models.providers.openai-codex`).
|
||||
- Перевірка передумов OAuth TLS для профілів OpenAI Codex OAuth.
|
||||
- Міграція застарілого стану на диску (сесії/каталог агента/автентифікація WhatsApp).
|
||||
- Міграція ключів контракту маніфеста застарілого Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
|
||||
- Міграція сховища застарілого Cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, `provider` у payload, прості fallback-завдання Webhook із `notify: true`).
|
||||
- Міграція застарілої runtime-policy агента до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`.
|
||||
- Попередження про перекриття Codex OAuth (`models.providers.openai-codex`).
|
||||
- Перевірка TLS-передумов OAuth для профілів OpenAI Codex OAuth.
|
||||
- Міграція застарілого стану на диску (sessions/каталог agent/автентифікація WhatsApp).
|
||||
- Міграція ключів контрактів маніфесту застарілого plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
|
||||
- Міграція сховища застарілого Cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, `provider` у payload, прості резервні Webhook-завдання `notify: true`).
|
||||
- Міграція застарілої політики виконання agent до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`.
|
||||
</Accordion>
|
||||
<Accordion title="Стан і цілісність">
|
||||
- Перевірка файлів блокування сесій і очищення застарілих блокувань.
|
||||
- Відновлення транскриптів сесій для дубльованих гілок prompt-rewrite, створених у вразливих збірках 2026.4.24.
|
||||
- Перевірки цілісності стану та прав доступу (сесії, транскрипти, каталог стану).
|
||||
- Перевірки прав доступу до файлу конфігурації (`chmod 600`) під час локального запуску.
|
||||
- Стан автентифікації моделей: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє про стани cooldown/disabled профілю автентифікації.
|
||||
- Відновлення транскриптів сесій для дубльованих гілок переписування промптів, створених у вразливих збірках 2026.4.24.
|
||||
- Перевірки цілісності стану та дозволів (sessions, transcripts, каталог стану).
|
||||
- Перевірки дозволів файла конфігурації (chmod 600) під час локального запуску.
|
||||
- Стан автентифікації моделей: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє про стани cooldown/disabled для auth-profile.
|
||||
- Виявлення додаткового каталогу робочого простору (`~/openclaw`).
|
||||
</Accordion>
|
||||
<Accordion title="Gateway, служби та supervisor">
|
||||
- Відновлення образу sandbox, коли sandboxing увімкнено.
|
||||
- Відновлення образу пісочниці, коли пісочниця ввімкнена.
|
||||
- Міграція застарілих служб і виявлення додаткових Gateway.
|
||||
- Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`).
|
||||
- Перевірки runtime Gateway (службу встановлено, але не запущено; кешована мітка launchd).
|
||||
- Попередження про стан каналу (перевіряються з запущеного Gateway).
|
||||
- Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим виправленням.
|
||||
- Очищення змінних середовища вбудованого proxy для служб Gateway, які підхопили значення оболонки `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час встановлення або оновлення.
|
||||
- Перевірки рекомендованих практик runtime Gateway (Node проти Bun, шляхи менеджера версій).
|
||||
- Діагностика конфліктів портів Gateway (типово `18789`).
|
||||
- Перевірки середовища виконання Gateway (службу встановлено, але не запущено; кешована мітка launchd).
|
||||
- Попередження про стан каналів (перевіряються через запущений Gateway).
|
||||
- Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим відновленням.
|
||||
- Очищення змінних середовища вбудованого проксі для служб Gateway, які підхопили значення оболонки `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час встановлення або оновлення.
|
||||
- Перевірки найкращих практик середовища виконання Gateway (Node проти Bun, шляхи менеджера версій).
|
||||
- Діагностика конфліктів порту Gateway (типово `18789`).
|
||||
</Accordion>
|
||||
<Accordion title="Автентифікація, безпека та сполучення">
|
||||
- Попередження безпеки для відкритих політик DM.
|
||||
- Перевірки автентифікації Gateway для локального режиму токена (пропонує згенерувати токен, якщо джерело токена відсутнє; не перезаписує конфігурації token SecretRef).
|
||||
- Виявлення проблем зі сполученням пристроїв (очікувані перші запити на сполучення, очікувані оновлення ролі/обсягу доступу, застарілий дрейф локального кешу токенів пристрою та дрейф автентифікації запису сполучення).
|
||||
- Перевірки автентифікації Gateway для режиму локального токена (пропонує згенерувати токен, якщо джерело токена відсутнє; не перезаписує конфігурації token SecretRef).
|
||||
- Виявлення проблем зі сполученням пристроїв (очікувані запити на перше сполучення, очікувані оновлення ролей/областей дії, застарілий дрейф локального кешу токенів пристрою та дрейф автентифікації запису сполучення).
|
||||
</Accordion>
|
||||
<Accordion title="Робочий простір і оболонка">
|
||||
- Перевірка systemd linger у Linux.
|
||||
- Перевірка розміру bootstrap-файлу робочого простору (попередження про обрізання/наближення до ліміту для контекстних файлів).
|
||||
- Перевірка стану completion оболонки та автоматичне встановлення/оновлення.
|
||||
- Перевірка готовності провайдера вбудовувань для пошуку в пам’яті (локальна модель, ключ віддаленого API або двійковий файл QMD).
|
||||
- Перевірки source-встановлення (невідповідність робочого простору pnpm, відсутні assets UI, відсутній двійковий файл tsx).
|
||||
- Записує оновлену конфігурацію та метадані wizard.
|
||||
- Перевірка розміру файлів bootstrap робочого простору (попередження про обрізання/наближення до ліміту для контекстних файлів).
|
||||
- Перевірка стану shell completion і автоматичне встановлення/оновлення.
|
||||
- Перевірка готовності провайдера embedding для пошуку в пам’яті (локальна модель, віддалений API key або двійковий файл QMD).
|
||||
- Перевірки source-встановлення (невідповідність робочого простору pnpm, відсутні ресурси UI, відсутній двійковий файл tsx).
|
||||
- Записує оновлену конфігурацію + метадані майстра.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Зворотне заповнення та скидання Dreams UI
|
||||
|
||||
Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для робочого процесу grounded Dreaming. Ці дії використовують RPC-методи у стилі doctor для Gateway, але вони **не** є частиною відновлення/міграції CLI `openclaw doctor`.
|
||||
Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для робочого процесу grounded dreaming. Ці дії використовують RPC-методи в стилі doctor для Gateway, але вони **не** є частиною відновлення/міграції CLI `openclaw doctor`.
|
||||
|
||||
Що вони роблять:
|
||||
|
||||
- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному робочому просторі, запускає grounded REM diary pass і записує зворотні записи backfill у `DREAMS.md`.
|
||||
- **Reset** видаляє з `DREAMS.md` лише ті записи щоденника backfill, що мають відповідну позначку.
|
||||
- **Clear Grounded** видаляє лише staged short-term записи, призначені тільки для grounded, які походять з історичного відтворення і ще не накопичили live recall або щоденної підтримки.
|
||||
- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному робочому просторі, запускає grounded REM diary pass і записує оборотні записи зворотного заповнення в `DREAMS.md`.
|
||||
- **Reset** видаляє з `DREAMS.md` лише ті позначені записи щоденника зворотного заповнення.
|
||||
- **Clear Grounded** видаляє лише staged grounded-only short-term entries, які надійшли з історичного відтворення і ще не накопичили live recall або daily support.
|
||||
|
||||
Чого вони самі по собі **не** роблять:
|
||||
|
||||
- вони не редагують `MEMORY.md`
|
||||
- вони не запускають повні міграції doctor
|
||||
- вони не переносять автоматично grounded candidates у live short-term promotion store, якщо ви явно не запустите спочатку staged CLI path
|
||||
- вони не переводять автоматично grounded candidates до live short-term promotion store, якщо ви явно не запустите спочатку staged CLI path
|
||||
|
||||
Якщо ви хочете, щоб grounded historical replay впливало на звичайний deep promotion lane, натомість використовуйте потік CLI:
|
||||
Якщо ви хочете, щоб grounded historical replay вплинув на звичайний deep promotion lane, натомість використовуйте CLI-процес:
|
||||
|
||||
```bash
|
||||
openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
```
|
||||
|
||||
Це переносить grounded durable candidates у short-term dreaming store, залишаючи `DREAMS.md` як поверхню для перегляду.
|
||||
Це переводить grounded durable candidates до short-term dreaming store, зберігаючи `DREAMS.md` як поверхню для перегляду.
|
||||
|
||||
## Детальна поведінка та обґрунтування
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="0. Необов’язкове оновлення (git-встановлення)">
|
||||
Якщо це git checkout і doctor запущено в інтерактивному режимі, він пропонує оновити систему (fetch/rebase/build) перед запуском doctor.
|
||||
Якщо це git checkout і doctor запущено в інтерактивному режимі, він пропонує оновитися (fetch/rebase/build) перед запуском doctor.
|
||||
</Accordion>
|
||||
<Accordion title="1. Нормалізація конфігурації">
|
||||
Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без перевизначення для конкретного каналу), doctor нормалізує їх до поточної схеми.
|
||||
|
||||
Це також охоплює застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.<provider>`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у мапу провайдерів.
|
||||
Це також включає застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.<provider>`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у карту провайдера.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2. Міграції ключів застарілої конфігурації">
|
||||
Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися і просять виконати `openclaw doctor`.
|
||||
Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися і просять вас виконати `openclaw doctor`.
|
||||
|
||||
Doctor виконає таке:
|
||||
Doctor:
|
||||
|
||||
- Пояснить, які застарілі ключі було знайдено.
|
||||
- Покажe міграцію, яку він застосував.
|
||||
- Покажe міграцію, яку було застосовано.
|
||||
- Перезапише `~/.openclaw/openclaw.json` з оновленою схемою.
|
||||
|
||||
Gateway також автоматично запускає міграції doctor під час старту, коли виявляє застарілий формат конфігурації, тож застарілі конфігурації виправляються без ручного втручання. Міграції сховища завдань Cron обробляються командою `openclaw doctor --fix`.
|
||||
Gateway також автоматично запускає міграції doctor під час старту, коли виявляє застарілий формат конфігурації, тож застарілі конфігурації виправляються без ручного втручання. Міграції сховища Cron обробляються командою `openclaw doctor --fix`.
|
||||
|
||||
Поточні міграції:
|
||||
|
||||
@ -182,7 +182,7 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
|
||||
- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
|
||||
- `routing.queue` → `messages.queue`
|
||||
- `routing.bindings` → верхньорівневий `bindings`
|
||||
- `routing.bindings` → `bindings` верхнього рівня
|
||||
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
|
||||
- застарілі `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
|
||||
- `routing.agentToAgent` → `tools.agentToAgent`
|
||||
@ -198,87 +198,87 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
|
||||
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
|
||||
- `bindings[].match.accountID` → `bindings[].match.accountId`
|
||||
- Для каналів з іменованими `accounts`, але із залишковими однокористувацькими верхньорівневими значеннями каналу, перенести ці значення, прив’язані до облікового запису, до просунутого облікового запису, вибраного для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/типову ціль)
|
||||
- Для каналів з іменованими `accounts`, але зі збереженими значеннями каналу верхнього рівня для одного облікового запису, перемістити ці значення рівня облікового запису до просунутого облікового запису, вибраного для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну ціль named/default)
|
||||
- `identity` → `agents.list[].identity`
|
||||
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
|
||||
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
|
||||
- видалити `agents.defaults.llm`; використовуйте `models.providers.<id>.timeoutSeconds` для тайм-аутів повільних провайдерів/моделей
|
||||
- видалити `agents.defaults.llm`; для тайм-аутів повільних провайдерів/моделей використовуйте `models.providers.<id>.timeoutSeconds`
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
|
||||
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
|
||||
- видалити `browser.relayBindHost` (застаріле налаштування relay для розширення)
|
||||
- застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (під час старту Gateway також пропускає провайдерів, чий `api` має майбутнє або невідоме enum-значення, замість того щоб аварійно завершувати роботу)
|
||||
- видалити `browser.relayBindHost` (застарілий параметр relay розширення)
|
||||
- застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (під час старту Gateway також пропускає провайдерів, у яких `api` встановлено на майбутнє або невідоме значення enum, замість повної відмови)
|
||||
|
||||
Попередження doctor також містять рекомендації щодо типового облікового запису для багатокористувацьких каналів:
|
||||
Попередження doctor також містять рекомендації щодо облікового запису за замовчуванням для багатoоблікових каналів:
|
||||
|
||||
- Якщо налаштовано два або більше записи в `channels.<channel>.accounts` без `channels.<channel>.defaultAccount` або `accounts.default`, doctor попереджає, що fallback-маршрутизація може вибрати неочікуваний обліковий запис.
|
||||
- Якщо `channels.<channel>.defaultAccount` вказує на невідомий ID облікового запису, doctor попереджає про це та перелічує налаштовані ID облікових записів.
|
||||
- Якщо налаштовано два або більше записи `channels.<channel>.accounts` без `channels.<channel>.defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис.
|
||||
- Якщо `channels.<channel>.defaultAccount` встановлено на невідомий ID облікового запису, doctor попереджає й перелічує налаштовані ID облікових записів.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2b. Перевизначення провайдера OpenCode">
|
||||
Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. Це може примусово спрямувати моделі на неправильний API або обнулити вартість. Doctor попереджає про це, щоб ви могли прибрати перевизначення і відновити маршрутизацію API та вартість для кожної моделі.
|
||||
Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. Це може примусово спрямувати моделі на неправильний API або обнулити вартість. Doctor попереджає про це, щоб ви могли прибрати перевизначення та відновити маршрутизацію API + вартість для кожної моделі.
|
||||
</Accordion>
|
||||
<Accordion title="2c. Міграція browser і готовність Chrome MCP">
|
||||
Якщо ваша конфігурація browser досі вказує на вилучений шлях розширення Chrome, doctor нормалізує її до поточної моделі підключення host-local Chrome MCP:
|
||||
<Accordion title="2c. Міграція браузера та готовність Chrome MCP">
|
||||
Якщо конфігурація браузера все ще вказує на вилучений шлях розширення Chrome, doctor нормалізує її до поточної моделі підключення Chrome MCP на локальному хості:
|
||||
|
||||
- `browser.profiles.*.driver: "extension"` стає `"existing-session"`
|
||||
- `browser.relayBindHost` видаляється
|
||||
|
||||
Doctor також перевіряє шлях host-local Chrome MCP, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`:
|
||||
Doctor також перевіряє шлях Chrome MCP на локальному хості, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`:
|
||||
|
||||
- перевіряє, чи встановлено Google Chrome на тому самому хості для типових профілів автопідключення
|
||||
- перевіряє, чи встановлено Google Chrome на тому самому хості для профілів автоматичного підключення за замовчуванням
|
||||
- перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144
|
||||
- нагадує увімкнути remote debugging на сторінці inspect браузера (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`)
|
||||
- нагадує ввімкнути remote debugging на сторінці інспектування браузера (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`)
|
||||
|
||||
Doctor не може увімкнути це налаштування на боці Chrome за вас. Host-local Chrome MCP усе ще вимагає:
|
||||
Doctor не може ввімкнути цей параметр у Chrome за вас. Chrome MCP на локальному хості все ще вимагає:
|
||||
|
||||
- браузер на основі Chromium 144+ на хості gateway/node
|
||||
- щоб браузер працював локально
|
||||
- браузер на базі Chromium 144+ на хості gateway/node
|
||||
- локально запущений браузер
|
||||
- увімкнений remote debugging у цьому браузері
|
||||
- схвалення першого запиту згоди на attach у браузері
|
||||
- підтвердження першого запиту на згоду підключення в браузері
|
||||
|
||||
Готовність тут стосується лише передумов локального attach. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, усе ще потребують керованого browser або raw CDP profile.
|
||||
Готовність тут стосується лише передумов для локального підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, усе ще вимагають керованого браузера або профілю raw CDP.
|
||||
|
||||
Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших headless-потоків. Вони й надалі використовують raw CDP.
|
||||
Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших безголових сценаріїв. Вони й надалі використовують raw CDP.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2d. Передумови OAuth TLS">
|
||||
Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє endpoint авторизації OpenAI, щоб переконатися, що локальний стек TLS Node/OpenSSL може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або self-signed cert), doctor виводить платформо-специфічні вказівки щодо виправлення. На macOS із Node, встановленим через Homebrew, виправленням зазвичай є `brew postinstall ca-certificates`. Із `--deep` перевірка виконується навіть тоді, коли Gateway справний.
|
||||
<Accordion title="2d. Передумови TLS для OAuth">
|
||||
Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє кінцеву точку авторизації OpenAI, щоб упевнитися, що локальний стек TLS Node/OpenSSL може валідувати ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або self-signed cert), doctor виводить інструкції з виправлення для конкретної платформи. На macOS з Homebrew Node виправленням зазвичай є `brew postinstall ca-certificates`. З `--deep` перевірка виконується навіть якщо Gateway у нормальному стані.
|
||||
</Accordion>
|
||||
<Accordion title="2e. Перевизначення провайдера Codex OAuth">
|
||||
Якщо ви раніше додавали застарілі параметри транспорту OpenAI у `models.providers.openai-codex`, вони можуть затіняти вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі параметри транспорту разом із Codex OAuth, щоб ви могли видалити або переписати застаріле перевизначення транспорту й повернути вбудовану поведінку маршрутизації/fallback. Власні proxy та перевизначення лише заголовків усе ще підтримуються і не викликають це попередження.
|
||||
Якщо ви раніше додали застарілі параметри транспорту OpenAI у `models.providers.openai-codex`, вони можуть перекривати шлях вбудованого провайдера Codex OAuth, який новіші релізи використовують автоматично. Doctor попереджає, коли бачить ці старі параметри транспорту поруч із Codex OAuth, щоб ви могли прибрати або переписати застаріле перевизначення транспорту та повернути вбудовану поведінку маршрутизації/резервного переходу. Користувацькі проксі та перевизначення лише заголовків, як і раніше, підтримуються та не викликають цього попередження.
|
||||
</Accordion>
|
||||
<Accordion title="2f. Попередження щодо маршрутів Plugin Codex">
|
||||
Коли вбудований Plugin Codex увімкнено, doctor також перевіряє, чи посилання на основну модель `openai-codex/*` усе ще розв’язуються через типовий раннер PI. Така комбінація допустима, якщо ви хочете автентифікацію Codex OAuth/subscription через PI, але її легко сплутати з власною app-server harness Codex. Doctor попереджає про це й указує на явну форму app-server: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`.
|
||||
<Accordion title="2f. Попередження про маршрути plugin Codex">
|
||||
Коли ввімкнено bundled plugin Codex, doctor також перевіряє, чи первинні посилання на моделі `openai-codex/*` і далі розв’язуються через стандартний PI runner. Така комбінація є коректною, якщо ви хочете використовувати автентифікацію Codex OAuth/subscription через PI, але її легко сплутати з нативним app-server harness Codex. Doctor попереджає про це і вказує на явну форму app-server: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`.
|
||||
|
||||
Doctor не виправляє це автоматично, тому що обидва маршрути є дійсними:
|
||||
Doctor не виправляє це автоматично, оскільки обидва маршрути є коректними:
|
||||
|
||||
- `openai-codex/*` + PI означає "використовувати автентифікацію Codex OAuth/subscription через звичайний раннер OpenClaw."
|
||||
- `openai/*` + `runtime: "codex"` означає "запускати вбудований хід через власний app-server Codex."
|
||||
- `/codex ...` означає "керувати або прив’язати власну розмову Codex із чату."
|
||||
- `/acp ...` або `runtime: "acp"` означає "використовувати зовнішній адаптер ACP/acpx."
|
||||
- `openai-codex/*` + PI означає «використовувати автентифікацію Codex OAuth/subscription через звичайний runner OpenClaw».
|
||||
- `openai/*` + `runtime: "codex"` означає «запустити вбудований turn через нативний app-server Codex».
|
||||
- `/codex ...` означає «керувати нативною розмовою Codex з чату або прив’язати її».
|
||||
- `/acp ...` або `runtime: "acp"` означає «використовувати зовнішній адаптер ACP/acpx».
|
||||
|
||||
Якщо з’являється це попередження, виберіть маршрут, який ви мали на увазі, і відредагуйте конфігурацію вручну. Залишайте попередження як є, якщо PI Codex OAuth задумано навмисно.
|
||||
Якщо з’являється це попередження, виберіть маршрут, який ви мали на увазі, і відредагуйте конфігурацію вручну. Залиште попередження без змін, якщо PI Codex OAuth використовується навмисно.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3. Міграції застарілого стану (структура на диску)">
|
||||
Doctor може переносити старіші структури на диску до поточної структури:
|
||||
Doctor може мігрувати старіші структури на диску до поточної:
|
||||
|
||||
- Сховище сесій + транскрипти:
|
||||
- з `~/.openclaw/sessions/` до `~/.openclaw/agents/<agentId>/sessions/`
|
||||
- Каталог агента:
|
||||
- Каталог agent:
|
||||
- з `~/.openclaw/agent/` до `~/.openclaw/agents/<agentId>/agent/`
|
||||
- Стан автентифікації WhatsApp (Baileys):
|
||||
- із застарілого `~/.openclaw/credentials/*.json` (крім `oauth.json`)
|
||||
- зі старих `~/.openclaw/credentials/*.json` (крім `oauth.json`)
|
||||
- до `~/.openclaw/credentials/whatsapp/<accountId>/...` (типовий ID облікового запису: `default`)
|
||||
|
||||
Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor виводить попередження, якщо залишає будь-які застарілі каталоги як резервні копії. Gateway/CLI також автоматично переносить застарілі сесії + каталог агента під час старту, тож історія/автентифікація/моделі потрапляють у шлях конкретного агента без ручного запуску doctor. Автентифікація WhatsApp навмисно переноситься лише через `openclaw doctor`. Нормалізація Talk provider/provider-map тепер порівнює за структурною рівністю, тож відмінності лише в порядку ключів більше не спричиняють повторні no-op зміни `doctor --fix`.
|
||||
Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor виведе попередження, якщо залишить якісь застарілі каталоги як резервні копії. Gateway/CLI також автоматично мігрує застарілі сесії + каталог agent під час запуску, тож історія/автентифікація/моделі потрапляють до шляху конкретного agent без ручного запуску doctor. Автентифікація WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація провайдера/карти провайдерів Talk тепер порівнюється за структурною рівністю, тому відмінності лише в порядку ключів більше не спричиняють повторних порожніх змін `doctor --fix`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3a. Міграції маніфеста застарілого Plugin">
|
||||
Doctor сканує всі встановлені маніфести Plugin на наявність застарілих ключів можливостей верхнього рівня (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Якщо такі знайдено, він пропонує перемістити їх в об’єкт `contracts` і переписати файл маніфеста на місці. Ця міграція є ідемпотентною; якщо ключ `contracts` уже містить ті самі значення, застарілий ключ видаляється без дублювання даних.
|
||||
<Accordion title="3a. Міграції застарілих маніфестів plugin">
|
||||
Doctor сканує всі встановлені маніфести plugin на наявність застарілих ключів можливостей верхнього рівня (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Якщо їх знайдено, він пропонує перемістити їх до об’єкта `contracts` і переписати файл маніфесту на місці. Ця міграція є ідемпотентною; якщо ключ `contracts` уже містить ті самі значення, застарілий ключ видаляється без дублювання даних.
|
||||
</Accordion>
|
||||
<Accordion title="3b. Міграції сховища застарілого Cron">
|
||||
Doctor також перевіряє сховище завдань Cron (`~/.openclaw/cron/jobs.json` типово, або `cron.store`, якщо його перевизначено) на наявність старих форм завдань, які scheduler досі приймає для сумісності.
|
||||
Doctor також перевіряє сховище завдань Cron (`~/.openclaw/cron/jobs.json` за замовчуванням або `cron.store`, якщо його перевизначено) на старі форми завдань, які планувальник усе ще приймає для сумісності.
|
||||
|
||||
Поточні очищення Cron включають:
|
||||
|
||||
@ -287,194 +287,197 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
- поля payload верхнього рівня (`message`, `model`, `thinking`, ...) → `payload`
|
||||
- поля delivery верхнього рівня (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
|
||||
- псевдоніми delivery `provider` у payload → явний `delivery.channel`
|
||||
- прості застарілі fallback-завдання Webhook з `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook`
|
||||
- прості застарілі резервні Webhook-завдання `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook`
|
||||
|
||||
Doctor автоматично переносить завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий fallback notify з наявним режимом delivery, відмінним від Webhook, doctor попереджає про це і залишає таке завдання для ручної перевірки.
|
||||
Doctor автоматично мігрує завдання `notify: true` лише тоді, коли це можна зробити без зміни поведінки. Якщо завдання поєднує застарілий резервний notify з наявним режимом delivery не через webhook, doctor попереджає й залишає це завдання для ручної перевірки.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3c. Очищення блокувань сесій">
|
||||
Doctor сканує каталог сесій кожного агента на наявність застарілих файлів блокування запису — файлів, що залишилися після аварійного завершення сесії. Для кожного знайденого файлу блокування він повідомляє: шлях, PID, чи PID усе ще активний, вік блокування та чи вважається воно застарілим (мертвий PID або старше 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше виводить примітку та радить запустити команду повторно з `--fix`.
|
||||
Doctor сканує каталог сесій кожного agent на наявність застарілих write-lock файлів — файлів, що залишилися після аварійного завершення сесії. Для кожного знайденого файла блокування він повідомляє: шлях, PID, чи цей PID ще активний, вік блокування та чи вважається воно застарілим (мертвий PID або старше 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше виводить примітку та пропонує повторно запустити з `--fix`.
|
||||
</Accordion>
|
||||
<Accordion title="3d. Відновлення гілок транскриптів сесій">
|
||||
Doctor сканує JSONL-файли сесій агента на наявність дубльованої форми гілок, створеної багом переписування prompt transcript у версії 2026.4.24: покинутий хід користувача з внутрішнім runtime context OpenClaw плюс активний сусідній запис із тим самим видимим запитом користувача. У режимі `--fix` / `--repair` doctor створює резервну копію кожного ураженого файлу поруч з оригіналом і переписує транскрипт на активну гілку, щоб історія Gateway та читачі пам’яті більше не бачили дубльованих ходів.
|
||||
Doctor сканує JSONL-файли сесій agent на наявність дубльованої форми гілок, створеної багом переписування транскриптів промптів у версії 2026.4.24: покинутий user turn із внутрішнім контекстом виконання OpenClaw плюс активний sibling з тим самим видимим user prompt. У режимі `--fix` / `--repair` doctor створює резервну копію кожного ураженого файла поруч з оригіналом і переписує транскрипт до активної гілки, щоб історія gateway і читачі пам’яті більше не бачили дубльованих turn.
|
||||
</Accordion>
|
||||
<Accordion title="4. Перевірки цілісності стану (збереження сесій, маршрутизація та безпека)">
|
||||
Каталог стану — це операційний стовбур системи. Якщо він зникне, ви втратите сесії, облікові дані, журнали та конфігурацію (якщо у вас немає резервних копій в іншому місці).
|
||||
Каталог стану — це операційний стовбур мозку. Якщо він зникне, ви втратите сесії, облікові дані, журнали та конфігурацію (якщо не маєте резервних копій в іншому місці).
|
||||
|
||||
Doctor перевіряє:
|
||||
|
||||
- **Каталог стану відсутній**: попереджає про катастрофічну втрату стану, пропонує відновити каталог і нагадує, що не може відновити відсутні дані.
|
||||
- **Права доступу до каталогу стану**: перевіряє можливість запису; пропонує виправити права доступу (і виводить підказку `chown`, якщо виявлено невідповідність власника/групи).
|
||||
- **Каталог стану macOS, синхронізований із хмарою**: попереджає, коли стан розміщується в iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, оскільки шляхи із синхронізацією можуть спричиняти повільніше I/O та конфлікти блокувань/синхронізації.
|
||||
- **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розміщується на джерелі монтування `mmcblk*`, оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час запису сесій та облікових даних.
|
||||
- **Каталог стану відсутній**: попереджає про катастрофічну втрату стану, пропонує створити каталог заново та нагадує, що не може відновити відсутні дані.
|
||||
- **Дозволи каталогу стану**: перевіряє можливість запису; пропонує виправити дозволи (і виводить підказку `chown`, якщо виявлено невідповідність власника/групи).
|
||||
- **Каталог стану macOS у хмарній синхронізації**: попереджає, коли стан розміщується в iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, оскільки шляхи із синхронізацією можуть спричиняти повільніший I/O та гонки блокувань/синхронізації.
|
||||
- **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розміщується на джерелі монтування `mmcblk*`, оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношуватися при записах сесій та облікових даних.
|
||||
- **Каталоги сесій відсутні**: `sessions/` і каталог сховища сесій потрібні для збереження історії та уникнення збоїв `ENOENT`.
|
||||
- **Невідповідність транскриптів**: попереджає, коли нещодавні записи сесій мають відсутні файли транскриптів.
|
||||
- **Основна сесія "1-line JSONL"**: позначає, коли головний транскрипт містить лише один рядок (історія не накопичується).
|
||||
- **Кілька каталогів стану**: попереджає, коли існує кілька тек `~/.openclaw` у різних домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може розділитися між встановленнями).
|
||||
- **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запускати його на віддаленому хості (саме там зберігається стан).
|
||||
- **Права доступу до файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групі/усім, і пропонує обмежити права до `600`.
|
||||
- **Основна сесія "1-line JSONL"**: позначає випадки, коли основний транскрипт має лише один рядок (історія не накопичується).
|
||||
- **Кілька каталогів стану**: попереджає, коли існує кілька каталогів `~/.openclaw` у різних домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може розділитися між встановленнями).
|
||||
- **Нагадування про remote mode**: якщо `gateway.mode=remote`, doctor нагадує запускати його на віддаленому хості (саме там живе стан).
|
||||
- **Дозволи файла конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групою/усіма, і пропонує посилити їх до `600`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="5. Стан автентифікації моделей (строк дії OAuth)">
|
||||
Doctor перевіряє OAuth-профілі у сховищі автентифікації, попереджає, коли строк дії токенів спливає або вже сплив, і може оновити їх, коли це безпечно. Якщо профіль Anthropic OAuth/token застарів, він пропонує Anthropic API key або шлях setup-token Anthropic. Запити на оновлення з’являються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення.
|
||||
Doctor перевіряє профілі OAuth у сховищі автентифікації, попереджає, коли токени прострочуються/прострочені, і може оновити їх, коли це безпечно. Якщо профіль Anthropic OAuth/token застарів, він пропонує Anthropic API key або шлях Anthropic setup-token. Запити на оновлення з’являються лише в інтерактивному режимі (TTY); `--non-interactive` пропускає спроби оновлення.
|
||||
|
||||
Коли оновлення OAuth остаточно завершується невдачею (наприклад, `refresh_token_reused`, `invalid_grant` або коли провайдер повідомляє, що потрібно ввійти знову), doctor повідомляє, що потрібна повторна автентифікація, і виводить точну команду `openclaw models auth login --provider ...`, яку слід виконати.
|
||||
Коли оновлення OAuth остаточно не вдається (наприклад, `refresh_token_reused`, `invalid_grant` або провайдер вимагає повторного входу), doctor повідомляє, що потрібна повторна автентифікація, і виводить точну команду `openclaw models auth login --provider ...`, яку слід виконати.
|
||||
|
||||
Doctor також повідомляє про профілі автентифікації, які тимчасово непридатні до використання через:
|
||||
|
||||
- короткі cooldown-періоди (обмеження швидкості/тайм-аути/збої автентифікації)
|
||||
- довші вимкнення (помилки білінгу/кредитів)
|
||||
- короткі cooldown-и (обмеження швидкості/тайм-аути/помилки автентифікації)
|
||||
- довші відключення (помилки білінгу/кредитів)
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="6. Перевірка моделі hooks">
|
||||
Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на модель за каталогом і allowlist та попереджає, коли воно не розв’язується або заборонене.
|
||||
Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на модель за каталогом і allowlist та попереджає, якщо воно не розв’язується або не дозволене.
|
||||
</Accordion>
|
||||
<Accordion title="7. Відновлення образу sandbox">
|
||||
Коли sandboxing увімкнено, doctor перевіряє Docker image і пропонує зібрати його або перемкнутися на застарілі імена, якщо поточний образ відсутній.
|
||||
Коли sandboxing увімкнено, doctor перевіряє Docker-образи та пропонує зібрати їх або перейти на застарілі назви, якщо поточний образ відсутній.
|
||||
</Accordion>
|
||||
<Accordion title="7b. Runtime-залежності вбудованих Plugin">
|
||||
Doctor перевіряє runtime-залежності лише для вбудованих Plugin, які активні в поточній конфігурації або ввімкнені типовим значенням у своєму вбудованому маніфесті, наприклад `plugins.entries.discord.enabled: true`, застаріле `channels.discord.enabled: true` або типовий увімкнений вбудований провайдер. Якщо чогось бракує, doctor повідомляє про пакунки й установлює їх у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Зовнішні Plugin, як і раніше, використовують `openclaw plugins install` / `openclaw plugins update`; doctor не встановлює залежності для довільних шляхів Plugin.
|
||||
<Accordion title="7b. Залежності середовища виконання bundled plugin">
|
||||
Doctor перевіряє залежності середовища виконання лише для bundled plugin, які активні в поточній конфігурації або ввімкнені типовим значенням їх bundled manifest, наприклад `plugins.entries.discord.enabled: true`, застаріле `channels.discord.enabled: true` або bundled provider, увімкнений за замовчуванням. Якщо чогось бракує, doctor повідомляє про пакунки та встановлює їх у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Зовнішні plugin, як і раніше, використовують `openclaw plugins install` / `openclaw plugins update`; doctor не встановлює залежності для довільних шляхів plugin.
|
||||
|
||||
Під час відновлення doctor npm-встановлення runtime-залежностей вбудованих пакетів показують прогрес через spinner у TTY-сеансах і періодичний построковий прогрес у piped/headless-виводі. Gateway і локальний CLI також можуть за потреби відновлювати runtime-залежності активних вбудованих Plugin перед імпортом вбудованого Plugin. Ці встановлення обмежені коренем встановлення runtime Plugin, виконуються з вимкненими scripts, не записують package lock і захищені блокуванням install-root, щоб одночасні запуски CLI або Gateway не змінювали те саме дерево `node_modules` одночасно.
|
||||
Під час відновлення doctor встановлення npm-залежностей середовища виконання bundled plugin показують прогрес через spinner у TTY-сеансах і періодичний построковий прогрес у конвеєрному/безголовому виводі. Gateway і локальний CLI також можуть за потреби відновлювати активні залежності середовища виконання bundled plugin перед імпортом bundled plugin. Ці встановлення обмежуються коренем встановлення середовища виконання plugin, виконуються з вимкненими скриптами, не записують package lock і захищені блокуванням кореня встановлення, щоб одночасні запуски CLI або Gateway не змінювали те саме дерево `node_modules` одночасно.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="8. Міграції служб Gateway і підказки з очищення">
|
||||
Doctor виявляє застарілі служби gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити службу OpenClaw з використанням поточного порту gateway. Він також може сканувати додаткові служби, схожі на gateway, і виводити підказки з очищення. Іменовані за профілем служби gateway OpenClaw вважаються повноцінними і не позначаються як "додаткові".
|
||||
<Accordion title="8. Міграції служб Gateway та підказки з очищення">
|
||||
Doctor виявляє застарілі служби gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити службу OpenClaw з поточним портом gateway. Він також може сканувати додаткові служби, схожі на gateway, і виводити підказки з очищення. Іменовані за профілем служби gateway OpenClaw вважаються повноцінними й не позначаються як «додаткові».
|
||||
|
||||
У Linux, якщо служба gateway на рівні користувача відсутня, але існує системна служба gateway OpenClaw, doctor не встановлює автоматично другу службу на рівні користувача. Перевірте через `openclaw gateway status --deep` або `openclaw doctor --deep`, потім видаліть дублікат або встановіть `OPENCLAW_SERVICE_REPAIR_POLICY=external`, якщо життєвим циклом gateway керує зовнішній supervisor.
|
||||
У Linux, якщо користувацька служба gateway відсутня, але існує системна служба gateway OpenClaw, doctor не встановлює автоматично другу користувацьку службу. Перевірте через `openclaw gateway status --deep` або `openclaw doctor --deep`, а потім видаліть дублікат або встановіть `OPENCLAW_SERVICE_REPAIR_POLICY=external`, якщо життєвим циклом gateway керує системний supervisor.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="8b. Стартова міграція Matrix">
|
||||
Коли обліковий запис каналу Matrix має очікувану або застосовну міграцію застарілого стану, doctor (у режимі `--fix` / `--repair`) створює знімок стану до міграції, а потім запускає best-effort кроки міграції: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки записуються в журнал, а запуск триває. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається.
|
||||
<Accordion title="8b. Міграція Matrix під час запуску">
|
||||
Якщо обліковий запис каналу Matrix має очікувану або застосовну міграцію застарілого стану, doctor (у режимі `--fix` / `--repair`) створює знімок стану перед міграцією, а потім виконує кроки міграції за принципом best-effort: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки логуються, а запуск триває. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається.
|
||||
</Accordion>
|
||||
<Accordion title="8c. Сполучення пристроїв і дрейф автентифікації">
|
||||
Тепер Doctor перевіряє стан сполучення пристроїв як частину звичайного проходу перевірки стану системи.
|
||||
Doctor тепер перевіряє стан сполучення пристроїв у межах звичайного проходу перевірки стану.
|
||||
|
||||
Що він повідомляє:
|
||||
|
||||
- очікувані запити на перше сполучення
|
||||
- очікувані підвищення ролі для вже сполучених пристроїв
|
||||
- очікувані підвищення scope для вже сполучених пристроїв
|
||||
- виправлення невідповідності public key, коли ID пристрою ще збігається, але ідентичність пристрою більше не збігається зі схваленим записом
|
||||
- очікувані оновлення ролей для вже сполучених пристроїв
|
||||
- очікувані оновлення областей дії для вже сполучених пристроїв
|
||||
- відновлення невідповідності відкритого ключа, коли ID пристрою все ще збігається, але ідентичність пристрою більше не збігається зі схваленим записом
|
||||
- сполучені записи без активного токена для схваленої ролі
|
||||
- сполучені токени, scope яких вийшли за межі схваленої базової лінії сполучення
|
||||
- локальні кешовані записи токенів пристрою для поточної машини, які передують ротації токена на боці gateway або містять застарілі метадані scope
|
||||
- сполучені токени, чиї області дії відхилилися від базового схваленого рівня сполучення
|
||||
- локальні кешовані записи токенів пристрою для поточної машини, які передують ротації токена на боці gateway або містять застарілі метадані області дії
|
||||
|
||||
Doctor не схвалює запити на сполучення автоматично і не виконує автоматичну ротацію токенів пристрою. Натомість він виводить точні наступні кроки:
|
||||
Doctor не схвалює автоматично запити на сполучення і не виконує автоматично ротацію токенів пристрою. Натомість він виводить точні наступні кроки:
|
||||
|
||||
- переглянути очікувані запити через `openclaw devices list`
|
||||
- схвалити конкретний запит через `openclaw devices approve <requestId>`
|
||||
- схвалити точний запит через `openclaw devices approve <requestId>`
|
||||
- виконати ротацію нового токена через `openclaw devices rotate --device <deviceId> --role <role>`
|
||||
- видалити застарілий запис і схвалити його знову через `openclaw devices remove <deviceId>`
|
||||
|
||||
Це закриває поширену проблему "пристрій уже сполучено, але все одно з’являється вимога сполучення": тепер doctor розрізняє перше сполучення, очікувані підвищення ролі/scope та дрейф застарілого токена/ідентичності пристрою.
|
||||
Це закриває поширену проблему «вже сполучено, але все одно вимагається сполучення»: тепер doctor розрізняє перше сполучення, очікувані оновлення ролі/області дії та дрейф застарілого токена/ідентичності пристрою.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="9. Попередження безпеки">
|
||||
Doctor виводить попередження, коли провайдер відкритий для DM без allowlist або коли політику налаштовано небезпечним чином.
|
||||
</Accordion>
|
||||
<Accordion title="10. systemd linger (Linux)">
|
||||
Якщо запуск відбувається як користувацька служба systemd, doctor переконується, що lingering увімкнено, щоб gateway залишався активним після виходу з системи.
|
||||
Якщо запуск виконується як користувацька служба systemd, doctor перевіряє, що lingering увімкнено, щоб gateway залишався активним після виходу з системи.
|
||||
</Accordion>
|
||||
<Accordion title="11. Стан робочого простору (Skills, Plugin і застарілі каталоги)">
|
||||
Doctor виводить зведення стану робочого простору для типового агента:
|
||||
<Accordion title="11. Стан робочого простору (skills, plugin та застарілі каталоги)">
|
||||
Doctor виводить підсумок стану робочого простору для agent за замовчуванням:
|
||||
|
||||
- **Стан Skills**: кількість доступних, тих, де бракує вимог, і Skills, заблокованих allowlist.
|
||||
- **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору існують поруч із поточним робочим простором.
|
||||
- **Стан Plugin**: підраховує ввімкнені/вимкнені/помилкові Plugin; перелічує ID Plugin для всіх помилок; повідомляє про можливості bundle Plugin.
|
||||
- **Попередження сумісності Plugin**: позначає Plugin, які мають проблеми сумісності з поточним runtime.
|
||||
- **Діагностика Plugin**: показує всі попередження або помилки під час завантаження, які видає реєстр Plugin.
|
||||
- **Стан Skills**: кількість доступних, таких, яким бракує вимог, і заблокованих allowlist skills.
|
||||
- **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору існують поряд із поточним робочим простором.
|
||||
- **Стан plugin**: рахує ввімкнені/вимкнені/plugin з помилками; перелічує ID plugin для всіх помилок; повідомляє про можливості bundle plugin.
|
||||
- **Попередження про сумісність plugin**: позначає plugin, які мають проблеми сумісності з поточним середовищем виконання.
|
||||
- **Діагностика plugin**: показує всі попередження або помилки під час завантаження, які видає реєстр plugin.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="11b. Розмір bootstrap-файлу">
|
||||
Doctor перевіряє, чи наближаються bootstrap-файли робочого простору (наприклад, `AGENTS.md`, `CLAUDE.md` або інші injected context files) до налаштованого ліміту символів або перевищують його. Він повідомляє для кожного файлу кількість сирих і вставлених символів, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість вставлених символів як частку від загального ліміту. Коли файли обрізаються або наближаються до ліміту, doctor виводить поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`.
|
||||
<Accordion title="11b. Розмір bootstrap-файла">
|
||||
Doctor перевіряє, чи bootstrap-файли робочого простору (наприклад, `AGENTS.md`, `CLAUDE.md` або інші вбудовані контекстні файли) наближаються до налаштованого ліміту символів або перевищують його. Він повідомляє для кожного файла необроблену й вбудовану кількість символів, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість вбудованих символів як частку від загального бюджету. Коли файли обрізаються або наближаються до ліміту, doctor виводить поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`.
|
||||
</Accordion>
|
||||
<Accordion title="11d. Очищення застарілого Plugin каналу">
|
||||
Коли `openclaw doctor --fix` видаляє відсутній Plugin каналу, він також видаляє завислу конфігурацію рівня каналу, яка посилалася на цей Plugin: записи `channels.<id>`, цілі Heartbeat, у яких згадувався канал, і перевизначення `agents.*.models["<channel>/*"]`. Це запобігає циклам завантаження Gateway, коли runtime каналу вже немає, але конфігурація все ще наказує gateway прив’язатися до нього.
|
||||
<Accordion title="11d. Очищення застарілих channel plugin">
|
||||
Коли `openclaw doctor --fix` видаляє відсутній channel plugin, він також видаляє завислу конфігурацію рівня каналу, яка посилалася на цей plugin: записи `channels.<id>`, цілі heartbeat, що вказували на канал, і перевизначення `agents.*.models["<channel>/*"]`. Це запобігає циклам перезапуску Gateway, коли середовище виконання каналу зникло, але конфігурація все ще вимагає від gateway прив’язатися до нього.
|
||||
</Accordion>
|
||||
<Accordion title="11c. Completion оболонки">
|
||||
Doctor перевіряє, чи встановлено completion за Tab для поточної оболонки (zsh, bash, fish або PowerShell):
|
||||
<Accordion title="11c. Shell completion">
|
||||
Doctor перевіряє, чи встановлено tab completion для поточної оболонки (zsh, bash, fish або PowerShell):
|
||||
|
||||
- Якщо профіль оболонки використовує повільний шаблон динамічного completion (`source <(openclaw completion ...)`), doctor оновлює його до швидшого варіанта з кешованим файлом.
|
||||
- Якщо completion налаштовано в профілі, але файл кешу відсутній, doctor автоматично відновлює кеш.
|
||||
- Якщо профіль оболонки використовує повільну динамічну схему completion (`source <(openclaw completion ...)`), doctor оновлює її до швидшого варіанта з кешованим файлом.
|
||||
- Якщо completion налаштовано в профілі, але кешований файл відсутній, doctor автоматично регенерує кеш.
|
||||
- Якщо completion взагалі не налаштовано, doctor пропонує встановити його (лише в інтерактивному режимі; пропускається з `--non-interactive`).
|
||||
|
||||
Виконайте `openclaw completion --write-state`, щоб вручну перевідтворити кеш.
|
||||
Виконайте `openclaw completion --write-state`, щоб вручну регенерувати кеш.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="12. Перевірки автентифікації Gateway (локальний токен)">
|
||||
Doctor перевіряє готовність автентифікації локального токена gateway.
|
||||
|
||||
- Якщо в режимі токена потрібен токен і жодного джерела токена немає, doctor пропонує згенерувати його.
|
||||
- Якщо режим токена потребує токен, а джерела токена немає, doctor пропонує згенерувати його.
|
||||
- Якщо `gateway.auth.token` керується через SecretRef, але недоступний, doctor попереджає і не перезаписує його відкритим текстом.
|
||||
- `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано token SecretRef.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="12b. Виправлення з урахуванням SecretRef у режимі лише читання">
|
||||
Деякі потоки виправлення потребують перевірки налаштованих облікових даних без послаблення поведінки runtime fail-fast.
|
||||
<Accordion title="12b. Відновлення з урахуванням SecretRef у режимі лише читання">
|
||||
Деякі сценарії відновлення потребують перевірки налаштованих облікових даних без послаблення поведінки fail-fast під час виконання.
|
||||
|
||||
- `openclaw doctor --fix` тепер використовує ту саму модель зведення SecretRef у режимі лише читання, що й команди сімейства status, для цільових виправлень конфігурації.
|
||||
- Приклад: виправлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані облікові дані бота, якщо вони доступні.
|
||||
- Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху виконання команди, doctor повідомляє, що облікові дані налаштовано, але вони недоступні, і пропускає авторозв’язання замість збою або хибного повідомлення, що токен відсутній.
|
||||
- `openclaw doctor --fix` тепер використовує ту саму модель підсумку SecretRef лише для читання, що й команди сімейства status, для цільового відновлення конфігурації.
|
||||
- Приклад: відновлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані облікові дані бота, якщо вони доступні.
|
||||
- Якщо токен Telegram-бота налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає авторозв’язання замість аварійного завершення або хибного повідомлення про відсутність токена.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="13. Перевірка стану Gateway + перезапуск">
|
||||
Doctor виконує перевірку стану системи і пропонує перезапустити gateway, якщо він виглядає несправним.
|
||||
Doctor виконує перевірку стану і пропонує перезапустити gateway, якщо той виглядає несправним.
|
||||
</Accordion>
|
||||
<Accordion title="13b. Готовність пошуку в пам’яті">
|
||||
Doctor перевіряє, чи готовий налаштований провайдер embedding для пошуку в пам’яті для типового агента. Поведінка залежить від налаштованого backend і провайдера:
|
||||
Doctor перевіряє, чи готовий налаштований провайдер embedding для пошуку в пам’яті для agent за замовчуванням. Поведінка залежить від налаштованого бекенда і провайдера:
|
||||
|
||||
- **QMD backend**: перевіряє, чи доступний і чи запускається двійковий файл `qmd`. Якщо ні, виводить вказівки щодо виправлення, зокрема npm-пакунок і варіант ручного шляху до двійкового файла.
|
||||
- **Явний локальний провайдер**: перевіряє наявність локального файлу моделі або розпізнаного URL віддаленої/завантажуваної моделі. Якщо його немає, пропонує перейти на віддаленого провайдера.
|
||||
- **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи є API key у середовищі або сховищі автентифікації. Якщо немає, виводить практичні підказки щодо виправлення.
|
||||
- **Автоматичний провайдер**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого провайдера в порядку автовору.
|
||||
- **Бекенд QMD**: перевіряє, чи двійковий файл `qmd` доступний і може запускатися. Якщо ні — виводить інструкції з виправлення, зокрема npm-пакет і варіант ручного шляху до двійкового файла.
|
||||
- **Явний локальний провайдер**: перевіряє наявність локального файла моделі або розпізнаного віддаленого/завантажуваного URL моделі. Якщо його немає, пропонує перейти на віддалений провайдер.
|
||||
- **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи наявний API key у середовищі або сховищі автентифікації. Якщо його немає, виводить практичні підказки з виправлення.
|
||||
- **Автоматичний провайдер**: спочатку перевіряє доступність локальної моделі, а потім пробує кожен віддалений провайдер у порядку автоматичного вибору.
|
||||
|
||||
Коли доступний кешований результат перевірки gateway (gateway був справний на момент перевірки), doctor звіряє його результат із конфігурацією, видимою CLI, і зазначає будь-які розбіжності. Doctor не запускає нову перевірку embedding за типовим шляхом; використовуйте команду deep status для пам’яті, коли потрібна жива перевірка провайдера.
|
||||
Коли доступний кешований результат перевірки gateway (на момент перевірки gateway був у нормальному стані), doctor звіряє його результат із конфігурацією, видимою CLI, і зазначає будь-які розбіжності. Doctor не запускає нову перевірку embedding на стандартному шляху; використовуйте команду глибокого статусу пам’яті, якщо хочете живу перевірку провайдера.
|
||||
|
||||
Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час runtime.
|
||||
Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час виконання.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="14. Попередження про стан каналу">
|
||||
Якщо gateway справний, doctor виконує перевірку стану каналу і повідомляє про попередження з рекомендованими виправленнями.
|
||||
<Accordion title="14. Попередження про стан каналів">
|
||||
Якщо gateway у нормальному стані, doctor виконує перевірку стану каналів і повідомляє про попередження з рекомендованими виправленнями.
|
||||
</Accordion>
|
||||
<Accordion title="15. Аудит конфігурації supervisor + виправлення">
|
||||
Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на відсутні або застарілі типові значення (наприклад, залежності systemd від network-online і затримка перезапуску). Коли він знаходить невідповідність, то рекомендує оновлення і може переписати файл служби/завдання відповідно до поточних типових значень.
|
||||
<Accordion title="15. Аудит конфігурації supervisor + відновлення">
|
||||
Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на наявність відсутніх або застарілих значень за замовчуванням (наприклад, залежностей systemd від network-online і затримки перезапуску). Коли він виявляє невідповідність, то рекомендує оновлення і може переписати файл служби/завдання відповідно до поточних значень за замовчуванням.
|
||||
|
||||
Примітки:
|
||||
|
||||
- `openclaw doctor` запитує підтвердження перед переписуванням конфігурації supervisor.
|
||||
- `openclaw doctor --yes` приймає типові запити на виправлення.
|
||||
- `openclaw doctor --yes` приймає типові запити на відновлення.
|
||||
- `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів.
|
||||
- `openclaw doctor --repair --force` перезаписує власні конфігурації supervisor.
|
||||
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу служби gateway. Він усе ще повідомляє про стан служби і запускає виправлення, не пов’язані зі службами, але пропускає встановлення/запуск/перезапуск/bootstrap служби, переписування конфігурації supervisor і очищення застарілих служб, оскільки цим життєвим циклом керує зовнішній supervisor.
|
||||
- Якщо для автентифікації токеном потрібен токен і `gateway.auth.token` керується через SecretRef, під час встановлення/виправлення служби doctor перевіряє SecretRef, але не зберігає розв’язані значення токена відкритим текстом у метаданих середовища служби supervisor.
|
||||
- Doctor виявляє керовані `.env`/підтримувані SecretRef значення середовища служби, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудовували inline, і переписує метадані служби так, щоб ці значення завантажувалися з джерела runtime, а не з визначення supervisor.
|
||||
- `openclaw doctor --repair --force` перезаписує користувацькі конфігурації supervisor.
|
||||
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу служби gateway. Він усе ще повідомляє про стан служби та виконує відновлення, не пов’язані зі службою, але пропускає встановлення/запуск/перезапуск/bootstrap служби, переписування конфігурації supervisor і очищення застарілих служб, оскільки цим життєвим циклом керує зовнішній supervisor.
|
||||
- Якщо автентифікація токеном вимагає токен, а `gateway.auth.token` керується через SecretRef, встановлення/відновлення служби doctor перевіряє SecretRef, але не зберігає розв’язані значення токенів відкритим текстом у метаданих середовища служби supervisor.
|
||||
- Doctor виявляє керовані `.env`/підкріплені SecretRef значення середовища служби, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудовували inline, і переписує метадані служби так, щоб ці значення завантажувалися з джерела середовища виконання, а не з визначення supervisor.
|
||||
- Doctor виявляє, коли команда служби все ще фіксує старий `--port` після зміни `gateway.port`, і переписує метадані служби на поточний порт.
|
||||
- Якщо для автентифікації токеном потрібен токен і налаштований token SecretRef не розв’язується, doctor блокує шлях встановлення/виправлення та надає практичні вказівки.
|
||||
- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не встановлено, doctor блокує встановлення/виправлення, доки режим не буде задано явно.
|
||||
- Якщо автентифікація токеном вимагає токен, а налаштований token SecretRef не розв’язано, doctor блокує шлях встановлення/відновлення та виводить практичні інструкції.
|
||||
- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не встановлено, doctor блокує встановлення/відновлення, доки режим не буде явно задано.
|
||||
- Для користувацьких unit systemd у Linux перевірки дрейфу токена в doctor тепер охоплюють і джерела `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації служби.
|
||||
- Виправлення служб doctor відмовляються переписувати, зупиняти або перезапускати службу gateway зі старішого двійкового файла OpenClaw, якщо конфігурацію востаннє було записано новішою версією. Див. [Усунення несправностей Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
|
||||
- Doctor відмовляється переписувати, зупиняти або перезапускати службу gateway зі старішого двійкового файла OpenClaw, якщо конфігурацію востаннє було записано новішою версією. Див. [Усунення проблем Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
|
||||
- Ви завжди можете примусово виконати повне переписування через `openclaw gateway install --force`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="16. Діагностика runtime Gateway і порту">
|
||||
Doctor перевіряє runtime служби (PID, останній статус завершення) і попереджає, коли службу встановлено, але вона фактично не запущена. Він також перевіряє конфлікти портів на порту gateway (типово `18789`) і повідомляє про ймовірні причини (gateway уже запущено, SSH-тунель).
|
||||
<Accordion title="16. Діагностика середовища виконання Gateway + порту">
|
||||
Doctor перевіряє середовище виконання служби (PID, останній статус завершення) і попереджає, якщо службу встановлено, але вона фактично не запущена. Він також перевіряє конфлікти на порту gateway (типово `18789`) і повідомляє про ймовірні причини (gateway уже запущений, SSH-тунель).
|
||||
</Accordion>
|
||||
<Accordion title="17. Рекомендовані практики runtime Gateway">
|
||||
Doctor попереджає, коли служба gateway працює на Bun або на шляху Node, керованому менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp і Telegram потребують Node, а шляхи менеджера версій можуть ламатися після оновлень, оскільки служба не завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системне встановлення Node, якщо воно доступне (Homebrew/apt/choco).
|
||||
</Accordion>
|
||||
<Accordion title="18. Запис конфігурації + метадані wizard">
|
||||
Doctor зберігає всі зміни конфігурації та проставляє метадані wizard, щоб зафіксувати запуск doctor.
|
||||
</Accordion>
|
||||
<Accordion title="19. Поради щодо робочого простору (резервні копії + система пам’яті)">
|
||||
Doctor пропонує систему пам’яті робочого простору, якщо вона відсутня, і виводить пораду щодо резервного копіювання, якщо робочий простір ще не перебуває під git.
|
||||
<Accordion title="17. Найкращі практики середовища виконання Gateway">
|
||||
Doctor попереджає, коли служба gateway працює на Bun або через шлях Node, керований менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджерів версій можуть ламатися після оновлень, тому що служба не завантажує вашу ініціалізацію оболонки. Doctor пропонує міграцію на системне встановлення Node, якщо воно доступне (Homebrew/apt/choco).
|
||||
|
||||
Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace) для повного посібника зі структури робочого простору та резервного копіювання через git (рекомендовано приватний GitHub або GitLab).
|
||||
Нещодавно встановлені або відновлені служби зберігають явні корені середовища (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) і стабільні каталоги user-bin, але резервні каталоги менеджерів версій, визначені евристично, записуються в PATH служби лише тоді, коли ці каталоги існують на диску. Це узгоджує згенерований PATH supervisor з тим самим аудитом мінімального PATH, який doctor виконує пізніше.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="18. Запис конфігурації + метадані майстра">
|
||||
Doctor зберігає всі зміни конфігурації та проставляє метадані майстра, щоб зафіксувати запуск doctor.
|
||||
</Accordion>
|
||||
<Accordion title="19. Поради щодо робочого простору (резервне копіювання + система пам’яті)">
|
||||
Doctor пропонує систему пам’яті робочого простору, якщо її немає, і виводить пораду щодо резервного копіювання, якщо робочий простір ще не перебуває під git.
|
||||
|
||||
Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб ознайомитися з повним посібником зі структури робочого простору та резервного копіювання через git (рекомендовано приватний GitHub або GitLab).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Інструкція для Gateway](/uk/gateway)
|
||||
- [Усунення несправностей Gateway](/uk/gateway/troubleshooting)
|
||||
- [Інструкція з експлуатації Gateway](/uk/gateway)
|
||||
- [Усунення проблем Gateway](/uk/gateway/troubleshooting)
|
||||
|
||||
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- Запуск OpenClaw за проксі з підтримкою ідентифікації
|
||||
- Запуск OpenClaw за identity-aware проксі
|
||||
- Налаштування Pomerium, Caddy або nginx з OAuth перед OpenClaw
|
||||
- Виправлення помилок WebSocket 1008 «неавторизовано» у конфігураціях зі зворотним проксі
|
||||
- Визначення місця налаштування HSTS та інших заголовків HTTP для посилення безпеки
|
||||
- Усунення помилок WebSocket 1008 «несанкціоновано» у конфігураціях зі зворотним проксі
|
||||
- Визначення, де встановлювати HSTS та інші заголовки посилення безпеки HTTP
|
||||
sidebarTitle: Trusted proxy auth
|
||||
summary: Делегуйте автентифікацію Gateway довіреному зворотному проксі (Pomerium, Caddy, nginx + OAuth)
|
||||
title: Автентифікація довіреного проксі
|
||||
title: Автентифікація через довірений проксі
|
||||
x-i18n:
|
||||
generated_at: "2026-04-26T08:15:43Z"
|
||||
generated_at: "2026-04-27T22:22:43Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 64e0f4dee942aedec548135f0408e7773e7b498f8262af13a4d0eff262cae646
|
||||
source_hash: 863a448f84d1bc5bf2a5a07a894bcc1bb7e724826ba9cec3fa135338af8dd3eb
|
||||
source_path: gateway/trusted-proxy-auth.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
<Warning>
|
||||
**Функція, чутлива до безпеки.** У цьому режимі автентифікація повністю делегується вашому зворотному проксі. Неправильна конфігурація може відкрити ваш Gateway для несанкціонованого доступу. Уважно прочитайте цю сторінку перед увімкненням.
|
||||
**Функція, чутлива до безпеки.** У цьому режимі автентифікація повністю делегується вашому зворотному проксі. Помилкова конфігурація може відкрити ваш Gateway для несанкціонованого доступу. Уважно прочитайте цю сторінку перед увімкненням.
|
||||
</Warning>
|
||||
|
||||
## Коли використовувати
|
||||
|
||||
Використовуйте режим автентифікації `trusted-proxy`, коли:
|
||||
|
||||
- Ви запускаєте OpenClaw за **проксі з підтримкою ідентифікації** (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth).
|
||||
- Ваш проксі виконує всю автентифікацію та передає ідентичність користувача через заголовки.
|
||||
- Ви працюєте в середовищі Kubernetes або контейнерному середовищі, де проксі є єдиним шляхом до Gateway.
|
||||
- Ви стикаєтеся з помилками WebSocket `1008 unauthorized`, тому що браузери не можуть передавати токени в корисному навантаженні WS.
|
||||
- Ви запускаєте OpenClaw за **identity-aware проксі** (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth).
|
||||
- Ваш проксі обробляє всю автентифікацію та передає ідентичність користувача через заголовки.
|
||||
- Ви перебуваєте в середовищі Kubernetes або контейнерному середовищі, де проксі є єдиним шляхом до Gateway.
|
||||
- Ви стикаєтеся з помилками WebSocket `1008 unauthorized`, тому що браузери не можуть передавати токени в WS payload.
|
||||
|
||||
## Коли НЕ використовувати
|
||||
## Коли НЕ слід використовувати
|
||||
|
||||
- Якщо ваш проксі не автентифікує користувачів (лише завершує TLS або є балансувальником навантаження).
|
||||
- Якщо існує будь-який шлях до Gateway в обхід проксі (дірки у фаєрволі, доступ із внутрішньої мережі).
|
||||
- Якщо ви не впевнені, що ваш проксі правильно видаляє/перезаписує переслані заголовки.
|
||||
- Якщо вам потрібен лише персональний доступ для одного користувача (розгляньте Tailscale Serve + loopback для простішого налаштування).
|
||||
- Якщо ви не впевнені, що ваш проксі правильно видаляє/перезаписує forwarded headers.
|
||||
- Якщо вам потрібен лише персональний доступ для одного користувача (для простішого налаштування розгляньте Tailscale Serve + local loopback).
|
||||
|
||||
## Як це працює
|
||||
|
||||
@ -46,25 +46,25 @@ x-i18n:
|
||||
Проксі додає заголовок з ідентичністю автентифікованого користувача (наприклад, `x-forwarded-user: nick@example.com`).
|
||||
</Step>
|
||||
<Step title="Gateway перевіряє довірене джерело">
|
||||
OpenClaw перевіряє, що запит надійшов від **довіреної IP-адреси проксі** (налаштованої в `gateway.trustedProxies`).
|
||||
OpenClaw перевіряє, що запит надійшов із **довіреної IP-адреси проксі** (налаштованої в `gateway.trustedProxies`).
|
||||
</Step>
|
||||
<Step title="Gateway витягує ідентичність">
|
||||
OpenClaw витягує ідентичність користувача з налаштованого заголовка.
|
||||
</Step>
|
||||
<Step title="Авторизація">
|
||||
Якщо все гаразд, запит авторизується.
|
||||
Якщо все перевірено успішно, запит авторизується.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Поведінка сполучення Control UI
|
||||
## Поведінка сполучення з Control UI
|
||||
|
||||
Коли `gateway.auth.mode = "trusted-proxy"` активний і запит проходить перевірки trusted-proxy, сеанси WebSocket Control UI можуть підключатися без ідентичності сполучення пристрою.
|
||||
|
||||
Наслідки:
|
||||
|
||||
- Сполучення більше не є основним бар’єром для доступу до Control UI в цьому режимі.
|
||||
- Сполучення більше не є основним бар’єром доступу до Control UI в цьому режимі.
|
||||
- Політика автентифікації вашого зворотного проксі та `allowUsers` стають фактичним контролем доступу.
|
||||
- Тримайте вхідний доступ до gateway заблокованим лише для IP-адрес довіреного проксі (`gateway.trustedProxies` + фаєрвол).
|
||||
- Тримайте вхідний доступ до Gateway заблокованим лише для довірених IP-адрес проксі (`gateway.trustedProxies` + фаєрвол).
|
||||
|
||||
## Конфігурація
|
||||
|
||||
@ -83,10 +83,10 @@ x-i18n:
|
||||
// Заголовок, що містить ідентичність автентифікованого користувача (обов’язково)
|
||||
userHeader: "x-forwarded-user",
|
||||
|
||||
// Необов’язково: заголовки, які ОБОВ’ЯЗКОВО мають бути присутні (перевірка проксі)
|
||||
// Необов’язково: заголовки, які ОБОВ’ЯЗКОВО мають бути присутніми (перевірка проксі)
|
||||
requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],
|
||||
|
||||
// Необов’язково: обмеження до конкретних користувачів (порожньо = дозволити всіх)
|
||||
// Необов’язково: обмежити конкретними користувачами (порожньо = дозволити всіх)
|
||||
allowUsers: ["nick@example.com", "admin@company.org"],
|
||||
},
|
||||
},
|
||||
@ -95,19 +95,19 @@ x-i18n:
|
||||
```
|
||||
|
||||
<Warning>
|
||||
**Важливі правила під час виконання**
|
||||
**Важливі правила часу виконання**
|
||||
|
||||
- Автентифікація trusted-proxy відхиляє запити з loopback-джерела (`127.0.0.1`, `::1`, loopback CIDR).
|
||||
- Зворотні проксі loopback на тому самому хості **не** задовольняють вимоги автентифікації trusted-proxy.
|
||||
- Для конфігурацій із loopback-проксі на тому самому хості використовуйте натомість автентифікацію за токеном/паролем або маршрутизуйте через не-loopback адресу довіреного проксі, яку OpenClaw може перевірити.
|
||||
- Розгортання Control UI поза loopback усе одно потребують явного `gateway.controlUi.allowedOrigins`.
|
||||
- **Докази з пересланих заголовків мають пріоритет над loopback-локальністю.** Якщо запит надходить через loopback, але містить заголовки `X-Forwarded-For` / `X-Forwarded-Host` / `X-Forwarded-Proto`, що вказують на не-локальне джерело, ці докази спростовують твердження про loopback-локальність. Такий запит вважається віддаленим для сполучення, автентифікації trusted-proxy та контролю ідентичності пристрою в Control UI. Це запобігає тому, щоб loopback-проксі на тому самому хості «відмивав» ідентичність із пересланих заголовків у trusted-proxy автентифікацію.
|
||||
- Зворотні проксі на loopback на тому самому хості **не** відповідають вимогам trusted-proxy auth.
|
||||
- Для конфігурацій проксі на loopback на тому самому хості натомість використовуйте автентифікацію токеном/паролем або маршрутизуйте через не-loopback адресу довіреного проксі, яку OpenClaw може перевірити.
|
||||
- Для не-loopback розгортань Control UI усе одно потрібен явний `gateway.controlUi.allowedOrigins`.
|
||||
- **Докази через forwarded headers мають пріоритет над loopback-локальністю.** Якщо запит надходить через loopback, але містить заголовки `X-Forwarded-For` / `X-Forwarded-Host` / `X-Forwarded-Proto`, що вказують на нелокальне джерело, ці докази скасовують твердження про loopback-локальність. Запит вважається віддаленим для сполучення, trusted-proxy auth і контролю ідентичності пристрою в Control UI. Це запобігає тому, щоб проксі на loopback на тому самому хості «відмивав» ідентичність із forwarded headers у trusted-proxy auth.
|
||||
</Warning>
|
||||
|
||||
### Довідник конфігурації
|
||||
### Довідник із конфігурації
|
||||
|
||||
<ParamField path="gateway.trustedProxies" type="string[]" required>
|
||||
Масив IP-адрес проксі, яким можна довіряти. Запити з інших IP-адрес відхиляються.
|
||||
Масив IP-адрес проксі, яким слід довіряти. Запити з інших IP-адрес відхиляються.
|
||||
</ParamField>
|
||||
<ParamField path="gateway.auth.mode" type="string" required>
|
||||
Має бути `"trusted-proxy"`.
|
||||
@ -116,10 +116,10 @@ x-i18n:
|
||||
Назва заголовка, що містить ідентичність автентифікованого користувача.
|
||||
</ParamField>
|
||||
<ParamField path="gateway.auth.trustedProxy.requiredHeaders" type="string[]">
|
||||
Додаткові заголовки, які мають бути присутні, щоб запит вважався довіреним.
|
||||
Додаткові заголовки, які мають бути присутніми, щоб запит вважався довіреним.
|
||||
</ParamField>
|
||||
<ParamField path="gateway.auth.trustedProxy.allowUsers" type="string[]">
|
||||
Список дозволених ідентичностей користувачів. Порожньо означає дозволити всіх автентифікованих користувачів.
|
||||
Список дозволених ідентичностей користувачів. Порожнє значення означає дозвіл для всіх автентифікованих користувачів.
|
||||
</ParamField>
|
||||
|
||||
## Завершення TLS і HSTS
|
||||
@ -128,7 +128,7 @@ x-i18n:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Завершення TLS на проксі (рекомендовано)">
|
||||
Коли ваш зворотний проксі обробляє HTTPS для `https://control.example.com`, налаштуйте `Strict-Transport-Security` на проксі для цього домену.
|
||||
Коли ваш зворотний проксі обробляє HTTPS для `https://control.example.com`, встановіть `Strict-Transport-Security` на проксі для цього домену.
|
||||
|
||||
- Добре підходить для розгортань, доступних з інтернету.
|
||||
- Зберігає сертифікати та політику посилення безпеки HTTP в одному місці.
|
||||
@ -142,7 +142,7 @@ x-i18n:
|
||||
|
||||
</Tab>
|
||||
<Tab title="Завершення TLS на Gateway">
|
||||
Якщо сам OpenClaw напряму обслуговує HTTPS (без проксі, що завершує TLS), налаштуйте:
|
||||
Якщо OpenClaw сам безпосередньо обслуговує HTTPS (без проксі, що завершує TLS), установіть:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -162,13 +162,13 @@ x-i18n:
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Рекомендації щодо поетапного впровадження
|
||||
### Рекомендації щодо розгортання
|
||||
|
||||
- Спочатку використовуйте короткий max age (наприклад, `max-age=300`) під час перевірки трафіку.
|
||||
- Збільшуйте до довготривалих значень (наприклад, `max-age=31536000`) лише після того, як будете повністю впевнені.
|
||||
- Переходьте до довгострокових значень (наприклад, `max-age=31536000`) лише після того, як матимете високу впевненість.
|
||||
- Додавайте `includeSubDomains` лише якщо кожен піддомен готовий до HTTPS.
|
||||
- Використовуйте preload лише якщо ви навмисно виконуєте вимоги preload для всього набору ваших доменів.
|
||||
- Локальна розробка лише на loopback не отримує переваг від HSTS.
|
||||
- Для суто локальної розробки лише на loopback HSTS не дає переваг.
|
||||
|
||||
## Приклади налаштування проксі
|
||||
|
||||
@ -208,13 +208,13 @@ x-i18n:
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Caddy з OAuth">
|
||||
Caddy з Plugin `caddy-security` може автентифікувати користувачів і передавати заголовки ідентичності.
|
||||
Caddy з плагіном `caddy-security` може автентифікувати користувачів і передавати заголовки ідентичності.
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
bind: "lan",
|
||||
trustedProxies: ["10.0.0.1"], // IP-адреса Caddy/sidecar proxy
|
||||
trustedProxies: ["10.0.0.1"], // IP-адреса Caddy/sidecar-проксі
|
||||
auth: {
|
||||
mode: "trusted-proxy",
|
||||
trustedProxy: {
|
||||
@ -293,18 +293,18 @@ x-i18n:
|
||||
|
||||
## Змішана конфігурація токенів
|
||||
|
||||
OpenClaw відхиляє неоднозначні конфігурації, у яких одночасно активні `gateway.auth.token` (або `OPENCLAW_GATEWAY_TOKEN`) і режим `trusted-proxy`. Змішані конфігурації токенів можуть призвести до того, що loopback-запити мовчки автентифікуватимуться неправильним шляхом автентифікації.
|
||||
OpenClaw відхиляє неоднозначні конфігурації, у яких одночасно активні і `gateway.auth.token` (або `OPENCLAW_GATEWAY_TOKEN`), і режим `trusted-proxy`. Змішані конфігурації токенів можуть призводити до того, що loopback-запити тихо автентифікуються неправильним шляхом автентифікації.
|
||||
|
||||
Якщо під час запуску ви бачите помилку `mixed_trusted_proxy_token`:
|
||||
|
||||
- Видаліть спільний токен, якщо використовуєте режим trusted-proxy, або
|
||||
- Змініть `gateway.auth.mode` на `"token"`, якщо ви маєте намір використовувати автентифікацію на основі токена.
|
||||
- Видаліть спільний токен при використанні режиму trusted-proxy, або
|
||||
- Перемкніть `gateway.auth.mode` на `"token"`, якщо ви маєте намір використовувати автентифікацію на основі токена.
|
||||
|
||||
Loopback trusted-proxy автентифікація також працює за принципом fail closed: виклики з того самого хоста мають передавати налаштовані заголовки ідентичності через довірений проксі, а не автентифікуватися мовчки.
|
||||
Заголовки ідентичності trusted-proxy для loopback усе одно відмовляють у закритому режимі: виклики з того самого хоста не автентифікуються непомітно як користувачі проксі. Внутрішні виклики OpenClaw, які обходять проксі, натомість можуть автентифікуватися через `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`. Резервний перехід на токен навмисно не підтримується в режимі trusted-proxy.
|
||||
|
||||
## Заголовок областей операторів
|
||||
## Заголовок областей оператора
|
||||
|
||||
Автентифікація trusted-proxy — це HTTP-режим, **що несе ідентичність**, тому виклики можуть за бажанням оголошувати області операторів через `x-openclaw-scopes`.
|
||||
Автентифікація trusted-proxy — це HTTP-режим, **що несе ідентичність**, тому викликачі за бажанням можуть оголошувати області оператора через `x-openclaw-scopes`.
|
||||
|
||||
Приклади:
|
||||
|
||||
@ -315,43 +315,44 @@ Loopback trusted-proxy автентифікація також працює за
|
||||
Поведінка:
|
||||
|
||||
- Коли заголовок присутній, OpenClaw враховує оголошений набір областей.
|
||||
- Коли заголовок присутній, але порожній, запит оголошує **жодних** областей операторів.
|
||||
- Коли заголовок відсутній, звичайні HTTP API, що несуть ідентичність, повертаються до стандартного набору областей операторів за замовчуванням.
|
||||
- **HTTP-маршрути Plugin** з gateway-auth за замовчуванням вужчі: коли `x-openclaw-scopes` відсутній, їхня область виконання повертається до `operator.write`.
|
||||
- HTTP-запити з браузера все одно мають проходити `gateway.controlUi.allowedOrigins` (або навмисний резервний режим Host-заголовка), навіть після успішної trusted-proxy автентифікації.
|
||||
- Коли заголовок присутній, але порожній, запит не оголошує **жодних** областей оператора.
|
||||
- Коли заголовок відсутній, звичайні HTTP API, що несуть ідентичність, повертаються до стандартного набору областей оператора за замовчуванням.
|
||||
- **HTTP-маршрути Plugin** з автентифікацією Gateway за замовчуванням вужчі: коли `x-openclaw-scopes` відсутній, їхня область часу виконання повертається до `operator.write`.
|
||||
- HTTP-запити з браузера все одно мають пройти `gateway.controlUi.allowedOrigins` (або навмисний резервний режим заголовка Host) навіть після успішної trusted-proxy auth.
|
||||
|
||||
Практичне правило: надсилайте `x-openclaw-scopes` явно, коли хочете, щоб trusted-proxy запит мав вужчі області, ніж типові значення за замовчуванням, або коли маршруту Plugin з gateway-auth потрібне щось сильніше за область write.
|
||||
Практичне правило: надсилайте `x-openclaw-scopes` явно, коли хочете, щоб trusted-proxy запит був вужчим за значення за замовчуванням, або коли маршруту plugin з автентифікацією Gateway потрібне щось сильніше за область write.
|
||||
|
||||
## Контрольний список безпеки
|
||||
|
||||
Перш ніж увімкнути автентифікацію trusted-proxy, перевірте:
|
||||
Перш ніж увімкнути trusted-proxy auth, переконайтеся, що:
|
||||
|
||||
- [ ] **Проксі є єдиним шляхом**: Порт Gateway захищений фаєрволом від усього, окрім вашого проксі.
|
||||
- [ ] **Проксі — єдиний шлях**: Порт Gateway закритий фаєрволом для всіх, окрім вашого проксі.
|
||||
- [ ] **trustedProxies мінімальний**: Лише фактичні IP-адреси вашого проксі, а не цілі підмережі.
|
||||
- [ ] **Немає loopback-джерела проксі**: автентифікація trusted-proxy працює за принципом fail closed для запитів із loopback-джерела.
|
||||
- [ ] **Проксі видаляє заголовки**: Ваш проксі перезаписує (а не додає) заголовки `x-forwarded-*`, отримані від клієнтів.
|
||||
- [ ] **Немає loopback-джерела проксі**: trusted-proxy auth відмовляє в закритому режимі для запитів із loopback-джерела.
|
||||
- [ ] **Проксі очищує заголовки**: Ваш проксі перезаписує (а не додає) заголовки `x-forwarded-*`, що надходять від клієнтів.
|
||||
- [ ] **Завершення TLS**: Ваш проксі обробляє TLS; користувачі підключаються через HTTPS.
|
||||
- [ ] **allowedOrigins явний**: Control UI поза loopback використовує явний `gateway.controlUi.allowedOrigins`.
|
||||
- [ ] **allowUsers налаштовано** (рекомендовано): Обмежуйте доступ відомими користувачами, а не дозволяйте будь-кому, хто пройшов автентифікацію.
|
||||
- [ ] **Немає змішаної конфігурації токена**: Не налаштовуйте одночасно `gateway.auth.token` і `gateway.auth.mode: "trusted-proxy"`.
|
||||
- [ ] **allowedOrigins задано явно**: Для не-loopback Control UI використовується явний `gateway.controlUi.allowedOrigins`.
|
||||
- [ ] **allowUsers задано** (рекомендовано): Обмежте доступ відомими користувачами, а не дозволяйте його будь-кому, хто автентифікувався.
|
||||
- [ ] **Немає змішаної конфігурації токенів**: Не встановлюйте одночасно `gateway.auth.token` і `gateway.auth.mode: "trusted-proxy"`.
|
||||
- [ ] **Локальний резервний пароль є приватним**: Якщо ви налаштовуєте `gateway.auth.password` для внутрішніх прямих викликачів, тримайте порт Gateway закритим фаєрволом, щоб віддалені клієнти не через проксі не могли напряму до нього підключитися.
|
||||
|
||||
## Аудит безпеки
|
||||
|
||||
`openclaw security audit` позначить автентифікацію trusted-proxy як проблему з рівнем серйозності **critical**. Це навмисно — це нагадування про те, що ви делегуєте безпеку вашій конфігурації проксі.
|
||||
`openclaw security audit` позначить автентифікацію trusted-proxy як проблему з рівнем серйозності **critical**. Це зроблено навмисно — як нагадування, що ви делегуєте безпеку конфігурації свого проксі.
|
||||
|
||||
Аудит перевіряє:
|
||||
|
||||
- Базове попередження/нагадування warning/critical для `gateway.trusted_proxy_auth`
|
||||
- Відсутня конфігурація `trustedProxies`
|
||||
- Відсутня конфігурація `userHeader`
|
||||
- Базове попередження/критичне нагадування `gateway.trusted_proxy_auth`
|
||||
- Відсутню конфігурацію `trustedProxies`
|
||||
- Відсутню конфігурацію `userHeader`
|
||||
- Порожній `allowUsers` (дозволяє будь-якого автентифікованого користувача)
|
||||
- Політика browser-origin із wildcard або її відсутність на відкритих поверхнях Control UI
|
||||
- Політику browser-origin із wildcard або її відсутність на відкритих поверхнях Control UI
|
||||
|
||||
## Усунення несправностей
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="trusted_proxy_untrusted_source">
|
||||
Запит не надійшов з IP-адреси, вказаної в `gateway.trustedProxies`. Перевірте:
|
||||
Запит надійшов не з IP-адреси в `gateway.trustedProxies`. Перевірте:
|
||||
|
||||
- Чи правильна IP-адреса проксі? (IP-адреси контейнерів Docker можуть змінюватися.)
|
||||
- Чи є балансувальник навантаження перед вашим проксі?
|
||||
@ -364,18 +365,18 @@ Loopback trusted-proxy автентифікація також працює за
|
||||
Перевірте:
|
||||
|
||||
- Чи підключається проксі з `127.0.0.1` / `::1`?
|
||||
- Чи намагаєтеся ви використовувати trusted-proxy автентифікацію зі зворотним loopback-проксі на тому самому хості?
|
||||
- Чи намагаєтеся ви використовувати trusted-proxy auth зі зворотним проксі на loopback на тому самому хості?
|
||||
|
||||
Виправлення:
|
||||
|
||||
- Використовуйте автентифікацію за токеном/паролем для конфігурацій із loopback-проксі на тому самому хості, або
|
||||
- Маршрутизуйте через не-loopback адресу довіреного проксі та збережіть цю IP-адресу в `gateway.trustedProxies`.
|
||||
- Використовуйте автентифікацію токеном/паролем для конфігурацій проксі на loopback на тому самому хості, або
|
||||
- Маршрутизуйте через не-loopback адресу довіреного проксі та тримайте цю IP-адресу в `gateway.trustedProxies`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="trusted_proxy_user_missing">
|
||||
Заголовок користувача був порожній або відсутній. Перевірте:
|
||||
Заголовок користувача був порожнім або відсутнім. Перевірте:
|
||||
|
||||
- Чи налаштований ваш проксі на передавання заголовків ідентичності?
|
||||
- Чи налаштовано ваш проксі на передавання заголовків ідентичності?
|
||||
- Чи правильна назва заголовка? (регістр не має значення, але написання має)
|
||||
- Чи користувач справді автентифікований на проксі?
|
||||
|
||||
@ -388,47 +389,47 @@ Loopback trusted-proxy автентифікація також працює за
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="trusted_proxy_user_not_allowed">
|
||||
Користувач автентифікований, але його немає в `allowUsers`. Або додайте його, або видаліть список дозволених.
|
||||
Користувач автентифікований, але його немає в `allowUsers`. Або додайте його, або приберіть список дозволених.
|
||||
</Accordion>
|
||||
<Accordion title="trusted_proxy_origin_not_allowed">
|
||||
Trusted-proxy автентифікація пройшла успішно, але заголовок браузера `Origin` не пройшов перевірки походження Control UI.
|
||||
Автентифікація trusted-proxy пройшла успішно, але заголовок браузера `Origin` не пройшов перевірки походження Control UI.
|
||||
|
||||
Перевірте:
|
||||
|
||||
- `gateway.controlUi.allowedOrigins` містить точне browser origin.
|
||||
- Ви не покладаєтеся на wildcard origins, якщо тільки навмисно не хочете поведінку «дозволити все».
|
||||
- Якщо ви навмисно використовуєте резервний режим Host-заголовка, `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` налаштовано свідомо.
|
||||
- Ви не покладаєтеся на wildcard origins, якщо тільки свідомо не хочете поведінку «дозволити все».
|
||||
- Якщо ви навмисно використовуєте резервний режим заголовка Host, `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` задано свідомо.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="WebSocket still failing">
|
||||
<Accordion title="WebSocket все ще не працює">
|
||||
Переконайтеся, що ваш проксі:
|
||||
|
||||
- Підтримує оновлення WebSocket (`Upgrade: websocket`, `Connection: upgrade`).
|
||||
- Передає заголовки ідентичності в запитах на оновлення WebSocket (а не лише для HTTP).
|
||||
- Не має окремого шляху автентифікації для з’єднань WebSocket.
|
||||
- Передає заголовки ідентичності в запитах оновлення WebSocket (а не лише HTTP).
|
||||
- Не має окремого шляху автентифікації для підключень WebSocket.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Міграція з автентифікації за токеном
|
||||
## Міграція з автентифікації токеном
|
||||
|
||||
Якщо ви переходите з автентифікації за токеном на trusted-proxy:
|
||||
Якщо ви переходите з автентифікації токеном на trusted-proxy:
|
||||
|
||||
<Steps>
|
||||
<Step title="Налаштуйте проксі">
|
||||
Налаштуйте ваш проксі на автентифікацію користувачів і передавання заголовків.
|
||||
Налаштуйте свій проксі на автентифікацію користувачів і передавання заголовків.
|
||||
</Step>
|
||||
<Step title="Окремо протестуйте проксі">
|
||||
Окремо протестуйте налаштування проксі (`curl` із заголовками).
|
||||
</Step>
|
||||
<Step title="Оновіть конфігурацію OpenClaw">
|
||||
Оновіть конфігурацію OpenClaw для trusted-proxy автентифікації.
|
||||
Оновіть конфігурацію OpenClaw для trusted-proxy auth.
|
||||
</Step>
|
||||
<Step title="Перезапустіть Gateway">
|
||||
Перезапустіть Gateway.
|
||||
</Step>
|
||||
<Step title="Перевірте WebSocket">
|
||||
Перевірте з’єднання WebSocket з Control UI.
|
||||
<Step title="Протестуйте WebSocket">
|
||||
Протестуйте WebSocket-підключення з Control UI.
|
||||
</Step>
|
||||
<Step title="Аудит">
|
||||
Запустіть `openclaw security audit` і перегляньте результати.
|
||||
@ -437,7 +438,7 @@ Loopback trusted-proxy автентифікація також працює за
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Конфігурація](/uk/gateway/configuration) — довідник конфігурації
|
||||
- [Конфігурація](/uk/gateway/configuration) — довідник із конфігурації
|
||||
- [Віддалений доступ](/uk/gateway/remote) — інші шаблони віддаленого доступу
|
||||
- [Безпека](/uk/gateway/security) — повний посібник із безпеки
|
||||
- [Tailscale](/uk/gateway/tailscale) — простіша альтернатива для доступу лише в межах tailnet
|
||||
- [Tailscale](/uk/gateway/tailscale) — простіша альтернатива для доступу лише в tailnet
|
||||
|
||||
@ -1,312 +1,312 @@
|
||||
---
|
||||
read_when:
|
||||
- Вибір правильного підшляху plugin-sdk для імпорту Plugin
|
||||
- Вибір правильного підшляху plugin-sdk для імпорту plugin
|
||||
- Аудит підшляхів bundled-plugin і допоміжних поверхонь
|
||||
summary: 'Каталог підшляхів Plugin SDK: які імпорти де розміщені, згруповано за областями'
|
||||
title: Підшляхи Plugin SDK
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T21:58:46Z"
|
||||
generated_at: "2026-04-27T22:22:42Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: c0a164b1e967c1e794c6f03f5a2ff42ec2b8121dd7e4b1232c8ede10d97a7ebb
|
||||
source_hash: 56f76f2371500ab77dc791ba862cb628daec596059f1f9def7227fecb2826347
|
||||
source_path: plugins/sdk-subpaths.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Plugin SDK доступний як набір вузьких підшляхів у `openclaw/plugin-sdk/`.
|
||||
На цій сторінці каталогізовано найуживаніші підшляхи, згруповані за призначенням. Згенерований
|
||||
Plugin SDK представлений як набір вузьких підшляхів у `openclaw/plugin-sdk/`.
|
||||
На цій сторінці наведено каталог поширено вживаних підшляхів, згрупованих за призначенням. Згенерований
|
||||
повний список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`;
|
||||
зарезервовані допоміжні підшляхи bundled-plugin також наведені там, але є деталями
|
||||
реалізації, якщо лише сторінка документації явно не рекомендує їх.
|
||||
реалізації, якщо лише сторінка документації явно не просуває їх.
|
||||
|
||||
Посібник з розробки Plugin дивіться в [Огляд Plugin SDK](/uk/plugins/sdk-overview).
|
||||
Посібник з розробки plugin див. у [Огляд Plugin SDK](/uk/plugins/sdk-overview).
|
||||
|
||||
## Точка входу Plugin
|
||||
## Точка входу plugin
|
||||
|
||||
| Підшлях | Основні експорти |
|
||||
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
|
||||
| `plugin-sdk/config-schema` | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/migration` | Допоміжні елементи постачальника міграцій, такі як `createMigrationItem`, константи причин, маркери статусу елементів, допоміжні засоби редагування та `summarizeMigrationItems` |
|
||||
| `plugin-sdk/migration-runtime` | Допоміжні засоби міграції під час виконання, такі як `copyMigrationFileItem` і `writeMigrationReport` |
|
||||
| Subpath | Основні експорти |
|
||||
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
|
||||
| `plugin-sdk/config-schema` | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/migration` | Допоміжні засоби елементів провайдера міграції, такі як `createMigrationItem`, константи причин, маркери статусу елементів, засоби редагування та `summarizeMigrationItems` |
|
||||
| `plugin-sdk/migration-runtime` | Допоміжні засоби міграції під час виконання, такі як `copyMigrationFileItem` і `writeMigrationReport` |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Підшляхи каналів">
|
||||
| Підшлях | Основні експорти |
|
||||
| Subpath | Основні експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/config-schema` | Експорт кореневої схеми Zod для `openclaw.json` (`OpenClawSchema`) |
|
||||
| `plugin-sdk/config-schema` | Експорт кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`) |
|
||||
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, підказки списку дозволених, побудовники статусу налаштування |
|
||||
| `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, підказки allowlist, побудовники статусу налаштування |
|
||||
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
|
||||
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | Допоміжні засоби для конфігурації кількох облікових записів і шлюзування дій, допоміжні засоби резервного переходу до облікового запису за замовчуванням |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації ідентифікатора облікового запису |
|
||||
| `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису та резервного переходу до значення за замовчуванням |
|
||||
| `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списку облікових записів і дій над обліковими записами |
|
||||
| `plugin-sdk/account-core` | Допоміжні засоби багатокористувацького конфігу/керування шлюзами дій, допоміжні засоби резервного переходу до типового облікового запису |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації account-id |
|
||||
| `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису + резервного переходу до типового |
|
||||
| `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списків облікових записів/дій з обліковими записами |
|
||||
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | Спільні примітиви схеми конфігурації каналу та універсальний побудовник |
|
||||
| `plugin-sdk/channel-config-schema-legacy` | Застарілі схеми конфігурації bundled-channel лише для сумісності з bundled |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервною сумісністю з bundled-контрактом |
|
||||
| `plugin-sdk/channel-config-schema` | Спільні примітиви схеми конфігу каналу та узагальнений побудовник |
|
||||
| `plugin-sdk/channel-config-schema-legacy` | Застарілі схеми конфігу bundled-channel лише для сумісності з вбудованими компонентами |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервною сумісністю з bundled-contract |
|
||||
| `plugin-sdk/command-gating` | Вузькі допоміжні засоби шлюзу авторизації команд |
|
||||
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/завершення чернеткового потоку |
|
||||
| `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби маршрутизації вхідних повідомлень і побудови конверта |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису та диспетчеризації вхідних повідомлень |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/фіналізації потоку чернеток |
|
||||
| `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби побудови вхідних маршрутів і envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису й диспетчеризації вхідних повідомлень |
|
||||
| `plugin-sdk/messaging-targets` | Допоміжні засоби розбору/зіставлення цілей |
|
||||
| `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження вихідних медіа |
|
||||
| `plugin-sdk/outbound-send-deps` | Легковаговий пошук залежностей надсилання вихідних повідомлень для адаптерів каналів |
|
||||
| `plugin-sdk/outbound-runtime` | Допоміжні засоби доставки вихідних повідомлень, ідентифікації, делегата надсилання, сесії, форматування та планування корисного навантаження |
|
||||
| `plugin-sdk/outbound-send-deps` | Полегшений пошук залежностей вихідного надсилання для адаптерів каналів |
|
||||
| `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідної доставки, ідентичності, делегата надсилання, сесій, форматування та планування payload |
|
||||
| `plugin-sdk/poll-runtime` | Вузькі допоміжні засоби нормалізації опитувань |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу прив’язок потоків і адаптерів |
|
||||
| `plugin-sdk/agent-media-payload` | Застарілий побудовник медіакорисного навантаження агента |
|
||||
| `plugin-sdk/conversation-runtime` | Допоміжні засоби прив’язки розмов/потоків, pairинг і налаштованих прив’язок |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Життєвий цикл прив’язок потоків та допоміжні засоби адаптерів |
|
||||
| `plugin-sdk/agent-media-payload` | Застарілий побудовник agent media payload |
|
||||
| `plugin-sdk/conversation-runtime` | Допоміжні засоби для прив’язки розмов/потоків, pairинг і налаштованих прив’язок |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб знімка конфігурації під час виконання |
|
||||
| `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення групової політики під час виконання |
|
||||
| `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення групових політик під час виконання |
|
||||
| `plugin-sdk/channel-status` | Спільні допоміжні засоби знімка/підсумку стану каналу |
|
||||
| `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації каналу |
|
||||
| `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації каналу |
|
||||
| `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти Plugin каналу |
|
||||
| `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації списку дозволених |
|
||||
| `plugin-sdk/group-access` | Спільні допоміжні засоби прийняття рішень щодо групового доступу |
|
||||
| `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігу каналу |
|
||||
| `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігу каналу |
|
||||
| `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти plugin каналу |
|
||||
| `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації allowlist |
|
||||
| `plugin-sdk/group-access` | Спільні допоміжні засоби для рішень щодо групового доступу |
|
||||
| `plugin-sdk/direct-dm` | Спільні допоміжні засоби авторизації/захисту прямих DM |
|
||||
| `plugin-sdk/interactive-runtime` | Семантичне представлення повідомлень, доставка та застарілі допоміжні засоби інтерактивних відповідей. Див. [Представлення повідомлень](/uk/plugins/message-presentation) |
|
||||
| `plugin-sdk/channel-inbound` | Barrel сумісності для debounce вхідних повідомлень, зіставлення згадок, допоміжних засобів політики згадок і допоміжних засобів конверта |
|
||||
| `plugin-sdk/channel-inbound` | Сумісний barrel для debounce вхідних повідомлень, зіставлення згадок, допоміжних засобів політики згадок та допоміжних засобів envelope |
|
||||
| `plugin-sdk/channel-inbound-debounce` | Вузькі допоміжні засоби debounce для вхідних повідомлень |
|
||||
| `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби політики згадок, маркерів згадок і тексту згадок без ширшої поверхні середовища виконання вхідних повідомлень |
|
||||
| `plugin-sdk/channel-envelope` | Вузькі допоміжні засоби форматування конверта вхідних повідомлень |
|
||||
| `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби політики згадок, маркерів згадок і тексту згадок без ширшої поверхні inbound runtime |
|
||||
| `plugin-sdk/channel-envelope` | Вузькі допоміжні засоби форматування вхідних envelope |
|
||||
| `plugin-sdk/channel-location` | Допоміжні засоби контексту розташування каналу та форматування |
|
||||
| `plugin-sdk/channel-logging` | Допоміжні засоби журналювання каналу для відкинутих вхідних повідомлень і помилок typing/ack |
|
||||
| `plugin-sdk/channel-logging` | Допоміжні засоби журналювання каналу для відкинутих вхідних повідомлень і збоїв typing/ack |
|
||||
| `plugin-sdk/channel-send-result` | Типи результатів відповіді |
|
||||
| `plugin-sdk/channel-actions` | Допоміжні засоби дій із повідомленнями каналу, а також застарілі допоміжні засоби нативної схеми, збережені для сумісності Plugin |
|
||||
| `plugin-sdk/channel-actions` | Допоміжні засоби дій із повідомленнями каналу, а також застарілі рідні допоміжні засоби схем, збережені для сумісності plugin |
|
||||
| `plugin-sdk/channel-targets` | Допоміжні засоби розбору/зіставлення цілей |
|
||||
| `plugin-sdk/channel-contract` | Типи контрактів каналу |
|
||||
| `plugin-sdk/channel-feedback` | Підключення відгуків/реакцій |
|
||||
| `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби контракту секретів, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей секретів |
|
||||
| `plugin-sdk/channel-feedback` | Підключення зворотного зв’язку/реакцій |
|
||||
| `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби контрактів секретів, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей секретів |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи постачальників">
|
||||
| Підшлях | Основні експорти |
|
||||
<Accordion title="Підшляхи провайдерів">
|
||||
| Subpath | Основні експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/lmstudio` | Підтримуваний фасад постачальника LM Studio для налаштування, виявлення каталогу та підготовки моделі під час виконання |
|
||||
| `plugin-sdk/lmstudio-runtime` | Підтримуваний фасад середовища виконання LM Studio для типових значень локального сервера, виявлення моделей, заголовків запитів і допоміжних засобів для завантажених моделей |
|
||||
| `plugin-sdk/provider-setup` | Кураторовані допоміжні засоби налаштування локальних/самостійно розміщених постачальників |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Цільові допоміжні засоби налаштування самостійно розміщених постачальників, сумісних з OpenAI |
|
||||
| `plugin-sdk/cli-backend` | Типові значення бекенда CLI та константи watchdog |
|
||||
| `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-ключа під час виконання для Plugin постачальників |
|
||||
| `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу API-ключа/запису профілю, такі як `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/lmstudio` | Підтримуваний фасад провайдера LM Studio для налаштування, виявлення каталогу та підготовки моделей під час виконання |
|
||||
| `plugin-sdk/lmstudio-runtime` | Підтримуваний runtime-фасад LM Studio для типових локальних серверів, виявлення моделей, заголовків запитів і допоміжних засобів завантажених моделей |
|
||||
| `plugin-sdk/provider-setup` | Кураторський набір допоміжних засобів налаштування локальних/self-hosted провайдерів |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted провайдерів, сумісних з OpenAI |
|
||||
| `plugin-sdk/cli-backend` | Типові значення CLI backend + константи watchdog |
|
||||
| `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-ключа під час виконання для plugin провайдерів |
|
||||
| `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу API-ключів/запису профілів, такі як `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | Стандартний побудовник результату OAuth-автентифікації |
|
||||
| `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для Plugin постачальників |
|
||||
| `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env var для автентифікації постачальників |
|
||||
| `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для plugin провайдерів |
|
||||
| `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env vars для автентифікації провайдерів |
|
||||
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники політик повторного відтворення, допоміжні засоби кінцевих точок постачальників і допоміжні засоби нормалізації ідентифікаторів моделей, такі як `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-catalog-runtime` | Хук середовища виконання каталогу постачальників і шви реєстру postачальників Plugin для тестів контрактів |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники політик повтору, допоміжні засоби endpoint провайдерів і допоміжні засоби нормалізації model-id, такі як `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-catalog-runtime` | Хуки runtime каталогу провайдерів і шви реєстру plugin-провайдерів для тестів контрактів |
|
||||
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-http` | Універсальні допоміжні засоби HTTP/можливостей кінцевих точок постачальників, HTTP-помилки постачальників і допоміжні засоби multipart form для транскрипції аудіо |
|
||||
| `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту конфігурації/вибору web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` |
|
||||
| `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування постачальників web-fetch |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби конфігурації/облікових даних web-search для постачальників, яким не потрібне підключення увімкнення Plugin |
|
||||
| `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setters/getters облікових даних |
|
||||
| `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/середовища виконання постачальників web-search |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini та діагностика, а також допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/endpoint-можливостей провайдерів, помилки HTTP провайдерів і допоміжні засоби multipart form для аудіотранскрипції |
|
||||
| `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контрактів конфігурації/вибору web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` |
|
||||
| `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування провайдерів web-fetch |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби конфігурації/облікових даних web-search для провайдерів, яким не потрібне підключення увімкнення plugin |
|
||||
| `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контрактів конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter для облікових даних |
|
||||
| `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime для провайдерів web-search |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика та допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібні |
|
||||
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоків і спільні допоміжні засоби обгорток для Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-transport-runtime` | Нативні допоміжні засоби транспорту постачальників, такі як guarded fetch, трансформації транспортних повідомлень і потоки подій транспорту з можливістю запису |
|
||||
| `plugin-sdk/provider-onboard` | Допоміжні засоби виправлення конфігурації онбордингу |
|
||||
| `plugin-sdk/provider-transport-runtime` | Власні допоміжні засоби транспортного рівня провайдерів, такі як guarded fetch, перетворення транспортних повідомлень і записувані потоки транспортних подій |
|
||||
| `plugin-sdk/provider-onboard` | Допоміжні засоби патчів конфігурації онбордингу |
|
||||
| `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache |
|
||||
| `plugin-sdk/group-activation` | Вузькі допоміжні засоби режиму активації груп і розбору команд |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи автентифікації та безпеки">
|
||||
| Підшлях | Основні експорти |
|
||||
| Subpath | Основні експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, включно з форматуванням меню динамічних аргументів, допоміжні засоби авторизації відправника |
|
||||
| `plugin-sdk/command-status` | Побудовники повідомлень команд/довідки, такі як `buildCommandsMessagePaginated` і `buildHelpMessage` |
|
||||
| `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення затверджувача та автентифікації дій у тому самому чаті |
|
||||
| `plugin-sdk/approval-client-runtime` | Нативні допоміжні засоби профілю/фільтра затвердження exec |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Нативні адаптери можливостей/доставки затвердження |
|
||||
| `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення Gateway затвердження |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | Легковагові допоміжні засоби завантаження нативного адаптера затвердження для гарячих точок входу каналів |
|
||||
| `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби середовища виконання обробника затвердження; віддавайте перевагу вужчим adapter/gateway seams, якщо їх достатньо |
|
||||
| `plugin-sdk/approval-native-runtime` | Нативні допоміжні засоби цілей затвердження та прив’язки облікових записів |
|
||||
| `plugin-sdk/approval-reply-runtime` | Допоміжні засоби корисного навантаження відповіді затвердження exec/plugin |
|
||||
| `plugin-sdk/approval-runtime` | Допоміжні засоби корисного навантаження затвердження exec/plugin, нативні допоміжні засоби маршрутизації/середовища виконання затвердження та допоміжні засоби структурованого відображення затвердження, такі як `formatApprovalDisplayPath` |
|
||||
| `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення затверджувача та автентифікації дій у тому ж чаті |
|
||||
| `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра native exec approval |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Native-адаптери можливостей/доставки approval |
|
||||
| `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення gateway для approval |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | Полегшені допоміжні засоби завантаження native-адаптерів approval для гарячих точок входу каналів |
|
||||
| `plugin-sdk/approval-handler-runtime` | Ширші runtime-допоміжні засоби для approval; віддавайте перевагу вужчим адаптерним/Gateway-швам, коли їх достатньо |
|
||||
| `plugin-sdk/approval-native-runtime` | Допоміжні засоби native approval target + прив’язки облікових записів |
|
||||
| `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповідей для exec/plugin approval |
|
||||
| `plugin-sdk/approval-runtime` | Допоміжні засоби payload для exec/plugin approval, native-допоміжні засоби маршрутизації/runtime approval і допоміжні засоби структурованого відображення approval, такі як `formatApprovalDisplayPath` |
|
||||
| `plugin-sdk/reply-dedupe` | Вузькі допоміжні засоби скидання дедуплікації вхідних відповідей |
|
||||
| `plugin-sdk/channel-contract-testing` | Вузькі допоміжні засоби тестування контракту каналу без широкого testing barrel |
|
||||
| `plugin-sdk/command-auth-native` | Нативні допоміжні засоби автентифікації команд, форматування меню динамічних аргументів і нативні допоміжні засоби цілей сесії |
|
||||
| `plugin-sdk/channel-contract-testing` | Вузькі допоміжні засоби тестування контрактів каналів без широкого testing barrel |
|
||||
| `plugin-sdk/command-auth-native` | Native-автентифікація команд, форматування меню динамічних аргументів і native-допоміжні засоби цілей сесій |
|
||||
| `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд |
|
||||
| `plugin-sdk/command-primitives-runtime` | Легковагові предикати тексту команд для гарячих шляхів каналів |
|
||||
| `plugin-sdk/command-surface` | Нормалізація тіла команди та допоміжні засоби command-surface |
|
||||
| `plugin-sdk/command-primitives-runtime` | Полегшені предикати тексту команд для гарячих шляхів каналів |
|
||||
| `plugin-sdk/command-surface` | Нормалізація тіла команд і допоміжні засоби поверхні команд |
|
||||
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання secret-contract для поверхонь секретів channel/plugin |
|
||||
| `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для парсингу secret-contract/config |
|
||||
| `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, шлюзування DM, зовнішнього вмісту, редагування чутливого тексту, порівняння секретів за сталий час і збирання секретів |
|
||||
| `plugin-sdk/ssrf-policy` | Допоміжні засоби allowlist хостів і політики SSRF для приватних мереж |
|
||||
| `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned-dispatcher без широкої поверхні infra runtime |
|
||||
| `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом SSRF, помилки SSRF і політики SSRF |
|
||||
| `plugin-sdk/secret-input` | Допоміжні засоби парсингу введення секретів |
|
||||
| `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання секретних контрактів для поверхонь секретів channel/plugin |
|
||||
| `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для розбору секретних контрактів/конфігурації |
|
||||
| `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, DM gating, зовнішнього вмісту, редагування чутливого тексту, порівняння секретів у сталий час і збирання секретів |
|
||||
| `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для allowlist хостів і приватних мереж |
|
||||
| `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned-dispatcher без широкої infra runtime-поверхні |
|
||||
| `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом SSRF, помилка SSRF і допоміжні засоби політики SSRF |
|
||||
| `plugin-sdk/secret-input` | Допоміжні засоби розбору секретного введення |
|
||||
| `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів/цілей Webhook і приведення raw websocket/body |
|
||||
| `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру тіла запиту/тайм-ауту |
|
||||
| `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру тіла запиту/тайм-аутів |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи середовища виконання та сховища">
|
||||
| Підшлях | Основні експорти |
|
||||
<Accordion title="Підшляхи runtime і сховища">
|
||||
| Subpath | Основні експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/runtime` | Широкі допоміжні засоби середовища виконання/журналювання/резервного копіювання/встановлення plugin |
|
||||
| `plugin-sdk/runtime-env` | Вузькі допоміжні засоби env середовища виконання, logger, timeout, retry і backoff |
|
||||
| `plugin-sdk/browser-config` | Підтримуваний фасад конфігурації браузера для нормалізованого профілю/типових значень, парсингу URL CDP та допоміжних засобів автентифікації керування браузером |
|
||||
| `plugin-sdk/channel-runtime-context` | Універсальні допоміжні засоби реєстрації та пошуку контексту середовища виконання каналу |
|
||||
| `plugin-sdk/runtime` | Широкі runtime/логування/резервного копіювання/встановлення plugin допоміжні засоби |
|
||||
| `plugin-sdk/runtime-env` | Вузькі допоміжні засоби runtime env, logger, timeout, retry і backoff |
|
||||
| `plugin-sdk/browser-config` | Підтримуваний фасад конфігурації браузера для нормалізованого профілю/типових значень, розбору CDP URL і допоміжних засобів автентифікації browser-control |
|
||||
| `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби реєстрації та пошуку runtime-context каналу |
|
||||
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/хуків/http/інтерактивності plugin |
|
||||
| `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline Webhook/внутрішніх хуків |
|
||||
| `plugin-sdk/lazy-runtime` | Допоміжні засоби ледачого імпорту/прив’язки runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Допоміжні засоби exec процесів |
|
||||
| `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування, версій, виклику аргументів і ледачих груп команд |
|
||||
| `plugin-sdk/gateway-runtime` | Клієнт Gateway, CLI RPC Gateway, помилки протоколу Gateway та допоміжні засоби patch статусу каналу |
|
||||
| `plugin-sdk/config-types` | Поверхня конфігурації лише для типів для форм конфігурації plugin, таких як `OpenClawConfig`, і типів конфігурації каналів/постачальників |
|
||||
| `plugin-sdk/plugin-config-runtime` | Допоміжні засоби пошуку конфігурації plugin під час виконання, такі як `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` |
|
||||
| `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби command/hook/http/interactive для plugin |
|
||||
| `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline Webhook/internal hook |
|
||||
| `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy runtime import/binding, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Допоміжні засоби виконання процесів |
|
||||
| `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування, версій, виклику аргументів і lazy command-group |
|
||||
| `plugin-sdk/gateway-runtime` | Допоміжні засоби Gateway client, Gateway CLI RPC, помилок протоколу Gateway і патчів статусу каналу |
|
||||
| `plugin-sdk/config-types` | Поверхня конфігурації лише для типів для форм конфігурації plugin, таких як `OpenClawConfig` і типи конфігурації каналів/провайдерів |
|
||||
| `plugin-sdk/plugin-config-runtime` | Runtime-допоміжні засоби пошуку plugin-config, такі як `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` |
|
||||
| `plugin-sdk/config-mutation` | Допоміжні засоби транзакційної мутації конфігурації, такі як `mutateConfigFile`, `replaceConfigFile` і `logConfigUpdated` |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Допоміжні засоби знімка конфігурації поточного процесу, такі як `getRuntimeConfig`, `getRuntimeConfigSnapshot` і setters тестових знімків |
|
||||
| `plugin-sdk/telegram-command-config` | Нормалізація назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня bundled-контракту Telegram недоступна |
|
||||
| `plugin-sdk/text-autolink-runtime` | Виявлення автопосилань на файлові посилання без широкого text-runtime barrel |
|
||||
| `plugin-sdk/approval-runtime` | Допоміжні засоби затвердження exec/plugin, побудовники можливостей затвердження, допоміжні засоби auth/profile, нативні допоміжні засоби маршрутизації/середовища виконання та форматування шляху структурованого відображення затвердження |
|
||||
| `plugin-sdk/reply-runtime` | Спільні допоміжні засоби середовища виконання вхідних повідомлень/відповідей, chunking, dispatch, Heartbeat, планувальник відповідей |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize відповідей і допоміжні засоби міток розмов |
|
||||
| `plugin-sdk/reply-history` | Спільні допоміжні засоби коротковіконної історії відповідей і маркери, такі як `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Допоміжні засоби знімка конфігурації поточного процесу, такі як `getRuntimeConfig`, `getRuntimeConfigSnapshot` і setter-и тестових знімків |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня контракту bundled Telegram недоступна |
|
||||
| `plugin-sdk/text-autolink-runtime` | Виявлення autolink посилань на файли без широкого text-runtime barrel |
|
||||
| `plugin-sdk/approval-runtime` | Допоміжні засоби exec/plugin approval, побудовники можливостей approval, допоміжні засоби auth/profile, native-допоміжні засоби routing/runtime і форматування шляху структурованого відображення approval |
|
||||
| `plugin-sdk/reply-runtime` | Спільні runtime-допоміжні засоби inbound/reply, розбиття на частини, диспетчеризація, Heartbeat, планувальник відповідей |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби диспетчеризації/фіналізації відповідей і міток розмов |
|
||||
| `plugin-sdk/reply-history` | Спільні допоміжні засоби short-window history відповідей і маркери, такі як `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/Markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища сесій, ключа сесії, updated-at і мутації сховища |
|
||||
| `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища сесій, ключа сесії, updated-at і мутацій сховища |
|
||||
| `plugin-sdk/cron-store-runtime` | Допоміжні засоби шляху/завантаження/збереження сховища Cron |
|
||||
| `plugin-sdk/state-paths` | Допоміжні засоби шляхів каталогів state/OAuth |
|
||||
| `plugin-sdk/routing` | Допоміжні засоби маршруту/ключа сесії/прив’язки облікового запису, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку статусу каналу/облікового запису, типові значення стану середовища виконання та допоміжні засоби метаданих проблем |
|
||||
| `plugin-sdk/state-paths` | Допоміжні засоби шляхів директорій state/OAuth |
|
||||
| `plugin-sdk/routing` | Допоміжні засоби маршрутизації/ключа сесії/прив’язки облікових записів, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку стану каналу/облікового запису, типові значення runtime-state і допоміжні засоби метаданих проблем |
|
||||
| `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби визначення цілей |
|
||||
| `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації slug/рядків |
|
||||
| `plugin-sdk/request-url` | Витягування рядкових URL з fetch/request-подібних вхідних даних |
|
||||
| `plugin-sdk/run-command` | Виконавець команд із тайм-аутом із нормалізованими результатами stdout/stderr |
|
||||
| `plugin-sdk/param-readers` | Стандартні читачі параметрів tool/CLI |
|
||||
| `plugin-sdk/tool-payload` | Витягування нормалізованих payload із об’єктів результатів tool |
|
||||
| `plugin-sdk/request-url` | Витягування рядкових URL з fetch/request-подібних входів |
|
||||
| `plugin-sdk/run-command` | Запускач команд із таймуванням і нормалізованими результатами stdout/stderr |
|
||||
| `plugin-sdk/param-readers` | Поширені зчитувачі параметрів tool/CLI |
|
||||
| `plugin-sdk/tool-payload` | Витягування нормалізованих payload з об’єктів результатів tool |
|
||||
| `plugin-sdk/tool-send` | Витягування канонічних полів цілі надсилання з аргументів tool |
|
||||
| `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів тимчасового завантаження |
|
||||
| `plugin-sdk/logging-core` | Допоміжні засоби logger підсистем і редагування |
|
||||
| `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму таблиць Markdown і перетворення |
|
||||
| `plugin-sdk/model-session-runtime` | Допоміжні засоби перевизначення моделі/сесії, такі як `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` |
|
||||
| `plugin-sdk/talk-config-runtime` | Допоміжні засоби визначення конфігурації постачальника talk |
|
||||
| `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису стану JSON |
|
||||
| `plugin-sdk/file-lock` | Допоміжні засоби повторно вхідного file-lock |
|
||||
| `plugin-sdk/persistent-dedupe` | Допоміжні засоби кешу дедуплікації з backing на диску |
|
||||
| `plugin-sdk/acp-runtime` | Допоміжні засоби середовища виконання/сесії ACP і dispatch відповідей |
|
||||
| `plugin-sdk/acp-binding-resolve-runtime` | Розв’язання прив’язок ACP лише для читання без імпортів запуску життєвого циклу |
|
||||
| `plugin-sdk/agent-config-primitives` | Вузькі примітиви config-schema runtime агента |
|
||||
| `plugin-sdk/boolean-param` | Читач нестрогих boolean-параметрів |
|
||||
| `plugin-sdk/model-session-runtime` | Допоміжні засоби перевизначення model/session, такі як `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` |
|
||||
| `plugin-sdk/talk-config-runtime` | Допоміжні засоби визначення конфігурації talk provider |
|
||||
| `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису JSON state |
|
||||
| `plugin-sdk/file-lock` | Допоміжні засоби реентерабельного file-lock |
|
||||
| `plugin-sdk/persistent-dedupe` | Допоміжні засоби дедуплікаційного кешу зберігання на диску |
|
||||
| `plugin-sdk/acp-runtime` | Допоміжні засоби ACP runtime/session і диспетчеризації відповідей |
|
||||
| `plugin-sdk/acp-binding-resolve-runtime` | Розв’язання прив’язки ACP лише для читання без імпортів запуску життєвого циклу |
|
||||
| `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації agent runtime |
|
||||
| `plugin-sdk/boolean-param` | Нестрогий зчитувач булевих параметрів |
|
||||
| `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення збігів небезпечних назв |
|
||||
| `plugin-sdk/device-bootstrap` | Допоміжні засоби початкового налаштування пристрою та токенів pairing |
|
||||
| `plugin-sdk/device-bootstrap` | Допоміжні засоби початкового налаштування пристрою та pairing token |
|
||||
| `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів passive-channel, status і ambient proxy |
|
||||
| `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповіді команди `/models`/постачальника |
|
||||
| `plugin-sdk/skill-commands-runtime` | Допоміжні засоби списку команд Skills |
|
||||
| `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/побудови/серіалізації нативних команд |
|
||||
| `plugin-sdk/agent-harness` | Експериментальна trusted-plugin поверхня для низькорівневих harness агента: типи harness, допоміжні засоби steer/abort активного запуску, допоміжні засоби мосту tool OpenClaw, допоміжні засоби політики tool плану runtime, класифікація результатів terminal, допоміжні засоби форматування/деталізації прогресу tool і утиліти результатів спроб |
|
||||
| `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення кінцевих точок Z.A.I |
|
||||
| `plugin-sdk/async-lock-runtime` | Допоміжний засіб process-local async lock для невеликих файлів стану runtime |
|
||||
| `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповідей команди `/models`/провайдера |
|
||||
| `plugin-sdk/skill-commands-runtime` | Допоміжні засоби переліку команд Skills |
|
||||
| `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/build/serialize native-команд |
|
||||
| `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих harness agent: типи harness, допоміжні засоби steer/abort активного запуску, допоміжні засоби мосту OpenClaw tool, допоміжні засоби політики runtime-plan tool, класифікація результатів terminal, допоміжні засоби форматування/деталізації прогресу tool і утиліти результатів спроб |
|
||||
| `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.AI |
|
||||
| `plugin-sdk/async-lock-runtime` | Допоміжний засіб process-local async lock для невеликих runtime state-файлів |
|
||||
| `plugin-sdk/channel-activity-runtime` | Допоміжний засіб телеметрії активності каналу |
|
||||
| `plugin-sdk/concurrency-runtime` | Допоміжний засіб обмеженої конкурентності асинхронних завдань |
|
||||
| `plugin-sdk/concurrency-runtime` | Допоміжний засіб обмеженої конкурентності async-завдань |
|
||||
| `plugin-sdk/dedupe-runtime` | Допоміжні засоби кешу дедуплікації в пам’яті |
|
||||
| `plugin-sdk/delivery-queue-runtime` | Допоміжний засіб дренування черги очікуваної вихідної доставки |
|
||||
| `plugin-sdk/file-access-runtime` | Допоміжні засоби безпечних шляхів локальних файлів і джерел медіа |
|
||||
| `plugin-sdk/delivery-queue-runtime` | Допоміжний засіб очищення черги очікуваної вихідної доставки |
|
||||
| `plugin-sdk/file-access-runtime` | Допоміжні засоби безпечних шляхів до локальних файлів і джерел медіа |
|
||||
| `plugin-sdk/heartbeat-runtime` | Допоміжні засоби подій і видимості Heartbeat |
|
||||
| `plugin-sdk/number-runtime` | Допоміжний засіб приведення чисел |
|
||||
| `plugin-sdk/secure-random-runtime` | Допоміжні засоби безпечних токенів/UUID |
|
||||
| `plugin-sdk/system-event-runtime` | Допоміжні засоби черги системних подій |
|
||||
| `plugin-sdk/transport-ready-runtime` | Допоміжний засіб очікування готовності транспорту |
|
||||
| `plugin-sdk/infra-runtime` | Застарілий shim сумісності; використовуйте цільові підшляхи runtime вище |
|
||||
| `plugin-sdk/infra-runtime` | Застарілий shim сумісності; використовуйте сфокусовані runtime-підшляхи вище |
|
||||
| `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби обмеженого кешу |
|
||||
| `plugin-sdk/diagnostic-runtime` | Допоміжні засоби прапорців, подій і trace-context діагностики |
|
||||
| `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичних прапорців, подій і trace-context |
|
||||
| `plugin-sdk/error-runtime` | Допоміжні засоби графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch, proxy і pinned lookup |
|
||||
| `plugin-sdk/runtime-fetch` | Runtime fetch з урахуванням dispatcher без імпортів proxy/guarded-fetch |
|
||||
| `plugin-sdk/response-limit-runtime` | Читач обмеженого тіла відповіді без широкої поверхні media runtime |
|
||||
| `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки розмови без маршрутизації налаштованих прив’язок або сховищ pairing |
|
||||
| `plugin-sdk/session-store-runtime` | Допоміжні засоби сховища сесій без широких імпортів запису/обслуговування конфігурації |
|
||||
| `plugin-sdk/context-visibility-runtime` | Розв’язання видимості контексту та фільтрація додаткового контексту без широких імпортів config/security |
|
||||
| `plugin-sdk/response-limit-runtime` | Допоміжний засіб читання обмеженого response-body без широкої media runtime-поверхні |
|
||||
| `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки розмови без routing налаштованих прив’язок або pairing stores |
|
||||
| `plugin-sdk/session-store-runtime` | Допоміжні засоби session-store без широких імпортів запису/обслуговування конфігурації |
|
||||
| `plugin-sdk/context-visibility-runtime` | Визначення видимості контексту та фільтрація додаткового контексту без широких імпортів config/security |
|
||||
| `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні засоби приведення та нормалізації primitive record/string без імпортів markdown/logging |
|
||||
| `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і SCP host |
|
||||
| `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і виконавця retry |
|
||||
| `plugin-sdk/agent-runtime` | Допоміжні засоби каталогу/ідентичності/робочого простору агента |
|
||||
| `plugin-sdk/directory-runtime` | Запит/dedup каталогу з backing у конфігурації |
|
||||
| `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і запуску retry |
|
||||
| `plugin-sdk/agent-runtime` | Допоміжні засоби директорії/ідентичності/робочого простору agent |
|
||||
| `plugin-sdk/directory-runtime` | Запит/дедуплікація директорій на основі конфігурації |
|
||||
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи можливостей і тестування">
|
||||
| Підшлях | Основні експорти |
|
||||
| Subpath | Основні експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа, а також побудовники корисного навантаження медіа |
|
||||
| `plugin-sdk/media-runtime` | Спільні допоміжні засоби отримання/перетворення/збереження медіа, а також побудовники media payload |
|
||||
| `plugin-sdk/media-store` | Вузькі допоміжні засоби сховища медіа, такі як `saveMediaBuffer` |
|
||||
| `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover для генерації медіа, вибір кандидатів і повідомлення про відсутню модель |
|
||||
| `plugin-sdk/media-understanding` | Типи постачальників розуміння медіа, а також експорти допоміжних засобів для зображень/аудіо, орієнтовані на постачальників |
|
||||
| `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/Markdown/logging, такі як вилучення тексту, видимого асистенту, допоміжні засоби рендерингу/chunking/таблиць Markdown, допоміжні засоби редагування, допоміжні засоби тегів директив і утиліти безпечного тексту |
|
||||
| `plugin-sdk/media-understanding` | Типи провайдерів розуміння медіа, а також експорти image/audio helper для провайдерів |
|
||||
| `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/markdown/logging, такі як видалення assistant-visible-text, допоміжні засоби render/chunking/table для markdown, допоміжні засоби редагування, допоміжні засоби тегів директив і утиліти safe-text |
|
||||
| `plugin-sdk/text-chunking` | Допоміжний засіб chunking вихідного тексту |
|
||||
| `plugin-sdk/speech` | Типи постачальників speech, а також експорти директив, реєстру, валідації та допоміжних засобів speech, орієнтовані на постачальників |
|
||||
| `plugin-sdk/speech-core` | Спільні типи постачальників speech, а також експорти реєстру, директив, нормалізації та допоміжних засобів speech |
|
||||
| `plugin-sdk/realtime-transcription` | Типи постачальників транскрипції в реальному часі, допоміжні засоби реєстру та спільний допоміжний засіб сесії WebSocket |
|
||||
| `plugin-sdk/realtime-voice` | Типи постачальників голосу в реальному часі та допоміжні засоби реєстру |
|
||||
| `plugin-sdk/image-generation` | Типи постачальників генерації зображень |
|
||||
| `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, допоміжні засоби failover, auth і реєстру |
|
||||
| `plugin-sdk/music-generation` | Типи постачальників/запитів/результатів генерації музики |
|
||||
| `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, пошук постачальника та парсинг model-ref |
|
||||
| `plugin-sdk/video-generation` | Типи постачальників/запитів/результатів генерації відео |
|
||||
| `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, пошук постачальника та парсинг model-ref |
|
||||
| `plugin-sdk/speech` | Типи speech provider, а також експорти directive, registry, validation і speech helper для провайдерів |
|
||||
| `plugin-sdk/speech-core` | Спільні типи speech provider, registry, directive, normalization і експорти speech helper |
|
||||
| `plugin-sdk/realtime-transcription` | Типи провайдерів транскрипції в реальному часі, допоміжні засоби registry і спільний допоміжний засіб WebSocket session |
|
||||
| `plugin-sdk/realtime-voice` | Типи провайдерів голосу в реальному часі та допоміжні засоби registry |
|
||||
| `plugin-sdk/image-generation` | Типи провайдерів генерації зображень |
|
||||
| `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, допоміжні засоби failover, auth і registry |
|
||||
| `plugin-sdk/music-generation` | Типи провайдерів/запитів/результатів генерації музики |
|
||||
| `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, пошук провайдерів і розбір model-ref |
|
||||
| `plugin-sdk/video-generation` | Типи провайдерів/запитів/результатів генерації відео |
|
||||
| `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, пошук провайдерів і розбір model-ref |
|
||||
| `plugin-sdk/webhook-targets` | Допоміжні засоби реєстру цілей Webhook і встановлення маршрутів |
|
||||
| `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляху Webhook |
|
||||
| `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа |
|
||||
| `plugin-sdk/zod` | Повторно експортований `zod` для споживачів plugin SDK |
|
||||
| `plugin-sdk/testing` | Публічні допоміжні засоби тестування extension, включно з моками реєстру/runtime plugin, допоміжними засобами schema/media/live-test, `installCommonResolveTargetErrorCases`, `writeSkill`, `createTestRegistry` і завантаженням env для live generation. Допоміжні засоби extension `*.test-support.ts` мають залишатися тут або на цільових підшляхах SDK, а не у внутрішніх компонентах core |
|
||||
| `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK |
|
||||
| `plugin-sdk/testing` | Публічні допоміжні засоби тестування extensions, включно з mock-об’єктами registry/runtime plugin, fetch/env/temp fixtures, допоміжними засобами schema/media/live-test, `installCommonResolveTargetErrorCases`, `writeSkill`, `createTestRegistry` і завантаженням env для live generation. Допоміжні засоби Extension `*.test-support.ts` мають залишатися тут або у сфокусованих підшляхах SDK, а не у внутрішніх компонентах core |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи пам’яті">
|
||||
| Підшлях | Основні експорти |
|
||||
| Subpath | Основні експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для менеджера/конфігурації/файлів/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Фасад runtime індексації/пошуку пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста пам’яті, доступ до реєстру, локальний постачальник і універсальні допоміжні засоби batch/remote |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби runtime CLI хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Основні допоміжні засоби runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-core` | Нейтральний до постачальника псевдонім для основних допоміжних засобів runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-events` | Нейтральний до постачальника псевдонім для допоміжних засобів журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-files` | Нейтральний до постачальника псевдонім для допоміжних засобів файлів/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби керованого Markdown для plugin, суміжних із пам’яттю |
|
||||
| `plugin-sdk/memory-host-search` | Фасад runtime Active Memory для доступу до менеджера пошуку |
|
||||
| `plugin-sdk/memory-host-status` | Нейтральний до постачальника псевдонім для допоміжних засобів статусу хоста пам’яті |
|
||||
| `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для manager/config/file/CLI helper |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Runtime-фасад індексу/пошуку пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine host-а пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding host-а пам’яті, доступ до registry, локальний провайдер і загальні пакетні/віддалені helper |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine host-а пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Експорти engine сховища host-а пам’яті |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Мультимодальні helper host-а пам’яті |
|
||||
| `plugin-sdk/memory-core-host-query` | Helper запитів host-а пам’яті |
|
||||
| `plugin-sdk/memory-core-host-secret` | Helper секретів host-а пам’яті |
|
||||
| `plugin-sdk/memory-core-host-events` | Helper журналу подій host-а пам’яті |
|
||||
| `plugin-sdk/memory-core-host-status` | Helper статусу host-а пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Runtime helper CLI host-а пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Core runtime helper host-а пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | File/runtime helper host-а пам’яті |
|
||||
| `plugin-sdk/memory-host-core` | Нейтральний до вендора псевдонім для core runtime helper host-а пам’яті |
|
||||
| `plugin-sdk/memory-host-events` | Нейтральний до вендора псевдонім для helper журналу подій host-а пам’яті |
|
||||
| `plugin-sdk/memory-host-files` | Нейтральний до вендора псевдонім для file/runtime helper host-а пам’яті |
|
||||
| `plugin-sdk/memory-host-markdown` | Спільні helper керованого markdown для plugin, суміжних із пам’яттю |
|
||||
| `plugin-sdk/memory-host-search` | Runtime-фасад Active Memory для доступу до менеджера пошуку |
|
||||
| `plugin-sdk/memory-host-status` | Нейтральний до вендора псевдонім для helper статусу host-а пам’яті |
|
||||
| `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів bundled memory-lancedb |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Зарезервовані підшляхи bundled-helper">
|
||||
| Сімейство | Поточні підшляхи | Призначення |
|
||||
| Family | Поточні підшляхи | Призначення |
|
||||
| --- | --- | --- |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки bundled browser plugin. `browser-profiles` експортує `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile` і `ResolvedBrowserTabCleanupConfig` для нормалізованої форми `browser.tabCleanup`. `browser-support` залишається barrel сумісності. |
|
||||
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня допоміжних засобів/runtime bundled Matrix |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних засобів/runtime bundled LINE |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних засобів bundled IRC |
|
||||
| Допоміжні засоби, специфічні для каналів | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | Застарілі шви сумісності/допоміжних засобів bundled channel. Нові plugins мають імпортувати універсальні підшляхи SDK або локальні barrel-файли plugin. |
|
||||
| Допоміжні засоби, специфічні для auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви допоміжних засобів bundled feature/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки bundled browser plugin. `browser-profiles` експортує `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile` і `ResolvedBrowserTabCleanupConfig` для нормалізованої форми `browser.tabCleanup`. `browser-support` залишається compatibility barrel. |
|
||||
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня helper/runtime bundled Matrix |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня helper/runtime bundled LINE |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня helper bundled IRC |
|
||||
| Специфічні для каналів helper | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | Застарілі шви сумісності/helper для bundled channel. Нові plugins повинні імпортувати загальні підшляхи SDK або plugin-local barrel. |
|
||||
| Helper автентифікації/специфічні для plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви helper для bundled feature/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Пов’язані матеріали
|
||||
## Пов’язане
|
||||
|
||||
- [Огляд Plugin SDK](/uk/plugins/sdk-overview)
|
||||
- [Налаштування Plugin SDK](/uk/plugins/sdk-setup)
|
||||
|
||||
@ -2,25 +2,25 @@
|
||||
read_when:
|
||||
- Ви пишете тести для Plugin
|
||||
- Вам потрібні утиліти тестування з SDK Plugin
|
||||
- Ви хочете зрозуміти контрактні тести для bundled Plugin
|
||||
- Ви хочете зрозуміти контрактні тести для вбудованих Plugin
|
||||
sidebarTitle: Testing
|
||||
summary: Утиліти тестування та шаблони для Plugin OpenClaw
|
||||
summary: Утиліти та шаблони тестування для Plugin OpenClaw
|
||||
title: Тестування Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T12:53:51Z"
|
||||
generated_at: "2026-04-27T22:22:43Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3030e2a838b641433da2882270ef2b332284a7fc2f16037681b51536de42998e
|
||||
source_hash: 358a1e76d6a8e78ad503b040d49bab7f66fa8bfb2f1fe7dcb6088ef932e56860
|
||||
source_path: plugins/sdk-testing.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Довідник з утиліт тестування, шаблонів і lint-контролю для Plugin OpenClaw.
|
||||
Довідник з утиліт тестування, шаблонів і забезпечення правил lint для Plugin OpenClaw.
|
||||
|
||||
<Tip>
|
||||
**Шукаєте приклади тестів?** У how-to посібниках є готові приклади тестів:
|
||||
[Тести Plugin каналів](/uk/plugins/sdk-channel-plugins#step-6-test) і
|
||||
[Тести Plugin провайдерів](/uk/plugins/sdk-provider-plugins#step-6-test).
|
||||
**Шукаєте приклади тестів?** Практичні посібники містять готові приклади тестів:
|
||||
[Тести Channel Plugin](/uk/plugins/sdk-channel-plugins#step-6-test) і
|
||||
[Тести Provider Plugin](/uk/plugins/sdk-provider-plugins#step-6-test).
|
||||
</Tip>
|
||||
|
||||
## Утиліти тестування
|
||||
@ -39,11 +39,22 @@ import {
|
||||
|
||||
### Доступні експорти
|
||||
|
||||
| Експорт | Призначення |
|
||||
| -------------------------------------- | ----------------------------------------------------- |
|
||||
| `installCommonResolveTargetErrorCases` | Спільні тестові випадки для обробки помилок визначення цілі |
|
||||
| `shouldAckReaction` | Перевірити, чи має канал додавати ack reaction |
|
||||
| `removeAckReactionAfterReply` | Видалити ack reaction після доставки відповіді |
|
||||
| Export | Purpose |
|
||||
| -------------------------------------- | ------------------------------------------------- |
|
||||
| `installCommonResolveTargetErrorCases` | Спільні тестові випадки для обробки помилок під час визначення цілі |
|
||||
| `shouldAckReaction` | Перевіряє, чи повинен канал додавати реакцію-підтвердження |
|
||||
| `removeAckReactionAfterReply` | Видаляє реакцію-підтвердження після доставки відповіді |
|
||||
| `createTestRegistry` | Створює фікстуру реєстру Channel Plugin |
|
||||
| `createEmptyPluginRegistry` | Створює порожню фікстуру реєстру Plugin |
|
||||
| `setActivePluginRegistry` | Встановлює фікстуру реєстру для runtime-тестів Plugin |
|
||||
| `createRequestCaptureJsonFetch` | Перехоплює JSON fetch-запити в тестах медіадопоміжників |
|
||||
| `withFetchPreconnect` | Запускає fetch-тести зі встановленими хуками preconnect |
|
||||
| `withEnv` / `withEnvAsync` | Тимчасово підміняє змінні середовища |
|
||||
| `createTempHomeEnv` / `withTempDir` | Створює ізольовані файлові фікстури для тестів |
|
||||
| `createMockServerResponse` | Створює мінімальний mock-відповідь HTTP-сервера |
|
||||
| `registerSingleProviderPlugin` | Реєструє один Provider Plugin у smoke-тестах завантажувача |
|
||||
| `createRuntimeTaskFlow` | Створює ізольований стан runtime TaskFlow |
|
||||
| `typedCases` | Зберігає literal-типи для табличних тестів |
|
||||
|
||||
### Типи
|
||||
|
||||
@ -62,24 +73,23 @@ import type {
|
||||
|
||||
## Тестування визначення цілі
|
||||
|
||||
Використовуйте `installCommonResolveTargetErrorCases`, щоб додати стандартні випадки помилок для
|
||||
визначення цілей каналу:
|
||||
Використовуйте `installCommonResolveTargetErrorCases`, щоб додати стандартні випадки помилок для визначення цілі каналу:
|
||||
|
||||
```typescript
|
||||
import { describe } from "vitest";
|
||||
import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/testing";
|
||||
|
||||
describe("визначення цілі my-channel", () => {
|
||||
describe("my-channel target resolution", () => {
|
||||
installCommonResolveTargetErrorCases({
|
||||
resolveTarget: ({ to, mode, allowFrom }) => {
|
||||
// Логіка визначення цілі вашого каналу
|
||||
// Your channel's target resolution logic
|
||||
return myChannelResolveTarget({ to, mode, allowFrom });
|
||||
},
|
||||
implicitAllowFrom: ["user1", "user2"],
|
||||
});
|
||||
|
||||
// Додайте тестові випадки, специфічні для каналу
|
||||
it("має визначати цілі @username", () => {
|
||||
// Add channel-specific test cases
|
||||
it("should resolve @username targets", () => {
|
||||
// ...
|
||||
});
|
||||
});
|
||||
@ -89,31 +99,21 @@ describe("визначення цілі my-channel", () => {
|
||||
|
||||
### Тестування контрактів реєстрації
|
||||
|
||||
Юніт-тести, які передають написаний вручну mock `api` у `register(api)`, не перевіряють
|
||||
шлюзи прийняття завантажувача OpenClaw. Додайте принаймні один smoke-тест на основі loader
|
||||
для кожної поверхні реєстрації, від якої залежить ваш Plugin, особливо для hooks і
|
||||
ексклюзивних можливостей, таких як memory.
|
||||
Юніт-тести, які передають вручну написаний mock `api` до `register(api)`, не перевіряють acceptance gate завантажувача OpenClaw. Додайте щонайменше один smoke-тест на основі завантажувача для кожної поверхні реєстрації, від якої залежить ваш Plugin, особливо для hook і ексклюзивних можливостей, таких як memory.
|
||||
|
||||
Справжній loader відхиляє реєстрацію Plugin, коли відсутні потрібні метадані або
|
||||
Plugin викликає API можливості, якою не володіє. Наприклад,
|
||||
`api.registerHook(...)` вимагає ім’я hook, а
|
||||
`api.registerMemoryCapability(...)` вимагає, щоб manifest Plugin або експортований
|
||||
entry оголошував `kind: "memory"`.
|
||||
Справжній завантажувач відхиляє реєстрацію Plugin, якщо бракує обов’язкових метаданих або якщо Plugin викликає API можливості, якою він не володіє. Наприклад, `api.registerHook(...)` вимагає назву hook, а `api.registerMemoryCapability(...)` вимагає, щоб маніфест Plugin або експортована точка входу оголошували `kind: "memory"`.
|
||||
|
||||
### Тестування доступу до конфігурації runtime
|
||||
### Тестування доступу до runtime-конфігурації
|
||||
|
||||
Під час тестування bundled Plugin надавайте перевагу спільному mock runtime Plugin із допоміжних засобів тестування репозиторію. Його застарілі mock `runtime.config.loadConfig()` і
|
||||
`runtime.config.writeConfigFile(...)` за замовчуванням викидають помилку, щоб тести виявляли нове
|
||||
використання API сумісності. Перевизначайте ці mocks лише тоді, коли тест
|
||||
явно покриває застарілу поведінку сумісності.
|
||||
Під час тестування вбудованих Plugin віддавайте перевагу спільному mock runtime Plugin із допоміжних засобів тестування репозиторію. Його застарілі mock `runtime.config.loadConfig()` і `runtime.config.writeConfigFile(...)` за замовчуванням викидають помилку, щоб тести виявляли нове використання API сумісності. Перевизначайте ці mock лише тоді, коли тест явно перевіряє застарілу поведінку сумісності.
|
||||
|
||||
### Юніт-тестування Plugin каналу
|
||||
### Юніт-тестування Channel Plugin
|
||||
|
||||
```typescript
|
||||
import { describe, it, expect, vi } from "vitest";
|
||||
|
||||
describe("plugin my-channel", () => {
|
||||
it("має визначати обліковий запис із конфігурації", () => {
|
||||
describe("my-channel plugin", () => {
|
||||
it("should resolve account from config", () => {
|
||||
const cfg = {
|
||||
channels: {
|
||||
"my-channel": {
|
||||
@ -127,7 +127,7 @@ describe("plugin my-channel", () => {
|
||||
expect(account.token).toBe("test-token");
|
||||
});
|
||||
|
||||
it("має перевіряти обліковий запис без materializing секретів", () => {
|
||||
it("should inspect account without materializing secrets", () => {
|
||||
const cfg = {
|
||||
channels: {
|
||||
"my-channel": { token: "test-token" },
|
||||
@ -137,22 +137,22 @@ describe("plugin my-channel", () => {
|
||||
const inspection = myPlugin.setup.inspectAccount(cfg, undefined);
|
||||
expect(inspection.configured).toBe(true);
|
||||
expect(inspection.tokenStatus).toBe("available");
|
||||
// Значення токена не розкривається
|
||||
// No token value exposed
|
||||
expect(inspection).not.toHaveProperty("token");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Юніт-тестування Plugin провайдера
|
||||
### Юніт-тестування Provider Plugin
|
||||
|
||||
```typescript
|
||||
import { describe, it, expect } from "vitest";
|
||||
|
||||
describe("plugin my-provider", () => {
|
||||
it("має визначати динамічні моделі", () => {
|
||||
describe("my-provider plugin", () => {
|
||||
it("should resolve dynamic models", () => {
|
||||
const model = myProvider.resolveDynamicModel({
|
||||
modelId: "custom-model-v2",
|
||||
// ... контекст
|
||||
// ... context
|
||||
});
|
||||
|
||||
expect(model.id).toBe("custom-model-v2");
|
||||
@ -160,10 +160,10 @@ describe("plugin my-provider", () => {
|
||||
expect(model.api).toBe("openai-completions");
|
||||
});
|
||||
|
||||
it("має повертати каталог, коли доступний API key", async () => {
|
||||
it("should return catalog when API key is available", async () => {
|
||||
const result = await myProvider.catalog.run({
|
||||
resolveProviderApiKey: () => ({ apiKey: "test-key" }),
|
||||
// ... контекст
|
||||
// ... context
|
||||
});
|
||||
|
||||
expect(result?.provider?.models).toHaveLength(2);
|
||||
@ -171,9 +171,9 @@ describe("plugin my-provider", () => {
|
||||
});
|
||||
```
|
||||
|
||||
### Mock runtime Plugin
|
||||
### Мокування runtime Plugin
|
||||
|
||||
Для коду, який використовує `createPluginRuntimeStore`, mock runtime у тестах має виглядати так:
|
||||
Для коду, який використовує `createPluginRuntimeStore`, мокайте runtime у тестах:
|
||||
|
||||
```typescript
|
||||
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
@ -184,42 +184,42 @@ const store = createPluginRuntimeStore<PluginRuntime>({
|
||||
errorMessage: "test runtime not set",
|
||||
});
|
||||
|
||||
// У налаштуванні тесту
|
||||
// In test setup
|
||||
const mockRuntime = {
|
||||
agent: {
|
||||
resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"),
|
||||
// ... інші mocks
|
||||
// ... other mocks
|
||||
},
|
||||
config: {
|
||||
current: vi.fn(() => ({}) as const),
|
||||
mutateConfigFile: vi.fn(),
|
||||
replaceConfigFile: vi.fn(),
|
||||
},
|
||||
// ... інші простори імен
|
||||
// ... other namespaces
|
||||
} as unknown as PluginRuntime;
|
||||
|
||||
store.setRuntime(mockRuntime);
|
||||
|
||||
// Після тестів
|
||||
// After tests
|
||||
store.clearRuntime();
|
||||
```
|
||||
|
||||
### Тестування зі stub для окремих екземплярів
|
||||
### Тестування зі стабами на рівні екземпляра
|
||||
|
||||
Надавайте перевагу stub для окремих екземплярів замість мутації prototype:
|
||||
Віддавайте перевагу стабам на рівні екземпляра замість мутації прототипу:
|
||||
|
||||
```typescript
|
||||
// Бажано: stub для окремого екземпляра
|
||||
// Preferred: per-instance stub
|
||||
const client = new MyChannelClient();
|
||||
client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" });
|
||||
|
||||
// Уникайте: мутація prototype
|
||||
// Avoid: prototype mutation
|
||||
// MyChannelClient.prototype.sendMessage = vi.fn();
|
||||
```
|
||||
|
||||
## Контрактні тести (Plugin у репозиторії)
|
||||
|
||||
Bundled Plugin мають контрактні тести, які перевіряють право власності на реєстрацію:
|
||||
Вбудовані Plugin мають контрактні тести, які перевіряють володіння реєстрацією:
|
||||
|
||||
```bash
|
||||
pnpm test -- src/plugins/contracts/
|
||||
@ -228,11 +228,11 @@ pnpm test -- src/plugins/contracts/
|
||||
Ці тести перевіряють:
|
||||
|
||||
- Які Plugin реєструють які провайдери
|
||||
- Які Plugin реєструють які speech providers
|
||||
- Які Plugin реєструють які мовленнєві провайдери
|
||||
- Коректність форми реєстрації
|
||||
- Відповідність runtime-контракту
|
||||
|
||||
### Запуск тестів з обмеженням області
|
||||
### Запуск тестів з обмеженою областю
|
||||
|
||||
Для конкретного Plugin:
|
||||
|
||||
@ -240,7 +240,7 @@ pnpm test -- src/plugins/contracts/
|
||||
pnpm test -- <bundled-plugin-root>/my-channel/
|
||||
```
|
||||
|
||||
Лише контрактні тести:
|
||||
Лише для контрактних тестів:
|
||||
|
||||
```bash
|
||||
pnpm test -- src/plugins/contracts/shape.contract.test.ts
|
||||
@ -248,32 +248,31 @@ pnpm test -- src/plugins/contracts/auth.contract.test.ts
|
||||
pnpm test -- src/plugins/contracts/runtime.contract.test.ts
|
||||
```
|
||||
|
||||
## Lint-контроль (Plugin у репозиторії)
|
||||
## Забезпечення правил lint (Plugin у репозиторії)
|
||||
|
||||
`pnpm check` застосовує три правила для Plugin у репозиторії:
|
||||
|
||||
1. **Без монолітних імпортів з кореня** -- кореневий barrel `openclaw/plugin-sdk` відхиляється
|
||||
1. **Без монолітних імпортів із кореня** -- кореневий barrel `openclaw/plugin-sdk` відхиляється
|
||||
2. **Без прямих імпортів `src/`** -- Plugin не можуть напряму імпортувати `../../src/`
|
||||
3. **Без self-imports** -- Plugin не можуть імпортувати власний підшлях `plugin-sdk/<name>`
|
||||
3. **Без самоімпортів** -- Plugin не можуть імпортувати власний підшлях `plugin-sdk/<name>`
|
||||
|
||||
Зовнішні Plugin не підпадають під ці lint-правила, але дотримуватися тих самих
|
||||
шаблонів рекомендується.
|
||||
На зовнішні Plugin ці правила lint не поширюються, але дотримуватися тих самих шаблонів рекомендовано.
|
||||
|
||||
## Конфігурація тестування
|
||||
|
||||
OpenClaw використовує Vitest із порогами покриття V8. Для тестів Plugin:
|
||||
|
||||
```bash
|
||||
# Запустити всі тести
|
||||
# Run all tests
|
||||
pnpm test
|
||||
|
||||
# Запустити тести конкретного Plugin
|
||||
# Run specific plugin tests
|
||||
pnpm test -- <bundled-plugin-root>/my-channel/src/channel.test.ts
|
||||
|
||||
# Запустити з фільтром за конкретною назвою тесту
|
||||
# Run with a specific test name filter
|
||||
pnpm test -- <bundled-plugin-root>/my-channel/ -t "resolves account"
|
||||
|
||||
# Запустити з coverage
|
||||
# Run with coverage
|
||||
pnpm test:coverage
|
||||
```
|
||||
|
||||
@ -283,9 +282,9 @@ pnpm test:coverage
|
||||
OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test
|
||||
```
|
||||
|
||||
## Пов’язані теми
|
||||
## Пов’язане
|
||||
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview) -- правила імпорту
|
||||
- [SDK Plugin каналів](/uk/plugins/sdk-channel-plugins) -- інтерфейс Plugin каналу
|
||||
- [SDK Plugin провайдерів](/uk/plugins/sdk-provider-plugins) -- hooks Plugin провайдера
|
||||
- [SDK Channel Plugins](/uk/plugins/sdk-channel-plugins) -- інтерфейс Channel Plugin
|
||||
- [SDK Provider Plugins](/uk/plugins/sdk-provider-plugins) -- hook Provider Plugin
|
||||
- [Створення Plugin](/uk/plugins/building-plugins) -- посібник для початку роботи
|
||||
|
||||
Loading…
Reference in New Issue
Block a user