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

Ключи конфигурации уровня агента в разделах 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

Необязательный список разрешённых навыков по умолчанию для агентов, у которых не задано agents.list[].skills.

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

• Не указывайте agents.defaults.skills, чтобы по умолчанию разрешить все навыки.
• Не указывайте agents.list[].skills, чтобы наследовать значения по умолчанию.
• Укажите agents.list[].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

Глобальное ограничение для компактного списка навыков, внедряемого в системный промпт. Оно не влияет на чтение файлов SKILL.md по запросу.

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

agents.list[].skillsLimits.maxSkillsPromptChars

Переопределение бюджета промпта навыков для отдельного агента.

{  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 }).
  • Используется общей функцией создания изображений и любыми будущими инструментами или плагинами, создающими изображения.
  • Типичные значения: 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 или OAuth OpenAI Codex для 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 провайдера.
  • Официальный плагин создания видео 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 для доступа через OAuth Codex). Если провайдер не указан, 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. При конфликте с созданными ключами запроса дополнительное тело имеет приоритет; маршруты дополнений, не являющиеся нативными, после этого всё равно удаляют предназначенный только для OpenAI параметр store.
• params.chat_template_kwargs: аргументы шаблона чата, совместимые с vLLM/OpenAI и объединяемые с телами запросов верхнего уровня api: "openai-completions". Для vllm/nemotron-3-* с отключённым мышлением встроенный плагин 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", идентификатор зарегистрированной среды плагина или поддерживаемый псевдоним бэкенда CLI. Встроенный плагин Codex регистрирует codex; встроенный плагин Anthropic предоставляет бэкенд CLI claude-cli.
• id: "auto" позволяет средам зарегистрированных плагинов принимать фактические маршруты, которые объявляют или иным образом выполняют их контракт поддержки, и использует OpenClaw, если подходящая среда не найдена. Явно заданная среда выполнения плагина, например 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. В OpenClaw для Anthropic Claude Opus 4.8 рассуждения по умолчанию отключены; если адаптивные рассуждения включены явно, принадлежащее провайдеру 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, вместо этого наложения OpenClaw для GPT-5, а для нативных потоков 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", // идентификатор зарегистрированного плагина — провайдера 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 контекста...» и «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", // постоянный | одноразовый            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: необязательный список разрешённых навыков для отдельного агента. Если он опущен, агент наследует agents.defaults.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 для обычной маршрутизации (при отсутствии типа по умолчанию используется маршрут), 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", // основной | для каждого собеседника | для каждого собеседника в канале | для каждой учётной записи, канала и собеседника    identityLinks: {      alice: ["telegram:123456789", "discord:987654321012345678"],    },    reset: {      mode: "daily", // ежедневно | при бездействии      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", // принудительное применение (по умолчанию) | предупреждение      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 переопределяет конечную точку OpenAI TTS. Порядок разрешения: конфигурация, затем OPENAI_TTS_BASE_URL, затем https://api.openai.com/v1.
• Когда providers.openai.baseUrl указывает на конечную точку, не принадлежащую OpenAI, OpenClaw рассматривает её как TTS-сервер, совместимый с OpenAI, и ослабляет проверку модели и голоса.

Разговор

Настройки по умолчанию для режима разговора (macOS/iOS/Android и браузерный Control UI).

{  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 режима разговора в реальном времени в Control UI. Не задавайте этот параметр, чтобы сохранить обычное поведение сеанса и модели.
• consultFastMode задаёт однократное переопределение быстрого режима для консультаций режима разговора в реальном времени в Control UI, не изменяя обычную настройку быстрого режима сеанса.
• 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.

Связанные материалы

• Справочник по конфигурации — все остальные ключи конфигурации
• Конфигурация — распространённые задачи и быстрая настройка
• Примеры конфигурации