nearai/ironclawSistema operativo per agenti AI sicuro e privato, con archiviazione crittografata locale, autenticazione OAuth/SSO, controllo degli accessi basato su policy e un framework estensibile per la creazione di strumenti, adatto a implementazioni personali e di produzione.
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/11714/bb76296dac15b760d2c93e6ac7df91bf41355b07c7c7fdecb15799be57ccf96c.png" alt="IronClaw" width="200"/>
</p>
<h1 align="center">IronClaw</h1>
<p align="center">
<strong>Il tuo assistente AI personale sicuro, sempre al tuo fianco</strong>
</p>
<p align="center">
<a href="#license"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
<a href="https://t.me/ironclawAI"><img src="https://img.shields.io/badge/Telegram-@ironclawAI-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/ironclawAI-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/ironclawAI" /></a>
<a href="https://gitcgr.com/nearai/ironclaw">
<img src="https://gitcgr.com/badge/nearai/ironclaw.svg" alt="gitcgr" />
</a>
</p>
<p align="center">
<a href="https://github.com/nearai/ironclaw/blob/main/README.md">English</a> |
<a href="https://github.com/nearai/ironclaw/blob/main/README.zh-CN.md">简体中文</a> |
<a href="https://github.com/nearai/ironclaw/blob/main/README.ru.md">Русский</a> |
<a href="https://github.com/nearai/ironclaw/blob/main/README.ja.md">日本語</a> |
<a href="https://github.com/nearai/ironclaw/blob/main/README.ko.md">한국어</a>
</p>
<p align="center">
<a href="#ironclaw-reborn-quick-start">Reborn Quick Start</a> •
<a href="#philosophy">Philosophy</a> •
<a href="#features">Features</a> •
<a href="#installation">Installation</a> •
<a href="#configuration">Configuration</a> •
<a href="#security">Security</a> •
<a href="#architecture">Architecture</a>
</p>
---
## IronClaw Reborn Quick Start
IronClaw Reborn è il runtime standalone presente nel branch `reborn-integration`.
Utilizza il binario separato `ironclaw-reborn` del pacchetto
`ironclaw_reborn_cli` e una directory di stato Reborn separata. Non utilizza
la directory di stato legacy `ironclaw` come root di configurazione.
Per il binario più vecchio `ironclaw`, consulta [Installazione](#installation) e
[Utilizzo legacy di IronClaw](#legacy-ironclaw-usage).
### Build o esegui il binario
Dalla root del repository:```bash
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- --help
```
Oppure compilalo prima:```bash
cargo build -p ironclaw_reborn_cli --bin ironclaw-reborn
./target/debug/ironclaw-reborn --help
```
La home predefinita di Reborn è `$HOME/.ironclaw/reborn`. Sostituiscila con un percorso assoluto quando vuoi uno stato isolato:```bash
export IRONCLAW_REBORN_HOME="$PWD/.reborn-home"
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- config path
```
`config path` e `doctor` sono diagnostici sicuri; riportano la home risolta, il profilo, `config.toml`, `providers.json`, e `v1_state: not-used`.
Non creano stato Reborn o file di configurazione seed.
### Configurare la route del modello
Il modo nativo tramite CLI per configurare la route predefinita del modello di Reborn è:```bash
export IRONCLAW_REBORN_HOME="$PWD/.reborn-home"
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- models set-provider openai --model gpt-5-mini
```
Questo scrive `$IRONCLAW_REBORN_HOME/config.toml` con `[llm.default]` e il
nome della variabile d'ambiente per le credenziali del provider. Controllalo con:```bash
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- models status
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- models list openai
```
Per OpenAI, imposta il valore segreto nell'ambiente prima di iniziare:```bash
export OPENAI_API_KEY="sk-..."
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- run --message "hello"
```
Ometti `--message` o usa `repl` per una sessione interattiva su stdin:```bash
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- repl
```
### `config.toml` forma
`config init` crea file di avvio modificabili:```bash
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- config init
```
Scrive:
- `$IRONCLAW_REBORN_HOME/config.toml`
- `$IRONCLAW_REBORN_HOME/providers.json`
Un percorso modello configurato minimale assomiglia a:```toml
[llm.default]
provider_id = "openai"
model = "gpt-5-mini"
api_key_env = "OPENAI_API_KEY"
```
`config.toml` può anche includere sezioni opzionali come `[boot]`, `[identity]`, `[runner]` e `[skills]`; `config init` scrive una guida commentata per i campi supportati.
Se `config.toml` è assente, il primo avvio stateful del runtime tramite `run`, `repl` o `serve` popola un file sparso con `api_version` e il profilo di avvio sicuro `local-dev`. I comandi in sola lettura e `run --dry-run` rimangono senza effetti collaterali. Selezioni ambientali una tantum come `IRONCLAW_REBORN_PROFILE=local-dev-yolo` non vengono persistite nel file popolato.
Importante: `api_key_env` è il nome di una variabile d'ambiente, non il segreto stesso. Reborn rifiuta valori inline con forma di segreto in `config.toml` e `providers.json`.
Lo storage di produzione utilizza lo stesso pattern solo-env. Una configurazione Reborn di produzione può nominare la variabile dell'URL PostgreSQL, ma non deve contenere l'URL grezzo:```toml
[storage]
backend = "postgres"
url_env = "IRONCLAW_REBORN_POSTGRES_URL"
secret_master_key_env = "IRONCLAW_REBORN_SECRET_MASTER_KEY"
# Optional; defaults to 2. Keep below the PostgreSQL server or managed
# session-pool cap after reserving capacity for restarts and operator sessions.
pool_max_size = 2
[policy]
deployment_mode = "hosted_multi_tenant"
default_profile = "secure_default"
```
Imposta `IRONCLAW_REBORN_POSTGRES_URL` nell'ambiente di processo, e imposta `IRONCLAW_REBORN_SECRET_MASTER_KEY` come materiale crittografico chiave indipendente.
I provider PostgreSQL remoti gestiti devono utilizzare TLS, ad esempio aggiungendo `sslmode=require`.
Il `run` in produzione richiede anche una sezione `[policy]` esplicita. La prima slice di avvio in produzione supporta policy runtime che non richiedono un binding di processo tenant-sandbox.
Una volta che `[llm.default]` esiste, quella configurazione seleziona il provider. `LLM_BACKEND` è solo un fallback di ambiente quando nessuno slot LLM predefinito è configurato. Per cambiare provider dopo aver scritto la configurazione, usa `models set-provider <provider>` o modifica `[llm.default].provider_id`.
### Env-only model selection
Se `$IRONCLAW_REBORN_HOME/config.toml` è assente o non ha `[llm.default]`, Reborn può risolvere l'LLM dalle variabili d'ambiente. Una configurazione seed sparsa al primo avvio non include `[llm.default]`, quindi la selezione del modello solo tramite ambiente continua a funzionare:```bash
export IRONCLAW_REBORN_HOME="$PWD/.reborn-env-only"
export LLM_BACKEND=openai
export OPENAI_API_KEY="sk-..."
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- run --message "hello"
```
Variabili d'ambiente comuni del provider:
| Provider | Selettore | Env richiesti |
| --- | --- | --- |
| OpenAI | `LLM_BACKEND=openai` | `OPENAI_API_KEY`; opzionali `OPENAI_MODEL`, `OPENAI_BASE_URL` |
| Anthropic | `LLM_BACKEND=anthropic` | `ANTHROPIC_API_KEY`; opzionali `ANTHROPIC_MODEL`, `ANTHROPIC_BASE_URL` |
| OpenAI-compatible | `LLM_BACKEND=openai_compatible` | `LLM_BASE_URL`; opzionali `LLM_API_KEY`, `LLM_MODEL` |
| OpenRouter | `LLM_BACKEND=openrouter` | `OPENROUTER_API_KEY`; opzionale `OPENROUTER_MODEL` |
| Ollama | `LLM_BACKEND=ollama` | nessuna chiave; opzionali `OLLAMA_BASE_URL`, `OLLAMA_MODEL` |
| Codex auth | `LLM_BACKEND=openai_codex` | `LLM_USE_CODEX_AUTH=true` o `CODEX_AUTH_PATH`; opzionale `OPENAI_CODEX_MODEL` |
Usa `models list <provider>` per vedere i metadati esatti del provider compilati nel ramo corrente.
### Variabili di avvio
| Variabile | Scopo |
| --- | --- |
| `IRONCLAW_REBORN_HOME` | Root assoluto dello stato Reborn. Predefinito a `$HOME/.ironclaw/reborn`. Il risolutore rifiuta percorsi non sicuri e alias v1 del root di stato come `$HOME/.ironclaw`. |
| `IRONCLAW_REBORN_PROFILE` | Selettore del profilo di avvio. Valori supportati: `local-dev`, `local-dev-yolo`, `hosted-single-tenant`, `hosted-single-tenant-volume`, `production`, `migration-dry-run`. |
| `IRONCLAW_REBORN_POSTGRES_URL` | URL di storage PostgreSQL di produzione quando `[storage].backend = "postgres"` e `[storage].url_env` nomina questa variabile. Tienila fuori da `config.toml`; i provider remoti devono usare TLS. |
| `IRONCLAW_REBORN_POSTGRES_POOL_MAX_SIZE` | Override opzionale per la dimensione del pool client PostgreSQL di Reborn. Usalo quando un provider gestito impone un limite ridotto del pool di sessioni. |
| `IRONCLAW_FILESYSTEM_POSTGRES_MIGRATION_CONNECT_MAX_WAIT_SECS` | Finestra di attesa opzionale all'avvio per i tentativi di connessione alla migrazione del filesystem Postgres. Predefinito a 300 secondi. |
| `IRONCLAW_REBORN_SECRET_MASTER_KEY` | Chiave segreta master di produzione Reborn quando `[storage].secret_master_key_env` nomina questa variabile. Tienila indipendente dall'URL del database e fuori da `config.toml`. |
| `IRONCLAW_REBORN_LOG` | Filtro di tracing per il binario Reborn, ad esempio `debug,ironclaw_runner=trace`. |
`run` e `repl` attualmente supportano la composizione runtime locale tramite `local-dev`, `local-dev-yolo` e `hosted-single-tenant-volume`. `hosted-single-tenant-volume` utilizza il substrato libSQL del runtime locale sotto `$IRONCLAW_REBORN_HOME/hosted-single-tenant-volume`, risolve la policy runtime sicura predefinita ospitata e disabilita strumenti basati su processi come la shell. È pensato per distribuzioni di anteprima single-tenant su un volume persistente, non come composizione di produzione completa PostgreSQL.
`local-dev-yolo` concede accesso all'host del laptop fidato e deve essere confermato esplicitamente:```bash
export IRONCLAW_REBORN_PROFILE=local-dev-yolo
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- repl --confirm-host-access
```
### Servizio WebUI
Il Reborn WebUI è compilato dietro la feature Cargo `webui-v2-beta`. Le build
con questa feature richiedono Node.js 22 con Corepack/pnpm affinché Cargo possa generare
e incorporare il bundle SPA. Compila o esegui il binario con quella feature per abilitare il comando
`serve`:```bash
cargo run -q -p ironclaw_reborn_cli --features webui-v2-beta --bin ironclaw-reborn -- serve --help
cargo build -p ironclaw_reborn_cli --features webui-v2-beta --bin ironclaw-reborn
```
Il listener WebUI è impostato su `127.0.0.1:3000`. Il servizio richiede un
token env-bearer e un ID utente all'avvio. Necessita anche della rotta del modello
dalla sezione precedente, inclusa la variabile d'ambiente per le credenziali di quel provider:```bash
export IRONCLAW_REBORN_HOME="$PWD/.reborn-home"
export OPENAI_API_KEY="sk-..." # or the required env var for your configured provider
export IRONCLAW_REBORN_WEBUI_TOKEN="$(openssl rand -hex 32)"
export IRONCLAW_REBORN_WEBUI_USER_ID="reborn-cli"
cargo run -q -p ironclaw_reborn_cli --features webui-v2-beta --bin ironclaw-reborn -- serve
```
Equivalente `config.toml` configurazione listener:```toml
[webui]
listen_host = "127.0.0.1"
listen_port = 3000
env_token_var = "IRONCLAW_REBORN_WEBUI_TOKEN"
env_user_id_var = "IRONCLAW_REBORN_WEBUI_USER_ID"
allowed_origins = ["http://127.0.0.1:3000", "http://localhost:3000"]
canonical_host = "127.0.0.1:3000"
```
`env_token_var` e `env_user_id_var` sono nomi di variabili d'ambiente. Mantieni il token effettivo e l'ID utente nell'ambiente.
Variabili d'ambiente WebUI obbligatorie:
| Variabile | Scopo |
| --- | --- |
| `IRONCLAW_REBORN_WEBUI_TOKEN` | Token Bearer per le richieste WebUI. Se SSO è abilitato, firma anche le sessioni e deve essere lungo almeno 32 byte. |
| `IRONCLAW_REBORN_WEBUI_USER_ID` | ID proprietario/utente di Reborn per richieste bearer tramite ambiente. Se `[identity].default_owner` è configurato, deve corrispondere a questo valore. |
Variabili d'ambiente WebUI OAuth opzionali:
| Variabile | Scopo |
| --- | --- |
| `IRONCLAW_REBORN_WEBUI_BASE_URL` | URL di base pubblico utilizzato per il login WebUI e i callback OAuth di autenticazione del prodotto. Le distribuzioni non in loopback devono utilizzare `https://`. |
| `IRONCLAW_REBORN_WEBUI_GOOGLE_CLIENT_ID` | Abilita Google SSO quando impostato. |
| `IRONCLAW_REBORN_WEBUI_GOOGLE_CLIENT_SECRET` | Necessario quando Google SSO è abilitato. |
| `IRONCLAW_REBORN_WEBUI_GOOGLE_ALLOWED_HD` | Restrizione opzionale del dominio ospitato da Google. |
| `IRONCLAW_REBORN_WEBUI_GITHUB_CLIENT_ID` | Abilita GitHub SSO quando impostato. |
| `IRONCLAW_REBORN_WEBUI_GITHUB_CLIENT_SECRET` | Necessario quando GitHub SSO è abilitato. |
| `IRONCLAW_REBORN_WEBUI_ALLOWED_EMAIL_DOMAINS` | Necessario quando un qualsiasi provider SSO è abilitato. Domini email verificati separati da virgola. |
| `IRONCLAW_REBORN_WEBUI_OAUTH_HTTP_TIMEOUT_SECS` | Sovrascrittura opzionale del timeout HTTP OAuth. |
Per Google SSO, crea un client web OAuth di Google e registra l'URI di reindirizzamento del WebUI Reborn come:```text
{IRONCLAW_REBORN_WEBUI_BASE_URL}/auth/callback/google
```
Ad esempio, con `IRONCLAW_REBORN_WEBUI_BASE_URL=https://ironclaw.example.com`, l'URI di reindirizzamento autorizzato in Google Cloud è:```text
https://ironclaw.example.com/auth/callback/google
```
I flussi di configurazione OAuth di Notion MCP e altri product-auth utilizzano lo stesso URL base WebUI pubblico quando registrano gli URL di callback del provider. Non includere una barra finale in `IRONCLAW_REBORN_WEBUI_BASE_URL`; Reborn la rimuove prima di costruire gli URL di callback. Se l'URL base viene omesso, Reborn utilizza l'indirizzo effettivo del listener, come `http://127.0.0.1:3000`, adatto solo per test OAuth in loopback/locale. Le distribuzioni OAuth pubbliche o non in loopback devono impostare un URL base `https://`.
Ambiente di avvio completo per Google SSO:```bash
export IRONCLAW_REBORN_HOME="/var/lib/ironclaw-reborn"
export IRONCLAW_REBORN_PROFILE=local-dev
export OPENAI_API_KEY="sk-..." # or the required env var for your configured provider
export IRONCLAW_REBORN_WEBUI_TOKEN="$(openssl rand -hex 32)"
export IRONCLAW_REBORN_WEBUI_USER_ID="reborn-cli"
export IRONCLAW_REBORN_WEBUI_BASE_URL="https://ironclaw.example.com"
export IRONCLAW_REBORN_WEBUI_ALLOWED_EMAIL_DOMAINS="example.com,team.example.com"
export IRONCLAW_REBORN_WEBUI_GOOGLE_CLIENT_ID="..."
export IRONCLAW_REBORN_WEBUI_GOOGLE_CLIENT_SECRET="..."
cargo run -q -p ironclaw_reborn_cli --features webui-v2-beta --bin ironclaw-reborn -- serve --host 0.0.0.0 --port 3000
```
`IRONCLAW_REBORN_WEBUI_ALLOWED_EMAIL_DOMAINS` è la lista di permessi effettiva per l'ammissione. `hd` di Google è solo un suggerimento facoltativo del dominio ospitato dal lato del provider; non fare affidamento su di esso al posto dell'elenco dei domini consentiti di Reborn. `IRONCLAW_REBORN_HOME` seleziona la directory radice di stato/config per questo servizio. `IRONCLAW_REBORN_PROFILE` è predefinito su `local-dev`; `local-dev-yolo` concede l'accesso host da laptop fidato e non può essere servito su un host non di loopback.
Utilizza `serve --host <ip> --port <port>` per sovrascrivere il listener dalla CLI. Il binding a un host non di loopback è sensibile alla produzione. La modalità di servizio `local-dev-yolo` richiede anche `--confirm-host-access` e rifiuta host non di loopback.
### Servizio Slack
Il supporto Slack è compilato dietro la feature Cargo `slack-v2-host-beta`. Questa feature include `webui-v2-beta`, quindi Slack viene eseguito con lo stesso comando `serve`:```bash
export IRONCLAW_REBORN_HOME="$PWD/.reborn-home"
export OPENAI_API_KEY="sk-..." # or the required env var for your configured provider
export IRONCLAW_REBORN_WEBUI_TOKEN="$(openssl rand -hex 32)"
export IRONCLAW_REBORN_WEBUI_USER_ID="reborn-cli"
export IRONCLAW_REBORN_SLACK_ENABLED="true"
cargo run -q -p ironclaw_reborn_cli --features slack-v2-host-beta --bin ironclaw-reborn -- serve
```
Abilita Slack impostando `IRONCLAW_REBORN_SLACK_ENABLED=true`, oppure aggiungendo una sezione `[slack]` a `config.toml`:```toml
[slack]
enabled = true
```
La variabile d'ambiente sovrascrive solo il gate di abilitazione della route Slack: `true`/`1` monta Slack, mentre `false`/`0` agisce come un interruttore di disattivazione del deployment. Dopo l'avvio del server, configura gli ID dell'app Slack, il token del bot, il signing secret e le mappature dei canali dalla configurazione dei canali della WebUI.
Impostazioni Slack richieste:
| Nome | Scopo |
| --- | --- |
| `[slack].enabled = true` o `IRONCLAW_REBORN_SLACK_ENABLED=true` | Monta la route Slack durante `serve`. |
| Configurazione workspace Slack dalla WebUI | Archivia gli ID di installazione di Slack, le mappature dei canali e i segreti del bot/signing di Slack. |
Note più dettagliate sulla configurazione di Slack si trovano in
[`docs/reborn/setup-slack-for-reborn-binary.md`](https://github.com/nearai/ironclaw/blob/main/docs/reborn/setup-slack-for-reborn-binary.md).
## Filosofia
IronClaw è costruito su un principio semplice: **il tuo assistente AI dovrebbe lavorare per te, non contro di te**.
In un mondo in cui i sistemi AI sono sempre più opachi riguardo alla gestione dei dati e allineati con interessi aziendali, IronClaw adotta un approccio diverso:
- **I tuoi dati rimangono tuoi** - Tutte le informazioni sono archiviate localmente, crittografate e non lasciano mai il tuo controllo
- **Trasparenza per progettazione** - Open source, verificabile, nessuna telemetria nascosta o raccolta di dati
- **Capacità auto-espandibili** - Crea nuovi strumenti al volo senza attendere aggiornamenti del fornitore
- **Difesa in profondità** - Molteplici livelli di sicurezza proteggono contro l'iniezione di prompt e l'esfiltrazione di dati
IronClaw è l'assistente AI di cui puoi davvero fidarti per la tua vita personale e professionale.
## Caratteristiche
### Sicurezza Prima
- **Sandbox WASM** - Gli strumenti non fidati vengono eseguiti in contenitori WebAssembly isolati con permessi basati sulle capacità
- **Protezione delle credenziali** - I segreti non vengono mai esposti agli strumenti; iniettati al confine dell'host con rilevamento di perdite
- **Difesa dall'iniezione di prompt** - Rilevamento di pattern, sanificazione del contenuto e applicazione delle policy
- **Allowlisting degli endpoint** - Richieste HTTP solo a host e percorsi esplicitamente approvati
### Sempre disponibile
- **Multi-canale** - REPL, webhook HTTP, canali WASM (Telegram, Slack) e gateway web
- **Sandbox Docker** - Esecuzione in contenitori isolati con token per job e pattern orchestratore/lavoratore
- **Gateway Web** - Interfaccia browser con streaming in tempo reale SSE/WebSocket
- **Routine** - Pianificazioni cron, trigger di eventi, gestori di webhook per automazione in background
- **Sistema Heartbeat** - Esecuzione proattiva in background per attività di monitoraggio e manutenzione
- **Job paralleli** - Gestisci più richieste contemporaneamente con contesti isolati
- **Autoriparazione** - Rilevamento e recupero automatici di operazioni bloccate
### Auto-espansione
- **Costruzione dinamica di strumenti** - Descrivi cosa ti serve e IronClaw lo costruisce come uno strumento WASM
- **Protocollo MCP** - Connettiti ai server Model Context Protocol per capacità aggiuntive
- **Architettura a plugin** - Aggiungi nuovi strumenti e canali WASM senza riavviare
### Memoria persistente
- **Ricerca ibrida** - Ricerca full-text + vettoriale usando Reciprocal Rank Fusion
- **Filesystem dell'area di lavoro** - Archiviazione flessibile basata su percorsi per note, log e contesto
- **File di identità** - Mantieni personalità e preferenze coerenti tra le sessioni
## Installazione
### Prerequisiti
- Rust 1.96+
- PostgreSQL 15+ con estensione [pgvector](https://github.com/pgvector/pgvector)
- Node.js 22+ con Corepack/pnpm per build da sorgente che abilitano la funzionalità `webui-v2-beta`
- Account NEAR AI (autenticazione gestita tramite procedura guidata di configurazione)
- `libclang` e una toolchain C funzionante se costruisci il percorso voce/SILK di WeChat dal sorgente
## Scarica o compila
Visita la [pagina delle release](https://github.com/nearai/ironclaw/releases/) per vedere gli ultimi aggiornamenti.
<details>
<summary>Installa tramite Windows Installer (Windows)</summary>
Scarica il [Windows Installer](https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-x86_64-pc-windows-msvc.msi) ed eseguilo.
</details>
<details>
<summary>Installa tramite script powershell (Windows)</summary>```sh
irm https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.ps1 | iex
```
</details>
<details>
<summary>Installa tramite script 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>Installa tramite Homebrew (macOS/Linux)</summary>```sh
brew install ironclaw
```
</details>
<details>
<summary>Compila il codice sorgente (Cargo su Windows, Linux, macOS)</summary>
Installalo con `cargo`, assicurati solo di avere [Rust](https://rustup.rs) installato sul tuo computer.```bash
# Clone the repository
git clone https://github.com/nearai/ironclaw.git
cd ironclaw
# Build
cargo build --release
# Run tests
cargo test
```
Per la **full release** (dopo aver modificato i sorgenti dei canali), esegui `./scripts/build-all.sh` per ricostruire prima i canali.
> **Opzionale:** Le note vocali di WeChat (`audio/silk`) richiedono l'helper standalone
> `ironclaw-silk-decoder` per essere trascrivibili. È escluso dalla build
> predefinita del workspace perché `silk-codec` trascina `bindgen`/`libclang`.
> Compilalo separatamente con `./crates/ironclaw_silk_decoder/build.sh` (necessita
> di libclang + un toolchain C) e posiziona il binario risultante su `$PATH`, accanto
> al binario `ironclaw`, o puntato da `IRONCLAW_SILK_DECODER`. Senza
> di esso, i messaggi vocali vengono comunque consegnati — solo come blob `audio/silk` grezzi.
</details>
### Configurazione del Database```bash
# Create database
createdb ironclaw
# Enable pgvector
psql ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"
```
## Configurazione
Esegui il wizard di configurazione per configurare IronClaw:```bash
ironclaw onboard
```
Il wizard gestisce la connessione al database, l'autenticazione NEAR AI (tramite OAuth del browser) e la crittografia dei segreti (utilizzando il portachiavi di sistema). Le impostazioni vengono persistenziate nel database connesso; le variabili bootstrap (ad es. `DATABASE_URL`, `LLM_BACKEND`) vengono scritte in `~/.ironclaw/.env` in modo che siano disponibili prima che il database si connetta.
### Provider LLM Alternativi
IronClaw utilizza NEAR AI come predefinito ma supporta molti provider LLM pronti all'uso. I provider integrati includono **Anthropic**, **OpenAI**, **GitHub Copilot**, **Google Gemini**, **MiniMax**, **Mistral** e **Ollama** (locale). Sono supportati anche servizi compatibili con OpenAI come **OpenRouter** (300+ modelli), **Together AI**, **Fireworks AI** e server auto-ospitati (**vLLM**, **LiteLLM**).
Seleziona il tuo provider nel wizard, oppure imposta direttamente le variabili d'ambiente:```env
# Example: MiniMax (built-in, 204K context)
LLM_BACKEND=minimax
MINIMAX_API_KEY=...
# Example: OpenAI-compatible endpoint
LLM_BACKEND=openai_compatible
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_API_KEY=sk-or-...
LLM_MODEL=anthropic/claude-sonnet-4
```
Vedi [docs/capabilities/llm-providers.md](https://github.com/nearai/ironclaw/blob/main/docs/capabilities/llm-providers.md) per una guida completa ai provider.
## Sicurezza
IronClaw implementa una difesa in profondità per proteggere i tuoi dati e prevenire abusi.
### WASM Sandbox
Tutti gli strumenti non fidati vengono eseguiti in contenitori WebAssembly isolati:
- **Autorizzazioni basate su capacità** - Adesione esplicita per HTTP, segreti, invocazione di strumenti
- **Autorizzazione degli endpoint** - Richieste HTTP solo a host/path approvati
- **Iniezione di credenziali** - Segreti iniettati al confine dell'host, mai esposti al codice WASM
- **Rilevamento di perdite** - Scansiona richieste e risposte per tentativi di esfiltrazione di segreti
- **Limitazione della frequenza** - Limiti di richieste per strumento per prevenire abusi
- **Limiti di risorse** - Vincoli di memoria, CPU e tempo di esecuzione```
WASM ──► Allowlist ──► Leak Scan ──► Credential ──► Execute ──► Leak Scan ──► WASM
Validator (request) Injector Request (response)
```
### Difesa dall'Iniezione di Prompt
I contenuti esterni passano attraverso diversi livelli di sicurezza:
- Rilevamento basato su pattern dei tentativi di iniezione
- Sanitizzazione e escaping dei contenuti
- Regole di policy con livelli di gravità (Blocca/Avvisa/Rivedi/Sanitizza)
- Incapsulamento dell'output degli strumenti per un'iniezione sicura nel contesto LLM
### Protezione dei Dati
- Tutti i dati archiviati localmente nel database PostgreSQL
- Segreti crittografati con AES-256-GCM
- Nessuna telemetria, analisi o condivisione dei dati
- Registro di audit completo di tutte le esecuzioni degli strumenti
## Architettura```
┌────────────────────────────────────────────────────────────────┐
│ Channels │
│ ┌──────┐ ┌──────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ REPL │ │ HTTP │ │WASM Channels│ │ Web Gateway │ │
│ └──┬───┘ └──┬───┘ └──────┬──────┘ │ (SSE + WS) │ │
│ │ │ │ └──────┬──────┘ │
│ └─────────┴──────────────┴────────────────┘ │
│ │ │
│ ┌─────────▼─────────┐ │
│ │ Agent Loop │ Intent routing │
│ └────┬──────────┬───┘ │
│ │ │ │
│ ┌──────────▼────┐ ┌──▼───────────────┐ │
│ │ Scheduler │ │ Routines Engine │ │
│ │(parallel jobs)│ │(cron, event, wh) │ │
│ └──────┬────────┘ └────────┬─────────┘ │
│ │ │ │
│ ┌─────────────┼────────────────────┘ │
│ │ │ │
│ ┌───▼─────┐ ┌────▼────────────────┐ │
│ │ Local │ │ Orchestrator │ │
│ │Workers │ │ ┌───────────────┐ │ │
│ │(in-proc)│ │ │ Docker Sandbox│ │ │
│ └───┬─────┘ │ │ Containers │ │ │
│ │ │ │ ┌───────────┐ │ │ │
│ │ │ │ │Worker / CC│ │ │ │
│ │ │ │ └───────────┘ │ │ │
│ │ │ └───────────────┘ │ │
│ │ └─────────┬───────────┘ │
│ └──────────────────┤ │
│ │ │
│ ┌───────────▼──────────┐ │
│ │ Tool Registry │ │
│ │ Built-in, MCP, WASM │ │
│ └──────────────────────┘ │
└────────────────────────────────────────────────────────────────┘
```
### Componenti Principali
| Componente | Scopo |
|-----------|---------|
| **Agent Loop** | Gestione principale dei messaggi e coordinamento dei job |
| **Router** | Classifica l'intento dell'utente (comando, richiesta, attività) |
| **Scheduler** | Gestisce l'esecuzione parallela dei job con priorità |
| **Worker** | Esegue job con ragionamento LLM e chiamate a strumenti |
| **Orchestrator** | Ciclo di vita dei container, proxy LLM, autenticazione per job |
| **Web Gateway** | Interfaccia utente browser con chat, memoria, job, log, estensioni, routine |
| **Routines Engine** | Attività in background pianificate (cron) e reattive (evento, webhook) |
| **Workspace** | Memoria persistente con ricerca ibrida |
| **Safety Layer** | Difesa contro l'iniezione di prompt e sanificazione dei contenuti |
## Utilizzo di IronClaw```bash
# First-time setup (configures database, auth, etc.)
ironclaw onboard
# Start interactive REPL
cargo run
# REPL with debug logging
RUST_LOG=ironclaw=debug cargo run
```
## Sviluppo```bash
# Format code
cargo fmt
# Lint
cargo clippy --all --benches --tests --examples --all-features
# Run tests
createdb ironclaw_test
cargo test
# Run specific test
cargo test test_name
```
- **Canali**: Vedi [docs/channels/overview.mdx](https://github.com/nearai/ironclaw/blob/main/docs/channels/overview.mdx) per la configurazione di Telegram, Discord e altri canali.
- **Modifica delle sorgenti dei canali**: Esegui `./channels-src/telegram/build.sh` prima di `cargo build` in modo che il WASM aggiornato venga raggruppato.
## Eredità di OpenClaw
IronClaw è una reimplementazione in Rust ispirata a [OpenClaw](https://github.com/openclaw/openclaw). Vedi [FEATURE_PARITY.md](https://github.com/nearai/ironclaw/blob/main/FEATURE_PARITY.md) per la matrice di tracciamento completa.
Differenze principali:
- **Rust vs TypeScript** - Prestazioni native, sicurezza della memoria, unico binario
- **Sandbox WASM vs Docker** - Leggero, sicurezza basata su capacità
- **PostgreSQL vs SQLite** - Persistenza pronta per la produzione
- **Design incentrato sulla sicurezza** - Multipli strati di difesa, protezione delle credenziali
## Licenza
Concesso in licenza secondo una delle seguenti:
- Apache License, Versione 2.0 ([LICENSE-APACHE](https://github.com/nearai/ironclaw/blob/main/LICENSE-APACHE))
- Licenza MIT ([LICENSE-MIT](https://github.com/nearai/ironclaw/blob/main/LICENSE-MIT))
a tua scelta.