diff --git a/docs/uk/gateway/cli-backends.md b/docs/uk/gateway/cli-backends.md index c826ef0be..ae6bb1dec 100644 --- a/docs/uk/gateway/cli-backends.md +++ b/docs/uk/gateway/cli-backends.md @@ -1,38 +1,38 @@ --- read_when: - - Вам потрібен надійний резервний варіант, коли постачальники API дають збій - - Ви запускаєте Codex CLI або інші локальні CLI зі ШІ та хочете повторно використовувати їх - - Ви хочете зрозуміти loopback-міст MCP для доступу до інструментів бекенду CLI -summary: 'Бекенди CLI: локальний резервний варіант CLI для ШІ з необов’язковим мостом інструментів MCP' + - Вам потрібен надійний резервний варіант на випадок збоїв у постачальників API + - Ви запускаєте Codex CLI або інші локальні CLI для ШІ й хочете повторно їх використовувати + - Ви хочете зрозуміти петльовий міст MCP для доступу CLI до інструментів бекенду +summary: 'Бекенди CLI: локальний резервний CLI для ШІ з необов’язковим мостом інструментів MCP' title: Бекенди CLI x-i18n: - generated_at: "2026-05-02T08:25:28Z" + generated_at: "2026-05-04T18:18:44Z" model: gpt-5.5 provider: openai - source_hash: f343469d6a42dc6146196355dc2ba3feed045515c3d8446941b90971aadc9a16 + source_hash: 55534c48c5e226857b9320fd369416583e5c2efc80eabd4746f939afdd027dc1 source_path: gateway/cli-backends.md workflow: 16 --- OpenClaw може запускати **локальні AI CLI** як **текстовий резервний варіант**, коли API-провайдери недоступні, -обмежені за лімітом запитів або тимчасово працюють некоректно. Це навмисно консервативний підхід: +мають обмеження швидкості або тимчасово працюють некоректно. Це навмисно консервативний підхід: -- **Інструменти OpenClaw не ін’єктуються напряму**, але бекенди з `bundleMcp: true` +- **Інструменти OpenClaw не впроваджуються напряму**, але бекенди з `bundleMcp: true` можуть отримувати інструменти gateway через loopback MCP-міст. -- **JSONL-стримінг** для CLI, які його підтримують. -- **Сесії підтримуються** (тому подальші ходи залишаються узгодженими). +- **JSONL-потокове передавання** для CLI, які це підтримують. +- **Сесії підтримуються** (тому наступні звернення залишаються узгодженими). - **Зображення можна передавати наскрізно**, якщо CLI приймає шляхи до зображень. -Це розроблено як **запобіжний механізм**, а не як основний шлях. Використовуйте його, коли вам -потрібні текстові відповіді, що «завжди працюють», без залежності від зовнішніх API. +Це задумано як **страхувальна сітка**, а не основний шлях. Використовуйте це, коли вам +потрібні текстові відповіді, які «завжди працюють», без залежності від зовнішніх API. -Якщо вам потрібне повноцінне середовище виконання harness із керуванням сесіями ACP, фоновими завданнями, -прив’язкою потоків/розмов і постійними зовнішніми сесіями кодування, натомість використовуйте +Якщо вам потрібне повноцінне середовище виконання harness з керуванням сесіями ACP, фоновими завданнями, +прив’язуванням потоків/розмов і сталими зовнішніми coding-сесіями, використовуйте [ACP Agents](/uk/tools/acp-agents). CLI-бекенди не є ACP. -## Простий швидкий старт для початківців +## Швидкий старт для початківців -Ви можете використовувати Codex CLI **без жодної конфігурації** (вбудований OpenAI Plugin +Ви можете використовувати Codex CLI **без будь-якої конфігурації** (вбудований OpenAI plugin реєструє стандартний бекенд): ```bash @@ -56,16 +56,16 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5 } ``` -Це все. Жодних ключів, жодної додаткової конфігурації автентифікації, окрім самого CLI, не потрібно. +Ось і все. Не потрібні ключі чи додаткова конфігурація автентифікації, окрім самої CLI. Якщо ви використовуєте вбудований CLI-бекенд як **основного провайдера повідомлень** на -gateway-хості, OpenClaw тепер автоматично завантажує вбудований Plugin-власник, коли ваша конфігурація -явно посилається на цей бекенд у посиланні на модель або в +gateway-хості, OpenClaw тепер автоматично завантажує власницький вбудований plugin, коли ваша конфігурація +явно посилається на цей бекенд у model ref або в `agents.defaults.cliBackends`. ## Використання як резервного варіанта -Додайте CLI-бекенд до списку резервних варіантів, щоб він запускався лише тоді, коли основні моделі не спрацюють: +Додайте CLI-бекенд до свого списку резервних варіантів, щоб він запускався лише тоді, коли основні моделі не спрацьовують: ```json5 { @@ -86,20 +86,20 @@ gateway-хості, OpenClaw тепер автоматично завантаж Примітки: -- Якщо ви використовуєте `agents.defaults.models` (allowlist), ви також маєте включити туди моделі свого CLI-бекенда. -- Якщо основний провайдер не спрацює (автентифікація, ліміти запитів, тайм-аути), OpenClaw - спробує CLI-бекенд наступним. +- Якщо ви використовуєте `agents.defaults.models` (список дозволених), ви також маєте включити туди моделі свого CLI-бекенда. +- Якщо основний провайдер зазнає збою (автентифікація, обмеження швидкості, тайм-аути), OpenClaw + далі спробує CLI-бекенд. ## Огляд конфігурації -Усі CLI-бекенди розташовані в: +Усі CLI-бекенди розміщуються в: ``` agents.defaults.cliBackends ``` -Кожен запис має ключ у вигляді **ідентифікатора провайдера** (наприклад, `codex-cli`, `my-cli`). -Ідентифікатор провайдера стає лівою частиною вашого посилання на модель: +Кожен запис має ключ **ідентифікатора провайдера** (наприклад, `codex-cli`, `my-cli`). +Ідентифікатор провайдера стає лівою частиною вашого model ref: ``` / @@ -148,45 +148,51 @@ agents.defaults.cliBackends ## Як це працює 1. **Вибирає бекенд** на основі префікса провайдера (`codex-cli/...`). -2. **Створює системний промпт** з використанням того самого промпта OpenClaw і контексту workspace. +2. **Створює системний prompt** з використанням того самого prompt OpenClaw і контексту робочої області. 3. **Виконує CLI** з ідентифікатором сесії (якщо підтримується), щоб історія залишалася узгодженою. - Вбудований бекенд `claude-cli` підтримує процес Claude stdio активним для кожної - сесії OpenClaw і надсилає подальші ходи через stream-json stdin. + Вбудований бекенд `claude-cli` підтримує процес Claude stdio живим для кожної + сесії OpenClaw і надсилає наступні звернення через stream-json stdin. 4. **Розбирає вивід** (JSON або звичайний текст) і повертає фінальний текст. -5. **Зберігає ідентифікатори сесій** для кожного бекенда, щоб подальші ходи повторно використовували ту саму CLI-сесію. +5. **Зберігає ідентифікатори сесій** для кожного бекенда, щоб наступні звернення повторно використовували ту саму CLI-сесію. -Вбудований бекенд Anthropic `claude-cli` знову підтримується. Співробітники Anthropic +Вбудований Anthropic-бекенд `claude-cli` знову підтримується. Співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає використання `claude -p` санкціонованим для цієї інтеграції, якщо Anthropic не опублікує нову політику. -Вбудований бекенд OpenAI `codex-cli` передає системний промпт OpenClaw через +Вбудований OpenAI-бекенд `codex-cli` передає системний prompt OpenClaw через перевизначення конфігурації Codex `model_instructions_file` (`-c -model_instructions_file="..."`). Codex не надає прапор у стилі Claude -`--append-system-prompt`, тому OpenClaw записує зібраний промпт у +model_instructions_file="..."`). Codex не надає Claude-подібний +прапорець `--append-system-prompt`, тому OpenClaw записує зібраний prompt у тимчасовий файл для кожної нової сесії Codex CLI. -Вбудований бекенд Anthropic `claude-cli` отримує знімок Skills OpenClaw -двома способами: компактний каталог Skills OpenClaw у доданому системному промпті та -тимчасовий Claude Code Plugin, переданий із `--plugin-dir`. Plugin містить -лише придатні Skills для цього агента/сесії, тому нативний резолвер Skills Claude Code +Вбудований Anthropic-бекенд `claude-cli` отримує знімок Skills OpenClaw +двома способами: компактний каталог Skills OpenClaw у доданому системному prompt і +тимчасовий Claude Code plugin, переданий через `--plugin-dir`. Plugin містить +лише придатні Skills для цього агента/сесії, тому нативний розпізнавач Skills Claude Code бачить той самий відфільтрований набір, який OpenClaw інакше оголосив би в -промпті. Перевизначення env/API-ключів Skills OpenClaw все одно застосовує до +prompt. Перевизначення env/API-ключів Skills усе ще застосовуються OpenClaw до середовища дочірнього процесу для запуску. Claude CLI також має власний неінтерактивний режим дозволів. OpenClaw відображає його -на наявну політику виконання замість додавання специфічної для Claude конфігурації: коли -ефективна запитана політика виконання є YOLO (`tools.exec.security: "full"` і +на наявну політику exec замість додавання конфігурації, специфічної для Claude: коли +ефективна запитана політика exec є YOLO (`tools.exec.security: "full"` і `tools.exec.ask: "off"`), OpenClaw додає `--permission-mode bypassPermissions`. Налаштування `agents.list[].tools.exec` для окремого агента перевизначають глобальні `tools.exec` для цього агента. Щоб примусово задати інший режим Claude, встановіть явні сирі аргументи бекенда, -наприклад `--permission-mode default` або `--permission-mode acceptEdits` у -`agents.defaults.cliBackends.claude-cli.args` і відповідних `resumeArgs`. +такі як `--permission-mode default` або `--permission-mode acceptEdits`, у +`agents.defaults.cliBackends.claude-cli.args` і відповідні `resumeArgs`. + +Вбудований Anthropic-бекенд `claude-cli` також відображає рівні OpenClaw `/think` +на нативний прапорець Claude Code `--effort` для рівнів, відмінних від off. `minimal` і +`low` відображаються на `low`, `adaptive` і `medium` відображаються на `medium`, а `high`, +`xhigh` і `max` відображаються напряму. Іншим CLI-бекендам потрібен їхній власницький plugin, щоб +оголосити еквівалентний argv-мапер, перш ніж `/think` зможе впливати на породжений CLI. Перш ніж OpenClaw зможе використовувати вбудований бекенд `claude-cli`, сам Claude Code -уже має бути авторизований на тому самому хості: +має вже бути автентифікований на тому самому хості: ```bash claude auth login @@ -201,93 +207,94 @@ openclaw models auth login --provider anthropic --method cli --set-default - Якщо CLI підтримує сесії, задайте `sessionArg` (наприклад, `--session-id`) або `sessionArgs` (placeholder `{sessionId}`), коли ідентифікатор потрібно вставити - в кілька прапорів. -- Якщо CLI використовує **підкоманду відновлення** з іншими прапорами, задайте - `resumeArgs` (замінює `args` під час відновлення) і за потреби `resumeOutput` - (для відновлень не у форматі JSON). + в кілька прапорців. +- Якщо CLI використовує **підкоманду resume** з іншими прапорцями, задайте + `resumeArgs` (замінює `args` під час відновлення) і, за потреби, `resumeOutput` + (для не-JSON відновлень). - `sessionMode`: - - `always`: завжди надсилати ідентифікатор сесії (новий UUID, якщо збереженого немає). + - `always`: завжди надсилати ідентифікатор сесії (новий UUID, якщо нічого не збережено). - `existing`: надсилати ідентифікатор сесії лише якщо його було збережено раніше. - `none`: ніколи не надсилати ідентифікатор сесії. - `claude-cli` за замовчуванням використовує `liveSession: "claude-stdio"`, `output: "jsonl"`, - і `input: "stdin"`, щоб подальші ходи повторно використовували активний live-процес Claude. - Теплий stdio тепер є стандартом, зокрема для користувацьких конфігурацій, - які не вказують транспортні поля. Якщо Gateway перезапускається або idle-процес + і `input: "stdin"`, щоб наступні звернення повторно використовували живий процес Claude, поки + він активний. Теплий stdio тепер є стандартним, зокрема для користувацьких конфігурацій, + які не вказують транспортні поля. Якщо Gateway перезапускається або неактивний процес завершується, OpenClaw відновлюється зі збереженого ідентифікатора сесії Claude. Збережені - ідентифікатори сесій перевіряються щодо наявного читабельного project transcript перед + ідентифікатори сесій перевіряються щодо наявного читабельного transcript проєкту перед відновленням, тому фантомні прив’язки очищаються з `reason=transcript-missing` - замість мовчазного старту нової сесії Claude CLI під `--resume`. -- Live-сесії Claude зберігають обмежені захисні ліміти JSONL-виводу. Стандартні значення дозволяють до - 8 MiB і 20 000 сирих JSONL-рядків на хід. Ходи Claude з великою кількістю інструментів можуть збільшити + замість тихого запуску нової сесії Claude CLI з `--resume`. +- Живі сесії Claude зберігають обмежені захисні ліміти JSONL-виводу. Стандартні значення дозволяють до + 8 MiB і 20,000 сирих JSONL-рядків на звернення. Звернення Claude з великою кількістю інструментів можуть підвищити їх для кожного бекенда через `agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars` - і `maxTurnLines`; OpenClaw обмежує ці налаштування до 64 MiB і 100 000 + і `maxTurnLines`; OpenClaw обмежує ці налаштування до 64 MiB і 100,000 рядків. -- Збережені CLI-сесії є безперервністю, якою володіє провайдер. Неявне щоденне скидання сесії +- Збережені CLI-сесії є безперервністю, що належить провайдеру. Неявне щоденне скидання сесії їх не перериває; `/reset` і явні політики `session.reset` усе ще - діють. + це роблять. Примітки щодо серіалізації: - `serialize: true` зберігає впорядкованість запусків у тому самому lane. - Більшість CLI серіалізуються в одному lane провайдера. -- OpenClaw відкидає повторне використання збереженої CLI-сесії, коли змінюється вибрана автентифікаційна ідентичність, - зокрема змінений ідентифікатор auth profile, статичний API-ключ, статичний токен або ідентичність OAuth-акаунта, - якщо CLI її надає. Ротація OAuth access і refresh token не перериває збережену CLI-сесію. Якщо CLI не надає - стабільний ідентифікатор OAuth-акаунта, OpenClaw дозволяє цьому CLI самостійно застосовувати дозволи відновлення. +- OpenClaw відкидає повторне використання збереженої CLI-сесії, коли змінюється вибрана auth-ідентичність, + зокрема змінений auth profile id, статичний API key, статичний token або ідентичність + облікового запису OAuth, якщо CLI її надає. Ротація access і refresh token OAuth + не перериває збережену CLI-сесію. Якщо CLI не надає + стабільний OAuth account id, OpenClaw дозволяє цій CLI самостійно застосовувати дозволи відновлення. -## Резервний prelude із сесій claude-cli +## Резервна преамбула із сесій claude-cli -Коли спроба `claude-cli` переходить на резервного кандидата, що не є CLI, у -[`agents.defaults.model.fallbacks`](/uk/concepts/model-failover), OpenClaw ініціалізує -наступну спробу контекстним prelude, отриманим із локального -JSONL-транскрипту Claude Code в `~/.claude/projects/`. Без цього seed резервний -провайдер стартував би з порожнього контексту, оскільки власний транскрипт сесії OpenClaw порожній +Коли спроба `claude-cli` переходить на не-CLI кандидата в +[`agents.defaults.model.fallbacks`](/uk/concepts/model-failover), OpenClaw засіває +наступну спробу контекстною преамбулою, отриманою з локального +JSONL transcript Claude Code у `~/.claude/projects/`. Без цього seed резервний +провайдер стартував би з чистого стану, бо власний session transcript OpenClaw порожній для запусків `claude-cli`. -- Prelude віддає перевагу найновішому резюме `/compact` або маркеру `compact_boundary`, - а потім додає найостанніші ходи після boundary у межах бюджету символів. - Ходи до boundary відкидаються, бо резюме вже їх представляє. -- Tool blocks згортаються до компактних підказок `(tool call: name)` і - `(tool result: …)`, щоб чесно утримувати бюджет промпта. Резюме - позначається як `(truncated)`, якщо воно переповнюється. -- Резервні переходи з `claude-cli` на `claude-cli` у межах того самого провайдера покладаються на власний - `--resume` Claude і пропускають prelude. -- Seed повторно використовує наявну валідацію шляху до session-file Claude, тому - довільні шляхи не можуть бути прочитані. +- Преамбула віддає перевагу найновішому summary `/compact` або маркеру `compact_boundary`, + а потім додає найсвіжіші звернення після boundary до бюджету символів. + Звернення до boundary відкидаються, бо summary вже їх представляє. +- Блоки інструментів об’єднуються в компактні підказки `(tool call: name)` і + `(tool result: …)`, щоб зберегти prompt budget реалістичним. Summary позначається + `(truncated)`, якщо воно переповнюється. +- Резервні переходи same-provider `claude-cli` до `claude-cli` покладаються на власний + `--resume` Claude і пропускають преамбулу. +- Seed повторно використовує наявну перевірку шляху до session-file Claude, тому + довільні шляхи не можна прочитати. ## Зображення (наскрізне передавання) -Якщо ваш CLI приймає шляхи до зображень, задайте `imageArg`: +Якщо ваша CLI приймає шляхи до зображень, задайте `imageArg`: ```json5 imageArg: "--image", imageMode: "repeat" ``` -OpenClaw записуватиме base64-зображення у тимчасові файли. Якщо `imageArg` задано, ці -шляхи передаються як аргументи CLI. Якщо `imageArg` відсутній, OpenClaw додає -шляхи до файлів у промпт (ін’єкція шляху), чого достатньо для CLI, які автоматично +OpenClaw запише base64-зображення у тимчасові файли. Якщо `imageArg` задано, ці +шляхи передаються як CLI-аргументи. Якщо `imageArg` відсутній, OpenClaw додає +шляхи до файлів у prompt (ін’єкція шляху), чого достатньо для CLI, які автоматично завантажують локальні файли зі звичайних шляхів. -## Входи / виходи +## Вхідні дані / вивід -- `output: "json"` (за замовчуванням) намагається розібрати JSON і витягти текст + ідентифікатор сесії. +- `output: "json"` (стандартно) намагається розібрати JSON і витягнути текст + ідентифікатор сесії. - Для JSON-виводу Gemini CLI OpenClaw читає текст відповіді з `response` і usage зі `stats`, коли `usage` відсутній або порожній. -- `output: "jsonl"` розбирає JSONL-потоки (наприклад, Codex CLI `--json`) і витягує фінальне повідомлення агента разом з ідентифікаторами сесії, - якщо вони наявні. +- `output: "jsonl"` розбирає JSONL-потоки (наприклад, Codex CLI `--json`) і витягує фінальне повідомлення агента плюс + ідентифікатори сесії, якщо вони наявні. - `output: "text"` трактує stdout як фінальну відповідь. Режими введення: -- `input: "arg"` (за замовчуванням) передає промпт як останній аргумент CLI. -- `input: "stdin"` надсилає промпт через stdin. -- Якщо промпт дуже довгий і `maxPromptArgChars` задано, використовується stdin. +- `input: "arg"` (стандартно) передає prompt як останній CLI-аргумент. +- `input: "stdin"` надсилає prompt через stdin. +- Якщо prompt дуже довгий і задано `maxPromptArgChars`, використовується stdin. -## Стандартні значення (належать Plugin) +## Стандартні значення (належать plugin) -Вбудований OpenAI Plugin також реєструє стандартні значення для `codex-cli`: +Вбудований OpenAI plugin також реєструє стандартне значення для `codex-cli`: - `command: "codex"` - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` @@ -298,7 +305,7 @@ OpenClaw записуватиме base64-зображення у тимчасо - `imageArg: "--image"` - `sessionMode: "existing"` -Вбудований Google Plugin також реєструє стандартні значення для `google-gemini-cli`: +Вбудований Google plugin також реєструє стандартне значення для `google-gemini-cli`: - `command: "gemini"` - `args: ["--output-format", "json", "--prompt", "{prompt}"]` @@ -315,26 +322,26 @@ OpenClaw записуватиме base64-зображення у тимчасо Примітки щодо JSON Gemini CLI: -- Текст відповіді читається з JSON-поля `response`. -- Usage використовує fallback до `stats`, коли `usage` відсутній або порожній. +- Текст відповіді зчитується з JSON-поля `response`. +- Використання повертається до `stats`, коли `usage` відсутнє або порожнє. - `stats.cached` нормалізується в OpenClaw `cacheRead`. -- Якщо `stats.input` відсутній, OpenClaw виводить input tokens із +- Якщо `stats.input` відсутнє, OpenClaw виводить вхідні токени з `stats.input_tokens - stats.cached`. -Перевизначайте лише за потреби (поширений випадок: абсолютний шлях `command`). +Перевизначайте лише за потреби (поширене: абсолютний шлях `command`). -## Стандартні значення, що належать Plugin +## Типові значення, що належать Plugin -Стандартні значення CLI-бекендів тепер є частиною поверхні Plugin: +Типові значення бекенда CLI тепер є частиною поверхні plugin: -- Plugins реєструють їх за допомогою `api.registerCliBackend(...)`. -- Backend `id` стає префіксом провайдера в посиланнях на моделі. -- Конфігурація користувача в `agents.defaults.cliBackends.` досі перевизначає стандартне значення Plugin. -- Очищення конфігурації, специфічної для backend, залишається у власності Plugin через необов’язковий hook - `normalizeConfig`. +- Плагіни реєструють їх за допомогою `api.registerCliBackend(...)`. +- `id` бекенда стає префіксом провайдера в посиланнях на моделі. +- Користувацька конфігурація в `agents.defaults.cliBackends.` і далі перевизначає типове значення plugin. +- Очищення конфігурації, специфічної для бекенда, залишається у власності plugin через необов’язковий + хук `normalizeConfig`. -Plugins, яким потрібні невеликі шими сумісності prompt/message, можуть оголошувати -двонапрямні текстові перетворення без заміни провайдера або CLI backend: +Плагіни, яким потрібні невеликі шими сумісності промптів/повідомлень, можуть оголошувати +двонапрямні текстові перетворення без заміни провайдера або бекенда CLI: ```typescript api.registerTextTransforms({ @@ -351,65 +358,65 @@ api.registerTextTransforms({ }); ``` -`input` переписує системний prompt і prompt користувача, передані до CLI. `output` -переписує потокові дельти помічника та розібраний фінальний текст до того, як OpenClaw обробить -власні керівні маркери й доставку в канал. +`input` переписує системний промпт і користувацький промпт, передані до CLI. `output` +переписує потокові дельти асистента й розібраний фінальний текст до того, як OpenClaw обробить +власні керівні маркери та доставку в канал. -Для CLI, що виводять JSONL, сумісний із Claude Code stream-json, задайте -`jsonlDialect: "claude-stream-json"` у конфігурації цього backend. +Для CLI, які виводять сумісний із Claude Code stream-json JSONL, встановіть +`jsonlDialect: "claude-stream-json"` у конфігурації цього бекенда. -## Об’єднання MCP-накладень +## Оверлеї MCP для пакета -CLI backends **не** отримують виклики інструментів OpenClaw напряму, але backend може -увімкнути згенероване накладення конфігурації MCP за допомогою `bundleMcp: true`. +Бекенди CLI **не** отримують виклики інструментів OpenClaw напряму, але бекенд може +увімкнути згенерований оверлей конфігурації MCP за допомогою `bundleMcp: true`. Поточна вбудована поведінка: -- `claude-cli`: згенерований файл суворої конфігурації MCP +- `claude-cli`: згенерований строгий файл конфігурації MCP - `codex-cli`: вбудовані перевизначення конфігурації для `mcp_servers`; згенерований - OpenClaw loopback server позначено режимом схвалення інструментів на рівні сервера Codex, - щоб MCP-виклики не могли зупинитися на локальних запитах схвалення + loopback-сервер OpenClaw позначається режимом схвалення інструментів Codex для кожного сервера, + щоб виклики MCP не зупинялися на локальних запитах схвалення - `google-gemini-cli`: згенерований файл системних налаштувань Gemini -Коли об’єднання MCP увімкнено, OpenClaw: +Коли MCP для пакета увімкнено, OpenClaw: -- запускає loopback HTTP MCP server, який відкриває gateway tools для процесу CLI -- автентифікує міст за допомогою токена на сеанс (`OPENCLAW_MCP_TOKEN`) -- обмежує доступ до інструментів поточним сеансом, обліковим записом і контекстом каналу -- завантажує увімкнені bundle-MCP servers для поточного workspace -- об’єднує їх із будь-якою наявною формою backend MCP config/settings -- переписує конфігурацію запуску, використовуючи режим інтеграції, що належить backend, із власницького Plugin +- запускає loopback HTTP MCP-сервер, який надає інструменти gateway процесу CLI +- автентифікує міст за допомогою токена для кожної сесії (`OPENCLAW_MCP_TOKEN`) +- обмежує доступ до інструментів поточною сесією, обліковим записом і контекстом каналу +- завантажує увімкнені bundle-MCP сервери для поточного workspace +- об’єднує їх із будь-якою наявною формою MCP-конфігурації/налаштувань бекенда +- переписує конфігурацію запуску, використовуючи режим інтеграції, що належить бекенду з extension-власника -Якщо MCP servers не ввімкнено, OpenClaw все одно впроваджує сувору конфігурацію, коли -backend вмикає bundle MCP, щоб фонові запуски залишалися ізольованими. +Якщо жоден MCP-сервер не увімкнено, OpenClaw усе одно ін’єктує строгу конфігурацію, коли +бекенд увімкнув MCP для пакета, щоб фонові запуски залишалися ізольованими. -Сеансові вбудовані MCP runtimes кешуються для повторного використання в межах сеансу, а потім -очищаються після `mcp.sessionIdleTtlMs` мілісекунд простою (за замовчуванням 10 -хвилин; задайте `0`, щоб вимкнути). Одноразові вбудовані запуски, як-от auth probes, -slug generation і active-memory recall request cleanup, завершуються наприкінці запуску, щоб stdio -children і Streamable HTTP/SSE streams не жили довше за сам запуск. +Сеансово-обмежені вбудовані середовища виконання MCP кешуються для повторного використання в межах сесії, а потім +очищаються після `mcp.sessionIdleTtlMs` мілісекунд простою (типово 10 +хвилин; встановіть `0`, щоб вимкнути). Одноразові вбудовані запуски, як-от перевірки автентифікації, +генерація slug і запити на пригадування active-memory, очищуються наприкінці запуску, щоб stdio +дочірні процеси та потоки Streamable HTTP/SSE не жили довше за сам запуск. ## Обмеження -- **Немає прямих викликів інструментів OpenClaw.** OpenClaw не впроваджує виклики інструментів у - протокол CLI backend. Backends бачать gateway tools лише тоді, коли вмикають +- **Немає прямих викликів інструментів OpenClaw.** OpenClaw не ін’єктує виклики інструментів у + протокол бекенда CLI. Бекенди бачать інструменти gateway лише тоді, коли вмикають `bundleMcp: true`. -- **Streaming залежить від backend.** Деякі backends транслюють JSONL; інші буферизують +- **Потокове передавання залежить від бекенда.** Деякі бекенди передають JSONL потоком; інші буферизують до завершення. -- **Структуровані виводи** залежать від формату JSON у CLI. -- **Сеанси Codex CLI** поновлюються через текстовий вивід (без JSONL), який менш - структурований, ніж початковий запуск `--json`. Сеанси OpenClaw все одно працюють +- **Структуровані виводи** залежать від JSON-формату CLI. +- **Сесії Codex CLI** відновлюються через текстовий вивід (без JSONL), який менш + структурований, ніж початковий запуск із `--json`. Сесії OpenClaw усе одно працюють нормально. ## Усунення несправностей -- **CLI не знайдено**: задайте `command` як повний шлях. +- **CLI не знайдено**: встановіть для `command` повний шлях. - **Неправильна назва моделі**: використовуйте `modelAliases`, щоб зіставити `provider/model` → модель CLI. -- **Немає безперервності сеансу**: переконайтеся, що `sessionArg` задано, а `sessionMode` не є - `none` (Codex CLI наразі не може поновлюватися з JSON-виводом). -- **Зображення ігноруються**: задайте `imageArg` (і перевірте, що CLI підтримує шляхи до файлів). +- **Немає неперервності сесії**: переконайтеся, що `sessionArg` задано, а `sessionMode` не дорівнює + `none` (Codex CLI наразі не може відновлюватися з JSON-виводом). +- **Зображення ігноруються**: встановіть `imageArg` (і перевірте, що CLI підтримує шляхи до файлів). ## Пов’язане -- [Gateway runbook](/uk/gateway) +- [Runbook Gateway](/uk/gateway) - [Локальні моделі](/uk/gateway/local-models) diff --git a/docs/uk/plugins/sdk-overview.md b/docs/uk/plugins/sdk-overview.md index b68203c28..b52782166 100644 --- a/docs/uk/plugins/sdk-overview.md +++ b/docs/uk/plugins/sdk-overview.md @@ -1,36 +1,35 @@ --- read_when: - Потрібно знати, з якого підшляху SDK імпортувати - - Вам потрібна довідка щодо всіх методів реєстрації в OpenClawPluginApi + - Вам потрібна довідка про всі методи реєстрації в OpenClawPluginApi - Ви шукаєте конкретний експорт SDK sidebarTitle: Plugin SDK overview -summary: Карта імпортів, довідник API реєстрації та архітектура SDK +summary: Мапа імпортів, довідник API реєстрації та архітектура SDK title: Огляд Plugin SDK x-i18n: - generated_at: "2026-05-02T02:49:22Z" + generated_at: "2026-05-04T18:18:33Z" model: gpt-5.5 provider: openai - source_hash: be5fa531e603fb6d87f84e3193ebd61be1431b57b8f284871ae15f34ca93fc69 + source_hash: 8187e7d4cfb9d6fb19bbdebfbaea0bb4d98fa5cea4742d0f82a765ae5bc60127 source_path: plugins/sdk-overview.md workflow: 16 --- -SDK плагінів — це типізований контракт між плагінами та ядром. Ця сторінка є -довідником щодо **того, що імпортувати** і **того, що можна реєструвати**. +SDK для плагінів є типізованим контрактом між плагінами та ядром. Ця сторінка є +довідником про **що імпортувати** і **що можна реєструвати**. - Ця сторінка призначена для авторів плагінів, які використовують - `openclaw/plugin-sdk/*` всередині OpenClaw. Для зовнішніх застосунків, - скриптів, панелей керування, завдань CI та розширень IDE, які хочуть запускати - агентів через Gateway, натомість використовуйте - [SDK застосунків OpenClaw](/uk/concepts/openclaw-sdk) і пакет `@openclaw/sdk`. + Ця сторінка призначена для авторів плагінів, які використовують `openclaw/plugin-sdk/*` всередині + OpenClaw. Для зовнішніх застосунків, скриптів, панелей керування, CI-завдань і розширень IDE, + які хочуть запускати агентів через Gateway, натомість використовуйте + [OpenClaw App SDK](/uk/concepts/openclaw-sdk) і пакет `@openclaw/sdk`. -Натомість шукаєте практичний посібник? Почніть із [Створення плагінів](/uk/plugins/building-plugins), використовуйте [Плагіни каналів](/uk/plugins/sdk-channel-plugins) для плагінів каналів, [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) для плагінів провайдерів і [Хуки Plugin](/uk/plugins/hooks) для плагінів хуків інструментів або життєвого циклу. +Шукаєте натомість практичний посібник? Почніть із [Створення плагінів](/uk/plugins/building-plugins), використовуйте [Плагіни каналів](/uk/plugins/sdk-channel-plugins) для плагінів каналів, [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) для плагінів провайдерів і [Хуки Plugin](/uk/plugins/hooks) для плагінів хуків інструментів або життєвого циклу. -## Угода щодо імпорту +## Угода про імпорт Завжди імпортуйте з конкретного підшляху: @@ -39,85 +38,82 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -Кожен підшлях — це невеликий самодостатній модуль. Це забезпечує швидкий запуск -і запобігає проблемам із циклічними залежностями. Для допоміжних засобів -входу/збирання, специфічних для каналів, віддавайте перевагу -`openclaw/plugin-sdk/channel-core`; залишайте `openclaw/plugin-sdk/core` для -ширшої спільної поверхні та спільних допоміжних засобів, як-от -`buildChannelConfigSchema`. +Кожен підшлях є невеликим самодостатнім модулем. Це прискорює запуск і +запобігає проблемам із циклічними залежностями. Для помічників входу/збірки, +специфічних для каналів, віддавайте перевагу `openclaw/plugin-sdk/channel-core`; +залишайте `openclaw/plugin-sdk/core` для ширшої поверхні-парасолі та спільних +помічників, таких як `buildChannelConfigSchema`. Для конфігурації каналу публікуйте JSON Schema, що належить каналу, через `openclaw.plugin.json#channelConfigs`. Підшлях `plugin-sdk/channel-config-schema` -призначений для спільних примітивів схеми та загального збирача. Вбудовані +призначений для спільних примітивів схем і загального builder. Вбудовані плагіни OpenClaw використовують `plugin-sdk/bundled-channel-config-schema` для збережених схем вбудованих каналів. Застарілі експорти сумісності залишаються в -`plugin-sdk/channel-config-schema-legacy`; жоден із підшляхів вбудованих схем не -є шаблоном для нових плагінів. +`plugin-sdk/channel-config-schema-legacy`; жоден підшлях вбудованих схем не є +шаблоном для нових плагінів. - Не імпортуйте зручні шви з брендингом провайдера або каналу (наприклад + Не імпортуйте зручні шви, брендовані провайдером або каналом (наприклад `openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`). - Вбудовані плагіни компонують загальні підшляхи SDK всередині власних барелів - `api.ts` / `runtime-api.ts`; споживачі ядра мають або використовувати ці - локальні для плагіна барелі, або додати вузький загальний контракт SDK, коли - потреба справді є міжканальною. + Вбудовані плагіни компонують загальні підшляхи SDK у власних барелях `api.ts` / + `runtime-api.ts`; споживачі ядра мають або використовувати ці локальні для + плагіна барелі, або додати вузький загальний контракт SDK, коли потреба справді + є міжканальною. -Невеликий набір допоміжних швів вбудованих плагінів досі з’являється у -згенерованій мапі експортів, коли для них відстежено використання власником. +Невеликий набір допоміжних швів вбудованих плагінів усе ще з’являється у +згенерованій мапі експортів, коли вони мають відстежене використання власником. Вони існують лише для супроводу вбудованих плагінів і не рекомендовані як шляхи імпорту для нових сторонніх плагінів. `openclaw/plugin-sdk/discord` і `openclaw/plugin-sdk/telegram-account` також збережені як застарілі фасади сумісності для відстеженого використання -власником. Не копіюйте ці шляхи імпорту в нові плагіни; натомість -використовуйте ін’єктовані runtime-допоміжні засоби та загальні підшляхи SDK -каналів. +власником. Не копіюйте ці шляхи імпорту в нові плагіни; натомість використовуйте +ін’єктовані runtime-помічники та загальні підшляхи SDK каналів. ## Довідник підшляхів -SDK плагінів надається як набір вузьких підшляхів, згрупованих за областями -(вхід плагіна, канал, провайдер, автентифікація, runtime, можливості, пам’ять і -зарезервовані допоміжні засоби вбудованих плагінів). Повний каталог — -згрупований і з посиланнями — дивіться в -[підшляхах SDK Plugin](/uk/plugins/sdk-subpaths). +SDK для плагінів надається як набір вузьких підшляхів, згрупованих за сферами +(вхід плагіна, канал, провайдер, автентифікація, runtime, capability, пам’ять і +зарезервовані помічники вбудованих плагінів). Повний каталог, згрупований і +пов’язаний посиланнями, дивіться в [Підшляхи SDK для плагінів](/uk/plugins/sdk-subpaths). Згенерований список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`. ## API реєстрації -Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` з такими +Callback `register(api)` отримує об’єкт `OpenClawPluginApi` з такими методами: -### Реєстрація можливостей +### Реєстрація capability | Метод | Що він реєструє | | ------------------------------------------------ | --------------------------------------- | -| `api.registerProvider(...)` | Текстове виведення (LLM) | -| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента | -| `api.registerCliBackend(...)` | Локальний backend виведення CLI | -| `api.registerChannel(...)` | Канал обміну повідомленнями | -| `api.registerSpeechProvider(...)` | Перетворення тексту на мовлення / синтез STT | +| `api.registerProvider(...)` | Текстовий inference (LLM) | +| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агентів | +| `api.registerCliBackend(...)` | Локальний CLI inference backend | +| `api.registerChannel(...)` | Канал повідомлень | +| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | | `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі | -| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сесії в реальному часі | +| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сеанси в реальному часі | | `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | | `api.registerImageGenerationProvider(...)` | Генерація зображень | | `api.registerMusicGenerationProvider(...)` | Генерація музики | | `api.registerVideoGenerationProvider(...)` | Генерація відео | -| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scraping | +| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | | `api.registerWebSearchProvider(...)` | Вебпошук | ### Інструменти та команди -| Метод | Що він реєструє | -| ------------------------------- | ---------------------------------------------- | +| Метод | Що він реєструє | +| ----------------------------- | -------------------------------------------- | | `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) | -| `api.registerCommand(def)` | Користувацька команда (оминає LLM) | +| `api.registerCommand(def)` | Користувацька команда (оминає LLM) | Команди плагінів можуть задавати `agentPromptGuidance`, коли агенту потрібна -коротка підказка маршрутизації, що належить команді. Тримайте цей текст про саму -команду; не додавайте політику, специфічну для провайдера або плагіна, до -збирачів prompt у ядрі. +коротка підказка маршрутизації, що належить команді. Тримайте цей текст про +саму команду; не додавайте політики, специфічної для провайдера або плагіна, до +builder prompt ядра. ### Інфраструктура @@ -125,80 +121,87 @@ SDK плагінів надається як набір вузьких підш | ---------------------------------------------- | --------------------------------------- | | `api.registerHook(events, handler, opts?)` | Хук події | | `api.registerHttpRoute(params)` | HTTP endpoint Gateway | -| `api.registerGatewayMethod(name, handler)` | Метод RPC Gateway | -| `api.registerGatewayDiscoveryService(service)` | Рекламодавець виявлення локального Gateway | +| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway | +| `api.registerGatewayDiscoveryService(service)` | Локальний рекламодавець виявлення Gateway | | `api.registerCli(registrar, opts?)` | Підкоманда CLI | | `api.registerService(service)` | Фонова служба | | `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | | `api.registerAgentToolResultMiddleware(...)` | Runtime middleware результатів інструментів | -| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt поруч із пам’яттю | -| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті | +| `api.registerMemoryPromptSupplement(builder)` | Додатковий розділ prompt поруч із пам’яттю | +| `api.registerMemoryCorpusSupplement(adapter)` | Додатковий корпус пошуку/читання пам’яті | -### Хостові хуки для workflow-плагінів +### Хуки хоста для плагінів workflow -Хостові хуки — це шви SDK для плагінів, яким потрібно брати участь у життєвому +Хуки хоста є швами SDK для плагінів, яким потрібно брати участь у життєвому циклі хоста, а не лише додавати провайдера, канал або інструмент. Це загальні -контракти; Plan Mode може їх використовувати, але так само можуть workflow -погоджень, policy gates робочого простору, фонові монітори, майстри -налаштування та супровідні UI-плагіни. +контракти; режим Plan може їх використовувати, але так само можуть workflow +затверджень, шлюзи політики workspace, фонові монітори, майстри налаштування та +супровідні UI-плагіни. | Метод | Контракт, яким він володіє | -| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerSessionExtension(...)` | Стан сесії, що належить плагіну, сумісний із JSON і проєктується через сесії Gateway | -| `api.enqueueNextTurnInjection(...)` | Стійкий рівно-один-раз контекст, ін’єктований у наступний хід агента для однієї сесії | -| `api.registerTrustedToolPolicy(...)` | Політика інструментів вбудованого/довіреного pre-plugin, яка може блокувати або переписувати параметри інструменту | -| `api.registerToolMetadata(...)` | Метадані відображення каталогу інструментів без зміни реалізації інструменту | -| `api.registerCommand(...)` | Обмежені за областю команди плагінів; результати команд можуть задавати `continueAgent: true`; нативні команди Discord підтримують `descriptionLocalizations` | -| `api.registerControlUiDescriptor(...)` | Дескриптори внеску Control UI для поверхонь сесії, інструменту, запуску або налаштувань | -| `api.registerRuntimeLifecycle(...)` | Зворотні виклики очищення для runtime-ресурсів, що належать плагіну, на шляхах reset/delete/reload | -| `api.registerAgentEventSubscription(...)` | Санітизовані підписки на події для стану workflow та моніторів | -| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Чернетковий стан плагіна для окремого запуску, очищений під час термінального життєвого циклу запуску | -| `api.registerSessionSchedulerJob(...)` | Записи завдань планувальника сесій, що належать плагіну, з детермінованим очищенням | +| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerSessionExtension(...)` | JSON-сумісний стан сеансу, що належить плагіну та проєктується через сеанси Gateway | +| `api.enqueueNextTurnInjection(...)` | Стійкий exactly-once контекст, ін’єктований у наступний хід агента для одного сеансу | +| `api.registerTrustedToolPolicy(...)` | Політика інструментів pre-plugin для вбудованих/довірених плагінів, яка може блокувати або переписувати параметри інструмента | +| `api.registerToolMetadata(...)` | Метадані відображення каталогу інструментів без зміни реалізації інструмента | +| `api.registerCommand(...)` | Обмежені плагіном команди; результати команд можуть задавати `continueAgent: true`; нативні команди Discord підтримують `descriptionLocalizations` | +| `api.registerControlUiDescriptor(...)` | Дескриптори внесків Control UI для поверхонь сеансу, інструмента, запуску або налаштувань | +| `api.registerRuntimeLifecycle(...)` | Callback-и очищення для runtime-ресурсів, що належать плагіну, на шляхах reset/delete/reload | +| `api.registerAgentEventSubscription(...)` | Санітизовані підписки на події для стану workflow і моніторів | +| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Тимчасовий стан плагіна для окремого запуску, що очищується під час термінального життєвого циклу запуску | +| `api.registerSessionSchedulerJob(...)` | Записи завдань планувальника сеансів, що належать плагіну, з детермінованим очищенням | Контракти навмисно розділяють повноваження: -- Зовнішні плагіни можуть володіти розширеннями сесій, дескрипторами UI, командами, метаданими інструментів, ін’єкціями наступного ходу та звичайними хуками. -- Довірені політики інструментів виконуються перед звичайними хуками `before_tool_call` і доступні лише вбудованим плагінам, бо вони беруть участь у політиці безпеки хоста. -- Зарезервоване володіння командами доступне лише вбудованим плагінам. Зовнішні плагіни мають використовувати власні назви команд або псевдоніми. -- `allowPromptInjection=false` вимикає хуки, що змінюють prompt, включно з `agent_turn_prepare`, `before_prompt_build`, `heartbeat_prompt_contribution`, полями prompt із застарілого `before_agent_start` та `enqueueNextTurnInjection`. +- Зовнішні плагіни можуть володіти розширеннями сеансів, дескрипторами UI, + командами, метаданими інструментів, ін’єкціями наступного ходу та звичайними + хуками. +- Довірені політики інструментів виконуються перед звичайними хуками + `before_tool_call` і доступні лише для вбудованих плагінів, оскільки беруть + участь у політиці безпеки хоста. +- Зарезервоване володіння командами доступне лише для вбудованих плагінів. + Зовнішні плагіни мають використовувати власні назви команд або псевдоніми. +- `allowPromptInjection=false` вимикає хуки, що змінюють prompt, включно з + `agent_turn_prepare`, `before_prompt_build`, `heartbeat_prompt_contribution`, + полями prompt із застарілого `before_agent_start` і + `enqueueNextTurnInjection`. -Приклади споживачів, не пов’язаних із Plan: +Приклади споживачів, що не належать до Plan: -| Архетип плагіна | Використані хуки | -| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| Workflow погодження | Розширення сесії, продовження команди, ін’єкція наступного ходу, дескриптор UI | -| Policy gate бюджету/робочого простору | Довірена політика інструментів, метадані інструментів, проєкція сесії | -| Фоновий монітор життєвого циклу | Очищення runtime-життєвого циклу, підписка на події агента, володіння/очищення планувальника сесій, внесок heartbeat prompt, дескриптор UI | -| Майстер налаштування або onboarding | Розширення сесії, scoped-команди, дескриптор Control UI | +| Архетип плагіна | Використані хуки | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| Workflow затвердження | Розширення сеансу, продовження команди, ін’єкція наступного ходу, дескриптор UI | +| Шлюз політики бюджету/workspace | Довірена політика інструментів, метадані інструментів, проєкція сеансу | +| Фоновий монітор життєвого циклу | Очищення runtime lifecycle, підписка на події агента, володіння/очищення планувальника сеансів, внесок heartbeat prompt, дескриптор UI | +| Майстер налаштування або onboarding | Розширення сеансу, обмежені команди, дескриптор Control UI | - Зарезервовані простори імен адміністрування ядра (`config.*`, - `exec.approvals.*`, `wizard.*`, `update.*`) завжди залишаються - `operator.admin`, навіть якщо плагін намагається призначити вужчу область - методу gateway. Віддавайте перевагу префіксам, специфічним для плагіна, для + Зарезервовані простори імен адміністратора ядра (`config.*`, `exec.approvals.*`, `wizard.*`, + `update.*`) завжди залишаються `operator.admin`, навіть якщо плагін намагається призначити + вужчий scope методу Gateway. Віддавайте перевагу префіксам, специфічним для плагіна, для методів, що належать плагіну. Вбудовані плагіни можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли - їм потрібно переписати результат інструменту після виконання і до того, як runtime - передасть цей результат назад у модель. Це довірений runtime-нейтральний - шов для асинхронних редукторів виводу, таких як tokenjuice. + їм потрібно переписати результат інструмента після виконання і до того, як runtime + передасть цей результат назад у модель. Це довірений runtime-нейтральний шов + для асинхронних редукторів виводу, таких як tokenjuice. -Вбудовані плагіни мають оголошувати `contracts.agentToolResultMiddleware` для -кожного цільового runtime, наприклад `["pi", "codex"]`. Зовнішні плагіни -не можуть реєструвати цей middleware; залишайте звичайні хуки плагінів OpenClaw для роботи, -якій не потрібен timing результатів інструментів перед моделлю. Старий шлях -реєстрації вбудованої фабрики розширень лише для Pi було вилучено. +Вбудовані плагіни мають оголошувати `contracts.agentToolResultMiddleware` для кожного +цільового runtime, наприклад `["pi", "codex"]`. Зовнішні плагіни +не можуть реєструвати це middleware; залишайте звичайні хуки плагінів OpenClaw для роботи, +якій не потрібен timing результату інструмента перед моделлю. Старий шлях реєстрації +вбудованої фабрики розширень лише для Pi було видалено. ### Реєстрація виявлення Gateway -`api.registerGatewayDiscoveryService(...)` дає плагіну змогу оголошувати активний -Gateway у локальному транспорті виявлення, як-от mDNS/Bonjour. OpenClaw викликає -службу під час запуску Gateway, коли локальне виявлення ввімкнено, передає -поточні порти Gateway і несекретні підказки TXT, а під час завершення роботи -Gateway викликає повернений обробник `stop`. +`api.registerGatewayDiscoveryService(...)` дає змогу Plugin оголошувати активний +Gateway у локальному транспорті виявлення, такому як mDNS/Bonjour. OpenClaw викликає +сервіс під час запуску Gateway, коли локальне виявлення ввімкнено, передає +поточні порти Gateway і несекретні дані підказок TXT, а також викликає повернений +обробник `stop` під час завершення роботи Gateway. ```typescript api.registerGatewayDiscoveryService({ @@ -214,9 +217,9 @@ api.registerGatewayDiscoveryService({ }); ``` -Плагіни виявлення Gateway не повинні вважати оголошені значення TXT секретами чи -автентифікацією. Виявлення — це підказка для маршрутизації; автентифікація -Gateway і прив’язування TLS усе ще відповідають за довіру. +Plugin-и виявлення Gateway не повинні трактувати оголошені значення TXT як секрети або +автентифікацію. Виявлення є підказкою маршрутизації; автентифікація Gateway і прив’язування TLS +і далі відповідають за довіру. ### Метадані реєстрації CLI @@ -224,11 +227,11 @@ Gateway і прив’язування TLS усе ще відповідають - `commands`: явні корені команд, якими володіє реєстратор - `descriptors`: дескриптори команд під час розбору, що використовуються для довідки кореневого CLI, - маршрутизації та лінивої реєстрації CLI плагіна + маршрутизації та лінивої реєстрації CLI Plugin -Якщо ви хочете, щоб команда плагіна лишалася ліниво завантажуваною у звичайному -шляху кореневого CLI, надайте `descriptors`, які охоплюють кожен корінь команди -верхнього рівня, відкритий цим реєстратором. +Якщо потрібно, щоб команда Plugin залишалася ліниво завантажуваною у звичайному шляху кореневого CLI, +надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, що відкриває цей +реєстратор. ```typescript api.registerCli( @@ -248,100 +251,100 @@ api.registerCli( ); ``` -Використовуйте лише `commands` тільки тоді, коли вам не потрібна лінива -реєстрація кореневого CLI. Цей нетерплячий шлях сумісності й надалі -підтримується, але він не встановлює заповнювачі на основі дескрипторів для -лінивого завантаження під час розбору. +Використовуйте `commands` окремо лише тоді, коли вам не потрібна лінива реєстрація кореневого CLI. +Цей шлях активної сумісності й надалі підтримується, але він не встановлює +заповнювачі на основі дескрипторів для лінивого завантаження під час розбору. -### Реєстрація бекенда CLI +### Реєстрація бекенду CLI -`api.registerCliBackend(...)` дає плагіну змогу володіти типовою конфігурацією -для локального бекенда AI CLI, як-от `codex-cli`. +`api.registerCliBackend(...)` дає змогу Plugin володіти типовою конфігурацією для локального +бекенду AI CLI, такого як `codex-cli`. -- `id` бекенда стає префіксом провайдера в посиланнях на моделі, як-от `codex-cli/gpt-5`. -- `config` бекенда використовує ту саму форму, що й `agents.defaults.cliBackends.`. +- `id` бекенду стає префіксом провайдера в посиланнях на моделі, як-от `codex-cli/gpt-5`. +- `config` бекенду використовує ту саму форму, що й `agents.defaults.cliBackends.`. - Конфігурація користувача все одно має пріоритет. OpenClaw об’єднує `agents.defaults.cliBackends.` поверх - типового значення плагіна перед запуском CLI. + типових налаштувань Plugin перед запуском CLI. - Використовуйте `normalizeConfig`, коли бекенду потрібні переписування сумісності після об’єднання (наприклад, нормалізація старих форм прапорців). +- Використовуйте `resolveExecutionArgs` для переписування argv в межах запиту, яке належить до + діалекту CLI, наприклад зіставлення рівнів мислення OpenClaw із нативним прапорцем зусилля. ### Ексклюзивні слоти -| Метод | Що реєструє | -| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Двигун контексту (один активний одночасно). Зворотний виклик `assemble()` отримує `availableTools` і `citationsMode`, щоб двигун міг адаптувати додатки до промпта. | -| `api.registerMemoryCapability(capability)` | Уніфікована можливість пам’яті | -| `api.registerMemoryPromptSection(builder)` | Побудовник розділу промпта пам’яті | -| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану скидання пам’яті | +| Метод | Що реєструє | +| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | Рушій контексту (активний один за раз). Callback `assemble()` отримує `availableTools` і `citationsMode`, щоб рушій міг адаптувати доповнення до промпта. | +| `api.registerMemoryCapability(capability)` | Уніфікована можливість пам’яті | +| `api.registerMemoryPromptSection(builder)` | Побудовник секції промпта пам’яті | +| `api.registerMemoryFlushPlan(resolver)` | Resolver плану скидання пам’яті | | `api.registerMemoryRuntime(runtime)` | Адаптер середовища виконання пам’яті | -### Адаптери вбудовування пам’яті +### Адаптери embedding пам’яті -| Метод | Що реєструє | -| ---------------------------------------------- | ----------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер вбудовування пам’яті для активного плагіна | +| Метод | Що реєструє | +| ---------------------------------------------- | ------------------------------------------ | +| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам’яті для активного Plugin | -- `registerMemoryCapability` — бажаний ексклюзивний API плагіна пам’яті. +- `registerMemoryCapability` є рекомендованим API ексклюзивного Plugin пам’яті. - `registerMemoryCapability` також може відкривати `publicArtifacts.listArtifacts(...)`, - щоб супровідні плагіни могли споживати експортовані артефакти пам’яті через - `openclaw/plugin-sdk/memory-host-core`, а не звертатися до приватної структури - конкретного плагіна пам’яті. + щоб супутні Plugin могли споживати експортовані артефакти пам’яті через + `openclaw/plugin-sdk/memory-host-core`, а не звертатися до приватної структури конкретного + Plugin пам’яті. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` і - `registerMemoryRuntime` — ексклюзивні API плагіна пам’яті зі спадковою сумісністю. + `registerMemoryRuntime` є API ексклюзивного Plugin пам’яті із сумісністю зі спадщиною. - `MemoryFlushPlan.model` може закріпити хід скидання за точним посиланням - `provider/model`, як-от `ollama/qwen3:8b`, без успадкування активного ланцюжка - резервних варіантів. -- `registerMemoryEmbeddingProvider` дає активному плагіну пам’яті змогу - зареєструвати один або кілька ідентифікаторів адаптерів вбудовування - (наприклад `openai`, `gemini` або власний ідентифікатор, визначений плагіном). + `provider/model`, таким як `ollama/qwen3:8b`, без успадкування активного fallback + ланцюжка. +- `registerMemoryEmbeddingProvider` дає змогу активному Plugin пам’яті зареєструвати один + або кілька id адаптерів embedding (наприклад `openai`, `gemini` або власний + id, визначений Plugin). - Конфігурація користувача, як-от `agents.defaults.memorySearch.provider` і - `agents.defaults.memorySearch.fallback`, розв’язується відносно цих - зареєстрованих ідентифікаторів адаптерів. + `agents.defaults.memorySearch.fallback`, зіставляється з цими зареєстрованими + id адаптерів. ### Події та життєвий цикл -| Метод | Що робить | -| -------------------------------------------- | ------------------------------- | -| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | -| `api.onConversationBindingResolved(handler)` | Зворотний виклик прив’язки розмови | +| Метод | Що робить | +| -------------------------------------------- | ------------------------------ | +| `api.on(hookName, handler, opts?)` | Типізований hook життєвого циклу | +| `api.onConversationBindingResolved(handler)` | Callback прив’язки розмови | -Див. [хуки плагінів](/uk/plugins/hooks), щоб знайти приклади, поширені назви хуків -і семантику запобіжників. +Див. [hooks Plugin](/uk/plugins/hooks) для прикладів, поширених назв hook і семантики guard. -### Семантика рішень хуків +### Семантика рішень hook -- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. -- `before_tool_call`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як пропуск `block`), а не як перевизначення. -- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. -- `before_install`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як пропуск `block`), а не як перевизначення. -- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник заявляє про обробку відправлення, обробники з нижчим пріоритетом і типовий шлях відправлення моделі пропускаються. -- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. -- `message_sending`: повернення `{ cancel: false }` розглядається як відсутність рішення (так само, як пропуск `cancel`), а не як перевизначення. -- `message_received`: використовуйте типізоване поле `threadId`, коли вам потрібна маршрутизація вхідної гілки/теми. Залишайте `metadata` для додаткових даних, специфічних для каналу. +- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник установлює його, обробники з нижчим пріоритетом пропускаються. +- `before_tool_call`: повернення `{ block: false }` трактується як відсутність рішення (те саме, що пропустити `block`), а не як перевизначення. +- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник установлює його, обробники з нижчим пріоритетом пропускаються. +- `before_install`: повернення `{ block: false }` трактується як відсутність рішення (те саме, що пропустити `block`), а не як перевизначення. +- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник заявляє dispatch, обробники з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються. +- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник установлює його, обробники з нижчим пріоритетом пропускаються. +- `message_sending`: повернення `{ cancel: false }` трактується як відсутність рішення (те саме, що пропустити `cancel`), а не як перевизначення. +- `message_received`: використовуйте типізоване поле `threadId`, коли потрібна вхідна маршрутизація гілки/теми. Залишайте `metadata` для специфічних для каналу додаткових даних. - `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж переходити до специфічних для каналу `metadata`. -- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, яким володіє Gateway, замість покладання на внутрішні хуки `gateway:startup`. -- `cron_changed`: спостерігайте за змінами життєвого циклу cron, яким володіє Gateway. Використовуйте `event.job?.state?.nextRunAtMs` і `ctx.getCron?.()` під час синхронізації зовнішніх планувальників пробудження, а OpenClaw залишайте джерелом істини для перевірок строків і виконання. +- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, яким володіє gateway, замість покладання на внутрішні hooks `gateway:startup`. +- `cron_changed`: спостерігайте за змінами життєвого циклу cron, яким володіє gateway. Використовуйте `event.job?.state?.nextRunAtMs` і `ctx.getCron?.()` під час синхронізації зовнішніх планувальників пробудження, а OpenClaw залишайте джерелом істини для перевірок строків і виконання. ### Поля об’єкта API -| Поле | Тип | Опис | -| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | Ідентифікатор плагіна | -| `api.name` | `string` | Відображувана назва | -| `api.version` | `string?` | Версія плагіна (необов’язково) | -| `api.description` | `string?` | Опис плагіна (необов’язково) | -| `api.source` | `string` | Шлях до джерела плагіна | -| `api.rootDir` | `string?` | Кореневий каталог плагіна (необов’язково) | -| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок середовища виконання в пам’яті, коли доступний) | -| `api.pluginConfig` | `Record` | Конфігурація, специфічна для плагіна, з `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Допоміжні засоби середовища виконання](/uk/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Логер з областю дії (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування перед повним входом | -| `api.resolvePath(input)` | `(string) => string` | Розв’язати шлях відносно кореня плагіна | +| Поле | Тип | Опис | +| ------------------------ | ------------------------- | ---------------------------------------------------------------------------------------------- | +| `api.id` | `string` | id Plugin | +| `api.name` | `string` | Відображувана назва | +| `api.version` | `string?` | Версія Plugin (необов’язково) | +| `api.description` | `string?` | Опис Plugin (необов’язково) | +| `api.source` | `string` | Шлях джерела Plugin | +| `api.rootDir` | `string?` | Кореневий каталог Plugin (необов’язково) | +| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок runtime в пам’яті, коли доступний) | +| `api.pluginConfig` | `Record` | Специфічна для Plugin конфігурація з `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Scoped logger (`debug`, `info`, `warn`, `error`) | +| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування до повного entry | +| `api.resolvePath(input)` | `(string) => string` | Resolve path відносно кореня Plugin | -## Внутрішня домовленість щодо модулів +## Конвенція внутрішніх модулів -У своєму плагіні використовуйте локальні barrel-файли для внутрішніх імпортів: +У межах вашого Plugin використовуйте локальні barrel-файли для внутрішніх імпортів: ``` my-plugin/ @@ -352,57 +355,56 @@ my-plugin/ ``` - Ніколи не імпортуйте власний плагін через `openclaw/plugin-sdk/` - з виробничого коду. Спрямовуйте внутрішні імпорти через `./api.ts` або - `./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт. + Ніколи не імпортуйте власний Plugin через `openclaw/plugin-sdk/` + з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або + `./runtime-api.ts`. Шлях SDK є лише зовнішнім контрактом. -Публічні поверхні вбудованого плагіна, завантажені через фасад (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` і подібні публічні вхідні файли), віддають перевагу -активному знімку конфігурації середовища виконання, коли OpenClaw уже працює. Якщо знімка -середовища виконання ще немає, вони повертаються до розв’язаної конфігурації на диску. -Фасади упакованих вбудованих плагінів слід завантажувати через фасадні завантажувачі -плагінів OpenClaw; прямі імпорти з `dist/extensions/...` обходять маніфест -і перевірки бічного середовища виконання, які упаковані встановлення використовують -для коду, яким володіє плагін. +Публічні поверхні bundled Plugin, завантажені через facade (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` і подібні публічні entry-файли), віддають перевагу +активному знімку runtime config, коли OpenClaw уже працює. Якщо знімка runtime +ще немає, вони повертаються до розв’язаної конфігурації на диску. +Упаковані facades bundled Plugin мають завантажуватися через facade loaders Plugin +OpenClaw; прямі імпорти з `dist/extensions/...` оминають маніфест +і перевірки runtime sidecar, які встановлення пакетів використовують для коду, яким володіє Plugin. -Плагіни провайдерів можуть відкривати вузький локальний для плагіна контрактний -barrel-файл, коли допоміжний засіб навмисно специфічний для провайдера й поки що -не належить до загального підшляху SDK. Вбудовані приклади: +Provider Plugin можуть відкривати вузький локальний для Plugin barrel контракту, коли +helper навмисно є специфічним для провайдера і ще не належить до загального підшляху SDK. +Bundled приклади: -- **Anthropic**: публічний шов `api.ts` / `contract-api.ts` для Claude - beta-header і потокових допоміжних засобів `service_tier`. -- **`@openclaw/openai-provider`**: `api.ts` експортує побудовники провайдерів, - допоміжні засоби типових моделей і побудовники провайдерів реального часу. -- **`@openclaw/openrouter-provider`**: `api.ts` експортує побудовник провайдера - разом із допоміжними засобами онбордингу/конфігурації. +- **Anthropic**: публічний seam `api.ts` / `contract-api.ts` для Claude + beta-header і helpers потоків `service_tier`. +- **`@openclaw/openai-provider`**: `api.ts` експортує provider builders, + helpers типової моделі та realtime provider builders. +- **`@openclaw/openrouter-provider`**: `api.ts` експортує provider builder + плюс helpers onboarding/config. - Виробничий код розширення також має уникати імпортів `openclaw/plugin-sdk/`. - Якщо допоміжний засіб справді спільний, просуньте його до нейтрального підшляху SDK, - як-от `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої - поверхні, орієнтованої на можливості, замість зв’язування двох плагінів між собою. + Production-коду Extension також слід уникати імпортів `openclaw/plugin-sdk/`. + Якщо helper справді спільний, підніміть його до нейтрального підшляху SDK, + такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або інша + поверхня, орієнтована на capability, замість зв’язування двох Plugin між собою. ## Пов’язане - Параметри `definePluginEntry` і `defineChannelPluginEntry`. + Опції `definePluginEntry` і `defineChannelPluginEntry`. - Повний довідник простору імен `api.runtime`. + Повна довідка простору імен `api.runtime`. Пакування, маніфести та схеми конфігурації. - Тестові утиліти та правила лінтингу. + Утиліти для тестування та правила lint. Міграція із застарілих поверхонь. - - Глибока архітектура та модель можливостей. + + Поглиблена архітектура та модель можливостей. diff --git a/docs/uk/tools/thinking.md b/docs/uk/tools/thinking.md index d36c81b66..055ed8688 100644 --- a/docs/uk/tools/thinking.md +++ b/docs/uk/tools/thinking.md @@ -1,13 +1,13 @@ --- read_when: - - Налаштування розбору директив мислення, швидкого режиму або докладного режиму чи їхніх значень за замовчуванням + - Налаштування парсингу або стандартних значень для мислення, швидкого режиму чи докладної директиви summary: Синтаксис директив для /think, /fast, /verbose, /trace і видимості міркувань title: Рівні мислення x-i18n: - generated_at: "2026-05-04T00:48:56Z" + generated_at: "2026-05-04T18:18:28Z" model: gpt-5.5 provider: openai - source_hash: 6fa1b0a2b5f7b93a706488c3ad39dfe08c08eed0bdd30880eb4c07d730ee4d4f + source_hash: fcd1cd76ca5d0b08656e0629df656ad8aa037201d8de68093b3e46eb0708f811 source_path: tools/thinking.md workflow: 16 --- @@ -20,124 +20,125 @@ x-i18n: - low → “think hard” - medium → “think harder” - high → “ultrathink” (максимальний бюджет) - - xhigh → “ultrathink+” (моделі GPT-5.2+ і Codex, а також effort Anthropic Claude Opus 4.7) - - adaptive → адаптивне мислення, кероване провайдером (підтримується для Claude 4.6 на Anthropic/Bedrock, Anthropic Claude Opus 4.7 і динамічного мислення Google Gemini) - - max → максимальне reasoning провайдера (Anthropic Claude Opus 4.7; Ollama відображає це на свій найвищий нативний effort `think`) - - `x-high`, `x_high`, `extra-high`, `extra high` і `extra_high` відображаються на `xhigh`. - - `highest` відображається на `high`. -- Примітки щодо провайдерів: - - Меню й засоби вибору мислення керуються профілем провайдера. Provider plugins оголошують точний набір рівнів для вибраної моделі, включно з мітками на кшталт бінарного `on`. - - `adaptive`, `xhigh` і `max` рекламуються лише для профілів провайдера/моделі, які їх підтримують. Введені директиви для непідтримуваних рівнів відхиляються з чинними параметрами цієї моделі. + - xhigh → “ultrathink+” (моделі GPT-5.2+ і Codex, а також Anthropic Claude Opus 4.7 effort) + - adaptive → адаптивне мислення, кероване провайдером (підтримується для Claude 4.6 в Anthropic/Bedrock, Anthropic Claude Opus 4.7 і Google Gemini dynamic thinking) + - max → максимальне міркування провайдера (Anthropic Claude Opus 4.7; Ollama зіставляє це зі своїм найвищим нативним рівнем `think`) + - `x-high`, `x_high`, `extra-high`, `extra high` і `extra_high` зіставляються з `xhigh`. + - `highest` зіставляється з `high`. +- Нотатки щодо провайдерів: + - Меню та вибір мислення керуються профілем провайдера. Provider plugins оголошують точний набір рівнів для вибраної моделі, зокрема мітки на кшталт бінарного `on`. + - `adaptive`, `xhigh` і `max` рекламуються лише для профілів провайдера/моделі, які їх підтримують. Типізовані директиви для непідтримуваних рівнів відхиляються з коректними параметрами для цієї моделі. - Наявні збережені непідтримувані рівні перепризначаються за рангом профілю провайдера. `adaptive` повертається до `medium` на неадаптивних моделях, а `xhigh` і `max` повертаються до найбільшого підтримуваного не-`off` рівня для вибраної моделі. - - Моделі Anthropic Claude 4.6 за замовчуванням використовують `adaptive`, якщо явний рівень мислення не задано. - - Anthropic Claude Opus 4.7 не використовує адаптивне мислення за замовчуванням. Його API effort за замовчуванням лишається у власності провайдера, якщо ви явно не задасте рівень мислення. - - Anthropic Claude Opus 4.7 відображає `/think xhigh` на адаптивне мислення плюс `output_config.effort: "xhigh"`, оскільки `/think` є директивою мислення, а `xhigh` є налаштуванням effort Opus 4.7. - - Anthropic Claude Opus 4.7 також надає `/think max`; це відображається на той самий шлях максимального effort, що належить провайдеру. - - Моделі DeepSeek V4 надають `/think xhigh|max`; обидва відображаються на DeepSeek `reasoning_effort: "max"`, тоді як нижчі не-`off` рівні відображаються на `high`. - - Моделі Ollama з підтримкою мислення надають `/think low|medium|high|max`; `max` відображається на нативний `think: "high"`, оскільки нативний API Ollama приймає рядки effort `low`, `medium` і `high`. - - Моделі OpenAI GPT відображають `/think` через підтримку effort у специфічному для моделі Responses API. `/think off` надсилає `reasoning.effort: "none"` лише тоді, коли цільова модель це підтримує; інакше OpenClaw пропускає вимкнене reasoning-навантаження замість надсилання непідтримуваного значення. - - Власні записи каталогу, сумісні з OpenAI, можуть увімкнути `/think xhigh`, задавши `models.providers..models[].compat.supportedReasoningEfforts` так, щоб він містив `"xhigh"`. Це використовує ті самі compat-метадані, що відображають вихідні OpenAI reasoning effort payloads, тож меню, перевірка сесії, CLI агента й `llm-task` узгоджуються з поведінкою транспорту. - - Застарілі налаштовані посилання OpenRouter Hunter Alpha пропускають ін’єкцію reasoning через проксі, оскільки цей виведений з експлуатації маршрут міг повертати текст фінальної відповіді через поля reasoning. - - Google Gemini відображає `/think adaptive` на динамічне мислення Gemini, що належить провайдеру. Запити Gemini 3 пропускають фіксований `thinkingLevel`, тоді як запити Gemini 2.5 надсилають `thinkingBudget: -1`; фіксовані рівні все одно відображаються на найближчий Gemini `thinkingLevel` або бюджет для цієї сім’ї моделей. - - MiniMax (`minimax/*`) на Anthropic-сумісному потоковому шляху за замовчуванням використовує `thinking: { type: "disabled" }`, якщо ви явно не задасте мислення в параметрах моделі або параметрах запиту. Це запобігає витоку дельт `reasoning_content` з ненативного формату потоку Anthropic від MiniMax. - - Z.AI (`zai/*`) підтримує лише бінарне мислення (`on`/`off`). Будь-який рівень, що не є `off`, вважається `on` (відображається на `low`). - - Moonshot (`moonshot/*`) відображає `/think off` на `thinking: { type: "disabled" }`, а будь-який рівень, що не є `off`, на `thinking: { type: "enabled" }`. Коли мислення ввімкнено, Moonshot приймає лише `tool_choice` `auto|none`; OpenClaw нормалізує несумісні значення до `auto`. + - Моделі Anthropic Claude 4.6 за замовчуванням використовують `adaptive`, коли явний рівень мислення не задано. + - Anthropic Claude Opus 4.7 не використовує адаптивне мислення за замовчуванням. Його типовий API effort лишається під контролем провайдера, якщо ви явно не задасте рівень мислення. + - Anthropic Claude Opus 4.7 зіставляє `/think xhigh` з адаптивним мисленням плюс `output_config.effort: "xhigh"`, тому що `/think` є директивою мислення, а `xhigh` є налаштуванням effort для Opus 4.7. + - Anthropic Claude Opus 4.7 також надає `/think max`; це зіставляється з тим самим шляхом максимального effort, керованим провайдером. + - Моделі DeepSeek V4 надають `/think xhigh|max`; обидва зіставляються з DeepSeek `reasoning_effort: "max"`, тоді як нижчі не-`off` рівні зіставляються з `high`. + - Моделі Ollama з підтримкою мислення надають `/think low|medium|high|max`; `max` зіставляється з нативним `think: "high"`, тому що нативний API Ollama приймає рядки effort `low`, `medium` і `high`. + - Моделі OpenAI GPT зіставляють `/think` через підтримку effort у Responses API, специфічну для моделі. `/think off` надсилає `reasoning.effort: "none"` лише тоді, коли цільова модель це підтримує; інакше OpenClaw пропускає вимкнене корисне навантаження міркування замість надсилання непідтримуваного значення. + - Користувацькі сумісні з OpenAI записи каталогу можуть увімкнути підтримку `/think xhigh`, задавши `models.providers..models[].compat.supportedReasoningEfforts` так, щоб він містив `"xhigh"`. Це використовує ті самі метадані сумісності, які зіставляють вихідні корисні навантаження OpenAI reasoning effort, тож меню, валідація сеансу, agent CLI і `llm-task` узгоджуються з поведінкою транспорту. + - Застарілі налаштовані посилання OpenRouter Hunter Alpha пропускають інʼєкцію проксі-міркування, тому що цей вилучений маршрут міг повертати текст фінальної відповіді через поля міркування. + - Google Gemini зіставляє `/think adaptive` з керованим провайдером dynamic thinking Gemini. Запити Gemini 3 пропускають фіксований `thinkingLevel`, тоді як запити Gemini 2.5 надсилають `thinkingBudget: -1`; фіксовані рівні й далі зіставляються з найближчим Gemini `thinkingLevel` або бюджетом для цієї сімʼї моделей. + - MiniMax (`minimax/*`) на Anthropic-сумісному потоковому шляху за замовчуванням використовує `thinking: { type: "disabled" }`, якщо ви явно не задасте мислення в параметрах моделі або параметрах запиту. Це запобігає витоку дельт `reasoning_content` із ненативного потокового формату Anthropic від MiniMax. + - Z.AI (`zai/*`) підтримує лише бінарне мислення (`on`/`off`). Будь-який не-`off` рівень вважається `on` (зіставляється з `low`). + - Moonshot (`moonshot/*`) зіставляє `/think off` з `thinking: { type: "disabled" }`, а будь-який не-`off` рівень з `thinking: { type: "enabled" }`. Коли мислення увімкнене, Moonshot приймає лише `tool_choice` `auto|none`; OpenClaw нормалізує несумісні значення до `auto`. -## Порядок вирішення +## Порядок визначення 1. Вбудована директива в повідомленні (застосовується лише до цього повідомлення). -2. Перевизначення сесії (задається надсиланням повідомлення, що містить лише директиву). -3. Стандартне значення для окремого агента (`agents.list[].thinkingDefault` у конфігурації). -4. Глобальне стандартне значення (`agents.defaults.thinkingDefault` у конфігурації). -5. Резервний варіант: стандартне значення, оголошене провайдером, коли доступне; інакше моделі з підтримкою reasoning вирішуються в `medium` або найближчий підтримуваний не-`off` рівень для цієї моделі, а моделі без reasoning лишаються `off`. +2. Перевизначення сеансу (задається надсиланням повідомлення лише з директивою). +3. Типове значення для агента (`agents.list[].thinkingDefault` у конфігурації). +4. Глобальне типове значення (`agents.defaults.thinkingDefault` у конфігурації). +5. Резервний варіант: оголошене провайдером типове значення, якщо доступне; інакше моделі з підтримкою міркування визначаються як `medium` або найближчий підтримуваний не-`off` рівень для цієї моделі, а моделі без міркування лишаються `off`. -## Задання стандартного значення сесії +## Налаштування типового значення сеансу - Надішліть повідомлення, яке містить **лише** директиву (пробіли дозволені), наприклад `/think:medium` або `/t high`. -- Це закріплюється для поточної сесії (за замовчуванням для кожного відправника); очищується через `/think:off` або скидання сесії через бездіяльність. -- Надсилається відповідь-підтвердження (`Thinking level set to high.` / `Thinking disabled.`). Якщо рівень недійсний (наприклад, `/thinking big`), команда відхиляється з підказкою, а стан сесії лишається без змін. +- Це закріплюється для поточного сеансу (типово для кожного відправника); очищується через `/think:off` або скидання після простою сеансу. +- Надсилається відповідь-підтвердження (`Thinking level set to high.` / `Thinking disabled.`). Якщо рівень некоректний (наприклад, `/thinking big`), команда відхиляється з підказкою, а стан сеансу лишається незмінним. - Надішліть `/think` (або `/think:`) без аргументу, щоб побачити поточний рівень мислення. -## Застосування агентом +## Застосування за агентом -- **Вбудований Pi**: вирішений рівень передається до середовища виконання агента Pi в межах процесу. +- **Вбудований Pi**: визначений рівень передається в рантайм агента Pi в межах процесу. +- **Бекенд Claude CLI**: не-`off` рівні передаються в Claude Code як `--effort` під час використання `claude-cli`; див. [CLI-бекенди](/uk/gateway/cli-backends). ## Швидкий режим (/fast) - Рівні: `on|off`. -- Повідомлення лише з директивою перемикає перевизначення швидкого режиму сесії та відповідає `Fast mode enabled.` / `Fast mode disabled.`. +- Повідомлення лише з директивою перемикає перевизначення швидкого режиму сеансу й відповідає `Fast mode enabled.` / `Fast mode disabled.`. - Надішліть `/fast` (або `/fast status`) без режиму, щоб побачити поточний ефективний стан швидкого режиму. -- OpenClaw вирішує швидкий режим у такому порядку: - 1. Вбудований/лише директивний `/fast on|off` - 2. Перевизначення сесії - 3. Стандартне значення для окремого агента (`agents.list[].fastModeDefault`) - 4. Конфігурація для окремої моделі: `agents.defaults.models["/"].params.fastMode` +- OpenClaw визначає швидкий режим у такому порядку: + 1. Вбудована директива або повідомлення лише з директивою `/fast on|off` + 2. Перевизначення сеансу + 3. Типове значення для агента (`agents.list[].fastModeDefault`) + 4. Конфігурація для моделі: `agents.defaults.models["/"].params.fastMode` 5. Резервний варіант: `off` -- Для `openai/*` швидкий режим відображається на пріоритетну обробку OpenAI шляхом надсилання `service_tier=priority` у підтримуваних запитах Responses. +- Для `openai/*` швидкий режим зіставляється з пріоритетною обробкою OpenAI через надсилання `service_tier=priority` у підтримуваних запитах Responses. - Для `openai-codex/*` швидкий режим надсилає той самий прапорець `service_tier=priority` у Codex Responses. OpenClaw зберігає один спільний перемикач `/fast` для обох шляхів автентифікації. -- Для прямих публічних запитів `anthropic/*`, включно з OAuth-автентифікованим трафіком, надісланим до `api.anthropic.com`, швидкий режим відображається на рівні сервісу Anthropic: `/fast on` задає `service_tier=auto`, `/fast off` задає `service_tier=standard_only`. +- Для прямих публічних запитів `anthropic/*`, зокрема OAuth-автентифікованого трафіку, надісланого до `api.anthropic.com`, швидкий режим зіставляється з рівнями сервісу Anthropic: `/fast on` задає `service_tier=auto`, `/fast off` задає `service_tier=standard_only`. - Для `minimax/*` на Anthropic-сумісному шляху `/fast on` (або `params.fastMode: true`) переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. -- Явні параметри моделі Anthropic `serviceTier` / `service_tier` перевизначають стандартне значення швидкого режиму, коли задано обидва. OpenClaw все одно пропускає ін’єкцію рівня сервісу Anthropic для не-Anthropic базових URL проксі. -- `/status` показує `Fast` лише коли швидкий режим увімкнено. +- Явні параметри моделі Anthropic `serviceTier` / `service_tier` перевизначають типове значення швидкого режиму, коли задано обидва. OpenClaw і далі пропускає інʼєкцію рівня сервісу Anthropic для базових URL проксі, які не є Anthropic. +- `/status` показує `Fast` лише тоді, коли швидкий режим увімкнено. -## Докладні директиви (/verbose або /v) +## Директиви докладності (/verbose або /v) -- Рівні: `on` (мінімальний) | `full` | `off` (за замовчуванням). -- Повідомлення лише з директивою перемикає докладність сесії та відповідає `Verbose logging enabled.` / `Verbose logging disabled.`; недійсні рівні повертають підказку без зміни стану. -- `/verbose off` зберігає явне перевизначення сесії; очистьте його через UI Sessions, вибравши `inherit`. -- Вбудована директива впливає лише на це повідомлення; інакше застосовуються стандартні значення сесії/глобальні стандартні значення. +- Рівні: `on` (мінімальний) | `full` | `off` (типово). +- Повідомлення лише з директивою перемикає докладність сеансу й відповідає `Verbose logging enabled.` / `Verbose logging disabled.`; некоректні рівні повертають підказку без зміни стану. +- `/verbose off` зберігає явне перевизначення сеансу; очистьте його через UI сеансів, вибравши `inherit`. +- Вбудована директива впливає лише на це повідомлення; інакше застосовуються типові значення сеансу/глобальні типові значення. - Надішліть `/verbose` (або `/verbose:`) без аргументу, щоб побачити поточний рівень докладності. -- Коли докладність увімкнена, агенти, що видають структуровані результати інструментів (Pi, інші JSON-агенти), надсилають кожен виклик інструмента назад як окреме повідомлення лише з метаданими, з префіксом ` : `, коли доступно. Ці підсумки інструментів надсилаються одразу після запуску кожного інструмента (окремі бульбашки), а не як потокові дельти. -- Підсумки помилок інструментів лишаються видимими у звичайному режимі, але необроблені суфікси деталей помилок приховані, якщо докладність не є `on` або `full`. -- Коли докладність має значення `full`, виходи інструментів також пересилаються після завершення (окрема бульбашка, обрізана до безпечної довжини). Якщо перемкнути `/verbose on|full|off`, поки виконання триває, наступні бульбашки інструментів враховують нове налаштування. -- `agents.defaults.toolProgressDetail` керує формою підсумків інструментів `/verbose` і рядків інструментів у чернетці прогресу. Використовуйте `"explain"` (за замовчуванням) для компактних людських міток, як-от `🛠️ Exec: checking JS syntax`; використовуйте `"raw"`, коли також потрібно додати необроблену команду/деталі для налагодження. `agents.list[].toolProgressDetail` для окремого агента перевизначає стандартне значення. +- Коли докладність увімкнена, агенти, що виводять структуровані результати інструментів (Pi, інші JSON-агенти), надсилають кожен виклик інструмента назад як окреме повідомлення лише з метаданими, з префіксом ` : `, коли доступно. Ці підсумки інструментів надсилаються одразу після запуску кожного інструмента (окремі бульбашки), а не як потокові дельти. +- Підсумки помилок інструментів лишаються видимими у звичайному режимі, але суфікси з необробленими деталями помилок приховані, якщо докладність не `on` або `full`. +- Коли докладність дорівнює `full`, результати інструментів також пересилаються після завершення (окрема бульбашка, обрізана до безпечної довжини). Якщо перемкнути `/verbose on|full|off`, поки виконання триває, наступні бульбашки інструментів врахують нове налаштування. +- `agents.defaults.toolProgressDetail` керує формою підсумків інструментів `/verbose` і рядків інструментів у чернетках прогресу. Використовуйте `"explain"` (типово) для компактних зрозумілих міток на кшталт `🛠️ Exec: checking JS syntax`; використовуйте `"raw"`, коли також потрібно додавати необроблену команду/деталі для налагодження. `agents.list[].toolProgressDetail` для окремого агента перевизначає типове значення. - `explain`: `🛠️ Exec: check JS syntax for /tmp/app.js` - `raw`: `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js` ## Директиви трасування Plugin (/trace) -- Рівні: `on` | `off` (за замовчуванням). -- Повідомлення лише з директивою перемикає вивід трасування Plugin у сесії та відповідає `Plugin trace enabled.` / `Plugin trace disabled.`. -- Вбудована директива впливає лише на це повідомлення; інакше застосовуються стандартні значення сесії/глобальні стандартні значення. +- Рівні: `on` | `off` (типово). +- Повідомлення лише з директивою перемикає вивід трасування Plugin у сеансі й відповідає `Plugin trace enabled.` / `Plugin trace disabled.`. +- Вбудована директива впливає лише на це повідомлення; інакше застосовуються типові значення сеансу/глобальні типові значення. - Надішліть `/trace` (або `/trace:`) без аргументу, щоб побачити поточний рівень трасування. -- `/trace` вужчий за `/verbose`: він відкриває лише рядки трасування/налагодження, що належать Plugin, як-от налагоджувальні підсумки Active Memory. -- Рядки трасування можуть з’являтися в `/status` і як подальше діагностичне повідомлення після звичайної відповіді асистента. +- `/trace` вужчий за `/verbose`: він показує лише рядки трасування/налагодження, що належать Plugin, наприклад підсумки налагодження Active Memory. +- Рядки трасування можуть зʼявлятися в `/status` і як подальше діагностичне повідомлення після звичайної відповіді асистента. -## Видимість reasoning (/reasoning) +## Видимість міркування (/reasoning) - Рівні: `on|off|stream`. - Повідомлення лише з директивою перемикає, чи показуються блоки мислення у відповідях. -- Коли ввімкнено, reasoning надсилається як **окреме повідомлення** з префіксом `Reasoning:`. -- `stream` (лише Telegram): потоково передає reasoning у бульбашку чернетки Telegram, поки генерується відповідь, а потім надсилає фінальну відповідь без reasoning. +- Коли увімкнено, міркування надсилається як **окреме повідомлення** з префіксом `Reasoning:`. +- `stream` (лише Telegram): транслює міркування в чернеткову бульбашку Telegram, поки генерується відповідь, а потім надсилає фінальну відповідь без міркування. - Псевдонім: `/reason`. -- Надішліть `/reasoning` (або `/reasoning:`) без аргументу, щоб побачити поточний рівень reasoning. -- Порядок вирішення: вбудована директива, потім перевизначення сесії, потім стандартне значення для окремого агента (`agents.list[].reasoningDefault`), потім резервний варіант (`off`). +- Надішліть `/reasoning` (або `/reasoning:`) без аргументу, щоб побачити поточний рівень міркування. +- Порядок визначення: вбудована директива, потім перевизначення сеансу, потім типове значення для агента (`agents.list[].reasoningDefault`), потім резервний варіант (`off`). -Некоректні теги reasoning локальної моделі обробляються консервативно. Закриті блоки `...` лишаються прихованими у звичайних відповідях, а незакрите reasoning після вже видимого тексту також приховується. Якщо відповідь повністю обгорнута в один незакритий початковий тег і інакше була б доставлена як порожній текст, OpenClaw видаляє некоректний початковий тег і доставляє решту тексту. +Некоректні теги міркування локальних моделей обробляються консервативно. Закриті блоки `...` лишаються прихованими у звичайних відповідях, а незакрите міркування після вже видимого тексту також приховується. Якщо відповідь повністю обгорнута в один незакритий початковий тег і інакше була б доставлена як порожній текст, OpenClaw видаляє некоректний початковий тег і доставляє решту тексту. -## Пов’язане +## Повʼязане -- Документація підвищеного режиму розміщена в [Підвищений режим](/uk/tools/elevated). +- Документація режиму підвищених прав міститься в [Режим підвищених прав](/uk/tools/elevated). ## Heartbeat -- Тіло зонду Heartbeat є налаштованим запитом Heartbeat (за замовчуванням: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Вбудовані директиви в повідомленні Heartbeat застосовуються як зазвичай (але уникайте зміни стандартних значень сесії з Heartbeat). -- Доставка Heartbeat за замовчуванням обмежується лише фінальним payload. Щоб також надсилати окреме повідомлення `Reasoning:` (коли доступне), задайте `agents.defaults.heartbeat.includeReasoning: true` або для окремого агента `agents.list[].heartbeat.includeReasoning: true`. +- Тіло зонду Heartbeat є налаштованим запитом heartbeat (типово: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Вбудовані директиви в повідомленні heartbeat застосовуються як зазвичай (але уникайте зміни типових значень сеансу з heartbeat). +- Доставка Heartbeat за замовчуванням обмежується лише фінальним корисним навантаженням. Щоб також надсилати окреме повідомлення `Reasoning:` (коли доступно), задайте `agents.defaults.heartbeat.includeReasoning: true` або для окремого агента `agents.list[].heartbeat.includeReasoning: true`. ## UI вебчату -- Селектор мислення у вебчаті віддзеркалює збережений рівень сесії зі сховища/конфігурації вхідної сесії під час завантаження сторінки. -- Вибір іншого рівня негайно записує перевизначення сесії через `sessions.patch`; він не чекає наступного надсилання й не є одноразовим перевизначенням `thinkingOnce`. -- Перший параметр завжди `Default ()`, де вирішене стандартне значення походить із профілю мислення провайдера активної моделі сесії плюс та сама резервна логіка, яку використовують `/status` і `session_status`. -- Засіб вибору використовує `thinkingLevels`, повернуті рядком/стандартними значеннями сесії Gateway, а `thinkingOptions` зберігається як застарілий список міток. UI браузера не зберігає власного списку regex провайдерів; Plugins володіють наборами рівнів для конкретних моделей. -- `/think:` все ще працює й оновлює той самий збережений рівень сесії, тому директиви чату й засіб вибору лишаються синхронізованими. +- Селектор мислення вебчату віддзеркалює збережений рівень сеансу зі сховища/конфігурації вхідного сеансу під час завантаження сторінки. +- Вибір іншого рівня негайно записує перевизначення сеансу через `sessions.patch`; він не чекає наступного надсилання й не є одноразовим перевизначенням `thinkingOnce`. +- Перший параметр завжди `Default ()`, де визначене типове значення береться з профілю мислення провайдера активної моделі сеансу плюс та сама резервна логіка, яку використовують `/status` і `session_status`. +- Селектор використовує `thinkingLevels`, повернені рядком/типовими значеннями сеансу Gateway, а `thinkingOptions` збережено як застарілий список міток. UI браузера не зберігає власний список регулярних виразів провайдерів; plugins володіють наборами рівнів, специфічними для моделей. +- `/think:` і далі працює та оновлює той самий збережений рівень сеансу, тож директиви чату й селектор лишаються синхронізованими. ## Профілі провайдерів -- Plugin-и постачальника можуть надавати `resolveThinkingProfile(ctx)`, щоб визначати підтримувані моделлю рівні та стандартне значення. -- Plugin-и постачальника, які проксіюють моделі Claude, мають повторно використовувати `resolveClaudeThinkingProfile(modelId)` з `openclaw/plugin-sdk/provider-model-shared`, щоб прямі каталоги Anthropic і проксі-каталоги залишалися узгодженими. -- Кожен рівень профілю має збережений канонічний `id` (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` або `max`) і може містити відображувану `label`. Бінарні постачальники використовують `{ id: "low", label: "on" }`. -- Інструментальні Plugin-и, яким потрібно перевіряти явне перевизначення мислення, мають використовувати `api.runtime.agent.resolveThinkingPolicy({ provider, model })` разом із `api.runtime.agent.normalizeThinkingLevel(...)`; їм не слід зберігати власні списки рівнів постачальників/моделей. -- Інструментальні Plugin-и з доступом до налаштованих метаданих користувацьких моделей можуть передавати `catalog` у `resolveThinkingPolicy`, щоб явні увімкнення `compat.supportedReasoningEfforts` враховувалися у перевірці на боці Plugin-а. +- Plugin провайдерів можуть надавати `resolveThinkingProfile(ctx)`, щоб визначати підтримувані моделлю рівні та значення за замовчуванням. +- Plugin провайдерів, які проксіюють моделі Claude, мають повторно використовувати `resolveClaudeThinkingProfile(modelId)` з `openclaw/plugin-sdk/provider-model-shared`, щоб прямі каталоги Anthropic і проксі-каталоги залишалися узгодженими. +- Кожен рівень профілю має збережений канонічний `id` (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` або `max`) і може містити відображуваний `label`. Бінарні провайдери використовують `{ id: "low", label: "on" }`. +- Tool Plugin, яким потрібно перевіряти явне перевизначення мислення, мають використовувати `api.runtime.agent.resolveThinkingPolicy({ provider, model })` разом із `api.runtime.agent.normalizeThinkingLevel(...)`; вони не повинні зберігати власні списки рівнів провайдера/моделі. +- Tool Plugin із доступом до налаштованих метаданих користувацької моделі можуть передавати `catalog` у `resolveThinkingPolicy`, щоб opt-in `compat.supportedReasoningEfforts` відображалися у валідації на боці Plugin. - Опубліковані застарілі хуки (`supportsXHighThinking`, `isBinaryThinking` і `resolveDefaultThinkingLevel`) залишаються адаптерами сумісності, але нові користувацькі набори рівнів мають використовувати `resolveThinkingProfile`. -- Рядки/стандартні значення Gateway надають `thinkingLevels`, `thinkingOptions` і `thinkingDefault`, щоб клієнти ACP/чату відображали ті самі ідентифікатори та мітки профілів, які використовує перевірка під час виконання. +- Рядки/значення за замовчуванням Gateway надають `thinkingLevels`, `thinkingOptions` і `thinkingDefault`, щоб клієнти ACP/чату відображали ті самі ідентифікатори й мітки профілю, які використовує валідація під час виконання.