chore(i18n): refresh uk translations

This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-22 17:41:11 +00:00
parent 592f188412
commit 21f3194fc9

View File

@ -1,47 +1,47 @@
---
read_when:
- Вам потрібен надійний резервний варіант, коли API-провайдери не працюють
- Ви запускаєте Codex CLI або інші локальні AI CLI й хочете повторно використовувати їх
- Ви хочете зрозуміти міст local loopback MCP для доступу CLI-бекенду до інструментів
summary: 'Бекенди CLI: резервний локальний AI CLI з необов’язковим мостом інструментів MCP'
- Вам потрібен надійний резервний варіант, коли постачальники API зазнають збою
- Ви запускаєте Codex CLI або інші локальні AI CLI і хочете повторно використовувати їх
- Ви хочете зрозуміти міст local loopback MCP для доступу інструментів до бекенда CLI
summary: 'Бекенди CLI: локальний резервний AI CLI з необов’язковим мостом інструментів MCP'
title: Бекенди CLI
x-i18n:
generated_at: "2026-04-22T10:06:57Z"
generated_at: "2026-04-22T17:40:13Z"
model: gpt-5.4
provider: openai
source_hash: d0f224027422cccad6777a7b68208774d2a176c4faafb2e0188d50549653eacc
source_hash: d252cf0db426ad091038dd8ce3bc12b810b02f42a4c81d326ec766b21dbadd01
source_path: gateway/cli-backends.md
workflow: 15
---
# Бекенди CLI (резервне середовище виконання)
OpenClaw може запускати **локальні AI CLI** як **суто текстовий резервний варіант**, коли API-провайдери недоступні,
обмежені за rate limit або тимчасово працюють некоректно. Це навмисно консервативний підхід:
OpenClaw може запускати **локальні AI CLI** як **текстовий резервний варіант**, коли постачальники API недоступні,
обмежують запити або тимчасово працюють нестабільно. Це навмисно консервативний підхід:
- **Інструменти OpenClaw не впроваджуються напряму**, але бекенди з `bundleMcp: true`
можуть отримувати інструменти Gateway через loopback-міст MCP.
- **JSONL-стримінг** для CLI, які його підтримують.
- **Сесії підтримуються** (тому наступні ходи залишаються узгодженими).
- **Зображення можна передавати наскрізно**, якщо CLI приймає шляхи до зображень.
- **Інструменти OpenClaw не вбудовуються безпосередньо**, але бекенди з `bundleMcp: true`
можуть отримувати інструменти Gateway через міст loopback MCP.
- **Потокова передача JSONL** для CLI, які її підтримують.
- **Сеанси підтримуються** (щоб наступні ходи залишалися узгодженими).
- **Зображення можна передавати далі**, якщо CLI приймає шляхи до зображень.
Це задумано як **запобіжна сітка**, а не основний шлях. Використовуйте це, коли
вам потрібні текстові відповіді у стилі «завжди працює» без залежності від зовнішніх API.
Це задумано як **страхувальна сітка**, а не як основний шлях. Використовуйте це, коли
вам потрібні текстові відповіді в режимі «завжди працює» без залежності від зовнішніх API.
Якщо вам потрібне повноцінне harness-середовище виконання з керуванням сесіями ACP, фоновими завданнями,
прив’язкою до потоку/розмови та постійними зовнішніми сесіями кодування, використовуйте
Якщо вам потрібне повноцінне середовище виконання harness із керуванням сеансами ACP, фоновими завданнями,
прив’язкою до потоку/розмови та постійними зовнішніми сеансами кодування, використовуйте
[ACP Agents](/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,14 +58,14 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4
}
```
Ось і все. Жодних ключів, жодної додаткової конфігурації автентифікації, окрім самої CLI.
Ось і все. Жодних ключів, жодної додаткової конфігурації автентифікації понад ту, що вже потрібна самому CLI.
Якщо ви використовуєте вбудований бекенд CLI як **основного провайдера повідомлень** на
хості Gateway, OpenClaw тепер автоматично завантажує пов’язаний вбудований Plugin, коли ваша конфігурація
Якщо ви використовуєте вбудований бекенд CLI як **основного постачальника повідомлень** на
хості Gateway, OpenClaw тепер автоматично завантажує відповідний вбудований Plugin, коли ваша конфігурація
явно посилається на цей бекенд у посиланні на модель або в
`agents.defaults.cliBackends`.
## Використання як резервного варіанту
## Використання як резервного варіанта
Додайте бекенд CLI до списку резервних варіантів, щоб він запускався лише тоді, коли основні моделі не працюють:
@ -88,20 +88,20 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4
Примітки:
- Якщо ви використовуєте `agents.defaults.models` (allowlist), ви також маєте включити туди моделі вашого бекенду CLI.
- Якщо основний провайдер не працює (автентифікація, rate limit, тайм-аути), OpenClaw
далі спробує бекенд CLI.
- Якщо ви використовуєте `agents.defaults.models` (список дозволених), ви також маєте включити туди моделі вашого бекенда CLI.
- Якщо основний постачальник не працює (автентифікація, обмеження швидкості, тайм-аути), OpenClaw
спробує далі бекенд CLI.
## Огляд конфігурації
Усі бекенди CLI розташовані в:
Усі бекенди CLI знаходяться в:
```
agents.defaults.cliBackends
```
Кожен запис має ключ у вигляді **ідентифікатора провайдера** (наприклад, `codex-cli`, `my-cli`).
Ідентифікатор провайдера стає лівою частиною посилання на модель:
Кожен запис має ключ у вигляді **ідентифікатора постачальника** (наприклад, `codex-cli`, `my-cli`).
Ідентифікатор постачальника стає лівою частиною посилання на модель:
```
<provider>/<model>
@ -131,7 +131,7 @@ agents.defaults.cliBackends
sessionMode: "existing",
sessionIdFields: ["session_id", "conversation_id"],
systemPromptArg: "--system",
// CLI у стилі Codex можуть натомість вказувати на файл запиту:
// CLI у стилі Codex можуть натомість вказувати на файл промпту:
// systemPromptFileConfigArg: "-c",
// systemPromptFileConfigKey: "model_instructions_file",
systemPromptWhen: "first",
@ -147,91 +147,90 @@ agents.defaults.cliBackends
## Як це працює
1. **Вибирає бекенд** на основі префікса провайдера (`codex-cli/...`).
2. **Формує системний запит** з використанням того самого запиту OpenClaw і контексту робочого простору.
3. **Виконує CLI** з ідентифікатором сесії (якщо підтримується), щоб історія залишалася узгодженою.
Вбудований бекенд `claude-cli` підтримує активний stdio-процес Claude для кожної
сесії OpenClaw і надсилає наступні ходи через stream-json stdin.
4. **Розбирає вивід** (JSON або звичайний текст) і повертає фінальний текст.
5. **Зберігає ідентифікатори сесій** для кожного бекенду, щоб у наступних ходах повторно використовувати ту саму CLI-сесію.
1. **Вибирає бекенд** на основі префікса постачальника (`codex-cli/...`).
2. **Формує системний промпт** із використанням того самого промпту OpenClaw + контексту робочого простору.
3. **Виконує CLI** з ідентифікатором сеансу (якщо підтримується), щоб історія залишалася узгодженою.
Вбудований бекенд `claude-cli` підтримує процес Claude stdio активним для кожного
сеансу OpenClaw і надсилає наступні ходи через stream-json stdin.
4. **Аналізує вивід** (JSON або звичайний текст) і повертає фінальний текст.
5. **Зберігає ідентифікатори сеансів** для кожного бекенда, щоб наступні звернення повторно використовували той самий сеанс CLI.
<Note>
Вбудований бекенд Anthropic `claude-cli` знову підтримується. Співробітники Anthropic
повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тож OpenClaw розглядає
використання `claude -p` як санкціоноване для цієї інтеграції, доки Anthropic не опублікує
повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw розглядає
використання `claude -p` як санкціоноване для цієї інтеграції, якщо Anthropic не опублікує
нову політику.
</Note>
Вбудований бекенд OpenAI `codex-cli` передає системний запит OpenClaw через
перевизначення конфігурації `model_instructions_file` у Codex (`-c
model_instructions_file="..."`). Codex не надає прапорця у стилі Claude
`--append-system-prompt`, тому OpenClaw записує зібраний запит у
тимчасовий файл для кожної нової сесії 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 у доданому системному запиті та
тимчасовий плагін Claude Code, переданий через `--plugin-dir`. Плагін містить
лише допустимі Skills для цього агента/сесії, тож нативний механізм розв’язання Skills у Claude Code бачить
той самий відфільтрований набір, який OpenClaw інакше оголошував би в запиті.
Перевизначення середовища/API-ключів Skill, як і раніше, застосовуються OpenClaw до середовища дочірнього процесу для цього запуску.
двома способами: компактний каталог Skills OpenClaw у доданому системному промпті та
тимчасовий Plugin Claude Code, переданий через `--plugin-dir`. Plugin містить
лише допустимі Skills для цього агента/сеансу, тож вбудований механізм розв’язання навичок Claude Code
бачить той самий відфільтрований набір, який OpenClaw інакше рекламував би у промпті. Перевизначення змінних середовища/API-ключів для Skill, як і раніше, застосовуються OpenClaw до середовища дочірнього процесу під час запуску.
## Сесії
## Сеанси
- Якщо CLI підтримує сесії, установіть `sessionArg` (наприклад, `--session-id`) або
`sessionArgs` (заповнювач `{sessionId}`), коли ID потрібно вставити
- Якщо CLI підтримує сеанси, задайте `sessionArg` (наприклад, `--session-id`) або
`sessionArgs` (заповнювач `{sessionId}`), коли ідентифікатор потрібно вставити
в кілька прапорців.
- Якщо CLI використовує **підкоманду відновлення** з іншими прапорцями, установіть
`resumeArgs` (замінює `args` під час відновлення) і за потреби `resumeOutput`
- Якщо CLI використовує **підкоманду resume** з іншими прапорцями, задайте
`resumeArgs` (замінює `args` при відновленні) та, за потреби, `resumeOutput`
(для відновлення не у форматі JSON).
- `sessionMode`:
- `always`: завжди надсилати ідентифікатор сесії (новий UUID, якщо нічого не збережено).
- `existing`: надсилати ідентифікатор сесії лише якщо його вже було збережено раніше.
- `none`: ніколи не надсилати ідентифікатор сесії.
- Вбудований бекенд `claude-cli` використовує `liveSession: "claude-stdio"`, тому
наступні ходи повторно використовують активний процес Claude, доки він активний. Якщо
Gateway перезапускається або неактивний процес завершується, OpenClaw відновлюється із збереженого
ідентифікатора сесії Claude.
- Збережені CLI-сесії — це безперервність, що належить провайдеру. Неявне щоденне
скидання сесії не обриває їх; `/reset` і явні політики `session.reset` — так.
- `always`: завжди надсилати ідентифікатор сеансу (новий UUID, якщо жодного не збережено).
- `existing`: надсилати ідентифікатор сеансу лише якщо його вже було збережено раніше.
- `none`: ніколи не надсилати ідентифікатор сеансу.
- Для `claude-cli` типовими є `liveSession: "claude-stdio"`, `output: "jsonl"`,
і `input: "stdin"`, тому наступні ходи повторно використовують активний процес Claude, поки
він активний. Якщо Gateway перезапускається або неактивний процес завершується, OpenClaw
відновлюється із збереженого ідентифікатора сеансу Claude.
- Збережені сеанси CLI — це безперервність, якою володіє постачальник. Неявне щоденне
скидання сеансу їх не обриває; `/reset` і явні політики `session.reset` — обривають.
Примітки щодо серіалізації:
- `serialize: true` зберігає впорядкованість запусків у межах однієї лінії.
- Більшість CLI серіалізують роботу в одній лінії провайдера.
- OpenClaw скидає повторне використання збереженої CLI-сесії, коли змінюється стан автентифікації бекенду, зокрема після повторного входу, ротації токенів або зміни облікових даних профілю автентифікації.
- `serialize: true` зберігає впорядкованість запусків в одній смузі.
- Більшість CLI серіалізують виконання в одній смузі постачальника.
- OpenClaw скидає повторне використання збереженого сеансу CLI, коли змінюється стан автентифікації бекенда, зокрема під час повторного входу, ротації токена або зміни облікових даних профілю автентифікації.
## Зображення (наскрізна передача)
## Зображення (передавання далі)
Якщо ваша CLI приймає шляхи до зображень, установіть `imageArg`:
Якщо ваш CLI приймає шляхи до зображень, задайте `imageArg`:
```json5
imageArg: "--image",
imageMode: "repeat"
```
OpenClaw записуватиме зображення з base64 до тимчасових файлів. Якщо `imageArg` установлено,
ці шляхи передаватимуться як аргументи CLI. Якщо `imageArg` відсутній, OpenClaw додасть
шляхи до файлів у запит (ін’єкція шляху), чого достатньо для CLI, які автоматично
завантажують локальні файли за звичайними шляхами.
OpenClaw записуватиме зображення base64 у тимчасові файли. Якщо `imageArg` задано, ці
шляхи передаються як аргументи CLI. Якщо `imageArg` відсутній, OpenClaw додає
шляхи до файлів у промпт (ін’єкція шляху), чого достатньо для CLI, які автоматично
завантажують локальні файли зі звичайних шляхів.
## Входи / виходи
- `output: "json"` (типово) намагається розібрати JSON і витягти текст + ідентифікатор сесії.
- Для JSON-виводу Gemini CLI OpenClaw читає текст відповіді з `response`, а
використання — зі `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 як фінальну відповідь.
Режими введення:
- `input: "arg"` (типово) передає запит як останній аргумент CLI.
- `input: "stdin"` надсилає запит через stdin.
- Якщо запит дуже довгий і встановлено `maxPromptArgChars`, використовується stdin.
- `input: "arg"` (типово) передає промпт як останній аргумент CLI.
- `input: "stdin"` надсилає промпт через stdin.
- Якщо промпт дуже довгий і задано `maxPromptArgChars`, використовується stdin.
## Значення за замовчуванням (належать Plugin)
## Типові значення (керуються Plugin)
Вбудований плагін OpenAI також реєструє значення за замовчуванням для `codex-cli`:
Вбудований Plugin OpenAI також реєструє типові значення для `codex-cli`:
- `command: "codex"`
- `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
@ -242,7 +241,7 @@ OpenClaw записуватиме зображення з base64 до тимча
- `imageArg: "--image"`
- `sessionMode: "existing"`
Вбудований плагін Google також реєструє значення за замовчуванням для `google-gemini-cli`:
Вбудований Plugin Google також реєструє типові значення для `google-gemini-cli`:
- `command: "gemini"`
- `args: ["--output-format", "json", "--prompt", "{prompt}"]`
@ -257,28 +256,28 @@ OpenClaw записуватиме зображення з base64 до тимча
`gemini` у `PATH` (`brew install gemini-cli` або
`npm install -g @google/gemini-cli`).
Примітки щодо JSON у Gemini CLI:
Примітки щодо JSON Gemini CLI:
- Текст відповіді зчитується з поля JSON `response`.
- Дані використання беруться зі `stats`, якщо `usage` відсутнє або порожнє.
- `stats.cached` нормалізується в OpenClaw `cacheRead`.
- Якщо `stats.input` відсутнє, OpenClaw обчислює вхідні токени з
- Використання повертається до `stats`, якщо `usage` відсутній або порожній.
- `stats.cached` нормалізується до OpenClaw `cacheRead`.
- Якщо `stats.input` відсутній, OpenClaw обчислює вхідні токени як
`stats.input_tokens - stats.cached`.
Перевизначайте лише за потреби (типовий випадок: абсолютний шлях `command`).
## Значення за замовчуванням, що належать Plugin
## Типові значення, керовані Plugin
Значення за замовчуванням для бекендів CLI тепер є частиною поверхні Plugin:
Типові значення бекендів CLI тепер є частиною поверхні Plugin:
- Plugins реєструють їх через `api.registerCliBackend(...)`.
- `id` бекенду стає префіксом провайдера в посиланнях на моделі.
- Конфігурація користувача в `agents.defaults.cliBackends.<id>` усе ще перевизначає стандартне значення Plugin.
- Очищення конфігурації, специфічне для бекенду, і далі належить Plugin через необов’язковий
хук `normalizeConfig`.
- `id` бекенда стає префіксом постачальника в посиланнях на моделі.
- Конфігурація користувача в `agents.defaults.cliBackends.<id>` як і раніше перевизначає типове значення Plugin.
- Очищення конфігурації, специфічне для бекенда, залишається під керуванням Plugin через необов’язковий хук
`normalizeConfig`.
Plugins, яким потрібні невеликі суміснісні shim-перетворення для запитів/повідомлень, можуть оголошувати
двоспрямовані текстові перетворення без заміни провайдера або бекенду CLI:
Plugins, яким потрібні невеликі суміснісні шими для промптів/повідомлень, можуть оголошувати
двоспрямовані текстові перетворення без заміни постачальника чи бекенда CLI:
```typescript
api.registerTextTransforms({
@ -295,52 +294,52 @@ api.registerTextTransforms({
});
```
`input` переписує системний запит і запит користувача, передані до CLI. `output`
переписує потокові дельти асистента та розібраний фінальний текст до того, як OpenClaw обробить
власні керувальні маркери й доставку в канал.
`input` переписує системний промпт і користувацький промпт, передані до CLI. `output`
переписує потокові дельти асистента й розібраний фінальний текст до того, як OpenClaw обробить
власні керувальні маркери та доставку каналом.
Для CLI, які виводять JSONL, сумісний із Claude Code stream-json, установіть
`jsonlDialect: "claude-stream-json"` у конфігурації цього бекенду.
Для CLI, які виводять JSONL, сумісний із Claude Code stream-json, задайте
`jsonlDialect: "claude-stream-json"` у конфігурації цього бекенда.
## Bundle MCP overlays
Бекенди CLI **не** отримують виклики інструментів OpenClaw напряму, але бекенд може
явно ввімкнути згенерований оверлей конфігурації MCP через `bundleMcp: true`.
Бекенди CLI **не** отримують виклики інструментів OpenClaw безпосередньо, але бекенд може
погодитися на згенероване накладання конфігурації MCP через `bundleMcp: true`.
Поточна вбудована поведінка:
- `claude-cli`: згенерований суворий файл конфігурації MCP
- `claude-cli`: згенерований файл суворої конфігурації MCP
- `codex-cli`: вбудовані перевизначення конфігурації для `mcp_servers`
- `google-gemini-cli`: згенерований файл системних налаштувань Gemini
Коли bundle MCP увімкнено, OpenClaw:
- запускає loopback HTTP MCP-сервер, який надає інструменти Gateway процесу CLI
- автентифікує міст за допомогою токена для кожної сесії (`OPENCLAW_MCP_TOKEN`)
- обмежує доступ до інструментів поточною сесією, обліковим записом і контекстом каналу
- завантажує ввімкнені bundle-MCP-сервери для поточного робочого простору
- об’єднує їх із будь-якою наявною формою конфігурації/налаштувань MCP бекенду
- переписує конфігурацію запуску, використовуючи режим інтеграції, що належить бекенду, із розширення-власника
- автентифікує міст за допомогою токена для кожного сеансу (`OPENCLAW_MCP_TOKEN`)
- обмежує доступ до інструментів поточним сеансом, обліковим записом і контекстом каналу
- завантажує увімкнені bundle-MCP-сервери для поточного робочого простору
- об’єднує їх із будь-якою наявною формою MCP-конфігурації/налаштувань бекенда
- переписує конфігурацію запуску за допомогою режиму інтеграції, що належить бекенду, з відповідного розширення
Якщо жоден MCP-сервер не ввімкнено, OpenClaw усе одно впроваджує сувору конфігурацію, коли
бекенд явно використовує bundle MCP, щоб фонові запуски залишалися ізольованими.
Якщо жоден 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` повний шлях.
- **CLI не знайдено**: задайте `command` як повний шлях.
- **Неправильна назва моделі**: використовуйте `modelAliases`, щоб зіставити `provider/model` → модель CLI.
- **Немає безперервності сесії**: переконайтеся, що встановлено `sessionArg`, а `sessionMode` не дорівнює
- **Немає безперервності сеансу**: переконайтеся, що задано `sessionArg` і що `sessionMode` не має значення
`none` (Codex CLI наразі не може відновлюватися з JSON-виводом).
- **Зображення ігноруються**: установіть `imageArg` (і переконайтеся, що CLI підтримує шляхи до файлів).
- **Зображення ігноруються**: задайте `imageArg` (і переконайтеся, що CLI підтримує шляхи до файлів).