Перейти до основного вмісту

​
CLI-бекенди (резервне середовище виконання)

OpenClaw може запускати локальні AI CLI як лише текстовий резервний варіант, коли API-провайдери недоступні, обмежені за частотою запитів або тимчасово працюють некоректно. Це навмисно консервативний підхід:
  • Інструменти OpenClaw не вбудовуються напряму, але бекенди з bundleMcp: true можуть отримувати інструменти gateway через loopback-міст MCP.
  • Потокова передача JSONL для CLI, які це підтримують.
  • Сесії підтримуються (тож наступні ходи залишаються узгодженими).
  • Зображення можна передавати далі, якщо CLI приймає шляхи до зображень.
Це задумано як страхувальна сітка, а не як основний шлях. Використовуйте це, коли потрібні текстові відповіді у стилі «завжди працює» без залежності від зовнішніх API. Якщо вам потрібне повноцінне середовище виконання harness із керуванням сесіями ACP, фоновими завданнями, прив’язкою до потоку/розмови та постійними зовнішніми сесіями кодування, натомість використовуйте ACP Agents. CLI-бекенди — це не ACP.

​
Швидкий старт для початківців

Ви можете використовувати Codex CLI без жодної конфігурації (вбудований плагін OpenAI реєструє типовий бекенд): 
openclaw agent --message "hi" --model codex-cli/gpt-5.4
Якщо ваш gateway працює під launchd/systemd і PATH мінімальний, додайте лише шлях до команди: 
{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
      },
    },
  },
}
І це все. Жодних ключів, жодної додаткової конфігурації автентифікації, окрім самої CLI. Якщо ви використовуєте вбудований CLI-бекенд як основного провайдера повідомлень на хості gateway, OpenClaw тепер автоматично завантажує відповідний вбудований плагін, коли ваша конфігурація явно посилається на цей бекенд у посиланні на модель або в agents.defaults.cliBackends.

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

Додайте CLI-бекенд до списку резервних варіантів, щоб він запускався лише тоді, коли основні моделі не працюють: 
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["codex-cli/gpt-5.4"],
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "codex-cli/gpt-5.4": {},
      },
    },
  },
}
Примітки:
  • Якщо ви використовуєте agents.defaults.models (allowlist), ви також маєте включити туди моделі CLI-бекенду.
  • Якщо основний провайдер не працює (автентифікація, ліміти запитів, тайм-аути), OpenClaw спробує CLI-бекенд наступним.

​
Огляд конфігурації

Усі CLI-бекенди знаходяться в: 
agents.defaults.cliBackends
Кожен запис має ключ у вигляді id провайдера (наприклад, codex-cli, my-cli). ID провайдера стає лівою частиною посилання на модель: 
<provider>/<model>

​
Приклад конфігурації

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "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",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

​
Як це працює

  1. Вибирає бекенд на основі префікса провайдера (codex-cli/...).
  2. Створює системний промпт із використанням того самого промпту OpenClaw і контексту робочого простору.
  3. Запускає CLI з id сесії (якщо підтримується), щоб історія залишалася узгодженою.
  4. Розбирає вивід (JSON або звичайний текст) і повертає фінальний текст.
  5. Зберігає id сесій для кожного бекенду, щоб наступні ходи повторно використовували ту саму CLI-сесію.
Вбудований бекенд Anthropic claude-cli знову підтримується. Співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає використання claude -p санкціонованим для цієї інтеграції, якщо Anthropic не опублікує нову політику.

​
Сесії

  • Якщо CLI підтримує сесії, задайте sessionArg (наприклад, --session-id) або sessionArgs (заповнювач {sessionId}), коли ID потрібно вставляти в кілька прапорців.
  • Якщо CLI використовує підкоманду відновлення з іншими прапорцями, задайте resumeArgs (замінює args під час відновлення) і, за потреби, resumeOutput (для відновлення не у форматі JSON).
  • sessionMode:
    • always: завжди передавати id сесії (новий UUID, якщо нічого не збережено).
    • existing: передавати id сесії лише тоді, якщо його вже було збережено раніше.
    • none: ніколи не передавати id сесії.
