Бекенди CLI

OpenClaw може запускати локальний AI CLI як суто текстовий резервний варіант, коли постачальники API недоступні, обмежують частоту запитів або працюють некоректно. Цей механізм навмисно консервативний:

• Інструменти OpenClaw не впроваджуються безпосередньо, але бекенд із bundleMcp: true може отримувати інструменти Gateway через локальний MCP-міст.
• Потокове передавання JSONL для CLI, які його підтримують.
• Сеанси підтримуються, тому наступні звернення залишаються узгодженими.
• Зображення передаються далі, якщо CLI приймає шляхи до зображень.

Використовуйте цей механізм як захисний резерв для текстових відповідей, які «завжди працюють», а не як основний шлях. Для повноцінного середовища виконання з керуванням сеансами ACP, фоновими завданнями, прив’язуванням потоків/розмов і постійними зовнішніми сеансами програмування натомість використовуйте агентів ACP; бекенди CLI не є ACP.

Швидкий початок

Вбудований Plugin Anthropic реєструє стандартний бекенд claude-cli, тому він працює без додаткового налаштування, якщо Claude Code встановлено й у ньому виконано вхід:

openclaw agent --agent main --message "hi" --model claude-cli/claude-sonnet-4-6

main — стандартний ідентифікатор агента, якщо явний список агентів не налаштовано; в іншому разі замініть його ідентифікатором свого агента.

Якщо Gateway працює під керуванням launchd/systemd із мінімальним PATH, явно вкажіть шлях до виконуваного файла:

{  agents: {    defaults: {      cliBackends: {        "claude-cli": {          command: "/opt/homebrew/bin/claude",        },      },    },  },}

Якщо ви використовуєте вбудований бекенд CLI як основного постачальника повідомлень на вузлі Gateway, OpenClaw автоматично завантажує відповідний вбудований Plugin, коли конфігурація посилається на цей бекенд у посиланні на модель або в agents.defaults.cliBackends.

Використання як резервного варіанта

Додайте бекенд CLI до списку резервних варіантів, щоб він запускався лише в разі відмови основних моделей:

{  agents: {    defaults: {      model: {        primary: "anthropic/claude-opus-4-6",        fallbacks: ["claude-cli/claude-sonnet-4-6"],      },      models: {        "anthropic/claude-opus-4-6": { alias: "Opus" },        "claude-cli/claude-sonnet-4-6": {},      },    },  },}

Якщо ви використовуєте agents.defaults.models як список дозволених моделей, також додайте туди моделі бекенду CLI. Коли основний постачальник зазнає відмови через автентифікацію, обмеження частоти запитів або перевищення часу очікування, OpenClaw наступним пробує бекенд CLI.

Налаштування

Усі бекенди CLI розміщуються в agents.defaults.cliBackends і мають ключі за ідентифікатором постачальника (наприклад, claude-cli, my-cli). Ідентифікатор постачальника стає лівою частиною посилання на модель: <provider>/<model>.

