Применимо к OpenClaw v2026.2 | Статья предназначена для пользователей, завершивших базовую настройку и желающих глубже понять архитектуру. Рекомендуется сначала пройти первые 3 руководства.

TL;DR: Gateway — центральная плоскость управления OpenClaw. Session — контейнер контекста диалога (main/channel/group), Message Router определяет маршрутизацию сообщений, Tool Registry управляет правами инструментов, Skills — предварительно упакованные расширения возможностей. WebSocket-эндпоинт ws://127.0.0.1:18789/ws, основные команды openclaw gateway/doctor/config. Понимание этих концепций — основа для расширенной настройки.

Обзор архитектуры

Общая архитектура

flowchart TB
    subgraph Clients["Клиентский уровень"]
        WA[WhatsApp]
        TG[Telegram]
        DC[Discord]
        SL[Slack]
        WC[WebChat]
        CLI[CLI]
        MAC[macOS App]
        IOS[iOS Node]
        AND[Android Node]
    end
    
    subgraph Gateway["Уровень Gateway"]
        WS[WebSocket Server]
        HTTP[HTTP Server]
        MR[Message Router]
        SM[Session Manager]
        TR[Tool Registry]
        EM[Event Manager]
        CFG[Config Store]
    end
    
    subgraph Agent["Уровень Agent"]
        PI[Pi Agent]
        PROMPT[Prompt Engine]
        TOOLS[Tool Executor]
        SKILLS[Skills Manager]
    end
    
    subgraph External["Внешние сервисы"]
        FS[Файловая система]
        BR[Браузер]
        API[API-сервисы]
        DB[База данных]
        CAL[Cron-планировщик]
    end
    
    Clients --> WS
    Clients --> HTTP
    WS --> MR
    HTTP --> MR
    MR --> SM
    SM --> PI
    PI --> PROMPT
    PI --> TOOLS
    PI --> SKILLS
    TOOLS --> TR
    TR --> External
    EM --> MR
    CFG --> SM
    CFG --> TR

Обязанности компонентов

Поток данных

sequenceDiagram
    participant U as Пользователь
    participant C as Channel
    participant WS as WebSocket
    participant MR as Router
    participant SM as Session
    participant A as Agent
    participant T as Tools
    
    U->>C: Отправка сообщения
    C->>WS: Передача сообщения
    WS->>MR: Запрос маршрутизации
    MR->>SM: Поиск/создание сессии
    SM-->>MR: Возврат сессии
    MR->>A: Доставка сообщения
    A->>A: Обработка сообщения
    A->>T: Вызов инструмента (опционально)
    T-->>A: Возврат результата
    A-->>MR: Генерация ответа
    MR->>WS: Отправка ответа
    WS->>C: Передача ответа
    C-->>U: Отображение сообщения

Модель сессий Session

Что такое Session?

Session — одна из ключевых концепций OpenClaw. Каждая Session представляет независимый контекст диалога, содержащий:

Типы Session

{
  "sessions": {
    "main": {
      "type": "main",
      "model": "anthropic/claude-opus-4-6",
      "thinkingLevel": "high",
      "channel": null,
      "created": "2026-02-26T10:00:00Z"
    },
    "telegram:user:123456789": {
      "type": "channel",
      "model": "anthropic/claude-opus-4-6",
      "thinkingLevel": "normal",
      "channel": "telegram",
      "sender": "123456789",
      "created": "2026-02-26T10:05:00Z"
    },
    "telegram:group:-100123456789": {
      "type": "group",
      "model": "anthropic/claude-sonnet-4",
      "thinkingLevel": "minimal",
      "channel": "telegram",
      "groupId": "-100123456789",
      "created": "2026-02-26T10:10:00Z"
    }
  }
}

Жизненный цикл Session

