From 8f8d9aad4b256ea7e4abae5a415634938299514e Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 22 Apr 2026 08:16:54 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/gateway/cli-backends.md | 217 ++++++++++++++++---------------- 1 file changed, 112 insertions(+), 105 deletions(-) diff --git a/docs/uk/gateway/cli-backends.md b/docs/uk/gateway/cli-backends.md index dcef419eb..8b998127a 100644 --- a/docs/uk/gateway/cli-backends.md +++ b/docs/uk/gateway/cli-backends.md @@ -1,47 +1,47 @@ --- read_when: - - Вам потрібен надійний резервний варіант, коли API-провайдери не працюють. - - Ви використовуєте Codex CLI або інші локальні AI CLI і хочете використовувати їх повторно. - - Ви хочете зрозуміти міст MCP local loopback для доступу інструментів до бекенду CLI. -summary: 'Бекенди CLI: локальний резервний CLI для AI з необов’язковим мостом інструментів MCP' + - Вам потрібен надійний резервний варіант, коли API-провайдери зазнають збоїв + - Ви запускаєте Codex CLI або інші локальні AI CLI і хочете використовувати їх повторно + - Ви хочете зрозуміти міст local loopback MCP для доступу CLI-бекенду до інструментів +summary: 'Бекенди CLI: локальний резервний AI CLI з необов’язковим мостом інструментів MCP' title: Бекенди CLI x-i18n: - generated_at: "2026-04-16T16:34:17Z" + generated_at: "2026-04-22T08:16:00Z" model: gpt-5.4 provider: openai - source_hash: 381273532a8622bc4628000a6fb999712b12af08faade2b5f2b7ac4cc7d23efe + source_hash: 3566d4f2b7a841473a4ed6379c1abd8dbd06c392dbff15ca37c4f8ea1e1ead51 source_path: gateway/cli-backends.md workflow: 15 --- # Бекенди CLI (резервне середовище виконання) -OpenClaw може запускати **локальні AI CLI** як **резервний варіант лише для тексту**, коли API-провайдери недоступні, -обмежені за частотою запитів або тимчасово працюють некоректно. Це навмисно консервативний режим: +OpenClaw може запускати **локальні AI CLI** як **лише текстовий резервний варіант**, коли API-провайдери недоступні, +обмежені за частотою запитів або тимчасово працюють некоректно. Це навмисно консервативний підхід: -- **Інструменти OpenClaw не інжектуються напряму**, але бекенди з `bundleMcp: true` - можуть отримувати інструменти gateway через міст MCP local loopback. -- **Потокова передача JSONL** для CLI, які її підтримують. -- **Сесії підтримуються** (тож наступні ходи залишаються узгодженими). -- **Зображення можна передавати далі**, якщо CLI приймає шляхи до зображень. +- **Інструменти OpenClaw не впроваджуються напряму**, але бекенди з `bundleMcp: true` + можуть отримувати інструменти gateway через loopback-міст MCP. +- **JSONL-стримінг** для CLI, які його підтримують. +- **Сеанси підтримуються** (тому наступні ходи залишаються узгодженими). +- **Зображення можна передавати наскрізь**, якщо CLI приймає шляхи до зображень. -Це задумано як **страхувальний механізм**, а не як основний шлях. Використовуйте це, коли вам -потрібні текстові відповіді у стилі «завжди працює» без залежності від зовнішніх API. +Це створено як **страхувальну сітку**, а не як основний шлях. Використовуйте це, коли +вам потрібні текстові відповіді у стилі «завжди працює» без залежності від зовнішніх API. -Якщо вам потрібне повноцінне середовище виконання harness із керуванням сесіями ACP, фоновими завданнями, -прив’язкою до потоку/розмови та постійними зовнішніми coding sessions, використовуйте -[ACP Agents](/uk/tools/acp-agents). Бекенди CLI — це не ACP. +Якщо вам потрібне повноцінне середовище з керуванням сеансами ACP, фоновими завданнями, +прив’язкою до потоку/розмови та постійними зовнішніми сеансами кодування, використовуйте +[Агенти ACP](/uk/tools/acp-agents). Бекенди CLI — це не ACP. ## Швидкий старт для початківців -Ви можете використовувати Codex CLI **без жодної конфігурації** (вбудований плагін OpenAI -реєструє стандартний бекенд): +Ви можете використовувати Codex CLI **без жодної конфігурації** (вбудований plugin OpenAI +реєструє бекенд за замовчуванням): ```bash openclaw agent --message "hi" --model codex-cli/gpt-5.4 ``` -Якщо ваш gateway працює під launchd/systemd і `PATH` мінімальний, додайте лише +Якщо ваш gateway працює під launchd/systemd і PATH мінімальний, додайте лише шлях до команди: ```json5 @@ -58,16 +58,16 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 } ``` -І все. Жодних ключів, жодної додаткової конфігурації автентифікації, окрім самої CLI. +Ось і все. Жодних ключів, жодної додаткової конфігурації автентифікації, окрім самої CLI. Якщо ви використовуєте вбудований бекенд CLI як **основного провайдера повідомлень** на -хості gateway, OpenClaw тепер автоматично завантажує відповідний вбудований Plugin, коли ваша конфігурація +хості gateway, OpenClaw тепер автоматично завантажує вбудований plugin-власник, коли ваша конфігурація явно посилається на цей бекенд у посиланні на модель або в `agents.defaults.cliBackends`. ## Використання як резервного варіанту -Додайте бекенд CLI до списку резервних, щоб він запускався лише тоді, коли основні моделі не працюють: +Додайте бекенд CLI до списку резервних варіантів, щоб він запускався лише тоді, коли основні моделі не працюють: ```json5 { @@ -88,13 +88,13 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 Примітки: -- Якщо ви використовуєте `agents.defaults.models` (allowlist), ви також маєте включити туди моделі вашого бекенду CLI. -- Якщо основний провайдер не працює (автентифікація, обмеження частоти запитів, тайм-аути), OpenClaw - спробує використати бекенд CLI далі. +- Якщо ви використовуєте `agents.defaults.models` (список дозволених моделей), ви також маєте включити туди моделі вашого бекенду CLI. +- Якщо основний провайдер зазнає збою (автентифікація, ліміти частоти, тайм-аути), OpenClaw + спробує далі бекенд CLI. ## Огляд конфігурації -Усі бекенди CLI знаходяться в: +Усі бекенди CLI розміщуються в: ``` agents.defaults.cliBackends @@ -131,7 +131,7 @@ agents.defaults.cliBackends sessionMode: "existing", sessionIdFields: ["session_id", "conversation_id"], systemPromptArg: "--system", - // CLI у стилі Codex можуть натомість вказувати на файл prompt: + // Натомість CLI у стилі Codex можуть вказувати на файл промпту: // systemPromptFileConfigArg: "-c", // systemPromptFileConfigKey: "model_instructions_file", systemPromptWhen: "first", @@ -148,51 +148,58 @@ agents.defaults.cliBackends ## Як це працює 1. **Вибирає бекенд** на основі префікса провайдера (`codex-cli/...`). -2. **Формує system prompt** з використанням того самого prompt OpenClaw і контексту workspace. -3. **Виконує CLI** з ідентифікатором сесії (якщо підтримується), щоб історія залишалася узгодженою. +2. **Будує системний промпт** з використанням того самого промпту OpenClaw і контексту робочого простору. +3. **Виконує CLI** з ідентифікатором сеансу (якщо підтримується), щоб історія залишалася узгодженою. + Вбудований бекенд `claude-cli` підтримує активний stdio-процес Claude для кожного + сеансу OpenClaw і надсилає наступні ходи через stdin stream-json. 4. **Розбирає вивід** (JSON або звичайний текст) і повертає фінальний текст. -5. **Зберігає ідентифікатори сесій** для кожного бекенду, щоб наступні запити повторно використовували ту саму CLI-сесію. +5. **Зберігає ідентифікатори сеансів** для кожного бекенду, щоб наступні ходи повторно використовували той самий сеанс CLI. Вбудований бекенд Anthropic `claude-cli` знову підтримується. Співробітники Anthropic -повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw розглядає -використання `claude -p` як санкціоноване для цієї інтеграції, якщо Anthropic не опублікує +повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає +використання `claude -p` санкціонованим для цієї інтеграції, якщо Anthropic не опублікує нову політику. -Вбудований бекенд OpenAI `codex-cli` передає system prompt OpenClaw через -перевизначення конфігурації `model_instructions_file` у Codex (`-c -model_instructions_file="..."`). Codex не надає прапора у стилі Claude -`--append-system-prompt`, тому OpenClaw записує зібраний prompt у -тимчасовий файл для кожної нової сесії Codex CLI. +Вбудований бекенд OpenAI `codex-cli` передає системний промпт OpenClaw через +перевизначення конфігурації Codex `model_instructions_file` (`-c +model_instructions_file="..."`). Codex не надає прапорця у стилі Claude +`--append-system-prompt`, тому OpenClaw записує зібраний промпт у +тимчасовий файл для кожного нового сеансу Codex CLI. Вбудований бекенд Anthropic `claude-cli` отримує знімок Skills OpenClaw -двома способами: компактний каталог Skills OpenClaw у доданому system prompt і -тимчасовий плагін Claude Code, переданий через `--plugin-dir`. Плагін містить -лише ті Skills, які дозволені для цього агента/сесії, тому вбудований -механізм визначення skill у Claude Code бачить той самий відфільтрований набір, який OpenClaw інакше рекламував би в prompt. -Перевизначення skill env/API key, як і раніше, застосовуються OpenClaw до середовища дочірнього процесу під час запуску. +двома способами: компактний каталог Skills OpenClaw у доданому системному промпті та +тимчасовий plugin Claude Code, переданий через `--plugin-dir`. Plugin містить +лише ті Skills, які підходять для цього агента/сеансу, тому нативний механізм +розв’язання навичок Claude Code бачить той самий відфільтрований набір, який OpenClaw інакше +рекламував би у промпті. Перевизначення env/API-ключів для Skills, як і раніше, застосовуються OpenClaw до +оточення дочірнього процесу під час запуску. -## Сесії +## Сеанси -- Якщо CLI підтримує сесії, задайте `sessionArg` (наприклад, `--session-id`) або - `sessionArgs` (з плейсхолдером `{sessionId}`), коли ID потрібно вставити - в кілька прапорів. -- Якщо CLI використовує **підкоманду resume** з іншими прапорами, задайте - `resumeArgs` (замінює `args` під час відновлення) і за потреби `resumeOutput` - (для відновлення без JSON). +- Якщо CLI підтримує сеанси, задайте `sessionArg` (наприклад, `--session-id`) або + `sessionArgs` (заповнювач `{sessionId}`), коли ID потрібно вставити + в кілька прапорців. +- Якщо CLI використовує **підкоманду відновлення** з іншими прапорцями, задайте + `resumeArgs` (замінює `args` під час відновлення) і, за потреби, `resumeOutput` + (для відновлень не у JSON). - `sessionMode`: - - `always`: завжди надсилати ідентифікатор сесії (новий UUID, якщо нічого не збережено). - - `existing`: надсилати ідентифікатор сесії лише якщо його вже було збережено. - - `none`: ніколи не надсилати ідентифікатор сесії. + - `always`: завжди надсилати ідентифікатор сеансу (новий UUID, якщо нічого не збережено). + - `existing`: надсилати ідентифікатор сеансу лише якщо його вже було збережено. + - `none`: ніколи не надсилати ідентифікатор сеансу. +- Вбудований бекенд `claude-cli` використовує `liveSession: "claude-stdio"`, тож + наступні ходи повторно використовують активний процес Claude, поки він активний. Якщо + Gateway перезапускається або неактивний процес завершується, OpenClaw відновлює роботу із + збереженого ідентифікатора сеансу Claude. Примітки щодо серіалізації: -- `serialize: true` зберігає впорядкованість запусків на одній смузі. -- Більшість CLI серіалізуються в межах однієї смуги провайдера. -- OpenClaw скидає повторне використання збереженої CLI-сесії, коли змінюється стан автентифікації бекенду, зокрема під час повторного входу, ротації токена або зміни облікових даних профілю автентифікації. +- `serialize: true` зберігає впорядкованість запусків у межах однієї смуги. +- Більшість CLI серіалізують роботу в межах однієї смуги провайдера. +- OpenClaw скидає повторне використання збереженого сеансу CLI, коли змінюється стан автентифікації бекенду, зокрема під час повторного входу, ротації токенів або зміни облікових даних профілю автентифікації. -## Зображення (pass-through) +## Зображення (наскрізна передача) Якщо ваша CLI приймає шляхи до зображень, задайте `imageArg`: @@ -203,27 +210,27 @@ imageMode: "repeat" OpenClaw записуватиме base64-зображення у тимчасові файли. Якщо `imageArg` задано, ці шляхи передаються як аргументи CLI. Якщо `imageArg` відсутній, OpenClaw додає -шляхи до файлів у prompt (інжекція шляху), чого достатньо для CLI, які автоматично +шляхи до файлів у промпт (ін’єкція шляху), чого достатньо для CLI, які автоматично завантажують локальні файли зі звичайних шляхів. ## Входи / виходи -- `output: "json"` (типово) намагається розібрати JSON і витягти текст + ідентифікатор сесії. -- Для JSON-виводу Gemini CLI OpenClaw читає текст відповіді з `response`, а - usage — з `stats`, коли `usage` відсутній або порожній. -- `output: "jsonl"` розбирає потоки JSONL (наприклад, Codex CLI `--json`) і витягує фінальне повідомлення агента та ідентифікатори сесії, +- `output: "json"` (типово) намагається розібрати JSON і витягти текст + ідентифікатор сеансу. +- Для JSON-виводу Gemini CLI OpenClaw зчитує текст відповіді з `response`, а + використання — зі `stats`, коли `usage` відсутній або порожній. +- `output: "jsonl"` розбирає JSONL-потоки (наприклад Codex CLI `--json`) і витягує фінальне повідомлення агента та ідентифікатори сеансу, якщо вони присутні. -- `output: "text"` обробляє stdout як фінальну відповідь. +- `output: "text"` сприймає stdout як фінальну відповідь. -Режими введення: +Режими входу: -- `input: "arg"` (типово) передає prompt як останній аргумент CLI. -- `input: "stdin"` надсилає prompt через stdin. -- Якщо prompt дуже довгий і задано `maxPromptArgChars`, використовується stdin. +- `input: "arg"` (типово) передає промпт як останній аргумент CLI. +- `input: "stdin"` надсилає промпт через stdin. +- Якщо промпт дуже довгий і задано `maxPromptArgChars`, використовується stdin. -## Типові значення (належать Plugin) +## Типові значення (власність plugin) -Вбудований Plugin OpenAI також реєструє типові значення для `codex-cli`: +Вбудований plugin OpenAI також реєструє типові значення для `codex-cli`: - `command: "codex"` - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` @@ -234,7 +241,7 @@ OpenClaw записуватиме base64-зображення у тимчасо - `imageArg: "--image"` - `sessionMode: "existing"` -Вбудований Plugin Google також реєструє типові значення для `google-gemini-cli`: +Вбудований plugin Google також реєструє типові значення для `google-gemini-cli`: - `command: "gemini"` - `args: ["--output-format", "json", "--prompt", "{prompt}"]` @@ -245,32 +252,32 @@ OpenClaw записуватиме base64-зображення у тимчасо - `sessionMode: "existing"` - `sessionIdFields: ["session_id", "sessionId"]` -Передумова: локальна Gemini CLI має бути встановлена й доступна як +Передумова: локальний Gemini CLI має бути встановлений і доступний як `gemini` у `PATH` (`brew install gemini-cli` або `npm install -g @google/gemini-cli`). Примітки щодо JSON Gemini CLI: -- Текст відповіді читається з поля JSON `response`. -- Usage береться з `stats`, якщо `usage` відсутній або порожній. -- `stats.cached` нормалізується в OpenClaw `cacheRead`. -- Якщо `stats.input` відсутній, OpenClaw обчислює вхідні токени з +- Текст відповіді зчитується з поля JSON `response`. +- Використання повертається до `stats`, коли `usage` відсутній або порожній. +- `stats.cached` нормалізується до OpenClaw `cacheRead`. +- Якщо `stats.input` відсутній, OpenClaw виводить вхідні токени з `stats.input_tokens - stats.cached`. -Перевизначайте лише за потреби (типовий випадок: абсолютний шлях `command`). +Перевизначайте лише за потреби (поширений випадок: абсолютний шлях `command`). -## Типові значення, що належать Plugin +## Типові значення, що належать plugin -Типові значення бекенду CLI тепер є частиною поверхні Plugin: +Типові значення бекендів CLI тепер є частиною поверхні plugin: - Plugins реєструють їх через `api.registerCliBackend(...)`. -- `id` бекенду стає префіксом провайдера в посиланнях на модель. -- Конфігурація користувача в `agents.defaults.cliBackends.` як і раніше перевизначає типове значення Plugin. -- Очищення конфігурації, специфічне для бекенду, залишається відповідальністю Plugin через необов’язковий +- `id` бекенду стає префіксом провайдера в посиланнях на моделі. +- Користувацька конфігурація в `agents.defaults.cliBackends.` як і раніше перевизначає типові значення plugin. +- Очищення конфігурації, специфічне для бекенду, залишається у власності plugin через необов’язковий хук `normalizeConfig`. -Plugins, яким потрібні невеликі compatibility shims для prompt/повідомлень, можуть оголошувати -двонапрямні текстові перетворення без заміни провайдера або бекенду CLI: +Plugins, яким потрібні невеликі шими сумісності для промптів/повідомлень, можуть оголошувати +двонапрямні текстові трансформації без заміни провайдера або бекенду CLI: ```typescript api.registerTextTransforms({ @@ -287,17 +294,17 @@ api.registerTextTransforms({ }); ``` -`input` переписує system prompt і prompt користувача, що передаються до CLI. `output` -переписує потокові дельти помічника і розібраний фінальний текст до того, як OpenClaw обробить -власні службові маркери та доставку в канал. +`input` переписує системний промпт і користувацький промпт, передані до CLI. `output` +переписує потокові дельти асистента та розібраний фінальний текст до того, як OpenClaw обробить +власні контрольні маркери та доставку в канал. -Для CLI, які видають JSONL, сумісний із Claude Code stream-json, задайте +Для CLI, які виводять JSONL, сумісний із Claude Code stream-json, задайте `jsonlDialect: "claude-stream-json"` у конфігурації цього бекенду. ## Bundle MCP overlays Бекенди CLI **не** отримують виклики інструментів OpenClaw напряму, але бекенд може -увімкнути згенерований MCP config overlay через `bundleMcp: true`. +увімкнути згенеровану накладену конфігурацію MCP за допомогою `bundleMcp: true`. Поточна вбудована поведінка: @@ -307,32 +314,32 @@ api.registerTextTransforms({ Коли bundle MCP увімкнено, OpenClaw: -- запускає loopback HTTP MCP-сервер, який надає інструменти gateway процесу CLI -- автентифікує міст за допомогою токена на сесію (`OPENCLAW_MCP_TOKEN`) -- обмежує доступ до інструментів поточною сесією, обліковим записом і контекстом каналу -- завантажує увімкнені bundle-MCP сервери для поточного workspace -- об’єднує їх з будь-якою наявною формою MCP-конфігурації/налаштувань бекенду -- переписує конфігурацію запуску, використовуючи режим інтеграції, що належить бекенду, з відповідного extension +- запускає loopback HTTP MCP-сервер, який відкриває інструменти gateway для процесу CLI +- автентифікує міст за допомогою токена на сеанс (`OPENCLAW_MCP_TOKEN`) +- обмежує доступ до інструментів поточним сеансом, обліковим записом і контекстом каналу +- завантажує увімкнені bundle-MCP-сервери для поточного робочого простору +- об’єднує їх із будь-якою наявною формою конфігурації/налаштувань MCP бекенду +- переписує конфігурацію запуску за допомогою режиму інтеграції, що належить бекенду, з розширення-власника -Якщо жодного MCP-сервера не увімкнено, OpenClaw усе одно інжектує строгу конфігурацію, коли +Якщо жоден MCP-сервер не увімкнений, OpenClaw все одно впроваджує строгу конфігурацію, коли бекенд увімкнув bundle MCP, щоб фонові запуски залишалися ізольованими. ## Обмеження -- **Немає прямих викликів інструментів OpenClaw.** OpenClaw не інжектує виклики інструментів у - протокол бекенду CLI. Бекенди бачать інструменти gateway лише коли вони увімкнули +- **Немає прямих викликів інструментів OpenClaw.** OpenClaw не впроваджує виклики інструментів у + протокол бекенду CLI. Бекенди бачать інструменти gateway лише тоді, коли вони вмикають `bundleMcp: true`. -- **Потокова передача залежить від бекенду.** Деякі бекенди передають JSONL потоково, інші буферизують +- **Стримінг залежить від бекенду.** Деякі бекенди передають JSONL-потік; інші буферизують до завершення. - **Структуровані виходи** залежать від JSON-формату CLI. -- **Сесії Codex CLI** відновлюються через текстовий вивід (без JSONL), що менш - структуровано, ніж початковий запуск `--json`. Сесії OpenClaw при цьому все одно працюють - нормально. +- **Сеанси Codex CLI** відновлюються через текстовий вивід (без JSONL), що менш + структуровано, ніж початковий запуск `--json`. Сеанси OpenClaw при цьому все одно + працюють нормально. -## Усунення неполадок +## Усунення несправностей - **CLI не знайдено**: задайте `command` як повний шлях. - **Неправильна назва моделі**: використовуйте `modelAliases`, щоб зіставити `provider/model` → модель CLI. -- **Немає безперервності сесії**: переконайтеся, що задано `sessionArg` і `sessionMode` не дорівнює +- **Немає безперервності сеансу**: переконайтеся, що `sessionArg` задано, а `sessionMode` не дорівнює `none` (Codex CLI наразі не може відновлюватися з JSON-виводом). -- **Зображення ігноруються**: задайте `imageArg` (і переконайтеся, що CLI підтримує шляхи до файлів). +- **Зображення ігноруються**: задайте `imageArg` (і перевірте, що CLI підтримує шляхи до файлів).