{  agents: {    defaults: {      cliBackends: {        "my-cli": {          command: "my-cli",          args: ["--json"],          output: "json",          input: "arg",          modelArg: "--model",          modelAliases: {            "claude-opus-4-6": "opus",            "claude-sonnet-4-6": "sonnet",          },          sessionArg: "--session",          sessionMode: "existing",          sessionIdFields: ["session_id", "conversation_id"],          systemPromptArg: "--system",          // Спеціальний прапорець файла підказки:          // systemPromptFileArg: "--system-file",          // Або натомість прапорець перевизначення конфігурації у стилі Codex:          // systemPromptFileConfigArg: "-c",          // systemPromptFileConfigKey: "model_instructions_file",          systemPromptWhen: "first",          imageArg: "--image",          imageMode: "repeat",          // Увімкніть лише тоді, коли цей бекенд може повторно ініціалізувати          // анульовані сеанси з обмеженої необробленої історії стенограми OpenClaw          // до Compaction.          reseedFromRawTranscriptWhenUncompacted: true,          serialize: true,        },      },    },  },}

Принцип роботи

1. Вибирає бекенд за префіксом постачальника (claude-cli/...).
2. Формує системну підказку, використовуючи ту саму підказку OpenClaw і контекст робочого простору.
3. Виконує CLI з ідентифікатором сеансу (якщо підтримується), щоб історія залишалася узгодженою. Вбудований бекенд claude-cli підтримує процес Claude stdio активним для кожного сеансу OpenClaw і надсилає наступні звернення через stdin у форматі stream-json.
4. Аналізує вивід (JSON або звичайний текст) і повертає остаточний текст.
5. Зберігає ідентифікатори сеансів для кожного бекенду, щоб наступні звернення повторно використовували той самий сеанс CLI.

Особливості Claude CLI

Вбудований бекенд claude-cli надає перевагу нативному механізму визначення Skills у Claude Code. Якщо поточний знімок Skills містить принаймні одну вибрану навичку з матеріалізованим шляхом, OpenClaw передає тимчасовий Plugin Claude Code через --plugin-dir і не додає дубльований каталог Skills OpenClaw до системної підказки. Якщо матеріалізованої навички Plugin немає, OpenClaw залишає каталог у підказці як резервний варіант. Перевизначення змінних середовища та ключів API для навичок і далі застосовуються до середовища дочірнього процесу під час запуску.

Claude CLI має власний неінтерактивний режим дозволів; OpenClaw зіставляє його з наявною політикою виконання замість додавання конфігурації, специфічної для Claude. Для керованих OpenClaw активних сеансів Claude фактична політика виконання є визначальною: режим YOLO (tools.exec.security: "full" і tools.exec.ask: "off") запускає Claude з --permission-mode bypassPermissions, тоді як обмежувальна політика запускає його з --permission-mode default. Налаштування agents.list[].tools.exec для окремого агента перевизначають глобальні tools.exec для цього агента. Необроблені аргументи бекенду можуть і далі містити --permission-mode, але активні запуски Claude нормалізують цей прапорець відповідно до фактичної політики.

Бекенд також зіставляє рівні /think OpenClaw із нативним прапорцем --effort Claude Code: minimal/low -> low, medium -> medium, а high/xhigh/max передаються без змін. adaptive видаляє налаштовані прапорці --effort і не надає заміни, тому Claude Code визначає фактичний рівень зусиль зі свого середовища, налаштувань і стандартних параметрів моделі. Щоб /think впливав на запущений CLI, для інших бекендів CLI їхній Plugin-власник має оголосити еквівалентний перетворювач argv.

Перш ніж OpenClaw зможе використовувати claude-cli, у самому Claude Code має бути виконано вхід на тому самому вузлі:

claude auth loginclaude auth status --textopenclaw models auth login --provider anthropic --method cli --set-default

Для встановлень Docker Claude Code потрібно встановити й увійти в нього всередині постійного домашнього каталогу контейнера, а не лише на вузлі; дивіться бекенд Claude CLI у Docker.

Установлюйте agents.defaults.cliBackends.claude-cli.command лише тоді, коли виконуваного файла claude ще немає в PATH.

Сеанси

• Якщо CLI підтримує сеанси, задайте sessionArg (наприклад, --session-id) або sessionArgs (заповнювач {sessionId}), коли ідентифікатор потрібно передати в кількох прапорцях.
• Якщо CLI використовує підкоманду відновлення з іншими прапорцями, задайте resumeArgs (замінює args під час відновлення) і, за потреби, resumeOutput для відновлень не у форматі JSON.
• sessionMode:
  • always: завжди надсилати ідентифікатор сеансу (новий UUID, якщо збереженого немає).
  • existing: надсилати ідентифікатор сеансу, лише якщо його було збережено раніше.
  • none: ніколи не надсилати ідентифікатор сеансу.
• claude-cli за замовчуванням використовує liveSession: "claude-stdio", output: "jsonl" та input: "stdin", тому наступні звернення повторно використовують активний процес Claude, зокрема для користувацьких конфігурацій, у яких не вказано поля транспорту. Якщо Gateway перезапускається або неактивний процес завершується, OpenClaw відновлює роботу зі збереженого ідентифікатора сеансу Claude. Перед відновленням збережені ідентифікатори сеансів перевіряються за доступною для читання стенограмою проєкту; відсутня стенограма очищає прив’язування (у журналі: reason=transcript-missing) замість непомітного запуску нового сеансу з --resume.
• Активні сеанси Claude мають обмеження виводу JSONL: за замовчуванням 8 МіБ і 20 000 необроблених рядків JSONL на звернення. Збільшуйте їх для окремого бекенду за допомогою agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars і maxTurnLines; OpenClaw обмежує ці налаштування до 64 МіБ і 100 000 рядків.
• Збережені сеанси CLI забезпечують безперервність, якою керує постачальник. Неявне щоденне скидання сеансу їх не перериває; /reset і явні політики session.reset усе ще переривають.
• Нові сеанси CLI зазвичай повторно ініціалізуються лише зі зведення Compaction OpenClaw і хвоста після Compaction. Для відновлення коротких сеансів, анульованих до Compaction, бекенд може увімкнути reseedFromRawTranscriptWhenUncompacted: true. Повторна ініціалізація з необробленої стенограми залишається обмеженою та застосовується лише для безпечних випадків анулювання, як-от відсутня стенограма CLI, загублений хвіст використання інструментів, зміни політики повідомлень/системної підказки/cwd/MCP або повторна спроба після завершення строку дії сеансу; зміни профілю автентифікації або епохи облікових даних ніколи не призводять до повторної ініціалізації з необробленої історії стенограми.

Серіалізація: serialize: true зберігає порядок запусків в одній смузі (більшість CLI серіалізують роботу в одній смузі постачальника). OpenClaw також припиняє повторне використання збереженого сеансу CLI, коли змінюється вибрана ідентичність автентифікації, зокрема ідентифікатор профілю автентифікації, статичний ключ API, статичний токен або ідентичність облікового запису OAuth, якщо CLI її надає; сама лише ротація токенів доступу/оновлення OAuth не перериває сеанс. Якщо CLI не має стабільного ідентифікатора облікового запису OAuth, OpenClaw дозволяє цьому CLI самостійно застосовувати власні дозволи на відновлення.

Вступний контекст резервного переходу із сеансів claude-cli

Коли спроба claude-cli перемикається після відмови на кандидата, що не є CLI, зі списку agents.defaults.model.fallbacks, OpenClaw ініціалізує наступну спробу вступним контекстом, отриманим із локальної стенограми JSONL Claude Code (у ~/.claude/projects/, окремо для кожного робочого простору). Без цього початкового контексту резервний постачальник починає без контексту, оскільки власна стенограма сеансу OpenClaw порожня для запусків claude-cli.

• Вступний контекст надає перевагу найновішому зведенню /compact або маркеру compact_boundary, а потім додає найновіші звернення після межі в межах бюджету символів. Звернення до межі відкидаються, оскільки зведення вже їх представляє.
• Блоки інструментів об’єднуються в компактні підказки (tool call: name) і (tool result: …), щоб чесно дотримуватися бюджету підказки; завелике зведення скорочується й позначається (truncated).
• Резервні переходи в межах одного постачальника з claude-cli на claude-cli покладаються на власний --resume Claude і пропускають вступний контекст.
• Початковий контекст повторно використовує наявну перевірку шляху до файла сеансу Claude, тому довільні шляхи неможливо прочитати.

Зображення

Якщо ваш CLI приймає шляхи до зображень, задайте imageArg:

imageArg: "--image",imageMode: "repeat"

OpenClaw записує зображення base64 у тимчасові файли. Якщо задано imageArg, ці шляхи передаються як аргументи CLI; якщо ні, OpenClaw додає шляхи до файлів у підказку (впровадження шляхів), що працює для CLI, які автоматично завантажують локальні файли зі звичайних шляхів.

Вхідні та вихідні дані

• output: "text" (за замовчуванням) вважає stdout остаточною відповіддю.
• output: "json" намагається проаналізувати JSON і видобути текст разом з ідентифікатором сеансу.
• output: "jsonl" аналізує потік JSONL і видобуває остаточне повідомлення агента разом з ідентифікаторами сеансу, якщо вони наявні.
• Для виводу Gemini CLI у форматі JSON OpenClaw зчитує текст відповіді з response, а дані використання — зі stats, коли usage відсутнє або порожнє. Вбудована стандартна конфігурація Gemini CLI використовує stream-json; старі перевизначення --output-format json і далі використовують аналізатор JSON.

Режими введення:

• input: "arg" (за замовчуванням) передає підказку як останній аргумент CLI.
• input: "stdin" надсилає підказку через stdin.
• Якщо підказка дуже довга й задано maxPromptArgChars, натомість використовується stdin.

Стандартні параметри, якими керує Plugin

Стандартні параметри бекенду CLI є частиною поверхні Plugin:

• Плагіни реєструють їх за допомогою api.registerCliBackend(...).
• id бекенду стає префіксом постачальника в посиланнях на моделі.
• Користувацька конфігурація в agents.defaults.cliBackends.<id> усе одно перевизначає стандартні параметри Plugin.
• Очищення конфігурації, специфічне для бекенду, залишається у власності Plugin через необов’язковий обробник normalizeConfig.

Anthropic володіє claude-cli, а Google — google-gemini-cli. Запуски агента OpenAI Codex використовують середовище app-server Codex через openai/*; OpenClaw більше не реєструє вбудований бекенд codex-cli.

Вбудований Plugin Anthropic реєструє для claude-cli:

Вбудований Plugin Google реєструється для google-gemini-cli:

Передумова: локальний Gemini CLI має бути встановлений і доступний у PATH як gemini (brew install gemini-cli або npm install -g @google/gemini-cli).

Примітки щодо виводу Gemini CLI:

• Стандартний аналізатор stream-json читає події message асистента, події інструментів, статистику використання з фінального result і події фатальних помилок Gemini.
• Якщо перевизначити аргументи Gemini на --output-format json, OpenClaw нормалізує цей бекенд назад до output: "json" і читає текст відповіді з поля response у JSON.
• Якщо usage відсутнє або порожнє, дані про використання беруться зі stats; stats.cached нормалізується в cacheRead OpenClaw, а якщо stats.input відсутнє, кількість вхідних токенів обчислюється як stats.input_tokens - stats.cached.

Перевизначайте стандартні значення лише за потреби (найчастіше — абсолютний шлях command).

Накладені перетворення тексту

Plugins, яким потрібні невеликі шари сумісності для запитів або повідомлень, можуть оголошувати двоспрямовані перетворення тексту без заміни провайдера чи бекенду CLI:

api.registerTextTransforms({  input: [{ from: /red basket/g, to: "blue basket" }],  output: [{ from: /blue basket/g, to: "red basket" }],});

input переписує системний і користувацький запити, передані до CLI. output переписує потоковий текст асистента й проаналізований фінальний текст до того, як OpenClaw обробить власні керівні маркери та доставлення в канал; для викликів моделей через провайдера він також відновлює рядкові значення всередині структурованих аргументів виклику інструментів після відновлення потоку й перед виконанням інструмента. Необроблені фрагменти JSON від провайдера залишаються незмінними; споживачам слід використовувати структуроване часткове, кінцеве або результативне корисне навантаження.

Для CLI, які виводять специфічні для провайдера події JSONL, установіть jsonlDialect у конфігурації відповідного бекенду: claude-stream-json для потоків, сумісних із Claude Code, і gemini-stream-json для подій stream-json Gemini CLI.

Власник нативного Compaction

Деякі бекенди CLI запускають агента, який самостійно виконує Compaction власної стенограми, тому OpenClaw не повинен запускати для них свій захисний засіб підсумовування — інакше він конфліктуватиме з власним Compaction бекенду та може спричинити критичний збій ходу.

claude-cli не має кінцевої точки рушія (Claude Code виконує Compaction внутрішньо), тому він оголошує ownsNativeCompaction: true, а шлях Compaction в OpenClaw повертає запис сеансу без змін. Натомість сеанси з нативним рушієм, як-от Codex, і далі спрямовуються до кінцевої точки Compaction свого рушія.

api.registerCliBackend({ id: "my-cli", ownsNativeCompaction: true /* ... */ });

Оголошуйте ownsNativeCompaction лише для бекенду, який справді відповідає за Compaction: він має надійно обмежувати власну стенограму поблизу межі контекстного вікна та зберігати сеанс із можливістю відновлення (наприклад, --resume / --session-id), інакше відкладений сеанс може залишитися понад ліміт.

Накладені конфігурації пакетного MCP

Бекенди CLI не отримують виклики інструментів OpenClaw безпосередньо, але бекенд може ввімкнути згенеровану накладену конфігурацію MCP за допомогою bundleMcp: true. Поточна вбудована поведінка:

• claude-cli: згенерований файл суворої конфігурації MCP.
• google-gemini-cli: згенерований файл системних налаштувань Gemini.

Коли пакетний MCP увімкнено, OpenClaw:

• запускає локальний циклічний HTTP-сервер MCP, який надає процесу CLI інструменти Gateway, автентифіковані дозволом контексту для окремого запуску (OPENCLAW_MCP_TOKEN), активним лише для поточної спроби виконання;
• прив’язує доступ до інструментів до вибраного Gateway контексту сеансу, облікового запису та каналу замість довіри до заголовків дочірнього процесу;
• завантажує ввімкнені сервери пакетного MCP для поточного робочого простору й об’єднує їх із наявною конфігурацією або структурою налаштувань MCP бекенду;
• переписує конфігурацію запуску, використовуючи режим інтеграції, яким керує Plugin-власник бекенду.

Якщо жодного сервера MCP не ввімкнено, OpenClaw усе одно додає сувору конфігурацію, коли бекенд вмикає пакетний MCP, щоб фонові запуски залишалися ізольованими.

Вбудовані середовища виконання MCP, прив’язані до сеансу, кешуються для повторного використання в межах сеансу, а потім видаляються після mcp.sessionIdleTtlMs мілісекунд бездіяльності (стандартно 10 хвилин; установіть 0, щоб вимкнути). Одноразові вбудовані запуски, як-от перевірки автентифікації, генерування коротких ідентифікаторів і відновлення Active Memory, запитують очищення після завершення запуску, щоб дочірні процеси stdio та потоки Streamable HTTP/SSE не продовжували існувати після нього.

Обмеження історії повторного заповнення

Коли новий сеанс CLI заповнюється з попередньої стенограми OpenClaw (наприклад, після повторної спроби через session_expired), відтворений блок <conversation_history> обмежується, щоб запити повторного заповнення не розросталися надмірно. Стандартне обмеження становить 12 288 символів (приблизно 3 000 токенів).

Бекенди Claude CLI натомість масштабують це обмеження відповідно до визначеного контекстного вікна Claude: більші контекстні вікна отримують більший фрагмент попередньої історії до фіксованої верхньої межі; інші бекенди CLI зберігають консервативне стандартне значення. Це обмеження керує лише блоком попередньої історії в запиті повторного заповнення — обмеження виводу активного сеансу налаштовуються окремо в reliability.outputLimits (див. Сеанси).

Обмеження

• Немає прямих викликів інструментів OpenClaw: OpenClaw не додає виклики інструментів до протоколу бекенду CLI. Бекенди бачать інструменти Gateway лише тоді, коли вмикають bundleMcp: true.
• Потокове передавання залежить від бекенду: деякі бекенди передають JSONL потоком, інші буферизують дані до завершення.
• Структурований вивід залежить від власного формату JSON CLI.

Усунення несправностей

Пов’язані матеріали

• Посібник з експлуатації Gateway
• Локальні моделі