--- read_when: - Первоначальная настройка OpenClaw - Поиск распространённых шаблонов конфигурации - Переход к определённым разделам конфигурации summary: 'Обзор конфигурации: распространённые задачи, быстрая настройка и ссылки на полное справочное руководство' title: Конфигурация x-i18n: generated_at: "2026-07-16T16:21:36Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: 77f45ec71032ad6f651fcb68f9fb37f6677de90ec5ccca33ee84794056c58f89 source_path: gateway/configuration.md workflow: 16 --- OpenClaw считывает необязательную конфигурацию **JSON5** из `~/.openclaw/openclaw.json`. Если файл отсутствует, OpenClaw использует безопасные значения по умолчанию. Активный путь конфигурации должен указывать на обычный файл. При записи OpenClaw атомарно заменяет его (переименовывая файл в указанный путь), поэтому для `openclaw.json`, являющегося символической ссылкой, будет заменён целевой файл, а не выполнена сквозная запись — избегайте конфигураций с символическими ссылками. Если конфигурация хранится вне каталога состояния по умолчанию, задайте в `OPENCLAW_CONFIG_PATH` прямой путь к фактическому файлу. Распространённые причины добавить конфигурацию: - Подключить каналы и настроить, кто может отправлять сообщения боту - Настроить модели, инструменты, изоляцию или автоматизацию (cron, хуки) - Настроить сеансы, медиа, сеть или пользовательский интерфейс Все доступные поля описаны в [полном справочнике](/ru/gateway/configuration-reference). Перед изменением конфигурации агенты и средства автоматизации должны использовать `config.schema.lookup` для получения точной документации по отдельным полям. Эта страница содержит практические инструкции, а [справочник по конфигурации](/ru/gateway/configuration-reference) — более полную карту полей и значений по умолчанию. **Впервые настраиваете конфигурацию?** Начните с `openclaw onboard` для интерактивной настройки или ознакомьтесь с руководством [«Примеры конфигурации»](/ru/gateway/configuration-examples), содержащим готовые конфигурации для копирования. ## Минимальная конфигурация ```json5 // ~/.openclaw/openclaw.json { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, channels: { whatsapp: { allowFrom: ["+15555550123"] } }, } ``` ## Редактирование конфигурации ```bash openclaw onboard # полный процесс первоначальной настройки openclaw configure # мастер конфигурации ``` ```bash openclaw config get agents.defaults.workspace openclaw config set agents.defaults.heartbeat.every "2h" openclaw config unset plugins.entries.brave.config.webSearch.apiKey ``` Откройте [http://127.0.0.1:18789](http://127.0.0.1:18789) и перейдите на вкладку **Config**. Панель управления формирует форму на основе актуальной схемы конфигурации, включая метаданные документации полей `title` / `description`, а также схемы плагинов и каналов, если они доступны, и предоставляет редактор **Raw JSON** как резервный вариант. Для интерфейсов с детализацией и других инструментов Gateway также предоставляет `config.schema.lookup`, позволяющий получить один узел схемы для заданного пути и сводные данные о его непосредственных дочерних элементах. Отредактируйте `~/.openclaw/openclaw.json` напрямую. Gateway отслеживает файл и автоматически применяет изменения (см. [горячую перезагрузку](#config-hot-reload)). ## Строгая проверка 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 не запускается либо перезагрузка пропускается, а текущая среда выполнения продолжает использовать последнюю принятую конфигурацию. Отклонённая запись также сохраняется как `.rejected.` для анализа. Gateway блокирует записи, похожие на случайную перезапись: удаление `gateway.mode`, потерю блока `meta` или сокращение файла более чем наполовину, — если запись явно не разрешает деструктивные изменения. Кандидат не становится последней работоспособной конфигурацией, если он содержит отредактированный заполнитель секрета, например `***` или `[redacted]`. ## Распространённые задачи У каждого канала есть собственный раздел конфигурации в `channels.`. Шаги настройки приведены на странице соответствующего канала: - [Discord](/ru/channels/discord) — `channels.discord` - [Feishu](/ru/channels/feishu) — `channels.feishu` - [Google Chat](/ru/channels/googlechat) — `channels.googlechat` - [iMessage](/ru/channels/imessage) — `channels.imessage` - [Mattermost](/ru/channels/mattermost) — `channels.mattermost` - [Microsoft Teams](/ru/channels/msteams) — `channels.msteams` - [Signal](/ru/channels/signal) — `channels.signal` - [Slack](/ru/channels/slack) — `channels.slack` - [Telegram](/ru/channels/telegram) — `channels.telegram` - [WhatsApp](/ru/channels/whatsapp) — `channels.whatsapp` Все каналы используют одинаковую схему политики личных сообщений: ```json5 { channels: { telegram: { enabled: true, botToken: "123:abc", dmPolicy: "pairing", // pairing | allowlist | open | disabled allowFrom: ["tg:123"], // только для allowlist/open }, }, } ``` Задайте основную модель и необязательные резервные модели: ```json5 { 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 '' --strict-json --merge`, чтобы добавлять записи в список разрешений без удаления существующих моделей. Простые замены, удаляющие записи, отклоняются, если не передан `--replace`. - Ссылки на модели используют формат `provider/model` (например, `anthropic/claude-opus-4-6`). - `agents.defaults.imageMaxDimensionPx` управляет уменьшением масштаба изображений в расшифровках и инструментах (по умолчанию `1200`); меньшие значения обычно сокращают расход токенов компьютерного зрения при выполнении задач с большим количеством снимков экрана. - Сведения о переключении моделей в чате см. в разделе [CLI моделей](/ru/concepts/models), а о ротации аутентификации и поведении резервных моделей — в разделе [Переключение при отказе модели](/ru/concepts/model-failover). - Сведения о пользовательских и самостоятельно размещённых поставщиках см. в разделе [Пользовательские поставщики](/ru/gateway/config-tools#custom-providers-and-base-urls) справочника. Доступ к личным сообщениям настраивается отдельно для каждого канала через `dmPolicy` (по умолчанию `"pairing"`): - `"pairing"`: неизвестные отправители получают одноразовый код сопряжения для подтверждения - `"allowlist"`: разрешены только отправители из `allowFrom` (или из хранилища разрешённых сопряжений) - `"open"`: разрешить все входящие личные сообщения (требуется `allowFrom: ["*"]`) - `"disabled"`: игнорировать все личные сообщения Для групп используйте `groupPolicy` (`"allowlist" | "open" | "disabled"`) вместе с `groupAllowFrom` или списками разрешений для конкретных каналов. Подробности для каждого канала приведены в [полном справочнике](/ru/gateway/config-channels#dm-and-group-access). По умолчанию групповые сообщения **требуют упоминания**. Настройте шаблоны срабатывания отдельно для каждого агента. Обычные ответы в группах и каналах публикуются автоматически; для общих комнат, где агент должен сам решать, когда отвечать, включите использование инструмента сообщений: ```json5 { 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` переопределяет это для групп и каналов. - Режимы видимых ответов, переопределения для отдельных каналов и режим чата с самим собой описаны в [полном справочнике](/ru/gateway/config-channels#group-chat-mention-gating). Используйте `agents.defaults.skills` как общую базовую конфигурацию, а затем переопределяйте её для отдельных агентов с помощью `agents.list[].skills`: ```json5 { 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](/ru/tools/skills), [конфигурацию Skills](/ru/tools/skills-config) и [справочник по конфигурации](/ru/gateway/config-agents#agents-defaults-skills). Настройте интенсивность перезапуска каналов, которые выглядят неактивными: ```json5 { gateway: { channelHealthCheckMinutes: 5, channelStaleEventThresholdMinutes: 30, channelMaxRestartsPerHour: 10, }, channels: { telegram: { healthMonitor: { enabled: false }, accounts: { alerts: { healthMonitor: { enabled: true }, }, }, }, }, } ``` - Показанные значения используются по умолчанию. Задайте `gateway.channelHealthCheckMinutes: 0`, чтобы глобально отключить перезапуски по результатам мониторинга состояния. - `channelStaleEventThresholdMinutes` должно быть больше или равно интервалу проверки. - Используйте `channels..healthMonitor.enabled` или `channels..accounts..healthMonitor.enabled`, чтобы отключить автоматические перезапуски для отдельного канала или учётной записи, не отключая глобальный мониторинг. - Сведения об эксплуатационной диагностике см. в разделе [«Проверки состояния»](/ru/gateway/health), а описание всех полей — в [полном справочнике](/ru/gateway/configuration-reference#gateway). Предоставьте локальным клиентам больше времени для завершения предварительного WebSocket-рукопожатия до аутентификации на загруженных или маломощных узлах: ```json5 { gateway: { handshakeTimeoutMs: 30000, }, } ``` - По умолчанию — `15000` миллисекунд. - `OPENCLAW_HANDSHAKE_TIMEOUT_MS` по-прежнему имеет приоритет для разовых переопределений службы или оболочки. - Сначала рекомендуется устранить задержки при запуске или в цикле событий; этот параметр предназначен для исправных хостов, которые медленно прогреваются. Сеансы управляют непрерывностью и изоляцией диалогов: ```json5 { 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 — темы или диалоги). - Сведения об областях действия, связях идентификаторов и политике отправки см. в разделе [Управление сеансами](/ru/concepts/session). - Все поля см. в [полном справочнике](/ru/gateway/config-agents#session). Запускайте сеансы агентов в изолированных средах песочницы: ```json5 { agents: { defaults: { sandbox: { mode: "non-main", // off | non-main | all scope: "agent", // session | agent | shared }, }, }, } ``` Сначала соберите образ: из рабочей копии исходного кода выполните `scripts/sandbox-setup.sh`, а при установке из npm см. встроенную команду `docker build` в разделе [Песочница § Образы и настройка](/ru/gateway/sandboxing#images-and-setup). Полное руководство см. в разделе [Песочница](/ru/gateway/sandboxing), а все параметры — в [полном справочнике](/ru/gateway/config-agents#agentsdefaultssandbox). Для push-уведомлений в общедоступных сборках из App Store используется размещённый ретранслятор OpenClaw: `https://ios-push-relay.openclaw.ai`. Для собственных развёртываний ретранслятора требуется намеренно отдельный путь сборки и развёртывания iOS, в котором URL ретранслятора совпадает с URL ретранслятора Gateway. Если используется собственная сборка с ретранслятором, задайте в конфигурации Gateway следующее: ```json5 { gateway: { push: { apns: { relay: { baseUrl: "https://relay.example.com", // Необязательно. По умолчанию: 10000 timeoutMs: 10000, }, }, }, }, } ``` Эквивалентная команда CLI: ```bash 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](/ru/platforms/ios#relay-backed-push-for-official-builds), а модель безопасности ретранслятора — в разделе [Процесс аутентификации и установления доверия](/ru/platforms/ios#authentication-and-trust-flow). ```json5 { agents: { defaults: { heartbeat: { every: "30m", target: "last", }, }, }, } ``` - `every`: строка длительности (`30m`, `2h`). Чтобы отключить, задайте `0m`. По умолчанию: `30m`. - `target`: `last` | `none` | `` (например, `discord`, `matrix`, `telegram` или `whatsapp`) - `directPolicy`: `allow` (по умолчанию) или `block` для целей Heartbeat в стиле личных сообщений - Полное руководство см. в разделе [Heartbeat](/ru/gateway/heartbeat). ```json5 { cron: { enabled: true, maxConcurrentRuns: 8, // по умолчанию; диспетчеризация cron + изолированное выполнение хода агента cron sessionRetention: "24h", }, } ``` - `sessionRetention`: удаляет завершённые изолированные сеансы запусков из строк сеансов SQLite (по умолчанию `24h`; чтобы отключить, задайте `false`). - В истории запусков автоматически сохраняются 2000 новейших конечных строк для каждого задания; для потерянных строк сохраняется 24-часовое окно очистки. - Обзор возможностей и примеры CLI см. в разделе [Задания Cron](/ru/automation/cron-jobs). Включите конечные точки HTTP-вебхуков на Gateway: ```json5 { 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 см. в [полном справочнике](/ru/gateway/configuration-reference#hooks). Запускайте несколько изолированных агентов с отдельными рабочими пространствами и сеансами: ```json5 { 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" } }, ], } ``` Правила привязки и профили доступа отдельных агентов см. в разделах [Несколько агентов](/ru/concepts/multi-agent) и [полный справочник](/ru/gateway/config-agents#multi-agent-routing). Используйте `$include` для организации больших конфигураций: ```json5 // ~/.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](/ru/gateway/troubleshooting#gateway-rejected-invalid-config). ### Режимы перезагрузки | Режим | Поведение | | ---------------------- | --------------------------------------------------------------------------------------- | | **`hybrid`** (по умолчанию) | Мгновенно применяет безопасные изменения без перезапуска. Автоматически перезапускает систему при критических изменениях. | | **`hot`** | Применяет без перезапуска только безопасные изменения. Если требуется перезапуск, записывает предупреждение в журнал — перезапуск выполняется вручную. | | **`restart`** | Перезапускает Gateway при любом изменении конфигурации, независимо от его безопасности. | | **`off`** | Отключает отслеживание файлов. Изменения вступают в силу при следующем ручном перезапуске. | ```json5 { 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` | **Да** | `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`. Используйте [справочник по конфигурации](/ru/gateway/configuration-reference), если требуется общая карта конфигурации, значения по умолчанию или ссылки на отдельные справочники подсистем. Частота управляющих операций записи (`config.apply`, `config.patch`, `update.run`) ограничена 3 запросами за 60 секунд на `deviceId+clientIp`. Запросы на перезапуск объединяются, после чего между циклами перезапуска действует 30-секундный период ожидания. `update.status` доступен только для чтения, но требует прав администратора, поскольку маркер перезапуска может содержать сводки этапов обновления и заключительные фрагменты вывода команд. Пример частичного патча: ```bash openclaw gateway call config.get --params '{}' # получить payload.hash openclaw gateway call config.patch --params '{ "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }", "baseHash": "" }' ``` Как `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 { env: { OPENROUTER_API_KEY: "sk-or-...", vars: { GROQ_API_KEY: "gsk-..." }, }, } ``` Если эта функция включена и ожидаемые ключи не заданы, OpenClaw запускает оболочку входа и импортирует только отсутствующие ключи: ```json5 { env: { shellEnv: { enabled: true, timeoutMs: 15000 }, }, } ``` Эквивалентная переменная окружения: `OPENCLAW_LOAD_SHELL_ENV=1`. Значение `timeoutMs` по умолчанию: `15000`. Ссылайтесь на переменные окружения в любом строковом значении конфигурации с помощью `${VAR_NAME}`: ```json5 { 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"` Для полей, поддерживающих объекты SecretRef, можно использовать: ```json5 { 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`) приведены в разделе [Управление секретами](/ru/gateway/secrets). Поддерживаемые пути учётных данных перечислены в разделе [Поверхность учётных данных SecretRef](/ru/reference/secretref-credential-surface). Полные сведения о приоритетах и источниках см. в разделе [Окружение](/ru/help/environment). ## Полный справочник Полный справочник по каждому полю см. в разделе **[Справочник по конфигурации](/ru/gateway/configuration-reference)**. --- _См. также: [Примеры конфигурации](/ru/gateway/configuration-examples) · [Справочник по конфигурации](/ru/gateway/configuration-reference) · [Doctor](/ru/gateway/doctor)_ ## Связанные материалы - [Справочник по конфигурации](/ru/gateway/configuration-reference) - [Примеры конфигурации](/ru/gateway/configuration-examples) - [Руководство по эксплуатации Gateway](/ru/gateway)