ClawX/docs/ru-RU/architecture.md

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

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

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

Доставка конфигурации OpenClaw также управляется Electron Main. Когда Gateway запущен, ClawX использует авторитетный снимок из config.get как основу и применяет изменения через config.set. Когда Gateway остановлен или запускается, тот же координатор обновляет разрешённый JSON5-файл конфигурации, не запуская Gateway из-за этого обновления. Поэтому обычные изменения провайдера, агента, канала, привязки, навыка и модели не заменяют процесс Gateway. Полные перезапуски остаются только для изменений среды запуска процесса, например прокси, и явных действий пользователя. Подтверждённые завершения процесса и закрытия WebSocket используют существующие пути автоматического переподключения. Первые три последовательных пропуска WebSocket heartbeat являются только диагностикой, поэтому краткая задержка pong не прерывает долгую операцию; pong или любое входящее сообщение сбрасывает счётчик, а при четвёртом последовательном пропуске запрашивается защищённое автоматическое восстановление Gateway, если его жизненный цикл находится в состоянии running с разрешённым автовосстановлением. После записи конфигурации аутентификации в SQLite ClawX вызывает secrets.reload OpenClaw, чтобы работающие агенты получили новые учётные данные без перезапуска процесса.

Chat использует ACP stdio bridge, принадлежащий Electron Main. Main передаёт тому же локальному дочернему процессу управляемый приложением Gateway token через приватное окружение процесса, поэтому после перезагрузки конфигурации среды выполнения воспроизведение истории ACP остаётся аутентифицированным. Если защищённое восстановление Gateway прерывает принятый run основной сессии, исправленная среда OpenClaw запускает отдельный восстановительный run с явной ссылкой на id прерванного run. События Chat и agent сохраняют эту связь; переподключившийся ACP bridge принимает новый run для ожидающего prompt, сбрасывает потоковые курсоры run и подписывается на события инструментов сессии. Renderer не использует идентификатор среды Gateway и продолжает строить одну ACP timeline в памяти из типизированных host events. Gateway продолжает отвечать за возможности вне Chat: providers, models, skills, workspace, settings, diagnostics и media configuration.

Семантический авторитет ACP

ACP является предпочтительным семантическим источником для каждого значения и контекста Chat, которые он предоставляет, а не только для истории session/load. Сюда относятся, где применимо, идентификатор сессии и маршрутизация, рабочее пространство и исполняемый cwd, состояние prompt и timeline, а также семантика стандартных resource и вложений. Если ACP предоставляет значение или событие, Main и Renderer должны использовать его, а не заменять снимком Gateway, выводом из transcript, локальной конфигурацией или параллельной проекцией.

Обход ACP разрешён только тогда, когда в upstream нет эквивалентной возможности. Такой путь совместимости должен быть узким, ограниченным и привязанным к session и generation. В соответствующем Harness reference или rule необходимо указать причину, источник истины, ограничения, поведение согласования и условие удаления; обход не должен незаметно стать конкурирующим источником истины.

Авторитет истории ACP и ограниченные дополнения из transcript

Воспроизведение ACP session/load является главным источником истории Chat. ClawX не сохраняет второй ACP ledger, сокращённую timeline, кэш воспроизведения или восстановленную историю инструментов. Если структурированный ACP event ledger OpenClaw недоступен, его ACP adapter преобразует сохранённые записи transcript toolCall и toolResult в нативные обновления инструментов в исходном порядке, сохраняя границы text-tool-text; сам ClawX эти записи не выводит. Некоторые возможности OpenClaw пока не имеют полного соответствия в ACP. Например, media assistant может отсутствовать в ACP, а обработка Gateway может удалять директивы assistant MEDIA: из видимого потокового ответа. Поэтому ClawX хранит только ограниченные, помеченные дополнения совместимости в памяти:

