IronClaw

Votre assistant IA personnel sécurisé, toujours à vos côtés

Démarrage rapide Reborn • Philosophie • Fonctionnalités • Installation • Configuration • Sécurité • Architecture

Démarrage rapide d'IronClaw Reborn

IronClaw Reborn est l'environnement d'exécution autonome sur la branche reborn-integration. Il utilise le binaire séparé ironclaw-reborn du paquet ironclaw_reborn_cli et une racine d'état Reborn distincte. Il n'utilise pas le répertoire d'état ironclaw hérité comme racine de configuration.

Pour l'ancien binaire ironclaw, voir Installation et Utilisation héritée d'IronClaw.

Compiler ou exécuter le binaire

Depuis la racine du dépôt :```bash cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- --help

Ou construisez-le d'abord :```bash
cargo build -p ironclaw_reborn_cli --bin ironclaw-reborn
./target/debug/ironclaw-reborn --help

Le répertoire par défaut de Reborn est $HOME/.ironclaw/reborn. Remplacez-le par un chemin absolu lorsque vous souhaitez un état isolé :```bash export IRONCLAW_REBORN_HOME="$PWD/.reborn-home" cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- config path

`config path` et `doctor` sont des diagnostics sûrs ; ils rapportent le home résolu, le profil, `config.toml`, `providers.json`, et `v1_state: not-used`.
Ils ne créent pas d'état Reborn ni de fichiers de configuration initiaux.

### Configurer la route du modèle

La méthode CLI-native pour configurer la route de modèle par défaut de Reborn est :```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

Cela écrit $IRONCLAW_REBORN_HOME/config.toml avec [llm.default] et le nom de variable d'environnement du credential du fournisseur. Vérifiez-le avec :```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

Pour OpenAI, définissez la valeur secrète dans l'environnement avant de commencer :```bash
export OPENAI_API_KEY="sk-..."
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- run --message "hello"

Omettre --message ou utiliser repl pour une session interactive stdin:```bash cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- repl

### `config.toml` structure

`config init` crée des fichiers de démarrage modifiables :```bash
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- config init

Il écrit :

$IRONCLAW_REBORN_HOME/config.toml
$IRONCLAW_REBORN_HOME/providers.json

Un itinéraire de modèle minimal configuré ressemble à :```toml [llm.default] provider_id = "openai" model = "gpt-5-mini" api_key_env = "OPENAI_API_KEY"

`config.toml` peut également inclure des sections optionnelles telles que `[boot]`,
`[identity]`, `[runner]` et `[skills]` ; `config init` écrit des instructions
commentées pour les champs pris en charge.

Si `config.toml` est manquant, le premier démarrage d'exécution avec état via
`run`, `repl` ou `serve` génère un fichier sparse avec `api_version` et le profil
de démarrage `local-dev` sécurisé. Les commandes en lecture seule et
`run --dry-run` restent sans effet de bord. Les sélections d'environnement
ponctuelles comme `IRONCLAW_REBORN_PROFILE=local-dev-yolo` ne sont pas
persistées dans le fichier généré.

Important : `api_key_env` est le nom d'une variable d'environnement, pas le secret
lui-même. Reborn rejette les valeurs secrètes inline dans `config.toml` et
`providers.json`.

Le stockage de production utilise le même modèle exclusif aux variables d'environnement.
Une configuration Reborn de production peut nommer la variable d'URL PostgreSQL,
mais ne doit pas contenir l'URL brute :```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"

Définissez IRONCLAW_REBORN_POSTGRES_URL dans l'environnement du processus, et définissez IRONCLAW_REBORN_SECRET_MASTER_KEY avec un matériel de clé cryptographique indépendant. Les fournisseurs PostgreSQL distants gérés doivent utiliser TLS, par exemple en ajoutant sslmode=require. La production run nécessite également une section [policy] explicite. La première tranche de lancement de production prend en charge les politiques d'exécution qui ne nécessitent pas de liaison de processus tenant-sandbox.

