diff --git a/docs/uk/gateway/cli-backends.md b/docs/uk/gateway/cli-backends.md index b4c3fad94..42e7fa1ac 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 й хочете використовувати їх повторно - - Ви хочете зрозуміти 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`). +Ідентифікатор провайдера стає лівою частиною посилання на модель: ``` / @@ -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-сесію. Вбудований бекенд Anthropic `claude-cli` знову підтримується. Співробітники Anthropic @@ -157,53 +160,59 @@ ID провайдера стає лівою частиною посилання нову політику. +Вбудований бекенд 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.` як і раніше перевизначає типове значення плагіна. -- Очищення конфігурації, специфічне для бекенду, залишається у власності плагіна через необов’язковий - хук `normalizeConfig`. +- `id` бекенда стає префіксом провайдера в посиланнях на моделі. +- Конфігурація користувача в `agents.defaults.cliBackends.` і далі перевизначає типове значення плагіна. +- Очищення конфігурації, специфічне для бекенда, залишається на боці плагіна через необов’язковий + гук `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 підтримує шляхи до файлів).