Вопрос

Где лежит конфиг OpenClaw и как его править

Разберёмся, в каком файле живёт конфиг и почему ручная правка иногда не применяется, и что делать вместо неё.

· 4 мин чтения

Коротко

  • Конфиг — это ~/.openclaw/openclaw.json в формате JSON5, путь можно переопределить через OPENCLAW_CONFIG_PATH.
  • Правьте через CLI или Control UI: записи проходят ту же строгую валидацию, что и при старте Gateway.
  • Gateway сам следит за файлом и применяет большинство изменений на лету, но часть секций всё равно требует рестарта.
  • Если конфиг невалиден, Gateway не стартует. Лечит openclaw doctor --fix, бэкап остаётся в .bak.

Сверено с документацией OpenClaw 2026.9.7, 2 октября 2026.

OpenClaw держит конфиг в одном файле, это ~/.openclaw/openclaw.json в формате JSON5. Если файла нет, Gateway стартует с безопасными значениями по умолчанию. Сам файл подменять симлинком нельзя: при записи OpenClaw атомарно переименовывает временный файл поверх цели, и симлинк будет заменён, а не пройдёт насквозь. Если держите конфиг вне дефолтной директории состояния, укажите путь переменной OPENCLAW_CONFIG_PATH прямо на нужный файл.

Где лежит и как разделён

Корень файла и секция agents.defaults — это два разных слоя. На верхнем уровне живёт инфраструктура и общие для всех агентов значения: каналы, модели, инструменты, песочница, автоматизация, сеть, UI. В agents.defaults лежит поведение цикла агента. Записи в agents.entries могут перекрывать оба слоя там, где схема это разрешает. Для правок агентов предпочитайте пути agents.entries.<id>.

Как править

Откройте Control UI на http://127.0.0.1:18789: вкладка Config строит форму по живой схеме, рядом есть редактор Raw JSON. Из терминала то же самое делают команды openclaw config: get, set, unset, patch, validate, schema, file. Команда без подкоманды открывает тот же визард, что и openclaw configure.

openclaw config file
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config set 'agents.entries.work.tools.exec.node' "node-id-or-name"
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
openclaw config validate

Запись в файл проходит строгую валидацию: неизвестные ключи, неверные типы и значения заставляют Gateway отказаться стартовать. Единственное корневое исключение — поле $schema (строка), чтобы редакторы могли подцепить JSON Schema. Если в файле остались старые ключи, openclaw doctor --fix чинит их теми же детерминированными миграциями, что и старт, и пишет только когда вся конфигурация валидна. Бэкап остаётся в .bak.

Что применяется на лету, а что нет

Gateway следит за файлом и применяет большинство правок сам, в режиме hybrid по умолчанию. Прямые правки файла считаются недоверенными, пока не пройдут валидацию: адаптер ждёт, пока редактор закончит временную запись и переименование, читает итог и отбрасывает невалидное, не переписывая файл. Записи через сам Gateway идут быстрее: снимок публикуется владельцу перезагрузки напрямую, без ожидания наблюдателя за файлом.

Каждое изменение классифицируется по самому длинному совпавшему префиксу: restart — перезапустить процесс, hot — применить без перезапуска (иногда с перезапуском подсистемы вроде канала или cron), none — обновить снимок без активного действия. По умолчанию без правила плагина путь уходит в перезапуск Gateway. Устаревшие режимы hot и restart doctor --fix сводит к hybrid.

Когда правка не доходит

Если конфиг невалиден, Gateway не стартует. Работают только диагностические команды: openclaw doctor, openclaw logs, openclaw health, openclaw status. Запустите openclaw doctor --fix (он же --repair, с --yes пропускает подтверждения). Gateway хранит последнюю удачную копию, но сам её не восстанавливает — это делает только doctor --fix.

Отдельно проверьте две вещи. OPENCLAW_CONFIG_READONLY=1 или OPENCLAW_NIX_MODE=1 делают файл неизменяемым: команды чтения (get, file, schema, validate) работают, любые записи блокируются. Это переменная окружения хоста, а не поле в JSON, в env.vars её класть бесполезно. И второй сценарий: вы выбрали рабочую директорию с устаревшим состоянием настройки. Gateway откажет в перезагрузке и оставит прошлый рабочий снимок, подсказка будет в логе вместе с командой openclaw doctor --fix.

Частые ошибки

  • Правите ~/.openclaw/openclaw.json, а система управления развёртыванием выставляет OPENCLAW_CONFIG_READONLY=1 или OPENCLAW_NIX_MODE=1: записи блокируются, читается всё ещё старое.
  • Симлинк на конфиг. OpenClaw перезапишет сам симлинк атомарным переименованием, вы потеряете ссылку. Положите реальный файл и при необходимости укажите OPENCLAW_CONFIG_PATH.
  • Правят только корень, а нужное поле перекрыто в agents.entries.<id>.
  • Сначала openclaw config validate, иначе наблюдатель за файлом отбросит невалидный файл и оставит прошлый снимок.
  • Меняют канал или провайдера авторизации. Смотрите в логе режим изменения: для каналов и web (WhatsApp) решение о перезапуске зависит от настройки и плагина.