Бэкенды CLI

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

• Инструменты OpenClaw не внедряются напрямую, но бэкенд с bundleMcp: true может получать инструменты Gateway через loopback-мост 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 поддерживает отдельный активный процесс Claude stdio для каждого сеанса 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 определяет действующий уровень усилий из собственной среды, настроек и значений модели по умолчанию. Для других бэкендов CLI владеющий ими плагин должен объявить эквивалентное преобразование argv, прежде чем /think начнёт влиять на запускаемый CLI.

Прежде чем 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 используют обвязку сервера приложений 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 запускают агента, который самостоятельно выполняет Compaction своей истории диалога, поэтому OpenClaw не должен запускать для них защитное суммирование — это конфликтует с собственной Compaction бэкенда и может привести к критическому сбою хода.

У claude-cli нет конечной точки обвязки (Claude Code выполняет Compaction внутри), поэтому он объявляет ownsNativeCompaction: true, а путь Compaction OpenClaw возвращает запись сеанса без изменений. OpenClaw передаёт фактический бюджет контекста запуска через документированную переменную Claude Code CLAUDE_CODE_AUTO_COMPACT_WINDOW, поддерживая согласованность собственной автоматической Compaction с настроенными ограничениями Anthropic contextTokens. Сеансы с собственной обвязкой, например 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 на loopback-интерфейсе, который предоставляет процессу 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
• Локальные модели