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

Конфигурация OpenClaw хранится в файле ~/.openclaw/openclaw.json. Формат — JSON5 (поддерживает комментарии и запятые на конце). Если файла нет, используются безопасные настройки по умолчанию.

Зачем нужна конфигурация

Как редактировать

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

openclaw configure

Через CLI (однострочники):

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset plugins.entries.brave.config.webSearch.apiKey

Через Control UI: откройте http://127.0.0.1:18789 → вкладка Config.

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

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

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

Выбор модели

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

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },
        "openai/gpt-5.4": { alias: "gpt" },
      },
    },
  },
}

Формат: провайдер/модель. models — каталог и allowlist для /model в чате.

Каналы

Каждый канал имеет свою секцию в конфиге. Политика доступа (dmPolicy):

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      allowFrom: ["tg:123"],
    },
  },
}

Подробнее: Telegram, Discord, WhatsApp, Все каналы

Групповые чаты

По умолчанию бот реагирует только на упоминания:

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

Сессии

{
  session: {
    dmScope: "per-channel-peer",
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}

Режимы dmScope: main (общий), per-peer, per-channel-peer, per-account-channel-peer.

MCP

OpenClaw может подключаться к MCP-серверам как клиент:

{
  mcp: {
    sessionIdleTtlMs: 600000, // 10 минут, 0 = отключить
    servers: {
      docs: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-fetch"],
      },
      remote: {
        url: "https://example.com/mcp",
        transport: "streamable-http",
        headers: { Authorization: "Bearer ${MCP_REMOTE_TOKEN}" },
      },
    },
  },
}

Управление: openclaw mcp list, openclaw mcp show, openclaw mcp set.

Skills

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: { extraDirs: ["~/Projects/agent-scripts/skills"] },
    entries: {
      "image-lab": { apiKey: "GEMINI_KEY_HERE" },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

Плагины

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    entries: {
      "voice-call": {
        enabled: true,
        config: { provider: "twilio" },
      },
    },
  },
}

Плагины загружаются из ~/.openclaw/extensions, <workspace>/.openclaw/extensions и plugins.load.paths. Изменения требуют перезапуска Gateway.

Browser

{
  browser: {
    enabled: true,
    defaultProfile: "openclaw",
    profiles: {
      openclaw: { cdpPort: 18800 },
      user: { driver: "existing-session", attachOnly: true },
    },
  },
}

Повторная отправка (retry)

OpenClaw автоматически повторяет неудачные HTTP-запросы к каналам (отправка сообщений, загрузка медиа, реакции). Повтор применяется к каждому отдельному запросу, а не к многошаговому потоку.

Значения по умолчанию

Поведение по каналам

Discord: повтор только при ошибках rate-limit (HTTP 429). Использует Discord retry_after, если доступен; иначе экспоненциальный backoff.

Telegram: повтор при транзиентных ошибках (429, timeout, connect/reset/closed, temporarily unavailable). Ошибки парсинга Markdown не повторяются — fallback на plain text.

Настройка

{
  channels: {
    telegram: {
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

Очередь сообщений

OpenClaw сериализует автоматические ответы через in-process очередь, предотвращая столкновение нескольких запусков агента при одновременном поступлении сообщений.

Режимы очереди

Настройка

{
  messages: {
    queue: {
      mode: "collect",
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",
      byChannel: { discord: "collect" },
    },
  },
}

Параметры: debounceMs — ждать тишины перед запуском followup; cap — максимум сообщений в очереди; drop — политика переполнения (old, new, summarize).

Per-session: команда /queue <mode> в чате. Сброс: /queue default.

Heartbeat

Heartbeat — периодический запуск агента для фоновых задач (проверка почты, календаря, напоминаний). По умолчанию — каждые 30 минут.

Быстрый старт

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

target: "last" — отправлять последнему контакту. "none" — по умолчанию (не отправлять).

Полный конфиг

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        model: "anthropic/claude-sonnet-4-6",
        target: "last",
        lightContext: true,
        isolatedSession: true,
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "Europe/Moscow",
        },
      },
    },
  },
}

Ключевые параметры

• every — интервал (строка, например "30m", "1h"). "0m" отключает.
• lightContext: true — загружать только HEARTBEAT.md, экономя токены.
• isolatedSession: true — каждый heartbeat в новой сессии без истории.
• activeHours — ограничение по времени (start/end/timezone).
• prompt — переопределяет промпт по умолчанию.

Контракт ответа

Если ничего не требует внимания, агент отвечает HEARTBEAT_OK. Этот токен удаляется, а ответ отбрасывается. Для оповещений — возвращайте только текст без HEARTBEAT_OK.

Per-agent heartbeat

Если любой агент в agents.list[] включает блок heartbeat, только эти агенты запускают heartbeat:

{
  agents: {
    list: [
      { id: "main", default: true },
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "whatsapp",
          to: "+15551234567",
        },
      },
    ],
  },
}

Логирование

Файловые логи

Ротирующийся журнал по умолчанию: /tmp/openclaw/openclaw-YYYY-MM-DD.log (один файл в день, JSON по строке).

{
  logging: {
    level: "info",       // debug | info | warn | error
    file: "/var/log/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty",  // pretty | compact | json
  },
}

