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

# Конфигурация

OpenClaw считывает необязательную конфигурацию **JSON5** (JSON5 поддерживает комментарии и завершающие запятые) из `~/.openclaw/openclaw.json`. Если файл отсутствует, OpenClaw использует безопасные значения по умолчанию.

Активный путь конфигурации должен указывать на обычный файл. При записи OpenClaw атомарно заменяет его (переименовывая файл в указанный путь), поэтому для `openclaw.json`, являющегося символической ссылкой, будет заменён целевой файл, а не выполнена сквозная запись — избегайте конфигураций с символическими ссылками. Если конфигурация хранится вне каталога состояния по умолчанию, задайте в `OPENCLAW_CONFIG_PATH` прямой путь к фактическому файлу.

Распространённые причины добавить конфигурацию:

* Подключить каналы и настроить, кто может отправлять сообщения боту
* Настроить модели, инструменты, изоляцию или автоматизацию (cron, хуки)
* Настроить сеансы, медиа, сеть или пользовательский интерфейс

Все доступные поля описаны в [полном справочнике](https://docs2.openclaw.ai/ru/gateway/configuration-reference.md).

Перед изменением конфигурации агенты и средства автоматизации должны использовать `config.schema.lookup`
для получения точной документации по отдельным полям. Эта страница содержит практические инструкции,
а [справочник по конфигурации](https://docs2.openclaw.ai/ru/gateway/configuration-reference.md) — более полную
карту полей и значений по умолчанию.

> [!TIP]
>
> **Впервые настраиваете конфигурацию?** Начните с `openclaw onboard` для интерактивной настройки или ознакомьтесь с руководством [«Примеры конфигурации»](https://docs2.openclaw.ai/ru/gateway/configuration-examples.md), содержащим готовые конфигурации для копирования.

## Минимальная конфигурация

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
// ~/.openclaw/openclaw.json
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}
```

## Редактирование конфигурации

> [tab] Интерактивный мастер
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw onboard       # полный процесс первоначальной настройки
> openclaw configure     # мастер конфигурации
> ```

> [tab] CLI (однострочные команды)
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw config get agents.defaults.workspace
> openclaw config set agents.defaults.heartbeat.every "2h"
> openclaw config unset plugins.entries.brave.config.webSearch.apiKey
> ```

> [tab] Панель управления
>
> Откройте [http://127.0.0.1:18789](http://127.0.0.1:18789) и перейдите на вкладку **Config**.
> Панель управления формирует форму на основе актуальной схемы конфигурации, включая метаданные
> документации полей `title` / `description`, а также схемы плагинов и каналов, если
> они доступны, и предоставляет редактор **Raw JSON** как резервный вариант. Для интерфейсов
> с детализацией и других инструментов Gateway также предоставляет `config.schema.lookup`, позволяющий
> получить один узел схемы для заданного пути и сводные данные о его непосредственных дочерних элементах.

> [tab] Прямое редактирование
>
> Отредактируйте `~/.openclaw/openclaw.json` напрямую. Gateway отслеживает файл и автоматически применяет изменения (см. [горячую перезагрузку](#config-hot-reload)).

## Строгая проверка

> [!WARNING]
>
> OpenClaw принимает только конфигурации, полностью соответствующие схеме. Неизвестные ключи, некорректные типы или недопустимые значения приводят к тому, что Gateway **отказывается запускаться**. Единственное исключение на корневом уровне — `$schema` (строка), позволяющее редакторам добавлять метаданные JSON Schema.

`openclaw config schema` выводит каноническую JSON Schema, используемую панелью управления
и при проверке. `config.schema.lookup` получает отдельный узел для заданного пути и
сводные данные о дочерних элементах для инструментов с детализацией. Метаданные документации
полей `title`/`description` передаются во вложенные объекты, ветви с подстановочным
знаком (`*`), элементы массивов (`[]`) и ветви `anyOf`/
`oneOf`/`allOf`. Схемы плагинов и каналов среды выполнения объединяются с ней
после загрузки реестра манифестов.

При ошибке проверки:

* Gateway не запускается
* Работают только диагностические команды (`openclaw doctor`, `openclaw logs`, `openclaw health`, `openclaw status`)
* Выполните `openclaw doctor`, чтобы просмотреть конкретные проблемы
* Выполните `openclaw doctor --fix` (`--repair` — тот же флаг; `--yes` отключает запросы подтверждения), чтобы применить исправления

После каждого успешного запуска Gateway сохраняет доверенную копию последней
работоспособной конфигурации, однако при запуске и горячей перезагрузке она не восстанавливается
автоматически — это выполняет только `openclaw doctor --fix`. Если `openclaw.json` не проходит проверку
(включая локальную проверку плагина), Gateway не запускается либо перезагрузка пропускается, а текущая
среда выполнения продолжает использовать последнюю принятую конфигурацию. Отклонённая запись также
сохраняется как `<path>.rejected.<timestamp>` для анализа.
Gateway блокирует записи, похожие на случайную перезапись: удаление `gateway.mode`,
потерю блока `meta` или сокращение файла более чем наполовину, — если запись
явно не разрешает деструктивные изменения. Кандидат не становится последней работоспособной
конфигурацией, если он содержит отредактированный заполнитель секрета, например
`***` или `[redacted]`.

## Распространённые задачи

> [accordion] Настройка канала (WhatsApp, Telegram, Discord и т. д.)
>
> У каждого канала есть собственный раздел конфигурации в `channels.<provider>`. Шаги настройки приведены на странице соответствующего канала:
>
> * [Discord](https://docs2.openclaw.ai/ru/channels/discord.md) — `channels.discord`
> * [Feishu](https://docs2.openclaw.ai/ru/channels/feishu.md) — `channels.feishu`
> * [Google Chat](https://docs2.openclaw.ai/ru/channels/googlechat.md) — `channels.googlechat`
> * [iMessage](https://docs2.openclaw.ai/ru/channels/imessage.md) — `channels.imessage`
> * [Mattermost](https://docs2.openclaw.ai/ru/channels/mattermost.md) — `channels.mattermost`
> * [Microsoft Teams](https://docs2.openclaw.ai/ru/channels/msteams.md) — `channels.msteams`
> * [Signal](https://docs2.openclaw.ai/ru/channels/signal.md) — `channels.signal`
> * [Slack](https://docs2.openclaw.ai/ru/channels/slack.md) — `channels.slack`
> * [Telegram](https://docs2.openclaw.ai/ru/channels/telegram.md) — `channels.telegram`
> * [WhatsApp](https://docs2.openclaw.ai/ru/channels/whatsapp.md) — `channels.whatsapp`
>
> Все каналы используют одинаковую схему политики личных сообщений:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   channels: {
>     telegram: {
>       enabled: true,
>       botToken: "123:abc",
>       dmPolicy: "pairing",   // pairing | allowlist | open | disabled
>       allowFrom: ["tg:123"], // только для allowlist/open
>     },
>   },
> }
> ```

> [accordion] Выбор и настройка моделей
>
> Задайте основную модель и необязательные резервные модели:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   agents: {
>     defaults: {
>       model: {
>         primary: "anthropic/claude-sonnet-4-6",
>         fallbacks: ["openai/gpt-5.4"],
>       },
>       models: {
>         "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
>         "openai/gpt-5.4": { alias: "GPT" },
>       },
>     },
>   },
> }
> ```
>
> * `agents.defaults.models` определяет каталог моделей и служит списком разрешений для `/model`; записи `provider/*` ограничивают `/model`, `/models` и средства выбора моделей выбранными поставщиками, сохраняя динамическое обнаружение моделей.
> * Используйте `openclaw config set agents.defaults.models '<json>' --strict-json --merge`, чтобы добавлять записи в список разрешений без удаления существующих моделей. Простые замены, удаляющие записи, отклоняются, если не передан `--replace`.
> * Ссылки на модели используют формат `provider/model` (например, `anthropic/claude-opus-4-6`).
> * `agents.defaults.imageMaxDimensionPx` управляет уменьшением масштаба изображений в расшифровках и инструментах (по умолчанию `1200`); меньшие значения обычно сокращают расход токенов компьютерного зрения при выполнении задач с большим количеством снимков экрана.
> * Сведения о переключении моделей в чате см. в разделе [CLI моделей](https://docs2.openclaw.ai/ru/concepts/models.md), а о ротации аутентификации и поведении резервных моделей — в разделе [Переключение при отказе модели](https://docs2.openclaw.ai/ru/concepts/model-failover.md).
> * Сведения о пользовательских и самостоятельно размещённых поставщиках см. в разделе [Пользовательские поставщики](https://docs2.openclaw.ai/ru/gateway/config-tools.md#custom-providers-and-base-urls) справочника.

> [accordion] Управление доступом к боту
>
> Доступ к личным сообщениям настраивается отдельно для каждого канала через `dmPolicy` (по умолчанию `"pairing"`):
>
> * `"pairing"`: неизвестные отправители получают одноразовый код сопряжения для подтверждения
> * `"allowlist"`: разрешены только отправители из `allowFrom` (или из хранилища разрешённых сопряжений)
> * `"open"`: разрешить все входящие личные сообщения (требуется `allowFrom: ["*"]`)
> * `"disabled"`: игнорировать все личные сообщения
>
> Для групп используйте `groupPolicy` (`"allowlist" | "open" | "disabled"`) вместе с `groupAllowFrom` или списками разрешений для конкретных каналов.
>
> Подробности для каждого канала приведены в [полном справочнике](https://docs2.openclaw.ai/ru/gateway/config-channels.md#dm-and-group-access).

> [accordion] Настройка обязательных упоминаний в групповых чатах
>
> По умолчанию групповые сообщения **требуют упоминания**. Настройте шаблоны срабатывания отдельно для каждого агента. Обычные ответы в группах и каналах публикуются автоматически; для общих комнат, где агент должен сам решать, когда отвечать, включите использование инструмента сообщений:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   messages: {
>     visibleReplies: "automatic", // задайте "message_tool", чтобы везде требовать отправку через инструмент сообщений
>     groupChat: {
>       visibleReplies: "message_tool", // включается явно; видимый вывод требует message(action=send)
>       unmentionedInbound: "room_event", // постоянный фоновый обмен сообщениями в группе без упоминаний служит ненавязчивым контекстом
>     },
>   },
>   agents: {
>     list: [
>       {
>         id: "main",
>         groupChat: {
>           mentionPatterns: ["@openclaw", "openclaw"],
>         },
>       },
>     ],
>   },
>   channels: {
>     whatsapp: {
>       groups: { "*": { requireMention: true } },
>     },
>   },
> }
> ```
>
> * **Упоминания в метаданных**: нативные @-упоминания (упоминание касанием в WhatsApp, @bot в Telegram и т. д.)
> * **Текстовые шаблоны**: безопасные регулярные выражения в `mentionPatterns`
> * **Видимые ответы**: `messages.visibleReplies` может глобально требовать отправку через инструмент сообщений; `messages.groupChat.visibleReplies` переопределяет это для групп и каналов.
> * Режимы видимых ответов, переопределения для отдельных каналов и режим чата с самим собой описаны в [полном справочнике](https://docs2.openclaw.ai/ru/gateway/config-channels.md#group-chat-mention-gating).

> [accordion] Ограничение Skills для отдельных агентов
>
> Используйте `agents.defaults.skills` как общую базовую конфигурацию, а затем переопределяйте её
> для отдельных агентов с помощью `agents.list[].skills`:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   agents: {
>     defaults: {
>       skills: ["github", "weather"],
>     },
>     list: [
>       { id: "writer" }, // наследует github, weather
>       { id: "docs", skills: ["docs-search"] }, // заменяет значения по умолчанию
>       { id: "locked-down", skills: [] }, // без skills
>     ],
>   },
> }
> ```
>
> * Чтобы по умолчанию не ограничивать Skills, не указывайте `agents.defaults.skills`.
> * Чтобы наследовать значения по умолчанию, не указывайте `agents.list[].skills`.
> * Чтобы отключить Skills, задайте `agents.list[].skills: []`.
> * См. [Skills](https://docs2.openclaw.ai/ru/tools/skills.md), [конфигурацию Skills](https://docs2.openclaw.ai/ru/tools/skills-config.md) и
>   [справочник по конфигурации](https://docs2.openclaw.ai/ru/gateway/config-agents.md#agents-defaults-skills).

> [accordion] Настройка мониторинга состояния каналов Gateway
>
> Настройте интенсивность перезапуска каналов, которые выглядят неактивными:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   gateway: {
>     channelHealthCheckMinutes: 5,
>     channelStaleEventThresholdMinutes: 30,
>     channelMaxRestartsPerHour: 10,
>   },
>   channels: {
>     telegram: {
>       healthMonitor: { enabled: false },
>       accounts: {
>         alerts: {
>           healthMonitor: { enabled: true },
>         },
>       },
>     },
>   },
> }
> ```
>
> * Показанные значения используются по умолчанию. Задайте `gateway.channelHealthCheckMinutes: 0`, чтобы глобально отключить перезапуски по результатам мониторинга состояния.
> * `channelStaleEventThresholdMinutes` должно быть больше или равно интервалу проверки.
> * Используйте `channels.<provider>.healthMonitor.enabled` или `channels.<provider>.accounts.<id>.healthMonitor.enabled`, чтобы отключить автоматические перезапуски для отдельного канала или учётной записи, не отключая глобальный мониторинг.
> * Сведения об эксплуатационной диагностике см. в разделе [«Проверки состояния»](https://docs2.openclaw.ai/ru/gateway/health.md), а описание всех полей — в [полном справочнике](https://docs2.openclaw.ai/ru/gateway/configuration-reference.md#gateway).

> [accordion] Настройка тайм-аута рукопожатия WebSocket в Gateway
>
> Предоставьте локальным клиентам больше времени для завершения предварительного
> WebSocket-рукопожатия до аутентификации на загруженных или маломощных узлах:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   gateway: {
>     handshakeTimeoutMs: 30000,
>   },
> }
> ```
>
> * По умолчанию — `15000` миллисекунд.
> * `OPENCLAW_HANDSHAKE_TIMEOUT_MS` по-прежнему имеет приоритет для разовых переопределений службы или оболочки.
> * Сначала рекомендуется устранить задержки при запуске или в цикле событий; этот параметр предназначен для исправных хостов, которые медленно прогреваются.

> [accordion] Настройка сеансов и сбросов
>
> Сеансы управляют непрерывностью и изоляцией диалогов:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   session: {
>     dmScope: "per-channel-peer",  // рекомендуется для нескольких пользователей
>     threadBindings: {
>       enabled: true,
>       idleHours: 24,
>       maxAgeHours: 0,
>     },
>     reset: {
>       mode: "daily",
>       atHour: 4,
>       idleMinutes: 120,
>     },
>   },
> }
> ```
>
> * `dmScope`: `main` (общий) | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
> * `threadBindings`: глобальные значения по умолчанию для маршрутизации сеансов, привязанных к веткам. `/focus`, `/unfocus`, `/agents`, `/session idle` и `/session max-age` позволяют привязывать, отвязывать, перечислять и настраивать это для каждого сеанса (Discord привязывает ветки, Telegram — темы или диалоги).
> * Сведения об областях действия, связях идентификаторов и политике отправки см. в разделе [Управление сеансами](https://docs2.openclaw.ai/ru/concepts/session.md).
> * Все поля см. в [полном справочнике](https://docs2.openclaw.ai/ru/gateway/config-agents.md#session).

> [accordion] Включение песочницы
>
> Запускайте сеансы агентов в изолированных средах песочницы:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   agents: {
>     defaults: {
>       sandbox: {
>         mode: "non-main",  // off | non-main | all
>         scope: "agent",    // session | agent | shared
>       },
>     },
>   },
> }
> ```
>
> Сначала соберите образ: из рабочей копии исходного кода выполните `scripts/sandbox-setup.sh`, а при установке из npm см. встроенную команду `docker build` в разделе [Песочница § Образы и настройка](https://docs2.openclaw.ai/ru/gateway/sandboxing.md#images-and-setup).
>
> Полное руководство см. в разделе [Песочница](https://docs2.openclaw.ai/ru/gateway/sandboxing.md), а все параметры — в [полном справочнике](https://docs2.openclaw.ai/ru/gateway/config-agents.md#agentsdefaultssandbox).

> [accordion] Включение push-уведомлений через ретранслятор для официальных сборок iOS
>
> Для push-уведомлений в общедоступных сборках из App Store используется размещённый ретранслятор OpenClaw: `https://ios-push-relay.openclaw.ai`.
>
> Для собственных развёртываний ретранслятора требуется намеренно отдельный путь сборки и развёртывания iOS, в котором URL ретранслятора совпадает с URL ретранслятора Gateway. Если используется собственная сборка с ретранслятором, задайте в конфигурации Gateway следующее:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   gateway: {
>     push: {
>       apns: {
>         relay: {
>           baseUrl: "https://relay.example.com",
>           // Необязательно. По умолчанию: 10000
>           timeoutMs: 10000,
>         },
>       },
>     },
>   },
> }
> ```
>
> Эквивалентная команда CLI:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
> ```
>
> Результат:
>
> * Позволяет Gateway отправлять `push.test`, сигналы пробуждения и сигналы пробуждения для переподключения через внешний ретранслятор.
> * Использует разрешение на отправку, ограниченное регистрацией и переданное сопряжённым приложением iOS. Gateway не требуется токен ретранслятора для всего развёртывания.
> * Привязывает каждую регистрацию через ретранслятор к идентификатору Gateway, с которым сопряжено приложение iOS, чтобы другой Gateway не мог повторно использовать сохранённую регистрацию.
> * Для локальных и вручную собранных версий iOS сохраняется прямая отправка через APNs. Отправка через ретранслятор применяется только к официально распространяемым сборкам, зарегистрированным через ретранслятор.
> * Должен совпадать с базовым URL ретранслятора, встроенным в сборку iOS, чтобы трафик регистрации и отправки поступал в одно и то же развёртывание ретранслятора.
>
> Сквозной процесс:
>
> 1. Установите официальное приложение iOS.
> 2. Необязательно: настраивайте `gateway.push.apns.relay.baseUrl` на Gateway только при использовании намеренно отдельной собственной сборки с ретранслятором.
> 3. Сопрягите приложение iOS с Gateway и дождитесь подключения сеансов Node и оператора.
> 4. Приложение iOS получает идентификатор Gateway, регистрируется в ретрансляторе с помощью App Attest и квитанции приложения, а затем публикует полезную нагрузку `push.apns.register` для ретранслятора в сопряжённом Gateway.
> 5. Gateway сохраняет дескриптор ретранслятора и разрешение на отправку, а затем использует их для `push.test`, сигналов пробуждения и сигналов пробуждения для переподключения.
>
> Примечания по эксплуатации:
>
> * Если приложение iOS переключено на другой Gateway, переподключите его, чтобы оно могло опубликовать новую регистрацию ретранслятора, привязанную к этому Gateway.
> * Если выпущена новая сборка iOS, указывающая на другое развёртывание ретранслятора, приложение обновляет кэшированную регистрацию ретранслятора вместо повторного использования прежнего источника ретранслятора.
>
> Примечание о совместимости:
>
> * `OPENCLAW_APNS_RELAY_BASE_URL` и `OPENCLAW_APNS_RELAY_TIMEOUT_MS` по-прежнему работают как временные переопределения через переменные среды.
> * URL собственного ретранслятора Gateway должен совпадать с базовым URL ретранслятора, встроенным в сборку iOS; канал выпуска в общедоступном App Store отклоняет переопределения URL собственного ретранслятора iOS.
> * `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` остаётся предназначенным только для loopback аварийным вариантом для разработки; не сохраняйте URL ретранслятора HTTP в конфигурации.
>
> Сквозной процесс см. в разделе [Приложение iOS](https://docs2.openclaw.ai/ru/platforms/ios.md#relay-backed-push-for-official-builds), а модель безопасности ретранслятора — в разделе [Процесс аутентификации и установления доверия](https://docs2.openclaw.ai/ru/platforms/ios.md#authentication-and-trust-flow).

> [accordion] Настройка Heartbeat (периодических проверок)
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   agents: {
>     defaults: {
>       heartbeat: {
>         every: "30m",
>         target: "last",
>       },
>     },
>   },
> }
> ```
>
> * `every`: строка длительности (`30m`, `2h`). Чтобы отключить, задайте `0m`. По умолчанию: `30m`.
> * `target`: `last` | `none` | `<channel-id>` (например, `discord`, `matrix`, `telegram` или `whatsapp`)
> * `directPolicy`: `allow` (по умолчанию) или `block` для целей Heartbeat в стиле личных сообщений
> * Полное руководство см. в разделе [Heartbeat](https://docs2.openclaw.ai/ru/gateway/heartbeat.md).

> [accordion] Настройка заданий Cron
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   cron: {
>     enabled: true,
>     maxConcurrentRuns: 8, // по умолчанию; диспетчеризация cron + изолированное выполнение хода агента cron
>     sessionRetention: "24h",
>   },
> }
> ```
>
> * `sessionRetention`: удаляет завершённые изолированные сеансы запусков из строк сеансов SQLite (по умолчанию `24h`; чтобы отключить, задайте `false`).
> * В истории запусков автоматически сохраняются 2000 новейших конечных строк для каждого задания; для потерянных строк сохраняется 24-часовое окно очистки.
> * Обзор возможностей и примеры CLI см. в разделе [Задания Cron](https://docs2.openclaw.ai/ru/automation/cron-jobs.md).

> [accordion] Настройка вебхуков (хуков)
>
> Включите конечные точки HTTP-вебхуков на Gateway:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   hooks: {
>     enabled: true,
>     token: "shared-secret",
>     path: "/hooks",
>     defaultSessionKey: "hook:ingress",
>     allowRequestSessionKey: false,
>     allowedSessionKeyPrefixes: ["hook:"],
>     mappings: [
>       {
>         match: { path: "gmail" },
>         action: "agent",
>         agentId: "main",
>         deliver: true,
>       },
>     ],
>   },
> }
> ```
>
> Примечание по безопасности:
>
> * Считайте всё содержимое полезной нагрузки хука или вебхука недоверенными входными данными.
> * Используйте отдельный `hooks.token`; не используйте повторно активные секреты аутентификации Gateway (`gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` или `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`).
> * Аутентификация хуков выполняется только через заголовок (`Authorization: Bearer ...` или `x-openclaw-token`); токены в строке запроса отклоняются.
> * `hooks.path` не может быть `/`; размещайте входящие вебхуки в отдельном подпути, например `/hooks`.
> * Не включайте флаги обхода проверки небезопасного содержимого (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), кроме случаев строго ограниченной отладки.
> * Если включён `hooks.allowRequestSessionKey`, также задайте `hooks.allowedSessionKeyPrefixes`, чтобы ограничить выбираемые вызывающей стороной ключи сеансов.
> * Для агентов, запускаемых хуками, рекомендуется использовать мощные современные уровни моделей и строгую политику инструментов (например, только обмен сообщениями и, где возможно, песочницу).
>
> Все параметры сопоставления и интеграцию с Gmail см. в [полном справочнике](https://docs2.openclaw.ai/ru/gateway/configuration-reference.md#hooks).

> [accordion] Настройка маршрутизации между несколькими агентами
>
> Запускайте несколько изолированных агентов с отдельными рабочими пространствами и сеансами:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   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" } },
>   ],
> }
> ```
>
> Правила привязки и профили доступа отдельных агентов см. в разделах [Несколько агентов](https://docs2.openclaw.ai/ru/concepts/multi-agent.md) и [полный справочник](https://docs2.openclaw.ai/ru/gateway/config-agents.md#multi-agent-routing).

> [accordion] Разделение конфигурации на несколько файлов (\$include)
>
> Используйте `$include` для организации больших конфигураций:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> // ~/.openclaw/openclaw.json
> {
>   gateway: { port: 18789 },
>   agents: { $include: "./agents.json5" },
>   broadcast: {
>     $include: ["./clients/a.json5", "./clients/b.json5"],
>   },
> }
> ```
>
> * **Один файл**: заменяет содержащий его объект
> * **Массив файлов**: глубоко объединяются по порядку (последующие имеют приоритет), до 10 уровней вложенности
> * **Соседние ключи**: объединяются после включений (переопределяют включённые значения)
> * **Относительные пути**: разрешаются относительно включающего файла
> * **Формат пути**: пути включений не должны содержать нулевые байты и должны быть строго короче 4096 символов до и после разрешения
> * **Запись со стороны OpenClaw**: если запись изменяет только один раздел верхнего уровня,
>   поддерживаемый включением одного файла, например `plugins: { $include: "./plugins.json5" }`,
>   OpenClaw обновляет этот включённый файл и оставляет `openclaw.json` без изменений
> * **Неподдерживаемая сквозная запись**: корневые включения, массивы включений и включения
>   с соседними переопределениями приводят к безопасному отказу записи со стороны OpenClaw вместо
>   сведения конфигурации в один файл
> * **Ограничение области**: пути `$include` должны разрешаться внутри каталога, содержащего
>   `openclaw.json`. Чтобы совместно использовать дерево на разных компьютерах или между пользователями, задайте
>   `OPENCLAW_INCLUDE_ROOTS` как список путей (`:` в POSIX, `;` в Windows) к
>   дополнительным каталогам, на которые могут ссылаться включения. Символические ссылки разрешаются
>   и проверяются повторно, поэтому путь, который лексически находится в каталоге конфигурации, но
>   фактическая цель которого выходит за пределы всех разрешённых корней, всё равно отклоняется.
> * **Обработка ошибок**: понятные ошибки для отсутствующих файлов, ошибок разбора, циклических включений, недопустимого формата пути и чрезмерной длины

## Горячая перезагрузка конфигурации

Gateway отслеживает `~/.openclaw/openclaw.json` и автоматически применяет изменения — для большинства настроек ручной перезапуск не требуется.

Прямые изменения файла считаются недоверенными, пока не пройдут проверку. Наблюдатель ожидает
завершения временных операций записи и переименования редактора, считывает итоговый файл и отклоняет
недопустимые внешние изменения, не перезаписывая `openclaw.json`. При записи конфигурации со стороны
OpenClaw перед записью применяется та же проверка схемы (правила перезаписи и отката, применимые
к каждой записи, см. в разделе [Строгая проверка](#strict-validation)).

Если отображается `config reload skipped (invalid config)` или при запуске сообщается `Invalid
config`, проверьте конфигурацию, выполните `openclaw config validate`, а затем для исправления — `openclaw
doctor --fix`. Контрольный список см. в разделе [Устранение неполадок Gateway](https://docs2.openclaw.ai/ru/gateway/troubleshooting.md#gateway-rejected-invalid-config).

### Режимы перезагрузки

| Режим | Поведение |
| - | - |
| **`hybrid`** (по умолчанию) | Мгновенно применяет безопасные изменения без перезапуска. Автоматически перезапускает систему при критических изменениях. |
| **`hot`** | Применяет без перезапуска только безопасные изменения. Если требуется перезапуск, записывает предупреждение в журнал — перезапуск выполняется вручную. |
| **`restart`** | Перезапускает Gateway при любом изменении конфигурации, независимо от его безопасности. |
| **`off`** | Отключает отслеживание файлов. Изменения вступают в силу при следующем ручном перезапуске. |

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}
```

### Какие изменения применяются без перезапуска, а какие требуют его

Большинство полей применяются без перезапуска и простоя; при изменении некоторых разделов
перезапускается только соответствующая подсистема (канал, Cron, Heartbeat, монитор работоспособности),
а не весь Gateway. В режиме `hybrid` изменения, требующие перезапуска Gateway,
обрабатываются автоматически.

| Категория | Поля | Требуется перезапуск Gateway? |
| - | - | - |
| Каналы | `channels.*`, `web` (WhatsApp) — все встроенные каналы и каналы плагинов | Нет (перезапускается этот канал) |
| Агент и модели | `agent`, `agents`, `models`, `routing` | Нет |
| Автоматизация | `hooks`, `cron`, `agent.heartbeat` | Нет (перезапускается эта подсистема) |
| Сеансы и сообщения | `session`, `messages` | Нет |
| Инструменты и медиафайлы | `tools`, `skills`, `mcp`, `audio`, `talk` | Нет |
| Конфигурация плагинов | `plugins.entries.*`, `plugins.allow`, `plugins.deny`, `plugins.enabled` | Нет (среда выполнения плагинов перезагружается) |
| Интерфейс и прочее | `ui`, `logging`, `identity`, `bindings` | Нет |
| Сервер Gateway | `gateway.*` (порт, привязка, аутентификация, Tailscale, TLS, HTTP, push-уведомления) | **Да** |
| Инфраструктура | `discovery`, `browser`, `plugins.load`, `plugins.installs` | **Да** |

> [!NOTE]
>
> `gateway.reload` и `gateway.remote` являются исключениями в разделе `gateway.*` — их изменение **не** вызывает перезапуск. Отдельные плагины также могут переопределять эту таблицу: загруженный плагин может объявить собственные префиксы конфигурации, вызывающие перезапуск (например, встроенный плагин Canvas перезапускает Gateway при изменении `plugins.enabled`, `plugins.allow` и `plugins.deny`, а не только собственного `plugins.entries.canvas`), поэтому фактическое поведение зависит от активных плагинов.

### Планирование перезагрузки

При редактировании исходного файла, указанного через `$include`, OpenClaw планирует
перезагрузку на основе исходной структуры, а не плоского представления в памяти.
Благодаря этому решения о горячей перезагрузке (применение без перезапуска или перезапуск)
остаются предсказуемыми, даже если отдельный раздел верхнего уровня находится в собственном
подключаемом файле, например `plugins: { $include: "./plugins.json5" }`. Если структура
исходных файлов неоднозначна, планирование перезагрузки завершается отказом.

## RPC конфигурации (программные обновления)

Для инструментов, записывающих конфигурацию через API Gateway, предпочтителен следующий порядок:

* `config.schema.lookup` для просмотра одного поддерева (неглубокий узел схемы и сводки
  дочерних элементов)
* `config.get` для получения текущего снимка вместе с `hash`
* `config.patch` для частичных обновлений (объединяющий патч JSON: объекты объединяются, `null`
  удаляет значения, а массивы заменяются после явного подтверждения с помощью `replacePaths`,
  если из них будут удалены элементы)
* `config.apply` только при намеренной замене всей конфигурации
* `update.run` для явного самообновления с перезапуском; добавьте `continuationMessage`, если после перезапуска сеанс должен выполнить ещё один запрос
* `update.status` для просмотра последнего маркера перезапуска после обновления и проверки запущенной версии после перезапуска

Для получения точной документации и ограничений на уровне отдельных полей агентам
следует сначала обращаться к `config.schema.lookup`. Используйте [справочник по конфигурации](https://docs2.openclaw.ai/ru/gateway/configuration-reference.md),
если требуется общая карта конфигурации, значения по умолчанию или ссылки на отдельные
справочники подсистем.

> [!NOTE]
>
> Частота управляющих операций записи (`config.apply`, `config.patch`, `update.run`)
> ограничена 3 запросами за 60 секунд на `deviceId+clientIp`. Запросы на перезапуск
> объединяются, после чего между циклами перезапуска действует 30-секундный период ожидания.
> `update.status` доступен только для чтения, но требует прав администратора, поскольку маркер перезапуска
> может содержать сводки этапов обновления и заключительные фрагменты вывода команд.

Пример частичного патча:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway call config.get --params '{}'  # получить payload.hash
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'
```

Как `config.apply`, так и `config.patch` принимают `raw`, `baseHash`, `sessionKey`,
`note` и `restartDelayMs`. Если файл конфигурации уже существует, `baseHash` обязателен для обоих
методов (при первой записи без существующей конфигурации эта проверка пропускается).

`config.patch` также принимает `replacePaths` — массив путей конфигурации, для которых
замена массива является намеренной. Если патч заменяет или удаляет существующий массив,
оставляя меньше элементов, Gateway отклоняет запись, если соответствующий точный путь
не указан в `replacePaths`; для вложенных массивов внутри элементов массива используется `[]`,
например `agents.list[].skills`. Это предотвращает незаметную перезапись массивов маршрутизации
или списков разрешений усечёнными снимками `config.get`. Используйте `config.apply`,
если требуется заменить всю конфигурацию.

## Переменные окружения

OpenClaw считывает переменные окружения из родительского процесса, а также из следующих источников:

* `.env` из текущего рабочего каталога (при наличии)
* `~/.openclaw/.env` (глобальный резервный источник)

Ни один из этих файлов не переопределяет существующие переменные окружения. Их также можно задать непосредственно в конфигурации:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
```

> [accordion] Импорт окружения оболочки (необязательно)
>
> Если эта функция включена и ожидаемые ключи не заданы, OpenClaw запускает оболочку входа и импортирует только отсутствующие ключи:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   env: {
>     shellEnv: { enabled: true, timeoutMs: 15000 },
>   },
> }
> ```
>
> Эквивалентная переменная окружения: `OPENCLAW_LOAD_SHELL_ENV=1`. Значение `timeoutMs` по умолчанию: `15000`.

> [accordion] Подстановка переменных окружения в значениях конфигурации
>
> Ссылайтесь на переменные окружения в любом строковом значении конфигурации с помощью `${VAR_NAME}`:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
>   models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
> }
> ```
>
> Правила:
>
> * Распознаются только имена в верхнем регистре: `[A-Z_][A-Z0-9_]*`
> * Отсутствующие или пустые переменные вызывают ошибку при загрузке
> * Для буквального вывода экранируйте с помощью `$${VAR}`
> * Работает внутри файлов `$include`
> * Встроенная подстановка: `"${BASE}/v1"` → `"https://api.example.com/v1"`

> [accordion] Ссылки на секреты (окружение, файл, выполнение команды)
>
> Для полей, поддерживающих объекты SecretRef, можно использовать:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   models: {
>     providers: {
>       openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
>     },
>   },
>   skills: {
>     entries: {
>       "image-lab": {
>         apiKey: {
>           source: "file",
>           provider: "filemain",
>           id: "/skills/entries/image-lab/apiKey",
>         },
>       },
>     },
>   },
>   channels: {
>     googlechat: {
>       serviceAccountRef: {
>         source: "exec",
>         provider: "vault",
>         id: "channels/googlechat/serviceAccount",
>       },
>     },
>   },
> }
> ```
>
> Подробные сведения о SecretRef (включая `secrets.providers` для `env`/`file`/`exec`) приведены в разделе [Управление секретами](https://docs2.openclaw.ai/ru/gateway/secrets.md).
> Поддерживаемые пути учётных данных перечислены в разделе [Поверхность учётных данных SecretRef](https://docs2.openclaw.ai/ru/reference/secretref-credential-surface.md).

Полные сведения о приоритетах и источниках см. в разделе [Окружение](https://docs2.openclaw.ai/ru/help/environment.md).

## Полный справочник

Полный справочник по каждому полю см. в разделе **[Справочник по конфигурации](https://docs2.openclaw.ai/ru/gateway/configuration-reference.md)**.

***

*См. также: [Примеры конфигурации](https://docs2.openclaw.ai/ru/gateway/configuration-examples.md) · [Справочник по конфигурации](https://docs2.openclaw.ai/ru/gateway/configuration-reference.md) · [Doctor](https://docs2.openclaw.ai/ru/gateway/doctor.md)*

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

* [Справочник по конфигурации](https://docs2.openclaw.ai/ru/gateway/configuration-reference.md)
* [Примеры конфигурации](https://docs2.openclaw.ai/ru/gateway/configuration-examples.md)
* [Руководство по эксплуатации Gateway](https://docs2.openclaw.ai/ru/gateway.md)