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

Ключи конфигурации на уровне агента в разделах 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 }).
  • Используется общей функцией генерации изображений и любыми будущими инструментами или плагинами, создающими изображения.
  • Типичные значения: 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 провайдера.
  • Официальный плагин генерации видео 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. При конфликте с генерируемыми ключами запроса дополнительное тело имеет приоритет; после этого маршруты завершений без нативной поддержки по-прежнему удаляют специфичный для 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",          // Также поддерживаются SecretRef / встроенное содержимое:          // 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: "Main Agent",        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: "Samantha",          theme: "helpful sloth",          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: необязательный список разрешённых навыков для отдельного агента. Если он отсутствует, агент наследует 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 МБ. 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 (по умолчанию) | 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 рассматривает её как TTS-сервер, совместимый с OpenAI, и смягчает проверку модели и голоса.

Разговор

Значения по умолчанию для режима разговора (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.

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

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