Руководство по разработке ClawX

Этот документ содержит подробную версию раздела «Разработка» из README.

Требования

Node.js: 22.22.3+, 24.15.0+ или 25.9.0+ в пределах соответствующей основной версии (рекомендуется Node 24 LTS)
Менеджер пакетов: pnpm 9+ (npm также поддерживается)
Linux (Ubuntu/Debian): перед запуском Electron установите необходимые системные библиотеки:
```
sudo apt-get install -y libnss3 libgtk-3-0 libxss1 libxtst6 libatspi2.0-0 libnotify4 xdg-utils
```
В Ubuntu 24.04+ некоторые пакеты используют суффикс t64; после выполнения команды apt автоматически выберет подходящий вариант.

Структура проекта

ClawX/
├── electron/                 # Главный процесс Electron
│   ├── services/            # Типизированные Host API, провайдеры, секреты и runtime-сервисы
│   │   ├── providers/       # Логика синхронизации моделей provider/account
│   │   └── secrets/         # Связка ключей ОС и хранилище секретов
│   ├── shared/              # Общие схемы провайдеров и константы
│   │   └── providers/
│   ├── main/                # Точка входа приложения, окна и регистрация IPC
│   ├── gateway/             # Менеджер процесса OpenClaw Gateway
│   ├── preload/             # Безопасный IPC-мост
│   └── utils/               # Утилиты для хранилища, аутентификации и путей
├── src/                      # Процесс Renderer на React
│   ├── lib/                 # Унифицированный фронтенд API и модель ошибок
│   ├── stores/              # Хранилища Zustand (settings/chat/gateway)
│   ├── components/          # Переиспользуемые UI-компоненты
│   ├── pages/               # Setup/Dashboard/Chat/Channels/Skills/Cron/Settings
│   ├── i18n/                # Ресурсы локализации
│   └── types/               # Определения типов TypeScript
├── tests/
│   ├── e2e/                 # Сквозные дымовые тесты Playwright Electron
│   └── unit/                # Модульные и интеграционные тесты Vitest
├── resources/                # Статические ресурсы (иконки и изображения)
└── scripts/                  # Скрипты сборки и утилит

Доступные команды

# Разработка
pnpm run init             # Установить зависимости и скачать встроенные бинарные файлы (uv, agent-browser)
pnpm dev                  # Запуск с горячей перезагрузкой (автоподготовка bundled skills при отсутствии)

# Качество
pnpm lint                 # Запустить ESLint
pnpm typecheck            # Проверить типы TypeScript

# Тестирование
pnpm test                 # Запустить модульные тесты
pnpm run test:e2e         # Запустить дымовые E2E-тесты Electron
pnpm run test:e2e:headed  # Запустить E2E-тесты Electron с видимым окном
pnpm run perf:chat        # Получить синтетические CPU-профили Chat Renderer/Main
pnpm run profile:main     # Запустить собранное приложение с Main inspector на порту 9229
pnpm run comms:replay     # Рассчитать метрики повторного воспроизведения коммуникаций
pnpm run comms:baseline   # Обновить снимок базовой линии коммуникаций
pnpm run comms:compare    # Сравнить метрики с порогами базовой линии

# Сборка и упаковка
pnpm run build:vite       # Собрать только фронтенд
pnpm build                # Полная production-сборка с ресурсами упаковки
pnpm package              # Упаковать для текущей платформы со встроенными навыками
pnpm package:mac          # Упаковать для macOS
pnpm package:win          # Упаковать для Windows
pnpm package:linux        # Упаковать для Linux

В headless Linux тестам Electron нужен сервер отображения. Используйте xvfb-run -a pnpm run test:e2e.

Функциональные E2E-тесты Electron локально и в CI по умолчанию используют два worker-процесса Playwright. Обычную параллельную группу можно настроить через CLAWX_E2E_WORKERS=<положительное целое>. Тесты, затрагивающие глобальное состояние ОС, используют однопоточный проект exclusive, а профили производительности хоста запускаются отдельно после них. Новые E2E-тесты по умолчанию параллельны; при использовании реального буфера обмена или другого общего ресурса машины применяйте E2E_EXCLUSIVE_TAG из tests/e2e/parallel-policy.ts.