• Асинхронное завершение генерации изображения можно восстановить только при наличии подтверждённого контекста image_generate в той же сессии и доверенного либо разрешённого transcript-доказательства.
• Обычные вложения можно восстановить из канонических сохранённых фактов assistant __openclaw.media или явных директив assistant MEDIA: в начале строки. Восстанавливаются только ссылки на вложения и объявленные метаданные, но не окружающее сообщение assistant.
• Поскольку ACP replay не содержит исходных временных меток событий, Main может добавить метаданные длительности всего хода из ограниченных записей transcript JSONL. Они могут быть привязаны только к уже восстановленному ACP-ходу.
• Если ACP replay cron-сессии полностью пуст, типизированный API истории cron в Main может предоставить запланированный запрос и сводку завершения. Если сводка идентифицированного запуска содержит маркер усечения OpenClaw, Main может восстановить финальный текст assistant из transcript этого запуска только когда transcript длиннее и содержит полный сохранённый префикс сводки.

Историческое чтение ограничено последними 1000 сообщениями transcript. Успешный live prompt выполняет одно немедленное чтение и одну повторную попытку через 1500 мс. Каждое дополнение привязано к точной session, ACP generation, операции и, где применимо, текущему пользовательскому ходу; устаревшие, отсутствующие, дублирующиеся и неоднозначные совпадения отбрасываются. Эти пути не должны восстанавливать обычные сообщения assistant, thoughts, tools, plans, permissions, файловые операции, пропущенные ходы или параллельную историю Chat. Main не создаёт нативные события ACP из transcript-доказательств. Стандартные ACP resources остаются предпочтительными, а после появления эквивалентного контента upstream эти исключения совместимости должны быть удалены.

Незавершённый ответ ACP продолжает потоковую выдачу при открытии другого разговора или страницы. Возврат до завершения восстанавливает последнюю timeline в памяти и продолжает отображение ответа. После завершения обычное воспроизведение истории ACP остаётся источником истины.

Ходы assistant в ACP показывают длительность всего хода. Живой таймер следует за наблюдаемым клиентом жизненным циклом prompt и сохраняется при навигации внутри приложения. Историческая длительность вычисляется Electron Main по ограниченным временным меткам transcript OpenClaw и добавляется только к ходу, уже восстановленному ACP replay.

ACP Chat отображает стандартные ACP resources как вложения. Выбранные пользователем изображения показываются как миниатюры с именем файла при наведении, а другие доступные карточки вложений содержат имя файла и приглушённый обрезаемый исходный путь. Если текущий OpenClaw ACP adapter не передаёт media assistant, канонические сохранённые факты media OpenClaw и явные директивы assistant MEDIA: также могут быть восстановлены как карточки вложений без отображения метаданных, предназначенных только для transcript.

Существующие локальные ссылки на файлы, включая пути за пределами активного рабочего пространства, перед каждым предпросмотром или открытием повторно проверяются Electron Main для точной session и generation. Локальные вложения, созданные AI и доступные для предпросмотра, включая .docx и .pptx размером до 20 МБ, сохраняют основное действие предпросмотра только для чтения внутри приложения и дополнительное меню для открытия совместимым приложением или показа в Finder, File Explorer либо системном файловом менеджере. Для локальных HTML-вложений первый пункт меню открывает файл во вкладке Preview справа.

Для Office действуют те же ограничения: .doc и .ppt открываются системным приложением, разбиение DOCX на страницы может отличаться от Microsoft Word, а анимации, переходы и воспроизведение медиа в PPTX не поддерживаются. Поиск совместимых приложений доступен только в macOS и Windows; в Linux или при ошибке поиска происходит незаметный переход к действию показа расположения. Остальные локальные файлы, включая Office-файлы размером более 20 МБ, открываются системным приложением после нажатия пользователя. Выбранные пользователем папки остаются доступными после отправки и открываются системным файловым менеджером; ClawX не читает и не просматривает их содержимое. Вложения HTTP и HTTPS открываются внешне после нажатия. Обычные пути в тексте без канонических media-фактов не считаются вложениями.

ACP Chat также может показывать предпросмотр сгенерированных изображений, когда среда выполнения доставляет media генерации как доверенные структурированные данные. Доверенные OpenClaw internal-UI доставки и финальные ответы, связанные с задачей генерации, сохраняют исходный пользовательский текст завершения, включая текстовое описание ошибки, вместо замены на общий заголовок изображения. При историческом воспроизведении OpenClaw маркеры assistant MEDIA: переводятся в встроенный просмотр изображения только после зарегистрированного запуска задачи генерации в той же сессии. ClawX загружает предпросмотр через обработку media на стороне Electron Main, а не через произвольный доступ Renderer к файловой системе. Стандартные изображения и ресурсы ACP остаются предпочтительным путём и отображаются напрямую.