stateDiagram-v2
    [*] --> Created: Сообщение получено
    Created --> Active: Первый ответ
    Active --> Active: Обмен сообщениями
    Active --> Idle: Нет активности
    Idle --> Active: Новое сообщение
    Idle --> Compacted: Автоматическое сжатие
    Compacted --> Active: Продолжение диалога
    Active --> Reset: Команда /reset
    Reset --> Created: Начало заново
    Active --> Pruned: Очистка сессии
    Idle --> Pruned: Очистка по таймауту
    Pruned --> [*]

Команды Session

Команды управления сессиями (отправляются в чате):

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

{
  "sessionPruning": {
    "enabled": true,
    "maxAge": 86400000,
    "maxSize": 100,
    "pruneOnStartup": true
  },
  "sessionCompression": {
    "enabled": true,
    "threshold": 50000,
    "targetRatio": 0.3
  }
}

Message Router — маршрутизация сообщений

Правила маршрутизации

Message Router отвечает за маршрутизацию входящих сообщений к нужной Session:

flowchart TB
    MSG[Сообщение получено] --> CH{Тип канала?}
    CH -->|Личное| DM[Извлечение ID отправителя]
    CH -->|Группа| GRP[Извлечение ID группы]
    CH -->|WebChat/CLI| MAIN[Использование main сессии]
    
    DM --> SID[Session: channel:user:id]
    GRP --> GID[Session: channel:group:id]
    
    SID --> EXISTS{Сессия существует?}
    GID --> EXISTS
    
    EXISTS -->|Да| LOAD[Загрузка сессии]
    EXISTS -->|Нет| CREATE[Создание новой сессии]
    
    CREATE --> LOAD
    LOAD --> AGENT[Передача Agent]

Конфигурация маршрутизации

{
  "messageRouting": {
    "defaultSession": "main",
    "channelMapping": {
      "telegram": {
        "userPrefix": "telegram:user",
        "groupPrefix": "telegram:group"
      },
      "whatsapp": {
        "userPrefix": "whatsapp:user",
        "groupPrefix": "whatsapp:group"
      }
    },
    "groupActivation": {
      "mode": "mention",
      "mentionPatterns": ["@bot", "/bot"]
    }
  }
}

Стратегии активации в группах

{
  "channels": {
    "telegram": {
      "groups": {
        "*": {
          "requireMention": true
        },
        "-100WORKGROUP": {
          "requireMention": false,
          "activationMode": "always"
        }
      }
    }
  }
}

Tool Registry — реестр инструментов

Встроенные инструменты

OpenClaw содержит богатый набор встроенных инструментов:

Управление правами инструментов

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "off",
        "allowlist": ["read", "write", "bash", "web_search"],
        "denylist": []
      }
    }
  }
}

Подробная конфигурация песочницы

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "allowlist": [
          "read",
          "write",
          "edit",
          "bash",
          "web_search",
          "sessions_list",
          "sessions_history"
        ],
        "denylist": [
          "browser",
          "canvas",
          "camera",
          "screen_record"
        ]
      }
    }
  }
}

Система навыков Skills

Архитектура Skills

flowchart LR
    subgraph Skills["Каталог Skills"]
        S1[gmail/SKILL.md]
        S2[calendar/SKILL.md]
        S3[home-assistant/SKILL.md]
    end
    
    subgraph Manager["Skills Manager"]
        DISC[Обнаружение]
        LOAD[Загрузка]
        EXEC[Выполнение]
    end
    
    subgraph Agent["Agent"]
        PROMPT[Инъекция в Prompt]
        TOOLS[Регистрация Tools]
        RES[Возврат результата]
    end
    
    Skills --> DISC
    DISC --> LOAD
    LOAD --> PROMPT
    LOAD --> TOOLS
    PROMPT --> Agent
    TOOLS --> Agent
    Agent --> EXEC
    EXEC --> RES

Структура каталога Skills

~/.openclaw/workspace/skills/
├── gmail/
│   ├── SKILL.md          # Определение навыка
│   ├── package.json      # Зависимости (опционально)
│   └── src/
│       └── index.js      # Реализация (опционально)
├── calendar/
│   └── SKILL.md
└── my-custom-skill/
    └── SKILL.md

