
<p align="center">
<img src="src/assets/logo.svg" width="128" height="128" alt="ClawX Logo" />
</p>

<h1 align="center">ClawX</h1>

<p align="center">
<strong>Десктоп-интерфейс для AI-агентов OpenClaw</strong>
</p>

<p align="center">
<a href="#возможности">Возможности</a> •
<a href="#почему-clawx">Почему ClawX</a> •
<a href="#быстрый-старт">Быстрый старт</a> •
<a href="#архитектура">Архитектура</a> •
<a href="#разработка">Разработка</a> •
<a href="#участие">Участие</a>
</p>

<p align="center">
<img src="https://img.shields.io/badge/platform-MacOS%20%7C%20Windows%20%7C%20Linux-blue" alt="Platform" />
<img src="https://img.shields.io/badge/electron-40+-47848F?logo=electron" alt="Electron" />
<img src="https://img.shields.io/badge/react-19-61DAFB?logo=react" alt="React" />
<a href="https://discord.com/invite/84Kex3GGAh" target="_blank">
<img src="https://img.shields.io/discord/1399603591471435907?logo=discord&labelColor=%20%235462eb&logoColor=%20%23f5f5f5&color=%20%235462eb" alt="chat on Discord" />
</a>
<img src="https://img.shields.io/github/downloads/ValueCell-ai/ClawX/total?color=%23027DEB" alt="Downloads" />
<img src="https://img.shields.io/badge/license-MIT-green" alt="License" />
</p>

<p align="center">
<a href="README.md">English</a> | <a href="README.zh-CN.md">简体中文</a> | <a href="README.ja-JP.md">日本語</a> | Русский
</p>

---

## Обзор

