mirror of
https://github.com/outbackdingo/optimclaw.git
synced 2026-08-25 14:53:34 +00:00
Ikko Eltociear AshimineGitHubgemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>* docs: add Japanese README * Update README.ja.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * Update README.ja.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --------- Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
331 lines
20 KiB
Markdown
331 lines
20 KiB
Markdown
<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> |
|
||
<a href="README.ja.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, но поддерживает множество 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/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))
|