Skip to main content

​
Анатомия OpenClaw

​
Введение: OpenClaw как организм

OpenClaw — это не просто программа, это распределенная система, организованная как живой организм. Если представить её анатомию:
  • Gateway — сердце и нервная система, которая качает данные и координирует все процессы
  • Agent — мозг, который думает и принимает решения
  • Tools — руки, которые выполняют действия
  • Workspace — долговременная память и личное пространство
  • Sessions — кратковременная память разговоров
  • Nodes — дополнительные конечности (камера, экран, микрофон)
Этот документ раскрывает устройство каждого органа до уровня файлов и конфигов, показывает, как они взаимодействуют, и иллюстрирует на практических примерах.

​
Часть 1: Gateway — Сердце системы

​
1.1. Что такое Gateway и зачем он нужен

Gateway — это долгоживущий процесс-демон, который:
  • Держит постоянные подключения к каналам (Telegram, WhatsApp, Discord, Slack)
  • Маршрутизирует входящие сообщения к правильным агентам
  • Хранит состояние сессий (история диалогов)
  • Предоставляет API (HTTP/WebSocket) для UI и внешних интеграций
  • Запускает периодические задачи (cron, heartbeat)
  • Управляет подключенными nodes (устройствами)
Аналогия с человеком: Gateway — это сердечно-сосудистая система + нервная система. Он качает события (как кровь) между каналами и агентами, передаёт сигналы (как нервные импульсы) от органов чувств (каналов) к мозгу (агенту) и обратно.

​
1.2. Файловая структура Gateway

Все данные Gateway хранятся в ~/.openclaw/: ~/.openclaw/config.json — главный конфиг Gateway:
  • Настройки аутентификации (gateway.auth.token/password)
  • Порт WebSocket API (по умолчанию 18789)
  • Конфиги каналов (telegram.token, whatsapp.credentials и т.д.)
  • Настройки безопасности exec (sandbox, approvals)
  • Конфиги browser tool (профили, executable path)
~/.openclaw/agents/<agentId>/ — данные каждого агента:
  • sessions/sessions.json — метаданные всех сессий (кто, когда, канал, статус)
  • sessions/<SessionId>.jsonl — полная история каждого диалога (каждая строка = одно сообщение)
  • workspace/ — личная память агента (об этом в Части 2)
~/.openclaw/channels/ — персистентные данные каналов:
  • telegram/session.json — сессия Telegram бота
  • whatsapp/.wwebjs_auth/ — сессия WhatsApp (QR-авторизация)
~/.openclaw/exec-approvals.json — список разрешённых команд для exec tool (whitelist)

​
1.3. Как Gateway обрабатывает входящее сообщение

Шаг 1: Сообщение приходит в канал (например, Telegram)
  • Gateway держит постоянное подключение к Telegram API
  • Получает webhook или long-polling событие: новое сообщение от пользователя
Шаг 2: Маршрутизация к агенту
  • Gateway смотрит в конфиг bindings: какой агент должен обработать это сообщение?
  • Определяет SessionId: для DM обычно один главный контекст (dmScope: "main"), либо изолированный (dmScope: "per-channel-peer")
  • Если сессия новая, создаёт запись в sessions.json и новый .jsonl файл
Шаг 3: Запуск agent loop
  • Gateway читает историю сессии из .jsonl
  • Подмешивает bootstrap-файлы из workspace (AGENTS.md, SOUL.md, USER.md и т.д.)
  • Добавляет доступные skills
  • Формирует полный контекст и отправляет в LLM
Шаг 4: Обработка ответа
  • LLM возвращает либо текст, либо tool calls (вызовы инструментов)
  • Если tool call, Gateway выполняет его (exec, browser, file write и т.д.) и возвращает результат в контекст
  • Цикл повторяется, пока LLM не вернёт финальный ответ
  • Ответ стримится обратно в канал (пользователь видит печатание в реальном времени)
Шаг 5: Сохранение в память
  • Весь exchange (user message + assistant response + tool calls) записывается в .jsonl
  • Обновляется sessions.json (timestamp, message count)

​
1.4. Практический пример: Multi-agent система

