Конфигурация OpenClaw: полный справочник настроек на русском

Конфигурация — это сердце OpenClaw. Один файл ~/.openclaw/openclaw.json определяет, как работает ваш AI-агент: какие каналы подключены, какие модели используются, кто может общаться с ботом и как организованы сессии. В этой статье мы разберём все ключевые аспекты конфигурации OpenClaw на русском языке.

Если вы только начинаете — сначала прочитайте руководство по быстрому старту.

Основы: файл конфигурации

OpenClaw использует формат JSON5 — расширение JSON, которое поддерживает комментарии и висящие запятые. Файл конфигурации расположен по пути:

~/.openclaw/openclaw.json

Если файла нет, OpenClaw работает с безопасными значениями по умолчанию. Основные причины создать конфигурацию:

• Подключить каналы связи (Telegram, WhatsApp, Discord)
• Выбрать AI-модели и настроить резервные варианты
• Определить политики доступа (кто может общаться с ботом)
• Настроить sandboxing, cron-задачи, вебхуки
• Управление сессиями и медиа-файлами

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

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

Способы редактирования конфигурации

OpenClaw предлагает четыре способа изменить настройки:

1. Интерактивный мастер

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

2. CLI-команды (одной строкой)

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

3. Control UI (веб-интерфейс)

Откройте http://127.0.0.1:18789 и используйте вкладку Config. Есть удобная форма и режим редактирования Raw JSON.

4. Прямое редактирование файла

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

Настройка каналов

Каждый канал имеет свой раздел в конфигурации под channels.<provider>. Все каналы используют единый шаблон политики доступа к личным сообщениям:

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

Поддерживаемые каналы: WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Google Chat, Mattermost, MS Teams. Подробнее — в нашей статье о каналах.

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

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

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

Формат ссылок на модели: provider/model (например, anthropic/claude-opus-4-6). Подробнее о моделях — в статье о провайдерах.

Политики доступа: кто может общаться с ботом

Доступ к личным сообщениям контролируется через dmPolicy:

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

Для групп используется groupPolicy + groupAllowFrom с аналогичной логикой.

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

Сессии контролируют непрерывность разговора:

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

Варианты dmScope:

• main — все ЛС в одной сессии (по умолчанию, для одного пользователя)
• per-peer — изоляция по отправителю
• per-channel-peer — изоляция по каналу и отправителю
• per-account-channel-peer — максимальная изоляция

Подробнее — в статье о сессиях.

Sandboxing (изоляция агента)

Для безопасности можно запускать агента в Docker-контейнере:

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

Подробнее — в статье о безопасности.

Heartbeat (периодические проверки)

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

Агент будет «просыпаться» каждые 30 минут и проверять почту, календарь или выполнять другие фоновые задачи.

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

Gateway отслеживает файл конфигурации и применяет изменения автоматически, без перезапуска. Есть четыре режима:

• hybrid (по умолчанию) — безопасные изменения применяются мгновенно, критические перезапускают Gateway автоматически
• hot — только безопасные изменения, для остальных нужен ручной перезапуск
• restart — перезапуск Gateway при любом изменении
• off — отслеживание файла отключено

Большинство настроек применяются «горячо»: каналы, агенты, модели, автоматизация, сессии, инструменты. Перезапуск нужен только для gateway.* (порт, привязка, аутентификация, TLS).

Разделение конфигурации на файлы

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

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

Поддерживается до 10 уровней вложенности, относительные пути и понятные сообщения об ошибках.

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

Можно запустить несколько агентов с отдельными рабочими пространствами:

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