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

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

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

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

Новичкам в конфигурации? Начните с openclaw onboard для интерактивной настройки или посмотрите руководство Configuration Examples с готовыми конфигами для копирования.

Минимальный конфиг

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

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

Интерактивный мастер
CLI (однострочники)
Control UI
Прямое редактирование

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

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset tools.web.search.apiKey

Отредактируйте ~/.openclaw/openclaw.json напрямую. Gateway отслеживает файл и автоматически применяет изменения (см. горячую перезагрузку).

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

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

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

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

Частые задачи

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

У каждого канала свой раздел конфигурации в channels.<provider>. См. страницу нужного канала:

WhatsApp — channels.whatsapp
Telegram — channels.telegram
Discord — channels.discord
Slack — channels.slack
Signal — channels.signal
iMessage — channels.imessage
Google Chat — channels.googlechat
Mattermost — channels.mattermost
MS Teams — channels.msteams

Все каналы используют одинаковый шаблон политики DM:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // только для allowlist/open
    },
  },
}

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

Укажите основную модель и резервные:

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}

agents.defaults.models определяет каталог моделей и действует как allowlist для /model.
Ссылки на модели используют формат provider/model (например, anthropic/claude-opus-4-6).
См. Models CLI для переключения моделей в чате и Model Failover для ротации авторизации и fallback-поведения.
Для кастомных/self-hosted провайдеров см. Custom providers.

Управлять тем, кто может писать боту

Доступ к DM настраивается отдельно для каждого канала через dmPolicy:

"pairing" (по умолчанию): неизвестные отправители получают одноразовый код подтверждения
"allowlist": только отправители из allowFrom (или из хранилища сопряжений)
"open": разрешить все входящие DM (требуется allowFrom: ["*"])
"disabled": игнорировать все DM

Для групп используйте groupPolicy + groupAllowFrom или allowlist’ы конкретного канала.См. полный справочник.

Настроить gating упоминаний в группах

По умолчанию сообщения в группах требуют упоминания. Настройка на уровне агента:

{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

Metadata mentions: нативные @‑упоминания (WhatsApp tap-to-mention, Telegram @bot и т. д.)
Text patterns: regex-шаблоны в mentionPatterns
См. полный справочник.

Настроить сессии и сбросы

Сессии управляют непрерывностью диалога и изоляцией:

{
  session: {
    dmScope: "per-channel-peer",  // рекомендуется для нескольких пользователей
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}

dmScope: main | per-peer | per-channel-peer | per-account-channel-peer
См. Session Management и полный справочник.

Включить песочницу (sandbox)

Запускать сессии агента в изолированных Docker-контейнерах:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}

Сначала соберите образ: scripts/sandbox-setup.shСм. Sandboxing и полный справочник.

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

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}

every: строка длительности (30m, 2h). Установите 0m, чтобы отключить.
target: last | whatsapp | telegram | discord | none
См. Heartbeat.

Настроить cron-задачи

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
  },
}

См. Cron jobs.

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

Включить HTTP-вебхуки на Gateway:

{
  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,
      },
    ],
  },
}

См. полный справочник.

Мультиагентная маршрутизация

Запуск нескольких изолированных агентов с разными workspace и сессиями:

{
  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" } },
  ],
}

См. Multi-Agent и полный справочник.

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

Используйте $include для организации больших конфигов:

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}

Один файл: заменяет содержащий объект
Массив файлов: глубокое слияние по порядку (поздние переопределяют ранние)
Соседние ключи: объединяются после include (переопределяют значения)
Вложенные include: поддерживаются до 10 уровней
Относительные пути: относительно включающего файла
Ошибки: понятные сообщения для отсутствующих файлов, ошибок парсинга и циклов include

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

Gateway отслеживает ~/.openclaw/openclaw.json и автоматически применяет изменения — перезапуск вручную обычно не требуется.

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

Режим	Поведение
`hybrid` (по умолчанию)	Безопасные изменения применяются сразу. Критические — с автоперезапуском.
`hot`	Применяются только безопасные изменения. При необходимости перезапуска выводится предупреждение.
`restart`	Gateway перезапускается при любом изменении конфига.
`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	`gateway.*` (port, bind, auth, tailscale, TLS, HTTP)	Да
Инфраструктура	`discovery`, `canvasHost`, `plugins`	Да

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

Environment variables

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

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

Ни один .env не переопределяет уже существующие переменные окружения. Можно также задать inline‑переменные в конфиге:

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

Импорт env из shell (опционально)

Если включено и ожидаемые ключи не заданы, OpenClaw запускает login-shell и импортирует только отсутствующие переменные:

{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}

Эквивалент через env: OPENCLAW_LOAD_SHELL_ENV=1

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

Ссылаться на env-переменные можно в любом строковом значении через ${VAR_NAME}:

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

Правила:

Поддерживаются только имена в верхнем регистре: [A-Z_][A-Z0-9_]*
Отсутствующие/пустые переменные вызывают ошибку загрузки
Экранирование: $${VAR} для вывода литерала
Работает внутри $include
Inline-подстановка: "${BASE}/v1" → "https://api.example.com/v1"

См. Environment для полного порядка приоритета.

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

Для полного описания всех полей см. Configuration Reference.

Связано: Configuration Examples · Configuration Reference · Doctor

Шлюз

Удалённый доступ

Веб-интерфейсы

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

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

Минимальный конфиг

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

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

Частые задачи

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

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

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

Environment variables

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

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

​Минимальный конфиг

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

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

​Частые задачи

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

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

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

​Environment variables

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

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

Минимальный конфиг

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

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

Частые задачи

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

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

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

Environment variables

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