Une fois que [llm.default] existe, cette configuration sélectionne le fournisseur. LLM_BACKEND n'est qu'un repli d'environnement lorsqu'aucun emplacement LLM par défaut n'est configuré. Pour changer de fournisseur après avoir écrit la configuration, utilisez models set-provider <provider> ou modifiez [llm.default].provider_id.

Sélection du modèle par environnement uniquement

Si $IRONCLAW_REBORN_HOME/config.toml est absent ou ne contient pas de [llm.default], Reborn peut résoudre le LLM à partir des variables d'environnement. Une configuration initiale clairsemée ne comprend pas [llm.default], donc la sélection du modèle par environnement continue de fonctionner :```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"

Variables d'environnement communes aux fournisseurs :

| Fournisseur | Sélecteur | Env requis |
| --- | --- | --- |
| OpenAI | `LLM_BACKEND=openai` | `OPENAI_API_KEY` ; optionnel `OPENAI_MODEL`, `OPENAI_BASE_URL` |
| Anthropic | `LLM_BACKEND=anthropic` | `ANTHROPIC_API_KEY` ; optionnel `ANTHROPIC_MODEL`, `ANTHROPIC_BASE_URL` |
| Compatible OpenAI | `LLM_BACKEND=openai_compatible` | `LLM_BASE_URL` ; optionnel `LLM_API_KEY`, `LLM_MODEL` |
| OpenRouter | `LLM_BACKEND=openrouter` | `OPENROUTER_API_KEY` ; optionnel `OPENROUTER_MODEL` |
| Ollama | `LLM_BACKEND=ollama` | pas de clé ; optionnel `OLLAMA_BASE_URL`, `OLLAMA_MODEL` |
| Codex auth | `LLM_BACKEND=openai_codex` | `LLM_USE_CODEX_AUTH=true` ou `CODEX_AUTH_PATH` ; optionnel `OPENAI_CODEX_MODEL` |

Utilisez `models list <provider>` pour voir les métadonnées exactes du fournisseur compilées dans la branche actuelle.

### Variables de démarrage

| Variable | Objectif |
| --- | --- |
| `IRONCLAW_REBORN_HOME` | Racine absolue de l'état Reborn. Par défaut `$HOME/.ironclaw/reborn`. Le résolveur rejette les chemins non sécurisés et les alias de racine d'état v1 tels que `$HOME/.ironclaw`. |
| `IRONCLAW_REBORN_PROFILE` | Sélecteur de profil de démarrage. Valeurs prises en charge : `local-dev`, `local-dev-yolo`, `hosted-single-tenant`, `hosted-single-tenant-volume`, `production`, `migration-dry-run`. |
| `IRONCLAW_REBORN_POSTGRES_URL` | URL de stockage PostgreSQL de production lorsque `[storage].backend = "postgres"` et `[storage].url_env` nomme cette variable. Gardez-la hors de `config.toml` ; les fournisseurs distants doivent utiliser TLS. |
| `IRONCLAW_REBORN_POSTGRES_POOL_MAX_SIZE` | Remplacement optionnel de la taille du pool de clients PostgreSQL Reborn. Utilisez-le lorsqu'un fournisseur géré impose une petite limite de pool de sessions. |
| `IRONCLAW_FILESYSTEM_POSTGRES_MIGRATION_CONNECT_MAX_WAIT_SECS` | Fenêtre d'attente optionnelle au démarrage pour les tentatives de connexion de migration de système de fichiers Postgres. Par défaut 300 secondes. |
| `IRONCLAW_REBORN_SECRET_MASTER_KEY` | Clé maître secrète Reborn de production lorsque `[storage].secret_master_key_env` nomme cette variable. Gardez-la indépendante de l'URL de la base de données et hors de `config.toml`. |
| `IRONCLAW_REBORN_LOG` | Filtre de traçage pour le binaire Reborn, par exemple `debug,ironclaw_runner=trace`. |

`run` et `repl` prennent actuellement en charge la composition d'exécution locale via `local-dev`, `local-dev-yolo` et `hosted-single-tenant-volume`.
`hosted-single-tenant-volume` utilise le substrat libSQL d'exécution locale sous `$IRONCLAW_REBORN_HOME/hosted-single-tenant-volume`, résout la politique d'exécution sécurisée par défaut hébergée et désactive les outils basés sur des processus tels que le shell.
Il est destiné aux déploiements d'aperçu monoténant sur un volume persistant, et non à la composition complète de production PostgreSQL.