Семантика файловых операций ACP

• Файловые операции проецируются из успешных завершённых вызовов OpenClaw write, edit и apply_patch. Распознавание инструментов соответствует официальному OpenClaw Chat UI; фильтрация только завершённых вызовов специфична для ClawX.
• Строки созданных и изменённых файлов используют ту же оболочку карточки и меню Open with, что и предпросматриваемые вложения assistant, сохраняя статус и необязательную сводку +/-. Для HTML первый пункт меню открывает файл во вкладке Preview справа. Удалённые строки сохраняют только действие Changes. Каждый запрос списка приложений, выбора приложения и показа расположения заново проверяется Electron Main по корню рабочего пространства и относительному пути. Пути из инструментов не становятся вложениями и не раскрывают Renderer канонические системные пути.
• write отображается так, как его объявляет инструмент: как создание с разницей из всех добавленных строк, даже если путь уже может существовать.
• Changes — это хронологическая запись объявленной инструментом активности на уровне сессии. Это не вывод Git и не проверенная разница относительно исходной базы.
• Для каждого файла Changes отображает не более одного diff-редактора на ход assistant. Последовательные фрагменты объединяются, если это безопасно; независимые фрагменты объединяются в один редактор без утверждения, что это полная разница относительно базовой версии файла.
• Побочные эффекты shell-команд, скриптов, пользователей или IDE не обнаруживаются.
• Полное ACP replay может восстановить записанные файловые операции. При неполном replay ClawX не выводит пропущенную активность через fallback.

┌──────────────────────────────────────────────────────────────────┐
│                        Десктопное приложение ClawX                │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │              Главный процесс Electron                       │  │
│  │  • Управление жизненным циклом окна и приложения             │  │
│  │  • Наблюдение за процессом Gateway                           │  │
│  │  • Интеграция с системой (трей, уведомления, связка ключей)  │  │
│  │  • Оркестрация автообновлений                                │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────┬───────────────────────────────────┘
                               │
                               │ IPC (авторитетная плоскость управления)
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│              Процесс Renderer на React                            │
│  • Современный компонентный UI (React 19)                         │
│  • Управление состоянием с Zustand                                │
│  • Унифицированные вызовы host-api/api-client                     │
│  • Ответы assistant в Markdown, ввод пользователя как обычный текст│
└──────────────────────────────┬───────────────────────────────────┘
                               │
                               │ Типизированные IPC-запросы
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│                Main Host Services и Gateway Manager               │
│  • Типизированный диспетчер сервисов host:invoke                  │
│  • Настройки, файлы, сессии, навыки, провайдеры, диагностика       │
│  • WebSocket Gateway и наблюдение за процессом принадлежат Main   │
└──────────────────────────────┬───────────────────────────────────┘
                               │
                               │ WebSocket под управлением Main
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│                     OpenClaw Gateway                              │
│  • Среда выполнения и оркестрация AI-агентов                       │
│  • Управление каналами сообщений                                  │
│  • Среда выполнения навыков/плагинов                              │
│  • Уровень абстракции провайдеров                                 │
└──────────────────────────────────────────────────────────────────┘

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

• Изоляция процессов: AI-среда выполнения работает в отдельном процессе, сохраняя отзывчивость UI даже при тяжёлых вычислениях.
• Единая точка входа для фронтенда: запросы Renderer проходят через host-api / api-client, а детали протокола скрыты за стабильным интерфейсом.
• Транспорт принадлежит Main: Electron Main владеет ACP Chat stdio bridge и транспортами Gateway; Renderer общается с Main через типизированный IPC.
• Расширения через IPC: расширения Main-процесса добавляют действия host-api через типизированный IPC-реестр, а не через HTTP routes.
• Корректное восстановление: встроенные переподключение, таймауты и backoff автоматически обрабатывают временные сбои.
• Безопасное хранение: API-ключи и конфиденциальные данные используют нативные механизмы безопасного хранения ОС.
• CORS-безопасность: Renderer не вызывает напрямую локальные HTTP-эндпоинты Gateway или Host API.

Модель процессов и устранение неполадок Gateway

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