Юзкейс: У вас есть рабочий агент (для задач компании) и личный агент (для быта). Вы хотите, чтобы в Telegram @work_bot отвечал рабочий, а в личке вам писал личный. Настройка: Создаёте два workspace: 
~/.openclaw/agents/work/workspace/      — с AGENTS.md для рабочих задач
~/.openclaw/agents/personal/workspace/  — с AGENTS.md для личных дел
В config.json прописываете bindings: 
{ "channel": "telegram", "chatId": "@work_bot", "agentId": "work" }
{ "channel": "telegram", "chatId": "YOUR_USER_ID", "agentId": "personal" }
Для изоляции контекста между агентами: 
session.dmScope: "per-agent"  (каждый агент видит только свои диалоги)
Результат: Когда вы пишете @work_bot, Gateway маршрутизирует к агенту “work”, который видит только рабочий workspace и рабочие сессии. Когда пишете в личку, Gateway переключается на агента “personal” с его workspace и сессиями.

​
1.5. API и удалённый доступ

Gateway поднимает WebSocket API на порту 18789 (по умолчанию). Это позволяет:
  • Подключать UI клиенты (веб-интерфейс, мобильное приложение)
  • Интегрироваться с внешними системами через HTTP API
  • Использовать OpenAI-совместимый endpoint для совместимости с существующими инструментами
Безопасность: По умолчанию Gateway слушает только 127.0.0.1 (localhost). Для удалённого доступа:
  • VPN/Tailscale — прокидываете Gateway в вашу приватную сеть
  • SSH tunnel — ssh -L 18789:127.0.0.1:18789 user@server
  • Никогда не открывайте 18789 в интернет напрямую — это доступ ко всем вашим данным

​
Часть 2: Workspace — Долговременная память

​
2.1. Что такое Workspace

Workspace — это папка с Markdown файлами, которые определяют:
  • Поведение агента (как думать, как работать с пользователем)
  • Персональность (тон, границы, имя)
  • Знание о пользователе (предпочтения, контекст)
  • Долгосрочную память (важные факты, решения, наработки)
  • Дневник (оперативные заметки по дням)
Аналогия с человеком: Workspace — это “дом памяти” — ваши тетради, конспекты, дневники, инструкции к себе. Это то, что вы записываете, чтобы не забыть и всегда иметь под рукой.

​
2.2. Файловая структура Workspace

Типичная структура ~/.openclaw/agents/<agentId>/workspace/: AGENTS.md — операционный мануал агента:
  • Как принимать решения
  • Когда использовать какие инструменты
  • Правила безопасности (например, “всегда подтверждай exec команды”)
  • Docs-first подход (“сначала читай документацию, потом пиши код”)
SOUL.md — персона и тон:
  • Как общаться (формально, дружелюбно, лаконично?)
  • Границы (что агент не будет делать)
  • Ценности и приоритеты
USER.md — профиль пользователя:
  • Как обращаться (имя, обращение на ты/вы)
  • Предпочтения (формат ответов, стиль работы)
  • Контекст (чем занимается пользователь, его цели)
IDENTITY.md — имя и виб агента (например, “Меня зовут Алекс, я твой ассистент по автоматизации”) TOOLS.md — локальные подсказки по инструментам:
  • Где лежат скрипты (например, /home/user/scripts/process.py)
  • Какие команды доступны в этом окружении
  • Шорткаты и алиасы
HEARTBEAT.md — чеклист для периодических проверок:
  • “Проверь, нет ли новых писем от клиентов”
  • “Посмотри, запущен ли мониторинг”
  • “Обнови статус в Notion”
YYYY-MM-DD.md — дневник по дням:
  • Краткие заметки о событиях дня
  • Что делали, какие решения приняли
  • Контекст текущей работы (“сейчас разбираемся с багом в модуле X”)
MEMORY.md — долгосрочная память (конспект важного):
  • Важные факты, которые не должны забыться
  • Принятые решения и их причины
  • Уроки из прошлого опыта
  • Обычно доступен только в main/private контексте (не в публичных чатах)

​
2.3. Как агент использует Workspace

Bootstrap-файлы: При каждом запуске agent loop, Gateway читает определённые файлы из workspace и подмешивает их в контекст перед вызовом LLM:
  • AGENTS.md (всегда)
  • SOUL.md (всегда)
  • USER.md (всегда)
  • IDENTITY.md (всегда)
  • TOOLS.md (если есть)
  • Сегодняшний дневник (YYYY-MM-DD.md)
  • MEMORY.md (только для main/private контекста)
Memory search: Если включён memory plugin (по умолчанию memory-core), агент может:
  • Искать по смыслу в MEMORY.md и других .md файлах через векторный индекс
  • Находить релевантные факты, даже если они не упомянуты явно в bootstrap
