Бэкенды CLI

• Инструменты OpenClaw не внедряются напрямую, но бэкенды с bundleMcp: true могут получать инструменты Gateway через loopback MCP-мост.
• Потоковая передача JSONL для CLI, которые ее поддерживают.
• Сессии поддерживаются (поэтому последующие ходы остаются согласованными).
• Изображения можно передавать сквозным образом, если CLI принимает пути к изображениям.

​

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

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

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

​

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

{
  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-бэкенд следующим.

​

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

agents.defaults.cliBackends

<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",
          // For CLIs with a dedicated prompt-file flag:
          // systemPromptFileArg: "--system-file",
          // Codex-style CLIs can point at a prompt file instead:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          // Opt in only if this backend may reseed safe invalidated sessions
          // from bounded raw OpenClaw transcript history before 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 auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

​

Сессии

• Если CLI поддерживает сессии, задайте sessionArg (например, --session-id) или sessionArgs (заполнитель {sessionId}), когда идентификатор нужно вставить в несколько флагов.
• Если CLI использует подкоманду resume с другими флагами, задайте resumeArgs (заменяет args при возобновлении) и при необходимости resumeOutput (для возобновлений не в JSON).
• sessionMode:
  • always: всегда отправлять идентификатор сессии (новый UUID, если сохраненного нет).
  • existing: отправлять идентификатор сессии только если он был сохранен ранее.
  • none: никогда не отправлять идентификатор сессии.
• claude-cli по умолчанию использует liveSession: "claude-stdio", output: "jsonl", и input: "stdin", поэтому последующие ходы повторно используют активный процесс Claude, пока он активен. Warm stdio теперь используется по умолчанию, в том числе для пользовательских конфигураций, которые опускают поля транспорта. Если Gateway перезапускается или бездействующий процесс завершается, OpenClaw возобновляет работу из сохраненного идентификатора сессии Claude. Сохраненные идентификаторы сессий проверяются по существующему читаемому транскрипту проекта перед возобновлением, поэтому фантомные привязки очищаются с reason=transcript-missing вместо тихого запуска новой сессии Claude CLI под --resume.
• Активные сессии Claude сохраняют ограниченные предохранители вывода JSONL. Значения по умолчанию допускают до 8 MiB и 20 000 необработанных строк JSONL на ход. Ходы Claude с большим количеством инструментов могут увеличить их для каждого бэкенда с помощью 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. OpenClaw все равно ограничивает повторную инициализацию из необработанного транскрипта и применяет ее только к безопасным инвалидациям, таким как отсутствующие транскрипты CLI, изменения системного промпта/MCP или повторная попытка из-за истекшей сессии; изменения профиля аутентификации или эпохи учетных данных никогда не переинициализируют историю необработанного транскрипта.

• serialize: true сохраняет порядок запусков в одной lane.
• Большинство CLI сериализуются на одной lane провайдера.
• OpenClaw прекращает повторное использование сохраненной CLI-сессии, когда выбранная идентичность аутентификации меняется, включая измененный идентификатор профиля аутентификации, статический API-ключ, статический токен или идентичность учетной записи OAuth, если CLI ее предоставляет. Ротация токенов доступа и обновления OAuth не прерывает сохраненную CLI-сессию. Если CLI не предоставляет стабильный идентификатор учетной записи OAuth, OpenClaw позволяет этой CLI самостоятельно применять разрешения на возобновление.

​

Резервная прелюдия из сессий claude-cli

• Прелюдия предпочитает последнюю сводку /compact или маркер compact_boundary, затем добавляет последние ходы после границы до лимита символов. Ходы до границы отбрасываются, потому что сводка уже представляет их.
• Блоки инструментов объединяются в компактные подсказки (tool call: name) и (tool result: …), чтобы честно расходовать бюджет промпта. Сводка помечается (truncated), если она переполняется.
• Резервные переходы с claude-cli на claude-cli у того же провайдера полагаются на собственный --resume Claude и пропускают прелюдию.
• Начальный контекст повторно использует существующую проверку пути к файлу сессии Claude, поэтому произвольные пути не могут быть прочитаны.

​

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

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

​

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

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

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

​

Значения по умолчанию (принадлежат plugin)

• command: "claude"
• args: ["-p","--output-format","stream-json","--include-partial-messages","--verbose", ...]
• output: "jsonl"
• input: "stdin"
• modelArg: "--model"
• sessionMode: "always"

• command: "gemini"
• args: ["--skip-trust", "--approval-mode", "auto_edit", "--output-format", "stream-json", "--prompt", "{prompt}"]
• resumeArgs: ["--skip-trust", "--approval-mode", "auto_edit", "--resume", "{sessionId}", "--output-format", "stream-json", "--prompt", "{prompt}"]
• output: "jsonl"
• resumeOutput: "jsonl"
• jsonlDialect: "gemini-stream-json"
• imageArg: "@"
• imagePathScope: "workspace"
• modelArg: "--model"
• sessionMode: "existing"
• sessionIdFields: ["session_id", "sessionId"]

• Парсер stream-json по умолчанию читает события message ассистента, события инструментов, итоговое использование result и фатальные события ошибок Gemini.
• Если вы переопределяете аргументы Gemini на --output-format json, OpenClaw нормализует этот бэкенд обратно к output: "json" и читает текст ответа из поля JSON response.
• Если usage отсутствует или пуст, использование берется из stats.
• stats.cached нормализуется в cacheRead OpenClaw.
• Если stats.input отсутствует, OpenClaw вычисляет входные токены из stats.input_tokens - stats.cached.

​

Значения по умолчанию, принадлежащие plugin

• Plugins регистрируют их через api.registerCliBackend(...).
• id бэкенда становится префиксом провайдера в ссылках на модели.
• Пользовательская конфигурация в agents.defaults.cliBackends.<id> по-прежнему переопределяет значение по умолчанию plugin.
• Очистка конфигурации, специфичная для бэкенда, остается в собственности plugin через необязательный хук normalizeConfig.

api.registerTextTransforms({
  input: [
    { from: /red basket/g, to: "blue basket" },
    { from: /paper ticket/g, to: "digital ticket" },
    { from: /left shelf/g, to: "right shelf" },
  ],
  output: [
    { from: /blue basket/g, to: "red basket" },
    { from: /digital ticket/g, to: "paper ticket" },
    { from: /right shelf/g, to: "left shelf" },
  ],
});

​

Владение нативной Compaction

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

​

Наложения Bundle MCP

• claude-cli: сгенерированный строгий файл конфигурации MCP
• google-gemini-cli: сгенерированный файл системных настроек Gemini

• запускает loopback HTTP MCP-сервер, который предоставляет gateway-инструменты процессу CLI
• аутентифицирует мост с помощью токена на сессию (OPENCLAW_MCP_TOKEN)
• ограничивает доступ к инструментам текущей сессией, учетной записью и контекстом канала
• загружает включенные bundle-MCP-серверы для текущей рабочей области
• объединяет их с любой существующей формой MCP-конфигурации/настроек бэкенда
• переписывает конфигурацию запуска, используя режим интеграции, принадлежащий бэкенду, из владеющего расширения

​

Ограничение истории при reseed

• Лимит управляет только блоком предыдущей истории в reseed-промпте. Лимиты вывода live-сессии настраиваются отдельно в reliability.outputLimits (см. Сессии).

​

Ограничения

• Нет прямых вызовов инструментов OpenClaw. OpenClaw не внедряет вызовы инструментов в протокол CLI-бэкенда. Бэкенды видят gateway-инструменты только при подключении к bundleMcp: true.
• Streaming зависит от бэкенда. Некоторые бэкенды транслируют JSONL; другие буферизуют до завершения.
• Структурированные выводы зависят от JSON-формата CLI.

​

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

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

​

Связанные материалы

• Runbook Gateway
• Локальные модели