Просмотр: openclaw logs --follow. В Control UI → вкладка Logs.

Verbose vs уровни

• --verbose влияет только на консоль, не на файловый журнал.
• Чтобы захватить verbose в файл: logging.level: "debug".

Сокрытие чувствительных данных

logging.redactSensitive: "tools" (по умолчанию) маскирует токены в сводках инструментов. Отключить: "off".

WebSocket-логи

Без --verbose: только ошибки и медленные вызовы (≥50 мс). С --verbose: весь WS-трафик.

openclaw gateway --verbose --ws-log compact  # парный вывод
openclaw gateway --verbose --ws-log full     # полные метаданные

Диагностика и OpenTelemetry

Диагностика — структурированные события для запусков моделей и телеметрии потока сообщений. Не заменяет логи; питает метрики, трассировки и экспортёры.

Включение

{
  diagnostics: { enabled: true }
}

Флаги диагностики

Дополнительные отладочные логи без повышения logging.level:

{
  diagnostics: { flags: ["telegram.http"] }
}

Через env: OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Экспорт в OpenTelemetry

{
  plugins: {
    allow: ["diagnostics-otel"],
    entries: {
      "diagnostics-otel": { enabled: true },
    },
  },
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "http://otel-collector:4318",
      protocol: "http/protobuf",
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: true,
      sampleRate: 0.2,
    },
  },
}

Экспортируемые метрики

• openclaw.tokens, openclaw.cost.usd — использование моделей
• openclaw.webhook.received, openclaw.webhook.duration_ms — вебхуки
• openclaw.message.queued, openclaw.message.processed — сообщения
• openclaw.queue.depth, openclaw.queue.wait_ms — очереди
• openclaw.session.state, openclaw.session.stuck — сессии

Поддерживаемые env

• OTEL_EXPORTER_OTLP_ENDPOINT
• OTEL_SERVICE_NAME
• OTEL_EXPORTER_OTLP_PROTOCOL

Валидация

OpenClaw принимает только конфигурацию, полностью соответствующую схеме. Неизвестные ключи или неверные значения не дадут Gateway запуститься.

Если что-то не так:

openclaw doctor          # показать проблемы
openclaw doctor --fix    # исправить автоматически

Gateway хранит резервную копию последней рабочей конфигурации и восстанавливает её при сбое.

Эксплуатация Gateway

Запуск и проверка

openclaw gateway --port 18789
openclaw gateway status
openclaw channels status --probe
openclaw logs --follow

Здоровый baseline: Runtime: running, Connectivity probe: ok.

Команды оператора

openclaw gateway status --deep   # глубокая проверка
openclaw gateway install         # установить сервис (launchd/systemd)
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw doctor

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

Супервизия

macOS: openclaw gateway install → LaunchAgent ai.openclaw.gateway.

Linux (systemd): openclaw gateway install → systemctl --user enable --now openclaw-gateway. Для persistence: sudo loginctl enable-linger <user>.

Windows: Scheduled Task OpenClaw Gateway.

Несколько gateway

Нужны только при необходимости изоляции. Чеклист: уникальный gateway.port, OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, agents.defaults.workspace.

Частые сбои

Блокировка Gateway

Gateway гарантирует запуск только одного экземпляра на базовый порт. Механизм — эксклюзивный TCP-листенер (WebSocket).

Как работает

• Gateway привязывает WebSocket при запуске (ws://127.0.0.1:18789)
• Если порт занят — GatewayLockError("another gateway instance is already listening")
• ОС автоматически освобождает порт при выходе процесса (включая SIGKILL)
• Отдельный файл блокировки не нужен

Решение проблем

• Порт занят другим процессом → освободите порт или выберите другой: openclaw gateway --port <port>
• Несколько gateway → используйте изолированные профили и уникальные порты

Проверка здоровья

Быстрые команды

В чате: /status как отдельное сообщение для получения статуса без вызова агента.

Конфигурация монитора здоровья

{
  gateway: {
    channelHealthCheckMinutes: 5,           // как часто проверять каналы
    channelStaleEventThresholdMinutes: 30,  // таймаут бездействия канала
    channelMaxRestartsPerHour: 10,          // лимит перезапусков
  },
}

Отключение для конкретного канала: channels.<provider>.healthMonitor.enabled: false.

Когда что-то не работает

• logged out или 409–515 → openclaw channels logout затем openclaw channels login
• Gateway недоступен → openclaw gateway --port 18789
• Нет входящих → проверьте привязку и allowFrom

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
  },
  identity: {
    name: "Samantha",
    theme: "helpful assistant",
    emoji: "🦥",
  },
  logging: { level: "info" },
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"],
      },
      thinkingDefault: "low",
      timeoutSeconds: 600,
      heartbeat: { every: "30m" },
    },
    list: [
      { id: "main", default: true },
      { id: "quick", thinkingDefault: "off" },
    ],
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      allowFrom: ["123456789"],
    },
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+79001234567"],
      groups: { "*": { requireMention: true } },
    },
  },
  session: {
    dmScope: "per-channel-peer",
    reset: { mode: "daily", atHour: 4, idleMinutes: 60 },
  },
  tools: {
    allow: ["exec", "process", "read", "write", "edit"],
    deny: ["browser", "canvas"],
  },
}

Что дальше