Перейти к основному содержанию

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

OpenClaw читает необязательный -конфиг из ~/.openclaw/openclaw.json. Если файл отсутствует, OpenClaw использует безопасные значения по умолчанию. Частые причины добавить конфиг:
  • Подключить каналы и управлять тем, кто может писать боту
  • Настроить модели, инструменты, песочницу или автоматизацию (cron, hooks)
  • Тонко настроить сессии, медиа, сеть или UI
См. полный справочник для всех доступных полей.
Новичкам в конфигурации? Начните с openclaw onboard для интерактивной настройки или посмотрите руководство Configuration Examples с готовыми конфигами для копирования.

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

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

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

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

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

OpenClaw принимает только конфигурации, полностью соответствующие схеме. Неизвестные ключи, неверные типы или недопустимые значения приводят к тому, что Gateway отказывается запускаться. Единственное исключение на корневом уровне — $schema (string), чтобы редакторы могли подключать JSON Schema.
При ошибке валидации:
  • Gateway не запускается
  • Работают только диагностические команды (openclaw doctor, openclaw logs, openclaw health, openclaw status)
  • Запустите openclaw doctor, чтобы увидеть точные проблемы
  • Запустите openclaw doctor --fix (или --yes) для автоматического исправления

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

У каждого канала свой раздел конфигурации в channels.<provider>. См. страницу нужного канала:Все каналы используют одинаковый шаблон политики 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’ы конкретного канала.См. полный справочник.
По умолчанию сообщения в группах требуют упоминания. Настройка на уровне агента:
{
  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,
    },
  },
}
Запускать сессии агента в изолированных Docker-контейнерах:
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}
Сначала соберите образ: scripts/sandbox-setup.shСм. Sandboxing и полный справочник.
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
  • every: строка длительности (30m, 2h). Установите 0m, чтобы отключить.
  • target: last | whatsapp | telegram | discord | none
  • См. Heartbeat.
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
  },
}
См. Cron jobs.
Включить 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 для организации больших конфигов:
// ~/.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Применяются только безопасные изменения. При необходимости перезапуска выводится предупреждение.
restartGateway перезапускается при любом изменении конфига.
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Нет
Сервер Gatewaygateway.* (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-..." },
  },
}
Если включено и ожидаемые ключи не заданы, OpenClaw запускает login-shell и импортирует только отсутствующие переменные:
{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}
Эквивалент через env: OPENCLAW_LOAD_SHELL_ENV=1
Ссылаться на 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