Бэкенды 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 поддерживает отдельный процесс 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. Настройки agents.list[].tools.exec конкретного агента переопределяют глобальные tools.exec для этого агента. Необработанные аргументы бэкенда всё ещё могут содержать --permission-mode, но при запуске активных сессий Claude этот флаг нормализуется в соответствии с действующей политикой.

Бэкенд также сопоставляет уровни /think OpenClaw со встроенным флагом --effort Claude Code: minimal/low -> low, medium -> medium, а high/xhigh/max передаются напрямую. 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 запускают агента, который самостоятельно выполняет 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 на петлевом интерфейсе, который предоставляет инструменты Gateway процессу CLI и аутентифицируется разрешением контекста для каждого запуска (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
• Локальные модели