optimclaw/README.ru.md

<p align="center">
  <img src="ironclaw.png?v=2" alt="IronClaw" width="200"/>
</p>

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

<p align="center">
  <strong>Ваш защищенный персональный AI-ассистент, всегда на вашей стороне</strong>
</p>

<p align="center">
  <a href="#license"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="Лицензия: MIT OR Apache-2.0" /></a>
  <a href="https://t.me/ironclawAI"><img src="https://img.shields.io/badge/Telegram-%40ironclawAI-26A5E4?style=flat&logo=telegram&logoColor=white" alt="Telegram: @ironclawAI" /></a>
  <a href="https://www.reddit.com/r/ironclawAI/"><img src="https://img.shields.io/badge/Reddit-r%2FironclawAI-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/ironclawAI" /></a>
</p>

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

<p align="center">
  <a href="#философия">Философия</a> •
  <a href="#возможности">Возможности</a> •
  <a href="#установка">Установка</a> •
  <a href="#конфигурация">Конфигурация</a> •
  <a href="#безопасность">Безопасность</a> •
  <a href="#архитектура">Архитектура</a>
</p>

---

## Философия

IronClaw построен на простом принципе: **ваш AI-ассистент должен работать на вас, а не против вас**.

В мире, где системы ИИ становятся все более непрозрачными в вопросах обработки данных и ориентируются на корпоративные интересы, IronClaw выбирает другой путь:

- **Ваши данные остаются вашими** — вся информация хранится локально, зашифрована и никогда не покидает ваш контроль.
- **Прозрачность по умолчанию** — открытый исходный код, возможность аудита, отсутствие скрытой телеметрии или сбора данных.
- **Саморасширяемые возможности** — создавайте новые инструменты «на лету», не дожидаясь обновлений от вендора.
- **Глубокая защита** — несколько уровней безопасности защищают от инъекций промптов и утечки данных.

IronClaw — это AI-ассистент, которому вы действительно можете доверять в личной и профессиональной жизни.

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

### Безопасность прежде всего

- **Песочница WASM** — непроверенные инструменты запускаются в изолированных контейнерах WebAssembly с правами на основе возможностей.
- **Защита учетных данных** — секреты никогда не раскрываются инструментам; они внедряются на границе хоста с детектированием утечек.
- **Защита от инъекций промптов** — обнаружение паттернов, очистка контента и применение политик безопасности.
- **Список разрешенных эндпоинтов** — HTTP-запросы только к явно одобренным хостам и путям.

### Всегда доступен

- **Многоканальность** — REPL, HTTP-вебхуки, WASM-каналы (Telegram, Slack) и веб-шлюз.
- **Песочница Docker** — изолированное выполнение контейнеров с токенами для каждого задания и паттерном «оркестратор/воркер».
- **Веб-шлюз** — браузерный интерфейс с потоковой передачей данных в реальном времени через SSE/WebSocket.
- **Рутины (Routines)** — расписания cron, триггеры событий, обработчики вебхуков для фоновой автоматизации.
- **Система Heartbeat** — проактивное фоновое выполнение задач мониторинга и обслуживания.
- **Параллельные задания** — одновременная обработка нескольких запросов с изолированными контекстами.
- **Самовосстановление** — автоматическое обнаружение и восстановление зависших операций.

### Саморасширяемый

- **Динамическое создание инструментов** — опишите, что вам нужно, и IronClaw создаст это как инструмент WASM.
- **Протокол MCP** — подключайтесь к серверам Model Context Protocol для получения дополнительных возможностей.
- **Плагинная архитектура** — добавляйте новые инструменты WASM и каналы без перезагрузки системы.

### Постоянная память

- **Гибридный поиск** — полнотекстовый + векторный поиск с использованием Reciprocal Rank Fusion.
- **Файловая система Workspace** — гибкое хранилище на основе путей для заметок, логов и контекста.
- **Файлы идентичности (Identity Files)** — сохранение индивидуальности и предпочтений между сессиями.

## Установка

### Предварительные условия