`local-dev-yolo` accorde l'accès à l'hôte du portable de confiance et doit être confirmé explicitement :```bash
export IRONCLAW_REBORN_PROFILE=local-dev-yolo
cargo run -q -p ironclaw_reborn_cli --bin ironclaw-reborn -- repl --confirm-host-access

Service WebUI

Les builds avec cette Cargo feature nécessitent Node.js 22 avec Corepack/pnpm afin que Cargo puisse générer et intégrer le bundle SPA. Construisez ou exécutez le binaire avec cette feature pour activer la commande 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

L'écouteur WebUI utilise par défaut `127.0.0.1:3000`. Le service nécessite un jeton env-bearer et un identifiant utilisateur au démarrage. Il a également besoin de la route du modèle de la section précédente, y compris la variable d'environnement des informations d'identification de ce fournisseur :```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

Configuration équivalente d'écouteur config.toml :```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` et `env_user_id_var` sont des noms de variables d'environnement. Conservez le jeton et l'identifiant utilisateur réels dans l'environnement.

Variables d'environnement requises pour WebUI :

| Variable | Utilité |
| --- | --- |
| `IRONCLAW_REBORN_WEBUI_TOKEN` | Jeton Bearer pour les requêtes WebUI. Si SSO est activé, cela signe également les sessions et doit faire au moins 32 octets. |
| `IRONCLAW_REBORN_WEBUI_USER_ID` | Identifiant propriétaire/utilisateur Reborn pour les requêtes env-bearer. Si `[identity].default_owner` est configuré, il doit correspondre à cette valeur. |

Variables d'environnement OAuth WebUI optionnelles :

| Variable | Utilité |
| --- | --- |
| `IRONCLAW_REBORN_WEBUI_BASE_URL` | URL de base publique utilisée pour la connexion WebUI et les rappels OAuth product-auth. Les déploiements non-loopback doivent utiliser `https://`. |
| `IRONCLAW_REBORN_WEBUI_GOOGLE_CLIENT_ID` | Active Google SSO lorsqu'elle est définie. |
| `IRONCLAW_REBORN_WEBUI_GOOGLE_CLIENT_SECRET` | Requis lorsque Google SSO est activé. |
| `IRONCLAW_REBORN_WEBUI_GOOGLE_ALLOWED_HD` | Restriction optionnelle de domaine hébergé Google. |
| `IRONCLAW_REBORN_WEBUI_GITHUB_CLIENT_ID` | Active GitHub SSO lorsqu'elle est définie. |
| `IRONCLAW_REBORN_WEBUI_GITHUB_CLIENT_SECRET` | Requis lorsque GitHub SSO est activé. |
| `IRONCLAW_REBORN_WEBUI_ALLOWED_EMAIL_DOMAINS` | Requis lorsqu'un fournisseur SSO est activé. Domaines de messagerie vérifiés séparés par des virgules. |
| `IRONCLAW_REBORN_WEBUI_OAUTH_HTTP_TIMEOUT_SECS` | Remplacement optionnel du délai d'attente HTTP OAuth. |

Pour Google SSO, créez un client web OAuth Google et enregistrez l'URI de redirection Reborn WebUI comme suit :```text
{IRONCLAW_REBORN_WEBUI_BASE_URL}/auth/callback/google

Par exemple, avec IRONCLAW_REBORN_WEBUI_BASE_URL=https://ironclaw.example.com, l'URI de redirection autorisée dans Google Cloud est :```text https://ironclaw.example.com/auth/callback/google

Les flux de configuration OAuth de Notion MCP et d'autres authentifications de produits utilisent la même URL de base WebUI publique lors de l'enregistrement des URL de rappel du fournisseur. N'incluez pas de barre oblique finale dans `IRONCLAW_REBORN_WEBUI_BASE_URL` ; Reborn la supprime avant de construire les URL de rappel. Si l'URL de base est omise, Reborn utilise l'adresse réelle de l'écouteur, comme `http://127.0.0.1:3000`, qui est adaptée uniquement aux tests OAuth en boucle locale/locale. Les déploiements OAuth publics ou non en boucle locale doivent définir une URL de base `https://`.

