IronClaw

Ваш защищенный персональный AI-ассистент, всегда на вашей стороне

Философия • Возможности • Установка • Конфигурация • Безопасность • Архитектура

--- ## Философия 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/), чтобы увидеть последние обновления.

Установка через установщик Windows (Windows)

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

Установка через powershell-скрипт (Windows)

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

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

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

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

```sh brew install ironclaw ```

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

Для установки используйте `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`, чтобы сначала пересобрать каналы.

### Настройка базы данных ```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, но поддерживает множество LLM-провайдеров из коробки. Встроенные провайдеры включают **Anthropic**, **OpenAI**, **Google Gemini**, **MiniMax**, **Mistral** и **Ollama** (локально). Также поддерживаются OpenAI-совместимые сервисы: **OpenRouter** (300+ моделей), **Together AI**, **Fireworks AI** и собственные серверы (**vLLM**, **LiteLLM**). Выберите провайдера в мастере настройки или установите переменные окружения напрямую: ```env # Пример: MiniMax (встроенный, контекст 204K) LLM_BACKEND=minimax MINIMAX_API_KEY=... # Пример: OpenAI-совместимый эндпоинт LLM_BACKEND=openai_compatible LLM_BASE_URL=https://openrouter.ai/api/v1 LLM_API_KEY=sk-or-... LLM_MODEL=anthropic/claude-sonnet-4 ``` Смотрите [docs/capabilities/llm-providers.md](docs/capabilities/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** | Постоянная память с гибридным поиском | | **Слой безопасности** | Защита от инъекций промптов и очистка контента | ## Использование Сейчас engine v2 включается отдельно. Если вы хотите запускать новый движок вместо устаревшего цикла агента, запускайте IronClaw с `ENGINE_V2=true`. ```bash # Первоначальная настройка (БД, аутентификация и т.д.) ironclaw onboard # Запуск установленного бинарника ironclaw # Запуск установленного бинарника с engine v2 ENGINE_V2=true ironclaw # Запуск интерактивного REPL из исходников cargo run # Запуск интерактивного REPL из исходников с engine v2 ENGINE_V2=true cargo run # Engine v2 с отладочными логами ENGINE_V2=true RUST_LOG=ironclaw=debug cargo run ``` ## Разработка ```bash # Форматирование кода cargo fmt # Линтинг cargo clippy --all --benches --tests --examples --all-features # Запуск тестов createdb ironclaw_test cargo test # Запуск конкретного теста cargo test название_теста ``` - **Каналы**: Смотрите [docs/channels/overview.mdx](docs/channels/overview.mdx) для настройки Telegram, Discord и других каналов. - **Изменение исходников каналов**: Перед `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))