chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
bbed7c3897
commit
f8b55df366
@ -1,47 +1,47 @@
|
||||
---
|
||||
read_when:
|
||||
- Вам потрібен надійний резервний варіант, коли API-провайдери не працюють
|
||||
- Ви запускаєте Codex CLI або інші локальні AI CLI й хочете використовувати їх повторно
|
||||
- Ви хочете зрозуміти loopback-міст MCP для доступу CLI-бекенду до інструментів
|
||||
summary: 'CLI-бекенди: локальний резервний AI CLI з необов’язковим мостом інструментів MCP'
|
||||
title: CLI-бекенди
|
||||
- Ви використовуєте Codex CLI або інші локальні AI CLI і хочете повторно використовувати їх
|
||||
- Ви хочете зрозуміти MCP-місток local loopback для доступу CLI бекенда до інструментів
|
||||
summary: 'CLI бекенди: локальний резервний AI CLI з необов’язковим MCP-містком для інструментів'
|
||||
title: CLI бекенди
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T09:37:56Z"
|
||||
generated_at: "2026-04-08T17:18:42Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b0e8c41f5f5a8e34466f6b765e5c08585ef1788fa9e9d953257324bcc6cbc414
|
||||
source_hash: 9b458f9fe6fa64c47864c8c180f3dedfd35c5647de470a2a4d31c26165663c20
|
||||
source_path: gateway/cli-backends.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# CLI-бекенди (резервне середовище виконання)
|
||||
# CLI бекенди (резервне середовище виконання)
|
||||
|
||||
OpenClaw може запускати **локальні AI CLI** як **лише текстовий резервний варіант**, коли API-провайдери недоступні,
|
||||
обмежені за частотою запитів або тимчасово працюють некоректно. Це навмисно консервативний підхід:
|
||||
|
||||
- **Інструменти OpenClaw не вбудовуються напряму**, але бекенди з `bundleMcp: true`
|
||||
можуть отримувати інструменти gateway через loopback-міст MCP.
|
||||
- **Потокова передача JSONL** для CLI, які це підтримують.
|
||||
- **Сесії підтримуються** (тож наступні ходи залишаються узгодженими).
|
||||
- **Інструменти OpenClaw не інжектуються безпосередньо**, але бекенди з `bundleMcp: true`
|
||||
можуть отримувати інструменти шлюзу через loopback MCP-місток.
|
||||
- **JSONL-стримінг** для CLI, які це підтримують.
|
||||
- **Сесії підтримуються** (щоб наступні звернення залишалися узгодженими).
|
||||
- **Зображення можна передавати далі**, якщо CLI приймає шляхи до зображень.
|
||||
|
||||
Це задумано як **страхувальна сітка**, а не як основний шлях. Використовуйте це, коли
|
||||
потрібні текстові відповіді у стилі «завжди працює» без залежності від зовнішніх API.
|
||||
Це розроблено як **страхувальна сітка**, а не як основний шлях. Використовуйте це, коли
|
||||
вам потрібні текстові відповіді у стилі «завжди працює» без залежності від зовнішніх API.
|
||||
|
||||
Якщо вам потрібне повноцінне середовище виконання harness із керуванням сесіями ACP, фоновими завданнями,
|
||||
прив’язкою до потоку/розмови та постійними зовнішніми сесіями кодування, натомість використовуйте
|
||||
[ACP Agents](/uk/tools/acp-agents). CLI-бекенди — це не ACP.
|
||||
[ACP Agents](/uk/tools/acp-agents). CLI бекенди — це не ACP.
|
||||
|
||||
## Швидкий старт для початківців
|
||||
|
||||
Ви можете використовувати Codex CLI **без жодної конфігурації** (вбудований плагін OpenAI
|
||||
реєструє типовий бекенд):
|
||||
реєструє стандартний бекенд):
|
||||
|
||||
```bash
|
||||
openclaw agent --message "hi" --model codex-cli/gpt-5.4
|
||||
```
|
||||
|
||||
Якщо ваш gateway працює під launchd/systemd і PATH мінімальний, додайте лише
|
||||
Якщо ваш шлюз працює під launchd/systemd і PATH мінімальний, додайте лише
|
||||
шлях до команди:
|
||||
|
||||
```json5
|
||||
@ -58,16 +58,16 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4
|
||||
}
|
||||
```
|
||||
|
||||
І це все. Жодних ключів, жодної додаткової конфігурації автентифікації, окрім самої CLI.
|
||||
І це все. Ні ключів, ні додаткової конфігурації автентифікації, окрім самої CLI, не потрібно.
|
||||
|
||||
Якщо ви використовуєте вбудований CLI-бекенд як **основного провайдера повідомлень** на
|
||||
хості gateway, OpenClaw тепер автоматично завантажує відповідний вбудований плагін, коли ваша конфігурація
|
||||
Якщо ви використовуєте вбудований CLI бекенд як **основного провайдера повідомлень** на
|
||||
хості шлюзу, OpenClaw тепер автоматично завантажує відповідний вбудований плагін, коли ваша конфігурація
|
||||
явно посилається на цей бекенд у посиланні на модель або в
|
||||
`agents.defaults.cliBackends`.
|
||||
|
||||
## Використання як резервного варіанта
|
||||
|
||||
Додайте CLI-бекенд до списку резервних варіантів, щоб він запускався лише тоді, коли основні моделі не працюють:
|
||||
Додайте CLI бекенд до свого списку резервних варіантів, щоб він запускався лише тоді, коли основні моделі не працюють:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -88,20 +88,20 @@ 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
|
||||
```
|
||||
|
||||
Кожен запис має ключ у вигляді **id провайдера** (наприклад, `codex-cli`, `my-cli`).
|
||||
ID провайдера стає лівою частиною посилання на модель:
|
||||
Кожен запис має ключ у вигляді **ідентифікатора провайдера** (наприклад, `codex-cli`, `my-cli`).
|
||||
Ідентифікатор провайдера стає лівою частиною посилання на модель:
|
||||
|
||||
```
|
||||
<provider>/<model>
|
||||
@ -131,6 +131,9 @@ ID провайдера стає лівою частиною посилання
|
||||
sessionMode: "existing",
|
||||
sessionIdFields: ["session_id", "conversation_id"],
|
||||
systemPromptArg: "--system",
|
||||
// CLI у стилі Codex можуть натомість вказувати файл підказки:
|
||||
// systemPromptFileConfigArg: "-c",
|
||||
// systemPromptFileConfigKey: "model_instructions_file",
|
||||
systemPromptWhen: "first",
|
||||
imageArg: "--image",
|
||||
imageMode: "repeat",
|
||||
@ -145,10 +148,10 @@ ID провайдера стає лівою частиною посилання
|
||||
## Як це працює
|
||||
|
||||
1. **Вибирає бекенд** на основі префікса провайдера (`codex-cli/...`).
|
||||
2. **Створює системний промпт** із використанням того самого промпту OpenClaw і контексту робочого простору.
|
||||
3. **Запускає CLI** з id сесії (якщо підтримується), щоб історія залишалася узгодженою.
|
||||
4. **Розбирає вивід** (JSON або звичайний текст) і повертає фінальний текст.
|
||||
5. **Зберігає id сесій** для кожного бекенду, щоб наступні ходи повторно використовували ту саму CLI-сесію.
|
||||
2. **Створює системну підказку** з використанням тієї самої підказки OpenClaw + контексту робочого простору.
|
||||
3. **Виконує CLI** з ідентифікатором сесії (якщо підтримується), щоб історія залишалася узгодженою.
|
||||
4. **Аналізує вивід** (JSON або звичайний текст) і повертає фінальний текст.
|
||||
5. **Зберігає ідентифікатори сесій** для кожного бекенда, щоб наступні звернення повторно використовували ту саму CLI-сесію.
|
||||
|
||||
<Note>
|
||||
Вбудований бекенд Anthropic `claude-cli` знову підтримується. Співробітники Anthropic
|
||||
@ -157,53 +160,59 @@ ID провайдера стає лівою частиною посилання
|
||||
нову політику.
|
||||
</Note>
|
||||
|
||||
Вбудований бекенд OpenAI `codex-cli` передає системну підказку OpenClaw через
|
||||
перевизначення конфігурації Codex `model_instructions_file` (`-c
|
||||
model_instructions_file="..."`). Codex не надає прапорця на кшталт Claude
|
||||
`--append-system-prompt`, тому OpenClaw записує зібрану підказку до
|
||||
тимчасового файла для кожної нової сесії Codex CLI.
|
||||
|
||||
## Сесії
|
||||
|
||||
- Якщо CLI підтримує сесії, задайте `sessionArg` (наприклад, `--session-id`) або
|
||||
`sessionArgs` (заповнювач `{sessionId}`), коли ID потрібно вставляти
|
||||
- Якщо CLI підтримує сесії, установіть `sessionArg` (наприклад, `--session-id`) або
|
||||
`sessionArgs` (заповнювач `{sessionId}`), коли ідентифікатор потрібно вставити
|
||||
в кілька прапорців.
|
||||
- Якщо CLI використовує **підкоманду відновлення** з іншими прапорцями, задайте
|
||||
`resumeArgs` (замінює `args` під час відновлення) і, за потреби, `resumeOutput`
|
||||
- Якщо CLI використовує **підкоманду відновлення** з іншими прапорцями, установіть
|
||||
`resumeArgs` (замінює `args` під час відновлення) і за потреби `resumeOutput`
|
||||
(для відновлення не у форматі JSON).
|
||||
- `sessionMode`:
|
||||
- `always`: завжди передавати id сесії (новий UUID, якщо нічого не збережено).
|
||||
- `existing`: передавати id сесії лише тоді, якщо його вже було збережено раніше.
|
||||
- `none`: ніколи не передавати id сесії.
|
||||
- `always`: завжди надсилати ідентифікатор сесії (новий UUID, якщо нічого не збережено).
|
||||
- `existing`: надсилати ідентифікатор сесії, лише якщо він уже був раніше збережений.
|
||||
- `none`: ніколи не надсилати ідентифікатор сесії.
|
||||
|
||||
Примітки щодо серіалізації:
|
||||
|
||||
- `serialize: true` зберігає впорядкованість запусків в одній лінії.
|
||||
- Більшість CLI серіалізують роботу в межах однієї лінії провайдера.
|
||||
- OpenClaw скидає повторне використання збереженої CLI-сесії, коли змінюється стан автентифікації бекенду, включно з повторним входом, ротацією токена або зміною облікових даних профілю автентифікації.
|
||||
- Більшість 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 і витягти текст + id сесії.
|
||||
- Для JSON-виводу Gemini CLI OpenClaw читає текст відповіді з `response`, а
|
||||
використання — з `stats`, коли `usage` відсутній або порожній.
|
||||
- `output: "jsonl"` розбирає потоки JSONL (наприклад Codex CLI `--json`) і витягує фінальне повідомлення агента разом з
|
||||
ідентифікаторами сесії, якщо вони присутні.
|
||||
- `output: "text"` трактує stdout як фінальну відповідь.
|
||||
- `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.
|
||||
|
||||
## Типові значення (належать плагіну)
|
||||
|
||||
@ -233,11 +242,11 @@ 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`, якщо `usage` відсутній або порожній.
|
||||
- `stats.cached` нормалізується в OpenClaw `cacheRead`.
|
||||
- Якщо `stats.input` відсутній, OpenClaw виводить кількість вхідних токенів із
|
||||
`stats.input_tokens - stats.cached`.
|
||||
|
||||
@ -245,53 +254,53 @@ OpenClaw записує base64-зображення у тимчасові фай
|
||||
|
||||
## Типові значення, що належать плагіну
|
||||
|
||||
Типові значення CLI-бекенду тепер є частиною поверхні плагіна:
|
||||
Типові значення CLI бекенда тепер є частиною поверхні плагіна:
|
||||
|
||||
- Плагіни реєструють їх через `api.registerCliBackend(...)`.
|
||||
- `id` бекенду стає префіксом провайдера в посиланнях на модель.
|
||||
- Конфігурація користувача в `agents.defaults.cliBackends.<id>` як і раніше перевизначає типове значення плагіна.
|
||||
- Очищення конфігурації, специфічне для бекенду, залишається у власності плагіна через необов’язковий
|
||||
хук `normalizeConfig`.
|
||||
- `id` бекенда стає префіксом провайдера в посиланнях на моделі.
|
||||
- Конфігурація користувача в `agents.defaults.cliBackends.<id>` і далі перевизначає типове значення плагіна.
|
||||
- Очищення конфігурації, специфічне для бекенда, залишається на боці плагіна через необов’язковий
|
||||
гук `normalizeConfig`.
|
||||
|
||||
## Bundle MCP overlays
|
||||
## Накладки Bundle MCP
|
||||
|
||||
CLI-бекенди **не** отримують виклики інструментів OpenClaw напряму, але бекенд може
|
||||
увімкнути згенерований накладений MCP-конфіг із `bundleMcp: true`.
|
||||
CLI бекенди **не** отримують виклики інструментів OpenClaw безпосередньо, але бекенд може
|
||||
увімкнути згенеровану накладку конфігурації MCP за допомогою `bundleMcp: true`.
|
||||
|
||||
Поточна вбудована поведінка:
|
||||
|
||||
- `claude-cli`: згенерований strict MCP config file
|
||||
- `codex-cli`: inline config overrides для `mcp_servers`
|
||||
- `google-gemini-cli`: згенерований Gemini system settings file
|
||||
- `claude-cli`: згенерований суворий файл конфігурації MCP
|
||||
- `codex-cli`: вбудовані перевизначення конфігурації для `mcp_servers`
|
||||
- `google-gemini-cli`: згенерований файл системних налаштувань Gemini
|
||||
|
||||
Коли bundle MCP увімкнено, OpenClaw:
|
||||
|
||||
- запускає loopback HTTP MCP-сервер, який відкриває інструменти gateway для процесу CLI
|
||||
- автентифікує міст за допомогою токена на сесію (`OPENCLAW_MCP_TOKEN`)
|
||||
- запускає loopback HTTP MCP-сервер, який надає інструменти шлюзу процесу CLI
|
||||
- автентифікує місток за допомогою токена на сесію (`OPENCLAW_MCP_TOKEN`)
|
||||
- обмежує доступ до інструментів поточною сесією, обліковим записом і контекстом каналу
|
||||
- завантажує ввімкнені bundle-MCP-сервери для поточного робочого простору
|
||||
- об’єднує їх із наявною формою MCP-конфігурації/налаштувань бекенду
|
||||
- переписує конфігурацію запуску, використовуючи режим інтеграції, що належить бекенду, з відповідного розширення
|
||||
- завантажує увімкнені сервери bundle-MCP для поточного робочого простору
|
||||
- об’єднує їх із будь-якою наявною формою конфігурації/налаштувань MCP бекенда
|
||||
- переписує конфігурацію запуску, використовуючи режим інтеграції, що належить бекенду з відповідного розширення
|
||||
|
||||
Якщо жоден MCP-сервер не ввімкнено, OpenClaw все одно вбудовує strict config, коли
|
||||
бекенд підтримує bundle MCP, щоб фонові запуски залишалися ізольованими.
|
||||
Якщо жоден MCP-сервер не ввімкнено, OpenClaw однаково інжектує сувору конфігурацію, коли
|
||||
бекенд використовує bundle MCP, щоб фонові запуски залишалися ізольованими.
|
||||
|
||||
## Обмеження
|
||||
|
||||
- **Немає прямих викликів інструментів OpenClaw.** OpenClaw не вбудовує виклики інструментів у
|
||||
протокол CLI-бекенду. Бекенди бачать інструменти gateway лише тоді, коли вони вмикають
|
||||
- **Немає прямих викликів інструментів OpenClaw.** OpenClaw не інжектує виклики інструментів у
|
||||
протокол CLI бекенда. Бекенди бачать інструменти шлюзу лише тоді, коли вони використовують
|
||||
`bundleMcp: true`.
|
||||
- **Потокова передача залежить від бекенду.** Деякі бекенди передають JSONL потоком; інші буферизують
|
||||
- **Стримінг залежить від бекенда.** Деякі бекенди транслюють JSONL; інші буферизують
|
||||
до завершення.
|
||||
- **Структуровані вихідні дані** залежать від JSON-формату CLI.
|
||||
- **Структуровані виходи** залежать від JSON-формату CLI.
|
||||
- **Сесії Codex CLI** відновлюються через текстовий вивід (без JSONL), що менш
|
||||
структуровано, ніж початковий запуск `--json`. Сесії OpenClaw все одно працюють
|
||||
структуровано, ніж початковий запуск `--json`. Сесії OpenClaw усе одно працюють
|
||||
нормально.
|
||||
|
||||
## Усунення проблем
|
||||
|
||||
- **CLI не знайдено**: задайте для `command` повний шлях.
|
||||
- **Неправильна назва моделі**: використайте `modelAliases`, щоб зіставити `provider/model` → модель CLI.
|
||||
- **Немає безперервності сесії**: переконайтеся, що задано `sessionArg`, а `sessionMode` не
|
||||
- **CLI не знайдено**: установіть для `command` повний шлях.
|
||||
- **Неправильна назва моделі**: використовуйте `modelAliases`, щоб зіставити `provider/model` → модель CLI.
|
||||
- **Немає безперервності сесії**: переконайтеся, що встановлено `sessionArg` і що `sessionMode` не дорівнює
|
||||
`none` (Codex CLI наразі не може відновлюватися з JSON-виводом).
|
||||
- **Зображення ігноруються**: задайте `imageArg` (і перевірте, що CLI підтримує шляхи до файлів).
|
||||
- **Зображення ігноруються**: установіть `imageArg` (і переконайтеся, що CLI підтримує шляхи до файлів).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user