Environnement de démarrage complet de 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 est la liste blanche d'admission réelle. hd de Google n'est qu'un indice facultatif du domaine hébergé côté fournisseur ; ne vous fiez pas à cela à la place de la liste des domaines autorisés de Reborn. IRONCLAW_REBORN_HOME sélectionne la racine d'état/configuration pour ce service. IRONCLAW_REBORN_PROFILE par défaut sur local-dev ; local-dev-yolo accorde l'accès à l'hôte du poste de confiance et ne peut être servi sur un hôte non-boucle locale.

Utilisez serve --host <ip> --port <port> pour remplacer l'écouteur depuis la CLI. La liaison à un hôte non-boucle locale est sensible à la production. Le mode local-dev-yolo nécessite également --confirm-host-access et refuse les hôtes non-boucle locale.

Service Slack

La prise en charge de Slack est compilée derrière la fonctionnalité Cargo slack-v2-host-beta. Cette fonctionnalité inclut webui-v2-beta, donc Slack s'exécute sur la même commande 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

Activez Slack en définissant `IRONCLAW_REBORN_SLACK_ENABLED=true`, ou en ajoutant une
section `[slack]` à `config.toml`:```toml
[slack]
enabled = true

La variable d'environnement remplace uniquement la porte d'activation de la route Slack : true/1 monte Slack, tandis que false/0 agit comme un interrupteur d'arrêt de déploiement. Après le démarrage du serveur, configurez les identifiants de l'application Slack, le token du bot, le secret de signature et les mappages de canaux depuis la configuration des canaux de l'interface Web.

Paramètres Slack requis :

Nom	Objectif
`[slack].enabled = true` ou `IRONCLAW_REBORN_SLACK_ENABLED=true`	Monte la route Slack pendant `serve`.
Configuration de l'espace de travail Slack dans l'interface Web	Stocke les identifiants d'installation Slack, les mappages de canaux et les secrets du bot Slack/de signature.

Des notes plus détaillées sur la configuration de Slack se trouvent dans docs/reborn/setup-slack-for-reborn-binary.md.

Philosophie

IronClaw est construit sur un principe simple : votre assistant IA doit travailler pour vous, pas contre vous.

Dans un monde où les systèmes d'IA sont de plus en plus opaques concernant le traitement des données et alignés sur les intérêts des entreprises, IronClaw adopte une approche différente :

Vos données restent vôtres - Toutes les informations sont stockées localement, chiffrées et ne quittent jamais votre contrôle
Transparence par conception - Open source, vérifiable, pas de télémétrie cachée ni de récolte de données
Capacités auto-expansibles - Créez de nouveaux outils à la volée sans attendre les mises à jour du fournisseur
Défense en profondeur - Plusieurs couches de sécurité protègent contre l'injection d'invites et l'exfiltration de données

IronClaw est l'assistant IA auquel vous pouvez vraiment faire confiance pour votre vie personnelle et professionnelle.

Fonctionnalités

Sécurité avant tout

Bac à sable WASM - Les outils non fiables s'exécutent dans des conteneurs WebAssembly isolés avec des permissions basées sur les capacités
Protection des identifiants - Les secrets ne sont jamais exposés aux outils ; injectés à la limite de l'hôte avec détection de fuite
Défense contre l'injection d'invites - Détection de motifs, assainissement du contenu et application des règles
Liste blanche des points de terminaison - Requêtes HTTP uniquement vers des hôtes et chemins explicitement approuvés

Toujours disponible

Multi-canal - REPL, webhooks HTTP, canaux WASM (Telegram, Slack) et passerelle web
Bac à sable Docker - Exécution isolée dans des conteneurs avec jetons par tâche et modèle orchestrateur/travailleur
Passerelle Web - Interface utilisateur dans le navigateur avec streaming en temps réel SSE/WebSocket
Routines - Planifications Cron, déclencheurs d'événements, gestionnaires de webhooks pour l'automatisation en arrière-plan
Système de battement - Exécution proactive en arrière-plan pour les tâches de surveillance et de maintenance
Tâches parallèles - Gérer plusieurs requêtes simultanément avec des contextes isolés
Auto-réparation - Détection automatique et récupération des opérations bloquées

Auto-expansion

Construction dynamique d'outils - Décrivez ce dont vous avez besoin, et IronClaw le construit comme un outil WASM
Protocole MCP - Connectez-vous aux serveurs du protocole de contexte de modèle pour des capacités supplémentaires
Architecture de plugins - Ajoutez de nouveaux outils et canaux WASM sans redémarrer

Mémoire persistante

Recherche hybride - Recherche plein texte + vectorielle en utilisant la fusion de classement réciproque
Système de fichiers de l'espace de travail - Stockage flexible basé sur les chemins pour les notes, les journaux et le contexte
Fichiers d'identité - Maintenir une personnalité et des préférences cohérentes entre les sessions

Installation

Prérequis

Rust 1.96+
PostgreSQL 15+ avec l'extension pgvector
Node.js 22+ avec Corepack/pnpm pour les builds source qui activent la fonctionnalité webui-v2-beta
Compte NEAR AI (authentification gérée par l'assistant de configuration)
libclang et une chaîne d'outils C fonctionnelle si vous construisez le chemin vocal/SILK WeChat à partir des sources

Télécharger ou compiler

Visitez la page des versions pour voir les dernières mises à jour.

Installation via l'installateur Windows (Windows)

Téléchargez l'installateur Windows et exécutez-le.

Installation via script powershell (Windows)

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

Installer via 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 ```