Примітки щодо серіалізації:
  • serialize: true зберігає впорядкованість запусків в одній лінії.
  • Більшість CLI серіалізують роботу в межах однієї лінії провайдера.
  • OpenClaw скидає повторне використання збереженої CLI-сесії, коли змінюється стан автентифікації бекенду, включно з повторним входом, ротацією токена або зміною облікових даних профілю автентифікації.

​
Зображення (передача далі)

Якщо ваша CLI приймає шляхи до зображень, задайте imageArg: 
imageArg: "--image",
imageMode: "repeat"
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 як фінальну відповідь.
Режими введення:
  • input: "arg" (типово) передає промпт як останній аргумент CLI.
  • input: "stdin" надсилає промпт через stdin.
  • Якщо промпт дуже довгий і задано maxPromptArgChars, використовується stdin.

​
Типові значення (належать плагіну)

Вбудований плагін OpenAI також реєструє типові значення для codex-cli:
  • command: "codex"
  • args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
  • resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
  • output: "jsonl"
  • resumeOutput: "text"
  • modelArg: "--model"
  • imageArg: "--image"
  • sessionMode: "existing"
Вбудований плагін Google також реєструє типові значення для google-gemini-cli:
  • command: "gemini"
  • args: ["--output-format", "json", "--prompt", "{prompt}"]
  • resumeArgs: ["--resume", "{sessionId}", "--output-format", "json", "--prompt", "{prompt}"]
  • imageArg: "@"
  • imagePathScope: "workspace"
  • modelArg: "--model"
  • sessionMode: "existing"
  • sessionIdFields: ["session_id", "sessionId"]
Передумова: локальний Gemini CLI має бути встановлений і доступний як gemini у PATH (brew install gemini-cli або npm install -g @google/gemini-cli). Примітки щодо JSON у Gemini CLI:
  • Текст відповіді читається з поля JSON response.
  • Дані про використання беруться з stats, якщо usage відсутній або порожній.
  • stats.cached нормалізується до OpenClaw cacheRead.
  • Якщо stats.input відсутній, OpenClaw виводить кількість вхідних токенів із stats.input_tokens - stats.cached.
Перевизначайте лише за потреби (поширений випадок: абсолютний шлях command).

​
Типові значення, що належать плагіну

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

​
Bundle MCP overlays

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
Коли bundle MCP увімкнено, OpenClaw:
  • запускає loopback HTTP MCP-сервер, який відкриває інструменти gateway для процесу CLI
  • автентифікує міст за допомогою токена на сесію (OPENCLAW_MCP_TOKEN)
  • обмежує доступ до інструментів поточною сесією, обліковим записом і контекстом каналу
  • завантажує ввімкнені bundle-MCP-сервери для поточного робочого простору
  • об’єднує їх із наявною формою MCP-конфігурації/налаштувань бекенду
  • переписує конфігурацію запуску, використовуючи режим інтеграції, що належить бекенду, з відповідного розширення
Якщо жоден MCP-сервер не ввімкнено, OpenClaw все одно вбудовує strict config, коли бекенд підтримує bundle MCP, щоб фонові запуски залишалися ізольованими.

​
Обмеження

  • Немає прямих викликів інструментів OpenClaw. OpenClaw не вбудовує виклики інструментів у протокол CLI-бекенду. Бекенди бачать інструменти gateway лише тоді, коли вони вмикають bundleMcp: true.
  • Потокова передача залежить від бекенду. Деякі бекенди передають JSONL потоком; інші буферизують до завершення.
  • Структуровані вихідні дані залежать від JSON-формату CLI.
  • Сесії Codex CLI відновлюються через текстовий вивід (без JSONL), що менш структуровано, ніж початковий запуск --json. Сесії OpenClaw все одно працюють нормально.

​
Усунення проблем

  • CLI не знайдено: задайте для command повний шлях.
  • Неправильна назва моделі: використайте modelAliases, щоб зіставити provider/model → модель CLI.
  • Немає безперервності сесії: переконайтеся, що задано sessionArg, а sessionMode не none (Codex CLI наразі не може відновлюватися з JSON-виводом).
  • Зображення ігноруються: задайте imageArg (і перевірте, що CLI підтримує шляхи до файлів).