Запись в память: Агент может писать в workspace, если workspace writable (по умолчанию да). Например:
  • Пользователь: “Запомни, что я предпочитаю React на TypeScript”
  • Агент: записывает это в MEMORY.md
  • Пользователь: “Запиши в дневник, что сегодня починили баг в auth”
  • Агент: дописывает в 2025-02-15.md

​
2.4. Практический пример: Персональный ассистент с памятью

Юзкейс: Вы хотите агента, который помнит ваши предпочтения, ведёт дневник ваших дел и умеет искать по прошлым заметкам. Настройка:
  • Создаёте workspace в ~/.openclaw/agents/personal/workspace/
  • Пишете в USER.md: “Пользователь: Артём, обращение на ты, предпочитает короткие ответы”
  • Пишете в AGENTS.md: “Всегда веди дневник. Записывай важные события в YYYY-MM-DD.md, а долгосрочные решения в MEMORY.md”
  • Говорите агенту: “Запомни, что я работаю в Web3 и интересуюсь автоматизацией”
  • Агент записывает это в MEMORY.md
Результат:
  • Через неделю вы спрашиваете: “Что мы делали в понедельник?”
  • Агент открывает 2025-02-10.md и рассказывает
  • Вы спрашиваете: “Какие у меня предпочтения в стеке?”
  • Агент ищет в MEMORY.md и отвечает: “Ты предпочитаешь React на TypeScript, работаешь в Web3”

​
Часть 3: Sessions — Кратковременная память

​
3.1. Что такое Session

Session — это “память разговора” — контекст одного диалога между пользователем и агентом. Каждая сессия:
  • Хранит историю сообщений (user, assistant, tool calls)
  • Изолирована от других сессий (если не настроено иначе)
  • Может быть приватной (DM) или групповой (чат)
  • Имеет свой SessionId (уникальный идентификатор)
Аналогия с человеком: Session — это “рабочая память” разговора. Пока вы говорите, вы помните контекст этого конкретного обсуждения. Закончили разговор, переключились на другую тему — новая сессия, новый контекст.

​
3.2. Файловая структура Sessions

~/.openclaw/agents/<agentId>/sessions/sessions.json — метаданные всех сессий:
  • SessionId, канал, пользователь
  • Timestamp создания и последнего сообщения
  • Количество сообщений, статус (active/archived)
~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl — полная история диалога:
  • Каждая строка = одно событие (user message, assistant response, tool call, tool result)
  • Формат JSONL: JSON Lines (каждая строка — валидный JSON)
  • Легко читать и парсить инкрементально

​
3.3. dmScope: Изоляция DM-сессий

Проблема: По умолчанию все DM (direct messages) в одном канале “схлопываются” в один главный контекст (dmScope: "main"). Это значит:
  • Если вам в личку Telegram пишут два разных человека, агент видит их сообщения в одной сессии
  • Риск утечки контекста: агент может случайно ответить одному пользователю информацией от другого
Решение: Изоляция DM-сессий через session.dmScope:
ЗначениеПоведение
"main"Все DM в одной сессии (небезопасно для multi-user)
"per-channel-peer"Каждый пользователь получает свою изолированную сессию (безопасно)
"per-agent"Изоляция по агентам (для multi-agent)
Рекомендация: Если в личку пишет больше 1 человека, всегда ставьте session.dmScope: "per-channel-peer".

​
3.4. Compaction: Сжатие истории

При длинных разговорах сессия может вырасти до десятков тысяч токенов. OpenClaw автоматически компактит историю:
  • Старые сообщения сворачиваются в summary (краткое описание)
  • Свежие сообщения остаются полными
  • Перед компакцией Gateway может сделать “memory flush” — попросить агента записать важное в MEMORY.md

​
Часть 4: Tools — Руки агента

​
4.1. Типы инструментов

Tools — это способ агента взаимодействовать с внешним миром:
  • exec — запуск команд в shell
  • browser — управление браузером (открыть страницу, кликнуть, сделать screenshot)
  • file — чтение/запись файлов
  • message — отправка сообщений в каналы
  • memory — поиск по долговременной памяти
  • node.* — команды на подключённых устройствах (camera.*, screen.*, location.* и т.д.)

​
4.2. exec tool: Запуск команд

exec позволяет агенту запускать shell-команды. Это самый мощный и самый опасный инструмент. Три режима выполнения:
  • host=sandbox — выполнение в изолированном Docker-контейнере (по умолчанию, если sandboxing включён)
  • host=gateway — выполнение на машине Gateway (с политиками и approvals)
  • host=node — выполнение на подключённом node (macOS app / headless)