Installer via Homebrew (macOS/Linux)

```sh brew install ironclaw ```

Compilez le code source (Cargo sur Windows, Linux, macOS)

Installez-le avec cargo, assurez-vous simplement d'avoir Rust installé sur votre ordinateur.```bash

Clone the repository

git clone https://github.com/nearai/ironclaw.git cd ironclaw

Build

cargo build --release

Run tests

cargo test

Pour une **version complète** (après modification des sources des canaux), exécutez `./scripts/build-all.sh` pour reconstruire les canaux d'abord.

> **Optionnel :** Les notes vocales WeChat (`audio/silk`) nécessitent l'assistant
> autonome `ironclaw-silk-decoder` pour être transcrites. Il est exclu de la
> construction par défaut de l'espace de travail car `silk-codec` entraîne
> `bindgen`/`libclang`.
> Construisez-le séparément avec `./crates/ironclaw_silk_decoder/build.sh` (nécessite
> libclang + une chaîne d'outils C) et placez le binaire résultant dans `$PATH`, à côté
> du binaire `ironclaw`, ou pointé par `IRONCLAW_SILK_DECODER`. Sans
> cela, les messages vocaux sont toujours livrés — mais sous forme de blobs `audio/silk` bruts.

</details>

### Configuration de la base de données```bash
# Create database
createdb ironclaw

# Enable pgvector
psql ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"

Composant	Objectif
Agent Loop	Gestion principale des messages et coordination des tâches
Router	Classifie l'intention de l'utilisateur (commande, requête, tâche)
Scheduler	Gère l'exécution parallèle des tâches avec priorités
Worker	Exécute les tâches avec raisonnement LLM et appels d'outils
Orchestrator	Cycle de vie des conteneurs, proxy LLM, authentification par tâche
Web Gateway	Interface navigateur avec chat, mémoire, tâches, journaux, extensions, routines
Routines Engine	Tâches planifiées (cron) et réactives (événement, webhook) en arrière-plan
Workspace	Mémoire persistante avec recherche hybride
Safety Layer	Défense contre l'injection de prompts et assainissement du contenu

ironclaw

Populaires

Configuration

Sécurité

Sandbox WASM

Composants principaux

Utilisation d'IronClaw```bash

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

Start interactive REPL

REPL with debug logging

Héritage OpenClaw

Licence