Для запуска отдельного обычного spec без эксклюзивного предварительного этапа используйте pnpm exec playwright test <spec> --project=parallel --no-deps.

Диагностика производительности Electron

pnpm run perf:chat запускает изолированные синтетические ACP-нагрузки для потоковой выдачи и взаимодействия с боковой панелью и прокруткой в статическом Markdown-документе. В каталог Playwright test-results/ записываются версионированные метрики и CPU-профили Renderer и Main. Профили Renderer охватывают production store/render-путь и плавность кадров. Потоковый профиль Main измеряет IPC fanout от Main к Renderer, а профиль интеракций показывает, остаётся ли Main свободным во время действий Renderer. Ни один профиль не включает процессы upstream OpenClaw/ACP или путь GPU-процесса.

CPU-профиль можно открыть в Chrome DevTools. Артефакты содержат только сгенерированный fixture-текст и не являются телеметрией продукта. Результаты зависят от оборудования, поэтому сравнивайте повторные запуски на одной машине, а не применяйте единый абсолютный порог для разных платформ.

Для записи реального Renderer запустите разработку командой CLAWX_REMOTE_DEBUGGING_PORT=9223 pnpm dev и подключите Playwright или Chrome DevTools к localhost:9223. Для записи реального Electron Main выполните pnpm run profile:main, откройте chrome://inspect, настройте localhost:9229 и выберите цель Electron Main. Не устанавливайте CLAWX_GATEWAY_WS_TRACE, если измеряется не сам WebSocket trace.

ClawX по умолчанию оставляет аппаратное ускорение Chromium включённым, чтобы длинные документы, прокрутка и анимации layout использовали GPU-композицию и растеризацию. При проблемах с графическим драйвером можно использовать встроенный переключатель Chromium --disable-gpu как резервный вариант диагностики.

Проверки регрессии коммуникаций

Если PR изменяет пути коммуникации, включая события Gateway, поток отправки/получения ACP Chat, доставку каналов или транспортный fallback, выполните:

pnpm run comms:replay
pnpm run comms:compare

Задача CI comms-regression проверяет обязательные сценарии и пороги.

E2E-тесты Electron

Набор Playwright Electron запускает упакованные Renderer и Main-процессы из dist/ и dist-electron/, поэтому заранее вручную запускать pnpm dev не требуется.

pnpm run test:e2e автоматически:

собирает Renderer и бандлы Electron через pnpm run build:vite
запускает Electron в изолированном E2E-режиме с временным HOME
использует временный каталог userData ClawX
запускает обычные spec-файлы параллельно, изолируя тесты глобальных ресурсов ОС и производительности
пропускает тяжёлые побочные эффекты запуска, такие как автозапуск Gateway, установка bundled skills, создание трея и автоустановка CLI

Первые базовые spec покрывают:

видимость Setup Wizard при первом запуске на чистом профиле
пропуск настройки и переход на страницу Models внутри приложения Electron

Добавляйте будущие сценарии Electron в tests/e2e/ и переиспользуйте общий fixture из tests/e2e/fixtures/electron.ts. Сохраняйте тесты безопасными для параллельного запуска: избегайте фиксированных доступных для записи путей, портов, нативных хранилищ ключей и другого внешнего общего состояния. Если изоляция невозможна, используйте E2E_EXCLUSIVE_TAG.

Технологический стек

Уровень	Технология
Среда выполнения	Electron 40+
UI-фреймворк	React 19 + TypeScript
Стилизация	Tailwind CSS + shadcn/ui
Состояние	Zustand
Сборка	Vite + electron-builder
Тестирование	Vitest + Playwright
Анимация	Framer Motion
Иконки	Lucide React

12 KiB Raw Blame History Unescape Escape