> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI-бэкенды

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

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

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

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

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw agent --message "hi" --model claude-cli/opus-4.6
```

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw agent --message "hi" --model codex-cli/gpt-5.3-codex
```

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
      },
    },
  },
}
```

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

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

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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`).
Идентификатор провайдера становится левой частью ссылки на модель:

```
<provider>/<model>
```

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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. **Формирует системный prompt** с использованием того же prompt OpenClaw + контекста рабочего пространства.
3. **Выполняет CLI** с идентификатором сеанса (если поддерживается), чтобы история оставалась согласованной.
4. **Разбирает вывод** (JSON или обычный текст) и возвращает финальный текст.
5. **Сохраняет идентификаторы сеансов** для каждого бэкенда, чтобы последующие запросы переиспользовали тот же сеанс CLI.

## Сеансы

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

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

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
imageArg: "--image",
imageMode: "repeat"
```

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

## Ввод / вывод

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

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

* `input: "arg"` (по умолчанию) передаёт prompt как последний аргумент CLI.
* `input: "stdin"` отправляет prompt через stdin.
* Если prompt очень длинный и задан `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 поддерживает пути к файлам).