CLI-бэкенды (резервная среда выполнения)

OpenClaw может запускать локальные AI CLI в качестве текстового резерва, когда API-провайдеры недоступны, ограничены по скорости или временно не работают. Это намеренно консервативно:

  • Инструменты отключены (нет вызовов инструментов).
  • Текст на входе → текст на выходе (надежно).
  • Сессии поддерживаются (так что последующие обороты остаются когерентными).
  • Изображения могут передаваться, если CLI принимает пути к изображениям.

Это разработано как страховочная сетка, а не основной путь. Используйте его, когда вам нужны текстовые ответы «всегда работает» без зависимости от внешних API.

Быстрый старт для начинающих

Вы можете использовать Claude Code CLI без какой-либо конфигурации (OpenClaw поставляется со встроенным значением по умолчанию):

openclaw agent --message "привет" --model claude-cli/opus-4.5

Codex CLI также работает из коробки:

openclaw agent --message "привет" --model codex-cli/gpt-5.2-codex

Если ваш шлюз работает под launchd/systemd и PATH минимален, добавьте только путь к команде:

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

Вот и все. Никаких ключей, никакой дополнительной конфигурации аутентификации, кроме самого CLI.

Использование в качестве резерва

Добавьте CLI-бэкенд в свой список резервов, чтобы он работал только тогда, когда основные модели не работают:

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

Примечания:

  • Если вы используете agents.defaults.models (белый список), вы должны включить claude-cli/....
  • Если основной провайдер не работает (аутентификация, ограничения скорости, тайм-ауты), OpenClaw попробует CLI-бэкенд следующим.

Обзор конфигурации

Все CLI-бэкенды находятся под:

agents.defaults.cliBackends

Каждая запись имеет ключ по идентификатору провайдера (например, claude-cli, my-cli). Идентификатор провайдера становится левой частью ссылки на вашу модель:

<provider>/<model>

Пример конфигурации

\{
  agents: \{
    defaults: \{
      cliBackends: \{
        "claude-cli": \{
          command: "/opt/homebrew/bin/claude"
        \},
        "my-cli": \{
          command: "my-cli",
          args: ["--json"],
          output: "json",
          input: "arg",
          modelArg: "--model",
          modelAliases: \{
            "claude-opus-4-5": "opus",
            "claude-sonnet-4-5": "sonnet"
          \},
          sessionArg: "--session",
          sessionMode: "existing",
          sessionIdFields: ["session_id", "conversation_id"],
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true
        \}
      \}
    \}
  \}
\}

Как это работает

  1. Выбирает бэкенд на основе префикса провайдера (claude-cli/...).
  2. Строит системный промпт используя тот же промпт OpenClaw + контекст рабочего пространства.
  3. Выполняет CLI с идентификатором сессии (если поддерживается), чтобы история оставалась согласованной.
  4. Парсит вывод (JSON или обычный текст) и возвращает финальный текст.
  5. Сохраняет идентификаторы сессий по бэкенду, чтобы последующие обращения повторно использовали ту же CLI-сессию.

Сессии

  • Если CLI поддерживает сессии, установите sessionArg (например, --session-id) или sessionArgs (плейсхолдер \{sessionId\}), когда ID нужно вставить в несколько флагов.
  • Если CLI использует подкоманду возобновления с разными флагами, установите resumeArgs (заменяет args при возобновлении) и опционально resumeOutput (для невJSON возобновлений).
  • sessionMode:
    • always: всегда отправляйте идентификатор сессии (новый UUID, если ни один не сохранен).
    • existing: отправляйте идентификатор сессии только если он был сохранен ранее.
    • none: никогда не отправляйте идентификатор сессии.

Изображения (сквозная передача)

Если ваш CLI принимает пути к изображениям, установите imageArg:

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

OpenClaw будет записывать base64-изображения во временные файлы. Если установлен imageArg, эти пути передаются как аргументы CLI. Если imageArg отсутствует, OpenClaw добавляет пути к файлам в промпт (инъекция путей), что достаточно для CLI, которые автоматически загружают локальные файлы из простых путей (поведение Claude Code CLI).

Входы / выходы

  • output: "json" (по умолчанию) пытается разобрать JSON и извлечь текст + идентификатор сессии.
  • output: "jsonl" парсит потоки JSONL (Codex CLI --json) и извлекает последнее сообщение агента плюс thread_id, когда присутствует.
  • output: "text" обрабатывает stdout как финальный ответ.

Режимы ввода:

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

Значения по умолчанию (встроенные)

OpenClaw поставляется с значением по умолчанию для claude-cli:

  • command: "claude"
  • args: ["-p", "--output-format", "json", "--dangerously-skip-permissions"]
  • resumeArgs: ["-p", "--output-format", "json", "--dangerously-skip-permissions", "--resume", "\{sessionId\}"]
  • modelArg: "--model"
  • systemPromptArg: "--append-system-prompt"
  • sessionArg: "--session-id"
  • systemPromptWhen: "first"
  • sessionMode: "always"

OpenClaw также поставляется с значением по умолчанию для codex-cli:

  • command: "codex"
  • args: ["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]
  • resumeArgs: ["exec","resume","\{sessionId\}","--color","never","--sandbox","read-only","--skip-git-repo-check"]
  • output: "jsonl"
  • resumeOutput: "text"
  • modelArg: "--model"
  • imageArg: "--image"
  • sessionMode: "existing"

Переопределяйте только при необходимости (обычно: абсолютный путь command).

Ограничения

  • Нет инструментов OpenClaw (CLI-бэкенд никогда не получает вызовы инструментов). Некоторые CLI все еще могут запускать свои собственные агентские инструменты.
  • Нет потоковой передачи (вывод CLI собирается, затем возвращается).
  • Структурированные выходы зависят от JSON-формата CLI.
  • Сессии Codex CLI возобновляются через текстовый вывод (не JSONL), который менее структурирован, чем начальный запуск --json. Сессии OpenClaw все еще работают нормально.

Устранение неполадок

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