Безопасность exec:
  • deny — exec полностью запрещён
  • allowlist — разрешены только команды из exec-approvals.json
  • full — разрешено всё (опасно!)
exec-approvals.json — whitelist команд: 
{ "pattern": "/usr/bin/git", "approved": true }
{ "pattern": "/usr/bin/python3", "args": ["script.py"], "approved": true }
{ "pattern": "rm", "approved": false }

​
4.3. browser tool: Управляемый браузер

Browser tool — это отдельный изолированный браузерный профиль, которым агент может управлять программно. Два режима:
  • openclaw — managed профиль, полная изоляция, не нужно расширение
  • chrome — управление вашим обычным Chrome через extension relay (нужна открытая вкладка с расширением)
Команды:
КомандаОписание
tabs.open(url)Открыть страницу
tabs.close(tabId)Закрыть вкладку
click(selector)Кликнуть на элемент
type(selector, text)Ввести текст
snapshot()Получить HTML/текст страницы
screenshot()Сделать скриншот
pdf()Сохранить страницу в PDF
Конфиг: browser.* в openclaw.json: 
"browser": {
  "enabled": true,
  "defaultProfile": "openclaw",
  "executablePath": "/usr/bin/chromium"
}

​
4.4. Практический пример: Автоматизация проверки email

Юзкейс: Вы хотите, чтобы агент каждое утро проверял ваш Gmail, искал письма от клиентов и отправлял вам summary в Telegram. (можно через API и скилл gog, а можно через браузер. Разберём с браузером. В некоторых случаях через gog удобнее) Настройка:
  • Включаете browser tool (browser.enabled: true)
  • Настраиваете cron job в Gateway:
openclaw cron add --schedule "0 9 * * *" --agent personal \
  --prompt "Зайди в Gmail, проверь письма от клиентов, отправь summary в Telegram"
  • В AGENTS.md прописываете инструкцию:
Для проверки Gmail: открой gmail.com, кликни на Inbox, используй snapshot()
чтобы получить список писем, отфильтруй письма от клиентов (домен @client.com),
составь summary и отправь через message tool в Telegram
Результат: Каждое утро в 9:00 агент:
  • Открывает браузер
  • Заходит в Gmail (профиль с сохранённой сессией)
  • Читает inbox через snapshot()
  • Фильтрует письма от клиентов
  • Отправляет вам в Telegram: “Сегодня 3 письма от клиентов: X просит апдейт, Y спрашивает про billing, Z благодарит”

​
Часть 5: Nodes — Дополнительные органы чувств

​
5.1. Что такое Node

Node — это физическое устройство (компьютер, смартфон, планшет), подключённое к Gateway и предоставляющее дополнительные возможности:
  • Камера (camera.capture)
  • Экран (screen.record, screen.capture)
  • Локация (location.get)
  • Системные команды (system.run)
  • Canvas (рисование на экране)
Аналогия с человеком: Node — это дополнительные конечности и органы чувств. Gateway на сервере — это мозг, а node на вашем маке — это глаза, руки, уши.

​
5.2. Подключение Node

macOS app:
  • Скачиваете OpenClaw
  • Запускаете, вводите адрес Gateway (например, через Tailscale)
  • Node регистрируется в Gateway и объявляет свои capabilities
Headless node:
  • Запускаете openclaw node start на удалённой машине
  • Прописываете адрес Gateway в конфиге
  • Node подключается и ждёт команд

​
5.3. Практический пример: Домашний мониторинг

Юзкейс: Вы хотите, чтобы агент мог делать скриншоты вашего домашнего компьютера по запросу (например, “покажи мой экран”). Настройка:
  • Gateway запущен на сервере (VPS)
  • На домашнем маке запускаете OpenClaw и подключаете к Gateway через Tailscale
  • Мак объявляет capability: screen.capture
Результат:
  1. В Telegram пишете агенту: “Покажи мой экран”
  2. Агент вызывает screen.capture на node
  3. Node делает скриншот и возвращает Gateway
  4. Агент отправляет скриншот в Telegram
Вы можете удалённо проверять, что происходит на домашнем компьютере, не настраивая VNC или TeamViewer.

​
Часть 6: Memory — Гиппокамп агента

​
6.1. Два уровня памяти

Bootstrap (прямое подмешивание): Файлы из workspace всегда читаются целиком и добавляются в контекст перед каждым прогоном.
  • Плюс: Гарантированно в контексте
  • Минус: Занимает много токенов, если файлы большие