Структура SKILL.md

# Gmail Skill

## Description
Send and read Gmail messages through OpenClaw.

## Triggers
- email
- gmail
- mail
- send email
- read email

## Instructions
When the user wants to send an email:
1. Ask for recipient, subject, and body
2. Use the gmail_send tool
3. Confirm the email was sent

When the user wants to check emails:
1. Use the gmail_list tool
2. Summarize the results

## Tools
- gmail_list: List recent emails
- gmail_send: Send an email
- gmail_read: Read a specific email

## Examples
User: "Check my email"
Action: Use gmail_list tool

User: "Send an email to [email protected]"
Action: Ask for subject and body, then use gmail_send

Способы установки Skills

# Установка из ClawHub
openclaw skill install gmail

# Установка из GitHub
openclaw skill install github:user/repo/skill-name

# Ручная установка
git clone https://github.com/user/skill-repo.git ~/.openclaw/workspace/skills/skill-name

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

{
  "skills": {
    "bundled": true,
    "managed": true,
    "workspace": true,
    "installGating": true
  }
}

Протокол WebSocket

Эндпоинт подключения

ws://127.0.0.1:18789/ws

Формат сообщений

{
  "type": "message_type",
  "id": "unique_message_id",
  "data": {
    // содержимое сообщения
  }
}

Типы клиентских сообщений

Типы серверных сообщений

Пример: отправка сообщения

// Подключение к WebSocket
const ws = new WebSocket('ws://127.0.0.1:18789/ws');

// Отправка сообщения
ws.send(JSON.stringify({
  type: 'agent.send',
  id: 'msg-001',
  data: {
    session: 'main',
    message: 'Привет, расскажи о себе'
  }
}));

// Получение ответа
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg);
  
  // Пример вывода:
  // {
  //   type: 'agent.response',
  //   id: 'msg-001',
  //   data: {
  //     content: 'Привет! Я твой помощник OpenClaw...',
  //     session: 'main'
  //   }
  // }
};

Event System — система событий

Встроенные события

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

{
  "webhooks": [
    {
      "url": "https://your-server.com/webhook/openclaw",
      "events": ["message.received", "tool.invoked"],
      "secret": "your_webhook_secret",
      "headers": {
        "X-Custom-Header": "value"
      }
    }
  ]
}

Полезная нагрузка Webhook

{
  "event": "message.received",
  "timestamp": "2026-02-26T10:30:00Z",
  "data": {
    "channel": "telegram",
    "sender": "123456789",
    "session": "telegram:user:123456789",
    "message": "Привет",
    "metadata": {
      "messageId": "msg_abc123",
      "timestamp": "2026-02-26T10:30:00Z"
    }
  },
  "signature": "sha256=..."
}

Cron — планирование задач

Пример конфигурации

{
  "cron": [
    {
      "id": "daily-briefing",
      "schedule": "0 9 * * *",
      "session": "main",
      "message": "Покажи моё расписание на сегодня",
      "enabled": true
    },
    {
      "id": "weekly-summary",
      "schedule": "0 18 * * 5",
      "session": "main",
      "message": "Сгенерируй сводку за неделю",
      "enabled": true
    }
  ]
}

Cron-выражения

┌───────────── минуты (0 - 59)
│ ┌───────────── часы (0 - 23)
│ │ ┌───────────── день месяца (1 - 31)
│ │ │ ┌───────────── месяц (1 - 12)
│ │ │ │ ┌───────────── день недели (0 - 6, 0 = воскресенье)
│ │ │ │ │
* * * * *

Распространённые примеры

Уровни и приоритеты конфигурации

Порядок приоритетов

Аргументы CLI > Переменные окружения > Конфигурационный файл > Значения по умолчанию

Источники конфигурации

Пример слияния конфигурации

// ~/.openclaw/openclaw.json
{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}

