Бекенди CLI

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• Інструменти OpenClaw не інʼєктуються напряму, але бекенди з bundleMcp: true можуть отримувати інструменти Gateway через міст local loopback MCP.
• Потокове передавання JSONL для CLI, які його підтримують.
• Сесії підтримуються (тому наступні звернення залишаються звʼязними).
• Зображення можна передавати далі, якщо CLI приймає шляхи до зображень.

​

Швидкий старт для початківців

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

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

​

Використання як резервного варіанта

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

• Якщо ви використовуєте agents.defaults.models (список дозволених), вам також потрібно включити туди моделі бекенда CLI.
• Якщо основний провайдер дає збій (автентифікація, ліміти запитів, тайм-аути), OpenClaw далі спробує бекенд CLI.

​

Огляд конфігурації

agents.defaults.cliBackends

<provider>/<model>

​

Приклад конфігурації

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "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. Вибирає бекенд на основі префікса провайдера (codex-cli/...).
2. Створює системний prompt з використанням того самого prompt OpenClaw і контексту робочої області.
3. Виконує CLI з ідентифікатором сесії (якщо підтримується), щоб історія залишалася узгодженою. Вбудований бекенд claude-cli підтримує процес Claude stdio активним для кожної сесії OpenClaw і надсилає наступні звернення через stream-json stdin.
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}), коли ID потрібно вставити в кілька прапорців.
• Якщо 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. Збережені ідентифікатори сесій перевіряються на наявність читабельного transcript проєкту перед відновленням, тому фантомні привʼязки очищаються з 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 усе одно утримує повторне засівання з необробленого transcript обмеженим і обмежує його безпечними інвалідаціями, як-от відсутні CLI transcript, зміни системного prompt/MCP або повторна спроба після session-expired; зміни профілю автентифікації чи епохи облікових даних ніколи не засівають повторно історію необробленого transcript.

• serialize: true зберігає порядок запусків в одній смузі.
• Більшість CLI серіалізуються в одній смузі провайдера.
• OpenClaw відкидає повторне використання збереженої сесії CLI, коли вибрана ідентичність автентифікації змінюється, включно зі зміненим ідентифікатором профілю автентифікації, статичним API key, статичним token або ідентичністю облікового запису OAuth, коли CLI її надає. Ротація access і refresh token OAuth не перериває збережену сесію CLI. Якщо CLI не надає стабільний ідентифікатор облікового запису OAuth, OpenClaw дозволяє цьому CLI самостійно забезпечувати дозволи resume.

​

Прелюдія резервного варіанта із сесій claude-cli

• Прелюдія надає перевагу найновішому підсумку /compact або маркеру compact_boundary, а потім додає найновіші звернення після межі в межах бюджету символів. Звернення до межі відкидаються, оскільки підсумок уже їх представляє.
• Блоки інструментів зводяться до компактних підказок (tool call: name) і (tool result: …), щоб чесно дотримуватися бюджету prompt. Підсумок позначається (truncated), якщо він переповнюється.
• Резервні переходи з claude-cli на claude-cli у межах того самого провайдера покладаються на власний --resume Claude і пропускають прелюдію.
• Засівання повторно використовує наявну перевірку шляху до файлу сесії Claude, тому довільні шляхи не можуть бути прочитані.

​

Зображення (наскрізне передавання)

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

​

Входи / виходи

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

• input: "arg" (типово) передає prompt як останній аргумент CLI.
• input: "stdin" надсилає prompt через stdin.
• Якщо prompt дуже довгий і maxPromptArgChars задано, використовується stdin.

​

Значення за замовчуванням (належать plugin)

• command: "codex"
• args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
• resumeArgs: ["exec","resume","{sessionId}","-c","sandbox_mode=\"workspace-write\"","--skip-git-repo-check"]
• output: "jsonl"
• resumeOutput: "text"
• modelArg: "--model"
• imageArg: "--image"
• sessionMode: "existing"

• command: "gemini"
• args: ["--output-format", "json", "--prompt", "{prompt}"]
• resumeArgs: ["--resume", "{sessionId}", "--output-format", "json", "--prompt", "{prompt}"]
• imageArg: "@"
• imagePathScope: "workspace"
• modelArg: "--model"
• sessionMode: "existing"
• sessionIdFields: ["session_id", "sessionId"]

• Текст відповіді зчитується з поля JSON response.
• Якщо usage відсутнє або порожнє, використовується запасний варіант stats.
• stats.cached нормалізується в OpenClaw cacheRead.
• Якщо 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" },
  ],
});

​

Накладення пакетного MCP

• claude-cli: згенерований суворий файл конфігурації MCP
• codex-cli: вбудовані перевизначення конфігурації для mcp_servers; згенерований сервер loopback OpenClaw позначається режимом схвалення інструментів для кожного сервера Codex, щоб виклики MCP не могли зупинятися на локальних запитах схвалення
• google-gemini-cli: згенерований файл системних налаштувань Gemini

• запускає loopback HTTP MCP-сервер, який надає інструменти Gateway процесу CLI
• автентифікує міст токеном для кожного сеансу (OPENCLAW_MCP_TOKEN)
• обмежує доступ до інструментів контекстом поточного сеансу, облікового запису та каналу
• завантажує ввімкнені сервери пакетного MCP для поточного робочого простору
• об’єднує їх з будь-якою наявною формою конфігурації/налаштувань MCP бекенда
• переписує конфігурацію запуску, використовуючи режим інтеграції, яким володіє бекенд, із власницького розширення

​

Обмеження

• Без прямих викликів інструментів OpenClaw. OpenClaw не вставляє виклики інструментів у протокол бекенда CLI. Бекенди бачать інструменти Gateway лише тоді, коли вмикають bundleMcp: true.
• Потокове передавання залежить від бекенда. Деякі бекенди потоково передають JSONL; інші буферизують до завершення.
• Структуровані виводи залежать від формату JSON CLI.
• Сеанси Codex CLI відновлюються через текстовий вивід (без JSONL), який менш структурований, ніж початковий запуск із --json. Сеанси OpenClaw все одно працюють звичайно.

​

Усунення несправностей

• CLI не знайдено: задайте для command повний шлях.
• Неправильна назва моделі: використовуйте modelAliases, щоб зіставити provider/model → модель CLI.
• Немає безперервності сеансу: переконайтеся, що sessionArg задано, а sessionMode не є none (Codex CLI наразі не може відновлюватися з JSON-виводом).
• Зображення ігноруються: задайте imageArg (і перевірте, що CLI підтримує шляхи до файлів).

​

Пов’язане

• Посібник з експлуатації Gateway
• Локальні моделі