Бекенди CLI

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

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

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

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

Вбудований плагін 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 автоматично завантажує відповідний вбудований плагін, коли конфігурація посилається на цей бекенд у посиланні на модель або в 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 підтримує окремий процес stdio Claude для кожного сеансу OpenClaw і надсилає наступні репліки через stdin у форматі stream-json.
4. Аналізує виведення (JSON або звичайний текст) і повертає остаточний текст.
5. Зберігає ідентифікатори сеансів для кожного бекенду, щоб наступні репліки повторно використовували той самий сеанс CLI.

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

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

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

Бекенд також зіставляє рівні /think OpenClaw із вбудованим прапорцем --effort Claude Code: minimal/low -> low, medium -> medium, а high/xhigh/max передаються безпосередньо. Завдяки цьому підтримувані рівні зусиль Fable 5 залишаються однаковими для Claude CLI із доступом через передплату та маршрутів із ключами API. adaptive вилучає налаштовані прапорці --effort і не надає заміни, тому Claude Code визначає чинний рівень зусиль із власного середовища, налаштувань і типових значень моделі. Щоб /think впливало на запущений CLI, для інших бекендів CLI відповідний плагін має оголосити аналогічне зіставлення 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 MiB і 20,000 необроблених рядків JSONL на репліку. Збільшуйте їх окремо для кожного бекенду за допомогою agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars і maxTurnLines; OpenClaw обмежує ці налаштування до 64 MiB і 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.

Значення за замовчуванням, визначені плагінами

Значення за замовчуванням для бекендів CLI є частиною поверхні плагіна:

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

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

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

Вбудований плагін 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" і читає текст відповіді з поля JSON response.
• Якщо usage відсутнє або порожнє, для використання застосовується резервне значення stats; stats.cached нормалізується в cacheRead OpenClaw, а якщо stats.input відсутнє, кількість вхідних токенів визначається з stats.input_tokens - stats.cached.

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

Накладення текстових перетворень

Плагіни, яким потрібні невеликі прокладки сумісності для запитів або повідомлень, можуть оголошувати двобічні текстові перетворення без заміни провайдера чи бекенда 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 для подій Gemini CLI stream-json.

Власність нативного Compaction

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

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

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

Оголошуйте ownsNativeCompaction лише для бекенда, який справді володіє ущільненням: він має надійно обмежувати власний транскрипт поблизу вікна контексту та зберігати сеанс, який можна поновити (наприклад, --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 бекенда;
• переписує конфігурацію запуску, використовуючи режим інтеграції бекенда з плагіна-власника.

Якщо жодного сервера 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
• Локальні моделі