# Переопределение через переменную окружения
export OPENCLAW_AGENT_MODEL="anthropic/claude-sonnet-4"

# Переопределение через CLI (наивысший приоритет)
openclaw gateway --model "anthropic/claude-opus-4"

Горячее обновление конфигурации

# Обновление конфигурации (без перезапуска)
openclaw config set agent.model "anthropic/claude-sonnet-4"

# Перезагрузка конфигурационного файла
openclaw config reload

# Проверка конфигурации
openclaw config get agent.model

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

Управление Gateway

# Запуск Gateway
openclaw gateway

# С указанием порта
openclaw gateway --port 18790

# Запуск в фоне
openclaw gateway --daemon

# Подробные логи
openclaw gateway --verbose

# Проверка здоровья
openclaw health

Управление сессиями

# Список всех сессий
openclaw session list

# Просмотр деталей сессии
openclaw session show main
openclaw session show telegram:user:123456789

# Сброс сессии
openclaw session reset main

# Удаление сессии
openclaw session delete telegram:user:123456789

Управление конфигурацией

# Просмотр конфигурации
openclaw config get agent.model
openclaw config get channels.telegram.botToken

# Установка конфигурации
openclaw config set agent.thinkingLevel high

# Список всей конфигурации
openclaw config list

# Валидация конфигурации
openclaw config validate

Инструменты диагностики

# Полная диагностика
openclaw doctor

# Проверка конкретного компонента
openclaw doctor --check gateway
openclaw doctor --check config
openclaw doctor --check channels

# Просмотр логов
openclaw logs
openclaw logs --follow
openclaw logs --level error

Устранение неполадок

Gateway не запускается

# Проверка занятости порта
lsof -i :18789
netstat -tlnp | grep 18789

# Проверка синтаксиса конфигурации
openclaw config validate

# Просмотр подробных ошибок
openclaw gateway --verbose 2>&1 | tee gateway.log

Потеря сессий

# Проверка каталога сессий
ls -la ~/.openclaw/sessions/

# Проверка конфигурации очистки
openclaw config get sessionPruning

# Отключение автоматической очистки
openclaw config set sessionPruning.enabled false

Ошибки при вызове инструментов

# Проверка конфигурации песочницы
openclaw config get agents.defaults.sandbox

# Временное отключение песочницы
openclaw config set agents.defaults.sandbox.mode off

# Просмотр логов инструментов
openclaw logs --filter tool

Ошибка подключения WebSocket

# Проверка статуса Gateway
curl http://127.0.0.1:18789/health

# Проверка WebSocket-эндпоинта
wscat -c ws://127.0.0.1:18789/ws

# Проверка файрвола
sudo ufw status
sudo iptables -L -n | grep 18789

Итоги

Понимание ключевых концепций Gateway — залог успешной работы с OpenClaw:

• Session: контейнер контекста диалога с поддержкой изоляции по типам
• Message Router: ядро маршрутизации, определяющее направление сообщений
• Tool Registry: центр регистрации инструментов, управляющий возможностями Agent
• Skills: система расширения навыков для быстрого улучшения функциональности
• WebSocket: протокол реального времени с поддержкой пользовательских клиентов
• Event System: механизм распределения событий с поддержкой Webhook и Cron

Эти концепции будут встречаться в последующих статьях. Глубокое их понимание поможет более эффективно настраивать и использовать OpenClaw.

Итоги статьи:

• Освоена общая архитектура Gateway и обязанности компонентов
• Понята модель сессий Session и жизненный цикл
• Изучены маршрутизация сообщений и стратегии активации в группах
• Рассмотрены права инструментов и конфигурация песочницы
• Освоены протокол WebSocket и система событий

История обновлений:

• 2026-02-26: первая публикация, на основе OpenClaw v2026.2

Навигация по серии:

• ← Предыдущая статья: Настройка каналов: начинаем с Telegram
• → Следующая статья: Мульти-модельная конфигурация и переключение