> ## Documentation Index > Fetch the complete documentation index at: https://ohmyclaw.sh/llms.txt > Use this file to discover all available pages before exploring further. # Анатомия # Анатомия 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//` — данные каждого агента: * `sessions/sessions.json` — метаданные всех сессий (кто, когда, канал, статус) * `sessions/.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: ```text theme={null} ~/.openclaw/agents/work/workspace/ — с AGENTS.md для рабочих задач ~/.openclaw/agents/personal/workspace/ — с AGENTS.md для личных дел ``` В `config.json` прописываете bindings: ```text theme={null} { "channel": "telegram", "chatId": "@work_bot", "agentId": "work" } { "channel": "telegram", "chatId": "YOUR_USER_ID", "agentId": "personal" } ``` Для изоляции контекста между агентами: ```text theme={null} 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//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//sessions/sessions.json` — метаданные всех сессий: * SessionId, канал, пользователь * Timestamp создания и последнего сообщения * Количество сообщений, статус (active/archived) `~/.openclaw/agents//sessions/.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 команд: ```text theme={null} { "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`: ```text theme={null} "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: ```text theme={null} openclaw cron add --schedule "0 9 * * *" --agent personal \ --prompt "Зайди в Gmail, проверь письма от клиентов, отправь summary в Telegram" ``` * В `AGENTS.md` прописываете инструкцию: ```text theme={null} Для проверки 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" **Команда:** ```text theme={null} openclaw cron add --schedule "0 9 * * *" --agent work --prompt "Проверь новые задачи в Notion" --announce ``` **Флаги:** * `--announce` — результат доставляется в канал (например, отправляется в Telegram) * `--no-deliver` — выполняется внутренне, результат не отправляется ## 7.2. Heartbeat: Пульс агента Heartbeat — это короткая периодическая проверка, которую Gateway просит агента сделать. * Агент читает `HEARTBEAT.md` * Выполняет чеклист (например, "проверь, запущен ли мониторинг") * Если что-то не так, пишет в канал (например, "Мониторинг упал!") **Пример** `HEARTBEAT.md`**:** ```text theme={null} - Проверь, запущен ли процесс monitoring.py - Проверь, свободно ли >10GB на диске - Проверь, нет ли новых ошибок в логах ``` *** # Часть 8: Skills — Обучение агента ## 8.1. Что такое Skill Skill — это папка с `SKILL.md`, которая учит агента пользоваться конкретным инструментом или процедурой. **Пример:** skill для работы с PDF: ```text theme={null} ~/.openclaw/skills/pdf/SKILL.md ``` Содержит: как читать PDF, как извлекать текст, как объединять PDF, как конвертировать в изображения. ## 8.2. Источники skills * **Bundled** — встроенные skills, поставляются с OpenClaw * `~/.openclaw/skills` — глобальные skills для всех агентов * `/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. Вы всегда контролируете систему полностью.