Тонкая настройка OpenClaw. Как дойти от установки до multi-agent за один вечер?

OpenClaw очень просто для быстрого старта. После openclaw onboard у тебя работает Gateway и один агент отвечает в Telegram. Но дальше начинается самое интересное — и самое неочевидное: как устроен openclaw.json, что из workspace-файлов реально попадает в контекст, как включить heartbeat так, чтобы он не превратился в генератор мусора и расхода токенов, и как правильно разнести нескольких агентов по чатам и топикам.

Документация OpenClaw покрывает это фрагментарно, а большинство гайдов заканчиваются на «поставил – работает». Этим туториалом постараемся закрыть следующие шаги: разбираем конфиг секция за секцией, показываем рабочие примеры для Telegram, bindings, session policy и multi-agent — всё, что нужно, чтобы перейти от одного бота в личке к нормальной продакшн-конфигурации.

Что такое OpenClaw после установки

После установки OpenClaw у тебя появляется не просто CLI, а целая среда:

• Gateway — центральный процесс: каналы, роутинг, сессии, веб‑интерфейс.

• Agent workspace — рабочая папка агента: файлы, память, локальные инструкции.

• Главный конфиг ~/.openclaw/openclaw.json — место, где задаётся почти всё.

• Каналы — Telegram, WhatsApp, Discord и другие.

• Автономность — heartbeat, cron, hooks.

• Multi‑agent — несколько агентов в одном Gateway.

Если совсем упростить: OpenClaw — это шлюз между мессенджерами, моделью и твоими агентами.

После установки твоя задача не в том, чтобы «заполнить все поля», а в том, чтобы:

1. поднять Gateway;

2. выбрать модель и канал;

3. привести в порядок openclaw.json;

4. настроить workspace;

5. только потом добавлять автономность и несколько агентов.

Что делать сразу после установки

Самый нормальный путь для новичка — не редактировать всё руками с первой минуты, а сначала пройти встроенный onboarding.

Базовая последовательность

openclaw onboard

Это мастер первичной настройки. Он помогает:

• выбрать режим работы;

• настроить Gateway;

• задать авторизацию;

• выбрать модель или провайдера;

• подключить канал;

• создать стартовую конфигурацию.

После этого, если нужно что то изменить, используйте:

openclaw configure

А потом проверить текущее состояние:

openclaw status
openclaw doctor

Если нужно понять, где лежит активный конфиг:

openclaw config file

Обычно это:

~/.openclaw/openclaw.json

OpenClaw может стартовать и без конфиг‑файла вообще — с безопасными дефолтами. Но как только ты хочешь подключить Telegram, ограничить доступы, выбрать модели, включить heartbeat или сделать multi‑agent, без openclaw.json уже никуда.

Главный файл: ~/.openclaw/openclaw.json

Почти вся взрослая настройка OpenClaw живёт в ~/.openclaw/openclaw.json.

Это главный конфиг Gateway. Формат — JSON5, а не строгий JSON.

OpenClaw строго валидирует конфиг.

Это значит:

• опечатка в ключе;

• неправильный тип значения;

• неизвестное поле;

• невалидная структура,

• и Gateway может отказаться стартовать.

После ручных правок полезно делать:

openclaw config validate
openclaw doctor

Можно ли редактировать конфиг «на лету»

Да, во многих случаях есть hot reload. Но часть настроек применяются сразу, а часть требует рестарта.

Практичное правило:

• каналы, агенты, heartbeat, messages, tools — чаще всего можно менять без боли;

• gateway‑настройки (порт, bind и т.п.) — чаще требуют рестарта.

Если не хочется гадать:

openclaw gateway restart

Какие конфиг‑файлы бывают

1) ~/.openclaw/openclaw.json

Это главный системный конфиг. Здесь настраиваются:

• Gateway

• каналы

• агенты

• routing / bindings

• heartbeat

• session policy

• tools

• models

• hooks / cron

• secrets и другое

Если нужно менять поведение системы — почти наверняка это делается здесь.

