Конфігурація — агенти

Ключі конфігурації рівня агента в agents.*, multiAgent.*, session.*, messages.* і talk.*. Відомості про канали, інструменти, середовище виконання Gateway та інші ключі верхнього рівня див. у довіднику з конфігурації.

Типові параметри агента

agents.defaults.workspace

Типове значення: OPENCLAW_WORKSPACE_DIR, якщо його задано, інакше ~/.openclaw/workspace (або ~/.openclaw/workspace-<profile>, якщо для OPENCLAW_PROFILE задано профіль, відмінний від типового).

{  agents: { defaults: { workspace: "~/.openclaw/workspace" } },}

Явне значення agents.defaults.workspace має пріоритет над OPENCLAW_WORKSPACE_DIR. Використовуйте змінну середовища, щоб спрямувати типових агентів до змонтованого робочого простору, якщо не потрібно записувати цей шлях у конфігурацію.

agents.defaults.repoRoot

Необов’язковий корінь репозиторію, що відображається в рядку Runtime системного запиту. Якщо не задано, OpenClaw автоматично визначає його, рухаючись угору від робочого простору.

{  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },}

agents.defaults.skills

Необов’язковий типовий список дозволених Skills для агентів, які не задають agents.list[].skills.

{  agents: {    defaults: { skills: ["github", "weather"] },    list: [      { id: "writer" }, // успадковує github, weather      { id: "docs", skills: ["docs-search"] }, // замінює типові значення      { id: "locked-down", skills: [] }, // без Skills    ],  },}

• Не вказуйте agents.defaults.skills, щоб Skills за замовчуванням не мали обмежень.
• Не вказуйте agents.list[].skills, щоб успадкувати типові значення.
• Задайте agents.list[].skills: [], щоб вимкнути всі Skills.
• Непорожній список agents.list[].skills є остаточним набором для цього агента; він не об’єднується з типовими значеннями.

agents.defaults.skipBootstrap

Вимикає автоматичне створення початкових файлів робочого простору (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md).

{  agents: { defaults: { skipBootstrap: true } },}

agents.defaults.skipOptionalBootstrapFiles

Пропускає створення вибраних необов’язкових файлів робочого простору, але продовжує записувати обов’язкові початкові файли (AGENTS.md, TOOLS.md, BOOTSTRAP.md). Допустимі значення: SOUL.md, USER.md, HEARTBEAT.md і IDENTITY.md.

{  agents: {    defaults: {      skipOptionalBootstrapFiles: ["SOUL.md", "USER.md"],    },  },}

agents.defaults.contextInjection

Керує тим, коли початкові файли робочого простору додаються до системного запиту. Типове значення: "always".

• "continuation-skip": під час безпечних ходів продовження (після завершеної відповіді асистента) повторне додавання початкових файлів робочого простору пропускається, що зменшує розмір запиту. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст.
• "never": вимикає додавання початкових файлів робочого простору та контекстних файлів під час кожного ходу. Використовуйте це лише для агентів, які повністю керують життєвим циклом свого запиту (власні рушії контексту, нативні середовища виконання, які самостійно формують контекст, або спеціалізовані робочі процеси без початкового завантаження). Ходи Heartbeat і відновлення після Compaction також пропускають додавання.

{  agents: { defaults: { contextInjection: "continuation-skip" } },}

Перевизначення для окремого агента: agents.list[].contextInjection. Пропущені значення успадковують agents.defaults.contextInjection.

agents.defaults.bootstrapMaxChars

Максимальна кількість символів у кожному початковому файлі робочого простору до скорочення. Типове значення: 20000.

{  agents: { defaults: { bootstrapMaxChars: 20000 } },}

Перевизначення для окремого агента: agents.list[].bootstrapMaxChars. Пропущені значення успадковують agents.defaults.bootstrapMaxChars.

agents.defaults.bootstrapTotalMaxChars

Максимальна загальна кількість символів, доданих з усіх початкових файлів робочого простору. Типове значення: 60000.

{  agents: { defaults: { bootstrapTotalMaxChars: 60000 } },}

Перевизначення для окремого агента: agents.list[].bootstrapTotalMaxChars. Пропущені значення успадковують agents.defaults.bootstrapTotalMaxChars.

Перевизначення профілю початкового завантаження для окремих агентів

Використовуйте перевизначення профілю початкового завантаження для окремого агента, якщо одному агенту потрібна інша поведінка додавання до запиту, ніж передбачено спільними типовими параметрами. Пропущені поля успадковуються з agents.defaults.

{  agents: {    defaults: {      contextInjection: "continuation-skip",      bootstrapMaxChars: 20000,      bootstrapTotalMaxChars: 60000,    },    list: [      {        id: "strict-worker",        contextInjection: "always",        bootstrapMaxChars: 50000,        bootstrapTotalMaxChars: 300000,      },    ],  },}

agents.defaults.bootstrapPromptTruncationWarning

Керує видимим для агента сповіщенням у системному запиті, коли початковий контекст скорочено. Типове значення: "always".

• "off": ніколи не додає текст сповіщення про скорочення до системного запиту.
• "once": додає стислий текст сповіщення один раз для кожної унікальної сигнатури скорочення.
• "always": додає стисле сповіщення під час кожного запуску, коли є скорочення (рекомендовано).

Докладні необроблені та додані кількості й поля налаштування конфігурації залишаються в діагностичних даних, як-от звіти про контекст і стан та журнали; звичайний контекст користувача й середовища виконання WebChat отримує лише стисле сповіщення про відновлення.

{  agents: { defaults: { bootstrapPromptTruncationWarning: "always" } }, // off | once | always}

Карта власників бюджету контексту

OpenClaw має кілька великооб’ємних бюджетів запиту й контексту, і їх навмисно розподілено між підсистемами, а не спрямовано через один універсальний параметр.

Відповідні перевизначення для окремих агентів:

• agents.list[].skillsLimits.maxSkillsPromptChars
• agents.list[].contextInjection
• agents.list[].bootstrapMaxChars
• agents.list[].bootstrapTotalMaxChars
• agents.list[].contextLimits.*

agents.defaults.startupContext

Керує преамбулою першого ходу під час запуску, що додається до запусків моделі під час скидання або запуску. Команди простого чату /new і /reset підтверджують скидання без виклику моделі, тому вони не завантажують цю преамбулу.

{  agents: {    defaults: {      startupContext: {        enabled: true,        applyOn: ["new", "reset"],        dailyMemoryDays: 2,        maxFileBytes: 16384,        maxFileChars: 1200,        maxTotalChars: 2800,      },    },  },}

agents.defaults.contextLimits

Спільні типові параметри для обмежених поверхонь контексту середовища виконання.

{  agents: {    defaults: {      contextLimits: {        memoryGetMaxChars: 12000,        memoryGetDefaultLines: 120,        postCompactionMaxChars: 1800,      },    },  },}

• memoryGetMaxChars: типовий ліміт фрагмента memory_get до додавання метаданих скорочення та сповіщення про продовження.
• memoryGetDefaultLines: типове вікно рядків memory_get, коли lines не вказано.
• toolResultMaxChars: розширена гранична межа результату інструмента під час роботи, що використовується для збережених результатів і відновлення після переповнення. Не задавайте її, щоб використовувати автоматичний ліміт контексту моделі: 16000 символів за менш ніж 100K токенів, 32000 символів за 100K+ токенів і 64000 символів за 200K+ токенів. Для моделей із довгим контекстом приймаються явні значення до 1000000, але фактичний ліміт усе одно обмежено приблизно 30% вікна контексту моделі. openclaw doctor --deep виводить фактичний ліміт, а doctor попереджає лише тоді, коли явне перевизначення застаріло або не має ефекту.
• postCompactionMaxChars: ліміт фрагмента AGENTS.md, що використовується під час додавання оновленого контексту після Compaction.

agents.list[].contextLimits

Перевизначення для окремого агента спільних параметрів contextLimits. Пропущені поля успадковуються з agents.defaults.contextLimits.

{  agents: {    defaults: {      contextLimits: { memoryGetMaxChars: 12000 },    },    list: [      {        id: "tiny-local",        contextLimits: {          memoryGetMaxChars: 6000,          toolResultMaxChars: 8000, // розширена гранична межа для цього агента        },      },    ],  },}

skills.limits.maxSkillsPromptChars

Глобальний ліміт компактного списку Skills, що додається до системного запиту. Це не впливає на читання файлів SKILL.md за запитом.

{  skills: { limits: { maxSkillsPromptChars: 18000 } },}

agents.list[].skillsLimits.maxSkillsPromptChars

Перевизначення бюджету запиту Skills для окремого агента.

{  agents: {    list: [{ id: "tiny-local", skillsLimits: { maxSkillsPromptChars: 6000 } }],  },}

agents.defaults.imageMaxDimensionPx

Максимальний розмір найдовшої сторони зображення в пікселях у блоках зображень транскрипту або інструмента перед викликами постачальника. Типове значення: 1200.

Менші значення зазвичай зменшують використання токенів зору та розмір корисного навантаження запиту для запусків із великою кількістю знімків екрана. Більші значення зберігають більше візуальних деталей.

{  agents: { defaults: { imageMaxDimensionPx: 1200 } },}

agents.defaults.imageQuality

Налаштування стиснення й деталізації інструмента зображень для зображень, завантажених зі шляхів до файлів, URL-адрес і посилань на медіафайли. Типове значення: auto.

OpenClaw адаптує послідовність зміни розміру до вибраної моделі зображень. Наприклад, Claude Opus 4.8, OpenAI GPT-5.6 Sol, Qwen VL і розміщені моделі зору Llama 4 можуть використовувати більші зображення, ніж старіші або типові шляхи зору з високою деталізацією, тоді як ходи з кількома зображеннями стискаються агресивніше в режимі auto, щоб контролювати витрати токенів і затримку.

Значення:

• auto: адаптація до обмежень моделі та кількості зображень.
• efficient: перевага меншим зображенням для зниження використання токенів і байтів.
• balanced: використання стандартної збалансованої послідовності.
• high: збереження більшої деталізації для знімків екрана, діаграм і зображень документів.

{  agents: { defaults: { imageQuality: "auto" } },}

agents.defaults.userTimezone

Часовий пояс для контексту системного запиту (не для часових позначок повідомлень). Якщо не задано, використовується часовий пояс хоста.

{  agents: { defaults: { userTimezone: "America/Chicago" } },}

agents.defaults.timeFormat

Формат часу в системному запиті. Типове значення: auto (налаштування ОС).

{  agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24}

agents.defaults.model

{  agents: {    defaults: {      models: {        "anthropic/claude-opus-4-6": { alias: "opus" },        "minimax/MiniMax-M2.7": { alias: "minimax" },      },      model: {        primary: "anthropic/claude-opus-4-6",        fallbacks: ["minimax/MiniMax-M2.7"],      },      utilityModel: "openai/gpt-5.4-mini",      imageModel: {        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],      },      imageGenerationModel: {        primary: "openai/gpt-image-2",        fallbacks: ["google/gemini-3.1-flash-image-preview"],      },      videoGenerationModel: {        primary: "qwen/wan2.6-t2v",        fallbacks: ["qwen/wan2.6-i2v"],      },      pdfModel: {        primary: "anthropic/claude-opus-4-6",        fallbacks: ["openai/gpt-5.4-mini"],      },      params: { cacheRetention: "long" }, // глобальні параметри постачальника за замовчуванням      pdfMaxBytesMb: 10,      pdfMaxPages: 20,      thinkingDefault: "low",      verboseDefault: "off",      toolProgressDetail: "explain",      reasoningDefault: "off",      elevatedDefault: "on",      timeoutSeconds: 600,      mediaMaxMb: 5,      contextTokens: 200000,      maxConcurrent: 4,    },  },}

• model: приймає рядок ("provider/model") або об’єкт ({ primary, fallbacks }).
  • Рядкова форма задає лише основну модель.
  • Об’єктна форма задає основну модель та впорядкований список резервних моделей.
• utilityModel: необов’язкове посилання provider/model або псевдонім для коротких внутрішніх завдань. Наразі використовується для створення заголовків сеансів Control UI, тем приватних повідомлень Telegram, автоматичних гілок Discord і текстового опису чернеток перебігу виконання. Якщо значення не задано, OpenClaw використовує оголошену основним провайдером типову малу модель, якщо вона існує (OpenAI → gpt-5.6-luna, Anthropic → claude-haiku-4-5); інакше завдання створення заголовків використовують основну модель агента, а текстовий опис залишається вимкненим. Установіть utilityModel: "", щоб повністю вимкнути маршрутизацію службових завдань. agents.list[].utilityModel перевизначає типове значення (порожнє значення для окремого агента вимикає цю функцію для нього), а перевизначення моделі для конкретної операції має вищий пріоритет за обидва. Службові завдання виконують окремі виклики моделі й надсилають вибраному провайдеру моделі вміст, призначений для конкретного завдання. Для створення заголовка панелі керування надсилаються щонайбільше перші 1 000 символів першого повідомлення, яке не є командою; для текстового опису надсилається вхідний запит разом зі стислими знеособленими підсумками інструментів. Виберіть провайдера, який відповідає вашим вимогам щодо вартості й обробки даних.
• imageModel: приймає рядок ("provider/model") або об’єкт ({ primary, fallbacks }).
  • Використовується шляхом інструмента image як конфігурація моделі комп’ютерного зору, коли активна модель не може приймати зображення. Натомість моделі з вбудованою підтримкою зору безпосередньо отримують завантажені байти зображення.
  • Також використовується для резервної маршрутизації, коли вибрана або типова модель не може приймати зображення.
  • Надавайте перевагу явним посиланням provider/model. Для сумісності приймаються ідентифікатори без префікса; якщо такий ідентифікатор однозначно відповідає налаштованому запису з підтримкою зображень у models.providers.*.models, OpenClaw додає до нього цього провайдера. За наявності кількох відповідних налаштованих записів потрібно явно вказати префікс провайдера.
• imageGenerationModel: приймає рядок ("provider/model") або об’єкт ({ primary, fallbacks }).
  • Використовується спільною можливістю генерування зображень і будь-якою майбутньою поверхнею інструмента або Plugin, що генерує зображення.
  • Типові значення: google/gemini-3.1-flash-image-preview для вбудованого генерування зображень Gemini, fal/fal-ai/flux/dev для fal, openai/gpt-image-2 для OpenAI Images або openai/gpt-image-1.5 для виведення OpenAI у форматі PNG/WebP із прозорим тлом.
  • Якщо провайдера або модель вибрано безпосередньо, також налаштуйте відповідну автентифікацію провайдера (наприклад, GEMINI_API_KEY або GOOGLE_API_KEY для google/*, OPENAI_API_KEY або OpenAI Codex OAuth для openai/gpt-image-2 / openai/gpt-image-1.5, FAL_KEY для fal/*).
  • Якщо значення не задано, image_generate усе одно може визначити типовий варіант провайдера з налаштованою автентифікацією. Спочатку перевіряється поточний типовий провайдер, а потім решта зареєстрованих провайдерів генерування зображень у порядку їхніх ідентифікаторів.
• musicGenerationModel: приймає рядок ("provider/model") або об’єкт ({ primary, fallbacks }).
  • Використовується спільною можливістю генерування музики та вбудованим інструментом music_generate.
  • Типові значення: google/lyria-3-clip-preview, google/lyria-3-pro-preview або minimax/music-2.6.
  • Якщо значення не задано, music_generate усе одно може визначити типовий варіант провайдера з налаштованою автентифікацією. Спочатку перевіряється поточний типовий провайдер, а потім решта зареєстрованих провайдерів генерування музики в порядку їхніх ідентифікаторів.
  • Якщо провайдера або модель вибрано безпосередньо, також налаштуйте відповідну автентифікацію або ключ API провайдера.
• videoGenerationModel: приймає рядок ("provider/model") або об’єкт ({ primary, fallbacks }).
  • Використовується спільною можливістю генерування відео та вбудованим інструментом video_generate.
  • Типові значення: qwen/wan2.6-t2v, qwen/wan2.6-i2v, qwen/wan2.6-r2v, qwen/wan2.6-r2v-flash або qwen/wan2.7-r2v.
  • Якщо значення не задано, video_generate усе одно може визначити типовий варіант провайдера з налаштованою автентифікацією. Спочатку перевіряється поточний типовий провайдер, а потім решта зареєстрованих провайдерів генерування відео в порядку їхніх ідентифікаторів.
  • Якщо провайдера або модель вибрано безпосередньо, також налаштуйте відповідну автентифікацію або ключ API провайдера.
  • Офіційний Plugin Qwen для генерування відео підтримує щонайбільше 1 вихідне відео, 1 вхідне зображення, 4 вхідні відео, тривалість 10 секунд і параметри рівня провайдера size, aspectRatio, resolution, audio та watermark.
• pdfModel: приймає рядок ("provider/model") або об’єкт ({ primary, fallbacks }).
  • Використовується інструментом pdf для маршрутизації моделі.
  • Якщо значення не задано, інструмент PDF спочатку використовує резервний варіант imageModel, а потім визначену модель сеансу або типову модель.
• pdfMaxBytesMb: типове обмеження розміру PDF для інструмента pdf, коли під час виклику не передано maxBytesMb.
• pdfMaxPages: типова максимальна кількість сторінок, які враховує резервний режим видобування в інструменті pdf.
• verboseDefault: типовий рівень докладності для агентів. Значення: "off", "on", "full". Типове значення: "off".
• toolProgressDetail: режим деталізації для підсумків інструмента /verbose і рядків інструментів у чернетках перебігу виконання. Значення: "explain" (типове, стислі зрозумілі назви) або "raw" (додавати необроблену команду або подробиці, коли вони доступні). Значення agents.list[].toolProgressDetail для окремого агента перевизначає це типове значення.
• reasoningDefault: типова видимість міркувань для агентів. Значення: "off", "on", "stream". Значення agents.list[].reasoningDefault для окремого агента перевизначає це типове значення. Налаштовані типові значення міркувань застосовуються лише для власників, авторизованих відправників або контекстів Gateway з правами адміністратора оператора, якщо не задано перевизначення міркувань для окремого повідомлення чи сеансу.
• elevatedDefault: типовий рівень розширеного виведення для агентів. Значення: "off", "on", "ask", "full". Типове значення: "on".
• model.primary: формат provider/model (наприклад, openai/gpt-5.6-sol для доступу через Codex OAuth). Якщо провайдера не вказано, OpenClaw спочатку перевіряє псевдонім, потім однозначний збіг серед налаштованих провайдерів для точного ідентифікатора моделі й лише після цього використовує налаштованого типового провайдера (застаріла поведінка сумісності, тому надавайте перевагу явному provider/model). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw використовує першу налаштовану пару провайдера й моделі замість повідомлення про застаріле типове значення видаленого провайдера.
• models: налаштований каталог моделей і список дозволених моделей для /model. Кожен запис може містити alias (скорочення) і params (специфічне для провайдера, наприклад temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold, маршрутизацію OpenRouter provider, chat_template_kwargs, extra_body/extraBody).
  • Використовуйте записи provider/*, як-от "openai/*": {} або "vllm/*": {}, щоб показати всі виявлені моделі вибраних провайдерів без ручного переліку кожного ідентифікатора моделі.
  • Додайте agentRuntime до запису provider/*, якщо всі динамічно виявлені моделі цього провайдера мають використовувати одне середовище виконання. Точна політика середовища виконання provider/model усе одно має вищий пріоритет за шаблон.
  • Безпечне редагування: використовуйте openclaw config set agents.defaults.models '<json>' --strict-json --merge, щоб додавати записи. config set відхиляє заміни, які видалили б наявні записи зі списку дозволених, якщо не передано --replace.
  • Процеси налаштування та початкового конфігурування для окремих провайдерів об’єднують вибрані моделі провайдера з цією мапою та зберігають уже налаштованих непов’язаних провайдерів.
  • Для безпосередніх моделей OpenAI Responses серверна Compaction вмикається автоматично. Використовуйте params.responsesServerCompaction: false, щоб припинити додавання context_management, або params.responsesCompactThreshold, щоб перевизначити порогове значення. Див. серверну Compaction OpenAI.
• params: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в agents.defaults.params (наприклад, { cacheRetention: "long" }).
• Пріоритет об’єднання params (конфігурація): agents.defaults.params (глобальна основа) перевизначається agents.defaults.models["provider/model"].params (для окремої моделі), після чого agents.list[].params (відповідний ідентифікатор агента) перевизначає значення за ключем. Докладніше див. у розділі Кешування запитів.
• models.providers.openrouter.params.provider: загальна для OpenRouter типова політика маршрутизації провайдерів. OpenClaw передає її в об’єкт provider запиту OpenRouter; agents.defaults.models["openrouter/<model>"].params.provider для окремої моделі та параметри агента перевизначають значення за ключем. Див. маршрутизацію провайдерів OpenRouter.
• params.extra_body/params.extraBody: розширений наскрізний JSON, який об’єднується з тілами запитів api: "openai-completions" для проксі, сумісних з OpenAI. У разі конфлікту зі згенерованими ключами запиту додаткове тіло має вищий пріоритет; маршрути доповнення, відмінні від нативних, усе одно після цього вилучають store, призначені лише для OpenAI.
• params.chat_template_kwargs: аргументи шаблону чату, сумісні з vLLM/OpenAI, що об’єднуються з тілами запитів верхнього рівня api: "openai-completions". Для vllm/nemotron-3-* з вимкненим міркуванням вбудований Plugin vLLM автоматично надсилає enable_thinking: false та force_nonempty_content: true; явні chat_template_kwargs перевизначають згенеровані типові значення, а extra_body.chat_template_kwargs усе одно має остаточний пріоритет. Налаштовані моделі міркувань vLLM Qwen і Nemotron надають двійкові варіанти /think (off, on) замість багаторівневої шкали інтенсивності.
• compat.thinkingFormat: стиль корисного навантаження міркувань, сумісний з OpenAI. Використовуйте "together" для reasoning.enabled у стилі Together, "qwen" для верхньорівневого enable_thinking у стилі Qwen або "qwen-chat-template" для chat_template_kwargs.enable_thinking у серверних реалізаціях сімейства Qwen, які підтримують аргументи шаблону чату на рівні запиту, як-от vLLM. OpenClaw зіставляє вимкнене міркування з false, а ввімкнене — з true; налаштовані моделі vLLM Qwen надають двійкові варіанти /think для цих форматів.
• compat.supportedReasoningEfforts: список рівнів інтенсивності міркувань для окремої моделі, сумісний з OpenAI. Додайте "xhigh" для власних кінцевих точок, які справді його приймають; після цього OpenClaw надає /think xhigh у меню команд, рядках сеансів Gateway, перевірці виправлень сеансів, перевірці CLI агента та перевірці llm-task для цієї налаштованої пари провайдера й моделі. Використовуйте compat.reasoningEffortMap, якщо серверній реалізації потрібне специфічне для провайдера значення канонічного рівня.
• params.preserveThinking: доступна лише для Z.AI явна згода на збереження міркувань. Коли її ввімкнено разом із міркуванням, OpenClaw надсилає thinking.clear_thinking: false і повторно відтворює попередні reasoning_content; див. міркування та збереження міркувань Z.AI.
• localService: необов’язковий диспетчер процесів на рівні провайдера для локальних або самостійно розгорнутих серверів моделей. Коли вибрана модель належить цьому провайдеру, OpenClaw перевіряє healthUrl (або baseUrl + "/models"), запускає command із args, якщо кінцева точка недоступна, очікує до readyTimeoutMs, а потім надсилає запит моделі. command має бути абсолютним шляхом. idleStopMs: 0 підтримує процес активним до завершення роботи OpenClaw; додатне значення зупиняє запущений OpenClaw процес після вказаної кількості мілісекунд бездіяльності. Див. Локальні служби моделей.
• Політика середовища виконання має належати провайдерам або моделям, а не agents.defaults. Використовуйте models.providers.<provider>.agentRuntime для правил на рівні провайдера або agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime для правил певної моделі. Сам по собі префікс провайдера/моделі ніколи не вибирає інструментарій. Якщо середовище виконання не задано або має значення auto, OpenAI може неявно вибрати Codex лише для точного офіційного маршруту HTTPS Platform Responses або ChatGPT Responses без заданого автором перевизначення запиту. Див. Неявне агентне середовище виконання OpenAI.
• Засоби запису конфігурації, які змінюють ці поля (наприклад, /models set, /models set-image і команди додавання/видалення резервних варіантів), зберігають канонічну об’єктну форму та, коли можливо, наявні списки резервних варіантів.
• maxConcurrent: максимальна кількість паралельних запусків агентів у різних сеансах (у межах кожного сеансу запуски й надалі виконуються послідовно). Типове значення: 4.

Політика середовища виконання

{  models: {    providers: {      openai: {        agentRuntime: { id: "codex" },      },    },  },  agents: {    defaults: {      model: "openai/gpt-5.6-sol",      models: {        "anthropic/claude-opus-4-8": {          agentRuntime: { id: "claude-cli" },        },        "vllm/*": {          agentRuntime: { id: "openclaw" },        },      },    },  },}

• id: "auto", "openclaw", ідентифікатор зареєстрованої оболонки Plugin або підтримуваний псевдонім бекенду CLI. Вбудований Plugin Codex реєструє codex; вбудований Plugin Anthropic надає бекенд CLI claude-cli.
• id: "auto" дає зареєстрованим оболонкам Plugin змогу обробляти фактичні маршрути, які оголошують або іншим чином задовольняють їхній контракт підтримки, і використовує OpenClaw, якщо жодна оболонка не відповідає. Явно задане середовище виконання Plugin, як-от id: "codex", вимагає наявності цієї оболонки та сумісного фактичного маршруту; воно безпечно завершується помилкою, якщо будь-що з них недоступне або якщо виконання завершується невдало.
• id: "pi" приймається лише як застарілий псевдонім для openclaw, щоб зберегти сумісність із випущеними конфігураціями версії v2026.5.22 і раніших. У новій конфігурації слід використовувати openclaw.
• Пріоритет середовища виконання: спочатку точна політика моделі (agents.list[].models["provider/model"], agents.defaults.models["provider/model"] або models.providers.<provider>.models[]), потім agents.list[] / agents.defaults.models["provider/*"], а далі загальна політика провайдера в models.providers.<provider>.agentRuntime.
• Ключі середовища виконання для всього агента є застарілими. agents.defaults.agentRuntime, agents.list[].agentRuntime, закріплення середовища виконання сеансу та OPENCLAW_AGENT_RUNTIME ігноруються під час вибору середовища виконання. Запустіть openclaw doctor --fix, щоб видалити застарілі значення.
• Відповідні точні офіційні HTTPS-маршрути OpenAI Responses/ChatGPT без явно заданого перевизначення запиту можуть неявно використовувати оболонку Codex. agentRuntime.id: "codex" провайдера/моделі робить Codex обов’язковою вимогою з безпечним завершенням помилкою, але не робить несумісний маршрут сумісним.
• Для розгортань Claude CLI рекомендовано використовувати model: "anthropic/claude-opus-4-8" разом із agentRuntime.id: "claude-cli", обмеженим областю моделі. Застарілі посилання claude-cli/<model> усе ще працюють для сумісності, але нова конфігурація має зберігати канонічний вибір провайдера/моделі та визначати бекенд виконання в політиці середовища виконання провайдера/моделі.
• Це керує лише виконанням текстових ходів агента. Генерування медіафайлів, обробка зображень, PDF, музики, відео та TTS і надалі використовують відповідні налаштування провайдера/моделі.

Вбудовані скорочені псевдоніми (застосовуються лише тоді, коли модель міститься в agents.defaults.models):

Налаштовані псевдоніми завжди мають пріоритет над типовими значеннями.

Моделі Z.AI GLM-4.x автоматично вмикають режим міркування, якщо не встановлено --thinking off або не визначено agents.defaults.models["zai/<model>"].params.thinking самостійно. Моделі Z.AI типово вмикають tool_stream для потокового передавання викликів інструментів. Установіть для agents.defaults.models["zai/<model>"].params.tool_stream значення false, щоб вимкнути його. Для Anthropic Claude Opus 4.8 міркування в OpenClaw типово вимкнене; коли адаптивне міркування явно ввімкнене, типовим рівнем зусиль, що визначається провайдером Anthropic, є high. Для моделей Claude 4.6 типовим значенням є adaptive, якщо рівень міркування явно не задано.

agents.defaults.cliBackends

Необов’язкові бекенди CLI для резервних запусків лише з текстом (без викликів інструментів). Корисні як резервний варіант у разі відмови провайдерів API.

{  agents: {    defaults: {      cliBackends: {        "claude-cli": {          command: "/opt/homebrew/bin/claude",        },        "my-cli": {          command: "my-cli",          args: ["--json"],          output: "json",          modelArg: "--model",          sessionArg: "--session",          sessionMode: "existing",          systemPromptArg: "--system",          // Або використовуйте systemPromptFileArg, коли CLI приймає прапорець файлу запиту.          systemPromptWhen: "first",          imageArg: "--image",          imageMode: "repeat",        },      },    },  },}

• Бекенди CLI орієнтовані насамперед на текст; інструменти завжди вимкнені.
• Сеанси підтримуються, коли встановлено sessionArg.
• Наскрізне передавання зображень підтримується, коли imageArg приймає шляхи до файлів.
• reseedFromRawTranscriptWhenUncompacted: true дає бекенду змогу безпечно відновлювати недійсні сеанси з обмеженого необробленого хвоста стенограми OpenClaw до появи першого підсумку Compaction. Зміни профілю автентифікації або епохи облікових даних усе одно ніколи не спричиняють повторне заповнення необробленими даними.

agents.defaults.promptOverlays

Незалежні від провайдера накладки запитів, які застосовуються за сімейством моделей до поверхонь запитів, сформованих OpenClaw. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки в маршрутах OpenClaw/провайдера; personality керує лише шаром дружнього стилю взаємодії. Нативні маршрути сервера застосунку Codex зберігають базові інструкції та інструкції моделі, що належать Codex, замість цієї накладки GPT-5 від OpenClaw, а OpenClaw вимикає вбудовану особистість Codex для нативних гілок.

{  agents: {    defaults: {      promptOverlays: {        gpt5: {          personality: "friendly", // friendly | on | off        },      },    },  },}

• "friendly" (типово) та "on" вмикають шар дружнього стилю взаємодії.
• "off" вимикає лише дружній шар; позначений контракт поведінки GPT-5 залишається ввімкненим.
• Застарілий plugins.entries.openai.config.personality усе ще зчитується, якщо це спільне налаштування не задано.

agents.defaults.heartbeat

Періодичні запуски Heartbeat.

{  agents: {    defaults: {      heartbeat: {        every: "30m", // 0m вимикає        model: "openai/gpt-5.4-mini",        includeReasoning: false,        includeSystemPromptSection: true, // типово: true; false вилучає розділ Heartbeat із системного запиту        lightContext: false, // типово: false; true залишає лише HEARTBEAT.md із файлів початкового завантаження робочого простору        isolatedSession: false, // типово: false; true запускає кожен Heartbeat у новому сеансі (без історії розмови)        skipWhenBusy: false, // типово: false; true також очікує завершення смуг субагентів/вкладених смуг цього агента        session: "main",        to: "+15555550123",        directPolicy: "allow", // allow (типово) | block        target: "none", // типово: none | варіанти: last | whatsapp | telegram | discord | ...        prompt: "Прочитай HEARTBEAT.md, якщо він існує...",        ackMaxChars: 300,        suppressToolErrorWarnings: false,        timeoutSeconds: 45,      },    },  },}

• every: рядок тривалості (ms/s/m/h). Типове значення: 30m (автентифікація ключем API) або 1h (автентифікація OAuth). Установіть 0m, щоб вимкнути.
• includeSystemPromptSection: якщо false, вилучає розділ Heartbeat із системного запиту та пропускає впровадження HEARTBEAT.md у контекст початкового завантаження. Типове значення: true.
• suppressToolErrorWarnings: якщо true, приховує корисні навантаження попереджень про помилки інструментів під час запусків Heartbeat.
• timeoutSeconds: максимальний дозволений час у секундах для ходу агента Heartbeat до його переривання. Залиште невстановленим, щоб використовувати agents.defaults.timeoutSeconds, якщо його задано, інакше — інтервал Heartbeat, обмежений 600 секундами.
• directPolicy: політика прямої доставки/доставки в особисті повідомлення. allow (типово) дозволяє доставку безпосередньому одержувачу. block пригнічує доставку безпосередньому одержувачу та створює reason=dm-blocked.
• lightContext: якщо true, запуски Heartbeat використовують полегшений контекст початкового завантаження та залишають лише HEARTBEAT.md із файлів початкового завантаження робочого простору.
• isolatedSession: якщо true, кожен Heartbeat запускається в новому сеансі без попередньої історії розмови. Та сама схема ізоляції, що й у Cron sessionTarget: "isolated". Зменшує витрати токенів на один Heartbeat із ~100K до ~2-5K токенів.
• skipWhenBusy: якщо true, запуски Heartbeat відкладаються, коли додаткові смуги цього агента зайняті: його власна прив’язана до ключа сеансу робота субагента або вкладеної команди. Смуги Cron завжди відкладають Heartbeat навіть без цього прапорця.
• Для кожного агента: установіть agents.list[].heartbeat. Якщо будь-який агент визначає heartbeat, Heartbeat запускають лише ці агенти.
• Heartbeat виконує повні ходи агента — коротші інтервали витрачають більше токенів.

agents.defaults.compaction

{  agents: {    defaults: {      compaction: {        mode: "safeguard", // default | safeguard        provider: "my-provider", // ідентифікатор зареєстрованого Plugin-провайдера Compaction (необов’язково)        timeoutSeconds: 180,        reserveTokensFloor: 24000,        keepRecentTokens: 50000,        recentTurnsPreserve: 3,        maxHistoryShare: 0.7,        identifierPolicy: "strict", // strict | off | custom        identifierInstructions: "Зберігай ідентифікатори розгортань, ідентифікатори заявок і пари хост:порт без змін.", // використовується, коли identifierPolicy=custom        qualityGuard: { enabled: true, maxRetries: 1 },        midTurnPrecheck: { enabled: false }, // необов’язкова перевірка навантаження циклу інструментів        postIndexSync: "async", // off | async | await        postCompactionSections: ["Session Startup", "Red Lines"], // явно вмикає повторне впровадження розділів AGENTS.md        model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для Compaction        truncateAfterCompaction: true, // після Compaction виконує ротацію до меншого наступного JSONL        maxActiveTranscriptBytes: "20mb", // необов’язковий тригер попередньої локальної Compaction        notifyUser: true, // сповіщення про початок/завершення Compaction і погіршення очищення пам’яті (типово: false)        memoryFlush: {          enabled: true,          model: "ollama/qwen3:8b", // необов’язкове перевизначення моделі лише для очищення пам’яті          softThresholdTokens: 6000,          forceFlushTranscriptBytes: "2mb",          systemPrompt: "Сеанс наближається до Compaction. Збережи довготривалі спогади зараз.",          prompt: "Запиши всі довготривалі нотатки до memory/YYYY-MM-DD.md; якщо зберігати нічого, дай відповідь точним беззвучним токеном NO_REPLY.",        },      },    },  },}

• mode: default або safeguard (порційне узагальнення для довгих історій). Див. Compaction.
• provider: ідентифікатор зареєстрованого плагіна постачальника Compaction. Якщо задано, замість вбудованого узагальнення за допомогою LLM викликається summarize() постачальника. У разі помилки використовується вбудований механізм. Задання постачальника примусово вмикає mode: "safeguard". Див. Compaction.
• timeoutSeconds: максимальна кількість секунд, відведена на одну операцію Compaction, після якої OpenClaw її перериває. Типове значення: 180.
• reserveTokens: резерв токенів, що залишається доступним для виведення моделі та майбутніх результатів інструментів після Compaction. Коли розмір контекстного вікна моделі відомий, OpenClaw обмежує фактичний резерв, щоб він не міг вичерпати бюджет запиту.
• reserveTokensFloor: мінімальний резерв, який забезпечує вбудоване середовище виконання. Задайте 0, щоб вимкнути нижню межу. Нижня межа й надалі підпорядковується активному обмеженню контекстного вікна.
• keepRecentTokens: бюджет точки відсікання агента для дослівного збереження найновішого хвоста транскрипту. Ручна /compact враховує його, якщо значення задано явно; інакше ручна Compaction є жорсткою контрольною точкою.
• recentTurnsPreserve: кількість найновіших реплік користувача й асистента, які зберігаються дослівно поза захисним узагальненням. Типове значення: 3.
• maxHistoryShare: максимальна частка загального бюджету контексту, дозволена для збереженої історії після Compaction (діапазон 0.1-0.9).
• identifierPolicy: strict (типове значення), off або custom. strict додає на початок вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час узагальнення Compaction.
• identifierInstructions: необов’язковий власний текст щодо збереження ідентифікаторів, який використовується, коли identifierPolicy=custom.
• qualityGuard: перевірки з повторною спробою в разі некоректно сформованого виведення для захисних узагальнень. Типово ввімкнено в захисному режимі; задайте enabled: false, щоб пропустити перевірку.
• midTurnPrecheck: необов’язкова перевірка навантаження циклу інструментів. Коли enabled: true, OpenClaw перевіряє заповнення контексту після додавання результатів інструментів і перед наступним викликом моделі. Якщо контекст більше не вміщується, система перериває поточну спробу до надсилання запиту й повторно використовує наявний шлях відновлення попередньої перевірки, щоб обрізати результати інструментів або виконати Compaction і повторити спробу. Працює з режимами Compaction default і safeguard. Типово вимкнено.
• postIndexSync: режим повторного індексування пам’яті сеансу після Compaction. Типове значення: "async". Використовуйте "await" для максимальної актуальності, "async" для меншої затримки Compaction або "off", лише коли синхронізація пам’яті сеансу виконується в іншому місці.
• postCompactionSections: необов’язкові назви розділів H2/H3 з AGENTS.md для повторного додавання після Compaction. Повторне додавання вимкнено, якщо значення не задано або задано як []. Явне задання ["Session Startup", "Red Lines"] вмикає цю пару та зберігає застарілий резервний механізм Every Session/Safety. Вмикайте це лише тоді, коли додатковий контекст виправдовує ризик дублювання настанов проєкту, уже відображених в узагальненні Compaction.
• model: необов’язковий provider/model-id або простий псевдонім із agents.defaults.models лише для узагальнення Compaction. Прості псевдоніми зіставляються до надсилання; налаштовані буквальні ідентифікатори моделей мають пріоритет у разі збігів. Використовуйте це, коли основний сеанс має працювати з однією моделлю, а узагальнення Compaction — з іншою; якщо значення не задано, Compaction використовує основну модель сеансу.
• truncateAfterCompaction: виконує ротацію активного транскрипту сеансу після Compaction, щоб майбутні репліки завантажували лише узагальнення та неузагальнений хвіст, а попередній повний транскрипт залишався в архіві. Запобігає необмеженому зростанню активного транскрипту в тривалих сеансах. Типове значення: false.
• maxActiveTranscriptBytes: необов’язковий поріг у байтах (number або рядки на кшталт "20mb"), який запускає звичайну локальну Compaction перед виконанням, коли історія транскрипту перевищує поріг. Потребує truncateAfterCompaction, щоб після успішної Compaction можна було виконати ротацію до меншого наступного транскрипту. Вимкнено, якщо значення не задано або задано як 0.
• notifyUser: коли true, надсилає користувачеві короткі сповіщення про обслуговування контексту: на початку й після завершення Compaction (наприклад, «Ущільнення контексту...» та «Ущільнення завершено»), а також коли вичерпано можливості скидання пам’яті перед Compaction і відповідь продовжується в обмеженому режимі (наприклад, «Тимчасово не вдалося виконати обслуговування пам’яті; відповідь буде продовжено.»). Типово вимкнено, щоб не показувати ці сповіщення.
• memoryFlush: безшумний агентний хід перед автоматичною Compaction для збереження довготривалої пам’яті. Задайте model як точного постачальника/модель, наприклад ollama/qwen3:8b, якщо цей службовий хід має залишатися на локальній моделі; перевизначення не успадковує активний ланцюжок резервних моделей сеансу. forceFlushTranscriptBytes примусово виконує скидання, коли розмір транскрипту досягає порога, навіть якщо лічильники токенів застаріли. Пропускається, коли робочий простір доступний лише для читання.

agents.defaults.runRetries

Межі ітерацій повторних спроб зовнішнього циклу виконання для вбудованого середовища виконання агента, які запобігають нескінченним циклам виконання під час відновлення після помилок. Цей параметр застосовується лише до вбудованого середовища виконання агента, а не до середовищ виконання ACP або CLI.

{  agents: {    defaults: {      runRetries: {        base: 24,        perProfile: 8,        min: 32,        max: 160,      },    },    list: [      {        id: "main",        runRetries: { max: 50 }, // необов’язкові перевизначення для окремого агента      },    ],  },}

• base: базова кількість ітерацій повторних спроб для зовнішнього циклу виконання. Типове значення: 24.
• perProfile: додаткові ітерації повторних спроб виконання, що надаються для кожного кандидата резервного профілю. Типове значення: 8.
• min: мінімальне абсолютне обмеження кількості ітерацій повторних спроб виконання. Типове значення: 32.
• max: максимальне абсолютне обмеження кількості ітерацій повторних спроб виконання для запобігання неконтрольованому виконанню. Типове значення: 160.

agents.defaults.contextPruning

Видаляє старі результати інструментів із контексту в пам’яті перед надсиланням до LLM. Не змінює історію сеансу на диску. Типово вимкнено; задайте mode: "cache-ttl", щоб увімкнути.

{  agents: {    defaults: {      contextPruning: {        mode: "cache-ttl", // off (типове значення) | cache-ttl        ttl: "1h", // тривалість (ms/s/m/h), типова одиниця: хвилини; типове значення: 5m        keepLastAssistants: 3,        softTrimRatio: 0.3,        hardClearRatio: 0.5,        minPrunableToolChars: 50000,        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },        hardClear: { enabled: true, placeholder: "[Вміст старого результату інструмента очищено]" },        tools: { deny: ["browser", "canvas"] },      },    },  },}

Докладніше про поведінку див. у розділі Очищення сеансу.

Блокове потокове передавання

{  agents: {    defaults: {      blockStreamingDefault: "off", // on | off      blockStreamingBreak: "text_end", // text_end | message_end      blockStreamingChunk: { minChars: 800, maxChars: 1200, breakPreference: "paragraph" },      blockStreamingCoalesce: { idleMs: 1000 },      humanDelay: { mode: "natural" }, // off (типове значення) | natural | custom (використовує minMs/maxMs)    },  },}

• Канали, відмінні від Telegram, потребують явного *.streaming.block.enabled: true для ввімкнення блокових відповідей. Виняток — QQ Bot: він не має ключів streaming.block і передає блокові відповіді потоково, якщо channels.qqbot.streaming.mode не дорівнює "off".
• Перевизначення для каналів: channels.<channel>.streaming.block.coalesce (і варіанти для окремих облікових записів). Для Discord, Google Chat, Mattermost, MS Teams, Signal і Slack типовими є minChars: 1500 / idleMs: 1000.
• blockStreamingChunk.breakPreference: бажана межа фрагмента ("paragraph" | "newline" | "sentence").
• humanDelay: випадкова пауза між блоковими відповідями. Типове значення: off. natural = 800-2500ms. custom використовує minMs/maxMs (для будь-якої незаданої межі використовується природний діапазон). Перевизначення для окремого агента: agents.list[].humanDelay.

Докладніше про поведінку та поділ на фрагменти див. у розділі Потокове передавання.

Індикатори введення

{  agents: {    defaults: {      typingMode: "instant", // never | instant | thinking | message      typingIntervalSeconds: 6,    },  },}

• Типові значення: instant для прямих чатів/згадок, message для групових чатів без згадки.
• Типове значення typingIntervalSeconds: 6.
• Перевизначення для окремого сеансу: session.typingMode, session.typingIntervalSeconds.

Див. Індикатори введення.

agents.defaults.sandbox

Необов’язкова ізоляція для вбудованого агента. Повний посібник див. у розділі Ізоляція.

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // off (типово) | non-main | all        backend: "docker", // docker (типово) | ssh | openshell        scope: "agent", // session | agent (типово) | shared        workspaceAccess: "none", // none (типово) | ro | rw        workspaceRoot: "~/.openclaw/sandboxes",        docker: {          image: "openclaw-sandbox:bookworm-slim",          containerPrefix: "openclaw-sbx-",          workdir: "/workspace",          readOnlyRoot: true,          tmpfs: ["/tmp", "/var/tmp", "/run"],          network: "none",          user: "1000:1000",          capDrop: ["ALL"],          env: { LANG: "C.UTF-8" },          setupCommand: "apt-get update && apt-get install -y git curl jq",          pidsLimit: 256,          memory: "1g",          memorySwap: "2g",          cpus: 1,          gpus: "all",          ulimits: {            nofile: { soft: 1024, hard: 2048 },            nproc: 256,          },          seccompProfile: "/path/to/seccomp.json",          apparmorProfile: "openclaw-sandbox",          dns: ["1.1.1.1", "8.8.8.8"],          extraHosts: ["internal.service:10.0.0.5"],          binds: ["/home/user/source:/source:rw"],        },        ssh: {          target: "user@gateway-host:22",          command: "ssh",          workspaceRoot: "/tmp/openclaw-sandboxes",          strictHostKeyChecking: true,          updateHostKeys: true,          identityFile: "~/.ssh/id_ed25519",          certificateFile: "~/.ssh/id_ed25519-cert.pub",          knownHostsFile: "~/.ssh/known_hosts",          // Також підтримуються SecretRefs / вбудований вміст:          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },        },        browser: {          enabled: false,          image: "openclaw-sandbox-browser:bookworm-slim",          network: "openclaw-sandbox-browser",          cdpPort: 9222,          cdpSourceRange: "172.21.0.1/32",          vncPort: 5900,          noVncPort: 6080,          headless: false,          enableNoVnc: true,          allowHostControl: false,          autoStart: true,          autoStartTimeoutMs: 12000,        },        prune: {          idleHours: 24,          maxAgeDays: 7,        },      },    },  },  tools: {    sandbox: {      tools: {        allow: [          "exec",          "process",          "read",          "write",          "edit",          "apply_patch",          "sessions_list",          "sessions_history",          "sessions_send",          "sessions_spawn",          "session_status",        ],        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],      },    },  },}

Наведені вище типові значення (off/docker/agent/none/образ bookworm-slim/мережа none/тощо) — це фактичні типові значення OpenClaw, а не лише ілюстративні приклади.

{plugins: {  entries: {    openshell: {      enabled: true,      config: {        mode: "mirror", // mirror (типово) | remote        command: "openshell",        from: "openclaw",        remoteWorkspaceDir: "/sandbox",        remoteAgentWorkspaceDir: "/agent",        gateway: "lab", // необов’язково        gatewayEndpoint: "https://lab.example", // необов’язково        policy: "strict", // необов’язковий ідентифікатор політики OpenShell        providers: ["openai"], // необов’язково        autoProviders: true,        timeoutSeconds: 120,      },    },  },},}

Ізоляція браузера та sandbox.docker.binds підтримуються лише в Docker.

Збирання образів (із робочої копії вихідного коду):

scripts/sandbox-setup.sh           # основний образ ізольованого середовищаscripts/sandbox-browser-setup.sh   # необов’язковий образ браузера

Для встановлення через npm без робочої копії вихідного коду див. вбудовані команди docker build у розділі Ізоляція § Образи та налаштування.

agents.list (перевизначення для окремих агентів)

Використовуйте agents.list[].tts, щоб призначити агенту власного постачальника TTS, голос, модель, стиль або режим автоматичного TTS. Блок агента глибоко об’єднується з глобальним messages.tts, тому спільні облікові дані можна зберігати в одному місці, а окремі агенти можуть перевизначати лише потрібні їм поля голосу або постачальника. Перевизначення активного агента застосовується до автоматичних озвучених відповідей, /tts audio, /tts status і інструмента агента tts. Приклади постачальників і порядок пріоритетів наведено в розділі Перетворення тексту на мовлення.

{  agents: {    list: [      {        id: "main",        default: true,        name: "Головний агент",        workspace: "~/.openclaw/workspace",        agentDir: "~/.openclaw/agents/main/agent",        model: "anthropic/claude-opus-4-6", // або { primary, fallbacks }        utilityModel: "openai/gpt-5.4-mini",        thinkingDefault: "high", // перевизначення рівня мислення для окремого агента        reasoningDefault: "on", // перевизначення видимості міркувань для окремого агента        fastModeDefault: false, // перевизначення швидкого режиму для окремого агента        params: { cacheRetention: "none" }, // перевизначає за ключем відповідні параметри defaults.models        tts: {          providers: {            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },          },        },        skills: ["docs-search"], // якщо задано, замінює agents.defaults.skills        identity: {          name: "Саманта",          theme: "послужливий лінивець",          emoji: "🦥",          avatar: "avatars/samantha.png",        },        groupChat: { mentionPatterns: ["@openclaw"] },        sandbox: { mode: "off" },        runtime: {          type: "acp",          acp: {            agent: "codex",            backend: "acpx",            mode: "persistent", // persistent | oneshot            cwd: "/workspace/openclaw",          },        },        subagents: { allowAgents: ["*"] },        tools: {          profile: "coding",          allow: ["browser"],          deny: ["canvas"],          elevated: { enabled: true },        },      },    ],  },}

• id: стабільний ідентифікатор агента (обов’язковий).
• default: якщо задано кілька, використовується перший (у журнал записується попередження). Якщо не задано жодного, типовим є перший запис списку.
• model: рядкова форма задає сувору основну модель для окремого агента без резервної моделі; об’єктна форма { primary } також є суворою, якщо не додати fallbacks. Використовуйте { primary, fallbacks: [...] }, щоб увімкнути резервну модель для цього агента, або { primary, fallbacks: [] }, щоб явно вказати сувору поведінку. Завдання Cron, які перевизначають лише primary, усе одно успадковують типові резервні моделі, якщо не задати fallbacks: [].
• utilityModel: необов’язкове перевизначення для окремого агента для коротких внутрішніх завдань, як-от створення назв сеансів і гілок. Якщо значення немає, використовується agents.defaults.utilityModel, потім оголошена основним постачальником типова мала модель, а потім основна модель цього агента. Порожній рядок вимикає маршрутизацію допоміжних завдань для цього агента.
• params: параметри потоку для окремого агента, які об’єднуються поверх запису вибраної моделі в agents.defaults.models. Використовуйте це для специфічних перевизначень агента, як-от cacheRetention, temperature або maxTokens, не дублюючи весь каталог моделей.
• tts: необов’язкові перевизначення синтезу мовлення для окремого агента. Блок глибоко об’єднується поверх messages.tts, тому зберігайте спільні облікові дані постачальника й політику резервування в messages.tts, а тут задавайте лише специфічні для персонажа значення, як-от постачальник, голос, модель, стиль або автоматичний режим.
• skills: необов’язковий список дозволених Skills для окремого агента. Якщо його пропущено, агент успадковує agents.defaults.skills, коли його задано; явно заданий список замінює типові значення, а не об’єднується з ними, а [] означає відсутність Skills.
• thinkingDefault: необов’язковий типовий рівень мислення для окремого агента (off | minimal | low | medium | high | xhigh | adaptive | max). Перевизначає agents.defaults.thinkingDefault для цього агента, коли немає перевизначення для повідомлення або сеансу. Профіль вибраного постачальника/моделі визначає допустимі значення; для Google Gemini adaptive зберігає динамічне мислення під керуванням постачальника (thinkingLevel пропускається в Gemini 3/3.1, thinkingBudget: -1 — у Gemini 2.5).
• reasoningDefault: необов’язкова типова видимість міркувань для окремого агента (on | off | stream). Перевизначає agents.defaults.reasoningDefault для цього агента, коли немає перевизначення міркувань для повідомлення або сеансу.
• fastModeDefault: необов’язкове типове значення швидкого режиму для окремого агента ("auto" | true | false). Застосовується, коли немає перевизначення швидкого режиму для повідомлення або сеансу.
• models: необов’язкові перевизначення каталогу моделей/середовища виконання для окремого агента з ключами у вигляді повних ідентифікаторів provider/model. Використовуйте models["provider/model"].agentRuntime для винятків середовища виконання окремого агента.
• runtime: необов’язковий дескриптор середовища виконання для окремого агента. Використовуйте type: "acp" з типовими значеннями runtime.acp (agent, backend, mode, cwd), коли агент за замовчуванням має використовувати сеанси оболонки ACP.
• identity.avatar: шлях відносно робочого простору, URL-адреса http(s) або URI data:.
• Розмір локальних файлів зображень identity.avatar за шляхами відносно робочого простору обмежено 2 MB. URL-адреси http(s) та URI data: не перевіряються щодо локального обмеження розміру файлу.
• identity виводить типові значення: ackReaction з emoji, mentionPatterns з name/emoji.
• subagents.allowAgents: список дозволених ідентифікаторів налаштованих агентів для явних цілей sessions_spawn.agentId (["*"] = будь-яка налаштована ціль; типово: лише той самий агент). Додайте ідентифікатор ініціатора запиту, якщо потрібно дозволити виклики agentId, спрямовані на самого себе. Застарілі записи, конфігурацію агента яких видалено, відхиляються sessions_spawn і пропускаються в agents_list; запустіть openclaw doctor --fix, щоб очистити їх, або додайте мінімальний запис agents.list[], якщо ця ціль має залишатися доступною для створення з успадкуванням типових значень.
• Захист успадкування пісочниці: якщо сеанс ініціатора запиту виконується в пісочниці, sessions_spawn відхиляє цілі, які виконувалися б поза пісочницею.
• subagents.requireAgentId: якщо значення true, блокувати виклики sessions_spawn, у яких пропущено agentId (вимагає явного вибору профілю; типове значення: false).
• subagents.maxConcurrent: максимальна кількість одночасних запусків дочірніх агентів у межах виконання підагентів. Типове значення: 8.
• subagents.maxChildrenPerAgent: максимальна кількість активних дочірніх агентів, яких може створити один сеанс агента. Типове значення: 5.
• subagents.maxSpawnDepth: максимальна глибина вкладеності створення підагентів (1-5). Типове значення: 1 (без вкладеності).
• subagents.archiveAfterMinutes: час, після якого стан завершеного підагента архівується. Типове значення: 60.

Маршрутизація між кількома агентами

Запускайте кілька ізольованих агентів усередині одного Gateway. Див. Кілька агентів.

{  agents: {    list: [      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },      { id: "work", workspace: "~/.openclaw/workspace-work" },    ],  },  bindings: [    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },  ],}

Поля відповідності прив’язки

• type (необов’язкове): route для звичайної маршрутизації (якщо тип не вказано, типовим є route), acp для постійних прив’язок розмов ACP.
• match.channel (обов’язкове)
• match.accountId (необов’язкове; * = будь-який обліковий запис; пропущене значення = типовий обліковий запис)
• match.peer (необов’язкове; { kind: direct|group|channel, id })
• match.guildId / match.teamId (необов’язкове; залежить від каналу)
• acp (необов’язкове; лише для type: "acp"): { mode, label, cwd, backend }

Детермінований порядок відповідності:

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (точна відповідність, без однорангового вузла/гільдії/команди)
5. match.accountId: "*" (для всього каналу)
6. Типовий агент

На кожному рівні використовується перший відповідний запис bindings.

Для записів type: "acp" OpenClaw виконує зіставлення за точною ідентичністю розмови (match.channel + обліковий запис + match.peer.id) і не використовує наведений вище порядок рівнів прив’язки маршрутів.

Профілі доступу для окремих агентів

{agents: {  list: [    {      id: "personal",      workspace: "~/.openclaw/workspace-personal",      sandbox: { mode: "off" },    },  ],},}

{agents: {  list: [    {      id: "family",      workspace: "~/.openclaw/workspace-family",      sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },      tools: {        allow: [          "read",          "sessions_list",          "sessions_history",          "sessions_send",          "sessions_spawn",          "session_status",        ],        deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],      },    },  ],},}

{agents: {  list: [    {      id: "public",      workspace: "~/.openclaw/workspace-public",      sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },      tools: {        allow: [          "sessions_list",          "sessions_history",          "sessions_send",          "sessions_spawn",          "session_status",          "whatsapp",          "telegram",          "slack",          "discord",          "gateway",        ],        deny: [          "read",          "write",          "edit",          "apply_patch",          "exec",          "process",          "browser",          "canvas",          "nodes",          "cron",          "gateway",          "image",        ],      },    },  ],},}

Докладніше про пріоритет див. в розділі Пісочниця та інструменти для кількох агентів.

Сеанс

{  session: {    scope: "per-sender",    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer    identityLinks: {      alice: ["telegram:123456789", "discord:987654321012345678"],    },    reset: {      mode: "daily", // daily | idle      atHour: 4,      idleMinutes: 60,    },    resetByType: {      thread: { mode: "daily", atHour: 4 },      direct: { mode: "idle", idleMinutes: 240 },      group: { mode: "idle", idleMinutes: 120 },    },    resetByChannel: {      discord: { mode: "idle", idleMinutes: 30 },    },    resetTriggers: ["/new", "/reset"],    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",    maintenance: {      mode: "enforce", // enforce (типово) | warn      pruneAfter: "30d",      maxEntries: 500,      resetArchiveRetention: "30d", // тривалість або false      maxDiskBytes: "500mb", // необов’язкове жорстке обмеження      highWaterBytes: "400mb", // необов’язкова ціль очищення    },    writeLock: {      acquireTimeoutMs: 60000,      staleMs: 1800000,      maxHoldMs: 300000,    },    threadBindings: {      enabled: true,      idleHours: 24, // типове автоматичне скасування фокуса після бездіяльності в годинах (`0` вимикає)      maxAgeHours: 0, // типовий жорсткий максимальний вік у годинах (`0` вимикає)    },    mainKey: "main", // застаріле (середовище виконання завжди використовує "main")    agentToAgent: { maxPingPongTurns: 5 },    sendPolicy: {      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],      default: "allow",    },  },}

Повідомлення

{  messages: {    responsePrefix: "🦞", // або "auto"    ackReaction: "👀",    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all | off | none    removeAckAfterReply: false,    queue: {      mode: "steer", // steer (за замовчуванням) | followup | collect | interrupt      debounceMs: 500,      cap: 20,      drop: "summarize", // old | new | summarize (за замовчуванням)      byChannel: {        whatsapp: "followup",        telegram: "followup",      },    },    inbound: {      debounceMs: 2000, // 0 вимикає      byChannel: {        whatsapp: 5000,        slack: 1500,      },    },  },}

Префікс відповіді

Перевизначення для окремих каналів або облікових записів: channels.<channel>.responsePrefix, channels.<channel>.accounts.<id>.responsePrefix.

Порядок визначення (найконкретніше має перевагу): обліковий запис → канал → глобальне значення. "" вимикає та зупиняє каскад. "auto" виводить [{identity.name}].

Змінні шаблону:

Змінні не залежать від регістру. {think} є псевдонімом для {thinkingLevel}.

Реакція-підтвердження

• За замовчуванням використовується identity.emoji активного агента, інакше — "👀". Установіть "", щоб вимкнути.
• Перевизначення для окремих каналів: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Порядок визначення: обліковий запис → канал → messages.ackReaction → резервне значення ідентичності.
• Область: group-mentions (за замовчуванням), group-all, direct, all або off/none (повністю вимикає реакції-підтвердження).
• removeAckAfterReply: видаляє реакцію-підтвердження після відповіді в каналах із підтримкою реакцій, як-от Slack, Discord, Signal, Telegram, WhatsApp та iMessage.
• messages.statusReactions.enabled: вмикає реакції стану життєвого циклу в Slack, Discord, Signal, Telegram і WhatsApp. У Discord, якщо значення не задано, реакції стану залишаються ввімкненими, коли активні реакції-підтвердження. У Slack, Signal, Telegram і WhatsApp явно встановіть значення true, щоб увімкнути реакції стану життєвого циклу. Slack за замовчуванням використовує власний стан гілки асистента та змінні повідомлення про завантаження для відображення поступу, водночас налаштована реакція-підтвердження залишається незмінною.
• messages.statusReactions.emojis: перевизначає ключі емодзі життєвого циклу: queued, thinking, compacting, tool, coding, web, deploy, build, concierge, done, error, stallSoft і stallHard. Telegram дозволяє лише фіксований набір реакцій, тому непідтримувані налаштовані емодзі замінюються найближчим підтримуваним варіантом стану для цього чату.

Черга

• mode: стратегія черги для вхідних повідомлень, які надходять під час активного виконання сеансу. За замовчуванням: "steer".
  • steer: вставляє новий запит в активне виконання.
  • followup: виконує новий запит після завершення активного виконання.
  • collect: групує сумісні повідомлення та виконує їх разом пізніше.
  • interrupt: перериває активне виконання перед запуском найновішого запиту.
• debounceMs: затримка перед передаванням повідомлення з черги або керованого повідомлення. За замовчуванням: 500.
• cap: максимальна кількість повідомлень у черзі до застосування політики відкидання. За замовчуванням: 20.
• drop: стратегія в разі перевищення обмеження. "summarize" (за замовчуванням) відкидає найстаріші записи, але зберігає стислі підсумки; "old" відкидає найстаріші без підсумків; "new" відхиляє найновіший елемент.
• byChannel: перевизначення mode для окремих каналів із ключами за ідентифікатором провайдера.
• debounceMsByChannel: перевизначення debounceMs для окремих каналів із ключами за ідентифікатором провайдера.

Усунення брязкоту вхідних повідомлень

Групує швидкі повідомлення лише з текстом від одного відправника в один хід агента. Медіафайли та вкладення спричиняють негайне передавання. Керівні команди оминають усунення брязкоту. Значення debounceMs за замовчуванням: 2000.

Інші ключі повідомлень

• messages.messagePrefix: текстовий префікс, що додається до вхідних повідомлень користувача перед їх передаванням до середовища виконання агента. Використовуйте помірковано для маркерів контексту каналу.
• messages.visibleReplies: керує видимими відповідями на джерело в прямих, групових і канальних розмовах ("message_tool" потребує message(action=send) для видимого виведення; "automatic" публікує звичайні відповіді, як і раніше).
• messages.usageTemplate / messages.responseUsage: власний шаблон нижнього колонтитула /usage і стандартний режим використання для кожної відповіді (off | tokens | full, а також застарілий псевдонім on для tokens).
• messages.groupChat.mentionPatterns / historyLimit: тригери згадок у групових повідомленнях і розмір вікна історії.
• messages.suppressToolErrors: коли встановлено true, приховує показувані користувачеві попередження ⚠️ про помилки інструментів (агент усе одно бачить помилки в контексті й може повторити спробу). За замовчуванням: false.

TTS (перетворення тексту на мовлення)

{  messages: {    tts: {      auto: "off", // off (default) | always | inbound | tagged      mode: "final", // final | all      provider: "elevenlabs",      summaryModel: "openai/gpt-5.4-mini",      modelOverrides: { enabled: true },      maxTextLength: 4000,      timeoutMs: 30000,      prefsPath: "~/.openclaw/settings/tts.json",      providers: {        elevenlabs: {          apiKey: "elevenlabs_api_key",          baseUrl: "https://api.elevenlabs.io",          speakerVoiceId: "voice_id",          modelId: "eleven_multilingual_v2",          seed: 42,          applyTextNormalization: "auto",          languageCode: "en",          voiceSettings: {            stability: 0.5,            similarityBoost: 0.75,            style: 0.0,            useSpeakerBoost: true,            speed: 1.0,          },        },        microsoft: {          speakerVoice: "en-US-MichelleNeural",          lang: "en-US",          outputFormat: "audio-24khz-48kbitrate-mono-mp3",        },        openai: {          apiKey: "openai_api_key",          baseUrl: "https://api.openai.com/v1",          model: "gpt-4o-mini-tts",          speakerVoice: "coral",        },      },    },  },}

• auto керує типовим автоматичним режимом TTS: off, always, inbound або tagged. /tts on|off може перевизначати локальні налаштування, а /tts status показує фактичний стан.
• summaryModel перевизначає agents.defaults.model.primary для автоматичного підсумовування.
• modelOverrides увімкнено типово (enabled !== false); modelOverrides.allowProvider вмикається окремо.
• Для ключів API використовуються резервні значення ELEVENLABS_API_KEY/XI_API_KEY та OPENAI_API_KEY.
• Вбудовані постачальники синтезу мовлення належать плагінам. Якщо встановлено plugins.allow, додайте кожен плагін постачальника TTS, який потрібно використовувати, наприклад microsoft для Edge TTS. Застарілий ідентифікатор постачальника edge приймається як псевдонім для microsoft.
• providers.openai.baseUrl перевизначає кінцеву точку TTS OpenAI. Порядок визначення: конфігурація, потім OPENAI_TTS_BASE_URL, потім https://api.openai.com/v1.
• Коли providers.openai.baseUrl указує на кінцеву точку, відмінну від OpenAI, OpenClaw розглядає її як сумісний з OpenAI сервер TTS і послаблює перевірку моделі та голосу.

Розмова

Типові параметри режиму «Розмова» (macOS/iOS/Android та браузерний інтерфейс керування).

{  talk: {    provider: "elevenlabs",    providers: {      elevenlabs: {        speakerVoiceId: "elevenlabs_voice_id",        voiceAliases: {          Clawd: "EXAVITQu4vr4xnSDxMaL",          Roger: "CwhRBWXzGAHq8TQ4Fs17",        },        modelId: "eleven_multilingual_v2",        outputFormat: "mp3_44100_128",        apiKey: "elevenlabs_api_key",      },      mlx: {        modelId: "mlx-community/Soprano-80M-bf16",      },      system: {},    },    consultThinkingLevel: "low",    consultFastMode: true,    speechLocale: "ru-RU",    silenceTimeoutMs: 1500,    interruptOnSpeech: true,    realtime: {      provider: "openai",      providers: {        openai: {          model: "gpt-realtime-2.1",          speakerVoice: "cedar",        },      },      instructions: "Говоріть доброзичливо й відповідайте стисло.",      mode: "realtime", // realtime | stt-tts | transcription      transport: "webrtc", // webrtc | provider-websocket | gateway-relay | managed-room      vadThreshold: 0.5,      silenceDurationMs: 500,      prefixPaddingMs: 300,      reasoningEffort: "medium",      brain: "agent-consult", // agent-consult | direct-tools | none    },  },}

• talk.provider має відповідати ключу в talk.providers, коли налаштовано кількох постачальників режиму «Розмова».
• Застарілі плоскі ключі режиму «Розмова» (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) призначені лише для сумісності. Запустіть openclaw doctor --fix, щоб перезаписати збережену конфігурацію у формат talk.providers.<provider>.
• Для ідентифікаторів голосу використовуються резервні значення ELEVENLABS_VOICE_ID або SAG_VOICE_ID (поведінка клієнта режиму «Розмова» для macOS).
• providers.*.apiKey приймає звичайні текстові рядки або об’єкти SecretRef.
• Резервне значення ELEVENLABS_API_KEY застосовується лише тоді, коли ключ API для режиму «Розмова» не налаштовано.
• providers.*.voiceAliases дає змогу використовувати в директивах режиму «Розмова» зрозумілі назви.
• providers.mlx.modelId вибирає репозиторій Hugging Face, який використовує локальний допоміжний засіб MLX для macOS. Якщо параметр пропущено, macOS використовує mlx-community/Soprano-80M-bf16.
• Відтворення MLX у macOS виконується через вбудований допоміжний засіб openclaw-mlx-tts, якщо він доступний, або через виконуваний файл у PATH; OPENCLAW_MLX_TTS_BIN перевизначає шлях до допоміжного засобу для розробки.
• consultThinkingLevel керує рівнем міркування для повного запуску агента OpenClaw, що виконується за викликами openclaw_agent_consult режиму «Розмова» в реальному часі в інтерфейсі керування. Не задавайте цей параметр, щоб зберегти звичайну поведінку сеансу та моделі.
• consultFastMode задає одноразове перевизначення швидкого режиму для консультацій режиму «Розмова» в реальному часі в інтерфейсі керування, не змінюючи звичайного налаштування швидкого режиму сеансу.
• speechLocale задає ідентифікатор локалі BCP 47, який використовується для розпізнавання мовлення в режимі «Розмова» на iOS/macOS. Не задавайте цей параметр, щоб використовувати типове значення пристрою.
• silenceTimeoutMs визначає, скільки часу режим «Розмова» очікує після того, як користувач замовкне, перш ніж надіслати транскрипцію. Якщо параметр не задано, зберігається типове для платформи вікно паузи (700 ms on macOS and Android, 900 ms on iOS).
• realtime.instructions додає системні інструкції для постачальника до вбудованого запиту OpenClaw для роботи в реальному часі, тому стиль голосу можна налаштувати без втрати типових настанов openclaw_agent_consult.
• realtime.vadThreshold задає поріг виявлення голосової активності постачальника від 0 (найчутливіший) до 1 (найменш чутливий). Якщо параметр не задано, зберігається типове значення постачальника.
• realtime.silenceDurationMs задає додатне цілочисельне вікно тиші, після якого постачальник фіксує репліку користувача в реальному часі. Якщо параметр не задано, зберігається типове значення постачальника.
• realtime.prefixPaddingMs задає невід’ємну цілочисельну тривалість аудіо, що зберігається перед початком виявленого мовлення. Якщо параметр не задано, зберігається типове значення постачальника.
• realtime.reasoningEffort задає специфічний для постачальника рівень міркування для сеансів у реальному часі. Якщо параметр не задано, зберігається типове значення постачальника.
• realtime.consultRouting: "provider-direct" (типово) зберігає прямі відповіді постачальника, коли постачальник роботи в реальному часі створює остаточну транскрипцію репліки користувача без openclaw_agent_consult. Натомість "force-agent-consult" спрямовує завершений запит через OpenClaw.

Пов’язані матеріали

• Довідник із конфігурації — усі інші ключі конфігурації
• Конфігурація — поширені завдання та швидке налаштування
• Приклади конфігурації