Конфигурация и операции

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

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

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

См. полный справочник для всех доступных полей.

💡 Новичок в настройке? Начните с openclaw onboard для интерактивной настройки или ознакомьтесь с руководством Примеры конфигураций для готовых конфигураций, которые можно скопировать и вставить.

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

// ~/.openclaw/openclaw.json
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

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

openclaw onboard       # полный мастер настройки
openclaw configure     # мастер конфигурации

Строгая валидация

⚠️ OpenClaw принимает только конфигурации, полностью соответствующие схеме. Неизвестные ключи, неправильные типы или недопустимые значения приводят к отказу шлюза запускаться. Единственное исключение на корневом уровне — $schema (строка), чтобы редакторы могли прикреплять метаданные JSON Schema.

При сбое валидации:

Шлюз не запускается
Работают только диагностические команды (openclaw doctor, openclaw logs, openclaw health, openclaw status)
Запустите openclaw doctor, чтобы увидеть точные проблемы
Запустите openclaw doctor --fix (или --yes), чтобы применить исправления

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

Настройка канала (WhatsApp, Telegram, Discord и т.д.)

Выбор и настройка моделей

Контроль того, кто может писать боту

Настройка упоминаний в групповых чатах

Настройка сессий и сбросов

Включение изоляции (sandboxing)

Настройка heartbeat (периодических проверок)

Настройка cron-задач

Настройка вебхуков (hooks)

Настройка маршрутизации между несколькими агентами

Разделение конфигурации на несколько файлов ($include)

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

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

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

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

{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

Что применяется "на горячую", а что требует перезапуска

Большинство полей применяются "на горячую" без простоя. В режиме hybrid изменения, требующие перезапуска, обрабатываются автоматически.

Категория	Поля	Требуется перезапуск?
Каналы	`channels.*`, `web` (WhatsApp) — все встроенные и расширенные каналы	Нет
Агенты и модели	`agent`, `agents`, `models`, `routing`	Нет
Автоматизация	`hooks`, `cron`, `agent.heartbeat`	Нет
Сессии и сообщения	`session`, `messages`	Нет
Инструменты и медиа	`tools`, `browser`, `skills`, `audio`, `talk`	Нет
UI и прочее	`ui`, `logging`, `identity`, `bindings`	Нет
Сервер шлюза	`gateway.*` (порт, привязка, аутентификация, tailscale, TLS, HTTP)	Да
Инфраструктура	`discovery`, `canvasHost`, `plugins`	Да

ℹ️ gateway.reload и gateway.remote являются исключениями — их изменение не вызывает перезапуск.

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

ℹ️ RPC-запросы на запись в плоскость управления (config.apply, config.patch, update.run) ограничены частотой 3 запроса в 60 секунд на deviceId+clientIp. При ограничении RPC возвращает UNAVAILABLE с retryAfterMs.

config.apply (полная замена)

config.patch (частичное обновление)

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

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

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

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

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}

Импорт из оболочки (опционально)

Подстановка переменных окружения в значениях конфигурации

Ссылки на секреты (env, file, exec)

См. Окружение для полного порядка приоритета и источников.

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

Для полного пошагового справочника см. Справочник по конфигурации.

Связанные темы: Примеры конфигураций · Справочник по конфигурации · Doctor

Ранбук шлюза Справочник по конфигурации