diff --git a/docs/uk/concepts/model-providers.md b/docs/uk/concepts/model-providers.md index f39dc7d6f..e52918d8b 100644 --- a/docs/uk/concepts/model-providers.md +++ b/docs/uk/concepts/model-providers.md @@ -1,40 +1,40 @@ --- read_when: - Вам потрібен довідник із налаштування моделей для кожного постачальника окремо - - Вам потрібні приклади конфігурацій або команд онбордингу CLI для постачальників моделей + - Вам потрібні приклади конфігурацій або команди онбордингу CLI для постачальників моделей summary: Огляд постачальників моделей із прикладами конфігурацій + потоками CLI title: Постачальники моделей x-i18n: - generated_at: "2026-04-10T20:23:44Z" + generated_at: "2026-04-10T20:29:02Z" model: gpt-5.4 provider: openai - source_hash: f3d50795107077c7065773b5e545fae04b97f1d932a650d577b325d93bf25192 + source_hash: fc970eacc8babdd43e3e83f164846b82d1289f8335732d2135dc9f41c560489e source_path: concepts/model-providers.md workflow: 15 --- # Постачальники моделей -На цій сторінці описано **постачальників LLM/моделей** (а не канали чату, як-от WhatsApp/Telegram). +Ця сторінка охоплює **постачальників LLM/моделей** (а не канали чату, як-от WhatsApp/Telegram). Правила вибору моделей див. у [/concepts/models](/uk/concepts/models). ## Швидкі правила -- Посилання на моделі використовують формат `provider/model` (приклад: `opencode/claude-opus-4-6`). -- Якщо ви встановите `agents.defaults.models`, це стане allowlist. +- Посилання на моделі використовують `provider/model` (приклад: `opencode/claude-opus-4-6`). +- Якщо ви задаєте `agents.defaults.models`, це стає списком дозволених моделей. - Допоміжні команди CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. -- Резервні правила середовища виконання, перевірки cooldown і збереження session-override +- Резервні правила середовища виконання, перевірки cooldown і збереження session override задокументовано в [/concepts/model-failover](/uk/concepts/model-failover). -- `models.providers.*.models[].contextWindow` — це нативні метадані моделі; +- `models.providers.*.models[].contextWindow` — це власні метадані моделі; `models.providers.*.models[].contextTokens` — це фактичне обмеження середовища виконання. - Плагіни постачальників можуть впроваджувати каталоги моделей через `registerProvider({ catalog })`; OpenClaw об’єднує цей вивід у `models.providers` перед записом `models.json`. - Маніфести постачальників можуть оголошувати `providerAuthEnvVars` і - `providerAuthAliases`, щоб загальні перевірки автентифікації на основі env - і варіанти постачальників не потребували завантаження середовища виконання плагіна. Решта основної мапи env-змінних тепер - використовується лише для неплагінних/основних постачальників і кількох випадків - із загальним пріоритетом, таких як онбординг Anthropic із пріоритетом API-ключа. + `providerAuthAliases`, щоб загальні перевірки автентифікації на основі env і варіанти постачальників + не потребували завантаження середовища виконання плагіна. Решта мапи env-змінних у core тепер + призначена лише для постачальників core/без плагінів і кількох випадків загального пріоритету, + як-от онбординг Anthropic із пріоритетом API-ключа. - Плагіни постачальників також можуть володіти поведінкою середовища виконання постачальника через `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, @@ -53,221 +53,224 @@ x-i18n: `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, і `onModelSelected`. -- Примітка: runtime `capabilities` постачальника — це спільні метадані виконувача (сімейство постачальника, особливості стенограми/інструментів, підказки щодо транспорту/кешу). Це не те +- Примітка: `capabilities` середовища виконання постачальника — це спільні метадані раннера (сімейство постачальника, особливості транскрипту/інструментів, підказки для транспорту/кешу). Це не те саме, що [публічна модель можливостей](/uk/plugins/architecture#public-capability-model), яка описує, що реєструє плагін (текстовий inference, мовлення тощо). -- Вбудований постачальник `codex` працює в парі з вбудованим агентним середовищем Codex. - Використовуйте `codex/gpt-*`, коли вам потрібні керований Codex вхід, виявлення моделей, нативне - відновлення thread і виконання app-server. Звичайні посилання `openai/gpt-*` і надалі - використовують постачальника OpenAI та стандартний транспорт постачальників OpenClaw. +- Вбудований постачальник `codex` поєднано з вбудованою обв’язкою агента Codex. + Використовуйте `codex/gpt-*`, якщо вам потрібні вхід Codex, виявлення моделей, власне + відновлення thread і виконання на app server. Звичайні посилання `openai/gpt-*` і надалі + використовують постачальника OpenAI та стандартний транспорт постачальника OpenClaw. + У розгортаннях лише з Codex можна вимкнути автоматичний резервний перехід на PI за допомогою + `agents.defaults.embeddedHarness.fallback: "none"`; див. + [Плагіни Agent Harness](/uk/plugins/sdk-agent-harness#disable-pi-fallback). -## Поведінка постачальників, якою володіє плагін +## Поведінка постачальника, що належить плагіну -Плагіни постачальників тепер можуть володіти більшістю специфічної для постачальника логіки, тоді як OpenClaw зберігає +Тепер плагіни постачальників можуть володіти більшістю логіки, специфічної для постачальника, тоді як OpenClaw зберігає загальний цикл inference. -Типовий поділ: +Типовий розподіл: - `auth[].run` / `auth[].runNonInteractive`: постачальник володіє потоками онбордингу/входу для `openclaw onboard`, `openclaw models auth` і безголового налаштування - `wizard.setup` / `wizard.modelPicker`: постачальник володіє мітками вибору автентифікації, - застарілими псевдонімами, підказками allowlist для онбордингу та записами + застарілими псевдонімами, підказками для allowlist під час онбордингу та записами налаштування в засобах вибору онбордингу/моделей - `catalog`: постачальник з’являється в `models.providers` - `normalizeModelId`: постачальник нормалізує застарілі/preview ідентифікатори моделей перед пошуком або канонізацією - `normalizeTransport`: постачальник нормалізує `api` / `baseUrl` сімейства транспорту перед загальним складанням моделі; OpenClaw спочатку перевіряє відповідного постачальника, - потім інші плагіни постачальників із підтримкою хуків, доки один із них справді не змінить + потім інші плагіни постачальників із підтримкою hook, доки один із них справді не змінить транспорт - `normalizeConfig`: постачальник нормалізує конфігурацію `models.providers.` перед використанням у середовищі виконання; OpenClaw спочатку перевіряє відповідного постачальника, потім інші - плагіни постачальників із підтримкою хуків, доки один із них справді не змінить конфігурацію. Якщо жоден - хук постачальника не переписує конфігурацію, вбудовані допоміжні засоби сімейства Google все одно + плагіни постачальників із підтримкою hook, доки один із них справді не змінить конфігурацію. Якщо жоден + hook постачальника не переписує конфігурацію, вбудовані допоміжні засоби сімейства Google все одно нормалізують підтримувані записи постачальників Google. -- `applyNativeStreamingUsageCompat`: постачальник застосовує переписування сумісності native streaming-usage на основі endpoint для конфігурованих постачальників -- `resolveConfigApiKey`: постачальник визначає автентифікацію маркерів env для конфігурованих постачальників - без примусового повного завантаження runtime-автентифікації. `amazon-bedrock` також має - тут вбудований розв’язувач маркерів AWS env, хоча runtime-автентифікація Bedrock використовує +- `applyNativeStreamingUsageCompat`: постачальник застосовує переписування сумісності native streaming-usage на основі endpoint для постачальників конфігурації +- `resolveConfigApiKey`: постачальник визначає автентифікацію з env-marker для постачальників конфігурації + без примусового повного завантаження автентифікації середовища виконання. `amazon-bedrock` також має + тут вбудований резолвер AWS env-marker, хоча автентифікація середовища виконання Bedrock використовує стандартний ланцюжок AWS SDK. - `resolveSyntheticAuth`: постачальник може надавати доступність локальної/self-hosted або іншої - автентифікації на основі конфігурації без збереження відкритих секретів -- `shouldDeferSyntheticProfileAuth`: постачальник може позначати збережені synthetic profile - placeholders як нижчі за пріоритетом, ніж автентифікація на основі env/конфігурації + автентифікації на основі конфігурації без збереження секретів у відкритому вигляді +- `shouldDeferSyntheticProfileAuth`: постачальник може позначати збережені синтетичні заповнювачі профілю + як такі, що мають нижчий пріоритет, ніж автентифікація на основі env/конфігурації - `resolveDynamicModel`: постачальник приймає ідентифікатори моделей, яких ще немає в локальному статичному каталозі -- `prepareDynamicModel`: постачальнику потрібне оновлення метаданих перед повторною спробою +- `prepareDynamicModel`: постачальнику потрібно оновити метадані перед повторною спробою динамічного визначення -- `normalizeResolvedModel`: постачальнику потрібні переписування транспорту або base URL -- `contributeResolvedModelCompat`: постачальник додає прапори сумісності для своїх - вендорських моделей, навіть якщо вони надходять через інший сумісний транспорт -- `capabilities`: постачальник публікує особливості стенограми/інструментів/сімейства постачальника -- `normalizeToolSchemas`: постачальник очищає схеми інструментів перед тим, як вбудований - виконувач їх побачить +- `normalizeResolvedModel`: постачальнику потрібні переписування транспорту або базового URL +- `contributeResolvedModelCompat`: постачальник додає прапорці сумісності для своїх + моделей постачальника, навіть коли вони надходять через інший сумісний транспорт +- `capabilities`: постачальник публікує особливості транскрипту/інструментів/сімейства постачальника +- `normalizeToolSchemas`: постачальник очищує схеми інструментів перед тим, як вбудований + раннер їх побачить - `inspectToolSchemas`: постачальник показує попередження про схеми, специфічні для транспорту, після нормалізації -- `resolveReasoningOutputMode`: постачальник вибирає нативні або теговані - контракти виводу reasoning -- `prepareExtraParams`: постачальник задає типові або нормалізує параметри запиту для кожної моделі -- `createStreamFn`: постачальник замінює звичайний шлях stream повністю +- `resolveReasoningOutputMode`: постачальник вибирає між native і tagged + контрактами виводу reasoning +- `prepareExtraParams`: постачальник задає типові значення або нормалізує параметри запиту для кожної моделі +- `createStreamFn`: постачальник замінює звичайний шлях потоку повністю користувацьким транспортом -- `wrapStreamFn`: постачальник застосовує обгортки сумісності для заголовків/тіла запиту/моделі -- `resolveTransportTurnState`: постачальник надає нативні транспортні - заголовки або метадані для кожного ходу -- `resolveWebSocketSessionPolicy`: постачальник надає нативні заголовки сесії WebSocket - або політику cool-down сесії +- `wrapStreamFn`: постачальник застосовує обгортки сумісності для заголовків/тіла/моделі запиту +- `resolveTransportTurnState`: постачальник надає власні заголовки + або метадані транспорту для кожного ходу +- `resolveWebSocketSessionPolicy`: постачальник надає власні заголовки сеансу WebSocket + або політику cool-down для сеансу - `createEmbeddingProvider`: постачальник володіє поведінкою memory embedding, коли вона - належить плагіну постачальника, а не основному комутатору embedding -- `formatApiKey`: постачальник форматує збережені профілі автентифікації у runtime - рядок `apiKey`, очікуваний транспортом -- `refreshOAuth`: постачальник володіє оновленням OAuth, коли спільних оновлювачів `pi-ai` + має належати плагіну постачальника, а не основному switchboard embedding +- `formatApiKey`: постачальник форматує збережені профілі автентифікації у + рядок `apiKey`, якого очікує транспорт у середовищі виконання +- `refreshOAuth`: постачальник володіє оновленням OAuth, коли спільних засобів оновлення `pi-ai` недостатньо -- `buildAuthDoctorHint`: постачальник додає рекомендації з виправлення, коли оновлення OAuth +- `buildAuthDoctorHint`: постачальник додає підказку з відновлення, коли оновлення OAuth не вдається - `matchesContextOverflowError`: постачальник розпізнає специфічні для постачальника - помилки переповнення вікна контексту, які загальні евристики пропустили б -- `classifyFailoverReason`: постачальник зіставляє специфічні для постачальника сирі транспортні/API - помилки з причинами failover, такими як rate limit або overload -- `isCacheTtlEligible`: постачальник визначає, які upstream ідентифікатори моделей підтримують prompt-cache TTL + помилки переповнення context-window, які загальні евристики могли б пропустити +- `classifyFailoverReason`: постачальник зіставляє специфічні для постачальника необроблені помилки транспорту/API + з причинами failover, як-от rate limit або overload +- `isCacheTtlEligible`: постачальник визначає, які upstream ідентифікатори моделей підтримують TTL кешу підказок - `buildMissingAuthMessage`: постачальник замінює загальну помилку сховища автентифікації на специфічну для постачальника підказку з відновлення -- `suppressBuiltInModel`: постачальник приховує застарілі upstream рядки та може повертати - помилку, що належить вендору, для прямих збоїв визначення -- `augmentModelCatalog`: постачальник додає synthetic/final рядки каталогу після +- `suppressBuiltInModel`: постачальник приховує застарілі upstream-рядки та може повертати + помилку, що належить постачальнику, для прямих збоїв визначення +- `augmentModelCatalog`: постачальник додає синтетичні/фінальні рядки каталогу після виявлення та об’єднання конфігурації -- `isBinaryThinking`: постачальник володіє UX для бінарного вмикання/вимикання thinking -- `supportsXHighThinking`: постачальник додає вибраним моделям підтримку `xhigh` +- `isBinaryThinking`: постачальник володіє UX бінарного ввімкнення/вимкнення thinking +- `supportsXHighThinking`: постачальник вмикає `xhigh` для вибраних моделей - `resolveDefaultThinkingLevel`: постачальник володіє типовою політикою `/think` для сімейства моделей - `applyConfigDefaults`: постачальник застосовує глобальні типові значення, специфічні для постачальника, - під час матеріалізації конфігурації на основі режиму автентифікації, env або сімейства моделей + під час матеріалізації конфігурації залежно від режиму автентифікації, env або сімейства моделей - `isModernModelRef`: постачальник володіє зіставленням бажаних моделей для live/smoke - `prepareRuntimeAuth`: постачальник перетворює налаштовані облікові дані на короткоживучий - runtime-токен -- `resolveUsageAuth`: постачальник визначає облікові дані usage/quota для `/usage` - та пов’язаних поверхонь стану/звітності -- `fetchUsageSnapshot`: постачальник володіє отриманням/розбором endpoint usage, тоді як + токен середовища виконання +- `resolveUsageAuth`: постачальник визначає облікові дані використання/квоти для `/usage` + та пов’язаних поверхонь status/reporting +- `fetchUsageSnapshot`: постачальник володіє отриманням/розбором endpoint використання, тоді як core і далі володіє оболонкою підсумку та форматуванням -- `onModelSelected`: постачальник виконує побічні ефекти після вибору моделі, такі як - телеметрія або облік сесій, що належить постачальнику +- `onModelSelected`: постачальник виконує побічні ефекти після вибору моделі, як-от + телеметрія або ведення обліку сеансу, що належить постачальнику Поточні вбудовані приклади: -- `anthropic`: резервна сумісність уперед для Claude 4.6, підказки з відновлення автентифікації, отримання - endpoint usage, метадані cache-TTL/сімейства постачальника та глобальні +- `anthropic`: резервний механізм прямої сумісності вперед для Claude 4.6, підказки з відновлення автентифікації, отримання + endpoint використання, метадані cache-TTL/сімейства постачальника та глобальні типові значення конфігурації з урахуванням автентифікації -- `amazon-bedrock`: зіставлення переповнення контексту, яким володіє постачальник, і класифікація - причин failover для специфічних помилок Bedrock throttle/not-ready, а також - спільне сімейство повторного відтворення `anthropic-by-model` для захистів політики повторного відтворення - лише для Claude у трафіку Anthropic -- `anthropic-vertex`: захисти політики повторного відтворення лише для Claude в трафіку - повідомлень Anthropic -- `openrouter`: наскрізні ідентифікатори моделей, обгортки запитів, підказки щодо можливостей постачальника, - санітизація Gemini thought-signature у проксійованому трафіку Gemini, впровадження proxy - reasoning через сімейство потоків `openrouter-thinking`, пересилання - метаданих маршрутизації та політика cache-TTL -- `github-copilot`: онбординг/вхід за пристроєм, резервна сумісність уперед для моделей, - підказки Claude-thinking для стенограм, обмін runtime-токенів і отримання - endpoint usage -- `openai`: резервна сумісність уперед для GPT-5.4, нормалізація прямого транспорту - OpenAI, підказки про відсутню автентифікацію з урахуванням Codex, придушення Spark, synthetic - рядки каталогу OpenAI/Codex, політика thinking/live-model, нормалізація псевдонімів usage-token +- `amazon-bedrock`: визначення переповнення контексту і класифікація + причин failover для специфічних помилок Bedrock на кшталт throttle/not-ready, а також + спільне сімейство повторного відтворення `anthropic-by-model` для захисту політики replay лише для Claude + на трафіку Anthropic +- `anthropic-vertex`: захист політики replay лише для Claude на трафіку + Anthropic-message +- `openrouter`: наскрізні ідентифікатори моделей, обгортки запитів, підказки + про можливості постачальника, санітизація thought-signature Gemini на проксійованому трафіку Gemini, + впровадження reasoning через проксі за допомогою сімейства потоків `openrouter-thinking`, + пересилання метаданих маршрутизації та політика cache-TTL +- `github-copilot`: онбординг/вхід за кодом пристрою, резервна сумісність моделей уперед, + підказки для транскрипту Claude-thinking, обмін runtime-токенами та отримання + endpoint використання +- `openai`: резервна сумісність уперед для GPT-5.4, пряма нормалізація транспорту OpenAI, + підказки щодо відсутньої автентифікації з урахуванням Codex, приховування Spark, синтетичні + рядки каталогу OpenAI/Codex, політика thinking/live-model, нормалізація псевдонімів токенів використання (`input` / `output` і сімейства `prompt` / `completion`), спільне - сімейство потоків `openai-responses-defaults` для нативних обгорток OpenAI/Codex, + сімейство потоків `openai-responses-defaults` для native-обгорток OpenAI/Codex, метадані сімейства постачальника, реєстрація вбудованого постачальника генерації зображень для `gpt-image-1` і реєстрація вбудованого постачальника генерації відео для `sora-2` - `google` і `google-gemini-cli`: резервна сумісність уперед для Gemini 3.1, - нативна перевірка повторного відтворення Gemini, санітизація bootstrap replay, тегований - режим виводу reasoning, зіставлення сучасних моделей, реєстрація вбудованого постачальника - генерації зображень для моделей Gemini image-preview і вбудована - реєстрація постачальника генерації відео для моделей Veo; Gemini CLI OAuth також - володіє форматуванням токенів профілю автентифікації, розбором usage-token і отриманням - endpoint квот для поверхонь usage -- `moonshot`: спільний транспорт, нормалізація payload thinking, якою володіє плагін -- `kilocode`: спільний транспорт, заголовки запитів, якими володіє плагін, нормалізація payload reasoning, - санітизація proxy-Gemini thought-signature і політика cache-TTL + native-перевірка replay для Gemini, санітизація bootstrap replay, tagged + режим виводу reasoning, зіставлення modern-model, реєстрація вбудованого постачальника генерації зображень + для моделей Gemini image-preview і реєстрація вбудованого + постачальника генерації відео для моделей Veo; Gemini CLI OAuth також + володіє форматуванням токенів профілю автентифікації, розбором токенів використання та отриманням + endpoint квот для поверхонь використання +- `moonshot`: спільний транспорт, нормалізація payload thinking, що належить плагіну +- `kilocode`: спільний транспорт, заголовки запитів, що належать плагіну, payload reasoning + нормалізація, санітизація thought-signature проксі-Gemini та політика cache-TTL - `zai`: резервна сумісність уперед для GLM-5, типові значення `tool_stream`, політика cache-TTL, - політика binary-thinking/live-model і usage auth + отримання квот; + політика binary-thinking/live-model та автентифікація використання + отримання квот; невідомі ідентифікатори `glm-5*` синтезуються з вбудованого шаблону `glm-4.7` -- `xai`: нативна нормалізація транспорту Responses, переписування псевдонімів `/fast` для - швидких варіантів Grok, типовий `tool_stream`, очищення схем інструментів / - payload reasoning, специфічне для xAI, і реєстрація вбудованого постачальника генерації відео +- `xai`: native-нормалізація транспорту Responses, переписування псевдонімів `/fast` для + швидких варіантів Grok, типове значення `tool_stream`, очищення схем інструментів / + payload reasoning, специфічне для xAI, та реєстрація вбудованого постачальника генерації відео для `grok-imagine-video` -- `mistral`: метадані можливостей, якими володіє плагін -- `opencode` і `opencode-go`: метадані можливостей, якими володіє плагін, плюс - санітизація proxy-Gemini thought-signature -- `alibaba`: каталог генерації відео, яким володіє плагін, для прямих посилань на моделі Wan, - таких як `alibaba/wan2.6-t2v` -- `byteplus`: каталоги, якими володіє плагін, плюс реєстрація вбудованого постачальника генерації відео +- `mistral`: метадані можливостей, що належать плагіну +- `opencode` і `opencode-go`: метадані можливостей, що належать плагіну, плюс + санітизація thought-signature проксі-Gemini +- `alibaba`: каталог генерації відео, що належить плагіну, для прямих посилань на моделі Wan + на кшталт `alibaba/wan2.6-t2v` +- `byteplus`: каталоги, що належать плагіну, плюс реєстрація вбудованого постачальника генерації відео для моделей Seedance text-to-video/image-to-video - `fal`: реєстрація вбудованого постачальника генерації відео для розміщених сторонніх - моделей, реєстрація постачальника генерації зображень для моделей FLUX плюс вбудована - реєстрація постачальника генерації відео для розміщених сторонніх відеомоделей + моделей, реєстрація постачальника генерації зображень для моделей FLUX, а також реєстрація вбудованого + постачальника генерації відео для розміщених сторонніх відеомоделей - `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` і `volcengine`: - лише каталоги, якими володіє плагін -- `qwen`: каталоги текстових моделей, якими володіє плагін, плюс спільні - реєстрації постачальників media-understanding і генерації відео для його - мультимодальних поверхонь; генерація відео Qwen використовує стандартні відеоendpoint-и DashScope - зі вбудованими моделями Wan, такими як `wan2.6-t2v` і `wan2.7-r2v` -- `runway`: реєстрація постачальника генерації відео, якою володіє плагін, для нативних - task-based моделей Runway, таких як `gen4.5` -- `minimax`: каталоги, якими володіє плагін, вбудована реєстрація постачальника генерації відео - для відеомоделей Hailuo, вбудована реєстрація постачальника генерації зображень - для `image-01`, гібридний вибір політики повторного відтворення Anthropic/OpenAI - і логіка auth/snapshot usage -- `together`: каталоги, якими володіє плагін, плюс вбудована реєстрація постачальника генерації відео + лише каталоги, що належать плагіну +- `qwen`: каталоги текстових моделей, що належать плагіну, плюс спільні + реєстрації постачальників media-understanding і video-generation для його + мультимодальних поверхонь; генерація відео Qwen використовує стандартні відеоendpoint-и DashScope з + вбудованими моделями Wan, такими як `wan2.6-t2v` і `wan2.7-r2v` +- `runway`: реєстрація постачальника генерації відео, що належить плагіну, для нативних + моделей на основі задач Runway, таких як `gen4.5` +- `minimax`: каталоги, що належать плагіну, реєстрація вбудованого постачальника генерації відео + для відеомоделей Hailuo, реєстрація вбудованого постачальника генерації зображень + для `image-01`, гібридний вибір політики replay Anthropic/OpenAI + та логіка автентифікації/знімків використання +- `together`: каталоги, що належать плагіну, плюс реєстрація вбудованого постачальника генерації відео для відеомоделей Wan -- `xiaomi`: каталоги, якими володіє плагін, плюс логіка auth/snapshot usage +- `xiaomi`: каталоги, що належать плагіну, плюс логіка автентифікації/знімків використання -Вбудований плагін `openai` тепер володіє обома ідентифікаторами постачальників: `openai` і +Вбудований плагін `openai` тепер володіє обома ідентифікаторами постачальника: `openai` і `openai-codex`. -Це охоплює постачальників, які все ще відповідають звичайним транспортам OpenClaw. Постачальник, -якому потрібен повністю користувацький виконувач запитів, — це окрема, глибша поверхня розширення. +Це охоплює постачальників, які все ще вписуються у звичайні транспорти OpenClaw. Постачальник, +якому потрібен повністю користувацький виконавець запитів, — це окрема, глибша поверхня розширення. ## Ротація API-ключів - Підтримує загальну ротацію постачальників для вибраних постачальників. - Налаштуйте кілька ключів через: - - `OPENCLAW_LIVE__KEY` (одне live-перевизначення, найвищий пріоритет) + - `OPENCLAW_LIVE__KEY` (один live override, найвищий пріоритет) - `_API_KEYS` (список через кому або крапку з комою) - `_API_KEY` (основний ключ) - `_API_KEY_*` (нумерований список, наприклад `_API_KEY_1`) -- Для постачальників Google `GOOGLE_API_KEY` також включається як запасний варіант. -- Порядок вибору ключів зберігає пріоритет і усуває дублікати значень. -- Запити повторюються з наступним ключем лише у відповідях із rate limit (наприклад - `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many +- Для постачальників Google `GOOGLE_API_KEY` також включається як резервний варіант. +- Порядок вибору ключів зберігає пріоритет і прибирає дублікати значень. +- Повторні спроби запитів із наступним ключем виконуються лише у відповідь на rate-limit + відповіді (наприклад `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, - `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт usage). -- Збої, не пов’язані з rate limit, завершуються одразу; ротація ключів не виконується. -- Якщо всі кандидатні ключі не спрацювали, повертається остання помилка з останньої спроби. + `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт використання). +- Збої, не пов’язані з rate-limit, завершуються негайно; ротація ключів не виконується. +- Коли всі можливі ключі не спрацювали, повертається фінальна помилка з останньої спроби. ## Вбудовані постачальники (каталог pi-ai) -OpenClaw постачається з каталогом pi‑ai. Ці постачальники **не** -потребують конфігурації `models.providers`; просто налаштуйте автентифікацію й виберіть модель. +OpenClaw постачається з каталогом pi‑ai. Для цих постачальників **не потрібна** +конфігурація `models.providers`; достатньо налаштувати автентифікацію та вибрати модель. ### OpenAI - Постачальник: `openai` - Автентифікація: `OPENAI_API_KEY` -- Необов’язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення) +- Необов’язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (один override) - Приклади моделей: `openai/gpt-5.4`, `openai/gpt-5.4-pro` - CLI: `openclaw onboard --auth-choice openai-api-key` -- Типовий транспорт — `auto` (спочатку WebSocket, запасний варіант SSE) -- Перевизначення для окремої моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) -- Warm-up OpenAI Responses WebSocket типово ввімкнений через `params.openaiWsWarmup` (`true`/`false`) +- Транспорт за замовчуванням — `auto` (спочатку WebSocket, резервно SSE) +- Override для окремої моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) +- Прогрівання OpenAI Responses WebSocket за замовчуванням увімкнено через `params.openaiWsWarmup` (`true`/`false`) - Пріоритетну обробку OpenAI можна ввімкнути через `agents.defaults.models["openai/"].params.serviceTier` -- `/fast` і `params.fastMode` зіставляють прямі запити Responses `openai/*` із `service_tier=priority` на `api.openai.com` -- Використовуйте `params.serviceTier`, якщо вам потрібен явний рівень замість спільного перемикача `/fast` +- `/fast` і `params.fastMode` зіставляють прямі запити `openai/*` Responses з `service_tier=priority` на `api.openai.com` +- Використовуйте `params.serviceTier`, якщо вам потрібен явний tier замість спільного перемикача `/fast` - Приховані заголовки атрибуції OpenClaw (`originator`, `version`, - `User-Agent`) застосовуються лише до нативного трафіку OpenAI до `api.openai.com`, а не - до загальних OpenAI-сумісних проксі -- Нативні маршрути OpenAI також зберігають `store` Responses, підказки prompt-cache і - формування payload для сумісності reasoning OpenAI; проксі-маршрути цього не роблять -- `openai/gpt-5.3-codex-spark` навмисно приглушено в OpenClaw, оскільки live API OpenAI його відхиляє; Spark вважається лише Codex + `User-Agent`) застосовуються лише до native-трафіку OpenAI на `api.openai.com`, а не + до загальних проксі, сумісних з OpenAI +- Native-маршрути OpenAI також зберігають Responses `store`, підказки кешу промптів і + формування payload сумісності reasoning OpenAI; проксі-маршрути — ні +- `openai/gpt-5.3-codex-spark` навмисно приховано в OpenClaw, оскільки live API OpenAI його відхиляє; Spark вважається доступним лише для Codex ```json5 { @@ -279,12 +282,12 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - Постачальник: `anthropic` - Автентифікація: `ANTHROPIC_API_KEY` -- Необов’язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, а також `OPENCLAW_LIVE_ANTHROPIC_KEY` (одне перевизначення) +- Необов’язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, а також `OPENCLAW_LIVE_ANTHROPIC_KEY` (один override) - Приклад моделі: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Прямі публічні запити Anthropic також підтримують спільний перемикач `/fast` і `params.fastMode`, зокрема для трафіку з автентифікацією через API-ключ і OAuth, надісланого на `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`) -- Примітка Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволено, тому OpenClaw вважає повторне використання Claude CLI і `claude -p` дозволеними для цієї інтеграції, якщо Anthropic не опублікує нову політику. -- Anthropic setup-token і надалі доступний як підтримуваний шлях токена OpenClaw, але тепер OpenClaw віддає перевагу повторному використанню Claude CLI і `claude -p`, коли це можливо. +- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, зокрема для трафіку з автентифікацією API-ключем і OAuth, надісланого на `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`) +- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволено, тому OpenClaw вважає повторне використання Claude CLI і `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. +- Setup-token Anthropic і далі доступний як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, якщо вони доступні. ```json5 { @@ -298,15 +301,15 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - Автентифікація: OAuth (ChatGPT) - Приклад моделі: `openai-codex/gpt-5.4` - CLI: `openclaw onboard --auth-choice openai-codex` або `openclaw models auth login --provider openai-codex` -- Типовий транспорт — `auto` (спочатку WebSocket, запасний варіант SSE) -- Перевизначення для окремої моделі через `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) -- `params.serviceTier` також пересилається в нативних запитах Codex Responses (`chatgpt.com/backend-api`) +- Транспорт за замовчуванням — `auto` (спочатку WebSocket, резервно SSE) +- Override для окремої моделі через `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) +- `params.serviceTier` також пересилається в native-запитах Codex Responses (`chatgpt.com/backend-api`) - Приховані заголовки атрибуції OpenClaw (`originator`, `version`, - `User-Agent`) додаються лише до нативного трафіку Codex на - `chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних проксі -- Має той самий спільний перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority` -- `openai-codex/gpt-5.3-codex-spark` і далі доступний, коли каталог Codex OAuth його показує; залежить від entitlement -- `openai-codex/gpt-5.4` зберігає нативні `contextWindow = 1050000` і типові runtime `contextTokens = 272000`; перевизначте runtime-ліміт через `models.providers.openai-codex.models[].contextTokens` + `User-Agent`) додаються лише до native-трафіку Codex на + `chatgpt.com/backend-api`, а не до загальних проксі, сумісних з OpenAI +- Використовує той самий перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority` +- `openai-codex/gpt-5.3-codex-spark` і далі доступний, коли каталог OAuth Codex його показує; залежить від entitlement +- `openai-codex/gpt-5.4` зберігає native `contextWindow = 1050000` і типове runtime-значення `contextTokens = 272000`; змініть runtime-обмеження через `models.providers.openai-codex.models[].contextTokens` - Примітка щодо політики: OAuth OpenAI Codex явно підтримується для зовнішніх інструментів/робочих процесів, таких як OpenClaw. ```json5 @@ -329,15 +332,15 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста ### Інші розміщені варіанти у стилі підписки -- [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud плюс зіставлення endpoint-ів Alibaba DashScope і Coding Plan -- [MiniMax](/uk/providers/minimax): доступ через OAuth або API-ключ MiniMax Coding Plan -- [GLM Models](/uk/providers/glm): endpoint-и Z.AI Coding Plan або загальні API +- [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud плюс зіставлення endpoint Alibaba DashScope і Coding Plan +- [MiniMax](/uk/providers/minimax): OAuth або доступ через API-ключ MiniMax Coding Plan +- [GLM Models](/uk/providers/glm): Z.AI Coding Plan або загальні API endpoint-и ### OpenCode - Автентифікація: `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`) -- Постачальник Zen runtime: `opencode` -- Постачальник Go runtime: `opencode-go` +- Постачальник середовища виконання Zen: `opencode` +- Постачальник середовища виконання Go: `opencode-go` - Приклади моделей: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5` - CLI: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go` @@ -351,31 +354,31 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - Постачальник: `google` - Автентифікація: `GEMINI_API_KEY` -- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, запасний варіант `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне перевизначення) +- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, резервний варіант `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (один override) - Приклади моделей: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` - Сумісність: застаріла конфігурація OpenClaw з `google/gemini-3.1-flash-preview` нормалізується до `google/gemini-3-flash-preview` - CLI: `openclaw onboard --auth-choice gemini-api-key` - Прямі запуски Gemini також приймають `agents.defaults.models["google/"].params.cachedContent` - (або застарілий `cached_content`) для пересилання нативного для постачальника - дескриптора `cachedContents/...`; cache hit-и Gemini відображаються як OpenClaw `cacheRead` + (або застарілий `cached_content`) для пересилання provider-native + дескриптора `cachedContents/...`; cache hit Gemini відображаються як OpenClaw `cacheRead` ### Google Vertex і Gemini CLI - Постачальники: `google-vertex`, `google-gemini-cli` -- Автентифікація: Vertex використовує gcloud ADC; Gemini CLI використовує свій потік OAuth -- Увага: Gemini CLI OAuth в OpenClaw — це неофіційна інтеграція. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити. -- Gemini CLI OAuth постачається як частина вбудованого плагіна `google`. +- Автентифікація: Vertex використовує gcloud ADC; Gemini CLI використовує власний потік OAuth +- Застереження: OAuth Gemini CLI в OpenClaw — це неофіційна інтеграція. Деякі користувачі повідомляли про обмеження облікових записів Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити. +- OAuth Gemini CLI постачається як частина вбудованого плагіна `google`. - Спочатку встановіть Gemini CLI: - `brew install gemini-cli` - або `npm install -g @google/gemini-cli` - - Увімкнення: `openclaw plugins enable google` - - Вхід: `openclaw models auth login --provider google-gemini-cli --set-default` - - Типова модель: `google-gemini-cli/gemini-3-flash-preview` + - Увімкніть: `openclaw plugins enable google` + - Увійдіть: `openclaw models auth login --provider google-gemini-cli --set-default` + - Модель за замовчуванням: `google-gemini-cli/gemini-3-flash-preview` - Примітка: вам **не потрібно** вставляти client id або secret у `openclaw.json`. Потік входу CLI зберігає - токени в профілях автентифікації на хості шлюзу. - - Якщо після входу запити не працюють, встановіть `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості шлюзу. - - JSON-відповіді Gemini CLI розбираються з `response`; usage резервно береться з - `stats`, а `stats.cached` нормалізується до OpenClaw `cacheRead`. + токени в профілях автентифікації на gateway host. + - Якщо після входу запити не працюють, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на gateway host. + - JSON-відповіді Gemini CLI розбираються з `response`; використання резервно береться з + `stats`, а `stats.cached` нормалізується в OpenClaw `cacheRead`. ### Z.AI (GLM) @@ -384,7 +387,7 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - Приклад моделі: `zai/glm-5.1` - CLI: `openclaw onboard --auth-choice zai-api-key` - Псевдоніми: `z.ai/*` і `z-ai/*` нормалізуються до `zai/*` - - `zai-api-key` автоматично визначає відповідний endpoint Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово вибирають конкретну поверхню + - `zai-api-key` автоматично визначає відповідний endpoint Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово задають конкретну поверхню ### Vercel AI Gateway @@ -399,10 +402,10 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - Автентифікація: `KILOCODE_API_KEY` - Приклад моделі: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` -- Base URL: `https://api.kilo.ai/api/gateway/` -- Статичний запасний каталог постачається з `kilocode/kilo/auto`; live - виявлення `https://api.kilo.ai/api/gateway/models` може додатково розширити runtime - каталог. +- Базовий URL: `https://api.kilo.ai/api/gateway/` +- Статичний резервний каталог постачається з `kilocode/kilo/auto`; live-виявлення через + `https://api.kilo.ai/api/gateway/models` може додатково розширити каталог + середовища виконання. - Точна upstream-маршрутизація за `kilocode/kilo/auto` належить Kilo Gateway, а не жорстко закодована в OpenClaw. @@ -412,25 +415,25 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - OpenRouter: `openrouter` (`OPENROUTER_API_KEY`) - Приклад моделі: `openrouter/auto` -- OpenClaw застосовує задокументовані заголовки атрибуції застосунку OpenRouter лише тоді, коли +- OpenClaw застосовує задокументовані OpenRouter заголовки атрибуції застосунку лише тоді, коли запит справді спрямовано на `openrouter.ai` - Специфічні для OpenRouter маркери Anthropic `cache_control` так само обмежуються - перевіреними маршрутами OpenRouter, а не довільними URL проксі -- OpenRouter і далі працює на шляху проксі-стилю, сумісному з OpenAI, тож нативне - формування запитів лише для OpenAI (`serviceTier`, Responses `store`, - підказки prompt-cache, payload-и сумісності reasoning OpenAI) не пересилається -- Посилання OpenRouter на базі Gemini зберігають лише шлях санітизації proxy-Gemini thought-signature; - нативна перевірка повторного відтворення Gemini та переписування bootstrap залишаються вимкненими + перевіреними маршрутами OpenRouter, а не довільними проксі-URL +- OpenRouter і далі працює на проксі-шляху у стилі OpenAI-compatible, тому + native-формування запитів лише для OpenAI (`serviceTier`, Responses `store`, + підказки кешу промптів, payload сумісності reasoning OpenAI) не пересилається +- Посилання OpenRouter на базі Gemini зберігають лише санітизацію thought-signature для проксі-Gemini; + native-перевірка replay Gemini і переписування bootstrap залишаються вимкненими - Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`) - Приклад моделі: `kilocode/kilo/auto` -- Посилання Kilo на базі Gemini зберігають той самий шлях - санітизації proxy-Gemini thought-signature; `kilocode/kilo/auto` та інші підказки - без підтримки proxy-reasoning пропускають впровадження proxy reasoning +- Посилання Kilo на базі Gemini зберігають той самий шлях санітизації + thought-signature для проксі-Gemini; `kilocode/kilo/auto` та інші підказки + без підтримки proxy-reasoning пропускають впровадження reasoning через проксі - MiniMax: `minimax` (API-ключ) і `minimax-portal` (OAuth) - Автентифікація: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal` - Приклад моделі: `minimax/MiniMax-M2.7` або `minimax-portal/MiniMax-M2.7` -- Онбординг MiniMax/налаштування API-ключа записує явні визначення моделі M2.7 з - `input: ["text", "image"]`; вбудований каталог постачальника зберігає chat refs +- Налаштування онбордингу/API-ключа MiniMax записує явні визначення моделей M2.7 з + `input: ["text", "image"]`; вбудований каталог постачальника зберігає chat-посилання лише текстовими, доки не буде матеріалізовано конфігурацію цього постачальника - Moonshot: `moonshot` (`MOONSHOT_API_KEY`) - Приклад моделі: `moonshot/kimi-k2.5` @@ -457,26 +460,26 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста - BytePlus: `byteplus` (`BYTEPLUS_API_KEY`) - Приклад моделі: `byteplus-plan/ark-code-latest` - xAI: `xai` (`XAI_API_KEY`) - - Нативні вбудовані запити xAI використовують шлях xAI Responses - - `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, + - Native-вбудовані запити xAI використовують шлях xAI Responses + - `/fast` або `params.fastMode: true` переписують `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast` - - `tool_stream` типово ввімкнено; установіть + - `tool_stream` увімкнено за замовчуванням; задайте `agents.defaults.models["xai/"].params.tool_stream` у `false`, щоб - його вимкнути + вимкнути його - Mistral: `mistral` (`MISTRAL_API_KEY`) - Приклад моделі: `mistral/mistral-large-latest` - CLI: `openclaw onboard --auth-choice mistral-api-key` - Groq: `groq` (`GROQ_API_KEY`) - Cerebras: `cerebras` (`CEREBRAS_API_KEY`) - Моделі GLM у Cerebras використовують ідентифікатори `zai-glm-4.7` і `zai-glm-4.6`. - - Base URL, сумісний з OpenAI: `https://api.cerebras.ai/v1`. + - Базовий URL, сумісний з OpenAI: `https://api.cerebras.ai/v1`. - GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`) - Приклад моделі Hugging Face Inference: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. Див. [Hugging Face (Inference)](/uk/providers/huggingface). -## Постачальники через `models.providers` (користувацький/base URL) +## Постачальники через `models.providers` (custom/base URL) -Використовуйте `models.providers` (або `models.json`), щоб додати **користувацьких** постачальників або -OpenAI/Anthropic-сумісні проксі. +Використовуйте `models.providers` (або `models.json`) для додавання **власних** постачальників або +проксі, сумісних з OpenAI/Anthropic. Багато з наведених нижче вбудованих плагінів постачальників уже публікують типовий каталог. Використовуйте явні записи `models.providers.` лише тоді, коли хочете перевизначити @@ -485,7 +488,7 @@ OpenAI/Anthropic-сумісні проксі. ### Moonshot AI (Kimi) Moonshot постачається як вбудований плагін постачальника. Типово використовуйте вбудованого постачальника, -і додавайте явний запис `models.providers.moonshot` лише тоді, коли +а явний запис `models.providers.moonshot` додавайте лише тоді, коли потрібно перевизначити base URL або метадані моделі: - Постачальник: `moonshot` @@ -525,7 +528,7 @@ Moonshot постачається як вбудований плагін пос ### Kimi Coding -Kimi Coding використовує Anthropic-сумісний endpoint Moonshot AI: +Kimi Coding використовує endpoint Moonshot AI, сумісний з Anthropic: - Постачальник: `kimi` - Автентифікація: `KIMI_API_KEY` @@ -559,13 +562,13 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши } ``` -Онбординг типово використовує coding surface, але загальний каталог `volcengine/*` +Під час онбордингу типовою є coding-поверхня, але загальний каталог `volcengine/*` реєструється одночасно. -У засобах вибору моделей для онбордингу/налаштування вибір автентифікації Volcengine віддає перевагу і рядкам -`volcengine/*`, і `volcengine-plan/*`. Якщо ці моделі ще не завантажено, +У засобах вибору моделі під час онбордингу/налаштування варіант автентифікації Volcengine надає перевагу і рядкам +`volcengine/*`, і `volcengine-plan/*`. Якщо ці моделі ще не завантажені, OpenClaw повертається до нефільтрованого каталогу замість показу порожнього -засобу вибору в межах постачальника. +засобу вибору, обмеженого постачальником. Доступні моделі: @@ -575,7 +578,7 @@ OpenClaw повертається до нефільтрованого катал - `volcengine/glm-4-7-251222` (GLM 4.7) - `volcengine/deepseek-v3-2-251201` (DeepSeek V3.2 128K) -Coding-моделі (`volcengine-plan`): +Моделі для coding (`volcengine-plan`): - `volcengine-plan/ark-code-latest` - `volcengine-plan/doubao-seed-code` @@ -600,13 +603,13 @@ BytePlus ARK надає міжнародним користувачам дост } ``` -Онбординг типово використовує coding surface, але загальний каталог `byteplus/*` +Під час онбордингу типовою є coding-поверхня, але загальний каталог `byteplus/*` реєструється одночасно. -У засобах вибору моделей для онбордингу/налаштування вибір автентифікації BytePlus віддає перевагу і рядкам -`byteplus/*`, і `byteplus-plan/*`. Якщо ці моделі ще не завантажено, +У засобах вибору моделі під час онбордингу/налаштування варіант автентифікації BytePlus надає перевагу і рядкам +`byteplus/*`, і `byteplus-plan/*`. Якщо ці моделі ще не завантажені, OpenClaw повертається до нефільтрованого каталогу замість показу порожнього -засобу вибору в межах постачальника. +засобу вибору, обмеженого постачальником. Доступні моделі: @@ -614,7 +617,7 @@ OpenClaw повертається до нефільтрованого катал - `byteplus/kimi-k2-5-260127` (Kimi K2.5) - `byteplus/glm-4-7-251222` (GLM 4.7) -Coding-моделі (`byteplus-plan`): +Моделі для coding (`byteplus-plan`): - `byteplus-plan/ark-code-latest` - `byteplus-plan/doubao-seed-code` @@ -624,7 +627,7 @@ Coding-моделі (`byteplus-plan`): ### Synthetic -Synthetic надає Anthropic-сумісні моделі через постачальника `synthetic`: +Synthetic надає моделі, сумісні з Anthropic, через постачальника `synthetic`: - Постачальник: `synthetic` - Автентифікація: `SYNTHETIC_API_KEY` @@ -656,27 +659,27 @@ MiniMax налаштовується через `models.providers`, оскіль - MiniMax OAuth (Global): `--auth-choice minimax-global-oauth` - MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` -- MiniMax API-ключ (Global): `--auth-choice minimax-global-api` -- MiniMax API-ключ (CN): `--auth-choice minimax-cn-api` +- MiniMax API key (Global): `--auth-choice minimax-global-api` +- MiniMax API key (CN): `--auth-choice minimax-cn-api` - Автентифікація: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal` Докладніше про налаштування, варіанти моделей і фрагменти конфігурації див. у [/providers/minimax](/uk/providers/minimax). -На Anthropic-сумісному streaming path MiniMax OpenClaw типово вимикає thinking, -якщо ви не ввімкнете його явно, а `/fast on` переписує +На шляху потокової передачі MiniMax, сумісному з Anthropic, OpenClaw вимикає thinking +за замовчуванням, якщо ви явно його не задасте, а `/fast on` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. -Поділ можливостей, якими володіє плагін: +Розподіл можливостей, що належать плагіну: -- Типові значення text/chat залишаються на `minimax/MiniMax-M2.7` +- Типові значення для тексту/чату залишаються на `minimax/MiniMax-M2.7` - Генерація зображень — це `minimax/image-01` або `minimax-portal/image-01` -- Розуміння зображень — це `MiniMax-VL-01`, яким володіє плагін, на обох шляхах автентифікації MiniMax +- Розуміння зображень — це `MiniMax-VL-01`, що належить плагіну, на обох шляхах автентифікації MiniMax - Вебпошук залишається на ідентифікаторі постачальника `minimax` ### Ollama -Ollama постачається як вбудований плагін постачальника й використовує нативний API Ollama: +Ollama постачається як вбудований плагін постачальника і використовує native API Ollama: - Постачальник: `ollama` - Автентифікація: не потрібна (локальний сервер) @@ -684,7 +687,7 @@ Ollama постачається як вбудований плагін пост - Встановлення: [https://ollama.com/download](https://ollama.com/download) ```bash -# Встановіть Ollama, потім завантажте модель: +# Установіть Ollama, а потім завантажте модель: ollama pull llama3.3 ``` @@ -696,26 +699,27 @@ ollama pull llama3.3 } ``` -Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви явно вмикаєте це через +Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви вмикаєте це через `OLLAMA_API_KEY`, а вбудований плагін постачальника додає Ollama безпосередньо до -`openclaw onboard` і засобу вибору моделей. Докладніше про онбординг, режим cloud/local і користувацьку конфігурацію див. у [/providers/ollama](/uk/providers/ollama). +`openclaw onboard` і засобу вибору моделей. Див. [/providers/ollama](/uk/providers/ollama) +щодо онбордингу, хмарного/локального режиму та користувацької конфігурації. ### vLLM vLLM постачається як вбудований плагін постачальника для локальних/self-hosted -OpenAI-сумісних серверів: +серверів, сумісних з OpenAI: - Постачальник: `vllm` - Автентифікація: необов’язкова (залежить від вашого сервера) -- Типовий base URL: `http://127.0.0.1:8000/v1` +- Базовий URL за замовчуванням: `http://127.0.0.1:8000/v1` -Щоб увімкнути локальне auto-discovery (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікації): +Щоб увімкнути автоматичне виявлення локально (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікації): ```bash export VLLM_API_KEY="vllm-local" ``` -Потім установіть модель (замініть на один з ідентифікаторів, які повертає `/v1/models`): +Потім задайте модель (замініть на один з ідентифікаторів, які повертає `/v1/models`): ```json5 { @@ -730,20 +734,20 @@ export VLLM_API_KEY="vllm-local" ### SGLang SGLang постачається як вбудований плагін постачальника для швидких self-hosted -OpenAI-сумісних серверів: +серверів, сумісних з OpenAI: - Постачальник: `sglang` - Автентифікація: необов’язкова (залежить від вашого сервера) -- Типовий base URL: `http://127.0.0.1:30000/v1` +- Базовий URL за замовчуванням: `http://127.0.0.1:30000/v1` -Щоб увімкнути локальне auto-discovery (підійде будь-яке значення, якщо ваш сервер не +Щоб увімкнути автоматичне виявлення локально (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікації): ```bash export SGLANG_API_KEY="sglang-local" ``` -Потім установіть модель (замініть на один з ідентифікаторів, які повертає `/v1/models`): +Потім задайте модель (замініть на один з ідентифікаторів, які повертає `/v1/models`): ```json5 { @@ -776,7 +780,7 @@ export SGLANG_API_KEY="sglang-local" models: [ { id: "my-local-model", - name: "Локальна модель", + name: "Local Model", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, @@ -793,20 +797,19 @@ export SGLANG_API_KEY="sglang-local" Примітки: - Для користувацьких постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов’язковими. - Якщо їх не вказано, OpenClaw типово використовує: + Якщо їх не вказано, OpenClaw використовує такі значення за замовчуванням: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- Рекомендовано: установлюйте явні значення, що відповідають лімітам вашого проксі/моделі. -- Для `api: "openai-completions"` на ненативних endpoint-ах (будь-який непорожній `baseUrl`, хост якого не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникнути помилок постачальника 400 для непідтримуваних ролей `developer`. -- Маршрути проксі-стилю, сумісні з OpenAI, також пропускають нативне формування запитів лише для OpenAI: - без `service_tier`, без Responses `store`, без підказок prompt-cache, без - формування payload для сумісності reasoning OpenAI і без прихованих заголовків - атрибуції OpenClaw. -- Якщо `baseUrl` порожній або не вказаний, OpenClaw зберігає типову поведінку OpenAI (яка спрямовується на `api.openai.com`). -- З міркувань безпеки явне `compat.supportsDeveloperRole: true` усе одно перевизначається на ненативних endpoint-ах `openai-completions`. +- Рекомендовано: задавати явні значення, що відповідають обмеженням вашого проксі/моделі. +- Для `api: "openai-completions"` на не-native endpoint-ах (будь-який непорожній `baseUrl`, у якого host не `api.openai.com`) OpenClaw примусово задає `compat.supportsDeveloperRole: false`, щоб уникнути помилок 400 від постачальника через непідтримувані ролі `developer`. +- Маршрути у стилі проксі, сумісні з OpenAI, також пропускають native-формування запитів лише для OpenAI: + без `service_tier`, без Responses `store`, без підказок кешу промптів, без + формування payload сумісності reasoning OpenAI і без прихованих заголовків атрибуції OpenClaw. +- Якщо `baseUrl` порожній/не вказаний, OpenClaw зберігає стандартну поведінку OpenAI (яка вказує на `api.openai.com`). +- З міркувань безпеки явне `compat.supportsDeveloperRole: true` усе одно перевизначається на не-native endpoint-ах `openai-completions`. ## Приклади CLI @@ -818,9 +821,9 @@ openclaw models list Див. також: [/gateway/configuration](/uk/gateway/configuration) для повних прикладів конфігурації. -## Пов’язане +## Пов’язані сторінки -- [Models](/uk/concepts/models) — конфігурація моделей і псевдоніми -- [Model Failover](/uk/concepts/model-failover) — ланцюжки резервування та поведінка повторних спроб -- [Configuration Reference](/uk/gateway/configuration-reference#agent-defaults) — ключі конфігурації моделей -- [Providers](/uk/providers) — посібники з налаштування для окремих постачальників +- [Моделі](/uk/concepts/models) — конфігурація моделей і псевдоніми +- [Резервне перемикання моделей](/uk/concepts/model-failover) — ланцюжки fallback і поведінка повторних спроб +- [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) — ключі конфігурації моделей +- [Постачальники](/uk/providers) — окремі посібники з налаштування постачальників diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index 39d2d4fa0..06fbbfefb 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -2,36 +2,36 @@ read_when: - Вам потрібні точні семантики полів конфігурації або значення за замовчуванням - Ви перевіряєте блоки конфігурації каналу, моделі, шлюзу або інструмента -summary: Довідник конфігурації шлюзу для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем -title: Довідник конфігурації +summary: Довідник з конфігурації шлюзу для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем +title: Довідник з конфігурації x-i18n: - generated_at: "2026-04-10T18:37:01Z" + generated_at: "2026-04-10T20:28:56Z" model: gpt-5.4 provider: openai - source_hash: 9ad435d9c7ea41d2a63c097e30d6f86c2ae8c3e71ab0d386d4b60f206f201b36 + source_hash: dae596e545735012a048b7e3aed66c04353f8fd497af3971f7e5b9f928f6f0c8 source_path: gateway/configuration-reference.md workflow: 15 --- -# Довідник конфігурації +# Довідник з конфігурації -Основний довідник конфігурації для `~/.openclaw/openclaw.json`. Для огляду за завданнями див. [Configuration](/uk/gateway/configuration). +Основний довідник з конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Конфігурація](/uk/gateway/configuration). -Ця сторінка охоплює основні поверхні конфігурації OpenClaw і дає посилання назовні, коли підсистема має власний детальніший довідник. Вона **не** намагається вбудувати на одній сторінці кожен каталог команд, що належить каналу/плагіну, або кожен глибокий параметр пам’яті/QMD. +Ця сторінка охоплює основні поверхні конфігурації OpenClaw і містить посилання назовні, коли підсистема має власний глибший довідник. Вона **не** намагається вбудувати на одну сторінку кожен каталог команд, що належить каналу/плагіну, або кожен глибокий параметр пам’яті/QMD. Джерело істини в коді: -- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та Control UI, з об’єднаними метаданими bundled/plugin/channel, коли вони доступні -- `config.schema.lookup` повертає один вузол схеми з обмеженням до шляху для інструментів детального перегляду -- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють хеш базового рівня документації конфігурації відносно поточної поверхні схеми +- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та Control UI, із об’єднаними метаданими bundled/plugin/channel, коли вони доступні +- `config.schema.lookup` повертає один вузол схеми, обмежений шляхом, для інструментів детального перегляду +- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють хеш базового рівня документації конфігурації щодо поточної поверхні схеми Окремі поглиблені довідники: -- [Довідник конфігурації пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації dreaming у `plugins.entries.memory-core.config.dreaming` -- [Косі команди](/uk/tools/slash-commands) для поточного каталогу вбудованих + bundled команд -- сторінки відповідних каналів/плагінів для поверхонь команд, специфічних для каналу +- [Довідник з конфігурації пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації dreaming у `plugins.entries.memory-core.config.dreaming` +- [Slash Commands](/uk/tools/slash-commands) для поточного каталогу вбудованих і bundled команд +- сторінки власника каналу/плагіну для поверхонь команд, специфічних для каналу -Формат конфігурації — **JSON5** (дозволені коментарі й кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх не вказано. +Формат конфігурації — **JSON5** (дозволені коментарі та кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх не вказано. --- @@ -39,32 +39,32 @@ x-i18n: Кожен канал запускається автоматично, коли існує його розділ конфігурації (якщо не вказано `enabled: false`). -### Доступ до приватних повідомлень і груп +### Доступ до особистих повідомлень і груп -Усі канали підтримують політики для приватних повідомлень і політики для груп: +Усі канали підтримують політики для особистих повідомлень і політики для груп: -| Політика DM | Поведінка | -| -------------------- | -------------------------------------------------------------- | -| `pairing` (типово) | Невідомі відправники отримують одноразовий код спарювання; власник має схвалити | -| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволів після спарювання) | -| `open` | Дозволити всі вхідні приватні повідомлення (потрібно `allowFrom: ["*"]`) | -| `disabled` | Ігнорувати всі вхідні приватні повідомлення | +| Політика особистих повідомлень | Поведінка | +| ------------------------------ | -------------------------------------------------------------- | +| `pairing` (типово) | Невідомі відправники отримують одноразовий код pairing; власник має схвалити | +| `allowlist` | Лише відправники з `allowFrom` (або зі сховища paired allow) | +| `open` | Дозволити всі вхідні особисті повідомлення (потрібно `allowFrom: ["*"]`) | +| `disabled` | Ігнорувати всі вхідні особисті повідомлення | -| Політика груп | Поведінка | -| --------------------- | ------------------------------------------------------ | -| `allowlist` (типово) | Лише групи, що відповідають налаштованому списку дозволених | -| `open` | Обійти списки дозволених груп (обмеження за згадками все одно застосовується) | -| `disabled` | Блокувати всі повідомлення в групах/кімнатах | +| Політика груп | Поведінка | +| ------------------------ | ------------------------------------------------------ | +| `allowlist` (типово) | Лише групи, що відповідають налаштованому allowlist | +| `open` | Обійти allowlist груп (фільтрація за згадкою все одно застосовується) | +| `disabled` | Блокувати всі повідомлення в групах/кімнатах | -`channels.defaults.groupPolicy` задає значення за замовчуванням, коли `groupPolicy` провайдера не встановлено. -Коди спарювання спливають через 1 годину. Очікувальні запити на спарювання для приватних повідомлень обмежені **3 на канал**. -Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (закрито за замовчуванням) із попередженням під час запуску. +`channels.defaults.groupPolicy` задає типове значення, коли `groupPolicy` провайдера не встановлено. +Коди pairing спливають через 1 годину. Очікувані запити pairing для особистих повідомлень обмежені **3 на канал**. +Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (відмова за замовчуванням) із попередженням під час запуску. -### Перевизначення моделі для каналів +### Перевизначення моделі для каналу -Використовуйте `channels.modelByChannel`, щоб прив’язати конкретні ідентифікатори каналів до моделі. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Відображення каналу застосовується, коли для сесії ще не задано перевизначення моделі (наприклад, через `/model`). +Використовуйте `channels.modelByChannel`, щоб закріпити конкретні ідентифікатори каналів за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Відображення каналу застосовується, коли для сесії ще немає перевизначення моделі (наприклад, встановленого через `/model`). ```json5 { @@ -105,15 +105,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`: резервна політика груп, коли `groupPolicy` на рівні провайдера не встановлено. -- `channels.defaults.contextVisibility`: типовий режим видимості додаткового контексту для всіх каналів. Значення: `all` (типово, включати весь контекст із цитат/тредів/історії), `allowlist` (включати контекст лише від відправників зі списку дозволених), `allowlist_quote` (як allowlist, але зберігати явний контекст цитати/відповіді). Перевизначення для окремого каналу: `channels..contextVisibility`. +- `channels.defaults.groupPolicy`: резервна політика групи, коли `groupPolicy` на рівні провайдера не встановлено. +- `channels.defaults.contextVisibility`: типовий режим видимості додаткового контексту для всіх каналів. Значення: `all` (типово, включати весь цитований/тредовий/історичний контекст), `allowlist` (включати контекст лише від відправників з allowlist), `allowlist_quote` (те саме, що allowlist, але зберігати явний контекст цитати/відповіді). Перевизначення для окремого каналу: `channels..contextVisibility`. - `channels.defaults.heartbeat.showOk`: включати статуси справних каналів у вивід heartbeat. -- `channels.defaults.heartbeat.showAlerts`: включати статуси деградації/помилок у вивід heartbeat. +- `channels.defaults.heartbeat.showAlerts`: включати деградовані/помилкові статуси у вивід heartbeat. - `channels.defaults.heartbeat.useIndicator`: відображати компактний вивід heartbeat у стилі індикатора. ### WhatsApp -WhatsApp працює через вебканал шлюзу (Baileys Web). Він запускається автоматично, коли існує прив’язана сесія. +WhatsApp працює через web-канал шлюзу (Baileys Web). Він запускається автоматично, коли існує прив’язана сесія. ```json5 { @@ -124,7 +124,7 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // сині галочки (false у режимі self-chat) + sendReadReceipts: true, // сині галочки (false у режимі чату із собою) groups: { "*": { requireMention: true }, }, @@ -146,7 +146,7 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві } ``` - + ```json5 { @@ -164,10 +164,10 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві } ``` -- Вихідні команди типово використовують обліковий запис `default`, якщо він є; інакше — перший налаштований ідентифікатор облікового запису (відсортований). -- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. -- Застарілий каталог автентифікації Baileys для одного облікового запису переноситься `openclaw doctor` до `whatsapp/default`. -- Перевизначення на рівні облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. +- Вихідні команди типово використовують обліковий запис `default`, якщо він присутній; інакше — перший налаштований ідентифікатор облікового запису (відсортований). +- Необов’язковий параметр `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- Застарілий каталог автентифікації Baileys для одного облікового запису мігрується через `openclaw doctor` до `whatsapp/default`. +- Перевизначення для окремого облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -202,7 +202,7 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) + streaming: "partial", // off | partial | block | progress (типово: off; явно вмикайте, щоб уникнути обмежень частоти preview-edit) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -226,11 +226,11 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві ``` - Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; символьні посилання відхиляються), з `TELEGRAM_BOT_TOKEN` як резервним варіантом для типового облікового запису. -- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. -- У конфігураціях із кількома обліковими записами (2+ ідентифікатори облікових записів) задайте явний типовий (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо цього немає або значення некоректне. -- `configWrites: false` блокує ініційовані з Telegram записи конфігурації (міграції ID супергруп, `/config set|unset`). -- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- Попередній перегляд потокової передачі в Telegram використовує `sendMessage` + `editMessageText` (працює в приватних і групових чатах). +- Необов’язковий параметр `channels.telegram.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- У конфігураціях із багатьма обліковими записами (2+ ідентифікаторів облікових записів) встановіть явний типовий обліковий запис (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо цього бракує або значення невалідне. +- `configWrites: false` блокує ініційовані Telegram записи конфігурації (міграції ID supergroup, `/config set|unset`). +- Елементи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні прив’язки ACP для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- Попередній перегляд потоку Telegram використовує `sendMessage` + `editMessageText` (працює в особистих і групових чатах). - Політика повторних спроб: див. [Політика повторних спроб](/uk/concepts/retry). ### Discord @@ -286,7 +286,7 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) + streaming: "off", // off | partial | block | progress (progress відповідає partial у Discord) maxLinesPerMessage: 17, ui: { components: { @@ -297,7 +297,7 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) + spawnSubagentSessions: false, // opt-in для sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -335,32 +335,32 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві - Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як резервним варіантом для типового облікового запису. - Прямі вихідні виклики, які надають явний Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку runtime. -- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. -- Використовуйте `user:` (DM) або `channel:` (канал guild) для цілей доставки; просто числові ідентифікатори відхиляються. -- Slug-и guild мають нижній регістр, а пробіли в них замінюються на `-`; ключі каналів використовують slug-ім’я (без `#`). Надавайте перевагу ідентифікаторам guild. +- Необов’язковий параметр `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- Використовуйте `user:` (DM) або `channel:` (канал guild) як цілі доставки; прості числові ідентифікатори відхиляються. +- Slug-и guild — у нижньому регістрі із заміною пробілів на `-`; ключі каналів використовують slug-ім’я (без `#`). Надавайте перевагу ідентифікаторам guild. - Повідомлення, створені ботом, типово ігноруються. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення ботів, які згадують бота (власні повідомлення все одно відфільтровуються). -- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення каналу) відкидає повідомлення, які згадують іншого користувача або роль, але не бота (за винятком @everyone/@here). -- `maxLinesPerMessage` (типово 17) розбиває високі повідомлення навіть тоді, коли вони коротші за 2000 символів. -- `channels.discord.threadBindings` керує маршрутизацією Discord, прив’язаною до тредів: - - `enabled`: перевизначення Discord для функцій сесій, прив’язаних до тредів (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив’язана доставка/маршрутизація) - - `idleHours`: перевизначення Discord для автоматичного зняття фокуса через неактивність у годинах (`0` вимикає) +- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення на рівні каналу) відкидає повідомлення, які згадують іншого користувача або роль, але не бота (за винятком @everyone/@here). +- `maxLinesPerMessage` (типово 17) розбиває довгі за висотою повідомлення навіть тоді, коли вони коротші за 2000 символів. +- `channels.discord.threadBindings` керує маршрутизацією, прив’язаною до тредів Discord: + - `enabled`: перевизначення Discord для функцій сесій, прив’язаних до тредів (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і доставка/маршрутизація з прив’язкою) + - `idleHours`: перевизначення Discord для автоматичного скасування фокуса через неактивність у годинах (`0` вимикає) - `maxAgeHours`: перевизначення Discord для жорсткого максимального віку в годинах (`0` вимикає) - - `spawnSubagentSessions`: перемикач opt-in для автоматичного створення/прив’язки тредів у `sessions_spawn({ thread: true })` -- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для каналів і тредів (використовуйте id каналу/треду в `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- `channels.discord.ui.components.accentColor` задає акцентний колір для контейнерів компонентів Discord v2. + - `spawnSubagentSessions`: перемикач opt-in для автоматичного створення/прив’язки тредів через `sessions_spawn({ thread: true })` +- Елементи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні прив’язки ACP для каналів і тредів (використовуйте id каналу/треду в `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- `channels.discord.ui.components.accentColor` задає акцентний колір для контейнерів Discord components v2. - `channels.discord.voice` вмикає розмови в голосових каналах Discord і необов’язкові перевизначення auto-join + TTS. -- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` напряму передаються до параметрів DAVE у `@discordjs/voice` (`true` і `24` типово). -- OpenClaw також додатково намагається відновити прийом голосу, виходячи й повторно входячи в голосову сесію після повторних збоїв дешифрування. -- `channels.discord.streaming` — канонічний ключ режиму потокової передачі. Застарілі значення `streamMode` і булеві значення `streaming` мігруються автоматично. -- `channels.discord.autoPresence` відображає доступність runtime у статус бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу. +- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` напряму передаються до параметрів DAVE `@discordjs/voice` (`true` і `24` типово). +- OpenClaw додатково намагається відновити прийом голосу, виходячи з голосової сесії та приєднуючись знову після повторних збоїв дешифрування. +- `channels.discord.streaming` — канонічний ключ режиму потоку. Застарілі значення `streamMode` і булеві значення `streaming` автоматично мігруються. +- `channels.discord.autoPresence` відображає доступність runtime у присутність бота (healthy => online, degraded => idle, exhausted => dnd) і дає змогу необов’язково перевизначати текст статусу. - `channels.discord.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваними іменами/тегами (режим сумісності break-glass). -- `channels.discord.execApprovals`: доставка підтверджень exec у стилі Discord і авторизація тих, хто може підтверджувати. - - `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі підтвердження exec активуються, коли тих, хто може підтверджувати, можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ідентифікатори користувачів Discord, яким дозволено підтверджувати exec-запити. Якщо не вказано, використовується резервний варіант `commands.ownerAllowFrom`. - - `agentFilter`: необов’язковий allowlist ідентифікаторів агентів. Якщо не вказано, підтвердження пересилаються для всіх агентів. +- `channels.discord.execApprovals`: нативна доставка схвалень exec для Discord і авторизація тих, хто схвалює. + - `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі схвалення exec активуються, коли тих, хто схвалює, можна визначити з `approvers` або `commands.ownerAllowFrom`. + - `approvers`: ідентифікатори користувачів Discord, яким дозволено схвалювати запити exec. Якщо не вказано, використовується `commands.ownerAllowFrom`. + - `agentFilter`: необов’язковий allowlist ідентифікаторів агентів. Не вказуйте, щоб пересилати схвалення для всіх агентів. - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex). - - `target`: куди надсилати запити на підтвердження. `"dm"` (типово) надсилає в DM користувачів, що підтверджують, `"channel"` надсилає у вихідний канал, `"both"` надсилає в обидва місця. Коли `target` включає `"channel"`, кнопки можуть використовувати лише визначені користувачі, що підтверджують. - - `cleanupAfterResolve`: коли `true`, видаляє DM-повідомлення з підтвердженням після схвалення, відхилення або тайм-ауту. + - `target`: куди надсилати запити на схвалення. `"dm"` (типово) надсилає їх у DM тим, хто схвалює, `"channel"` надсилає у вихідний канал, `"both"` надсилає в обидва місця. Коли target містить `"channel"`, кнопками можуть користуватися лише визначені ті, хто схвалює. + - `cleanupAfterResolve`: якщо `true`, видаляє DM зі схваленням після схвалення, відхилення або тайм-ауту. **Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, типово), `all` (усі повідомлення), `allowlist` (із `guilds..users` для всіх повідомлень). @@ -395,8 +395,8 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві - JSON облікового запису сервісу: вбудований (`serviceAccount`) або на основі файлу (`serviceAccountFile`). - Також підтримується SecretRef облікового запису сервісу (`serviceAccountRef`). -- Резервні змінні середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- Використовуйте `spaces/` або `users/` для цілей доставки. +- Резервні варіанти через змінні середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- Використовуйте `spaces/` або `users/` як цілі доставки. - `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваним email principal (режим сумісності break-glass). ### Slack @@ -449,7 +449,7 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // use Slack native streaming API when mode=partial + nativeTransport: true, // використовувати нативний потоковий API Slack, коли mode=partial }, mediaMaxMb: 20, execApprovals: { @@ -464,39 +464,39 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві } ``` -- **Режим socket** вимагає і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` як резервний варіант змінних середовища для типового облікового запису). -- **Режим HTTP** вимагає `botToken` плюс `signingSecret` (у корені або для окремого облікового запису). -- `botToken`, `appToken`, `signingSecret` і `userToken` приймають відкриті +- **Socket mode** вимагає і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` як резервний варіант через змінні середовища для типового облікового запису). +- **HTTP mode** вимагає `botToken` разом із `signingSecret` (у корені або для окремого облікового запису). +- `botToken`, `appToken`, `signingSecret` і `userToken` приймають звичайні текстові рядки або об’єкти SecretRef. -- Знімки облікових записів Slack показують поля джерела/статусу для кожних облікових даних, такі як - `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, у режимі HTTP, +- Знімки облікових записів Slack показують поля джерела/статусу для кожного облікового + запису, такі як `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, у режимі HTTP, `signingSecretStatus`. `configured_unavailable` означає, що обліковий запис - налаштовано через SecretRef, але поточний шлях команди/runtime не зміг + налаштований через SecretRef, але поточний шлях команди/runtime не зміг визначити значення секрету. -- `configWrites: false` блокує ініційовані зі Slack записи конфігурації. -- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. -- `channels.slack.streaming.mode` — канонічний ключ режиму потокової передачі Slack. `channels.slack.streaming.nativeTransport` керує власним транспортом потокової передачі Slack. Застарілі значення `streamMode`, булеві значення `streaming` і `nativeStreaming` мігруються автоматично. -- Використовуйте `user:` (DM) або `channel:` для цілей доставки. +- `configWrites: false` блокує записи конфігурації, ініційовані Slack. +- Необов’язковий параметр `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- `channels.slack.streaming.mode` — канонічний ключ режиму потоку Slack. `channels.slack.streaming.nativeTransport` керує нативним потоковим транспортом Slack. Застарілі значення `streamMode`, булеві значення `streaming` і `nativeStreaming` автоматично мігруються. +- Використовуйте `user:` (DM) або `channel:` як цілі доставки. **Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`). -**Ізоляція сесій тредів:** `thread.historyScope` — для окремого треду (типово) або спільно на рівні каналу. `thread.inheritParent` копіює стенограму батьківського каналу в нові треди. +**Ізоляція сесій тредів:** `thread.historyScope` — окремо для кожного треду (типово) або спільно для каналу. `thread.inheritParent` копіює транскрипт батьківського каналу в нові треди. -- Власна потокова передача Slack плюс статус треду Slack у стилі assistant "is typing..." вимагають цілі відповіді у треді. DM верхнього рівня типово залишаються поза тредом, тому вони використовують `typingReaction` або звичайну доставку замість попереднього перегляду в стилі треду. -- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack під час виконання відповіді, а після завершення видаляє її. Використовуйте shortcode emoji Slack, наприклад `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: доставка підтверджень exec у стилі Slack і авторизація тих, хто може підтверджувати. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ідентифікатори користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). +- Нативний потік Slack разом із thread status у стилі Slack assistant "is typing..." вимагають ціль відповіді у треді. DM верхнього рівня типово залишаються поза тредами, тому вони використовують `typingReaction` або звичайну доставку замість попереднього перегляду у стилі треду. +- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім видаляє її після завершення. Використовуйте shortcode емодзі Slack, наприклад `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: нативна доставка схвалень exec для Slack і авторизація тих, хто схвалює. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ідентифікатори користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). -| Група дій | Типово | Примітки | -| ------------ | -------- | ------------------------ | -| reactions | увімкнено | Реакції + список реакцій | -| messages | увімкнено | Читання/надсилання/редагування/видалення | -| pins | увімкнено | Закріплення/відкріплення/список | -| memberInfo | увімкнено | Інформація про учасника | -| emojiList | увімкнено | Список власних emoji | +| Група дій | Типово увімкнено | Примітки | +| ----------- | ---------------- | ------------------------ | +| reactions | увімкнено | Реагування + список реакцій | +| messages | увімкнено | Читання/надсилання/редагування/видалення | +| pins | увімкнено | Закріплення/відкріплення/список | +| memberInfo | увімкнено | Інформація про учасника | +| emojiList | увімкнено | Список користувацьких емодзі | ### Mattermost -Mattermost постачається як plugin: `openclaw plugins install @openclaw/mattermost`. +Mattermost постачається як плагін: `openclaw plugins install @openclaw/mattermost`. ```json5 { @@ -516,7 +516,7 @@ Mattermost постачається як plugin: `openclaw plugins install @open native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Необов’язкова явна URL-адреса для розгортань із reverse proxy/публічним доступом + // Необов’язкова явна URL-адреса для reverse-proxy/public deployment callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -526,23 +526,23 @@ Mattermost постачається як plugin: `openclaw plugins install @open } ``` -Режими чату: `oncall` (відповідати на @-згадування, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з тригерного префікса). +Режими чату: `oncall` (відповідати на @-згадку, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса тригера). -Коли власні команди Mattermost увімкнені: +Коли увімкнені нативні команди Mattermost: -- `commands.callbackPath` має бути шляхом (наприклад `/api/channels/mattermost/command`), а не повною URL-адресою. -- `commands.callbackUrl` має вказувати на ендпоінт шлюзу OpenClaw і бути доступним із сервера Mattermost. -- Власні зворотні виклики slash-команд автентифікуються токенами для кожної команди окремо, які Mattermost повертає - під час реєстрації slash-команди. Якщо реєстрація не вдається або жодну - команду не активовано, OpenClaw відхиляє зворотні виклики з повідомленням +- `commands.callbackPath` має бути шляхом (наприклад, `/api/channels/mattermost/command`), а не повною URL-адресою. +- `commands.callbackUrl` має вказувати на endpoint шлюзу OpenClaw і бути доступним із сервера Mattermost. +- Нативні зворотні виклики slash-команд автентифікуються за допомогою токенів + для кожної команди, які Mattermost повертає під час реєстрації slash-команди. Якщо реєстрація не вдається або жодну + команду не активовано, OpenClaw відхиляє зворотні виклики з `Unauthorized: invalid command token.` - Для приватних/tailnet/internal хостів зворотного виклику Mattermost може вимагати, щоб `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен зворотного виклику. Використовуйте значення хоста/домену, а не повні URL-адреси. -- `channels.mattermost.configWrites`: дозволити або заборонити ініційовані з Mattermost записи конфігурації. +- `channels.mattermost.configWrites`: дозволити або заборонити записи конфігурації, ініційовані Mattermost. - `channels.mattermost.requireMention`: вимагати `@mention` перед відповіддю в каналах. -- `channels.mattermost.groups..requireMention`: перевизначення обмеження за згадкою для окремого каналу (`"*"` для типового). -- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- `channels.mattermost.groups..requireMention`: перевизначення фільтрації за згадкою для окремого каналу (`"*"` для типового значення). +- Необов’язковий параметр `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. ### Signal @@ -565,13 +565,13 @@ Mattermost постачається як plugin: `openclaw plugins install @open **Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`). -- `channels.signal.account`: прив’язати запуск каналу до конкретної ідентичності облікового запису Signal. -- `channels.signal.configWrites`: дозволити або заборонити ініційовані з Signal записи конфігурації. -- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- `channels.signal.account`: закріпити запуск каналу за конкретною ідентичністю облікового запису Signal. +- `channels.signal.configWrites`: дозволити або заборонити записи конфігурації, ініційовані Signal. +- Необов’язковий параметр `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. ### BlueBubbles -BlueBubbles — рекомендований шлях для iMessage (підтримується plugin, налаштовується в `channels.bluebubbles`). +BlueBubbles — рекомендований шлях для iMessage (на основі плагіна, налаштовується в `channels.bluebubbles`). ```json5 { @@ -580,16 +580,16 @@ BlueBubbles — рекомендований шлях для iMessage (підт enabled: true, dmPolicy: "pairing", // serverUrl, password, webhookPath, group controls, and advanced actions: - // see /channels/bluebubbles + // див. /channels/bluebubbles }, }, } ``` -- Основні шляхи ключів, які тут охоплено: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. -- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних ACP-сесій. Використовуйте дескриптор BlueBubbles або рядок цілі (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- Повну конфігурацію каналу BlueBubbles задокументовано в [BlueBubbles](/uk/channels/bluebubbles). +- Основні шляхи ключів, охоплені тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- Необов’язковий параметр `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- Елементи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних сесій ACP. Використовуйте BlueBubbles handle або цільовий рядок (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- Повну конфігурацію каналу BlueBubbles описано в [BlueBubbles](/uk/channels/bluebubbles). ### iMessage @@ -617,15 +617,15 @@ OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Демон а } ``` -- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- Необов’язковий параметр `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. -- Потрібен Full Disk Access до бази даних Messages. -- Надавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб перелічити чати. -- `cliPath` може вказувати на SSH-обгортку; задайте `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. +- Потрібен Full Disk Access до БД Messages. +- Надавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів. +- `cliPath` може вказувати на обгортку SSH; задайте `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. - `attachmentRoots` і `remoteAttachmentRoots` обмежують шляхи вхідних вкладень (типово: `/Users/*/Library/Messages/Attachments`). -- SCP використовує сувору перевірку ключа хоста, тому переконайтеся, що ключ хоста ретранслятора вже існує в `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: дозволити або заборонити ініційовані з iMessage записи конфігурації. -- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних ACP-сесій. Використовуйте нормалізований дескриптор або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- SCP використовує сувору перевірку ключа хоста, тому переконайтеся, що ключ хоста relay вже існує в `~/.ssh/known_hosts`. +- `channels.imessage.configWrites`: дозволити або заборонити записи конфігурації, ініційовані iMessage. +- Елементи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних сесій ACP. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). @@ -669,20 +669,20 @@ Matrix підтримується розширенням і налаштовує ``` - Автентифікація за токеном використовує `accessToken`; автентифікація за паролем використовує `userId` + `password`. -- `channels.matrix.proxy` спрямовує HTTP-трафік Matrix через явний HTTP(S)-proxy. Іменовані облікові записи можуть перевизначати його через `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/internal homeserver. `proxy` і цей opt-in для мережі — незалежні елементи керування. +- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явний HTTP(S)-проксі. Іменовані облікові записи можуть перевизначати його через `channels.matrix.accounts..proxy`. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/внутрішні homeserver-и. `proxy` і цей мережевий opt-in — незалежні елементи керування. - `channels.matrix.defaultAccount` вибирає бажаний обліковий запис у конфігураціях із кількома обліковими записами. -- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати й нові запрошення в стилі DM ігноруються, доки ви не встановите `autoJoin: "allowlist"` із `autoJoinAllowlist` або `autoJoin: "always"`. -- `channels.matrix.execApprovals`: доставка підтверджень exec у стилі Matrix і авторизація тих, хто може підтверджувати. - - `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі підтвердження exec активуються, коли тих, хто може підтверджувати, можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ідентифікатори користувачів Matrix (наприклад `@owner:example.org`), яким дозволено підтверджувати exec-запити. - - `agentFilter`: необов’язковий allowlist ідентифікаторів агентів. Якщо не вказано, підтвердження пересилаються для всіх агентів. +- Типове значення `channels.matrix.autoJoin` — `off`, тому запрошені кімнати та нові запрошення у стилі DM ігноруються, доки ви не встановите `autoJoin: "allowlist"` з `autoJoinAllowlist` або `autoJoin: "always"`. +- `channels.matrix.execApprovals`: нативна доставка схвалень exec для Matrix і авторизація тих, хто схвалює. + - `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі схвалення exec активуються, коли тих, хто схвалює, можна визначити з `approvers` або `commands.ownerAllowFrom`. + - `approvers`: ідентифікатори користувачів Matrix (наприклад, `@owner:example.org`), яким дозволено схвалювати запити exec. + - `agentFilter`: необов’язковий allowlist ідентифікаторів агентів. Не вказуйте, щоб пересилати схвалення для всіх агентів. - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex). - - `target`: куди надсилати запити на підтвердження. `"dm"` (типово), `"channel"` (вихідна кімната) або `"both"`. + - `target`: куди надсилати запити на схвалення. `"dm"` (типово), `"channel"` (вихідна кімната) або `"both"`. - Перевизначення для окремого облікового запису: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` визначає, як DM Matrix групуються в сесії: `per-user` (типово) спільно використовує сесію за маршрутизованим peer, тоді як `per-room` ізолює кожну DM-кімнату. -- Перевірки статусу Matrix і живі пошуки в каталозі використовують ту саму політику proxy, що й трафік runtime. -- Повну конфігурацію Matrix, правила визначення цілей і приклади налаштування задокументовано в [Matrix](/uk/channels/matrix). +- `channels.matrix.dm.sessionScope` визначає, як DM Matrix групуються в сесії: `per-user` (типово) спільно використовує маршрутизованого peer, тоді як `per-room` ізолює кожну DM-кімнату. +- Перевірки статусу Matrix і пошук у live directory використовують ту саму політику проксі, що й runtime-трафік. +- Повну конфігурацію Matrix, правила таргетингу та приклади налаштування описано в [Matrix](/uk/channels/matrix). ### Microsoft Teams @@ -695,14 +695,14 @@ Microsoft Teams підтримується розширенням і налаш enabled: true, configWrites: true, // appId, appPassword, tenantId, webhook, team/channel policies: - // see /channels/msteams + // див. /channels/msteams }, }, } ``` -- Основні шляхи ключів, які тут охоплено: `channels.msteams`, `channels.msteams.configWrites`. -- Повну конфігурацію Teams (облікові дані, webhook, політика DM/груп, перевизначення для окремих команд/каналів) задокументовано в [Microsoft Teams](/uk/channels/msteams). +- Основні шляхи ключів, охоплені тут: `channels.msteams`, `channels.msteams.configWrites`. +- Повну конфігурацію Teams (облікові дані, webhook, політику DM/груп, перевизначення для окремих team/channel) описано в [Microsoft Teams](/uk/channels/msteams). ### IRC @@ -727,13 +727,13 @@ IRC підтримується розширенням і налаштовуєт } ``` -- Основні шляхи ключів, які тут охоплено: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. -- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/обмеження за згадками) задокументовано в [IRC](/uk/channels/irc). +- Основні шляхи ключів, охоплені тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- Необов’язковий параметр `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/фільтрацію за згадкою) описано в [IRC](/uk/channels/irc). -### Багатообліковість (усі канали) +### Кілька облікових записів (усі канали) -Запускайте кілька облікових записів на канал (кожен із власним `accountId`): +Запускайте кілька облікових записів для одного каналу (кожен із власним `accountId`): ```json5 { @@ -755,27 +755,27 @@ IRC підтримується розширенням і налаштовуєт ``` - `default` використовується, коли `accountId` не вказано (CLI + маршрутизація). -- Токени змінних середовища застосовуються лише до **типового** облікового запису. -- Базові налаштування каналу застосовуються до всіх облікових записів, якщо не перевизначені для окремого облікового запису. -- Використовуйте `bindings[].match.accountId`, щоб маршрутизувати кожен обліковий запис до іншого агента. -- Якщо ви додаєте нетиповий обліковий запис через `openclaw channels add` (або онбординг каналу), поки все ще використовуєте конфігурацію каналу верхнього рівня для одного облікового запису, OpenClaw спочатку переносить значення верхнього рівня для одного облікового запису, прив’язані до облікового запису, у мапу облікових записів каналу, щоб початковий обліковий запис продовжив працювати. Більшість каналів переміщують їх у `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. -- Наявні прив’язки лише до каналу (без `accountId`) і надалі відповідають типовому обліковому запису; прив’язки з областю облікового запису залишаються необов’язковими. +- Токени з env застосовуються лише до облікового запису **default**. +- Базові налаштування каналу застосовуються до всіх облікових записів, якщо для окремих облікових записів не задано перевизначення. +- Використовуйте `bindings[].match.accountId`, щоб спрямовувати кожен обліковий запис до іншого агента. +- Якщо ви додаєте не-типовий обліковий запис через `openclaw channels add` (або під час онбордингу каналу), залишаючись при цьому на однообліковій конфігурації каналу верхнього рівня, OpenClaw спочатку переносить значення верхнього рівня для одного облікового запису, прив’язані до конкретного облікового запису, в карту облікових записів каналу, щоб початковий обліковий запис продовжив працювати. Більшість каналів переміщують їх у `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. +- Наявні прив’язки лише на рівні каналу (без `accountId`) продовжують відповідати типовому обліковому запису; прив’язки з прив’язкою до облікового запису залишаються необов’язковими. - `openclaw doctor --fix` також виправляє змішані форми, переміщуючи значення верхнього рівня для одного облікового запису, прив’язані до облікового запису, у підвищений обліковий запис, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. ### Інші канали розширень -Багато каналів розширень налаштовуються як `channels.` і задокументовані на своїх окремих сторінках каналів (наприклад Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). +Багато каналів розширень налаштовуються як `channels.` і описані на окремих сторінках каналів (наприклад, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). Див. повний індекс каналів: [Channels](/uk/channels). -### Обмеження за згадками в групових чатах +### Фільтрація за згадкою в групових чатах -Для повідомлень у групах типово **потрібна згадка** (метадані згадки або безпечні шаблони regex). Це стосується групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage. +Для повідомлень у групах типово **потрібна згадка** (метадані згадки або безпечні regex-шаблони). Це стосується групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage. **Типи згадок:** -- **Згадки в метаданих**: власні @-згадки платформи. Ігноруються в режимі self-chat WhatsApp. -- **Текстові шаблони**: безпечні шаблони regex у `agents.list[].groupChat.mentionPatterns`. Некоректні шаблони й небезпечне вкладене повторення ігноруються. -- Обмеження за згадками застосовується лише тоді, коли виявлення можливе (власні згадки або принаймні один шаблон). +- **Згадки в метаданих**: нативні @-згадки платформи. Ігноруються в режимі self-chat WhatsApp. +- **Текстові шаблони**: безпечні regex-шаблони в `agents.list[].groupChat.mentionPatterns`. Невалідні шаблони та небезпечні вкладені повторення ігноруються. +- Фільтрація за згадкою застосовується лише тоді, коли виявлення можливе (нативні згадки або принаймні один шаблон). ```json5 { @@ -788,9 +788,9 @@ IRC підтримується розширенням і налаштовуєт } ``` -`messages.groupChat.historyLimit` задає глобальне значення за замовчуванням. Канали можуть перевизначати його через `channels..historyLimit` (або для окремого облікового запису). Установіть `0`, щоб вимкнути. +`messages.groupChat.historyLimit` задає глобальне типове значення. Канали можуть перевизначати його через `channels..historyLimit` (або для окремого облікового запису). Встановіть `0`, щоб вимкнути. -#### Обмеження історії DM +#### Ліміти історії DM ```json5 { @@ -805,13 +805,13 @@ IRC підтримується розширенням і налаштовуєт } ``` -Порядок визначення: перевизначення для окремого DM → типове значення провайдера → без обмеження (зберігається все). +Порядок визначення: перевизначення для конкретного DM → типове значення провайдера → без ліміту (зберігається все). Підтримується: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. #### Режим self-chat -Додайте свій власний номер у `allowFrom`, щоб увімкнути режим self-chat (ігнорує власні @-згадки, відповідає лише на текстові шаблони): +Додайте власний номер до `allowFrom`, щоб увімкнути режим self-chat (ігнорує нативні @-згадки, відповідає лише на текстові шаблони): ```json5 { @@ -837,16 +837,16 @@ IRC підтримується розширенням і налаштовуєт ```json5 { commands: { - native: "auto", // register native commands when supported - nativeSkills: "auto", // register native skill commands when supported - text: true, // parse /commands in chat messages - bash: false, // allow ! (alias: /bash) + native: "auto", // реєструвати нативні команди, якщо підтримується + nativeSkills: "auto", // реєструвати нативні команди Skills, якщо підтримується + text: true, // розбирати /commands у повідомленнях чату + bash: false, // дозволити ! (псевдонім: /bash) bashForegroundMs: 2000, - config: false, // allow /config - mcp: false, // allow /mcp - plugins: false, // allow /plugins - debug: false, // allow /debug - restart: true, // allow /restart + gateway restart tool + config: false, // дозволити /config + mcp: false, // дозволити /mcp + plugins: false, // дозволити /plugins + debug: false, // дозволити /debug + restart: true, // дозволити /restart + інструмент перезапуску шлюзу ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -861,38 +861,38 @@ IRC підтримується розширенням і налаштовуєт -- Цей блок налаштовує поверхні команд. Для поточного каталогу вбудованих + bundled команд див. [Косі команди](/uk/tools/slash-commands). -- Ця сторінка — **довідник ключів конфігурації**, а не повний каталог команд. Команди, що належать каналу/плагіну, такі як QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` і Talk `/voice`, задокументовані на сторінках їхніх каналів/плагінів, а також у [Косі команди](/uk/tools/slash-commands). +- Цей блок налаштовує поверхні команд. Для поточного каталогу вбудованих і bundled команд див. [Slash Commands](/uk/tools/slash-commands). +- Ця сторінка — **довідник за ключами конфігурації**, а не повний каталог команд. Команди, що належать каналу/плагіну, такі як QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` і Talk `/voice`, описані на сторінках відповідних каналів/плагінів, а також у [Slash Commands](/uk/tools/slash-commands). - Текстові команди мають бути **окремими** повідомленнями з початковим `/`. -- `native: "auto"` вмикає власні команди для Discord/Telegram, а для Slack залишає їх вимкненими. -- `nativeSkills: "auto"` вмикає власні команди Skills для Discord/Telegram, а для Slack залишає їх вимкненими. +- `native: "auto"` вмикає нативні команди для Discord/Telegram, залишає Slack вимкненим. +- `nativeSkills: "auto"` вмикає нативні команди Skills для Discord/Telegram, залишає Slack вимкненим. - Перевизначення для окремого каналу: `channels.discord.commands.native` (bool або `"auto"`). `false` очищає раніше зареєстровані команди. -- Перевизначайте реєстрацію власних команд Skills для окремого каналу через `channels..commands.nativeSkills`. +- Перевизначуйте реєстрацію нативних команд Skills для окремого каналу через `channels..commands.nativeSkills`. - `channels.telegram.customCommands` додає додаткові записи меню бота Telegram. -- `bash: true` вмикає `! ` для командної оболонки хоста. Потрібні `tools.elevated.enabled` і відправник у `tools.elevated.allowFrom.`. -- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів шлюзу `chat.send` постійні записи `/config set|unset` також потребують `operator.admin`; доступний лише для читання `/config show` залишається доступним для звичайних клієнтів оператора з правами запису. -- `mcp: true` вмикає `/mcp` для конфігурації MCP-сервера, яким керує OpenClaw, у `mcp.servers`. -- `plugins: true` вмикає `/plugins` для виявлення plugin, встановлення та елементів керування ввімкненням/вимкненням. -- `channels..configWrites` обмежує зміни конфігурації для окремого каналу (типово: true). -- Для багатооблікових каналів `channels..accounts..configWrites` також обмежує записи, що спрямовані на цей обліковий запис (наприклад `/allowlist --config --account ` або `/config set channels..accounts....`). +- `bash: true` вмикає `! ` для оболонки хоста. Потрібні `tools.elevated.enabled` і відправник у `tools.elevated.allowFrom.`. +- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів шлюзу `chat.send` постійні записи `/config set|unset` також вимагають `operator.admin`; доступний лише для читання `/config show` залишається доступним для звичайних клієнтів оператора з правами запису. +- `mcp: true` вмикає `/mcp` для конфігурації MCP-серверів під керуванням OpenClaw у `mcp.servers`. +- `plugins: true` вмикає `/plugins` для виявлення, встановлення, увімкнення та вимкнення плагінів. +- `channels..configWrites` керує мутаціями конфігурації для кожного каналу (типово: true). +- Для каналів із кількома обліковими записами `channels..accounts..configWrites` також керує записами, що спрямовані на цей обліковий запис (наприклад, `/allowlist --config --account ` або `/config set channels..accounts....`). - `restart: false` вимикає `/restart` і дії інструмента перезапуску шлюзу. Типове значення: `true`. -- `ownerAllowFrom` — явний список дозволених власників для команд/інструментів лише для власника. Він окремий від `allowFrom`. +- `ownerAllowFrom` — це явний allowlist власника для команд/інструментів лише для власника. Він відокремлений від `allowFrom`. - `ownerDisplay: "hash"` хешує ідентифікатори власника в системному запиті. Установіть `ownerDisplaySecret`, щоб керувати хешуванням. -- `allowFrom` задається окремо для кожного провайдера. Якщо його встановлено, це **єдине** джерело авторизації (списки дозволених каналів/спарювання і `useAccessGroups` ігноруються). -- `useAccessGroups: false` дозволяє командам обходити політики access-group, коли `allowFrom` не встановлено. -- Карта документації команд: - - каталог вбудованих + bundled: [Косі команди](/uk/tools/slash-commands) - - поверхні команд, специфічні для каналів: [Channels](/uk/channels) +- `allowFrom` є окремим для кожного провайдера. Якщо його встановлено, це **єдине** джерело авторизації (allowlist/pairing каналу і `useAccessGroups` ігноруються). +- `useAccessGroups: false` дозволяє командам обходити політики груп доступу, коли `allowFrom` не встановлено. +- Відповідність документації по командах: + - каталог вбудованих і bundled команд: [Slash Commands](/uk/tools/slash-commands) + - поверхні команд, специфічні для каналу: [Channels](/uk/channels) - команди QQ Bot: [QQ Bot](/uk/channels/qqbot) - - команди спарювання: [Pairing](/uk/channels/pairing) + - команди pairing: [Pairing](/uk/channels/pairing) - команда картки LINE: [LINE](/uk/channels/line) - - dreaming пам’яті: [Dreaming](/uk/concepts/dreaming) + - memory dreaming: [Dreaming](/uk/concepts/dreaming) --- -## Типові значення агента +## Типові значення агентів ### `agents.defaults.workspace` @@ -906,7 +906,7 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.repoRoot` -Необов’язковий корінь репозиторію, що показується в рядку Runtime системного запиту. Якщо не встановлено, OpenClaw автоматично визначає його, піднімаючись угору від робочого простору. +Необов’язковий корінь репозиторію, що показується в рядку Runtime системного запиту. Якщо не встановлено, OpenClaw автоматично визначає його, підіймаючись угору від workspace. ```json5 { @@ -916,7 +916,7 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.skills` -Необов’язковий типовий список дозволених Skills для агентів, які не задають +Необов’язковий типовий allowlist Skills для агентів, які не задають `agents.list[].skills`. ```json5 @@ -934,13 +934,13 @@ IRC підтримується розширенням і налаштовуєт - Не вказуйте `agents.defaults.skills`, щоб типово дозволити необмежені Skills. - Не вказуйте `agents.list[].skills`, щоб успадкувати типові значення. -- Встановіть `agents.list[].skills: []`, щоб не дозволяти жодних Skills. -- Непорожній список `agents.list[].skills` є остаточним набором для цього агента; він +- Установіть `agents.list[].skills: []`, щоб не дозволити жодних Skills. +- Непорожній список `agents.list[].skills` є фінальним набором для цього агента; він не об’єднується з типовими значеннями. ### `agents.defaults.skipBootstrap` -Вимикає автоматичне створення bootstrap-файлів робочого простору (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). +Вимикає автоматичне створення bootstrap-файлів workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). ```json5 { @@ -950,9 +950,9 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.contextInjection` -Керує тим, коли bootstrap-файли робочого простору вставляються в системний запит. Типове значення: `"always"`. +Керує тим, коли bootstrap-файли workspace вбудовуються в системний запит. Типове значення: `"always"`. -- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторну вставку bootstrap робочого простору, зменшуючи розмір запиту. Запуски heartbeat і повторні спроби після ущільнення все одно перебудовують контекст. +- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне вбудовування bootstrap workspace, зменшуючи розмір запиту. Запуски heartbeat і повторні спроби після ущільнення все одно перебудовують контекст. ```json5 { @@ -962,7 +962,7 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.bootstrapMaxChars` -Максимальна кількість символів на bootstrap-файл робочого простору перед обрізанням. Типове значення: `20000`. +Максимальна кількість символів на один bootstrap-файл workspace перед обрізанням. Типове значення: `20000`. ```json5 { @@ -972,7 +972,7 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.bootstrapTotalMaxChars` -Максимальна загальна кількість символів, що вставляються в усі bootstrap-файли робочого простору. Типове значення: `150000`. +Максимальна загальна кількість символів, що вбудовується в усі bootstrap-файли workspace. Типове значення: `150000`. ```json5 { @@ -985,9 +985,9 @@ IRC підтримується розширенням і налаштовуєт Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізається. Типове значення: `"once"`. -- `"off"`: ніколи не вставляти текст попередження в системний запит. -- `"once"`: вставляти попередження один раз для кожного унікального сигнатурного варіанта обрізання (рекомендовано). -- `"always"`: вставляти попередження під час кожного запуску, коли є обрізання. +- `"off"`: ніколи не вбудовувати текст попередження в системний запит. +- `"once"`: вбудовувати попередження один раз для кожного унікального сигнатурного обрізання (рекомендовано). +- `"always"`: вбудовувати попередження під час кожного запуску, коли є обрізання. ```json5 { @@ -997,10 +997,10 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.imageMaxDimensionPx` -Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень стенограми/інструментів перед викликами провайдера. +Максимальний розмір у пікселях для найдовшої сторони зображення в блоках зображень transcript/tool перед викликами провайдера. Типове значення: `1200`. -Нижчі значення зазвичай зменшують використання vision-token і розмір корисного навантаження запиту для запусків із великою кількістю знімків екрана. +Нижчі значення зазвичай зменшують використання vision-токенів і розмір payload запиту для запусків із великою кількістю скриншотів. Вищі значення зберігають більше візуальних деталей. ```json5 @@ -1011,7 +1011,7 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.userTimezone` -Часовий пояс для контексту системного запиту (не для часових міток повідомлень). Якщо не встановлено, використовується часовий пояс хоста. +Часовий пояс для контексту системного запиту (не для часових міток повідомлень). Якщо не задано, використовується часовий пояс хоста. ```json5 { @@ -1060,6 +1060,10 @@ IRC підтримується розширенням і налаштовуєт fallbacks: ["openai/gpt-5.4-mini"], }, params: { cacheRetention: "long" }, // глобальні типові параметри провайдера + embeddedHarness: { + runtime: "auto", // auto | pi | registered harness id, e.g. codex + fallback: "pi", // pi | none + }, pdfMaxBytesMb: 10, pdfMaxPages: 20, thinkingDefault: "low", @@ -1076,43 +1080,71 @@ IRC підтримується розширенням і налаштовуєт - `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Форма рядка задає лише основну модель. - - Форма об’єкта задає основну модель і впорядкований список резервних моделей для failover. + - Форма об’єкта задає основну модель плюс упорядковані моделі для аварійного перемикання. - `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується шляхом інструмента `image` як його конфігурація vision-model. + - Використовується шляхом інструмента `image` як його конфігурація vision-моделі. - Також використовується для резервної маршрутизації, коли вибрана/типова модель не може приймати вхідні зображення. - `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструмента/plugin, що генерує зображення. + - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструментів/плагінів, що генерує зображення. - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal або `openai/gpt-image-1` для OpenAI Images. - - Якщо ви вибираєте `provider/model` напряму, також налаштуйте відповідну автентифікацію/API key провайдера (наприклад `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). - - Якщо параметр пропущено, `image_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточний типовий провайдер, а потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id. + - Якщо ви безпосередньо вибираєте provider/model, також налаштуйте відповідну автентифікацію провайдера/API key (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). + - Якщо не вказано, `image_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації зображень у порядку provider-id. - `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується спільною можливістю генерації музики і вбудованим інструментом `music_generate`. + - Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`. - Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.5+`. - - Якщо параметр пропущено, `music_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточний типовий провайдер, а потім решту зареєстрованих провайдерів генерації музики в порядку provider-id. - - Якщо ви вибираєте `provider/model` напряму, також налаштуйте відповідну автентифікацію/API key провайдера. + - Якщо не вказано, `music_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації музики в порядку provider-id. + - Якщо ви безпосередньо вибираєте provider/model, також налаштуйте відповідну автентифікацію провайдера/API key. - `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується спільною можливістю генерації відео і вбудованим інструментом `video_generate`. + - Використовується спільною можливістю генерації відео та вбудованим інструментом `video_generate`. - Типові значення: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` або `qwen/wan2.7-r2v`. - - Якщо параметр пропущено, `video_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточний типовий провайдер, а потім решту зареєстрованих провайдерів генерації відео в порядку provider-id. - - Якщо ви вибираєте `provider/model` напряму, також налаштуйте відповідну автентифікацію/API key провайдера. - - Bundled провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. + - Якщо не вказано, `video_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації відео в порядку provider-id. + - Якщо ви безпосередньо вибираєте provider/model, також налаштуйте відповідну автентифікацію провайдера/API key. + - Вбудований провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. - `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується інструментом `pdf` для маршрутизації моделей. - - Якщо параметр пропущено, інструмент PDF повертається до `imageModel`, а потім до визначеної моделі сесії/типової моделі. -- `pdfMaxBytesMb`: типове обмеження розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. -- `pdfMaxPages`: типова максимальна кількість сторінок, яка враховується в режимі резервного вилучення для інструмента `pdf`. + - Використовується інструментом `pdf` для маршрутизації моделі. + - Якщо не вказано, інструмент PDF повертається до `imageModel`, а потім — до визначеної моделі сесії/типової моделі. +- `pdfMaxBytesMb`: типовий ліміт розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. +- `pdfMaxPages`: типова максимальна кількість сторінок, яку враховує режим резервного витягування в інструменті `pdf`. - `verboseDefault`: типовий рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. Типове значення: `"off"`. - `elevatedDefault`: типовий рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типове значення: `"on"`. -- `model.primary`: формат `provider/model` (наприклад `openai/gpt-5.4`). Якщо ви пропускаєте провайдера, OpenClaw спочатку пробує псевдонім, потім — унікальний збіг налаштованого провайдера для цього точного id моделі, і лише після цього повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому краще явно вказувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повертається до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле типове значення видаленого провайдера. -- `models`: налаштований каталог моделей і allowlist для `/model`. Кожен запис може включати `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад `{ cacheRetention: "long" }`). +- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.4`). Якщо ви пропускаєте провайдера, OpenClaw спочатку пробує псевдонім, потім — унікальний збіг exact model id серед налаштованих провайдерів, і лише після цього повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому краще явно вказувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повертається до першого налаштованого provider/model замість того, щоб показувати застаріле типове значення видаленого провайдера. +- `models`: налаштований каталог моделей і allowlist для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`). +- `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`). - Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для окремої моделі), а потім `agents.list[].params` (для відповідного id агента) перевизначає за ключем. Докладніше див. у [Prompt Caching](/uk/reference/prompt-caching). -- Засоби запису конфігурації, які змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення резервних моделей), зберігають канонічну форму об’єкта і, коли можливо, зберігають наявні списки резервних моделей. -- `maxConcurrent`: максимальна кількість паралельних запусків агентів у різних сесіях (кожна сесія все одно серіалізується). Типове значення: 4. +- `embeddedHarness`: типова політика низькорівневого runtime для вбудованого агента. Використовуйте `runtime: "auto"`, щоб дозволити зареєстрованим harness плагінів перехоплювати підтримувані моделі, `runtime: "pi"` — щоб примусово використовувати вбудований harness PI, або зареєстрований id harness, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід на PI. +- Засоби запису конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну форму об’єкта та, коли можливо, зберігають наявні списки fallback. +- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізується). Типове значення: 4. -**Вбудовані скорочення псевдонімів** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): +### `agents.defaults.embeddedHarness` -| Псевдонім | Модель | +`embeddedHarness` керує тим, який низькорівневий виконавець запускає ходи вбудованого агента. +Більшості розгортань слід залишити типове значення `{ runtime: "auto", fallback: "pi" }`. +Використовуйте його, коли довірений плагін надає нативний harness, наприклад bundled +harness app-server Codex. + +```json5 +{ + agents: { + defaults: { + model: "codex/gpt-5.4", + embeddedHarness: { + runtime: "codex", + fallback: "none", + }, + }, + }, +} +``` + +- `runtime`: `"auto"`, `"pi"` або id зареєстрованого harness плагіна. Bundled плагін Codex реєструє `codex`. +- `fallback`: `"pi"` або `"none"`. `"pi"` зберігає вбудований harness PI як резервний варіант сумісності. `"none"` призводить до помилки, якщо вибраний harness плагіна відсутній або не підтримується, замість тихого використання PI. +- Перевизначення через середовище: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` вимикає резервний перехід на PI для цього процесу. +- Для розгортань лише з Codex встановіть `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`. +- Це керує лише вбудованим chat harness. Генерація медіа, vision, PDF, музика, відео й TTS, як і раніше, використовують свої налаштування provider/model. + +**Вбудовані скорочення alias** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): + +| Alias | Модель | | ------------------- | -------------------------------------- | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | @@ -1123,15 +1155,15 @@ IRC підтримується розширенням і налаштовуєт | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Ваші налаштовані псевдоніми завжди мають пріоритет над типовими. +Ваші налаштовані alias завжди мають пріоритет над типовими. -Моделі Z.AI GLM-4.x автоматично вмикають режим thinking, якщо ви не задасте `--thinking off` або самі не визначите `agents.defaults.models["zai/"].params.thinking`. +Моделі Z.AI GLM-4.x автоматично вмикають режим thinking, якщо ви не встановите `--thinking off` або самі не задасте `agents.defaults.models["zai/"].params.thinking`. Моделі Z.AI типово вмикають `tool_stream` для потокової передачі викликів інструментів. Установіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це. -Для моделей Anthropic Claude 4.6 типово використовується thinking `adaptive`, якщо явний рівень thinking не задано. +Для моделей Anthropic Claude 4.6 типово використовується `adaptive` thinking, якщо явний рівень thinking не задано. ### `agents.defaults.cliBackends` -Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери не працюють. +Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери відмовляють. ```json5 { @@ -1161,7 +1193,7 @@ IRC підтримується розширенням і налаштовуєт - CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнені. - Сесії підтримуються, коли задано `sessionArg`. -- Пряма передача зображень підтримується, коли `imageArg` приймає шляхи до файлів. +- Наскрізна передача зображень підтримується, коли `imageArg` приймає шляхи до файлів. ### `agents.defaults.systemPromptOverride` @@ -1186,16 +1218,16 @@ IRC підтримується розширенням і налаштовуєт agents: { defaults: { heartbeat: { - every: "30m", // 0m disables + every: "30m", // 0m вимикає model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt - lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files - isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) + includeSystemPromptSection: true, // типово: true; false пропускає розділ Heartbeat із системного запиту + lightContext: false, // типово: false; true залишає лише HEARTBEAT.md із bootstrap-файлів workspace + isolatedSession: false, // типово: false; true запускає кожен heartbeat у свіжій сесії (без історії розмови) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (default) | block - target: "none", // default: none | options: last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow (типово) | block + target: "none", // типово: none | варіанти: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -1205,14 +1237,14 @@ IRC підтримується розширенням і налаштовуєт } ``` -- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація API key) або `1h` (автентифікація OAuth). Установіть `0m`, щоб вимкнути. -- `includeSystemPromptSection`: коли значення false, розділ Heartbeat не додається до системного запиту, а `HEARTBEAT.md` не вставляється в bootstrap-контекст. Типове значення: `true`. -- `suppressToolErrorWarnings`: коли значення true, попереджувальні payload-и помилок інструментів пригнічуються під час запусків heartbeat. -- `directPolicy`: політика прямої доставки/DM. `allow` (типово) дозволяє доставку напряму до цілі. `block` пригнічує пряму доставку до цілі та видає `reason=dm-blocked`. -- `lightContext`: коли значення true, запуски heartbeat використовують полегшений bootstrap-контекст і залишають із bootstrap-файлів робочого простору лише `HEARTBEAT.md`. -- `isolatedSession`: коли значення true, кожен heartbeat запускається в новій сесії без попередньої історії розмови. Та сама схема ізоляції, що й у cron `sessionTarget: "isolated"`. Зменшує вартість токенів на heartbeat приблизно зі ~100K до ~2-5K токенів. -- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, запуски heartbeat виконуються **лише для цих агентів**. -- Heartbeat виконує повні ходи агента — коротші інтервали спалюють більше токенів. +- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API key) або `1h` (автентифікація через OAuth). Установіть `0m`, щоб вимкнути. +- `includeSystemPromptSection`: якщо false, пропускає розділ Heartbeat із системного запиту та не вбудовує `HEARTBEAT.md` у bootstrap-контекст. Типове значення: `true`. +- `suppressToolErrorWarnings`: якщо true, пригнічує payload попереджень про помилки інструментів під час запусків heartbeat. +- `directPolicy`: політика прямої/DM-доставки. `allow` (типово) дозволяє доставку на пряму ціль. `block` пригнічує доставку на пряму ціль і видає `reason=dm-blocked`. +- `lightContext`: якщо true, запуски heartbeat використовують полегшений bootstrap-контекст і залишають лише `HEARTBEAT.md` із bootstrap-файлів workspace. +- `isolatedSession`: якщо true, кожен heartbeat запускається в новій сесії без попередньої історії розмови. Та сама схема ізоляції, що й для cron `sessionTarget: "isolated"`. Зменшує витрати токенів на один heartbeat приблизно зі ~100K до ~2-5K токенів. +- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, heartbeat запускаються **лише для цих агентів**. +- Heartbeat запускають повні ходи агента — коротші інтервали спалюють більше токенів. ### `agents.defaults.compaction` @@ -1222,19 +1254,19 @@ IRC підтримується розширенням і налаштовуєт defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id of a registered compaction provider plugin (optional) + provider: "my-provider", // id зареєстрованого compaction provider plugin (необов’язково) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection - model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override - notifyUser: true, // send a brief notice when compaction starts (default: false) + identifierInstructions: "Зберігайте deployment ID, ticket ID і пари host:port точно без змін.", // використовується, коли identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторне вбудовування + model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для compaction + notifyUser: true, // надсилати коротке сповіщення, коли починається compaction (типово: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "Session nearing compaction. Store durable memories now.", - prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", + systemPrompt: "Сесія наближається до compaction. Збережіть довготривалу пам’ять зараз.", + prompt: "Запишіть будь-які тривалі нотатки в memory/YYYY-MM-DD.md; якщо зберігати нічого, дайте відповідь точним тихим токеном NO_REPLY.", }, }, }, @@ -1242,15 +1274,15 @@ IRC підтримується розширенням і налаштовуєт } ``` -- `mode`: `default` або `safeguard` (підсумовування довгих історій частинами). Див. [Compaction](/uk/concepts/compaction). -- `provider`: id зареєстрованого plugin провайдера compaction. Якщо задано, замість вбудованого підсумовування LLM викликається `summarize()` провайдера. У разі збою використовується вбудований варіант. Установлення провайдера примусово задає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). +- `mode`: `default` або `safeguard` (підсумовування великих історій частинами). Див. [Compaction](/uk/concepts/compaction). +- `provider`: id зареєстрованого compaction provider plugin. Якщо задано, замість вбудованого підсумовування LLM викликається `summarize()` цього провайдера. У разі помилки повертається до вбудованого механізму. Встановлення провайдера примушує `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). - `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції compaction, після чого OpenClaw її перериває. Типове значення: `900`. -- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час підсумовування compaction. -- `identifierInstructions`: необов’язковий власний текст щодо збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. -- `postCompactionSections`: необов’язкові назви секцій H2/H3 з AGENTS.md, які повторно вставляються після compaction. Типово: `["Session Startup", "Red Lines"]`; установіть `[]`, щоб вимкнути повторну вставку. Якщо значення не задано або явно встановлено цю типову пару, старіші заголовки `Every Session`/`Safety` також приймаються як резервний варіант для сумісності. +- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів перед підсумовуванням compaction. +- `identifierInstructions`: необов’язковий користувацький текст щодо збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. +- `postCompactionSections`: необов’язкові назви секцій H2/H3 з AGENTS.md для повторного вбудовування після compaction. Типове значення — `["Session Startup", "Red Lines"]`; встановіть `[]`, щоб вимкнути повторне вбудовування. Коли не задано або явно встановлено цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як застарілий резервний варіант. - `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування compaction. Використовуйте це, коли основна сесія має залишатися на одній моделі, а підсумки compaction повинні виконуватися на іншій; якщо не задано, compaction використовує основну модель сесії. -- `notifyUser`: коли `true`, надсилає користувачу коротке сповіщення на початку compaction (наприклад, "Compacting context..."). Типово вимкнено, щоб compaction залишався безшумним. -- `memoryFlush`: тихий агентний хід перед автоматичним compaction для збереження довготривалих спогадів. Пропускається, якщо робочий простір доступний лише для читання. +- `notifyUser`: якщо `true`, надсилає користувачу коротке сповіщення, коли починається compaction (наприклад, "Compacting context..."). Типово вимкнено, щоб compaction залишався тихим. +- `memoryFlush`: тихий агентний хід перед auto-compaction для збереження довготривалої пам’яті. Пропускається, коли workspace доступний лише для читання. ### `agents.defaults.contextPruning` @@ -1262,13 +1294,13 @@ IRC підтримується розширенням і налаштовуєт defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // duration (ms/s/m/h), default unit: minutes + ttl: "1h", // тривалість (ms/s/m/h), типова одиниця: хвилини keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }, + hardClear: { enabled: true, placeholder: "[Вміст старого результату інструмента очищено]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1279,24 +1311,24 @@ IRC підтримується розширенням і налаштовуєт - `mode: "cache-ttl"` вмикає проходи обрізання. -- `ttl` визначає, як часто обрізання може запускатися знову (після останнього торкання кешу). -- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім, за потреби, повністю очищає старіші результати інструментів. +- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього торкання кешу). +- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім, за потреби, жорстко очищує старіші результати інструментів. **М’яке обрізання** зберігає початок і кінець та вставляє `...` посередині. -**Повне очищення** замінює весь результат інструмента на заповнювач. +**Жорстке очищення** замінює весь результат інструмента заповнювачем. Примітки: -- Блоки зображень ніколи не обрізаються й не очищаються. -- Співвідношення рахуються за символами (приблизно), а не за точною кількістю токенів. -- Якщо повідомлень assistant менше, ніж `keepLastAssistants`, обрізання пропускається. +- Блоки зображень ніколи не обрізаються й не очищуються. +- Співвідношення базуються на символах (приблизно), а не на точній кількості токенів. +- Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, обрізання пропускається. -Див. [Session Pruning](/uk/concepts/session-pruning) для подробиць поведінки. +Докладніше про поведінку див. у [Session Pruning](/uk/concepts/session-pruning). -### Блокова потокова передача +### Block streaming ```json5 { @@ -1306,17 +1338,17 @@ IRC підтримується розширенням і налаштовуєт blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) + humanDelay: { mode: "natural" }, // off | natural | custom (використовуйте minMs/maxMs) }, }, } ``` -- Канали, відмінні від Telegram, вимагають явного `*.blockStreaming: true`, щоб увімкнути блокові відповіді. -- Перевизначення для каналів: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типово `minChars: 1500`. -- `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500ms. Перевизначення для окремого агента: `agents.list[].humanDelay`. +- Для каналів, відмінних від Telegram, потрібно явно вказати `*.blockStreaming: true`, щоб увімкнути block replies. +- Перевизначення для каналів: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типове значення `minChars: 1500`. +- `humanDelay`: випадкова пауза між block replies. `natural` = 800–2500 мс. Перевизначення для окремого агента: `agents.list[].humanDelay`. -Див. [Streaming](/uk/concepts/streaming) для подробиць поведінки й розбиття на частини. +Докладніше про поведінку та chunking див. у [Streaming](/uk/concepts/streaming). ### Індикатори набору тексту @@ -1340,7 +1372,7 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.sandbox` -Необов’язкова ізоляція для вбудованого агента. Повний посібник див. в [Sandboxing](/uk/gateway/sandboxing). +Необов’язкова sandbox-ізоляція для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). ```json5 { @@ -1386,7 +1418,7 @@ IRC підтримується розширенням і налаштовуєт identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRefs / inline contents also supported: + // Також підтримуються SecretRef / вбудований вміст: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1437,52 +1469,52 @@ IRC підтримується розширенням і налаштовуєт -**Бекенд:** +**Backend:** - `docker`: локальний runtime Docker (типово) -- `ssh`: універсальний віддалений runtime на основі SSH +- `ssh`: загальний віддалений runtime на основі SSH - `openshell`: runtime OpenShell Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переносяться до `plugins.entries.openshell.config`. -**Конфігурація SSH-бекенда:** +**Конфігурація backend SSH:** -- `target`: SSH-ціль у форматі `user@host[:port]` -- `command`: команда SSH-клієнта (типово: `ssh`) -- `workspaceRoot`: абсолютний віддалений корінь, що використовується для робочих просторів у межах scope -- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, передані до OpenSSH +- `target`: ціль SSH у форматі `user@host[:port]` +- `command`: команда клієнта SSH (типово: `ssh`) +- `workspaceRoot`: абсолютний віддалений корінь, що використовується для workspace з урахуванням scope +- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, які передаються до OpenSSH - `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує у тимчасові файли під час runtime -- `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хостів OpenSSH +- `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH **Пріоритет автентифікації SSH:** - `identityData` має пріоритет над `identityFile` - `certificateData` має пріоритет над `certificateFile` - `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data`, що використовують SecretRef, визначаються з активного знімка runtime секретів до початку sandbox-сесії +- Значення `*Data`, що базуються на SecretRef, визначаються з активного знімка runtime секретів перед початком сесії sandbox -**Поведінка SSH-бекенда:** +**Поведінка backend SSH:** -- один раз ініціалізує віддалений робочий простір після створення або повторного створення -- потім зберігає віддалений SSH-робочий простір як канонічний -- маршрутизує `exec`, файлові інструменти й media-шляхи через SSH +- ініціалізує віддалений workspace один раз після створення або перевідтворення +- потім підтримує віддалений workspace як канонічний +- маршрутизує `exec`, файлові інструменти та медіашляхи через SSH - не синхронізує віддалені зміни назад на хост автоматично -- не підтримує browser-контейнери в sandbox +- не підтримує browser containers у sandbox -**Доступ до робочого простору:** +**Доступ до workspace:** -- `none`: робочий простір sandbox для кожного scope у `~/.openclaw/sandboxes` -- `ro`: робочий простір sandbox у `/workspace`, робочий простір агента змонтовано лише для читання в `/agent` -- `rw`: робочий простір агента змонтовано для читання/запису в `/workspace` +- `none`: workspace sandbox для кожного scope у `~/.openclaw/sandboxes` +- `ro`: workspace sandbox у `/workspace`, workspace агента монтується тільки для читання в `/agent` +- `rw`: workspace агента монтується для читання/запису в `/workspace` **Scope:** -- `session`: окремий контейнер + робочий простір для кожної сесії -- `agent`: один контейнер + робочий простір на агента (типово) -- `shared`: спільний контейнер і робочий простір (без ізоляції між сесіями) +- `session`: окремий контейнер + workspace для кожної сесії +- `agent`: один контейнер + workspace на агента (типово) +- `shared`: спільний контейнер і workspace (без ізоляції між сесіями) -**Конфігурація plugin OpenShell:** +**Конфігурація плагіна OpenShell:** ```json5 { @@ -1495,10 +1527,10 @@ IRC підтримується розширенням і налаштовуєт from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // optional - gatewayEndpoint: "https://lab.example", // optional - policy: "strict", // optional OpenShell policy id - providers: ["openai"], // optional + gateway: "lab", // необов’язково + gatewayEndpoint: "https://lab.example", // необов’язково + policy: "strict", // необов’язковий id політики OpenShell + providers: ["openai"], // необов’язково autoProviders: true, timeoutSeconds: 120, }, @@ -1510,30 +1542,30 @@ IRC підтримується розширенням і налаштовуєт **Режим OpenShell:** -- `mirror`: ініціалізувати віддалений простір із локального перед `exec`, синхронізувати назад після `exec`; локальний робочий простір залишається канонічним -- `remote`: один раз ініціалізувати віддалений простір, коли sandbox створюється, а потім зберігати віддалений робочий простір як канонічний +- `mirror`: ініціалізувати віддалене середовище з локального перед `exec`, синхронізувати назад після `exec`; локальний workspace залишається канонічним +- `remote`: ініціалізувати віддалене середовище один раз під час створення sandbox, після чого віддалений workspace залишається канонічним -У режимі `remote` локальні редагування на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку ініціалізації. -Транспортом є SSH до sandbox OpenShell, але plugin володіє життєвим циклом sandbox і необов’язковою дзеркальною синхронізацією. +У режимі `remote` редагування на локальному хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку ініціалізації. +Транспортом є SSH до sandbox OpenShell, але плагін володіє життєвим циклом sandbox і необов’язковою mirror-синхронізацією. -**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує виходу в мережу, записуваного кореня та користувача root. +**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потрібні вихід у мережу, доступний для запису root і користувач root. -**Контейнери типово використовують `network: "none"`** — установіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. -`"host"` заблоковано. `"container:"` типово також заблоковано, якщо ви явно не встановите +**Для контейнерів типово використовується `network: "none"`** — встановіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. +`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (режим break-glass). -**Вхідні вкладення** розміщуються в `media/inbound/*` в активному робочому просторі. +**Вхідні вкладення** розміщуються в `media/inbound/*` в активному workspace. **`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для окремого агента об’єднуються. -**Browser у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вставляється в системний запит. Не потребує `browser.enabled` у `openclaw.json`. -Доступ спостерігача через noVNC типово використовує автентифікацію VNC, а OpenClaw видає URL із короткоживучим токеном (замість того, щоб показувати пароль у спільному URL). +**Browser у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в системний запит. Не потребує `browser.enabled` в `openclaw.json`. +Доступ спостерігача через noVNC типово використовує VNC-автентифікацію, а OpenClaw видає URL із короткоживучим токеном (замість розкриття пароля в спільному URL). - `allowHostControl: false` (типово) блокує націлювання sandbox-сесій на браузер хоста. -- `network` типово має значення `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge` лише тоді, коли вам явно потрібна глобальна зв’язність bridge. -- `cdpSourceRange` необов’язково обмежує вхідний CDP-трафік на межі контейнера до діапазону CIDR (наприклад `172.21.0.1/32`). -- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер browser sandbox. Якщо параметр задано (включно з `[]`), він замінює `docker.binds` для контейнера browser. -- Типові параметри запуску визначені в `scripts/sandbox-browser-entrypoint.sh` і налаштовані для хостів контейнерів: +- `network` типово дорівнює `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge` лише тоді, коли вам явно потрібна глобальна підключеність bridge. +- `cdpSourceRange` необов’язково обмежує вхідний CDP-трафік на межі контейнера діапазоном CIDR (наприклад, `172.21.0.1/32`). +- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера sandbox. Якщо задано (включно з `[]`), воно замінює `docker.binds` для контейнера браузера. +- Типові параметри запуску визначені в `scripts/sandbox-browser-entrypoint.sh` і налаштовані для контейнерних хостів: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1550,29 +1582,28 @@ IRC підтримується розширенням і налаштовуєт - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - `--disable-extensions` (типово ввімкнено) + - `--disable-extensions` (типово увімкнено) - `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu` - типово ввімкнені й можуть бути вимкнені через + типово увімкнені та можуть бути вимкнені через `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо для WebGL/3D це потрібно. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо ваш робочий процес - від них залежить. + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо ваш workflow + залежить від них. - `--renderer-process-limit=2` можна змінити через - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використати + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати типове обмеження процесів Chromium. - - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`. - - Типові значення — це базовий рівень образу контейнера; щоб змінити типові параметри контейнера, - використовуйте власний образ browser із власним - entrypoint. + - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли увімкнено `noSandbox`. + - Типові значення є базовими значеннями образу контейнера; щоб змінити типові значення контейнера, використовуйте власний + образ браузера з власним entrypoint. -Browser sandboxing і `sandbox.docker.binds` доступні лише для Docker. +Ізоляція browser у sandbox і `sandbox.docker.binds` доступні лише для Docker. -Зібрати образи: +Зберіть образи: ```bash scripts/sandbox-setup.sh # основний образ sandbox -scripts/sandbox-browser-setup.sh # необов’язковий образ browser +scripts/sandbox-browser-setup.sh # необов’язковий образ браузера ``` ### `agents.list` (перевизначення для окремого агента) @@ -1587,12 +1618,13 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } - thinkingDefault: "high", // per-agent thinking level override - reasoningDefault: "on", // per-agent reasoning visibility override - fastModeDefault: false, // per-agent fast mode override - params: { cacheRetention: "none" }, // overrides matching defaults.models params by key - skills: ["docs-search"], // replaces agents.defaults.skills when set + model: "anthropic/claude-opus-4-6", // або { primary, fallbacks } + thinkingDefault: "high", // перевизначення типового рівня thinking для окремого агента + reasoningDefault: "on", // перевизначення типової видимості reasoning для окремого агента + fastModeDefault: false, // перевизначення типового fast mode для окремого агента + embeddedHarness: { runtime: "auto", fallback: "pi" }, + params: { cacheRetention: "none" }, // перевизначає ключі відповідних params із defaults.models + skills: ["docs-search"], // замінює agents.defaults.skills, якщо задано identity: { name: "Samantha", theme: "helpful sloth", @@ -1624,25 +1656,26 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br ``` - `id`: стабільний id агента (обов’язково). -- `default`: якщо встановлено для кількох агентів, перший має пріоритет (записується попередження). Якщо не встановлено ніде, типовим стає перший запис у списку. -- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні резервні моделі). Завдання cron, які перевизначають лише `primary`, усе одно успадковують типові резервні моделі, якщо ви не встановите `fallbacks: []`. -- `params`: параметри потоку для окремого агента, що зливаються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень, специфічних для агента, як-от `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. -- `skills`: необов’язковий allowlist Skills для окремого агента. Якщо не задано, агент успадковує `agents.defaults.skills`, коли його встановлено; явний список замінює типові значення замість злиття, а `[]` означає відсутність Skills. +- `default`: якщо задано кілька, перемагає перший (записується попередження). Якщо не задано жодного, типовим є перший запис у списку. +- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallbacks). Cron jobs, які перевизначають лише `primary`, усе одно успадковують типові fallbacks, якщо ви не встановите `fallbacks: []`. +- `params`: параметри потоку для окремого агента, об’єднані поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для специфічних для агента перевизначень, таких як `cacheRetention`, `temperature` або `maxTokens`, без дублювання всього каталогу моделей. +- `skills`: необов’язковий allowlist Skills для окремого агента. Якщо не задано, агент успадковує `agents.defaults.skills`, коли їх задано; явний список замінює типові значення замість об’єднання, а `[]` означає відсутність Skills. - `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення для окремого повідомлення або сесії. - `reasoningDefault`: необов’язкова типова видимість reasoning для окремого агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning для окремого повідомлення або сесії. -- `fastModeDefault`: необов’язкове типове значення швидкого режиму для окремого агента (`true | false`). Застосовується, коли не задано перевизначення швидкого режиму для окремого повідомлення або сесії. -- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` із типовими параметрами `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент типово має використовувати ACP harness sessions. -- `identity.avatar`: шлях відносно робочого простору, `http(s)` URL або `data:` URI. -- `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`. +- `fastModeDefault`: необов’язкове типове значення fast mode для окремого агента (`true | false`). Застосовується, коли не задано перевизначення fast mode для окремого повідомлення або сесії. +- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для окремого агента. Використовуйте `{ runtime: "codex", fallback: "none" }`, щоб зробити одного агента лише Codex, тоді як інші агенти зберігають типовий резервний перехід на PI. +- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` разом із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати ACP harness sessions. +- `identity.avatar`: шлях відносно workspace, URL `http(s)` або URI `data:`. +- `identity` виводить типові значення: `ackReaction` із `emoji`, `mentionPatterns` із `name`/`emoji`. - `subagents.allowAgents`: allowlist id агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). -- Захист успадкування sandbox: якщо сесія запитувача працює в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. -- `subagents.requireAgentId`: коли значення true, блокує виклики `sessions_spawn`, які не вказують `agentId` (примушує до явного вибору профілю; типово: false). +- Захист успадкування sandbox: якщо сесія запитувача працює в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б поза sandbox. +- `subagents.requireAgentId`: якщо true, блокує виклики `sessions_spawn`, що пропускають `agentId` (примушує до явного вибору профілю; типово: false). --- ## Маршрутизація кількох агентів -Запускайте кількох ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). +Запускайте кілька ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). ```json5 { @@ -1659,14 +1692,14 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br } ``` -### Поля відповідності прив’язок +### Поля відповідності прив’язки -- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип відсутній, типово використовується route), `acp` для постійних ACP-прив’язок розмов. +- `type` (необов’язково): `route` для звичайної маршрутизації (відсутній `type` типово означає route), `acp` для постійних прив’язок розмов ACP. - `match.channel` (обов’язково) -- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо пропущено = типовий обліковий запис) +- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; пропущено = типовий обліковий запис) - `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (необов’язково; специфічні для каналу) -- `acp` (необов’язково; лише для записів `type: "acp"`): `{ mode, label, cwd, backend }` +- `match.guildId` / `match.teamId` (необов’язково; залежить від каналу) +- `acp` (необов’язково; лише для `type: "acp"`): `{ mode, label, cwd, backend }` **Детермінований порядок відповідності:** @@ -1674,14 +1707,14 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (точний збіг, без peer/guild/team) -5. `match.accountId: "*"` (на весь канал) +5. `match.accountId: "*"` (для всього каналу) 6. Типовий агент У межах кожного рівня перемагає перший відповідний запис `bindings`. -Для записів `type: "acp"` OpenClaw виконує визначення за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує порядок рівнів route-прив’язок, наведений вище. +Для записів `type: "acp"` OpenClaw визначає відповідність за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує порядок рівнів route binding вище. -### Профілі доступу для окремих агентів +### Профілі доступу для окремого агента @@ -1701,7 +1734,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br - + ```json5 { @@ -1776,11 +1809,11 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br -Див. [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools) для подробиць щодо пріоритетів. +Докладніше про пріоритети див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). --- -## Сесія +## Session ```json5 { @@ -1802,22 +1835,22 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) + parentForkMaxTokens: 100000, // пропускати fork батьківського треду вище цього числа токенів (0 вимикає) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // duration or false - maxDiskBytes: "500mb", // optional hard budget - highWaterBytes: "400mb", // optional cleanup target + resetArchiveRetention: "30d", // тривалість або false + maxDiskBytes: "500mb", // необов’язковий жорсткий бюджет + highWaterBytes: "400mb", // необов’язкова ціль очищення }, threadBindings: { enabled: true, - idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) - maxAgeHours: 0, // default hard max age in hours (`0` disables) + idleHours: 24, // типове автоматичне unfocus через неактивність у годинах (`0` вимикає) + maxAgeHours: 0, // типовий жорсткий максимальний вік у годинах (`0` вимикає) }, - mainKey: "main", // legacy (runtime always uses "main") + mainKey: "main", // застаріле значення (runtime завжди використовує "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1827,36 +1860,36 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br } ``` - + - **`scope`**: базова стратегія групування сесій для контекстів групового чату. - `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту каналу. - - `global`: усі учасники в контексті каналу використовують одну спільну сесію (використовуйте лише тоді, коли спільний контекст справді потрібен). -- **`dmScope`**: спосіб групування DM. + - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли спільний контекст дійсно потрібен). +- **`dmScope`**: як групуються DM. - `main`: усі DM використовують спільну основну сесію. - `per-peer`: ізоляція за id відправника між каналами. - - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для багатоадресних вхідних скриньок). - - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для багатооблікових конфігурацій). -- **`identityLinks`**: зіставляє канонічні id із peer-ідентифікаторами з префіксом провайдера для спільного використання сесій між каналами. -- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва, спрацьовує те, що спливе раніше. + - `per-channel-peer`: ізоляція для кожного каналу + відправника (рекомендовано для inbox із кількома користувачами). + - `per-account-channel-peer`: ізоляція для кожного облікового запису + каналу + відправника (рекомендовано для багатьох облікових записів). +- **`identityLinks`**: відображає канонічні id на peer-и з префіксом провайдера для спільного використання сесій між каналами. +- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Коли налаштовано обидва, перемагає те, що спливає раніше. - **`resetByType`**: перевизначення для окремих типів (`direct`, `group`, `thread`). Застаріле `dm` приймається як псевдонім для `direct`. -- **`parentForkMaxTokens`**: максимальне `totalTokens` батьківської сесії, дозволене під час створення розгалуженої сесії треду (типово `100000`). - - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw запускає нову сесію треду замість успадкування історії стенограми батьківської сесії. - - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти розгалуження від батьківської сесії. -- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного кошика прямих чатів. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість відповідей назад між агентами під час обміну агент-агент (ціле число, діапазон: `0`–`5`). `0` вимикає ping-pong ланцюжки. -- **`sendPolicy`**: відповідність за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет. -- **`maintenance`**: керування очищенням сховища сесій і зберіганням. +- **`parentForkMaxTokens`**: максимальне значення `totalTokens` у батьківській сесії, дозволене під час створення форкнутої сесії треду (типово `100000`). + - Якщо значення `totalTokens` у батьківській сесії перевищує це значення, OpenClaw починає нову сесію треду замість успадкування історії transcript батьківської сесії. + - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти форк від батьківської сесії. +- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного кошика direct-chat. +- **`agentToAgent.maxPingPongTurns`**: максимальна кількість відповідей у відповідь між агентами під час обміну agent-to-agent (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжки ping-pong. +- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет. +- **`maintenance`**: очищення сховища сесій + керування зберіганням. - `mode`: `warn` лише виводить попередження; `enforce` застосовує очищення. - - `pruneAfter`: поріг давності для застарілих записів (типово `30d`). + - `pruneAfter`: поріг віку для застарілих записів (типово `30d`). - `maxEntries`: максимальна кількість записів у `sessions.json` (типово `500`). - - `rotateBytes`: обертати `sessions.json`, коли він перевищує цей розмір (типово `10mb`). - - `resetArchiveRetention`: строк зберігання архівів стенограм `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. - - `maxDiskBytes`: необов’язковий жорсткий ліміт дискового бюджету каталогу сесій. У режимі `warn` записує попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. - - `highWaterBytes`: необов’язкова ціль після очищення за бюджетом. Типово становить `80%` від `maxDiskBytes`. + - `rotateBytes`: ротує `sessions.json`, коли він перевищує цей розмір (типово `10mb`). + - `resetArchiveRetention`: строк зберігання архівів transcript `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. + - `maxDiskBytes`: необов’язковий бюджет дискового простору для каталогу сесій. У режимі `warn` виводить попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. + - `highWaterBytes`: необов’язкова ціль після очищення бюджету. Типово дорівнює `80%` від `maxDiskBytes`. - **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до тредів. - `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) - - `idleHours`: типове автоматичне зняття фокуса через неактивність у годинах (`0` вимикає; провайдери можуть перевизначати) + - `idleHours`: типове автоматичне unfocus через неактивність у годинах (`0` вимикає; провайдери можуть перевизначати) - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначати) @@ -1868,7 +1901,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br ```json5 { messages: { - responsePrefix: "🦞", // or "auto" + responsePrefix: "🦞", // або "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -1883,7 +1916,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br }, }, inbound: { - debounceMs: 2000, // 0 disables + debounceMs: 2000, // 0 вимикає byChannel: { whatsapp: 5000, slack: 1500, @@ -1897,34 +1930,34 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br Перевизначення для окремого каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Визначення (перемагає найспецифічніше): обліковий запис → канал → глобальне. `""` вимикає й зупиняє каскад. `"auto"` виводить `[{identity.name}]`. +Порядок визначення (найспецифічніше має пріоритет): обліковий запис → канал → глобальне значення. `""` вимикає й зупиняє каскад. `"auto"` виводить `[{identity.name}]`. **Змінні шаблону:** -| Змінна | Опис | Приклад | -| ----------------- | ------------------------ | --------------------------- | -| `{model}` | Коротка назва моделі | `claude-opus-4-6` | -| `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | -| `{provider}` | Назва провайдера | `anthropic` | +| Змінна | Опис | Приклад | +| ---------------- | ---------------------- | --------------------------- | +| `{model}` | Коротка назва моделі | `claude-opus-4-6` | +| `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | +| `{provider}` | Назва провайдера | `anthropic` | | `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | -| `{identity.name}` | Назва identity агента | (те саме, що `"auto"`) | +| `{identity.name}` | Ім’я identity агента | (те саме, що `"auto"`) | -Змінні нечутливі до регістру. `{think}` — псевдонім для `{thinkingLevel}`. +Змінні нечутливі до регістру. `{think}` є псевдонімом для `{thinkingLevel}`. ### Реакція підтвердження - Типово використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. - Перевизначення для окремого каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення identity. -- Scope: `group-mentions` (типово), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: прибирає підтвердження після відповіді в Slack, Discord і Telegram. +- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення з identity. +- Область дії: `group-mentions` (типово), `group-all`, `direct`, `all`. +- `removeAckAfterReply`: видаляє ack після відповіді в Slack, Discord і Telegram. - `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу в Slack, Discord і Telegram. - У Slack і Discord, якщо не задано, реакції статусу залишаються ввімкненими, коли активні реакції підтвердження. - У Telegram явно встановіть `true`, щоб увімкнути реакції статусу життєвого циклу. + У Slack і Discord, якщо значення не задано, реакції статусу залишаються ввімкненими, коли активні реакції ack. + У Telegram установіть це значення явно в `true`, щоб увімкнути реакції статусу життєвого циклу. -### Вхідне debounce +### Вхідний debounce -Об’єднує швидкі текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Керівні команди обходять debounce. +Об’єднує швидкі текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення одразу скидають буфер. Керівні команди оминають debounce. ### TTS (text-to-speech) @@ -1968,11 +2001,11 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br ``` - `auto` керує типовим режимом auto-TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначати локальні налаштування, а `/tts status` показує фактичний стан. -- `summaryModel` перевизначає `agents.defaults.model.primary` для автопідсумку. -- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово має значення `false` (потрібне явне opt-in). -- API key використовують резервні значення `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. -- `openai.baseUrl` перевизначає ендпоінт OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. -- Коли `openai.baseUrl` вказує на ендпоінт, відмінний від OpenAI, OpenClaw трактує його як OpenAI-сумісний TTS-сервер і послаблює валідацію моделі/голосу. +- `summaryModel` перевизначає `agents.defaults.model.primary` для auto-summary. +- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово дорівнює `false` (потрібен явний opt-in). +- API keys використовують резервні значення `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. +- `openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. +- Коли `openai.baseUrl` вказує на endpoint, відмінний від OpenAI, OpenClaw трактує його як OpenAI-compatible TTS server і послаблює валідацію model/voice. --- @@ -2003,12 +2036,12 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br ``` - `talk.provider` має збігатися з ключем у `talk.providers`, коли налаштовано кілька провайдерів Talk. -- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) використовуються лише для сумісності й автоматично мігруються до `talk.providers.`. -- Voice ID використовують резервні значення `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. -- `providers.*.apiKey` приймає відкриті рядки або об’єкти SecretRef. -- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли API key Talk не налаштовано. -- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні назви. -- `silenceTimeoutMs` визначає, як довго режим Talk чекає після тиші користувача перед надсиланням стенограми. Якщо не задано, зберігається типове вікно паузи платформи (`700 ms` на macOS і Android, `900 ms` на iOS). +- Застарілі пласкі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) використовуються лише для сумісності й автоматично мігруються в `talk.providers.`. +- Для voice ID використовуються резервні значення `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. +- `providers.*.apiKey` приймає звичайні текстові рядки або об’єкти SecretRef. +- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли не налаштовано API key Talk. +- `providers.*.voiceAliases` дає змогу директивам Talk використовувати дружні імена. +- `silenceTimeoutMs` визначає, як довго режим Talk чекає після мовчання користувача перед надсиланням transcript. Якщо значення не задано, використовується типове для платформи вікно паузи (`700 ms` на macOS і Android, `900 ms` на iOS). --- @@ -2018,35 +2051,35 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br `tools.profile` задає базовий allowlist перед `tools.allow`/`tools.deny`: -Локальний онбординг типово встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явні профілі зберігаються). +Локальний онбординг типово встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явно задані профілі зберігаються). -| Профіль | Містить | -| ---------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | лише `session_status` | +| Профіль | Містить | +| ---------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | лише `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Без обмежень (так само, як якщо не задано) | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | Без обмежень (те саме, що не задано) | ### Групи інструментів -| Група | Інструменти | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як псевдонім для `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| Група | Інструменти | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як псевдонім для `exec`) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Усі вбудовані інструменти (без plugin провайдерів) | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Усі вбудовані інструменти (без provider plugins) | ### `tools.allow` / `tools.deny` -Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Нечутлива до регістру, підтримує шаблони `*`. Застосовується навіть тоді, коли Docker sandbox вимкнено. +Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Нечутлива до регістру, підтримує wildcard `*`. Застосовується навіть тоді, коли Docker sandbox вимкнено. ```json5 { @@ -2072,7 +2105,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br ### `tools.elevated` -Керує elevated-доступом до exec поза sandbox: +Керує elevated-доступом до `exec` поза sandbox: ```json5 { @@ -2090,7 +2123,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br - Перевизначення для окремого агента (`agents.list[].tools.elevated`) може лише додатково обмежувати. - `/elevated on|off|ask|full` зберігає стан для кожної сесії; вбудовані директиви застосовуються до одного повідомлення. -- Elevated `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` типово або `node`, коли ціль exec — `node`). +- Elevated `exec` обходить sandbox і використовує налаштований escape path (`gateway` типово або `node`, коли ціллю exec є `node`). ### `tools.exec` @@ -2114,8 +2147,8 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br ### `tools.loopDetection` -Перевірки безпеки для циклів інструментів **типово вимкнені**. Установіть `enabled: true`, щоб увімкнути виявлення. -Налаштування можна задавати глобально в `tools.loopDetection` і перевизначати для окремого агента в `agents.list[].tools.loopDetection`. +Перевірки безпеки циклів інструментів **типово вимкнені**. Установіть `enabled: true`, щоб увімкнути виявлення. +Налаштування можна визначати глобально в `tools.loopDetection` і перевизначати для окремого агента в `agents.list[].tools.loopDetection`. ```json5 { @@ -2136,14 +2169,14 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br } ``` -- `historySize`: максимальна історія викликів інструментів, що зберігається для аналізу циклів. +- `historySize`: максимальний обсяг історії викликів інструментів, що зберігається для аналізу циклів. - `warningThreshold`: поріг повторюваного шаблону без прогресу для попереджень. - `criticalThreshold`: вищий поріг повторення для блокування критичних циклів. - `globalCircuitBreakerThreshold`: жорсткий поріг зупинки для будь-якого запуску без прогресу. - `detectors.genericRepeat`: попереджати про повторні виклики того самого інструмента з тими самими аргументами. - `detectors.knownPollNoProgress`: попереджати/блокувати відомі poll-інструменти (`process.poll`, `command_status` тощо). -- `detectors.pingPong`: попереджати/блокувати чергування пар шаблонів без прогресу. -- Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, валідація не проходить. +- `detectors.pingPong`: попереджати/блокувати шаблони чергування пар без прогресу. +- Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, валідація завершується помилкою. ### `tools.web` @@ -2153,14 +2186,14 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br web: { search: { enabled: true, - apiKey: "brave_api_key", // or BRAVE_API_KEY env + apiKey: "brave_api_key", // або env `BRAVE_API_KEY` maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // optional; omit for auto-detect + provider: "firecrawl", // необов’язково; пропустіть для auto-detect maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2185,7 +2218,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: send finished async music/video directly to the channel + directSend: false, // opt-in: надсилати завершені асинхронні music/video безпосередньо в канал }, audio: { enabled: true, @@ -2209,7 +2242,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br } ``` - + **Запис провайдера** (`type: "provider"` або пропущено): @@ -2226,15 +2259,15 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br - `capabilities`: необов’язковий список (`image`, `audio`, `video`). Типові значення: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для окремого запису. -- У разі збоїв використовується наступний запис. +- У разі помилки використовується наступний запис. -Автентифікація провайдера дотримується стандартного порядку: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`. +Автентифікація провайдера дотримується стандартного порядку: `auth-profiles.json` → env vars → `models.providers.*.apiKey`. **Поля асинхронного завершення:** - `asyncCompletion.directSend`: коли `true`, завершені асинхронні завдання `music_generate` - і `video_generate` спочатку намагаються доставлятися напряму в канал. Типове значення: `false` - (застарілий шлях пробудження сесії запитувача/доставки моделі). + і `video_generate` спочатку намагаються доставляти результат безпосередньо в канал. Типове значення: `false` + (застарілий шлях пробудження requester-session/model-delivery). @@ -2253,9 +2286,9 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br ### `tools.sessions` -Керує тим, на які сесії можуть націлюватися інструменти сесій (`sessions_list`, `sessions_history`, `sessions_send`). +Керує тим, на які сесії можуть націлюватися session tools (`sessions_list`, `sessions_history`, `sessions_send`). -Типове значення: `tree` (поточна сесія + сесії, породжені нею, наприклад субагенти). +Типове значення: `tree` (поточна сесія + сесії, породжені нею, наприклад subagents). ```json5 { @@ -2270,10 +2303,10 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br Примітки: -- `self`: лише ключ поточної сесії. -- `tree`: поточна сесія + сесії, породжені поточною сесією (субагенти). -- `agent`: будь-яка сесія, що належить поточному id агента (може включати інших користувачів, якщо ви використовуєте сесії per-sender під одним і тим самим id агента). -- `all`: будь-яка сесія. Націлювання між агентами все одно потребує `tools.agentToAgent`. +- `self`: лише поточний ключ сесії. +- `tree`: поточна сесія + сесії, породжені поточною сесією (subagents). +- `agent`: будь-яка сесія, що належить поточному id агента (може включати інших користувачів, якщо ви запускаєте per-sender сесії під тим самим id агента). +- `all`: будь-яка сесія. Націлювання між агентами все одно вимагає `tools.agentToAgent`. - Обмеження sandbox: коли поточна сесія працює в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється в `tree`, навіть якщо `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` @@ -2285,11 +2318,11 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: set true to allow inline file attachments - maxTotalBytes: 5242880, // 5 MB total across all files + enabled: false, // opt-in: встановіть true, щоб дозволити вбудовані файлові вкладення + maxTotalBytes: 5242880, // 5 MB загалом для всіх файлів maxFiles: 50, - maxFileBytes: 1048576, // 1 MB per file - retainOnSessionKeep: false, // keep attachments when cleanup="keep" + maxFileBytes: 1048576, // 1 MB на файл + retainOnSessionKeep: false, // зберігати вкладення, коли cleanup="keep" }, }, }, @@ -2299,21 +2332,21 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br Примітки: - Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP їх відхиляє. -- Файли матеріалізуються в дочірньому робочому просторі в `.openclaw/attachments//` разом із `.manifest.json`. -- Вміст вкладень автоматично редагується в збережених стенограмах. -- Входи Base64 проходять валідацію зі суворою перевіркою алфавіту/заповнення й захистом розміру до декодування. +- Файли матеріалізуються в дочірньому workspace у `.openclaw/attachments//` разом із `.manifest.json`. +- Вміст вкладень автоматично редагується в transcript persistence. +- Входи base64 перевіряються з жорсткими перевірками алфавіту/padding і захистом розміру до декодування. - Права доступу до файлів: `0700` для каталогів і `0600` для файлів. - Очищення дотримується політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише тоді, коли `retainOnSessionKeep: true`. ### `tools.experimental` -Прапорці експериментальних вбудованих інструментів. Типово вимкнені, якщо не застосовується правило автоматичного ввімкнення для конкретного runtime. +Прапорці експериментальних вбудованих інструментів. Типово вимкнено, якщо не застосовується правило автоматичного ввімкнення, специфічне для runtime. ```json5 { tools: { experimental: { - planTool: true, // enable experimental update_plan + planTool: true, // увімкнути експериментальний update_plan }, }, } @@ -2322,8 +2355,8 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br Примітки: - `planTool`: вмикає структурований інструмент `update_plan` для відстеження нетривіальної багатокрокової роботи. -- Типове значення: `false` для провайдерів, відмінних від OpenAI. Запуски OpenAI і OpenAI Codex автоматично вмикають його, якщо значення не задано; установіть `false`, щоб вимкнути це автоматичне ввімкнення. -- Коли ввімкнено, системний запит також додає вказівки щодо використання, щоб модель застосовувала його лише для суттєвої роботи й тримала не більше одного кроку в стані `in_progress`. +- Типове значення: `false` для провайдерів, відмінних від OpenAI. Для запусків OpenAI та OpenAI Codex він автоматично вмикається, якщо значення не задано; установіть `false`, щоб вимкнути це автоматичне ввімкнення. +- Коли його ввімкнено, системний запит також додає вказівки щодо використання, щоб модель застосовувала його лише для суттєвої роботи та зберігала щонайбільше один крок `in_progress`. ### `agents.defaults.subagents` @@ -2343,21 +2376,21 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br } ``` -- `model`: типова модель для створених субагентів. Якщо не задано, субагенти успадковують модель викликача. -- `allowAgents`: типовий allowlist цільових id агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). -- `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента не вказує `runTimeoutSeconds`. `0` означає відсутність тайм-ауту. -- Політика інструментів для субагентів: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- `model`: типова модель для створених sub-agents. Якщо не задано, sub-agents успадковують модель викликача. +- `allowAgents`: типовий allowlist id цільових агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). +- `runTimeoutSeconds`: типовий timeout (у секундах) для `sessions_spawn`, коли виклик інструмента не вказує `runTimeoutSeconds`. `0` означає відсутність timeout. +- Політика інструментів для окремого subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Власні провайдери й базові URL +## Користувацькі провайдери та base URL -OpenClaw використовує вбудований каталог моделей. Додавайте власних провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. +OpenClaw використовує вбудований каталог моделей. Додавайте користувацькі провайдери через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. ```json5 { models: { - mode: "merge", // merge (default) | replace + mode: "merge", // merge (типово) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2381,43 +2414,43 @@ OpenClaw використовує вбудований каталог модел } ``` -- Використовуйте `authHeader: true` + `headers` для власних потреб автентифікації. +- Використовуйте `authHeader: true` + `headers` для нестандартних потреб автентифікації. - Перевизначайте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий псевдонім змінної середовища). -- Пріоритет злиття для провайдерів із однаковими ID: - - Непорожні значення `baseUrl` з `models.json` агента мають пріоритет. - - Непорожні значення `apiKey` агента мають пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті конфігурації/auth-profile. - - Значення `apiKey` провайдера, керовані через SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань) замість збереження визначених секретів. - - Значення заголовків провайдера, керовані через SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань). - - Порожні або відсутні `apiKey`/`baseUrl` агента використовують резервні значення з `models.providers` у конфігурації. - - Для однакових моделей `contextWindow`/`maxTokens` використовують більше значення між явною конфігурацією та неявними значеннями каталогу. - - Для однакових моделей `contextTokens` зберігає явне обмеження runtime, коли воно задане; використовуйте його, щоб обмежити фактичний контекст без зміни рідних метаданих моделі. - - Використовуйте `models.mode: "replace"`, коли хочете, щоб конфігурація повністю переписала `models.json`. +- Пріоритет злиття для однакових id провайдерів: + - Непорожні значення `baseUrl` з agent `models.json` мають пріоритет. + - Непорожні значення `apiKey` агента мають пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті config/auth-profile. + - Значення `apiKey` провайдера, що керуються SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs) замість збереження визначених секретів. + - Значення заголовків провайдера, що керуються SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs). + - Порожні або відсутні `apiKey`/`baseUrl` агента повертаються до `models.providers` у конфігурації. + - Для однакових моделей `contextWindow`/`maxTokens` використовують вище значення між явною конфігурацією та неявними значеннями каталогу. + - Для однакових моделей `contextTokens` зберігає явне обмеження runtime, якщо воно присутнє; використовуйте це, щоб обмежити ефективний контекст без зміни нативних метаданих моделі. + - Використовуйте `models.mode: "replace"`, якщо хочете, щоб конфігурація повністю переписувала `models.json`. - Збереження маркерів є авторитетним щодо джерела: маркери записуються з активного знімка конфігурації джерела (до визначення), а не з визначених значень секретів runtime. -### Подробиці полів провайдера +### Деталі полів провайдера - `models.mode`: поведінка каталогу провайдерів (`merge` або `replace`). -- `models.providers`: мапа власних провайдерів із ключами за id провайдера. +- `models.providers`: карта користувацьких провайдерів, ключами якої є id провайдера. - `models.providers.*.api`: адаптер запитів (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо). -- `models.providers.*.apiKey`: облікові дані провайдера (краще використовувати SecretRef/підстановку через env). +- `models.providers.*.apiKey`: облікові дані провайдера (надавайте перевагу SecretRef/env substitution). - `models.providers.*.auth`: стратегія автентифікації (`api-key`, `token`, `oauth`, `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` додавати `options.num_ctx` у запити (типово: `true`). +- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` вбудовує `options.num_ctx` у запити (типово: `true`). - `models.providers.*.authHeader`: примусово передавати облікові дані в заголовку `Authorization`, коли це потрібно. -- `models.providers.*.baseUrl`: базовий URL API upstream. -- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації proxy/tenant. -- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів модельного провайдера. - - `request.headers`: додаткові заголовки (зливаються з типовими значеннями провайдера). Значення приймають SecretRef. - - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію провайдера), `"authorization-bearer"` (з `token`), `"header"` (з `headerName`, `value`, необов’язковим `prefix`). - - `request.proxy`: перевизначення HTTP proxy. Режими: `"env-proxy"` (використовувати змінні середовища `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (з `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`. +- `models.providers.*.baseUrl`: базова URL-адреса upstream API. +- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації через proxy/tenant. +- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів model-provider. + - `request.headers`: додаткові заголовки (об’єднуються з типовими значеннями провайдера). Значення приймають SecretRef. + - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію провайдера), `"authorization-bearer"` (із `token`), `"header"` (із `headerName`, `value`, необов’язковим `prefix`). + - `request.proxy`: перевизначення HTTP-проксі. Режими: `"env-proxy"` (використовувати env vars `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (із `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`. - `request.tls`: перевизначення TLS для прямих з’єднань. Поля: `ca`, `cert`, `key`, `passphrase` (усі приймають SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, якщо DNS визначається в приватні, CGNAT або подібні діапазони, через захист HTTP fetch провайдера (явний дозвіл оператора для довірених self-hosted OpenAI-сумісних ендпоінтів). WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF-запобіжник fetch. Типове значення `false`. + - `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, якщо DNS резолвиться в приватні, CGNAT або подібні діапазони, через захист SSRF у provider HTTP fetch (opt-in для оператора для довірених self-hosted OpenAI-compatible endpoint). WebSocket використовує той самий `request` для заголовків/TLS, але не цей захист SSRF fetch. Типове значення `false`. - `models.providers.*.models`: явні записи каталогу моделей провайдера. -- `models.providers.*.models.*.contextWindow`: метадані рідного вікна контексту моделі. -- `models.providers.*.models.*.contextTokens`: необов’язкове обмеження контексту runtime. Використовуйте це, коли хочете менший ефективний бюджет контексту, ніж рідне `contextWindow` моделі. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` з непорожнім нерідним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це значення в `false` під час runtime. Порожній/пропущений `baseUrl` зберігає типову поведінку OpenAI. -- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для OpenAI-сумісних chat-ендпоінтів, що приймають лише рядки. Коли `true`, OpenClaw сплющує масиви `messages[].content`, які містять лише текст, у звичайні рядки перед надсиланням запиту. -- `plugins.entries.amazon-bedrock.config.discovery`: корінь налаштувань авто-виявлення Bedrock. -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути або вимкнути неявне виявлення. +- `models.providers.*.models.*.contextWindow`: метадані нативного вікна контексту моделі. +- `models.providers.*.models.*.contextTokens`: необов’язкове обмеження контексту runtime. Використовуйте це, коли хочете менший ефективний бюджет контексту, ніж нативний `contextWindow` моделі. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` з непорожнім не-нативним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це значення в `false` під час runtime. Порожній/пропущений `baseUrl` зберігає типову поведінку OpenAI. +- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для OpenAI-compatible chat endpoint, які приймають лише рядки. Коли `true`, OpenClaw перетворює масиви `messages[].content`, що містять лише текст, у звичайні рядки перед надсиланням запиту. +- `plugins.entries.amazon-bedrock.config.discovery`: кореневий розділ налаштувань auto-discovery для Bedrock. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути/вимкнути неявне виявлення. - `plugins.entries.amazon-bedrock.config.discovery.region`: регіон AWS для виявлення. - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: необов’язковий фільтр provider-id для цільового виявлення. - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: інтервал опитування для оновлення виявлення. @@ -2460,7 +2493,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` для прямого Z.AI. +Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` для прямого доступу до Z.AI. @@ -2477,7 +2510,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Установіть `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`). Використовуйте посилання `opencode/...` для каталогу Zen або `opencode-go/...` для каталогу Go. Скорочення: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`. +Установіть `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`). Використовуйте посилання `opencode/...` для каталогу Zen або посилання `opencode-go/...` для каталогу Go. Скорочення: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`. @@ -2494,11 +2527,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` є прийнятними псевдонімами. Скорочення: `openclaw onboard --auth-choice zai-api-key`. +Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` приймаються як псевдоніми. Скорочення: `openclaw onboard --auth-choice zai-api-key`. -- Загальний ендпоінт: `https://api.z.ai/api/paas/v4` -- Ендпоінт для кодування (типовий): `https://api.z.ai/api/coding/paas/v4` -- Для загального ендпоінта визначте власного провайдера з перевизначенням base URL. +- Загальний endpoint: `https://api.z.ai/api/paas/v4` +- Endpoint для кодування (типовий): `https://api.z.ai/api/coding/paas/v4` +- Для загального endpoint визначте користувацького провайдера з перевизначенням base URL. @@ -2537,11 +2570,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Для ендпоінта Китаю: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`. +Для endpoint Китаю: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`. -Власні ендпоінти Moonshot оголошують сумісність використання потокової передачі на спільному -транспорті `openai-completions`, і OpenClaw спирається на можливості ендпоінта, -а не лише на вбудований id провайдера. +Нативні endpoint Moonshot рекламують сумісність використання потокової передачі на спільному +транспорті `openai-completions`, і OpenClaw прив’язує це до можливостей endpoint, +а не лише до вбудованого provider id. @@ -2559,11 +2592,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Anthropic-сумісний вбудований провайдер. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. +Сумісний з Anthropic, вбудований провайдер. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. - + ```json5 { @@ -2642,8 +2675,8 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й `openclaw onboard --auth-choice minimax-global-api` або `openclaw onboard --auth-choice minimax-cn-api`. Каталог моделей типово містить лише M2.7. -На Anthropic-сумісному шляху потокової передачі OpenClaw типово вимикає thinking для MiniMax, -якщо ви явно не встановите `thinking` самі. `/fast on` або +На Anthropic-compatible шляху потокової передачі OpenClaw типово вимикає thinking MiniMax, +якщо ви явно самі не встановите `thinking`. `/fast on` або `params.fastMode: true` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. @@ -2651,7 +2684,7 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й -Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; залишайте злитими хостовані моделі для резервного варіанта. +Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; залишайте hosted models об’єднаними для резервного використання. @@ -2672,7 +2705,7 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // або звичайний текстовий рядок env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2682,14 +2715,14 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- `allowBundled`: необов’язковий allowlist лише для bundled Skills (керовані/workspace Skills не зачіпаються). +- `allowBundled`: необов’язковий allowlist лише для bundled Skills (керовані/workspace Skills це не зачіпає). - `load.extraDirs`: додаткові спільні корені Skills (найнижчий пріоритет). - `install.preferBrew`: коли true, надавати перевагу інсталяторам Homebrew, якщо `brew` доступний, перед переходом до інших типів інсталяторів. -- `install.nodeManager`: пріоритет менеджера Node для специфікацій - `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). +- `install.nodeManager`: уподобання інсталятора node для специфікацій `metadata.openclaw.install` + (`npm` | `pnpm` | `yarn` | `bun`). - `entries..enabled: false` вимикає Skill, навіть якщо він bundled/встановлений. -- `entries..apiKey`: зручне поле для Skills, які оголошують основну env-змінну (відкритий рядок або об’єкт SecretRef). +- `entries..apiKey`: зручний спосіб для Skills, які оголошують основну env var (звичайний текстовий рядок або об’єкт SecretRef). --- @@ -2717,41 +2750,41 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- Завантажується з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. -- Виявлення приймає нативні plugins OpenClaw, а також сумісні пакети Codex і Claude, включно з пакетами Claude зі стандартним макетом без маніфеста. +- Завантажується з `~/.openclaw/extensions`, `/.openclaw/extensions` і `plugins.load.paths`. +- Виявлення приймає нативні плагіни OpenClaw, а також сумісні пакети Codex і пакети Claude, включно з безманіфестними пакетами Claude зі стандартною структурою. - **Зміни конфігурації потребують перезапуску шлюзу.** -- `allow`: необов’язковий allowlist (завантажуються лише перелічені plugins). `deny` має пріоритет. -- `plugins.entries..apiKey`: зручне поле API key на рівні plugin (коли plugin це підтримує). -- `plugins.entries..env`: мапа env-змінних у межах plugin. -- `plugins.entries..hooks.allowPromptInjection`: коли `false`, ядро блокує `before_prompt_build` й ігнорує поля зміни запиту із застарілого `before_agent_start`, зберігаючи при цьому застарілі `modelOverride` і `providerOverride`. Застосовується до нативних plugin hooks і підтримуваних каталогів hook, наданих пакетами. -- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому plugin запитувати перевизначення `provider` і `model` для окремих запусків фонових субагентів. -- `plugins.entries..subagent.allowedModels`: необов’язковий allowlist канонічних цілей `provider/model` для довірених перевизначень субагентів. Використовуйте `"*"`, лише якщо ви свідомо хочете дозволити будь-яку модель. -- `plugins.entries..config`: об’єкт конфігурації, визначений plugin (валідується нативною схемою plugin OpenClaw, коли вона доступна). -- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера веб-отримання Firecrawl. - - `apiKey`: API key Firecrawl (приймає SecretRef). Використовує резервне значення з `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілого `tools.web.fetch.firecrawl.apiKey` або env-змінної `FIRECRAWL_API_KEY`. - - `baseUrl`: базовий URL API Firecrawl (типово: `https://api.firecrawl.dev`). - - `onlyMainContent`: витягувати зі сторінок лише основний вміст (типово: `true`). +- `allow`: необов’язковий allowlist (завантажуються лише перелічені плагіни). `deny` має пріоритет. +- `plugins.entries..apiKey`: зручне поле API key на рівні плагіна (коли плагін це підтримує). +- `plugins.entries..env`: карта env vars у межах плагіна. +- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` і ігнорує поля legacy `before_agent_start`, що змінюють prompt, зберігаючи при цьому legacy `modelOverride` і `providerOverride`. Це застосовується до нативних хуків плагінів і підтримуваних каталогів хуків, наданих пакетами. +- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому плагіну запитувати перевизначення `provider` і `model` для окремого запуску фонових subagent. +- `plugins.entries..subagent.allowedModels`: необов’язковий allowlist канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"` лише тоді, коли свідомо хочете дозволити будь-яку модель. +- `plugins.entries..config`: об’єкт конфігурації, визначений плагіном (валідується нативною схемою плагіна OpenClaw, якщо вона доступна). +- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера Firecrawl web-fetch. + - `apiKey`: API key Firecrawl (приймає SecretRef). Використовує резервне значення `plugins.entries.firecrawl.config.webSearch.apiKey`, legacy `tools.web.fetch.firecrawl.apiKey` або env var `FIRECRAWL_API_KEY`. + - `baseUrl`: базова URL-адреса API Firecrawl (типово: `https://api.firecrawl.dev`). + - `onlyMainContent`: витягувати лише основний вміст сторінок (типово: `true`). - `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні). - - `timeoutSeconds`: тайм-аут запиту scraping у секундах (типово: `60`). + - `timeoutSeconds`: timeout запиту scrape у секундах (типово: `60`). - `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (вебпошук Grok). - - `enabled`: увімкнути провайдер X Search. - - `model`: модель Grok для пошуку (наприклад `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: налаштування dreaming пам’яті (експериментально). Див. [Dreaming](/uk/concepts/dreaming) щодо фаз і порогів. - - `enabled`: головний перемикач dreaming (типово `false`). - - `frequency`: cron-ритм для кожного повного проходу dreaming (`"0 3 * * *"` типово). - - політика фаз і пороги — це деталі реалізації (не користувацькі ключі конфігурації). -- Повна конфігурація пам’яті міститься в [Довіднику конфігурації пам’яті](/uk/reference/memory-config): + - `enabled`: увімкнути провайдера X Search. + - `model`: модель Grok для пошуку (наприклад, `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: налаштування memory dreaming (експериментально). Фази та пороги див. у [Dreaming](/uk/concepts/dreaming). + - `enabled`: головний перемикач dreaming (типове значення `false`). + - `frequency`: cron cadence для кожного повного циклу dreaming (типово `"0 3 * * *"`). + - Політика фаз і пороги є деталями реалізації (не користувацькими ключами конфігурації). +- Повна конфігурація пам’яті міститься в [Memory configuration reference](/uk/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Увімкнені plugins пакунків Claude також можуть додавати вбудовані типові значення Pi з `settings.json`; OpenClaw застосовує їх як санітизовані налаштування агента, а не як сирі патчі конфігурації OpenClaw. -- `plugins.slots.memory`: вибрати id активного plugin пам’яті або `"none"`, щоб вимкнути plugins пам’яті. -- `plugins.slots.contextEngine`: вибрати id активного plugin рушія контексту; типово `"legacy"`, якщо ви не встановите й не виберете інший рушій. -- `plugins.installs`: метадані встановлення, керовані CLI, які використовує `openclaw plugins update`. +- Увімкнені плагіни-пакети Claude також можуть додавати вбудовані типові значення Pi із `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як сирі патчі конфігурації OpenClaw. +- `plugins.slots.memory`: вибрати id активного memory plugin або `"none"`, щоб вимкнути memory plugins. +- `plugins.slots.contextEngine`: вибрати id активного context engine plugin; типове значення — `"legacy"`, доки ви не встановите й не виберете інший engine. +- `plugins.installs`: метадані встановлення під керуванням CLI, які використовуються `openclaw plugins update`. - Містить `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Сприймайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI замість ручного редагування. + - Розглядайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI замість ручного редагування. Див. [Plugins](/uk/tools/plugin). @@ -2766,8 +2799,8 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access - // allowPrivateNetwork: true, // legacy alias + // dangerouslyAllowPrivateNetwork: true, // opt-in лише для довіреного доступу до приватної мережі + // allowPrivateNetwork: true, // застарілий псевдонім // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -2794,28 +2827,28 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й ``` - `evaluateEnabled: false` вимикає `act:evaluate` і `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому навігація browser типово залишається суворою. -- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли свідомо довіряєте навігації browser у приватній мережі. -- У суворому режимі віддалені ендпоінти профілів CDP (`profiles.*.cdpUrl`) підлягають тому самому блокуванню приватної мережі під час перевірок доступності/виявлення. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо значення не задано, тому навігація browser типово залишається суворою. +- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте browser navigation у приватній мережі. +- У суворому режимі endpoint віддалених профілів CDP (`profiles.*.cdpUrl`) підпадають під те саме блокування приватної мережі під час перевірок доступності/виявлення. - `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім. - У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків. -- Віддалені профілі доступні лише для приєднання (start/stop/reset вимкнені). +- Віддалені профілі є attach-only (start/stop/reset вимкнено). - `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`. Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявляв `/json/version`; використовуйте WS(S), - коли ваш провайдер надає вам прямий URL DevTools WebSocket. + коли провайдер надає вам пряму URL-адресу DevTools WebSocket. - Профілі `existing-session` працюють лише на хості й використовують Chrome MCP замість CDP. -- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний +- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлюватися на конкретний профіль браузера на основі Chromium, наприклад Brave або Edge. - Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP: - дії на основі snapshot/ref замість націлювання через CSS-селектори, хуки завантаження - одного файла, без перевизначення тайм-ауту діалогів, без `wait --load networkidle`, а також без - `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій. + дії на основі snapshot/ref замість націлювання через CSS-selector, хуки + завантаження одного файла, без перевизначення timeout для діалогів, без + `wait --load networkidle`, а також без `responsebody`, експорту PDF, перехоплення завантажень чи пакетних дій. - Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно задавайте `cdpUrl` лише для віддаленого CDP. -- Порядок автовиявлення: типовий браузер, якщо він на основі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. -- Сервіс керування: лише loopback (порт визначається з `gateway.port`, типово `18791`). -- `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад - `--disable-gpu`, параметри розміру вікна або прапорці налагодження). +- Порядок auto-detect: типовий браузер, якщо він на основі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- Сервіс керування: лише loopback (порт виводиться з `gateway.port`, типово `18791`). +- `extraArgs` додає додаткові прапорці запуску до локального запуску Chromium (наприклад + `--disable-gpu`, розмір вікна або debug flags). --- @@ -2827,14 +2860,14 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji, short text, image URL, or data URI + avatar: "CB", // emoji, короткий текст, URL зображення або data URI }, }, } ``` -- `seamColor`: акцентний колір для chrome нативного UI (відтінок бульбашки Talk Mode тощо). -- `assistant`: перевизначення identity для Control UI. Використовує резервне значення з identity активного агента. +- `seamColor`: акцентний колір для chrome нативного застосунку UI (тон бульбашки Talk Mode тощо). +- `assistant`: перевизначення identity для Control UI. Якщо не задано, використовується identity активного агента. --- @@ -2849,8 +2882,8 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", - // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth + // password: "your-password", // або OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // для mode=trusted-proxy; див. /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -2867,8 +2900,8 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й enabled: true, basePath: "/openclaw", // root: "dist/control-ui", - // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI - // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode + // allowedOrigins: ["https://control.example.com"], // обов’язково для Control UI не на loopback + // dangerouslyAllowHostHeaderOriginFallback: false, // небезпечний режим резервного визначення origin через заголовок Host // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -2879,12 +2912,12 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // Optional. Default false. + // Необов’язково. Типове значення false. allowRealIpFallback: false, tools: { - // Additional /tools/invoke HTTP denies + // Додаткові HTTP deny для /tools/invoke deny: ["browser"], - // Remove tools from the default HTTP deny list + // Видалити інструменти зі списку HTTP deny за замовчуванням allow: ["gateway"], }, push: { @@ -2899,62 +2932,62 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` - + -- `mode`: `local` (запустити gateway) або `remote` (підключитися до віддаленого gateway). Gateway відмовляється запускатися, якщо не `local`. -- `port`: один мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. +- `mode`: `local` (запускати gateway) або `remote` (підключатися до віддаленого gateway). Gateway відмовляється запускатися, якщо не `local`. +- `port`: єдиний мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (типово), `lan` (`0.0.0.0`), `tailnet` (лише Tailscale IP) або `custom`. -- **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хостів (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Примітка щодо Docker**: типовий bind `loopback` слухає `127.0.0.1` усередині контейнера. За bridge-мережі Docker (`-p 18789:18789`) трафік надходить через `eth0`, тому gateway недоступний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` із `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. -- **Автентифікація**: типово обов’язкова. Прив’язки не до loopback вимагають автентифікації gateway. На практиці це означає спільний токен/пароль або reverse proxy з awareness identity з `gateway.auth.mode: "trusted-proxy"`. Майстер онбордингу типово генерує токен. -- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно із SecretRef), явно встановіть `gateway.auth.mode` у `token` або `password`. Під час запуску й у потоках встановлення/відновлення сервісу буде помилка, якщо налаштовано обидва значення, а `mode` не встановлено. -- `gateway.auth.mode: "none"`: явний режим без автентифікації. Використовуйте лише для довірених локальних конфігурацій loopback; цей варіант навмисно не пропонується в підказках онбордингу. -- `gateway.auth.mode: "trusted-proxy"`: делегувати автентифікацію reverse proxy з awareness identity і довіряти заголовкам identity від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **джерело proxy не з loopback**; reverse proxy на тому самому хості через loopback не задовольняють вимоги trusted-proxy auth. -- `gateway.auth.allowTailscale`: коли `true`, заголовки identity Tailscale Serve можуть задовольняти автентифікацію Control UI/WebSocket (перевіряється через `tailscale whois`). HTTP API-ендпоінти **не** використовують цю автентифікацію заголовками Tailscale; вони дотримуються звичайного режиму HTTP-автентифікації gateway. Цей безтокенний потік передбачає, що хост gateway є довіреним. Типово: `true`, коли `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб автентифікації. Застосовується для кожного IP клієнта й для кожної області автентифікації окремо (спільний секрет і токен пристрою відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`. - - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються до запису збою. Тому одночасні хибні спроби від того самого клієнта можуть спрацювати на ліміт уже на другому запиті, замість того щоб обидва пройшли як звичайні невідповідності. - - `gateway.auth.rateLimit.exemptLoopback` типово дорівнює `true`; установіть `false`, коли навмисно хочете також обмежувати трафік localhost (для тестових конфігурацій або суворих розгортань через proxy). -- Спроби автентифікації WS із джерела browser завжди обмежуються з вимкненим винятком для loopback (додатковий захист від brute force до localhost із браузера). -- На loopback такі блокування для джерел browser ізолюються за нормалізованим - значенням `Origin`, тож повторні збої з одного localhost-origin не блокують - автоматично інший origin. -- `tailscale.mode`: `serve` (лише tailnet, bind на loopback) або `funnel` (публічно, вимагає автентифікації). -- `controlUi.allowedOrigins`: явний allowlist browser-origin для підключень Gateway WebSocket. Обов’язковий, коли клієнти browser очікуються не з loopback-origin. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, що вмикає резервний origin через заголовок Host для розгортань, які навмисно покладаються на політику origin через заголовок Host. -- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` `remote.url` має бути `ws://` або `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське аварійне перевизначення, яке дозволяє відкритий `ws://` до довірених IP приватної мережі; типово відкритий трафік і далі дозволено лише для loopback. -- `gateway.remote.token` / `.password`: поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують автентифікацію gateway. -- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL для зовнішнього APNs relay, який використовують офіційні/TestFlight збірки iOS після публікації relay-backed registration до gateway. Цей URL має збігатися з URL relay, вбудованим у збірку iOS. -- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання gateway-to-relay у мілісекундах. Типове значення: `10000`. -- Registration із підтримкою relay делегуються конкретній identity gateway. Спарений застосунок iOS отримує `gateway.identity.get`, включає цю identity до реєстрації relay і пересилає до gateway grant на надсилання в межах цієї registration. Інший gateway не може повторно використати цю збережену registration. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові env-перевизначення для конфігурації relay вище. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний механізм лише для розробки, який дозволяє URL loopback HTTP relay. У production URL relay мають залишатися на HTTPS. -- `gateway.channelHealthCheckMinutes`: інтервал монітора стану каналів у хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски монітора стану. Типове значення: `5`. -- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Тримайте його більшим або рівним `gateway.channelHealthCheckMinutes`. Типове значення: `30`. -- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітора стану на канал/обліковий запис протягом ковзної години. Типове значення: `10`. -- `channels..healthMonitor.enabled`: вимкнення перезапусків монітора стану для окремого каналу при збереженні глобального монітора ввімкненим. -- `channels..accounts..healthMonitor.enabled`: перевизначення для окремого облікового запису в багатооблікових каналах. Якщо задано, воно має пріоритет над перевизначенням на рівні каналу. -- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано. -- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і значення не визначено, визначення завершується в закритому режимі (без маскування резервним віддаленим варіантом). -- `trustedProxies`: IP reverse proxy, які завершують TLS або вставляють заголовки перенаправленого клієнта. Додавайте лише ті proxy, якими ви керуєте. Записи loopback усе ще допустимі для конфігурацій proxy/local-detection на тому самому хості (наприклад Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. Типово `false` для поведінки fail-closed. -- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список заборон). -- `gateway.tools.allow`: прибирає назви інструментів із типового списку заборон HTTP. +- **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хоста (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Примітка для Docker**: типовий bind `loopback` слухає `127.0.0.1` всередині контейнера. З bridge-мережею Docker (`-p 18789:18789`) трафік надходить на `eth0`, тому gateway недоступний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. +- **Auth**: типово обов’язкова. Bind-и не на loopback вимагають auth gateway. На практиці це означає спільний token/password або identity-aware reverse proxy з `gateway.auth.mode: "trusted-proxy"`. Майстер онбордингу типово генерує token. +- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно встановіть `gateway.auth.mode` у `token` або `password`. Під час запуску та у потоках install/repair сервісу буде помилка, якщо налаштовано обидва значення, а mode не задано. +- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних налаштувань local loopback; цей режим навмисно не пропонується в запитах онбордингу. +- `gateway.auth.mode: "trusted-proxy"`: делегує auth identity-aware reverse proxy та довіряє заголовкам identity від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; reverse proxy на тому самому хості через loopback не задовольняє trusted-proxy auth. +- `gateway.auth.allowTailscale`: коли `true`, заголовки identity Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). HTTP API endpoint не використовують цю auth за заголовками Tailscale; вони дотримуються звичайного HTTP auth mode gateway. Цей безтокеновий потік передбачає, що хост gateway є довіреним. Типове значення — `true`, коли `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: необов’язковий лімітатор невдалих auth-спроб. Застосовується для кожного IP клієнта й для кожної області auth окремо (shared-secret і device-token відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`. + - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому паралельні хибні спроби від одного клієнта можуть спрацювати на лімітатор на другому запиті, замість того щоб обидві пройшли як звичайні невідповідності. + - `gateway.auth.rateLimit.exemptLoopback` типово дорівнює `true`; установіть `false`, якщо свідомо хочете, щоб трафік localhost також підлягав rate limiting (для тестових конфігурацій або суворих proxy deployment). +- Спроби WS auth з browser-origin завжди обмежуються без винятку для loopback (додатковий захист від brute force localhost із браузера). +- На loopback ці блокування для browser-origin ізольовані за нормалізованим значенням `Origin`, + тож повторні збої від одного localhost origin не блокують автоматично + інший origin. +- `tailscale.mode`: `serve` (лише tailnet, bind на loopback) або `funnel` (публічно, потребує auth). +- `controlUi.allowedOrigins`: явний allowlist browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються browser clients з origin, відмінних від loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає резервне визначення origin через заголовок Host для deployment, що свідомо покладаються на політику origin за заголовком Host. +- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське break-glass перевизначення, яке дозволяє відкритий `ws://` до довірених IP приватної мережі; типовим залишається дозвіл на відкритий трафік лише для loopback. +- `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Вони самі собою не налаштовують auth gateway. +- `gateway.push.apns.relay.baseUrl`: базова HTTPS URL-адреса зовнішнього APNs relay, який використовується офіційними/TestFlight збірками iOS після публікації relay-backed registrations у gateway. Ця URL-адреса має збігатися з relay URL, вбудованою в збірку iOS. +- `gateway.push.apns.relay.timeoutMs`: timeout надсилання gateway-to-relay у мілісекундах. Типове значення: `10000`. +- Relay-backed registrations делегуються конкретній identity gateway. Під’єднаний застосунок iOS викликає `gateway.identity.get`, включає цю identity в реєстрацію relay і передає gateway grant на надсилання в межах реєстрації. Інший gateway не може повторно використати таку збережену реєстрацію. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові перевизначення через env для наведеної вище конфігурації relay. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: тільки для розробки, escape hatch для loopback HTTP relay URL. Production relay URL мають залишатися на HTTPS. +- `gateway.channelHealthCheckMinutes`: інтервал моніторингу здоров’я каналу в хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски health-monitor. Типове значення: `5`. +- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого socket у хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типове значення: `30`. +- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor для кожного каналу/облікового запису за ковзну годину. Типове значення: `10`. +- `channels..healthMonitor.enabled`: відмова для окремого каналу від перезапусків health-monitor зі збереженням глобального монітора. +- `channels..accounts..healthMonitor.enabled`: перевизначення для окремого облікового запису для каналів із кількома обліковими записами. Якщо задано, має пріоритет над перевизначенням рівня каналу. +- Локальні шляхи викликів gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано. +- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і значення не вдалось визначити, застосовується fail-closed (без маскування резервним remote fallback). +- `trustedProxies`: IP reverse proxy, які завершують TLS або вставляють заголовки forwarded-client. Указуйте лише proxy, які ви контролюєте. Записи loopback і далі валідні для сценаріїв proxy/local-detection на тому самому хості (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять запити loopback придатними для `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. Типове значення `false` для fail-closed поведінки. +- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий deny list). +- `gateway.tools.allow`: прибирає назви інструментів із типового HTTP deny list. -### OpenAI-сумісні ендпоінти +### OpenAI-compatible endpoint - Chat Completions: типово вимкнено. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`. -- API Responses: `gateway.http.endpoints.responses.enabled`. -- Посилення захисту URL-входів Responses: +- Responses API: `gateway.http.endpoints.responses.enabled`. +- Захист URL-входів Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Порожні allowlist сприймаються як незадані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` - і/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. -- Необов’язковий заголовок посилення безпеки відповіді: - - `gateway.http.securityHeaders.strictTransportSecurity` (встановлюйте лише для HTTPS-origin, якими ви керуєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + Порожні allowlist трактуються як незадані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` + і/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання за URL. +- Необов’язковий заголовок захисту відповіді: + - `gateway.http.securityHeaders.strictTransportSecurity` (установлюйте лише для контрольованих вами HTTPS origin; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) ### Ізоляція кількох екземплярів @@ -2986,11 +3019,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типово: `false`). +- `enabled`: вмикає завершення TLS на listener gateway (HTTPS/WSS) (типово: `false`). - `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовано; лише для локального/dev використання. -- `certPath`: шлях файлової системи до файла TLS-сертифіката. -- `keyPath`: шлях файлової системи до файла приватного ключа TLS; обмежуйте права доступу. -- `caPath`: необов’язковий шлях до CA bundle для перевірки клієнта або власних ланцюжків довіри. +- `certPath`: шлях у файловій системі до файла TLS certificate. +- `keyPath`: шлях у файловій системі до файла TLS private key; обмежуйте доступ до нього правами. +- `caPath`: необов’язковий шлях до CA bundle для перевірки клієнта або користувацьких ланцюжків довіри. ### `gateway.reload` @@ -3007,12 +3040,12 @@ openclaw gateway --port 19001 ``` - `mode`: керує тим, як зміни конфігурації застосовуються під час runtime. - - `"off"`: ігнорувати живі зміни; зміни вимагають явного перезапуску. + - `"off"`: ігнорувати зміни наживо; зміни вимагають явного перезапуску. - `"restart"`: завжди перезапускати процес gateway при зміні конфігурації. - - `"hot"`: застосовувати зміни в процесі без перезапуску. - - `"hybrid"` (типово): спочатку спробувати hot reload; у разі потреби перейти до перезапуску. + - `"hot"`: застосовувати зміни в межах процесу без перезапуску. + - `"hybrid"` (типово): спочатку спробувати hot reload; за потреби перейти до перезапуску. - `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число). -- `deferralTimeoutMs`: максимальний час у мс очікування завершення операцій у польоті перед примусовим перезапуском (типово: `300000` = 5 хвилин). +- `deferralTimeoutMs`: максимальний час очікування в мс для операцій у процесі перед примусовим перезапуском (типово: `300000` = 5 хвилин). --- @@ -3049,37 +3082,37 @@ openclaw gateway --port 19001 } ``` -Автентифікація: `Authorization: Bearer ` або `x-openclaw-token: `. -Токени hooks у рядку запиту відхиляються. +Auth: `Authorization: Bearer ` або `x-openclaw-token: `. +Hook token у query string відхиляються. Примітки щодо валідації та безпеки: - `hooks.enabled=true` вимагає непорожній `hooks.token`. -- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання токена Gateway відхиляється. +- `hooks.token` має бути **відмінним** від `gateway.auth.token`; повторне використання token gateway відхиляється. - `hooks.path` не може бути `/`; використовуйте окремий підшлях, наприклад `/hooks`. -- Якщо `hooks.allowRequestSessionKey=true`, обмежуйте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). +- Якщо `hooks.allowRequestSessionKey=true`, обмежте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). -**Ендпоінти:** +**Endpoint:** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - `sessionKey` із payload запиту приймається лише тоді, коли `hooks.allowRequestSessionKey=true` (типово: `false`). - `POST /hooks/` → визначається через `hooks.mappings` - + -- `match.path` відповідає підшляху після `/hooks` (наприклад `/hooks/gmail` → `gmail`). +- `match.path` відповідає підшляху після `/hooks` (наприклад, `/hooks/gmail` → `gmail`). - `match.source` відповідає полю payload для загальних шляхів. -- Шаблони на кшталт `{{messages[0].subject}}` читають дані з payload. -- `transform` може вказувати на модуль JS/TS, який повертає дію hook. - - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та вихід за межі каталогу відхиляються). -- `agentId` маршрутизує до конкретного агента; невідомі ID використовують резервний типовий агент. -- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або відсутність = дозволити все, `[]` = заборонити все). -- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook-агента без явного `sessionKey`. +- Шаблони на кшталт `{{messages[0].subject}}` читають значення з payload. +- `transform` може вказувати на модуль JS/TS, що повертає дію hook. + - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та traversal відхиляються). +- `agentId` маршрутизує до конкретного агента; невідомі ID повертаються до типового. +- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або не задано = дозволити всі, `[]` = заборонити всі). +- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook agent без явного `sessionKey`. - `allowRequestSessionKey`: дозволити викликачам `/hooks/agent` задавати `sessionKey` (типово: `false`). - `allowedSessionKeyPrefixes`: необов’язковий allowlist префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. -- `deliver: true` надсилає фінальну відповідь у канал; `channel` типово має значення `last`. -- `model` перевизначає LLM для цього запуску hook (має бути дозволена, якщо каталог моделей налаштовано). +- `deliver: true` надсилає фінальну відповідь у канал; `channel` типово дорівнює `last`. +- `model` перевизначає LLM для цього запуску hook (має бути дозволена, якщо задано каталог моделей). @@ -3106,7 +3139,7 @@ openclaw gateway --port 19001 } ``` -- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, якщо його налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути. +- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, коли це налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути. - Не запускайте окремий `gog gmail watch serve` паралельно з Gateway. --- @@ -3118,23 +3151,23 @@ openclaw gateway --port 19001 canvasHost: { root: "~/.openclaw/workspace/canvas", liveReload: true, - // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1 + // enabled: false, // або OPENCLAW_SKIP_CANVAS_HOST=1 }, } ``` -- Обслуговує HTML/CSS/JS і A2UI, які агент може редагувати, через HTTP на порту Gateway: +- Обслуговує HTML/CSS/JS і A2UI, які може редагувати агент, через HTTP під портом Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - Лише локально: залишайте `gateway.bind: "loopback"` (типово). -- Прив’язки не до loopback: маршрути canvas вимагають автентифікації Gateway (token/password/trusted-proxy), так само як і інші HTTP-поверхні Gateway. -- Node WebView зазвичай не надсилають заголовки автентифікації; після спарювання й підключення вузла Gateway оголошує URL можливостей у межах вузла для доступу до canvas/A2UI. -- URL можливостей прив’язані до активної WS-сесії вузла й швидко спливають. Резервний варіант на основі IP не використовується. -- Вставляє клієнт live reload в HTML, що обслуговується. -- Автоматично створює стартовий `index.html`, якщо каталог порожній. +- Bind-и не на loopback: маршрути canvas вимагають Gateway auth (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway. +- Node WebView зазвичай не надсилають заголовки auth; після pairing і підключення node Gateway рекламує URL capability з прив’язкою до node для доступу до canvas/A2UI. +- URL capability прив’язані до активної WS-сесії node і швидко спливають. Резервний варіант на основі IP не використовується. +- Вбудовує клієнт live-reload у відданий HTML. +- Автоматично створює початковий `index.html`, якщо каталог порожній. - Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`. -- Зміни вимагають перезапуску gateway. -- Вимикайте live reload для великих каталогів або у випадку помилок `EMFILE`. +- Зміни потребують перезапуску gateway. +- Вимкніть live reload для великих каталогів або в разі помилок `EMFILE`. --- @@ -3152,9 +3185,9 @@ openclaw gateway --port 19001 } ``` -- `minimal` (типово): не включати `cliPath` + `sshPort` до TXT-записів. -- `full`: включати `cliPath` + `sshPort`. -- Hostname типово має значення `openclaw`. Перевизначення через `OPENCLAW_MDNS_HOSTNAME`. +- `minimal` (типово): не включає `cliPath` + `sshPort` до TXT-записів. +- `full`: включає `cliPath` + `sshPort`. +- Ім’я хоста типово `openclaw`. Перевизначається через `OPENCLAW_MDNS_HOSTNAME`. ### Wide-area (DNS-SD) @@ -3166,7 +3199,7 @@ openclaw gateway --port 19001 } ``` -Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + split DNS у Tailscale. +Записує unicast DNS-SD zone у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + Tailscale split DNS. Налаштування: `openclaw dns setup --apply`. @@ -3174,7 +3207,7 @@ openclaw gateway --port 19001 ## Environment -### `env` (вбудовані env-змінні) +### `env` (вбудовані env vars) ```json5 { @@ -3191,14 +3224,14 @@ openclaw gateway --port 19001 } ``` -- Вбудовані env-змінні застосовуються лише тоді, коли у середовищі процесу відсутній ключ. -- Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). +- Вбудовані env vars застосовуються лише тоді, коли в env процесу бракує цього ключа. +- Файли `.env`: `.env` у CWD + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). - `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell. -- Повний порядок пріоритетів див. в [Environment](/uk/help/environment). +- Повний порядок пріоритетів див. у [Environment](/uk/help/environment). -### Підстановка env-змінних +### Підстановка env vars -Посилайтеся на env-змінні в будь-якому рядку конфігурації через `${VAR_NAME}`: +Посилайтеся на env vars у будь-якому рядку конфігурації через `${VAR_NAME}`: ```json5 { @@ -3208,16 +3241,16 @@ openclaw gateway --port 19001 } ``` -- Підтримуються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. +- Відповідають лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. - Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації. -- Екрануйте через `$${VAR}` для буквального `${VAR}`. +- Екрануйте через `$${VAR}`, щоб отримати буквальний `${VAR}`. - Працює з `$include`. --- ## Secrets -Посилання на секрети є додатковими: відкриті значення й далі працюють. +Посилання на секрети є додатковими: звичайні текстові значення теж продовжують працювати. ### `SecretRef` @@ -3233,21 +3266,21 @@ openclaw gateway --port 19001 - шаблон `id` для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` - `id` для `source: "file"`: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`) - шаблон `id` для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `id` для `source: "exec"` не повинні містити сегментів шляху `.` або `..`, розділених `/` (наприклад `a/../b` відхиляється) +- `id` для `source: "exec"` не повинен містити slash-delimited path segment `.` або `..` (наприклад, `a/../b` відхиляється) ### Підтримувана поверхня облікових даних -- Канонічна матриця: [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface) +- Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface) - `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`. -- Посилання в `auth-profiles.json` включені в покриття визначення runtime та аудиту. +- Посилання `auth-profiles.json` включаються до визначення під час runtime і до охоплення audit. -### Конфігурація провайдерів секретів +### Конфігурація providers секретів ```json5 { secrets: { providers: { - default: { source: "env" }, // optional explicit env provider + default: { source: "env" }, // необов’язковий явний env provider filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -3271,17 +3304,17 @@ openclaw gateway --port 19001 Примітки: -- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue `id` має бути `"value"`). -- Провайдер `exec` вимагає абсолютний шлях `command` і використовує payload-и протоколу через stdin/stdout. -- Типово шляхи команд-символьних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символьні посилання з перевіркою шляху визначеної цілі. -- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до шляху визначеної цілі. +- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (`id` має дорівнювати `"value"` у режимі singleValue). +- Провайдер `exec` вимагає абсолютного шляху `command` і використовує payload протоколу через stdin/stdout. +- Типово шляхи команд-символьних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символічні посилання з перевіркою визначеного шляху цілі. +- Якщо налаштовано `trustedDirs`, перевірка trusted-dir застосовується до визначеного шляху цілі. - Середовище дочірнього процесу `exec` типово мінімальне; явно передавайте потрібні змінні через `passEnv`. - Посилання на секрети визначаються під час активації в знімок у пам’яті, після чого шляхи запитів читають лише цей знімок. - Під час активації застосовується фільтрація активної поверхні: невизначені посилання на ввімкнених поверхнях призводять до помилки запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. --- -## Сховище автентифікації +## Сховище auth ```json5 { @@ -3300,12 +3333,12 @@ openclaw gateway --port 19001 ``` - Профілі для окремого агента зберігаються в `/auth-profiles.json`. -- `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних. -- Профілі режиму OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані `auth-profile`, підкріплені SecretRef. -- Статичні облікові дані runtime беруться зі знімків у пам’яті з уже визначеними значеннями; застарілі статичні записи `auth.json` очищаються, якщо їх виявлено. -- Застарілі імпорти OAuth — із `~/.openclaw/credentials/oauth.json`. +- `auth-profiles.json` підтримує посилання на рівні значення (`keyRef` для `api_key`, `tokenRef` для `token`) для режимів статичних облікових даних. +- Профілі режиму OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілю auth на основі SecretRef. +- Статичні облікові дані runtime надходять із визначених знімків у пам’яті; застарілі статичні записи `auth.json` очищуються, якщо їх виявлено. +- Застарілий імпорт OAuth з `~/.openclaw/credentials/oauth.json`. - Див. [OAuth](/uk/concepts/oauth). -- Поведінка runtime для secrets і інструменти `audit/configure/apply`: [Керування secrets](/uk/gateway/secrets). +- Поведінка runtime для secrets і інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). ### `auth.cooldowns` @@ -3327,20 +3360,20 @@ openclaw gateway --port 19001 } ``` -- `billingBackoffHours`: базовий backoff у годинах, коли профіль завершується помилкою через справжні - помилки білінгу/недостатнього кредиту (типово: `5`). Явний текст про білінг - усе ще може потрапити сюди навіть у відповідях `401`/`403`, але специфічні для провайдера - зіставники тексту залишаються обмеженими лише провайдером, якому вони належать (наприклад OpenRouter - `Key limit exceeded`). Повторювані повідомлення HTTP `402` про вікно використання або - про ліміти витрат організації/робочого простору натомість лишаються у гілці `rate_limit`. -- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин backoff білінгу для окремих провайдерів. -- `billingMaxHours`: верхня межа в годинах для експоненційного зростання backoff білінгу (типово: `24`). -- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для високовпевнених збоїв `auth_permanent` (типово: `10`). -- `authPermanentMaxMinutes`: верхня межа в хвилинах для зростання backoff `auth_permanent` (типово: `60`). -- `failureWindowHours`: ковзне вікно в годинах, що використовується для лічильників backoff (типово: `24`). -- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile того самого провайдера при помилках перевантаження перед переходом до резервної моделі (типово: `1`). Сюди потрапляють форми на кшталт зайнятості провайдера, як-от `ModelNotReadyException`. -- `overloadedBackoffMs`: фіксована затримка перед повторною спробою перевантаженого провайдера/ротації профілю (типово: `0`). -- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile того самого провайдера при помилках rate limit перед переходом до резервної моделі (типово: `1`). До цього кошика rate limit входить текст у стилі провайдера, як-от `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. +- `billingBackoffHours`: базовий backoff у годинах, коли профіль зазнає помилки через справжні + billing/insufficient-credit помилки (типово: `5`). Явний billing text + усе ще може потрапити сюди навіть при відповідях `401`/`403`, але + text matcher-і для окремих провайдерів залишаються в межах свого провайдера (наприклад, OpenRouter + `Key limit exceeded`). Повторювані HTTP `402` повідомлення usage-window або + spend-limit організації/workspace натомість залишаються в шляху `rate_limit`. +- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин backoff для окремих провайдерів. +- `billingMaxHours`: обмеження в годинах для експоненційного зростання billing backoff (типово: `24`). +- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для high-confidence збоїв `auth_permanent` (типово: `10`). +- `authPermanentMaxMinutes`: обмеження в хвилинах для зростання backoff `auth_permanent` (типово: `60`). +- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників backoff (типово: `24`). +- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile в межах одного провайдера для overloaded errors перед переходом до model fallback (типово: `1`). Сюди потрапляють форми provider-busy, такі як `ModelNotReadyException`. +- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації overloaded provider/profile (типово: `0`). +- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile в межах одного провайдера для rate-limit errors перед переходом до model fallback (типово: `1`). До цього кошика rate-limit входять тексти у стилі провайдерів, такі як `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. --- @@ -3359,10 +3392,10 @@ openclaw gateway --port 19001 } ``` -- Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. +- Типовий log file: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Установіть `logging.file` для стабільного шляху. -- `consoleLevel` підвищується до `debug`, коли використовується `--verbose`. -- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого записи припиняються (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів. +- `consoleLevel` підвищується до `debug` при `--verbose`. +- `maxFileBytes`: максимальний розмір log file у байтах, після якого запис пригнічується (додатне ціле число; типово: `524288000` = 500 MB). Для production deployment використовуйте зовнішню ротацію логів. --- @@ -3399,24 +3432,24 @@ openclaw gateway --port 19001 } ``` -- `enabled`: головний перемикач для виводу інструментування (типово: `true`). -- `flags`: масив рядків-прапорців, що вмикають цільовий вивід журналів (підтримує wildcard, наприклад `"telegram.*"` або `"*"`). -- `stuckSessionWarnMs`: поріг давності в мс для виведення попереджень про застряглі сесії, поки сесія залишається у стані обробки. -- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). -- `otel.endpoint`: URL колектора для експорту OTel. +- `enabled`: головний перемикач виводу instrumentation (типово: `true`). +- `flags`: масив рядків-прапорців, що вмикають цільовий вивід логів (підтримує wildcard-и на кшталт `"telegram.*"` або `"*"`). +- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислі сесії, поки сесія залишається в стані обробки. +- `otel.enabled`: вмикає pipeline експорту OpenTelemetry (типово: `false`). +- `otel.endpoint`: URL-адреса collector для експорту OTel. - `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`. -- `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються із запитами експорту OTel. -- `otel.serviceName`: назва сервісу для атрибутів ресурсу. -- `otel.traces` / `otel.metrics` / `otel.logs`: вмикають експорт trace, metrics або logs. -- `otel.sampleRate`: частота семплювання trace `0`–`1`. -- `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в мс. -- `cacheTrace.enabled`: журналювати знімки cache trace для вбудованих запусків (типово: `false`). -- `cacheTrace.filePath`: шлях виводу для JSONL cache trace (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід cache trace (усе типово: `true`). +- `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються разом із запитами експорту OTel. +- `otel.serviceName`: ім’я сервісу для атрибутів ресурсу. +- `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт trace, metrics або logs. +- `otel.sampleRate`: частота вибірки trace `0`–`1`. +- `otel.flushIntervalMs`: інтервал періодичного flush телеметрії в мс. +- `cacheTrace.enabled`: журналювати знімки cache trace для embedded runs (типово: `false`). +- `cacheTrace.filePath`: шлях виводу для cache trace JSONL (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається до виводу cache trace (усе типово: `true`). --- -## Оновлення +## Update ```json5 { @@ -3435,11 +3468,11 @@ openclaw gateway --port 19001 ``` - `channel`: канал релізів для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`. -- `checkOnStart`: перевіряти оновлення npm під час запуску gateway (типово: `true`). -- `auto.enabled`: увімкнути фонове автооновлення для встановлень пакетів (типово: `false`). -- `auto.stableDelayHours`: мінімальна затримка в годинах перед автозастосуванням stable-каналу (типово: `6`; максимум: `168`). -- `auto.stableJitterHours`: додаткове вікно розтягування розгортання stable-каналу в годинах (типово: `12`; максимум: `168`). -- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу, у годинах (типово: `1`; максимум: `24`). +- `checkOnStart`: перевіряти наявність оновлень npm під час запуску gateway (типово: `true`). +- `auto.enabled`: увімкнути фонове auto-update для package installs (типово: `false`). +- `auto.stableDelayHours`: мінімальна затримка в годинах перед auto-apply для stable channel (типово: `6`; максимум: `168`). +- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable channel у годинах (типово: `12`; максимум: `168`). +- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta channel у годинах (типово: `1`; максимум: `24`). --- @@ -3472,22 +3505,22 @@ openclaw gateway --port 19001 } ``` -- `enabled`: глобальний feature gate ACP (типово: `false`). -- `dispatch.enabled`: незалежний gate для диспетчеризації ходів ACP-сесій (типово: `true`). Установіть `false`, щоб залишити ACP-команди доступними, але заблокувати виконання. -- `backend`: id типового runtime-бекенда ACP (має збігатися із зареєстрованим plugin runtime ACP). -- `defaultAgent`: резервний id цільового ACP-агента, коли spawn не вказує явну ціль. -- `allowedAgents`: allowlist id агентів, дозволених для runtime-сесій ACP; порожнє значення означає відсутність додаткових обмежень. -- `maxConcurrentSessions`: максимальна кількість одночасно активних ACP-сесій. -- `stream.coalesceIdleMs`: вікно idle flush у мс для потокового тексту. -- `stream.maxChunkChars`: максимальний розмір chunk перед розбиттям потокової проєкції блока. -- `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструментів на хід (типово: `true`). +- `enabled`: глобальний feature gate для ACP (типово: `false`). +- `dispatch.enabled`: незалежний gate для dispatch ходів ACP session (типово: `true`). Установіть `false`, щоб зберегти доступність ACP-команд, але заблокувати виконання. +- `backend`: id типового backend ACP runtime (має збігатися із зареєстрованим ACP runtime plugin). +- `defaultAgent`: резервний id цільового ACP agent, коли spawn не задає явної цілі. +- `allowedAgents`: allowlist id агентів, дозволених для ACP runtime sessions; порожнє значення означає відсутність додаткових обмежень. +- `maxConcurrentSessions`: максимальна кількість одночасно активних ACP sessions. +- `stream.coalesceIdleMs`: вікно idle flush у мс для streamed text. +- `stream.maxChunkChars`: максимальний розмір чанка перед розбиттям streamed block projection. +- `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструментів у межах одного ходу (типово: `true`). - `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до термінальних подій ходу. - `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (типово: `"paragraph"`). -- `stream.maxOutputChars`: максимальна кількість символів виводу assistant, проєктованих на хід ACP. +- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, що проєктується за один ACP turn. - `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлень ACP. -- `stream.tagVisibility`: запис зіставлення назв тегів із булевими перевизначеннями видимості для потокових подій. -- `runtime.ttlMinutes`: idle TTL у хвилинах для працівників ACP-сесій до моменту, коли стане можливим очищення. -- `runtime.installCommand`: необов’язкова команда встановлення для запуску під час bootstrap середовища runtime ACP. +- `stream.tagVisibility`: запис імен тегів у перевизначення видимості типу boolean для streamed events. +- `runtime.ttlMinutes`: idle TTL у хвилинах для ACP session workers, після якого вони можуть бути очищені. +- `runtime.installCommand`: необов’язкова команда встановлення, яку слід запускати під час bootstrap середовища ACP runtime. --- @@ -3503,17 +3536,17 @@ openclaw gateway --port 19001 } ``` -- `cli.banner.taglineMode` керує стилем підзаголовка банера: - - `"random"` (типово): змінні кумедні/сезонні підзаголовки. - - `"default"`: фіксований нейтральний підзаголовок (`All your chats, one OpenClaw.`). - - `"off"`: без тексту підзаголовка (заголовок/версія банера все одно показуються). -- Щоб приховати весь банер (а не лише підзаголовки), установіть env `OPENCLAW_HIDE_BANNER=1`. +- `cli.banner.taglineMode` керує стилем слогана банера: + - `"random"` (типово): змінні кумедні/сезонні слогани. + - `"default"`: фіксований нейтральний слоган (`All your chats, one OpenClaw.`). + - `"off"`: без тексту слогана (заголовок/версія банера все одно показуються). +- Щоб приховати весь банер (а не лише слогани), установіть env `OPENCLAW_HIDE_BANNER=1`. --- ## Wizard -Метадані, які записують керовані CLI-потоки налаштування (`onboard`, `configure`, `doctor`): +Метадані, які записуються потоками керованого налаштування CLI (`onboard`, `configure`, `doctor`): ```json5 { @@ -3531,13 +3564,13 @@ openclaw gateway --port 19001 ## Identity -Див. поля identity в `agents.list` у розділі [Типові значення агента](#agent-defaults). +Див. поля identity у `agents.list` у розділі [Типові значення агентів](#agent-defaults). --- -## Bridge (застаріло, вилучено) +## Bridge (застаріло, видалено) -Поточні збірки більше не містять TCP bridge. Вузли підключаються через WebSocket Gateway. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація не проходить, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). +Поточні збірки більше не містять TCP bridge. Nodes підключаються через Gateway WebSocket. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). @@ -3566,22 +3599,22 @@ openclaw gateway --port 19001 cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs - webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth - sessionRetention: "24h", // duration string or false + webhook: "https://example.invalid/legacy", // застарілий резервний варіант для збережених завдань notify:true + webhookToken: "replace-with-dedicated-token", // необов’язковий bearer token для вихідної auth webhook + sessionRetention: "24h", // рядок тривалості або false runLog: { - maxBytes: "2mb", // default 2_000_000 bytes - keepLines: 2000, // default 2000 + maxBytes: "2mb", // типово 2_000_000 байтів + keepLines: 2000, // типово 2000 }, }, } ``` -- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених стенограм cron. Типове значення: `24h`; установіть `false`, щоб вимкнути. -- `runLog.maxBytes`: максимальний розмір одного файла журналу запуску (`cron/runs/.jsonl`) перед очищенням. Типове значення: `2_000_000` байтів. -- `runLog.keepLines`: найновіші рядки, які зберігаються, коли спрацьовує очищення журналу запуску. Типове значення: `2000`. -- `webhookToken`: bearer-токен, який використовується для доставки cron webhook POST (`delivery.mode = "webhook"`); якщо не задано, заголовок автентифікації не надсилається. -- `webhook`: застарілий резервний URL webhook (http/https), який використовується лише для збережених завдань, у яких досі є `notify: true`. +- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених cron transcript. Типове значення: `24h`; установіть `false`, щоб вимкнути. +- `runLog.maxBytes`: максимальний розмір одного файлу журналу запуску (`cron/runs/.jsonl`) перед очищенням. Типове значення: `2_000_000` байтів. +- `runLog.keepLines`: кількість найновіших рядків, які зберігаються при спрацюванні очищення журналу запуску. Типове значення: `2000`. +- `webhookToken`: bearer token, який використовується для доставки cron webhook через POST (`delivery.mode = "webhook"`); якщо не задано, заголовок auth не надсилається. +- `webhook`: застаріла резервна URL-адреса webhook (http/https), яка використовується лише для збережених завдань, що досі мають `notify: true`. ### `cron.retry` @@ -3599,9 +3632,9 @@ openclaw gateway --port 19001 - `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань при тимчасових помилках (типово: `3`; діапазон: `0`–`10`). - `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів). -- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Якщо пропущено, повторні спроби виконуються для всіх тимчасових типів. +- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Не вказуйте, щоб повторювати для всіх тимчасових типів. -Застосовується лише до одноразових cron-завдань. Повторювані завдання використовують окрему обробку збоїв. +Застосовується лише до одноразових cron jobs. Для recurring jobs використовується окрема обробка збоїв. ### `cron.failureAlert` @@ -3619,11 +3652,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: увімкнути сповіщення про збої для cron-завдань (типово: `false`). -- `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мін.: `1`). -- `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число). -- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` надсилає POST до налаштованого webhook. -- `accountId`: необов’язковий id облікового запису або каналу для обмеження доставки сповіщень. +- `enabled`: увімкнути попередження про збої для cron jobs (типово: `false`). +- `after`: кількість послідовних збоїв перед надсиланням попередження (додатне ціле число, мінімум: `1`). +- `cooldownMs`: мінімальна кількість мілісекунд між повторними попередженнями для того самого завдання (невід’ємне ціле число). +- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` виконує POST на налаштований webhook. +- `accountId`: необов’язковий id облікового запису або каналу для обмеження доставки попередження. ### `cron.failureDestination` @@ -3640,51 +3673,51 @@ openclaw gateway --port 19001 } ``` -- Типова ціль для сповіщень про збої cron у всіх завданнях. +- Типова ціль для сповіщень про збої cron для всіх завдань. - `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо даних про ціль. -- `channel`: перевизначення каналу для доставки announce. `"last"` повторно використовує останній відомий канал доставки. -- `to`: явна ціль announce або URL webhook. Обов’язково для режиму webhook. +- `channel`: перевизначення каналу для доставки через announce. `"last"` повторно використовує останній відомий канал доставки. +- `to`: явна ціль announce або URL-адреса webhook. Обов’язково для режиму webhook. - `accountId`: необов’язкове перевизначення облікового запису для доставки. - `delivery.failureDestination` для окремого завдання перевизначає це глобальне типове значення. -- Коли не задано ні глобальну, ні індивідуальну ціль збоїв, завдання, які вже доставляють через `announce`, у разі збою використовують як резервну ціль той самий основний announce-target. -- `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` самого завдання не дорівнює `"webhook"`. +- Якщо не задано ні глобальну, ні окрему для завдання ціль збою, завдання, які вже доставляють через `announce`, у разі збою повертаються до цієї основної цілі announce. +- `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо тільки основне `delivery.mode` завдання не дорівнює `"webhook"`. Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [background tasks](/uk/automation/tasks). --- -## Змінні шаблону медіамоделі +## Змінні шаблону моделі медіа -Заповнювачі шаблонів, що розгортаються в `tools.media.models[].args`: +Заповнювачі шаблону, що розгортаються в `tools.media.models[].args`: | Змінна | Опис | | ----------------- | ------------------------------------------------- | | `{{Body}}` | Повний текст вхідного повідомлення | | `{{RawBody}}` | Сирий текст (без обгорток історії/відправника) | -| `{{BodyStripped}}`| Текст без згадок у групі | +| `{{BodyStripped}}` | Текст без згадок у групі | | `{{From}}` | Ідентифікатор відправника | -| `{{To}}` | Ідентифікатор одержувача | +| `{{To}}` | Ідентифікатор призначення | | `{{MessageSid}}` | Ідентифікатор повідомлення каналу | | `{{SessionId}}` | UUID поточної сесії | -| `{{IsNewSession}}`| `"true"`, коли створено нову сесію | +| `{{IsNewSession}}` | `"true"`, коли створено нову сесію | | `{{MediaUrl}}` | Псевдо-URL вхідного медіа | | `{{MediaPath}}` | Локальний шлях до медіа | | `{{MediaType}}` | Тип медіа (image/audio/document/…) | -| `{{Transcript}}` | Аудіостенограма | -| `{{Prompt}}` | Визначений медіазапит для записів CLI | +| `{{Transcript}}` | Audio transcript | +| `{{Prompt}}` | Визначений медіа-prompt для записів CLI | | `{{MaxChars}}` | Визначена максимальна кількість символів виводу для записів CLI | | `{{ChatType}}` | `"direct"` або `"group"` | -| `{{GroupSubject}}`| Тема групи (наскільки можливо) | -| `{{GroupMembers}}`| Попередній перегляд учасників групи (наскільки можливо) | -| `{{SenderName}}` | Відображуване ім’я відправника (наскільки можливо) | -| `{{SenderE164}}` | Номер телефону відправника (наскільки можливо) | +| `{{GroupSubject}}` | Тема групи (best effort) | +| `{{GroupMembers}}` | Попередній перегляд учасників групи (best effort) | +| `{{SenderName}}` | Відображуване ім’я відправника (best effort) | +| `{{SenderE164}}` | Номер телефону відправника (best effort) | | `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) | --- -## Включення конфігурації (`$include`) +## Include конфігурації (`$include`) -Розбивайте конфігурацію на кілька файлів: +Розділяйте конфігурацію на кілька файлів: ```json5 // ~/.openclaw/openclaw.json @@ -3700,12 +3733,12 @@ openclaw gateway --port 19001 **Поведінка злиття:** - Один файл: замінює об’єкт, у якому міститься. -- Масив файлів: глибоко зливається в заданому порядку (пізніші перевизначають ранніші). -- Сусідні ключі: зливаються після включень (перевизначають включені значення). -- Вкладені включення: до 10 рівнів углиб. -- Шляхи: визначаються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми/форми з `../` дозволені лише тоді, коли після визначення вони все одно залишаються в межах цього кордону. -- Помилки: чіткі повідомлення про відсутні файли, помилки парсингу та циклічні включення. +- Масив файлів: deep-merge у зазначеному порядку (пізніші перевизначають раніші). +- Сусідні ключі: зливаються після include (перевизначають включені значення). +- Вкладені include: до 10 рівнів глибини. +- Шляхи: визначаються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли вони все одно визначаються в межах цього кордону. +- Помилки: чіткі повідомлення для відсутніх файлів, помилок парсингу та циклічних include. --- -_Пов’язане: [Configuration](/uk/gateway/configuration) · [Configuration Examples](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_ +_Пов’язане: [Конфігурація](/uk/gateway/configuration) · [Приклади конфігурації](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_ diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 53bbb0e12..e985ca072 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,29 +1,29 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресій для помилок моделі/провайдера - - Налагодження поведінки gateway + агента -summary: 'Набір для тестування: unit/e2e/live набори, Docker-раннери та що охоплює кожен тест' + - Додавання регресій для помилок моделей/провайдерів + - Налагодження поведінки gateway + agent +summary: 'Набір для тестування: модульні/e2e/live набори, виконавці Docker і що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-10T20:23:45Z" + generated_at: "2026-04-10T20:28:58Z" model: gpt-5.4 provider: openai - source_hash: e24030b221699c7695ab5c87409a2646b7c5d014780a3482410c3375be8e3bd8 + source_hash: e19cfbfcc708c0075d77364e2f20d8e8b8c4300cba97b0c525524882612b7cad source_path: help/testing.md workflow: 15 --- # Тестування -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-раннерів. +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір виконавців Docker. Цей документ — посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює) -- Які команди запускати для типових сценаріїв (локально, перед push, налагодження) +- Які команди запускати для типових робочих сценаріїв (локально, перед push, налагодження) - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів -- Як додавати регресії для реальних проблем із моделями/провайдерами +- Як додавати регресії для реальних проблем моделей/провайдерів ## Швидкий старт @@ -31,13 +31,13 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm test` - Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` -- Прямий цикл Vitest watch: `pnpm test:watch` -- Пряме націлення на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Під час ітерацій над однією помилкою спершу віддавайте перевагу цільовим запускам. +- Прямий цикл спостереження Vitest: `pnpm test:watch` +- Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Під час ітерації над однією помилкою спершу віддавайте перевагу цільовим запускам. - QA-сайт на базі Docker: `pnpm qa:lab:up` -- QA-сценарій на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- QA-смуга на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви змінюєте тести або хочете більшої впевненості: +Коли ви змінюєте тести або хочете більше впевненості: - Gate покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` @@ -45,118 +45,118 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): - Live-набір (моделі + gateway tool/image probes): `pnpm test:live` -- Тихий запуск одного live-файлу: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Точково запустити один live-файл у тихому режимі: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Порада: коли вам потрібен лише один проблемний кейс, звужуйте live-тести через змінні середовища allowlist, описані нижче. +Порада: коли потрібен лише один проблемний випадок, звужуйте live-тести через змінні середовища allowlist, описані нижче. -## QA-специфічні раннери +## Спеціальні виконавці QA -Ці команди використовуються поряд з основними тестовими наборами, коли вам потрібен реалізм qa-lab: +Ці команди розташовані поруч з основними наборами тестів, коли потрібен реалізм QA-lab: - `pnpm openclaw qa suite` - Запускає QA-сценарії з репозиторію безпосередньо на хості. - - За замовчуванням запускає кілька вибраних сценаріїв паралельно в ізольованих gateway workers, до 64 workers або кількості вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати кількість workers, або `--concurrency 1` для старішого послідовного режиму. + - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими працівниками gateway, до 64 працівників або кількості вибраних сценаріїв. Використовуйте `--concurrency ` для налаштування кількості працівників або `--concurrency 1` для старішої послідовної смуги. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий QA-набір у тимчасовій Multipass Linux VM. + - Запускає той самий QA-набір усередині тимчасової Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски передають у guest підтримувані QA-автентифікаційні входи, які практично використовувати там: - ключі провайдерів із env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб guest міг записувати назад через змонтований workspace. - - Записує звичайний QA-звіт + summary, а також логи Multipass у + - Live-запуски пересилають підтримувані вхідні дані автентифікації QA, практичні для гостьової системи: + ключі провайдерів на основі env, шлях до конфігурації live-провайдера QA і `CODEX_HOME`, якщо він присутній. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через змонтований workspace. + - Записує стандартний QA-звіт і підсумок, а також журнали Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA-сайт на базі Docker для операторської QA-роботи. + - Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі. -## Тестові набори (що де запускається) +## Набори тестів (що де запускається) -Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості): +Думайте про набори як про «зростання реалізму» (і зростання нестабільності/вартості): ### Unit / integration (типово) - Команда: `pnpm test` -- Config: десять послідовних shard-запусків (`vitest.full-*.config.ts`) по наявних scoped Vitest projects -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelisted `ui` node-тести, охоплені `vitest.unit.config.ts` +- Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) по наявних scoped Vitest projects +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, охоплені `vitest.unit.config.ts` - Обсяг: - - Чисті unit-тести - - In-process integration-тести (gateway auth, routing, tooling, parsing, config) - - Детерміновані регресії для відомих багів + - Чисті модульні тести + - Внутрішньопроцесні інтеграційні тести (автентифікація gateway, маршрутизація, інструменти, парсинг, конфігурація) + - Детерміновані регресії для відомих помилок - Очікування: - - Запускається в CI + - Запускаються в CI - Реальні ключі не потрібні - - Має бути швидким і стабільним + - Мають бути швидкими й стабільними - Примітка про projects: - - Ненацілений `pnpm test` тепер запускає одинадцять менших shard-конфігів (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного великого native root-project process. Це зменшує пікове RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - - `pnpm test --watch` і далі використовує native root `vitest.config.ts` project graph, оскільки багатошардовий watch-цикл непрактичний. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні file/directory targets через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. - - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff зачіпає лише routable source/test files; зміни config/setup, як і раніше, повертаються до широкого root-project rerun. - - Вибрані тести `plugin-sdk` і `commands` також маршрутизуються через окремі легкі lanes, які пропускають `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються в наявних lanes. - - Вибрані helper source files у `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними sibling tests у цих light lanes, щоб зміни helper не спричиняли повторний запуск усього важкого набору для цього каталогу. - - `auto-reply` тепер має три окремі buckets: top-level core helpers, top-level `reply.*` integration tests і піддерево `src/auto-reply/reply/**`. Це не дає найважчій роботі reply harness потрапляти до дешевих status/chunk/token tests. + - Ненацілений `pnpm test` тепер запускає одинадцять менших shard-конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project процесу. Це зменшує піковий RSS на навантажених машинах і не дає роботі auto-reply/extension виснажувати нерелевантні набори. + - `pnpm test --watch` і далі використовує native root `vitest.config.ts` project graph, тому що цикл watch із багатьма shard-проєктами непрактичний. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. + - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише routable source/test файлів; зміни config/setup і далі повертаються до широкого повторного запуску root-project. + - Вибрані тести `plugin-sdk` і `commands` також маршрутизуються через окремі легкі lanes, які пропускають `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. + - Вибрані helper source-файли `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними сусідніми тестами в цих легких lanes, тож редагування helper-файлів не вимагає повторного запуску повного важкого набору для цього каталогу. + - `auto-reply` тепер має три окремі buckets: top-level core helpers, top-level `reply.*` integration tests і піддерево `src/auto-reply/reply/**`. Це не дає найважчій роботі reply harness впливати на дешеві тести status/chunk/token. - Примітка про embedded runner: - - Коли ви змінюєте входи виявлення message-tool або runtime context compaction, - зберігайте покриття на обох рівнях. - - Додавайте сфокусовані helper-регресії для чистих меж routing/normalization. - - Також підтримуйте в доброму стані embedded runner integration suites: + - Коли ви змінюєте вхідні дані виявлення message-tool або контекст runtime compaction, + зберігайте обидва рівні покриття. + - Додавайте фокусні helper-регресії для чистих меж маршрутизації/нормалізації. + - Також підтримуйте в здоровому стані інтеграційні набори embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped ids і поведінка compaction усе ще проходять - через реальні шляхи `run.ts` / `compact.ts`; тести лише на helper-рівні не є - достатньою заміною цим integration-шляхам. + - Ці набори перевіряють, що scoped id і поведінка compaction і далі проходять + через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є + достатньою заміною для цих інтеграційних шляхів. - Примітка про pool: - - Базовий config Vitest тепер за замовчуванням використовує `threads`. - - Спільний config Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, e2e і live configs. - - Root UI lane зберігає своє налаштування `jsdom` і optimizer, але тепер теж працює на спільному non-isolated runner. - - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільного config Vitest. - - Спільний launcher `scripts/run-vitest.mjs` тепер також за замовчуванням додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. + - Базова конфігурація Vitest тепер типово використовує `threads`. + - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує неізольований runner у root projects, e2e і live configs. + - Коренева смуга UI зберігає своє налаштування `jsdom` і optimizer, але тепер також працює на спільному неізольованому runner. + - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. + - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. - Примітка про швидкі локальні ітерації: - - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи однозначно відповідають меншому набору. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим лімітом workers. - - Автомасштабування локальних workers тепер навмисно консервативніше і також відступає, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. - - Базовий config Vitest позначає projects/config files як `forceRerunTriggers`, щоб reruns у changed-mode залишалися коректними, коли змінюється wiring тестів. - - Config зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. -- Примітка про perf-debug: - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість import, а також import-breakdown output. - - `pnpm test:perf:imports:changed` обмежує той самий профільований вигляд файлами, зміненими відносно `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` з native root-project path для цього закоміченого diff і виводить wall time та macOS max RSS. -- `pnpm test:perf:changed:bench -- --worktree` вимірює поточне брудне дерево, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root Vitest config. - - `pnpm test:perf:profile:main` записує CPU-профіль main thread для старту Vitest/Vite і transform overhead. - - `pnpm test:perf:profile:runner` записує CPU+heap-профілі runner для unit-набору з вимкненим файловим паралелізмом. + - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи чисто зіставляються з меншим набором. + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищою межею працівників. + - Автомасштабування локальних працівників тепер навмисно консервативне і також зменшується, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. + - Базова конфігурація Vitest позначає projects/config files як `forceRerunTriggers`, щоб повторні запуски в режимі changed залишалися коректними, коли змінюється wiring тестів. + - Конфігурація зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете явне розташування кешу для прямого профілювання. +- Примітка про налагодження продуктивності: + - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту та вивід розбивки імпортів. + - `pnpm test:perf:imports:changed` звужує той самий профільований перегляд до файлів, змінених відносно `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` з native root-project шляхом для цього зафіксованого diff і виводить wall time та macOS max RSS. +- `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного брудного дерева, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і кореневу конфігурацію Vitest. + - `pnpm test:perf:profile:main` записує CPU profile основного потоку для накладних витрат запуску та transform у Vitest/Vite. + - `pnpm test:perf:profile:runner` записує CPU+heap profiles runner-а для unit-набору з вимкненим паралелізмом файлів. ### E2E (gateway smoke) - Команда: `pnpm test:e2e` -- Config: `vitest.e2e.config.ts` +- Конфігурація: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- Типові параметри runtime: - - Використовує Vitest `threads` з `isolate: false`, узгоджено з рештою репозиторію. - - Використовує адаптивну кількість workers (CI: до 2, локально: 1 за замовчуванням). +- Типові налаштування runtime: + - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. + - Використовує адаптивну кількість працівників (CI: до 2, локально: 1 за замовчуванням). - За замовчуванням працює в тихому режимі, щоб зменшити накладні витрати на console I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` щоб примусово встановити кількість workers (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний console output. + - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість працівників (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль. - Обсяг: - - End-to-end поведінка gateway з кількома інстансами - - Поверхні WebSocket/HTTP, pairing вузлів і важчі мережеві сценарії + - Наскрізна поведінка gateway з кількома екземплярами + - Поверхні WebSocket/HTTP, pairing вузлів і більш важкі мережеві сценарії - Очікування: - - Запускається в CI (коли ввімкнено в pipeline) + - Запускається в CI (коли увімкнено в pipeline) - Реальні ключі не потрібні - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) -### E2E: smoke OpenShell backend +### E2E: backend smoke OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `test/openshell-sandbox.e2e.test.ts` - Обсяг: - - Запускає ізольований OpenShell gateway на хості через Docker + - Запускає ізольований gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє OpenClaw OpenShell backend через реальні `sandbox ssh-config` + SSH exec - - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge + - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + виконання SSH + - Перевіряє remote-canonical поведінку файлової системи через міст fs sandbox-а - Очікування: - - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потребує локального CLI `openshell` і працездатного Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує test gateway і sandbox + - Лише за запитом; не входить до типового запуску `pnpm test:e2e` + - Потрібен локальний CLI `openshell` і працездатний демон Docker + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий gateway і sandbox - Корисні перевизначення: - `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест під час ручного запуску ширшого e2e-набору - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб вказати нестандартний CLI binary або wrapper script @@ -164,145 +164,145 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` -- Config: `vitest.live.config.ts` +- Конфігурація: `vitest.live.config.ts` - Файли: `src/**/*.live.test.ts` - Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - - «Чи цей провайдер/модель справді працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей tool calling, проблем автентифікації та поведінки rate limit + - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» + - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем автентифікації та поведінки за rate limit - Очікування: - Навмисно нестабільний для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштує грошей / використовує ліміти частоти + - Коштує грошей / використовує rate limits - Краще запускати звужені підмножини, а не «все» -- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API keys. -- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють config/auth material у тимчасовий test home, щоб unit-fixtures не могли змінити ваш реальний `~/.openclaw`. +- Live-запуски підвантажують `~/.profile`, щоб підхопити відсутні API-ключі. +- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий test home, щоб unit-fixtures не могли змінювати ваш реальний `~/.openclaw`. - Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли свідомо хочете, щоб live-тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але прибирає додаткове повідомлення про `~/.profile` і приглушує логи bootstrap gateway/Bonjour chatter. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. -- Ротація API keys (залежно від провайдера): задайте `*_API_KEYS` у форматі кома/крапка з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використайте перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. +- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення `~/.profile` і вимикає журнали bootstrap gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні журнали запуску. +- Ротація API-ключів (залежно від провайдера): установіть `*_API_KEYS` у форматі comma/semicolon або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використайте перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. - Вивід прогресу/heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, щоб було видно активність під час довгих викликів провайдера, навіть коли захоплення console у Vitest працює тихо. - - `vitest.live.config.ts` вимикає перехоплення console у Vitest, тому рядки прогресу провайдера/gateway виводяться одразу під час live-запусків. - - Налаштовуйте heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Live-набори тепер виводять рядки прогресу в stderr, тож довгі виклики провайдера помітно активні навіть тоді, коли перехоплення консолі Vitest працює тихо. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/gateway надходили одразу під час live-запусків. + - Налаштовуйте heartbeat прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? -Користуйтеся цією таблицею рішень: +Використовуйте цю таблицю рішень: -- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змін було багато) -- Торкаєтеся gateway networking / WS protocol / pairing: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / tool calling: запустіть звужений `pnpm test:live` +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) +- Торкаєтесь мережевої частини gateway / протоколу WS / pairing: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / специфічні збої провайдера / виклик інструментів: запускайте звужений `pnpm test:live` -## Live: огляд можливостей Android node +## Live: перевірка можливостей Android node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яка зараз оголошена** підключеним Android node, і перевірити поведінку контракту команд. +- Мета: викликати **кожну команду, яку наразі рекламує** підключений Android node, і перевірити поведінку контракту команд. - Обсяг: - - Попередньо підготовлене/ручне налаштування (набір не встановлює, не запускає і не виконує pairing застосунку). - - Перевірка `node.invoke` у gateway для вибраного Android node, команда за командою. -- Потрібна попередня підготовка: - - Android-застосунок уже підключений і paired до gateway. - - Застосунок утримується на передньому плані. - - Дозволи/згода на захоплення надані для можливостей, які ви очікуєте успішно пройти. + - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не виконує pairing для застосунку). + - Перевірка gateway `node.invoke` команда за командою для вибраного Android node. +- Необхідне попереднє налаштування: + - Android-застосунок уже підключено й прив’язано до gateway. + - Застосунок має залишатися на передньому плані. + - Для можливостей, які ви очікуєте успішно пройти, мають бути надані дозволи/згода на захоплення. - Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. - Повні відомості про налаштування Android: [Android App](/uk/platforms/android) -## Live: smoke моделей (ключі профілів) +## Live: перевірка моделей (profile keys) -Live-тести поділено на два рівні, щоб ми могли ізолювати збої: +Live-тести поділено на два шари, щоб можна було ізолювати збої: -- «Пряма модель» показує, чи провайдер/модель взагалі може відповісти з наданим ключем. -- «Gateway smoke» показує, чи працює повний конвеєр gateway+agent для цієї моделі (сесії, історія, tools, sandbox policy тощо). +- «Direct model» показує, чи може провайдер/модель взагалі відповісти з наданим ключем. +- «Gateway smoke» показує, чи працює для цієї моделі повний конвеєр gateway+agent (сесії, історія, інструменти, політика sandbox тощо). -### Рівень 1: Пряме завершення моделі (без gateway) +### Шар 1: пряме завершення моделі (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - Перелічити виявлені моделі - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані - - Виконати невелике завершення для кожної моделі (і цільові регресії там, де це потрібно) + - Виконати невелике completion для кожної моделі (і цільові регресії, де це потрібно) - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускати Vitest напряму) -- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб справді запустити цей набір; інакше він буде пропущений, щоб `pnpm test:live` залишався зосередженим на gateway smoke + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) +- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб справді запустити цей набір; інакше його буде пропущено, щоб `pnpm test:live` залишався зосередженим на gateway smoke - Як вибирати моделі: - - `OPENCLAW_LIVE_MODELS=modern` для запуску modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для modern allowlist + - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для сучасного allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Для modern/all sweeps за замовчуванням використовується підібране обмеження з високим сигналом; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого ліміту. + - Сучасні/all-прогони за замовчуванням використовують відібрану межу високосигнальних моделей; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного сучасного прогону або додатне число для меншої межі. - Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - За замовчуванням: сховище профілів і резервні варіанти з env - - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** + - За замовчуванням: profile store і резервні варіанти env + - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** - Навіщо це існує: - Відокремлює «API провайдера зламаний / ключ недійсний» від «конвеєр gateway agent зламаний» - - Містить невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки tool-call) + - Містить невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки виклику інструментів) -### Рівень 2: Gateway + smoke dev agent (що насправді робить "@openclaw") +### Шар 2: gateway + smoke dev agent-а (те, що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - - Запустити in-process gateway - - Створити/оновити сесію `agent:dev:*` (з перевизначенням моделі для кожного запуску) + - Підняти in-process gateway + - Створити/змінити сесію `agent:dev:*` (перевизначення моделі на запуск) - Ітеруватися по моделях із ключами й перевіряти: - - «змістовну» відповідь (без tools) - - що справжній виклик tool працює (read probe) - - необов’язкові додаткові перевірки tool (exec+read probe) - - що шляхи регресії OpenAI (лише tool-call → подальший крок) продовжують працювати -- Відомості про probes (щоб ви могли швидко пояснювати збої): - - `read` probe: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce. - - `exec+read` probe: тест просить агента записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. + - «змістовну» відповідь (без інструментів) + - що реальний виклик інструмента працює (read probe) + - необов’язкові додаткові перевірки інструментів (exec+read probe) + - що шляхи регресій OpenAI (лише tool-call → подальший крок) і далі працюють +- Деталі probe-ів (щоб ви могли швидко пояснювати збої): + - `read` probe: тест записує nonce-файл у workspace і просить agent-а `read` його та повернути nonce назад. + - `exec+read` probe: тест просить agent-а записати nonce у тимчасовий файл через `exec`, а потім зчитати його назад через `read`. - image probe: тест прикріплює згенерований PNG (cat + випадковий код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускати Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - Як вибирати моделі: - - За замовчуванням: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для modern allowlist + - За замовчуванням: сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для сучасного allowlist - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір - - Для modern/all gateway sweeps за замовчуванням використовується підібране обмеження з високим сигналом; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого ліміту. -- Як вибирати провайдерів (щоб уникнути «всього OpenRouter»): + - Сучасні/all gateway-прогони за замовчуванням використовують відібрану межу високосигнальних моделей; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного сучасного прогону або додатне число для меншої межі. +- Як вибирати провайдерів (уникаючи «усе з OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) - Tool + image probes у цьому live-тесті завжди ввімкнені: - - `read` probe + `exec+read` probe (навантаження на tools) - - image probe запускається, коли модель оголошує підтримку image input - - Потік (на високому рівні): - - Тест генерує маленький PNG із “CAT” + випадковим кодом (`src/gateway/live-image-probe.ts`) + - `read` probe + `exec+read` probe (навантаження на інструменти) + - image probe запускається, коли модель рекламує підтримку введення зображень + - Потік (високорівнево): + - Тест генерує крихітний PNG із «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - Gateway розбирає attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Embedded agent пересилає мультимодальне повідомлення користувача до моделі - - Перевірка: відповідь містить `cat` + код (допускається OCR tolerance: незначні помилки) + - Gateway парсить вкладення в `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Embedded agent пересилає мультимодальне повідомлення користувача моделі + - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) -Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: +Порада: щоб побачити, що можна тестувати на вашій машині (і точні id `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke CLI backend (Claude, Codex, Gemini або інші локальні CLI) +## Live: smoke backend-а CLI (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + agent з використанням локального CLI backend, не торкаючись вашого типового config. -- Типові параметри smoke для конкретного backend містяться у визначенні `cli-backend.ts` відповідного extension. +- Мета: перевірити конвеєр Gateway + agent із локальним backend-ом CLI, не торкаючись вашої типової конфігурації. +- Типові значення smoke для конкретного backend-а знаходяться у визначенні `cli-backend.ts` розширення-власника. - Увімкнення: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускати Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Типові значення: - - Типовий provider/model: `claude-cli/claude-sonnet-4-6` - - Поведінка command/args/image береться з метаданих plugin відповідного CLI backend. -- Перевизначення (необов’язково): + - Типовий провайдер/модель: `claude-cli/claude-sonnet-4-6` + - Поведінка command/args/image береться з метаданих plugin-а backend-а CLI-власника. +- Перевизначення (необов’язкові): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` щоб надіслати справжнє image attachment (шляхи вставляються в prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` щоб передавати шляхи до image files як CLI args замість вставки в prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати передаванням image args, коли встановлено `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` щоб надіслати другий хід і перевірити потік resume. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` щоб вимкнути типову перевірку безперервності однієї сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати справжнє вкладення-зображення (шляхи інжектуються в prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як аргументи CLI замість інжекції в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати способом передавання аргументів зображення, коли встановлено `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити потік resume. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності в тій самій сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль переключення). Приклад: @@ -312,13 +312,13 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:live src/gateway/gateway-cli-backend.live.test.ts ``` -Docker-рецепт: +Рецепт Docker: ```bash pnpm test:docker:live-cli-backend ``` -Docker-рецепти для окремих провайдерів: +Рецепти Docker для одного провайдера: ```bash pnpm test:docker:live-cli-backend:claude @@ -329,28 +329,28 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Docker-раннер розташований у `scripts/test-live-cli-backend-docker.sh`. -- Він запускає live smoke CLI-backend усередині Docker-образу репозиторію як непривілейований користувач `node`. -- Він визначає метадані CLI smoke із відповідного extension, а потім встановлює відповідний Linux CLI package (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний префікс за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` вимагає portable Claude Code subscription OAuth через `~/.claude/.credentials.json` із `claudeAiOauth.subscriptionType` або `CLAUDE_CODE_OAUTH_TOKEN` із `claude setup-token`. Спочатку він підтверджує прямий `claude -p` у Docker, а потім запускає два ходи Gateway CLI-backend без збереження env-змінних API key Anthropic. Цей subscription lane за замовчуванням вимикає probes Claude MCP/tool та image, оскільки Claude наразі маршрутизує використання сторонніх застосунків через білінг extra-usage, а не звичайні ліміти subscription plan. -- Live smoke CLI-backend тепер перевіряє той самий повний потік end-to-end для Claude, Codex і Gemini: текстовий хід, хід класифікації image, потім виклик MCP tool `cron`, перевірений через gateway CLI. -- Типовий smoke для Claude також оновлює сесію з Sonnet до Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. +- Виконавець Docker розташовано в `scripts/test-live-cli-backend-docker.sh`. +- Він запускає live smoke backend-а CLI всередині Docker-образу репозиторію від імені непривілейованого користувача `node`. +- Він визначає метадані smoke CLI з розширення-власника, а потім установлює відповідний Linux-пакет CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний префікс за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` потребує переносної OAuth-підписки Claude Code через `~/.claude/.credentials.json` із `claudeAiOauth.subscriptionType` або `CLAUDE_CODE_OAUTH_TOKEN` від `claude setup-token`. Спершу він доводить, що прямий `claude -p` у Docker працює, а потім запускає два ходи Gateway CLI-backend без збереження змінних середовища ключа Anthropic API. Ця смуга підписки типово вимикає probe-и інструмента/image Claude MCP, оскільки Claude наразі маршрутизує використання сторонніх застосунків через білінг додаткового використання, а не через звичайні ліміти тарифного плану підписки. +- Live smoke backend-а CLI тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через gateway CLI. +- Типовий smoke Claude також змінює сесію із Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. ## Live: smoke ACP bind (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік ACP conversation-bind із live ACP agent: +- Мета: перевірити реальний потік прив’язки розмови ACP із live ACP agent-ом: - надіслати `/acp spawn --bind here` - - прив’язати синтетичну conversation message-channel на місці - - надіслати звичайний подальший хід у тій самій conversation - - перевірити, що подальший хід потрапляє в transcript прив’язаної ACP session + - прив’язати синтетичну розмову message-channel на місці + - надіслати звичайне подальше повідомлення в тій самій розмові + - перевірити, що подальше повідомлення потрапляє в transcript прив’язаної сесії ACP - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Типові значення: - - ACP agents у Docker: `claude,codex,gemini` + - ACP agent-и в Docker: `claude,codex,gemini` - ACP agent для прямого `pnpm test:live ...`: `claude` - - Синтетичний channel: контекст conversation у стилі Slack DM + - Синтетичний channel: контекст розмови в стилі Slack DM - ACP backend: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -359,8 +359,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Примітки: - - Цей lane використовує поверхню gateway `chat.send` з admin-only синтетичними полями originating-route, щоб тести могли прикріплювати контекст message-channel без імітації зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent плагіна `acpx` для вибраного ACP harness agent. + - Ця смуга використовує поверхню gateway `chat.send` з admin-only synthetic originating-route fields, щоб тести могли приєднати контекст message-channel, не вдаючи зовнішню доставку. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent-ів plugin-а `acpx` для вибраного ACP harness agent-а. Приклад: @@ -370,13 +370,13 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:live src/gateway/gateway-acp-bind.live.test.ts ``` -Docker-рецепт: +Рецепт Docker: ```bash pnpm test:docker:live-acp-bind ``` -Docker-рецепти для окремих agent: +Рецепти Docker для одного agent-а: ```bash pnpm test:docker:live-acp-bind:claude @@ -384,29 +384,31 @@ pnpm test:docker:live-acp-bind:codex pnpm test:docker:live-acp-bind:gemini ``` -Примітки щодо Docker: +Примітки про Docker: -- Docker-раннер розташований у `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він запускає smoke ACP bind послідовно для всіх підтримуваних live CLI agents: `claude`, `codex`, потім `gemini`. +- Виконавець Docker розташовано в `scripts/test-live-acp-bind-docker.sh`. +- За замовчуванням він запускає smoke ACP bind для всіх підтримуваних live CLI agent-ів послідовно: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. -- Він використовує `~/.profile`, підготовлює відповідний auth material CLI у контейнері, встановлює `acpx` у записуваний npm-префікс, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо він відсутній. -- Усередині Docker раннер установлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера із завантаженого профілю доступними для дочірнього harness CLI. +- Він підвантажує `~/.profile`, підготовлює відповідний auth-матеріал CLI у контейнер, установлює `acpx` у записуваний npm-префікс, а потім установлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо він відсутній. +- Усередині Docker виконавець установлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера із завантаженого профілю доступними для дочірнього harness CLI. -## Live: smoke Codex app-server harness +## Live: smoke harness app-server Codex -- Мета: перевірити harness Codex, що належить plugin, через звичайний метод gateway +- Мета: перевірити harness Codex, що належить plugin-у, через звичайний метод gateway `agent`: - - завантажити bundled plugin `codex` + - завантажити вбудований plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - надіслати перший хід gateway agent до `codex/gpt-5.4` - - надіслати другий хід до тієї самої сесії OpenClaw і перевірити, що потік + - надіслати другий хід у ту саму сесію OpenClaw і перевірити, що потік app-server може відновитися - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Типова модель: `codex/gpt-5.4` - Необов’язковий image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` - Необов’язковий MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Автентифікація: `OPENAI_API_KEY` з shell/profile, а також необов’язково скопійовані +- Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний Codex + harness не міг пройти, тихо переключившись на PI. +- Автентифікація: `OPENAI_API_KEY` із shell/profile, а також необов’язково скопійовані `~/.codex/auth.json` і `~/.codex/config.toml` Локальний рецепт: @@ -420,26 +422,26 @@ OPENCLAW_LIVE_CODEX_HARNESS=1 \ pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts ``` -Docker-рецепт: +Рецепт Docker: ```bash source ~/.profile pnpm test:docker:live-codex-harness ``` -Примітки щодо Docker: +Примітки про Docker: -- Docker-раннер розташований у `scripts/test-live-codex-harness-docker.sh`. -- Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли - автентифікації Codex CLI, якщо вони є, встановлює `@openai/codex` у записуваний змонтований npm- - префікс, готує дерево вихідного коду, а потім запускає лише live-тест Codex-harness. -- Docker за замовчуванням вмикає image та MCP/tool probes. Установіть +- Виконавець Docker розташовано в `scripts/test-live-codex-harness-docker.sh`. +- Він підвантажує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли + автентифікації CLI Codex, якщо вони присутні, установлює `@openai/codex` у записуваний змонтований npm + префікс, підготовлює вихідне дерево, а потім запускає лише live-тест Codex-harness. +- Docker за замовчуванням вмикає image і MCP/tool probe-и. Установіть `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` або - `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, коли вам потрібен вужчий налагоджувальний запуск. + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, коли потрібен вужчий налагоджувальний запуск. ### Рекомендовані live-рецепти -Вузькі, явні allowlist — найшвидші та найменш нестабільні: +Вузькі, явні allowlist-и — найшвидші та найменш нестабільні: - Одна модель, напряму (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` @@ -447,29 +449,29 @@ pnpm test:docker:live-codex-harness - Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Tool calling для кількох провайдерів: +- Виклик інструментів через кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Фокус на Google (API key Gemini + Antigravity): +- Фокус на Google (Gemini API key + Antigravity): - Gemini (API key): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` Примітки: - `google/...` використовує Gemini API (API key). -- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint агента у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості tools). +- `google-antigravity/...` використовує міст Antigravity OAuth (endpoint agent-а в стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості інструментів). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає розміщений Google Gemini API через HTTP (API key / автентифікація профілю); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw виконує локальний binary `gemini`; він має власну автентифікацію й може поводитися інакше (streaming/tool support/version skew). + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (API key / profile auth); саме це більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw виконує локальний binary `gemini`; він має власну автентифікацію й може поводитися інакше (streaming/підтримка інструментів/розбіжності версій). ## Live: матриця моделей (що ми охоплюємо) -Немає фіксованого «списку моделей для CI» (live — це opt-in), але ось **рекомендовані** моделі, які варто регулярно покривати на машині розробника з ключами. +Немає фіксованого «списку моделей CI» (live вмикається за запитом), але це **рекомендовані** моделі для регулярного покриття на dev-машині з ключами. -### Сучасний smoke-набір (tool calling + image) +### Сучасний smoke-набір (виклик інструментів + зображення) -Це запуск «поширених моделей», який ми очікуємо підтримувати робочим: +Це запуск «поширених моделей», який ми очікуємо підтримувати працездатним: - OpenAI (не-Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` @@ -479,12 +481,12 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запуск gateway smoke з tools + image: +Запуск gateway smoke з інструментами + зображенням: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Базовий рівень: tool calling (Read + необов’язковий Exec) +### Базове покриття: виклик інструментів (Read + необов’язковий Exec) -Виберіть щонайменше одну модель на кожне сімейство провайдерів: +Виберіть щонайменше одну модель для кожного сімейства провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -492,16 +494,16 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (було б добре мати): +Необов’язкове додаткове покриття (бажано мати): - xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас ввімкнено) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас увімкнено) - Cerebras: `cerebras/`… (якщо у вас є доступ) -- LM Studio: `lmstudio/`… (локально; tool calling залежить від режиму API) +- LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) -### Vision: надсилання image (вкладення → мультимодальне повідомлення) +### Vision: надсилання зображення (вкладення → мультимодальне повідомлення) -Додайте щонайменше одну модель із підтримкою image до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/варіанти OpenAI з підтримкою vision тощо), щоб перевірити image probe. +Додайте принаймні одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI варіанти з підтримкою vision тощо), щоб перевірити image probe. ### Агрегатори / альтернативні gateway @@ -510,63 +512,63 @@ pnpm test:docker:live-codex-harness - OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tool+image) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Інші провайдери, які можна включити до live-матриці (якщо у вас є облікові дані/config): +Інші провайдери, які можна додати до live-матриці (якщо у вас є облікові дані/конфігурація): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (власні endpoints): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (власні endpoint-и): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко закодувати «всі моделі» в документації. Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс доступні ключі. +Порада: не намагайтеся жорстко закодувати в документації «усі моделі». Авторитетний список — це все, що повертає `discoverModels(...)` на вашій машині, плюс усі доступні ключі. ## Облікові дані (ніколи не комітьте) Live-тести знаходять облікові дані так само, як і CLI. Практичні наслідки: -- Якщо CLI працює, live-тести мають знаходити ті самі ключі. +- Якщо CLI працює, live-тести мають знайти ті самі ключі. - Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі автентифікації для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це мається на увазі під «profile keys» у live-тестах) -- Config: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється до staged live home, якщо присутній, але це не головне сховище profile-key) -- Локальні live-запуски за замовчуванням копіюють активний config, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI до тимчасового test home; staged live homes пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probes не торкалися вашого реального workspace хоста. +- Профілі автентифікації для кожного agent-а: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «profile keys» у live-тестах) +- Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) +- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється в підготовлений live-home, якщо присутній, але це не основне сховище profile keys) +- Локальні live-запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для кожного agent-а, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI у тимчасовий test home; підготовлені live-home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probe-и не працювали у вашому реальному host workspace. -Якщо ви хочете покладатися на env keys (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-раннери нижче (вони можуть монтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте виконавці Docker нижче (вони можуть змонтувати `~/.profile` у контейнер). -## Deepgram live (транскрибування аудіо) +## Live: Deepgram (транскрипція аудіо) - Тест: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## BytePlus coding plan live +## Live: BytePlus coding plan - Тест: `src/agents/byteplus.live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## ComfyUI workflow media live +## Live: медіа workflow ComfyUI - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Обсяг: - - Перевіряє вбудовані шляхи comfy для image, video і `music_generate` + - Перевіряє вбудовані шляхи comfy image, video і `music_generate` - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано - - Корисно після змін у поданні workflow comfy, polling, downloads або реєстрації plugin + - Корисно після змін у надсиланні workflow comfy, polling, завантаженнях або реєстрації plugin-ів -## Image generation live +## Live: генерація зображень - Тест: `src/image-generation/runtime.live.test.ts` - Команда: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Обсяг: - - Перелічує кожен зареєстрований provider plugin для image generation - - Завантажує відсутні env-змінні провайдера з вашого shell входу (`~/.profile`) перед перевіркою - - За замовчуванням віддає перевагу live/env API keys над збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell credentials - - Пропускає провайдери без придатної автентифікації/профілю/моделі - - Запускає стандартні варіанти image generation через спільну runtime capability: + - Перелічує кожен зареєстрований plugin провайдера генерації зображень + - Перед перевіркою підвантажує відсутні env-змінні провайдерів із вашої login shell (`~/.profile`) + - За замовчуванням використовує live/env API-ключі перед збереженими auth-профілями, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Проганяє стандартні варіанти генерації зображень через спільну runtime capability: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні вбудовані провайдери, які охоплено: +- Поточні вбудовані провайдери, що покриваються: - `openai` - `google` - Необов’язкове звуження: @@ -574,198 +576,199 @@ Live-тести знаходять облікові дані так само, я - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів та ігнорувати перевизначення лише з env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через profile store й ігнорувати перевизначення лише через env -## Music generation live +## Live: генерація музики - Тест: `extensions/music-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Обсяг: - - Перевіряє спільний вбудований шлях provider для music generation + - Перевіряє спільний шлях вбудованих провайдерів генерації музики - Наразі охоплює Google і MiniMax - - Завантажує env-змінні провайдера з вашого shell входу (`~/.profile`) перед перевіркою - - За замовчуванням віддає перевагу live/env API keys над збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell credentials - - Пропускає провайдери без придатної автентифікації/профілю/моделі - - Запускає обидва оголошені runtime modes, коли вони доступні: - - `generate` із вводом лише prompt + - Перед перевіркою підвантажує env-змінні провайдерів із вашої login shell (`~/.profile`) + - За замовчуванням використовує live/env API-ключі перед збереженими auth-профілями, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Запускає обидва оголошені runtime-режими, коли вони доступні: + - `generate` з введенням лише prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - - Поточне покриття спільного lane: + - Поточне покриття спільної смуги: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий live-файл Comfy, не цей спільний sweep + - `comfy`: окремий live-файл Comfy, не цей спільний прогін - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів та ігнорувати перевизначення лише з env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через profile store й ігнорувати перевизначення лише через env -## Video generation live +## Live: генерація відео - Тест: `extensions/video-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Обсяг: - - Перевіряє спільний вбудований шлях video-generation provider - - Завантажує env-змінні провайдера з вашого shell входу (`~/.profile`) перед перевіркою - - За замовчуванням віддає перевагу live/env API keys над збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell credentials - - Пропускає провайдери без придатної автентифікації/профілю/моделі - - Запускає обидва оголошені runtime modes, коли вони доступні: - - `generate` із вводом лише prompt - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний image input на основі buffer у спільному sweep - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний video input на основі buffer у спільному sweep - - Поточні провайдери `imageToVideo`, оголошені, але пропущені у спільному sweep: - - `vydra`, оскільки вбудований `veo3` підтримує лише text, а вбудований `kling` вимагає віддалений image URL + - Перевіряє спільний шлях вбудованих провайдерів генерації відео + - Перед перевіркою підвантажує env-змінні провайдерів із вашої login shell (`~/.profile`) + - За замовчуванням використовує live/env API-ключі перед збереженими auth-профілями, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Запускає обидва оголошені runtime-режими, коли вони доступні: + - `generate` з введенням лише prompt + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальне введення зображення на основі buffer у спільному прогоні + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальне введення відео на основі buffer у спільному прогоні + - Поточні провайдери `imageToVideo`, оголошені, але пропущені у спільному прогоні: + - `vydra`, оскільки вбудований `veo3` підтримує лише текст, а вбудований `kling` потребує віддалений URL зображення - Покриття Vydra, специфічне для провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video, а також lane `kling`, який за замовчуванням використовує fixture з віддаленим image URL + - цей файл запускає `veo3` text-to-video, а також смугу `kling`, яка за замовчуванням використовує фікстуру з віддаленим URL зображення - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні провайдери `videoToVideo`, оголошені, але пропущені у спільному sweep: - - `alibaba`, `qwen`, `xai`, оскільки ці шляхи зараз вимагають віддалені reference URL `http(s)` / MP4 - - `google`, оскільки поточний спільний lane Gemini/Veo використовує локальний ввід на основі buffer, і цей шлях не приймається у спільному sweep - - `openai`, оскільки поточний спільний lane не гарантує організаційно-специфічний доступ до video inpaint/remix + - Поточні провайдери `videoToVideo`, оголошені, але пропущені у спільному прогоні: + - `alibaba`, `qwen`, `xai`, оскільки ці шляхи наразі потребують віддалені еталонні URL `http(s)` / MP4 + - `google`, оскільки поточна спільна смуга Gemini/Veo використовує локальне введення на основі buffer, і цей шлях не приймається у спільному прогоні + - `openai`, оскільки поточна спільна смуга не гарантує доступ до video inpaint/remix, специфічний для певної організації - Необов’язкове звуження: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів та ігнорувати перевизначення лише з env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через profile store й ігнорувати перевизначення лише через env ## Media live harness - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори для image, music і video через один вбудований entrypoint репозиторію - - Автоматично завантажує відсутні env-змінні провайдерів із `~/.profile` + - Запускає спільні live-набори для зображень, музики та відео через один вбудований у репозиторій entrypoint + - Автоматично підвантажує відсутні env-змінні провайдерів із `~/.profile` - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатну автентифікацію - - Повторно використовує `scripts/test-live.mjs`, тому heartbeat і тихий режим залишаються узгодженими + - Повторно використовує `scripts/test-live.mjs`, тому поведінка heartbeat і quiet mode залишається узгодженою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Docker-раннери (необов’язкові перевірки «працює в Linux») +## Виконавці Docker (необов’язкові перевірки «працює в Linux») -Ці Docker-раннери поділяються на дві категорії: +Ці виконавці Docker поділяються на дві категорії: -- Раннери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише свій відповідний live-файл profile-key усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтуючи ваш локальний каталог config і workspace (а також використовуючи `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoints — `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live-раннери за замовчуванням використовують менше smoke-обмеження, щоб повний Docker sweep залишався практичним: +- Виконавці live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише свій відповідний profile-key live-файл усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог config і workspace (а також підвантажують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint-и: `test:live:models-profiles` і `test:live:gateway-profiles`. +- Live-виконавці Docker за замовчуванням використовують меншу межу smoke, щоб повний прогін Docker залишався практичним: `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а `test:docker:live-gateway` — `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли - вам явно потрібне більше вичерпне сканування. -- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker-lane live-тестів. -- Контейнерні smoke-раннери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + вам свідомо потрібен більший вичерпний прогін. +- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, а потім повторно використовує його для двох live Docker-смуг. +- Контейнерні smoke-виконавці: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` підіймають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker-раннери live-моделей також bind-mount лише потрібні CLI auth homes (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб зовнішній CLI OAuth міг оновлювати токени, не змінюючи auth store хоста: +Виконавці Docker для live-моделей також bind-mount-ять лише потрібні домашні каталоги автентифікації CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени, не змінюючи host auth store: - Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) -- CLI backend smoke: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- Smoke ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) +- Smoke backend-а CLI: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Smoke harness app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) - Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) - Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Мережа gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Міст MCP channel (seeded Gateway + stdio bridge + smoke сирого notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (install smoke + псевдонім `/plugin` + семантика restart Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Мережева взаємодія gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Міст каналів MCP (seeded Gateway + stdio bridge + raw smoke notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (smoke встановлення + псевдонім `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -Docker-раннери live-моделей також монтують поточний checkout лише для читання і -підготовлюють його у тимчасовому workdir усередині контейнера. Це зберігає runtime- -образ компактним, але все одно запускає Vitest точно на вашому локальному source/config. -На етапі підготовки пропускаються великі локальні кеші та результати збірки застосунків, такі як -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги `.build` або -виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання -машинно-специфічних артефактів. -Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probes gateway не запускали -реальні workers каналів Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте +Виконавці Docker для live-моделей також bind-mount-ять поточний checkout у режимі лише читання і +підготовлюють його в тимчасовий workdir усередині контейнера. Це зберігає runtime +image компактним, водночас дозволяючи запускати Vitest точно проти вашого локального source/config. +Крок підготовки пропускає великі локальні кеші та результати збірки застосунків, як-от +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні каталоги `.build` або +виводу Gradle, щоб live-запуски Docker не витрачали хвилини на копіювання +машинозалежних артефактів. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe-и gateway не запускали +реальні працівники каналів Telegram/Discord тощо всередині контейнера. +`test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте `OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway -live-покриття з цього Docker-lane. -`test:docker:openwebui` — це smoke-перевірка сумісності вищого рівня: вона запускає -контейнер OpenClaw gateway з увімкненими HTTP endpoints, сумісними з OpenAI, -запускає закріплений контейнер Open WebUI проти цього gateway, входить через +live-покриття з цієї Docker-смуги. +`test:docker:openwebui` — це smoke сумісності вищого рівня: він запускає +контейнер gateway OpenClaw з увімкненими OpenAI-сумісними HTTP endpoint-ами, +запускає прикріплений контейнер Open WebUI проти цього gateway, виконує вхід через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний chat-запит через proxy `/api/chat/completions` Open WebUI. -Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися витягнути -образ Open WebUI, а самому Open WebUI — завершити власне холодне початкове налаштування. -Цей lane очікує наявний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` +реальний chat-запит через проксі Open WebUI `/api/chat/completions`. +Перший запуск може бути помітно повільнішим, оскільки Docker може потребувати завантажити +image Open WebUI, а сам Open WebUI може завершувати власне налаштування холодного старту. +Ця смуга очікує придатний live-ключ моделі, а `OPENCLAW_PROFILE_FILE` (`~/.profile` за замовчуванням) є основним способом надати його в Dockerized-запусках. Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він запускає seeded Gateway -контейнер, запускає другий контейнер, який піднімає `openclaw mcp serve`, а потім -перевіряє routed conversation discovery, читання transcript, метадані вкладень, -поведінку черги live events, маршрутизацію outbound send і channel + сповіщення -про дозволи у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень -безпосередньо аналізує сирі stdio MCP frames, тож smoke перевіряє те, що міст -справді випромінює, а не лише те, що випадково показує конкретний client SDK. +реального облікового запису Telegram, Discord або iMessage. Він підіймає seeded Gateway +контейнер, запускає другий контейнер, який стартує `openclaw mcp serve`, а потім +перевіряє виявлення маршрутизованих розмов, читання transcript, метадані вкладень, +поведінку черги live-подій, маршрутизацію вихідного надсилання та сповіщення у стилі Claude про канали + +дозволи через реальний міст stdio MCP. Перевірка сповіщень +безпосередньо аналізує сирі stdio MCP-кадри, тож smoke перевіряє те, що міст +справді випромінює, а не лише те, що певний клієнтський SDK випадково показує. -Ручний smoke plain-language thread для ACP (не CI): +Ручний ACP smoke для plain-language threads (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для регресійних сценаріїв і налагодження. Він може знову знадобитися для перевірки ACP thread routing, тож не видаляйте його. +- Зберігайте цей скрипт для робочих сценаріїв регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP threads, тому не видаляйте його. Корисні env-змінні: -- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`), монтується в `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`), монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`), монтується в `/home/node/.profile` і використовується перед запуском тестів -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`), монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker -- Зовнішні каталоги/файли CLI auth у `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед запуском тестів +- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`), змонтовано в `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`), змонтовано в `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`), змонтовано в `/home/node/.profile` і підвантажується перед запуском тестів +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`), змонтовано в `/home/node/.npm-global` для кешованих установок CLI усередині Docker +- Зовнішні каталоги/файли автентифікації CLI під `$HOME` монтуються лише для читання в `/host-auth...`, а потім копіюються в `/home/node/...` перед запуском тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Для звужених запусків провайдерів монтуються лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Ручне перевизначення: `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` для звуження запуску -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` для фільтрації провайдерів у контейнері -- `OPENCLAW_SKIP_DOCKER_BUILD=1` для повторного використання наявного образу `openclaw:local-live` для повторних запусків, які не потребують перебудови -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані беруться зі сховища профілів (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...` для вибору моделі, яку gateway показує для smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` для перевизначення prompt перевірки nonce, що використовується smoke Open WebUI -- `OPENWEBUI_IMAGE=...` для перевизначення закріпленого тега образу Open WebUI + - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Можна перевизначити вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів усередині контейнера +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний image `openclaw:local-live` для повторних запусків, які не потребують перебудови +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані надходять із profile store, а не з env +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити nonce-check prompt, який використовує smoke Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити прикріплений tag image Open WebUI ## Перевірка документації -Після змін у документації запускайте перевірки docs: `pnpm check:docs`. -Запускайте повну перевірку якорів Mintlify, якщо вам також потрібна перевірка заголовків у межах сторінки: `pnpm docs:check-links:anchors`. +Після редагування документації запускайте перевірки docs: `pnpm check:docs`. +Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. ## Офлайн-регресія (безпечна для CI) Це регресії «реального конвеєра» без реальних провайдерів: -- Tool calling gateway (імітація OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Виклик інструментів gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") - Майстер gateway (WS `wizard.start`/`wizard.next`, запис config + примусова auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") -## Оцінювання надійності агента (Skills) +## Оцінювання надійності agent-а (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності agent-а»: -- Імітація tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- End-to-end потоки майстра, які перевіряють прив’язку сесії та ефекти config (`src/gateway/gateway.test.ts`). +- Mock tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). +- Наскрізні потоки майстра, які перевіряють wiring сесій та ефекти конфігурації (`src/gateway/gateway.test.ts`). Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Прийняття рішень:** коли Skills перелічені в prompt, чи вибирає агент правильний Skills (або уникає нерелевантних)? -- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/args? -- **Контракти робочих процесів:** багатокрокові сценарії, які перевіряють порядок tools, перенесення історії сесії та межі sandbox. +- **Прийняття рішень:** коли Skills перелічено в prompt, чи вибирає agent правильний skill (або уникає нерелевантних)? +- **Дотримання вимог:** чи читає agent `SKILL.md` перед використанням і чи виконує потрібні кроки/аргументи? +- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні evals мають передусім залишатися детермінованими: +Майбутні eval-и мають спочатку залишатися детермінованими: -- Запускач сценаріїв із mock-провайдерами для перевірки викликів tools + порядку, читання skill-файлів і прив’язки сесії. -- Невеликий набір сценаріїв, орієнтованих на skills (використати чи уникнути, gating, prompt injection). -- Необов’язкові live evals (opt-in, із контролем через env) лише після того, як буде готовий безпечний для CI набір. +- Виконавець сценаріїв із mock-провайдерами для перевірки викликів інструментів + їхнього порядку, читання skill-файлів і wiring сесій. +- Невеликий набір skill-орієнтованих сценаріїв (використовувати чи уникати, gating, prompt injection). +- Необов’язкові live eval-и (за запитом, із керуванням через env) лише після того, як буде готовий безпечний для CI набір. ## Контрактні тести (форма plugin і channel) Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму -контракту інтерфейсу. Вони перебирають усі виявлені plugins і запускають набір перевірок -форми та поведінки. Типовий unit-lane `pnpm test` навмисно пропускає ці спільні файли -seam і smoke; запускайте контрактні команди явно, коли змінюєте спільні поверхні channel або provider. +контракту інтерфейсу. Вони ітеруються по всіх виявлених plugin-ах і запускають набір +перевірок форми та поведінки. Типова unit-смуга `pnpm test` навмисно +пропускає ці спільні seam- і smoke-файли; запускайте команди контрактів явно, +коли торкаєтеся спільних поверхонь channel або provider. ### Команди @@ -777,53 +780,53 @@ seam і smoke; запускайте контрактні команди явно Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма plugin (id, name, capabilities) +- **plugin** - Базова форма plugin-а (id, name, capabilities) - **setup** - Контракт майстра налаштування - **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій channel - **threading** - Обробка ID thread -- **directory** - API каталогу/списку учасників +- **directory** - API каталогу/реєстру - **group-policy** - Застосування групової політики ### Контракти статусу provider Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Перевірки status channel -- **registry** - Форма registry plugin +- **status** - Probe-и статусу channel +- **registry** - Форма реєстру plugin-ів ### Контракти provider Розташовані в `src/plugins/contracts/*.contract.test.ts`: - **auth** - Контракт потоку автентифікації -- **auth-choice** - Вибір/добір автентифікації +- **auth-choice** - Вибір/селекція автентифікації - **catalog** - API каталогу моделей -- **discovery** - Виявлення plugin -- **loader** - Завантаження plugin +- **discovery** - Виявлення plugin-ів +- **loader** - Завантаження plugin-ів - **runtime** - Runtime provider -- **shape** - Форма/інтерфейс plugin +- **shape** - Форма/інтерфейс plugin-а - **wizard** - Майстер налаштування ### Коли запускати -- Після зміни export або subpath у plugin-sdk -- Після додавання або змінення channel чи provider plugin -- Після рефакторингу реєстрації або виявлення plugin +- Після змін експортів або subpath-ів plugin-sdk +- Після додавання чи зміни plugin-а channel або provider +- Після рефакторингу реєстрації чи виявлення plugin-ів -Контрактні тести запускаються в CI і не потребують реальних API keys. +Контрактні тести запускаються в CI і не потребують реальних API-ключів. ## Додавання регресій (рекомендації) Коли ви виправляєте проблему provider/model, виявлену в live: -- Якщо можливо, додайте безпечну для CI регресію (імітація/stub provider або фіксація точної трансформації форми запиту) -- Якщо проблема за своєю природою лише live-типу (rate limits, політики автентифікації), залишайте live-тест вузьким і opt-in через env-змінні -- Віддавайте перевагу найменшому рівню, який ловить баг: - - баг конвертації/повторення запиту provider → тест direct models - - баг конвеєра gateway session/history/tool → gateway live smoke або безпечний для CI mock-тест gateway -- Захисне правило обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить один вибраний target на кожен клас SecretRef із метаданих registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec id відхиляються. - - Якщо ви додаєте нове сімейство target SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити. +- Якщо можливо, додайте безпечну для CI регресію (mock/stub provider або зафіксуйте точне перетворення форми запиту) +- Якщо проблема за своєю природою лише live (rate limits, політики автентифікації), робіть live-тест вузьким і таким, що вмикається через env vars +- Віддавайте перевагу найменшому шару, який виявляє помилку: + - помилка перетворення/повторного відтворення запиту provider → прямий тест моделей + - помилка конвеєра gateway session/history/tool → gateway live smoke або безпечний для CI mock-тест gateway +- Guardrail для обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль для кожного класу SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. + - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити. diff --git a/docs/uk/plugins/sdk-agent-harness.md b/docs/uk/plugins/sdk-agent-harness.md index 1ae8f2eb9..81b445d97 100644 --- a/docs/uk/plugins/sdk-agent-harness.md +++ b/docs/uk/plugins/sdk-agent-harness.md @@ -1,53 +1,53 @@ --- read_when: - - Ви змінюєте вбудоване середовище виконання агента або реєстр каркаса - - Ви реєструєте каркас агента з вбудованого або довіреного плагіна + - Ви змінюєте вбудований рантайм агента або реєстр harnessів + - Ви реєструєте harness агента з вбудованого або довіреного плагіна - Вам потрібно зрозуміти, як плагін Codex пов’язаний із постачальниками моделей sidebarTitle: Agent Harness summary: Експериментальна поверхня SDK для плагінів, які замінюють низькорівневий вбудований виконавець агента -title: Плагіни каркаса агента +title: Плагіни Agent Harness x-i18n: - generated_at: "2026-04-10T20:23:46Z" + generated_at: "2026-04-10T20:29:00Z" model: gpt-5.4 provider: openai - source_hash: ba482dd6a2e4730c2d623b4739e2e6037cec8bb71bf7164b4e9d7ea8e43056d8 + source_hash: 3afa7d81ca5a34f40da63e01bb9b42aa10ff8d6f92c2f78bf2588f1a71b5bc0e source_path: plugins/sdk-agent-harness.md workflow: 15 --- -# Плагіни каркаса агента +# Плагіни Agent Harness -**Каркас агента** — це низькорівневий виконавець одного підготовленого ходу агента OpenClaw. Це не постачальник моделей, не канал і не реєстр інструментів. +**Agent harness** — це низькорівневий виконавець для одного підготовленого ходу агента OpenClaw. Це не постачальник моделей, не канал і не реєстр інструментів. Використовуйте цю поверхню лише для вбудованих або довірених нативних плагінів. Контракт усе ще є експериментальним, оскільки типи параметрів навмисно віддзеркалюють поточний вбудований раннер. -## Коли використовувати каркас +## Коли використовувати harness -Реєструйте каркас агента, коли сімейство моделей має власне нативне середовище виконання сесій і звичайний транспорт постачальника OpenClaw є неправильною абстракцією. +Реєструйте agent harness, коли сімейство моделей має власний нативний рантайм сесії, а звичайний транспорт постачальника OpenClaw є неправильною абстракцією. Приклади: -- нативний сервер агента для кодування, який керує потоками та компакцією -- локальний CLI або демон, який має потоково передавати нативні події плану, міркувань і інструментів -- середовище виконання моделі, якому потрібен власний resume id на додачу до транскрипту сесії OpenClaw +- нативний сервер coding-agent, який керує потоками та компакцією +- локальний CLI або демон, який має потоково передавати нативні події плану/міркування/інструментів +- рантайм моделі, якому потрібен власний resume id на додачу до стенограми сесії OpenClaw -**Не** реєструйте каркас лише для того, щоб додати новий LLM API. Для звичайних HTTP або WebSocket API моделей створіть [плагін постачальника](/uk/plugins/sdk-provider-plugins). +**Не** реєструйте harness лише для того, щоб додати новий API LLM. Для звичайних HTTP або WebSocket API моделей створіть [плагін постачальника](/uk/plugins/sdk-provider-plugins). ## Чим усе ще керує ядро -До того, як буде вибрано каркас, OpenClaw уже визначив: +Перш ніж буде вибрано harness, OpenClaw уже визначив: - постачальника й модель -- стан автентифікації середовища виконання -- рівень міркувань і бюджет контексту -- файл транскрипту/сесії OpenClaw -- робочий простір, пісочницю та політику інструментів -- колбеки відповіді каналу та колбеки потокової передачі -- політику резервного перемикання моделей і перемикання живої моделі +- стан автентифікації рантайму +- рівень міркування та бюджет контексту +- файл стенограми/сесії OpenClaw +- workspace, sandbox і політику інструментів +- зворотні виклики відповіді каналу та потокові зворотні виклики +- політику резервного переходу між моделями та перемикання live-моделей -Цей поділ є навмисним. Каркас виконує підготовлену спробу; він не вибирає постачальників, не замінює доставлення каналу й не перемикає моделі непомітно. +Такий поділ є навмисним. Harness виконує підготовлену спробу; він не вибирає постачальників, не замінює доставку каналом і не перемикає моделі непомітно. -## Зареєструвати каркас +## Реєстрація harness **Імпорт:** `openclaw/plugin-sdk/agent-harness` @@ -85,38 +85,40 @@ export default definePluginEntry({ ## Політика вибору -OpenClaw вибирає каркас після визначення постачальника/моделі: +OpenClaw вибирає harness після визначення постачальника/моделі: -1. `OPENCLAW_AGENT_RUNTIME=` примусово вибирає зареєстрований каркас із цим id. -2. `OPENCLAW_AGENT_RUNTIME=pi` примусово вибирає вбудований каркас PI. -3. `OPENCLAW_AGENT_RUNTIME=auto` запитує зареєстровані каркаси, чи підтримують вони визначеного постачальника/модель. -4. Якщо жоден зареєстрований каркас не підходить, OpenClaw використовує PI. +1. `OPENCLAW_AGENT_RUNTIME=` примусово вибирає зареєстрований harness із цим id. +2. `OPENCLAW_AGENT_RUNTIME=pi` примусово вибирає вбудований harness PI. +3. `OPENCLAW_AGENT_RUNTIME=auto` запитує зареєстровані harness-и, чи підтримують вони визначеного постачальника/модель. +4. Якщо жоден зареєстрований harness не підходить, OpenClaw використовує PI, якщо резервний перехід на PI не вимкнено. -Помилки примусово вибраного каркаса плагіна відображаються як помилки виконання. У режимі `auto` OpenClaw може повернутися до PI, якщо вибраний каркас плагіна зазнає збою до того, як хід спричинить побічні ефекти. +Збої примусово вибраного harness плагіна відображаються як збої запуску. У режимі `auto` OpenClaw може перейти на PI, якщо вибраний harness плагіна зазнає збою до того, як хід створить побічні ефекти. Установіть `OPENCLAW_AGENT_HARNESS_FALLBACK=none` або `embeddedHarness.fallback: "none"`, щоб зробити такий резервний перехід жорсткою помилкою. -Вбудований плагін Codex реєструє `codex` як id свого каркаса. Для сумісності `codex-app-server` і `app-server` також вказують на цей самий каркас, коли ви вручну задаєте `OPENCLAW_AGENT_RUNTIME`. +Вбудований плагін Codex реєструє `codex` як свій id harness. Для сумісності `codex-app-server` і `app-server` також зіставляються з цим самим harness, коли ви вручну задаєте `OPENCLAW_AGENT_RUNTIME`. -## Поєднання постачальника та каркаса +## Парування постачальника та harness -Більшість каркасів також мають реєструвати постачальника. Постачальник робить посилання на моделі, стан автентифікації, метадані моделі та вибір `/model` видимими для решти OpenClaw. Потім каркас заявляє про цей постачальник у `supports(...)`. +Більшість harness-ів також мають реєструвати постачальника. Постачальник робить refs моделей, статус автентифікації, метадані моделей і вибір `/model` видимими для решти OpenClaw. Потім harness заявляє про цей постачальник у `supports(...)`. Вбудований плагін Codex дотримується цього шаблону: - id постачальника: `codex` -- посилання на моделі для користувача: `codex/gpt-5.4`, `codex/gpt-5.2` або інша модель, повернена сервером застосунку Codex -- id каркаса: `codex` -- автентифікація: синтетична доступність постачальника, оскільки каркас Codex керує нативним входом/сесією Codex -- запит до app-server: OpenClaw надсилає до Codex голий id моделі й дозволяє каркасу працювати з нативним протоколом app-server +- refs моделей для користувача: `codex/gpt-5.4`, `codex/gpt-5.2` або інша модель, повернена сервером додатка Codex +- id harness: `codex` +- автентифікація: синтетична доступність постачальника, оскільки harness Codex керує нативним входом/сесією Codex +- запит app-server: OpenClaw надсилає до Codex базовий id моделі й дозволяє harness взаємодіяти з нативним протоколом app-server -Плагін Codex є додатковим. Звичайні посилання `openai/gpt-*` залишаються посиланнями постачальника OpenAI і продовжують використовувати звичайний шлях постачальника OpenClaw. Вибирайте `codex/gpt-*`, коли вам потрібні автентифікація під керуванням Codex, виявлення моделей Codex, нативні потоки та виконання через Codex app-server. `/model` може перемикатися між моделями Codex, які повертає Codex app-server, без потреби в облікових даних постачальника OpenAI. +Плагін Codex є адитивним. Звичайні refs `openai/gpt-*` залишаються refs постачальника OpenAI і продовжують використовувати звичайний шлях постачальника OpenClaw. Вибирайте `codex/gpt-*`, коли вам потрібні автентифікація під керуванням Codex, виявлення моделей Codex, нативні потоки та виконання через app-server Codex. `/model` може перемикатися між моделями Codex, які повертає app-server Codex, без потреби в облікових даних постачальника OpenAI. -OpenClaw вимагає Codex app-server версії `0.118.0` або новішої. Плагін Codex перевіряє initialize handshake app-server і блокує старі або неверсіоновані сервери, щоб OpenClaw працював лише з тією поверхнею протоколу, з якою його було протестовано. +OpenClaw вимагає Codex app-server версії `0.118.0` або новішої. Плагін Codex перевіряє initialize handshake app-server і блокує старі або неверсіоновані сервери, щоб OpenClaw працював лише з поверхнею протоколу, з якою його було протестовано. -## Політика вибору каркаса +## Вимкнення резервного переходу на PI -За замовчуванням OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, установленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані каркаси плагінів можуть претендувати на пару постачальник/модель. Якщо не підходить жоден або якщо автоматично вибраний каркас плагіна зазнає збою до створення виводу, OpenClaw повертається до PI. +За замовчуванням OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, установленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані harness-и плагінів можуть заявити про пару постачальник/модель. Якщо жоден не підходить або якщо автоматично вибраний harness плагіна зазнає збою до створення виводу, OpenClaw переходить на PI. -Установіть `fallback: "none"`, коли вам потрібно довести, що виконується лише каркас плагіна: +Установіть `fallback: "none"`, коли вам потрібно довести, що єдиним задіяним рантаймом є harness плагіна. Це вимикає автоматичний резервний перехід на PI; це не блокує явний `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`. + +Для вбудованих запусків лише з Codex: ```json { @@ -132,6 +134,21 @@ OpenClaw вимагає Codex app-server версії `0.118.0` або нові } ``` +Якщо ви хочете, щоб будь-який зареєстрований harness плагіна міг заявити про відповідні моделі, але ніколи не хочете, щоб OpenClaw непомітно переходив на PI, залиште `runtime: "auto"` і вимкніть резервний перехід: + +```json +{ + "agents": { + "defaults": { + "embeddedHarness": { + "runtime": "auto", + "fallback": "none" + } + } + } +} +``` + Перевизначення для окремого агента використовують ту саму форму: ```json @@ -157,36 +174,46 @@ OpenClaw вимагає Codex app-server версії `0.118.0` або нові } ``` -`OPENCLAW_AGENT_RUNTIME` усе ще перевизначає налаштоване середовище виконання. Використовуйте `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути резервний перехід до PI через змінну середовища. +`OPENCLAW_AGENT_RUNTIME` усе ще перевизначає налаштований рантайм. Використовуйте `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути резервний перехід на PI через середовище. -## Нативні сесії та дзеркало транскрипту +```bash +OPENCLAW_AGENT_RUNTIME=codex \ +OPENCLAW_AGENT_HARNESS_FALLBACK=none \ +openclaw gateway run +``` -Каркас може зберігати нативний id сесії, id потоку або токен відновлення на боці демона. Явно пов’язуйте цю прив’язку із сесією OpenClaw і продовжуйте віддзеркалювати видимий для користувача вивід асистента/інструментів у транскрипт OpenClaw. +Коли резервний перехід вимкнено, сесія завершується помилкою на ранньому етапі, якщо запитаний harness не зареєстровано, не підтримує визначеного постачальника/модель або зазнає збою до створення побічних ефектів ходу. Це зроблено навмисно для розгортань лише з Codex і для live-тестів, які мають довести, що фактично використовується шлях Codex app-server. -Транскрипт OpenClaw залишається шаром сумісності для: +Цей параметр керує лише harness-ом вбудованого агента. Він не вимикає маршрутизацію моделей для зображень, відео, музики, TTS, PDF або інших моделей, специфічних для постачальника. -- видимої в каналі історії сесії -- пошуку та індексації транскрипту -- перемикання назад на вбудований каркас PI у наступному ході +## Нативні сесії та дзеркалювання стенограми + +Harness може зберігати нативний id сесії, id потоку або токен відновлення на боці демона. Явно пов’язуйте цю прив’язку із сесією OpenClaw і продовжуйте дзеркалити видимий користувачеві вивід помічника/інструментів у стенограму OpenClaw. + +Стенограма OpenClaw залишається шаром сумісності для: + +- історії сесії, видимої в каналі +- пошуку та індексації стенограми +- повернення до вбудованого harness PI на пізнішому ході - загальної поведінки `/new`, `/reset` і видалення сесії -Якщо ваш каркас зберігає побічну прив’язку, реалізуйте `reset(...)`, щоб OpenClaw міг очистити її, коли пов’язану сесію OpenClaw скинуто. +Якщо ваш harness зберігає прив’язку sidecar, реалізуйте `reset(...)`, щоб OpenClaw міг очистити її, коли пов’язану сесію OpenClaw буде скинуто. ## Результати інструментів і медіа -Ядро формує список інструментів OpenClaw і передає його в підготовлену спробу. Коли каркас виконує динамічний виклик інструмента, повертайте результат інструмента назад через форму результату каркаса, а не надсилайте медіа каналу самостійно. +Ядро формує список інструментів OpenClaw і передає його в підготовлену спробу. Коли harness виконує динамічний виклик інструмента, повертайте результат інструмента через форму результату harness замість того, щоб самостійно надсилати медіа в канал. -Це зберігає текст, зображення, відео, музику, TTS, затвердження та вивід інструментів обміну повідомленнями на тому самому шляху доставлення, що й у виконаннях на базі PI. +Це зберігає текст, зображення, відео, музику, TTS, погодження та виводи інструментів обміну повідомленнями на тому самому шляху доставки, що й у запусках на основі PI. ## Поточні обмеження - Публічний шлях імпорту є загальним, але деякі псевдоніми типів спроб/результатів усе ще містять назви `Pi` для сумісності. -- Установлення сторонніх каркасів є експериментальним. Надавайте перевагу плагінам постачальників, доки вам не знадобиться нативне середовище виконання сесій. -- Перемикання каркасів між ходами підтримується. Не перемикайте каркаси посеред ходу після того, як уже почалися нативні інструменти, затвердження, текст асистента або надсилання повідомлень. +- Встановлення сторонніх harness-ів є експериментальним. Віддавайте перевагу плагінам постачальників, доки вам не знадобиться нативний рантайм сесії. +- Перемикання harness-ів між ходами підтримується. Не перемикайте harness посеред ходу після того, як уже почалися нативні інструменти, погодження, текст помічника або надсилання повідомлень. ## Пов’язане - [Огляд SDK](/uk/plugins/sdk-overview) -- [Допоміжні засоби середовища виконання](/uk/plugins/sdk-runtime) +- [Допоміжні засоби рантайму](/uk/plugins/sdk-runtime) - [Плагіни постачальників](/uk/plugins/sdk-provider-plugins) - [Постачальники моделей](/uk/concepts/model-providers)