**ClawX** — это мост между мощными AI-агентами и повседневными пользователями. Построенный на базе [OpenClaw](https://github.com/OpenClaw), он превращает управление AI через командную строку в доступный и красивый десктоп-опыт — терминал не нужен.

Автоматизация рабочих процессов, управление AI-каналами или планирование интеллектуальных задач — ClawX предоставляет интерфейс для эффективного использования AI-агентов.

ClawX поставляется с предустановленными лучшими практиками для провайдеров моделей и нативно поддерживает Windows, а также многоязычные настройки. Вы можете тонко настроить расширенные параметры через **Настройки → Дополнительно → Режим разработчика**.

---

## Скриншоты

<p align="center">
<img src="resources/screenshot/ru/chat.png" style="width: 100%; height: auto;">
</p>

<p align="center">
<img src="resources/screenshot/ru/cron.png" style="width: 100%; height: auto;">
</p>

<p align="center">
<img src="resources/screenshot/ru/skills.png" style="width: 100%; height: auto;">
</p>

<p align="center">
<img src="resources/screenshot/ru/channels.png" style="width: 100%; height: auto;">
</p>

<p align="center">
<img src="resources/screenshot/ru/models.png" style="width: 100%; height: auto;">
</p>

<p align="center">
<img src="resources/screenshot/ru/settings.png" style="width: 100%; height: auto;">
</p>

---

## Почему ClawX

Создание AI-агентов не должно требовать владения командной строкой. Философия ClawX проста: **мощные технологии заслуживают интерфейса, который уважает ваше время.**

| Проблема | Решение ClawX |
|----------|---------------|
| Сложная настройка через CLI | Установка в один клик с мастером настройки |
| Редактирование конфигурационных файлов | Визуальные настройки с проверкой в реальном времени |
| Управление процессами | Автоматическое управление жизненным циклом шлюза |
| Несколько AI-провайдеров | Единая панель настройки провайдеров |
| Установка навыков/плагинов | Встроенный маркетплейс и управление навыками |

### OpenClaw внутри

ClawX построен непосредственно на официальном ядре **OpenClaw**. Вместо отдельной установки мы встраиваем среду выполнения в приложение для бесшовного опыта "всё включено".

Мы стремимся поддерживать строгое соответствие с проектом OpenClaw, чтобы вы всегда имели доступ к новейшим возможностям, улучшениям стабильности и совместимости с экосистемой.

---

## Возможности

### 🎯 Нулевой порог настройки
Весь процесс — от установки до первого взаимодействия с AI — выполняется через интуитивный графический интерфейс. Без терминальных команд, без YAML-файлов, без поиска переменных окружения.

### 💬 Интеллектуальный интерфейс чата
Общайтесь с AI-агентами через современный чат. Поддержка нескольких контекстов разговора, истории сообщений, рендеринга Markdown и прямая маршрутизация через `@agent` в главном поле ввода для мультиагентных конфигураций.
При выборе другого агента через `@agent` ClawX переключается непосредственно в контекст этого агента вместо ретрансляции через агента по умолчанию. Рабочие пространства агентов по умолчанию разделены, но более строгая изоляция зависит от настроек песочницы OpenClaw.
Каждый агент может переопределить свои настройки `provider/model`; агенты без переопределения продолжают наследовать глобальную модель по умолчанию.

### 📡 Управление несколькими каналами
Настраивайте и отслеживайте несколько AI-каналов одновременно. Каждый канал работает независимо, позволяя запускать специализированных агентов для разных задач.
Каждый канал теперь поддерживает несколько учётных записей, привязку агента к учётной записи и переключение канала по умолчанию прямо на странице Каналы.
Для пользовательских идентификаторов учётных записей каналов ClawX требует совместимый с OpenClaw канонический формат (`[a-z0-9_-]`, строчные буквы, максимум 64 символа, должен начинаться с буквы или цифры) для предотвращения ошибок маршрутизации.
ClawX также включает официальный плагин личного WeChat от Tencent, позволяя подключить WeChat напрямую со страницы Каналы через встроенный QR-код.

### ⏰ Автоматизация по расписанию
Планируйте автоматический запуск AI-задач. Определяйте триггеры, устанавливайте интервалы и позволяйте AI-агентам работать круглосуточно без ручного вмешательства.
На странице Cron теперь можно настроить внешнюю доставку непосредственно в форме задачи с отдельными селекторами учётной записи отправителя и цели получателя. Для поддерживаемых каналов цели получателей автоматически обнаруживаются из каталогов каналов или известной истории сессий, поэтому больше не нужно редактировать `jobs.json` вручную.

### 🧩 Расширяемая система навыков
Расширяйте возможности AI-агентов готовыми навыками. Просматривайте, устанавливайте и управляйте навыками через встроенную панель — менеджеры пакетов не нужны.
ClawX также предварительно упаковывает полные навыки обработки документов (`pdf`, `xlsx`, `docx`, `pptx`), автоматически развёртывает их в управляемый каталог навыков (по умолчанию `~/.openclaw/skills`) при запуске и включает по умолчанию при первой установке. Дополнительные упакованные навыки (`find-skills`, `self-improving-agent`, `tavily-search`, `brave-web-search`) также включены по умолчанию; если необходимые API-ключи отсутствуют, OpenClaw покажет ошибки конфигурации во время выполнения.
На странице Навыки отображаются навыки из нескольких источников OpenClaw (управляемый каталог, workspace и дополнительные каталоги навыков), а также показывается фактическое расположение каждого навыка для прямого открытия папки.

Переменные окружения для встроенных поисковых навыков:
- `BRAVE_SEARCH_API_KEY` для `brave-web-search`
- `TAVILY_API_KEY` для `tavily-search` (OAuth также может поддерживаться вышестоящей средой выполнения)
- `find-skills` и `self-improving-agent` не требуют API-ключей

### 🔐 Безопасная интеграция провайдеров
Подключайтесь к нескольким AI-провайдерам (OpenAI, Anthropic и др.) с учётными данными, безопасно хранящимися в системной связке ключей. OpenAI поддерживает как API-ключи, так и OAuth через браузер (подписка Codex).
Для провайдеров **Custom**, используемых с OpenAI-совместимыми шлюзами, вы можете установить пользовательский `User-Agent` в **Настройки → AI Провайдеры → Редактировать провайдера** для совместимости с чувствительными эндпоинтами.
Когда совместимый шлюз отклоняет `/models` по причинам, не связанным с аутентификацией, ClawX автоматически переключается на легковесный зонд `/chat/completions` или `/responses` при проверке API-ключа.

### 🌙 Адаптивные темы
Светлая тема, тёмная тема или синхронизация с системой. ClawX автоматически адаптируется к вашим предпочтениям.

### 🚀 Управление автозапуском
В **Настройки → Общие** вы можете включить **Запускать при старте системы**, чтобы ClawX автоматически запускался после входа в систему.

---

## Быстрый старт

### Системные требования

- **Операционная система**: macOS 11+, Windows 10+ или Linux (Ubuntu 20.04+)
- **Память**: минимум 4 ГБ RAM (рекомендуется 8 ГБ)
- **Хранилище**: 1 ГБ свободного места на диске

### Установка

#### Готовые релизы (рекомендуется)

Скачайте последний релиз для вашей платформы со страницы [Releases](https://github.com/ValueCell-ai/ClawX/releases).

#### Сборка из исходников

```bash
# Клонирование репозитория
git clone https://github.com/ValueCell-ai/ClawX.git
cd ClawX

# Инициализация проекта
pnpm run init

# Запуск в режиме разработки
pnpm dev
```

### Первый запуск

При первом запуске ClawX **Мастер настройки** проведёт вас через:

1. **Язык и регион** — настройка предпочтительного языка и региона
2. **AI-провайдер** — добавление провайдеров с API-ключами или OAuth (для провайдеров, поддерживающих вход через браузер/устройство)
3. **Пакеты навыков** — выбор предустановленных навыков для распространённых сценариев
4. **Проверка** — тестирование конфигурации перед входом в основной интерфейс

Мастер предварительно выбирает системный язык, если он поддерживается, иначе переключается на английский.

### Настройки прокси

ClawX включает встроенные настройки прокси для сред, где Electron, шлюз OpenClaw или каналы вроде Telegram должны выходить в интернет через локальный прокси-клиент.

Откройте **Настройки → Шлюз → Прокси** и настройте:

- **Прокси-сервер**: прокси по умолчанию для всех запросов
- **Правила обхода**: хосты, которые должны подключаться напрямую, разделённые точкой с запятой, запятыми или новыми строками
- В **Режиме разработчика** можно дополнительно переопределить:
  - **HTTP Прокси**
  - **HTTPS Прокси**
  - **ALL_PROXY / SOCKS**

Рекомендуемые примеры локальных настроек:

```text
Прокси-сервер: http://127.0.0.1:7890
```
Примечания:

- Значение `host:port` рассматривается как HTTP.
- Если расширенные поля прокси пусты, ClawX использует `Прокси-сервер`.
- Сохранение настроек прокси немедленно повторно применяет сеть Electron и автоматически перезапускает шлюз.
- ClawX также синхронизирует прокси с конфигурацией канала Telegram в OpenClaw, когда Telegram включён.
- При перезапуске шлюза существующий прокси канала Telegram сохраняется, если прокси ClawX отключен.
- Чтобы явно очистить прокси Telegram из конфигурации OpenClaw, сохраните настройки прокси с отключенным прокси.
- В **Настройки → Дополнительно → Разработчик** можно запустить **OpenClaw Doctor** для выполнения `openclaw doctor --json` и просмотра диагностического вывода, не покидая приложение.
- В упакованных сборках Windows встроенный `openclaw` CLI/TUI запускается через поставляемый `node.exe` для стабильного поведения ввода в терминале.

---

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

ClawX использует **двухпроцессную архитектуру с унифицированным уровнем Host API**. Рендерер обращается к единой абстракции клиента, а Electron Main управляет выбором протокола и жизненным циклом процессов:

```
┌─────────────────────────────────────────────────────────────────┐
│                     Десктоп-приложение ClawX                    │
│                                                                 │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │               Главный процесс Electron                     │ │
│  │  • Управление жизненным циклом окна и приложения          │ │
│  │  • Наблюдение за процессом шлюза                          │ │
│  │  • Интеграция с системой (трей, уведомления, связка ключей)│ │
│  │  • Оркестрация автообновлений                             │ │
│  └────────────────────────────────────────────────────────────┘ │
│                            │                                    │
│                   IPC (авторитетная плоскость управления)       │
│                            ▼                                    │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │               Процесс рендерера React                      │ │
│  │  • Современный UI на компонентах (React 19)               │ │
│  │  • Управление состоянием с Zustand                        │ │
│  │  • Унифицированные вызовы host-api/api-client             │ │
│  │  • Рендеринг Markdown                                     │ │
│  └────────────────────────────────────────────────────────────┘ │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                Стратегия транспорта, управляемая Main
                   (Сначала WS, затем HTTP, затем IPC)
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                 Host API и прокси-уровень Main                  │
│                                                                 │
│  • hostapi:fetch (прокси Main, избегает CORS в dev/prod)        │
│  • gateway:httpProxy (Рендерер не вызывает Gateway HTTP напрямую)│
│  • Унифицированное отображение ошибок и повторные попытки       │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                    Резерв WS / HTTP / IPC
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Шлюз OpenClaw                              │
│                                                                 │
│  • Среда выполнения AI-агентов и оркестрация                   │
│  • Управление каналами сообщений                               │
│  • Среда выполнения навыков/плагинов                           │
│  • Уровень абстракции провайдеров                              │
└─────────────────────────────────────────────────────────────────┘
```

### Принципы проектирования

- **Изоляция процессов**: Среда выполнения AI работает в отдельном процессе, обеспечивая отзывчивость UI даже при тяжёлых вычислениях
- **Единая точка входа для фронтенда**: Запросы рендерера проходят через host-api/api-client; детали протокола скрыты за стабильным интерфейсом
- **Владение транспортом в Main**: Electron Main управляет использованием WS/HTTP и откатом к IPC для надёжности
- **Корректное восстановление**: Встроенная логика переподключения, таймаутов и отката автоматически обрабатывает временные сбои
- **Безопасное хранение**: API-ключи и конфиденциальные данные используют нативные механизмы безопасного хранения ОС
- **Безопасность CORS**: Локальный HTTP-доступ проксируется через Main, предотвращая CORS-проблемы на стороне рендерера

### Модель процессов и устранение неполадок шлюза

- ClawX — это приложение Electron, поэтому **один экземпляр приложения обычно отображается как несколько процессов ОС** (main/renderer/zygote/utility). Это нормально.
- Защита единственного экземпляра использует блокировку Electron плюс локальный файл блокировки процессов, предотвращая дублирование запуска приложения в средах с нестабильным IPC/сессионной шиной.
- При последовательных обновлениях смешанные старые/новые версии могут иметь асимметричное поведение защиты. Для лучшей надёжности обновите все десктоп-клиенты до одной версии.
- Слушатель шлюза OpenClaw должен быть **единственным владельцем**: только один процесс должен слушать `127.0.0.1:18789`.
- Для проверки активного слушателя:
  - macOS/Linux: `lsof -nP -iTCP:18789 -sTCP:LISTEN`
  - Windows (PowerShell): `Get-NetTCPConnection -LocalPort 18789 -State Listen`
- Нажатие кнопки закрытия окна (`X`) скрывает ClawX в трей; это **не** полностью закрывает приложение. Используйте меню трея **Quit ClawX** для полного завершения.

---

## Варианты использования

### 🤖 Персональный AI-ассистент
Настройте универсального AI-агента, который может отвечать на вопросы, составлять письма, резюмировать документы и помогать с повседневными задачами — всё через чистый десктоп-интерфейс.

### 📊 Автоматизированный мониторинг
Настройте запланированных агентов для отслеживания новостных лент, цен или определённых событий. Результаты доставляются в ваш предпочтительный канал уведомлений.

### 💻 Производительность разработчика
Интегрируйте AI в рабочий процесс разработки. Используйте агентов для проверки кода, генерации документации или автоматизации повторяющихся задач кодирования.

### 🔄 Автоматизация рабочих процессов
Связывайте несколько навыков для создания сложных конвейеров автоматизации. Обрабатывайте данные, преобразовывайте контент и запускайте действия — всё визуально оркестрируется.

---

## Разработка

### Требования

- **Node.js**: 22+ (рекомендуется LTS)
- **Менеджер пакетов**: pnpm 9+ (рекомендуется) или npm

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

```
ClawX/
├── electron/                 # Главный процесс Electron
│   ├── api/                  # Маршрутизатор API и обработчики Main
│   │   └── routes/           # Модули маршрутов RPC/HTTP прокси
│   ├── services/             # Службы провайдеров, секретов и среды выполнения
│   │   ├── providers/        # Логика синхронизации моделей provider/account
│   │   └── secrets/          # Связка ключей ОС и хранилище секретов
│   ├── shared/               # Общие схемы провайдеров и константы
│   │   └── providers/
│   ├── main/                 # Точка входа приложения, окна, регистрация IPC
│   ├── gateway/              # Менеджер процесса шлюза OpenClaw
│   ├── preload/              # Безопасный IPC-мост
│   └── utils/                # Утилиты (хранилище, аутентификация, пути)
├── src/                      # Процесс рендерера 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/                  # Скрипты сборки и утилит
```

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

```bash
# Разработка
pnpm run init                 # Установить зависимости + скачать uv
pnpm dev                      # Запуск с горячей перезагрузкой (автоподготовка упакованных навыков при отсутствии)

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

# Тестирование
pnpm test                     # Запустить модульные тесты
pnpm run test:e2e             # Запустить E2E дымовые тесты Electron с Playwright
pnpm run test:e2e:headed      # Запустить E2E тесты Electron с видимым окном
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`.

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

Когда PR изменяет пути коммуникации (события шлюза, поток отправки/получения чата, доставка каналов или откат транспорта), запустите:

```bash
pnpm run comms:replay
pnpm run comms:compare
```

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

### E2E-тесты Electron

Сьют Playwright Electron запускает упакованный рендерер и главный процесс из `dist/` и `dist-electron/`, поэтому не требует предварительного ручного запуска `pnpm dev`.

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

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

Первые два базовых спецификации покрывают:

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

Добавляйте будущие потоки Electron в `tests/e2e/` и переиспользуйте общий fixture в `tests/e2e/fixtures/electron.ts`.

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

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

---

## Участие

Мы приветствуем вклад сообщества! Исправления багов, новые функции, улучшения документации или переводы — каждый вклад делает ClawX лучше.

### Как внести вклад

1. **Сделайте форк** репозитория
2. **Создайте** ветку функции (`git checkout -b feature/amazing-feature`)
3. **Зафиксируйте** изменения с понятными сообщениями
4. **Отправьте** в свою ветку
5. **Откройте** Pull Request

### Руководящие принципы

- Следуйте существующему стилю кода (ESLint + Prettier)
- Пишите тесты для нового функционала
- Обновляйте документацию по мере необходимости
- Держите коммиты атомарными и описательными

---

## Благодарности

ClawX построен на плечах отличных проектов с открытым исходным кодом:

- [OpenClaw](https://github.com/OpenClaw) – Среда выполнения AI-агентов
- [Electron](https://www.electronjs.org/) – Кроссплатформенный десктоп-фреймворк
- [React](https://react.dev/) – Библиотека UI-компонентов
- [shadcn/ui](https://ui.shadcn.com/) – Красиво спроектированные компоненты
- [Zustand](https://github.com/pmndrs/zustand) – Легковесное управление состоянием

---

## Сообщество

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

| WeChat Enterprise | Feishu Group | Discord |
| :---: | :---: | :---: |
| <img src="src/assets/community/wecom-qr.png" width="150" alt="WeChat QR Code" /> | <img src="src/assets/community/feishu-qr.png" width="150" alt="Feishu QR Code" /> | <img src="src/assets/community/20260212-185822.png" width="150" alt="Discord QR Code" /> |

### Партнёрская программа ClawX 🚀

Мы запускаем Партнёрскую программу ClawX и ищем партнёров, которые могут помочь представить ClawX большему числу клиентов, особенно тем, у кого есть потребности в кастомных AI-агентах или автоматизации.

Партнёры помогают связывать нас с потенциальными пользователями и проектами, а команда ClawX предоставляет полную техническую поддержку, кастомизацию и интеграцию.

Если вы работаете с клиентами, заинтересованными в AI-инструментах или автоматизации, мы будем рады сотрудничеству.

Напишите нам в DM или на [public@valuecell.ai](mailto:public@valuecell.ai) для получения дополнительной информации.

---

## История звёзд

<p align="center">
<img src="https://api.star-history.com/svg?repos=ValueCell-ai/ClawX&type=Date" alt="Star History Chart" />
</p>

---

## Лицензия

ClawX выпускается под [лицензией MIT](LICENSE). Вы можете свободно использовать, модифицировать и распространять это программное обеспечение.

---

<p align="center">
<sub>Создано с ❤️ командой ValueCell</sub>
</p>