Semantic search (векторный индекс): Memory plugin индексирует MEMORY.md и другие .md файлы, ищет релевантные куски по смыслу.
  • Плюс: Эффективный поиск по большому объёму заметок
  • Минус: Не гарантирует, что нужный факт будет найден

​
6.2. Правильная стратегия использования памяти

MEMORY.md: Долгоживущие факты, которые должны ВСЕГДА помниться
  • Предпочтения пользователя (“Артём предпочитает короткие ответы”)
  • Принятые решения (“Решили использовать PostgreSQL для основной БД”)
  • Уроки из опыта (“Не используй библиотеку X, она глючная”)
YYYY-MM-DD.md: События и контекст конкретного дня
  • Что делали сегодня
  • Текущие задачи (“Сейчас разбираемся с багом в модуле auth”)
  • Временные заметки, которые потом можно архивировать
Как записывать:
  • Прямая инструкция: “Запиши в память, что я работаю в Web3”
  • Агент сам решает: если workspace writable и включён memory flush, агент может автоматически записывать важное перед компакцией сессии

​
Часть 7: Cron и Heartbeat — Распорядок дня

​
7.1. Cron: Периодические задачи

Cron — это планировщик задач на стороне Gateway. Вы можете настроить:
  • “Каждый день в 9:00 проверяй email и отправляй summary”
  • “Каждые 30 минут проверяй статус мониторинга”
  • “Раз в сутки делай бэкап workspace в git”
Команда: 
openclaw cron add --schedule "0 9 * * *" --agent work --prompt "Проверь новые задачи в Notion" --announce
Флаги:
  • --announce — результат доставляется в канал (например, отправляется в Telegram)
  • --no-deliver — выполняется внутренне, результат не отправляется

​
7.2. Heartbeat: Пульс агента

Heartbeat — это короткая периодическая проверка, которую Gateway просит агента сделать.
  • Агент читает HEARTBEAT.md
  • Выполняет чеклист (например, “проверь, запущен ли мониторинг”)
  • Если что-то не так, пишет в канал (например, “Мониторинг упал!”)
Пример HEARTBEAT.md: 
- Проверь, запущен ли процесс monitoring.py
- Проверь, свободно ли >10GB на диске
- Проверь, нет ли новых ошибок в логах

​
Часть 8: Skills — Обучение агента

​
8.1. Что такое Skill

Skill — это папка с SKILL.md, которая учит агента пользоваться конкретным инструментом или процедурой. Пример: skill для работы с PDF: 
~/.openclaw/skills/pdf/SKILL.md
Содержит: как читать PDF, как извлекать текст, как объединять PDF, как конвертировать в изображения.

​
8.2. Источники skills

  • Bundled — встроенные skills, поставляются с OpenClaw
  • ~/.openclaw/skills — глобальные skills для всех агентов
  • <workspace>/skills — skills конкретного агента (перекрывают глобальные)
Приоритет: workspace > global > bundled

​
8.3. Gating: Условное включение skills

Skill может быть “замкнут” на наличие определённых условий:
  • Наличие бинарника (например, показывать skill для git только если /usr/bin/git существует)
  • Конфиг (например, показывать browser skill только если browser.enabled=true)
  • Env переменная (например, API_KEY установлена)

​
Заключение: Собираем всё вместе

OpenClaw — это не просто “LLM с инструментами”. Это распределённая система с:
  • Центральным координатором (Gateway) — который держит подключения, маршрутизирует сообщения, хранит сессии
  • Долговременной памятью (Workspace) — которая определяет поведение, персональность и знания агента
  • Кратковременной памятью (Sessions) — которая хранит контекст разговоров
  • Исполнительными органами (Tools) — которые позволяют агенту действовать в реальном мире
  • Дополнительными органами чувств (Nodes) — которые расширяют возможности агента на физические устройства
  • Обучающими материалами (Skills) — которые учат агента использовать инструменты эффективно
Понимая устройство каждого компонента, где он живёт в файловой системе, как он взаимодействует с другими частями системы, вы можете:
  • Настраивать сложные multi-agent сценарии
  • Безопасно давать агенту доступ к критическим системам
  • Строить устойчивую память, которая сохраняется между сессиями
  • Автоматизировать рутинные задачи через cron и heartbeat
  • Расширять возможности агента через nodes и custom skills
Ключевой принцип: OpenClaw — это не чёрный ящик. Каждый компонент прозрачен, каждый конфиг доступен для редактирования, каждая сессия хранится в простом JSONL. Вы всегда контролируете систему полностью.