IronClaw

Il tuo assistente AI personale sicuro, sempre al tuo fianco

Reborn Quick Start • Philosophy • Features • Installation • Configuration • Security • Architecture

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 e Utilizzo legacy di IronClaw.

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.

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
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 per vedere gli ultimi aggiornamenti.

Installa tramite Windows Installer (Windows)

Scarica il Windows Installer ed eseguilo.

Installa tramite script powershell (Windows)

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

Installa tramite script shell (macOS, Linux, Windows/WSL)

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

Installa tramite Homebrew (macOS/Linux)

```sh brew install ironclaw ```

Compila il codice sorgente (Cargo su Windows, Linux, macOS)

Installalo con cargo, assicurati solo di avere Rust 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;"

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

ironclaw

Più Popolari

Configurazione

Sicurezza

WASM Sandbox

Componenti Principali

Utilizzo di IronClaw```bash

First-time setup (configures database, auth, etc.)

Start interactive REPL

REPL with debug logging

Eredità di OpenClaw

Licenza