- Rust 1.85+
- PostgreSQL 15+ с расширением [pgvector](https://github.com/pgvector/pgvector)
- Аккаунт NEAR AI (аутентификация через мастер настройки)

## Загрузка и сборка

Посетите [страницу релизов](https://github.com/nearai/ironclaw/releases/), чтобы увидеть последние обновления.

<details>
  <summary>Установка через установщик Windows (Windows)</summary>

Загрузите [Windows Installer](https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-x86_64-pc-windows-msvc.msi) и запустите его.

</details>

<details>
  <summary>Установка через powershell-скрипт (Windows)</summary>

```sh
irm https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.ps1 | iex
```

</details>

<details>
  <summary>Установка через shell-скрипт (macOS, Linux, Windows/WSL)</summary>

```sh
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh
```
</details>

<details>
  <summary>Установка через Homebrew (macOS/Linux)</summary>

```sh
brew install ironclaw
```

</details>

<details>
  <summary>Компиляция из исходного кода (Cargo на Windows, Linux, macOS)</summary>

Для установки используйте `cargo`, предварительно убедившись, что у вас установлен [Rust](https://rustup.rs).

```bash
# Клонируйте репозиторий
git clone https://github.com/nearai/ironclaw.git
cd ironclaw

# Сборка
cargo build --release

# Запуск тестов
cargo test
```

Для **полного релиза** (после модификации исходников каналов) выполните `./scripts/build-all.sh`, чтобы сначала пересобрать каналы.

</details>

### Настройка базы данных

```bash
# Создание базы данных
createdb ironclaw

# Включение pgvector
psql ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"
```

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

Запустите мастер настройки для конфигурации IronClaw:

```bash
ironclaw onboard
```

Мастер настройки поможет установить соединение с базой данных, пройти аутентификацию NEAR AI (через браузер OAuth) и настроить шифрование секретов (используя системную связку ключей). Настройки сохраняются в базе данных; базовые переменные (например, `DATABASE_URL`, `LLM_BACKEND`) записываются в `~/.ironclaw/.env`, чтобы они были доступны до подключения к БД.

### Альтернативные LLM-провайдеры

IronClaw по умолчанию использует NEAR AI, но работает с любыми OpenAI-совместимыми эндпоинтами.
Популярные варианты включают **OpenRouter** (300+ моделей), **Together AI**, **Fireworks AI**, **Ollama** (локально) и собственные серверы, такие как **vLLM** или **LiteLLM**.

Выберите *"OpenAI-compatible"* в мастере настройки или установите переменные окружения напрямую:

```env
LLM_BACKEND=openai_compatible
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_API_KEY=sk-or-...
LLM_MODEL=anthropic/claude-sonnet-4
```

Смотрите [docs/LLM_PROVIDERS.md](docs/LLM_PROVIDERS.md) для получения полного руководства по провайдерам.

## Безопасность

IronClaw реализует эшелонированную защиту для обеспечения безопасности ваших данных и предотвращения злоупотреблений.

### Песочница WASM

Все непроверенные инструменты запускаются в изолированных контейнерах WebAssembly:

- **Права на основе возможностей** — явное разрешение на HTTP, доступ к секретам, вызов инструментов.
- **Список разрешенных эндпоинтов** — HTTP-запросы только к одобренным хостам/путям.
- **Внедрение учетных данных** — секреты внедряются на границе хоста и никогда не раскрываются коду WASM.
- **Детектирование утечек** — сканирование запросов и ответов на попытки кражи секретов.
- **Ограничение частоты запросов** — лимиты для каждого инструмента для предотвращения злоупотреблений.
- **Лимиты ресурсов** — ограничения по памяти, процессору и времени выполнения.

```
WASM ──► Валидатор ──► Сканер ───► Инъектор ──► Выполнение ──► Сканер ───► WASM
         хостов        утечек      секретов      запроса        утечек
                       (запрос)                                 (ответ)
```

### Защита от инъекций промптов

Внешний контент проходит через несколько уровней безопасности:

- Обнаружение попыток инъекций на основе паттернов.
- Очистка и экранирование контента.
- Правила политик с уровнями серьезности (Блокировка/Предупреждение/Проверка/Очистка).
- Обертывание вывода инструментов для безопасного внедрения в контекст LLM.

### Защита данных

- Все данные хранятся локально в вашей базе данных PostgreSQL.
- Секреты зашифрованы с использованием AES-256-GCM.
- Никакой телеметрии, аналитики или обмена данными.
- Полный журнал аудита выполнения всех инструментов.

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

```
┌────────────────────────────────────────────────────────────────┐
│                           Каналы                               │
│  ┌──────┐  ┌──────┐   ┌─────────────┐  ┌─────────────┐         │
│  │ REPL │  │ HTTP │   │WASM-каналы  │  │  Веб-шлюз   │         │
│  └──┬───┘  └──┬───┘   └──────┬──────┘  │ (SSE + WS)  │         │
│     │         │              │         └──────┬──────┘         │
│     └─────────┴──────────────┴────────────────┘                │
│                              │                                 │
│                    ┌─────────▼─────────┐                       │
│                    │    Цикл агента    │  Маршрутизация        │
│                    └────┬──────────┬───┘  намерений            │
│                         │          │                           │
│              ┌──────────▼────┐  ┌──▼───────────────┐           │
│              │ Планировщик   │  │ Движок рутин     │           │
│              │ (пар. задачи) │  │(cron, соб., wh)  │           │
│              └──────┬────────┘  └────────┬─────────┘           │
│                     │                    │                     │
│       ┌─────────────┼────────────────────┘                     │
│       │             │                                          │
│   ┌───▼─────┐  ┌────▼────────────────┐                         │
│   │ Локальн.│  │    Оркестратор      │                         │
│   │ воркеры │  │  ┌───────────────┐  │                         │
│   │(in-proc)│  │  │ Песочница     │  │                         │
│   └───┬─────┘  │  │ Docker        │  │                         │
│       │        │  │ ┌───────────┐ │  │                         │
│       │        │  │ │Воркер / CC│ │  │                         │
│       │        │  │ └───────────┘ │  │                         │
│       │        │  └───────────────┘  │                         │
│       │        └─────────┬───────────┘                         │
│       └──────────────────┤                                     │
│                          │                                     │
│              ┌───────────▼──────────┐                          │
│              │  Реестр инструментов │                          │
│              │ Встроенные, MCP, WASM│                          │
│              └──────────────────────┘                          │
└────────────────────────────────────────────────────────────────┘
```

### Основные компоненты

| Компонент | Назначение |
|-----------|------------|
| **Цикл агента** | Основная обработка сообщений и координация задач |
| **Роутер** | Классификация намерений пользователя (команда, запрос, задача) |
| **Планировщик** | Управление выполнением параллельных задач с приоритетами |
| **Воркер** | Выполнение задач с рассуждениями LLM и вызовами инструментов |
| **Оркестратор** | Жизненный цикл контейнеров, проксирование LLM, аутентификация для каждой задачи |
| **Веб-шлюз** | Браузерный интерфейс (чат, память, задачи, логи, расширения, рутины) |
| **Движок рутин** | Фоновые задачи: запланированные (cron) и реактивные (события, вебхуки) |
| **Workspace** | Постоянная память с гибридным поиском |
| **Слой безопасности** | Защита от инъекций промптов и очистка контента |

## Использование

```bash
# Первоначальная настройка (БД, аутентификация и т.д.)
ironclaw onboard

# Запуск интерактивного REPL
cargo run

# С отладочными логами
RUST_LOG=ironclaw=debug cargo run
```

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

```bash
# Форматирование кода
cargo fmt

# Линтинг
cargo clippy --all --benches --tests --examples --all-features

# Запуск тестов
createdb ironclaw_test
cargo test

# Запуск конкретного теста
cargo test название_теста
```

- **Telegram-канал**: Смотрите [docs/TELEGRAM_SETUP.md](docs/TELEGRAM_SETUP.md) для настройки и привязки аккаунта.
- **Изменение исходников каналов**: Перед `cargo build` выполните `./channels-src/telegram/build.sh`, чтобы обновить встроенный WASM.

## Наследие OpenClaw

IronClaw — это реализация на Rust, вдохновленная проектом [OpenClaw](https://github.com/openclaw/openclaw). Полную матрицу соответствия функций можно найти в [FEATURE_PARITY.md](FEATURE_PARITY.md).

Ключевые отличия:

- **Rust vs TypeScript** — нативная производительность, безопасность памяти, один бинарный файл.
- **Песочница WASM vs Docker** — легковесность, безопасность на основе возможностей.
- **PostgreSQL vs SQLite** — надежное хранилище, готовое к продакшну.
- **Безопасность прежде всего** — многослойная защита, сохранность учетных данных.

## Лицензия

Лицензировано по вашему выбору:

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT License ([LICENSE-MIT](LICENSE-MIT))