Skip to content

README.ru.md

Latest commit

 

History

History
329 lines (241 loc) · 20.4 KB

README.ru.md

File metadata and controls

329 lines (241 loc) · 20.4 KB

IronClaw

IronClaw

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

Лицензия: MIT OR Apache-2.0 Telegram: @ironclawAI Reddit: r/ironclawAI

English | 简体中文 | Русский

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

Философия

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
  • Аккаунт NEAR AI (аутентификация через мастер настройки)

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

Посетите страницу релизов, чтобы увидеть последние обновления.

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

Загрузите Windows Installer и запустите его.

Установка через powershell-скрипт (Windows) 
irm https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.ps1 | iex
Установка через shell-скрипт (macOS, Linux, Windows/WSL) 
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh
Установка через Homebrew (macOS/Linux) 
brew install ironclaw
Компиляция из исходного кода (Cargo на Windows, Linux, macOS)

Для установки используйте cargo, предварительно убедившись, что у вас установлен Rust.

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

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

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

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

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

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

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

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

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

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).

Выберите провайдера в мастере настройки или установите переменные окружения напрямую:

# Пример: 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/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 Постоянная память с гибридным поиском
Слой безопасности Защита от инъекций промптов и очистка контента

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

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

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

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

Разработка

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

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

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

# Запуск конкретного теста
cargo test название_теста
  • Telegram-канал: Смотрите docs/TELEGRAM_SETUP.md для настройки и привязки аккаунта.
  • Изменение исходников каналов: Перед cargo build выполните ./channels-src/telegram/build.sh, чтобы обновить встроенный WASM.

Наследие OpenClaw

IronClaw — это реализация на Rust, вдохновленная проектом OpenClaw. Полную матрицу соответствия функций можно найти в FEATURE_PARITY.md.

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

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

Лицензия

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