2) ~/.openclaw/workspace/*

Это рабочая среда агента. Обычно там есть:

• AGENTS.md

• SOUL.md

• USER.md

• TOOLS.md

• HEARTBEAT.md

• IDENTITY.md

• memory/YYYY-MM-DD.md

• MEMORY.md

Это не просто заметки: эти файлы попадают в контекст агента и сильно влияют на поведение и расход токенов.

3) auth-profiles.json и связанные auth‑файлы

Полезно, когда доходишь до multi‑agent: авторизация у агентов может быть разделена.

4) .env и ~/.openclaw/.env

OpenClaw умеет читать переменные окружения:

• из процесса;

• из локального .env;

• из ~/.openclaw/.env.

Это удобно для ключей, токенов и приватных данных.

5) Разбитые конфиги через $include

Если конфиг разрастается, его можно делить на несколько файлов:

{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  channels: { $include: "./channels.json5" },
}

Как мыслить об openclaw.json, чтобы не утонуть

Разбей его мысленно на 6 блоков:

1. как работает шлюз → gateway

2. какие агенты → agents

3. откуда приходят сообщения → channels

4. куда маршрутизировать → bindings

5. как живут сессии и ответы → session, messages

6. автономность и права → heartbeat, tools, cron, hooks

Если понять эти шесть частей, дальше всё становится сильно проще.

Разбор ключевых секций openclaw.json

gateway: как работает OpenClaw как сервис

Простейший пример:

{
  gateway: {
    mode: "local",
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token",
      token: "super-secret-token",
    },
  },
}

• Что здесь важно новичку

  • mode: обычно нужен local.

  • port: по умолчанию часто 18789.

  • bind:

    • loopback — безопасный вариант (доступ только локально).

    • lan — слушать на всех интерфейсах.

    • tailnet — для Tailscale.

    • custom — кастомный bind.

  • auth: чтобы не оставить Gateway без защиты, настрой токен.

agents: кто вообще у тебя работает

Минимальный стартовый пример:

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "openai/gpt-5.4",
      },
    },
  },
}

• На что смотреть в agents.defaults

  • workspace: папка, где живёт агент.

  • model: основная модель, можно настроить fallback.

  • userTimezone: чтобы heartbeat и расписания работали адекватно.

  • heartbeat: автономность (ниже — отдельный раздел).

channels: откуда агент получает сообщения

Пример для Telegram:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456:ABCDEF",
      dmPolicy: "pairing",
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

Ментальная модель: channels отвечает на вопрос: через какие мессенджеры можно достучаться и на каких правилах.

bindings: как сообщения попадают к конкретному агенту

Пример:

{
  bindings: [
    { agentId: "main", match: { channel: "telegram", accountId: "default" } },
    { agentId: "ops", match: { channel: "telegram", accountId: "ops-bot" } },
  ],
}

channels описывает входные двери, а bindings решает, в какую комнату отправить посетителя.

session: как живёт память разговора

{
  session: {
    dmScope: "per-channel-peer",
    reset: {
      mode: "idle",
      idleMinutes: 180,
    },
    threadBindings: {
      enabled: true,
      idleHours: 24,
    },
  },
}

messages: как агент отвечает

{
  messages: {
    ackReaction: "👀",
    queue: {
      mode: "collect",
      debounceMs: 1000,
    },
    inbound: {
      debounceMs: 1500,
    },
  },
}

tools: что агенту вообще разрешено

Безопасный старт:

{
  tools: {
    profile: "coding",
    deny: ["browser", "canvas"],
    elevated: {
      enabled: false,
    },
  },
}

Heartbeat: автономность без хаоса

Большинство агентов реактивны: написал — ответил. Heartbeat делает агента проактивным. Это чуть ли не самое крутое что есть в OpenClaw.
По таймеру Gateway отправляет агенту сигнал, и тот решает — есть ли что-то, о чём стоит сообщить, или нужно выполнить фоновую задачу. Это может быть проверка статуса деплоя, напоминание о зависшей задаче или утренний дайджест. По сути, heartbeat превращает агента из собеседника в фонового ассистента, который работает даже когда ты ему не пишешь.

Если openclaw.json — мозг конфигурации, то heartbeat — сердце автономной работы.

Heartbeat очень мощный, но легко становится источником шума и расхода токенов, если не задать понятный сценарий.

Как включается heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        directPolicy: "allow",
        lightContext: true,
      },
    },
  },
}

• Что значат основные настройки

  • every: интервал (30m, 1h, 2h, 0m — выключить).

  • target: куда отправлять результат (none, last, конкретный канал).

  • directPolicy: можно ли писать в личку.

  • lightContext: облегчённый контекст, в основном с опорой на HEARTBEAT.md.

Зачем нужен HEARTBEAT.md

Без HEARTBEAT.md heartbeat часто превращается в:

• шумного собеседника, который дёргает без дела;

• дорогой таймер, который регулярно сжигает токены.

HEARTBEAT.md — это чеклист автономного режима.

Пример:

# HEARTBEAT

- Проверь, есть ли что-то срочное или зависшее в текущих задачах.
- Если есть блокер — коротко скажи, что именно мешает.
- Если есть законченный важный результат — коротко сообщи.
- Не дёргай без причины.
- Если ничего важного нет, отвечай HEARTBEAT_OK.
- Ночью без срочности не пиши.

Telegram: как настроить бота нормально

Базовый конфиг Telegram‑бота

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456:ABCDEF",
      dmPolicy: "pairing",
      groups: {
        "*": { requireMention: true },
      },
      historyLimit: 50,
      replyToMode: "first",
      linkPreview: true,
      streaming: "partial",
    },
  },
}

• Ключевые моменты

  • botToken: токен от BotFather.

  • dmPolicy:

    • pairing — мягкий вход.

    • allowlist — самый предсказуемый доступ.

    • open — все.

    • disabled — личка выключена.

  • requireMention: true в группах — хорошая защита от «болтливого» бота.

Multi‑agent: несколько агентов и привязка к каналам, чатам, топикам

Правильная модель: один Gateway держит несколько изолированных агентов. У каждого может быть свой workspace, инструкции, auth‑профили и маршрутизация входящих сообщений.

1) Добавить нового агента

openclaw agents add research

Пример руками:

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
      },
      {
        id: "research",
        workspace: "~/.openclaw/workspace-research",
        agentDir: "~/.openclaw/agents/research/agent",
      },
    ],
  },
}

Один workspace на двух агентов — почти всегда плохая идея. Разделяй workspace и agentDir.

2) Привязать агента к отдельному Telegram‑аккаунту (два бота)

{
  channels: {
    telegram: {
      accounts: {
        default: {
          botToken: "123456:MAIN_TOKEN",
          dmPolicy: "allowlist",
          allowFrom: ["tg:123456789"],
        },
        researchbot: {
          botToken: "654321:RESEARCH_TOKEN",
          dmPolicy: "allowlist",
          allowFrom: ["tg:123456789"],
        },
      },
    },
  },
  bindings: [
    { agentId: "main", match: { channel: "telegram", accountId: "default" } },
    { agentId: "research", match: { channel: "telegram", accountId: "researchbot" } },
  ],
}

3) Привязать агента к конкретному чату

{
  bindings: [
    {
      agentId: "research",
      match: {
        channel: "telegram",
        peer: { kind: "group", id: "-1001234567890" },
      },
    },
  ],
}

4) Привязать агента к конкретному Telegram topic

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: true,
          topics: {
            "3": { agentId: "dev", requireMention: false },
            "5": { agentId: "ops", requireMention: false },
          },
        },
      },
    },
  },
}

5) Отдельный heartbeat для каждого агента

{
  agents: {
    defaults: {
      heartbeat: {
        every: "0m",
      },
    },
    list: [
      {
        id: "main",
        default: true,
        workspace: "~/.openclaw/workspace-main",
      },
      {
        id: "ops",
        workspace: "~/.openclaw/workspace-ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "123456789",
          lightContext: true,
        },
      },
    ],
  },
}

Итог

OpenClaw спроектирован так, что можно начать с одного агента в Telegram и постепенно наращивать сложность – не переписывая конфиг с нуля, а добавляя секции по мере необходимости. Главное – не пытаться включить всё сразу, действуйте шаг за шагом, смотрите к чему приводят перемены, все ли вас устраивает.
Gateway, одна модель, один канал, чистый workspace – этого достаточно, чтобы агент заработал. Heartbeat, bindings, multi-agent – это следующий шаг, когда понятно, зачем они нужны именно тебе.
Если что-то пошло не так – openclaw doctor и openclaw status почти всегда подскажут, где копать.

==
В следующем туториале планируем разобрать workspace подробнее: как писать SOUL.md и AGENTS.md так, чтобы агент вёл себя предсказуемо, как устроена память и сколько токенов на самом деле съедают эти файлы. Если есть темы, которые хочется разобрать в первую очередь и в чем кажется основные проблемы – пишите в комментариях.

А если хочется обсудить конкретные конфигурации или посмотреть, как другие строят своих агентов – заходите в наше сообщество: – https://t.me/openclaw_lab_community, там уже есть топик где агенты общаются между собой 🙈