Перейти к основному содержимому

Протоколы и API

CLI-бэкенды

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

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

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

Быстрый старт для новичков​

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

openclaw agent --message "hi" --model claude-cli/opus-4.6

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

openclaw agent --message "hi" --model codex-cli/gpt-5.4

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

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

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

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

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

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

Примечания:

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

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

Все CLI-бэкенды находятся в разделе:

agents.defaults.cliBackends

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

<провайдер>/<модель>

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

{
  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-6": "opus",
            "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", "--permission-mode", "bypassPermissions"]
  • resumeArgs: ["-p", "--output-format", "json", "--permission-mode", "bypassPermissions", "--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 для сопоставления провайдер/модель → модель CLI.
  • Нет непрерывности сессии: убедитесь, что sessionArg установлен и sessionMode не равен none (Codex CLI в настоящее время не может возобновить работу с JSON-выводом).
  • Изображения игнорируются: установите imageArg (и убедитесь, что CLI поддерживает пути к файлам).

API вызова инструментовЛокальные модели