zeroclaw 0.1.7 - Docs.rs

<p align="center">
  <img src="zeroclaw.png" alt="ZeroClaw" width="200" />
</p>

<h1 align="center">ZeroClaw 🦀</h1>

<p align="center">
  <strong>Zéro surcharge. Zéro compromis. 100% Rust. 100% Agnostique.</strong><br>
  ⚡️ <strong>Fonctionne sur du matériel à 10$ avec <5 Mo de RAM : C'est 99% de mémoire en moins qu'OpenClaw et 98% moins cher qu'un Mac mini !</strong>
</p>

<p align="center">
  <a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="Licence : MIT ou Apache-2.0" /></a>
  <a href="NOTICE"><img src="https://img.shields.io/badge/contributors-27+-green.svg" alt="Contributeurs" /></a>
  <a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Offrez-moi un café" /></a>
  <a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X : @zeroclawlabs" /></a>
  <a href="https://zeroclawlabs.cn/group.jpg"><img src="https://img.shields.io/badge/WeChat-Group-B7D7A8?logo=wechat&logoColor=white" alt="WeChat Group" /></a>
  <a href="https://www.xiaohongshu.com/user/profile/67cbfc43000000000d008307?xsec_token=AB73VnYnGNx5y36EtnnZfGmAmS-6Wzv8WMuGpfwfkg6Yc%3D&xsec_source=pc_search"><img src="https://img.shields.io/badge/Xiaohongshu-Official-FF2442?style=flat" alt="Xiaohongshu : Officiel" /></a>
  <a href="https://t.me/zeroclawlabs"><img src="https://img.shields.io/badge/Telegram-%40zeroclawlabs-26A5E4?style=flat&logo=telegram&logoColor=white" alt="Telegram : @zeroclawlabs" /></a>
  <a href="https://www.facebook.com/groups/zeroclaw"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
  <a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit : r/zeroclawlabs" /></a>
</p>
<p align="center">
Construit par des étudiants et membres des communautés Harvard, MIT et Sundai.Club.
</p>

<p align="center">
  🌐 <strong>Langues :</strong> <a href="README.md">English</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ru.md">Русский</a> · <a href="README.fr.md">Français</a> · <a href="README.vi.md">Tiếng Việt</a>
</p>

<p align="center">
  <a href="#démarrage-rapide">Démarrage</a> |
  <a href="bootstrap.sh">Configuration en un clic</a> |
  <a href="docs/README.md">Hub Documentation</a> |
  <a href="docs/SUMMARY.md">Table des matières Documentation</a>
</p>

<p align="center">
  <strong>Accès rapides :</strong>
  <a href="docs/reference/README.md">Référence</a> ·
  <a href="docs/operations/README.md">Opérations</a> ·
  <a href="docs/troubleshooting.md">Dépannage</a> ·
  <a href="docs/security/README.md">Sécurité</a> ·
  <a href="docs/hardware/README.md">Matériel</a> ·
  <a href="docs/contributing/README.md">Contribuer</a>
</p>

<p align="center">
  <strong>Infrastructure d'assistant IA rapide, légère et entièrement autonome</strong><br />
  Déployez n'importe où. Échangez n'importe quoi.
</p>

<p align="center">
  ZeroClaw est le <strong>système d'exploitation runtime</strong> pour les workflows agentiques — une infrastructure qui abstrait les modèles, outils, mémoire et exécution pour construire des agents une fois et les exécuter partout.
</p>

<p align="center"><code>Architecture pilotée par traits · runtime sécurisé par défaut · fournisseur/canal/outil interchangeables · tout est pluggable</code></p>

### 📢 Annonces

Utilisez ce tableau pour les avis importants (changements incompatibles, avis de sécurité, fenêtres de maintenance et bloqueurs de version).

| Date (UTC) | Niveau      | Avis                                                                                                                                                                                                                                                                                                                                                                                                              | Action                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ---------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2026-02-19 | _Critique_  | Nous ne sommes **pas affiliés** à `openagen/zeroclaw` ou `zeroclaw.org`. Le domaine `zeroclaw.org` pointe actuellement vers le fork `openagen/zeroclaw`, et ce domaine/dépôt usurpe l'identité de notre site web/projet officiel.                                                                                                                                                                                 | Ne faites pas confiance aux informations, binaires, levées de fonds ou annonces provenant de ces sources. Utilisez uniquement [ce dépôt](https://github.com/zeroclaw-labs/zeroclaw) et nos comptes sociaux vérifiés.                                                                                                                                                                                                                                                                                                                                                          |
| 2026-02-21 | _Important_ | Notre site officiel est désormais en ligne : [zeroclawlabs.ai](https://zeroclawlabs.ai). Merci pour votre patience pendant cette attente. Nous constatons toujours des tentatives d'usurpation : ne participez à aucune activité d'investissement/financement au nom de ZeroClaw si elle n'est pas publiée via nos canaux officiels.                                                                                                                   | Utilisez [ce dépôt](https://github.com/zeroclaw-labs/zeroclaw) comme source unique de vérité. Suivez [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Telegram (@zeroclawlabs)](https://t.me/zeroclawlabs), [Facebook (groupe)](https://www.facebook.com/groups/zeroclaw), [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/), et [Xiaohongshu](https://www.xiaohongshu.com/user/profile/67cbfc43000000000d008307?xsec_token=AB73VnYnGNx5y36EtnnZfGmAmS-6Wzv8WMuGpfwfkg6Yc%3D&xsec_source=pc_search) pour les mises à jour officielles. |
| 2026-02-19 | _Important_ | Anthropic a mis à jour les conditions d'utilisation de l'authentification et des identifiants le 2026-02-19. L'authentification OAuth (Free, Pro, Max) est exclusivement destinée à Claude Code et Claude.ai ; l'utilisation de tokens OAuth de Claude Free/Pro/Max dans tout autre produit, outil ou service (y compris Agent SDK) n'est pas autorisée et peut violer les Conditions d'utilisation grand public. | Veuillez temporairement éviter les intégrations OAuth de Claude Code pour prévenir toute perte potentielle. Clause originale : [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use).                                                                                                                                                                                                                                                                                                                      |

### ✨ Fonctionnalités

- 🏎️ **Runtime Léger par Défaut :** Les workflows CLI courants et de statut s'exécutent dans une enveloppe mémoire de quelques mégaoctets sur les builds de production.
- 💰 **Déploiement Économique :** Conçu pour les cartes à faible coût et les petites instances cloud sans dépendances runtime lourdes.
- ⚡ **Démarrages à Froid Rapides :** Le runtime Rust mono-binaire maintient le démarrage des commandes et démons quasi instantané pour les opérations quotidiennes.
- 🌍 **Architecture Portable :** Un workflow binaire unique sur ARM, x86 et RISC-V avec fournisseurs/canaux/outils interchangeables.

### Pourquoi les équipes choisissent ZeroClaw

- **Léger par défaut :** petit binaire Rust, démarrage rapide, empreinte mémoire faible.
- **Sécurisé par conception :** appairage, sandboxing strict, listes d'autorisation explicites, portée de workspace.
- **Entièrement interchangeable :** les systèmes centraux sont des traits (fournisseurs, canaux, outils, mémoire, tunnels).
- **Aucun verrouillage :** support de fournisseur compatible OpenAI + endpoints personnalisés pluggables.

## Instantané de Benchmark (ZeroClaw vs OpenClaw, Reproductible)

Benchmark rapide sur machine locale (macOS arm64, fév. 2026) normalisé pour matériel edge 0.8 GHz.

|                              | OpenClaw      | NanoBot        | PicoClaw        | ZeroClaw 🦀           |
| ---------------------------- | ------------- | -------------- | --------------- | --------------------- |
| **Langage**                  | TypeScript    | Python         | Go              | **Rust**              |
| **RAM**                      | > 1 Go        | > 100 Mo       | < 10 Mo         | **< 5 Mo**            |
| **Démarrage (cœur 0.8 GHz)** | > 500s        | > 30s          | < 1s            | **< 10ms**            |
| **Taille Binaire**           | ~28 Mo (dist) | N/A (Scripts)  | ~8 Mo           | **3.4 Mo**            |
| **Coût**                     | Mac Mini 599$ | Linux SBC ~50$ | Carte Linux 10$ | **Tout matériel 10$** |

> Notes : Les résultats ZeroClaw sont mesurés sur des builds de production utilisant `/usr/bin/time -l`. OpenClaw nécessite le runtime Node.js (typiquement ~390 Mo de surcharge mémoire supplémentaire), tandis que NanoBot nécessite le runtime Python. PicoClaw et ZeroClaw sont des binaires statiques. Les chiffres RAM ci-dessus sont la mémoire runtime ; les exigences de compilation build-time sont plus élevées.

<p align="center">
  <img src="zero-claw.jpeg" alt="Comparaison ZeroClaw vs OpenClaw" width="800" />
</p>

### Mesure locale reproductible

Les affirmations de benchmark peuvent dériver au fil de l'évolution du code et des toolchains, donc mesurez toujours votre build actuel localement :

```bash
cargo build --release
ls -lh target/release/zeroclaw

/usr/bin/time -l target/release/zeroclaw --help
/usr/bin/time -l target/release/zeroclaw status
```

Exemple d'échantillon (macOS arm64, mesuré le 18 février 2026) :

- Taille binaire release : `8.8M`
- `zeroclaw --help` : environ `0.02s` de temps réel, ~`3.9 Mo` d'empreinte mémoire maximale
- `zeroclaw status` : environ `0.01s` de temps réel, ~`4.1 Mo` d'empreinte mémoire maximale

## Prérequis

<details>
<summary><strong>Windows</strong></summary>

### Windows — Requis

1. **Visual Studio Build Tools** (fournit le linker MSVC et le Windows SDK) :

    ```powershell
    winget install Microsoft.VisualStudio.2022.BuildTools
    ```

    Pendant l'installation (ou via le Visual Studio Installer), sélectionnez la charge de travail **"Développement Desktop en C++"**.

2. **Toolchain Rust :**

    ```powershell
    winget install Rustlang.Rustup
    ```

    Après l'installation, ouvrez un nouveau terminal et exécutez `rustup default stable` pour vous assurer que la toolchain stable est active.

3. **Vérifiez** que les deux fonctionnent :
    ```powershell
    rustc --version
    cargo --version
    ```

### Windows — Optionnel

- **Docker Desktop** — requis seulement si vous utilisez le [runtime sandboxé Docker](#support-runtime-actuel) (`runtime.kind = "docker"`). Installez via `winget install Docker.DockerDesktop`.

</details>

<details>
<summary><strong>Linux / macOS</strong></summary>

### Linux / macOS — Requis

1. **Outils de build essentiels :**
    - **Linux (Debian/Ubuntu) :** `sudo apt install build-essential pkg-config`
    - **Linux (Fedora/RHEL) :** `sudo dnf group install development-tools && sudo dnf install pkg-config`
    - **macOS :** Installez les Outils de Ligne de Commande Xcode : `xcode-select --install`

2. **Toolchain Rust :**

    ```bash
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    ```

    Voir [rustup.rs](https://rustup.rs) pour les détails.

3. **Vérifiez :**
    ```bash
    rustc --version
    cargo --version
    ```

### Linux / macOS — Optionnel

- **Docker** — requis seulement si vous utilisez le [runtime sandboxé Docker](#support-runtime-actuel) (`runtime.kind = "docker"`).
    - **Linux (Debian/Ubuntu) :** voir [docs.docker.com](https://docs.docker.com/engine/install/ubuntu/)
    - **Linux (Fedora/RHEL) :** voir [docs.docker.com](https://docs.docker.com/engine/install/fedora/)
    - **macOS :** installez Docker Desktop via [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop/)

</details>

## Démarrage Rapide

### Option 1 : Configuration automatisée (recommandée)

Le script `bootstrap.sh` installe Rust, clone ZeroClaw, le compile, et configure votre environnement de développement initial :

```bash
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/bootstrap.sh | bash
```

Ceci va :

1. Installer Rust (si absent)
2. Cloner le dépôt ZeroClaw
3. Compiler ZeroClaw en mode release
4. Installer `zeroclaw` dans `~/.cargo/bin/`
5. Créer la structure de workspace par défaut dans `~/.zeroclaw/workspace/`
6. Générer un fichier de configuration `~/.zeroclaw/workspace/config.toml` de démarrage

Après le bootstrap, relancez votre shell ou exécutez `source ~/.cargo/env` pour utiliser la commande `zeroclaw` globalement.

### Option 2 : Installation manuelle

<details>
<summary><strong>Cliquez pour voir les étapes d'installation manuelle</strong></summary>

```bash
# 1. Clonez le dépôt
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw

# 2. Compilez en release
cargo build --release --locked

# 3. Installez le binaire
cargo install --path . --locked

# 4. Initialisez le workspace
zeroclaw init

# 5. Vérifiez l'installation
zeroclaw --version
zeroclaw status
```

</details>

### Après l'installation

Une fois installé (via bootstrap ou manuellement), vous devriez voir :

```
~/.zeroclaw/workspace/
├── config.toml          # Configuration principale
├── .pairing             # Secrets de pairing (généré au premier lancement)
├── logs/                # Journaux de daemon/agent
├── skills/              # Compétences personnalisées
└── memory/              # Stockage de contexte conversationnel
```

**Prochaines étapes :**

1. Configurez vos fournisseurs d'IA dans `~/.zeroclaw/workspace/config.toml`
2. Consultez la [référence de configuration](docs/config-reference.md) pour les options avancées
3. Lancez l'agent : `zeroclaw agent start`
4. Testez via votre canal préféré (voir [référence des canaux](docs/channels-reference.md))

## Configuration

Éditez `~/.zeroclaw/workspace/config.toml` pour configurer les fournisseurs, canaux et comportement du système.

### Référence de Configuration Rapide

```toml
[providers.anthropic]
api_key = "sk-ant-..."
model = "claude-sonnet-4-20250514"

[providers.openai]
api_key = "sk-..."
model = "gpt-4o"

[channels.telegram]
enabled = true
bot_token = "123456:ABC-DEF..."

[channels.matrix]
enabled = true
homeserver_url = "https://matrix.org"
username = "@bot:matrix.org"
password = "..."

[memory]
kind = "markdown"  # ou "sqlite" ou "none"

[runtime]
kind = "native"    # ou "docker" (nécessite Docker)
```

**Documents de référence complets :**

- [Référence de Configuration](docs/config-reference.md) — tous les paramètres, validations, valeurs par défaut
- [Référence des Fournisseurs](docs/providers-reference.md) — configurations spécifiques aux fournisseurs d'IA
- [Référence des Canaux](docs/channels-reference.md) — Telegram, Matrix, Slack, Discord et plus
- [Opérations](docs/operations-runbook.md) — surveillance en production, rotation des secrets, mise à l'échelle

### Support Runtime (actuel)

ZeroClaw prend en charge deux backends d'exécution de code :

- **`native`** (par défaut) — exécution de processus directe, chemin le plus rapide, idéal pour les environnements de confiance
- **`docker`** — isolation complète du conteneur, politiques de sécurité renforcées, nécessite Docker

Utilisez `runtime.kind = "docker"` si vous avez besoin d'un sandboxing strict ou de l'isolation réseau. Voir [référence de configuration](docs/config-reference.md#runtime) pour les détails complets.

## Commandes

```bash
# Gestion du workspace
zeroclaw init                # Initialise un nouveau workspace
zeroclaw status              # Affiche l'état du daemon/agent
zeroclaw config validate     # Vérifie la syntaxe et les valeurs de config.toml

# Gestion du daemon
zeroclaw daemon start        # Démarre le daemon en arrière-plan
zeroclaw daemon stop         # Arrête le daemon en cours d'exécution
zeroclaw daemon restart      # Redémarre le daemon (rechargement de config)
zeroclaw daemon logs         # Affiche les journaux du daemon

# Gestion de l'agent
zeroclaw agent start         # Démarre l'agent (nécessite daemon en cours d'exécution)
zeroclaw agent stop          # Arrête l'agent
zeroclaw agent restart       # Redémarre l'agent (rechargement de config)

# Opérations de pairing
zeroclaw pairing init        # Génère un nouveau secret de pairing
zeroclaw pairing rotate      # Fait tourner le secret de pairing existant

# Tunneling (pour exposition publique)
zeroclaw tunnel start        # Démarre un tunnel vers le daemon local
zeroclaw tunnel stop         # Arrête le tunnel actif

# Diagnostic
zeroclaw doctor              # Exécute les vérifications de santé du système
zeroclaw version             # Affiche la version et les informations de build
```

Voir [Référence des Commandes](docs/commands-reference.md) pour les options et exemples complets.

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        Canaux (trait)                           │
│  Telegram │ Matrix │ Slack │ Discord │ Web │ CLI │ Custom       │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Orchestrateur Agent                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │   Routage    │  │   Contexte   │  │  Exécution   │          │
│  │   Message    │  │   Mémoire    │  │    Outil     │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────┬───────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ Fournisseurs │  │   Mémoire    │  │    Outils    │
│   (trait)    │  │   (trait)    │  │   (trait)    │
├──────────────┤  ├──────────────┤  ├──────────────┤
│  Anthropic   │  │   Markdown   │  │  Filesystem  │
│   OpenAI     │  │    SQLite    │  │     Bash     │
│   Gemini     │  │     None     │  │   Web Fetch  │
│   Ollama     │  │    Custom    │  │   Custom     │
│   Custom     │  └──────────────┘  └──────────────┘
└──────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Runtime (trait)                                │
│                  Native │ Docker                                 │
└─────────────────────────────────────────────────────────────────┘
```

**Principes clés :**

- Tout est un **trait** — fournisseurs, canaux, outils, mémoire, tunnels
- Les canaux appellent l'orchestrateur ; l'orchestrateur appelle les fournisseurs + outils
- Le système mémoire gère le contexte conversationnel (markdown, SQLite, ou aucun)
- Le runtime abstrait l'exécution de code (natif ou Docker)
- Aucun verrouillage de fournisseur — échangez Anthropic ↔ OpenAI ↔ Gemini ↔ Ollama sans changement de code

Voir [documentation architecture](docs/architecture.svg) pour les diagrammes détaillés et les détails d'implémentation.

## Exemples

### Telegram Bot

```toml
[channels.telegram]
enabled = true
bot_token = "123456:ABC-DEF..."
allowed_users = [987654321]  # Votre Telegram user ID
```

Démarrez le daemon + agent, puis envoyez un message à votre bot sur Telegram :

```
/start
Bonjour ! Pouvez-vous m'aider à écrire un script Python ?
```

Le bot répond avec le code généré par l'IA, exécute les outils si demandé, et conserve le contexte de conversation.

### Matrix (chiffré de bout en bout)

```toml
[channels.matrix]
enabled = true
homeserver_url = "https://matrix.org"
username = "@zeroclaw:matrix.org"
password = "..."
device_name = "zeroclaw-prod"
e2ee_enabled = true
```

Invitez `@zeroclaw:matrix.org` dans une salle chiffrée, et le bot répondra avec le chiffrement complet. Voir [Guide Matrix E2EE](docs/matrix-e2ee-guide.md) pour la configuration de vérification de dispositif.

### Multi-Fournisseur

```toml
[providers.anthropic]
enabled = true
api_key = "sk-ant-..."
model = "claude-sonnet-4-20250514"

[providers.openai]
enabled = true
api_key = "sk-..."
model = "gpt-4o"

[orchestrator]
default_provider = "anthropic"
fallback_providers = ["openai"]  # Bascule en cas d'erreur du fournisseur
```

Si Anthropic échoue ou rate-limit, l'orchestrateur bascule automatiquement vers OpenAI.

### Mémoire Personnalisée

```toml
[memory]
kind = "sqlite"
path = "~/.zeroclaw/workspace/memory/conversations.db"
retention_days = 90  # Purge automatique après 90 jours
```

Ou utilisez Markdown pour un stockage lisible par l'humain :

```toml
[memory]
kind = "markdown"
path = "~/.zeroclaw/workspace/memory/"
```

Voir [Référence de Configuration](docs/config-reference.md#memory) pour toutes les options mémoire.

## Support de Fournisseur

| Fournisseur       | Statut      | Clé API             | Modèles Exemple                                      |
| ----------------- | ----------- | ------------------- | ---------------------------------------------------- |
| **Anthropic**     | ✅ Stable   | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514`, `claude-opus-4-20250514` |
| **OpenAI**        | ✅ Stable   | `OPENAI_API_KEY`    | `gpt-4o`, `gpt-4o-mini`, `o1`, `o1-mini`             |
| **Google Gemini** | ✅ Stable   | `GOOGLE_API_KEY`    | `gemini-2.0-flash-exp`, `gemini-exp-1206`            |
| **Ollama**        | ✅ Stable   | N/A (local)         | `llama3.3`, `qwen2.5`, `phi4`                        |
| **Cerebras**      | ✅ Stable   | `CEREBRAS_API_KEY`  | `llama-3.3-70b`                                      |
| **Groq**          | ✅ Stable   | `GROQ_API_KEY`      | `llama-3.3-70b-versatile`                            |
| **Mistral**       | 🚧 Planifié | `MISTRAL_API_KEY`   | TBD                                                  |
| **Cohere**        | 🚧 Planifié | `COHERE_API_KEY`    | TBD                                                  |

### Endpoints Personnalisés

ZeroClaw prend en charge les endpoints compatibles OpenAI :

```toml
[providers.custom]
enabled = true
api_key = "..."
base_url = "https://api.your-llm-provider.com/v1"
model = "your-model-name"
```

Exemple : utilisez [LiteLLM](https://github.com/BerriAI/litellm) comme proxy pour accéder à n'importe quel LLM via l'interface OpenAI.

Voir [Référence des Fournisseurs](docs/providers-reference.md) pour les détails de configuration complets.

## Support de Canal

| Canal        | Statut      | Authentification         | Notes                                                     |
| ------------ | ----------- | ------------------------ | --------------------------------------------------------- |
| **Telegram** | ✅ Stable   | Bot Token                | Support complet incluant fichiers, images, boutons inline |
| **Matrix**   | ✅ Stable   | Mot de passe ou Token    | Support E2EE avec vérification de dispositif              |
| **Slack**    | 🚧 Planifié | OAuth ou Bot Token       | Accès workspace requis                                    |
| **Discord**  | 🚧 Planifié | Bot Token                | Permissions guild requises                                |
| **WhatsApp** | 🚧 Planifié | Twilio ou API officielle | Compte business requis                                    |
| **CLI**      | ✅ Stable   | Aucun                    | Interface conversationnelle directe                       |
| **Web**      | 🚧 Planifié | Clé API ou OAuth         | Interface de chat basée navigateur                        |

Voir [Référence des Canaux](docs/channels-reference.md) pour les instructions de configuration complètes.

## Support d'Outil

ZeroClaw fournit des outils intégrés pour l'exécution de code, l'accès au système de fichiers et la récupération web :

| Outil                | Description                 | Runtime Requis                |
| -------------------- | --------------------------- | ----------------------------- |
| **bash**             | Exécute des commandes shell | Native ou Docker              |
| **python**           | Exécute des scripts Python  | Python 3.8+ (natif) ou Docker |
| **javascript**       | Exécute du code Node.js     | Node.js 18+ (natif) ou Docker |
| **filesystem_read**  | Lit des fichiers            | Native ou Docker              |
| **filesystem_write** | Écrit des fichiers          | Native ou Docker              |
| **web_fetch**        | Récupère du contenu web     | Native ou Docker              |

### Sécurité de l'Exécution

- **Runtime Natif** — s'exécute en tant que processus utilisateur du daemon, accès complet au système de fichiers
- **Runtime Docker** — isolation complète du conteneur, systèmes de fichiers et réseaux séparés

Configurez la politique d'exécution dans `config.toml` :

```toml
[runtime]
kind = "docker"
allowed_tools = ["bash", "python", "filesystem_read"]  # Liste d'autorisation explicite
```

Voir [Référence de Configuration](docs/config-reference.md#runtime) pour les options de sécurité complètes.

## Déploiement

### Déploiement Local (Développement)

```bash
zeroclaw daemon start
zeroclaw agent start
```

### Déploiement Serveur (Production)

Utilisez systemd pour gérer le daemon et l'agent en tant que services :

```bash
# Installez le binaire
cargo install --path . --locked

# Configurez le workspace
zeroclaw init

# Créez les fichiers de service systemd
sudo cp deployment/systemd/zeroclaw-daemon.service /etc/systemd/system/
sudo cp deployment/systemd/zeroclaw-agent.service /etc/systemd/system/

# Activez et démarrez les services
sudo systemctl enable zeroclaw-daemon zeroclaw-agent
sudo systemctl start zeroclaw-daemon zeroclaw-agent

# Vérifiez le statut
sudo systemctl status zeroclaw-daemon
sudo systemctl status zeroclaw-agent
```

Voir [Guide de Déploiement Réseau](docs/network-deployment.md) pour les instructions de déploiement en production complètes.

### Docker

```bash
# Compilez l'image
docker build -t zeroclaw:latest .

# Exécutez le conteneur
docker run -d \
  --name zeroclaw \
  -v ~/.zeroclaw/workspace:/workspace \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  zeroclaw:latest
```

Voir [`Dockerfile`](Dockerfile) pour les détails de construction et les options de configuration.

### Matériel Edge

ZeroClaw est conçu pour fonctionner sur du matériel à faible consommation d'énergie :

- **Raspberry Pi Zero 2 W** — ~512 Mo RAM, cœur ARMv8 simple, <5$ coût matériel
- **Raspberry Pi 4/5** — 1 Go+ RAM, multi-cœur, idéal pour les charges de travail concurrentes
- **Orange Pi Zero 2** — ~512 Mo RAM, quad-core ARMv8, coût ultra-faible
- **SBCs x86 (Intel N100)** — 4-8 Go RAM, builds rapides, support Docker natif

Voir [Guide du Matériel](docs/hardware/README.md) pour les instructions de configuration spécifiques aux dispositifs.

## Tunneling (Exposition Publique)

Exposez votre daemon ZeroClaw local au réseau public via des tunnels sécurisés :

```bash
zeroclaw tunnel start --provider cloudflare
```

Fournisseurs de tunnel supportés :

- **Cloudflare Tunnel** — HTTPS gratuit, aucune exposition de port, support multi-domaine
- **Ngrok** — configuration rapide, domaines personnalisés (plan payant)
- **Tailscale** — réseau maillé privé, pas de port public

Voir [Référence de Configuration](docs/config-reference.md#tunnel) pour les options de configuration complètes.

## Sécurité

ZeroClaw implémente plusieurs couches de sécurité :

### Pairing

Le daemon génère un secret de pairing au premier lancement stocké dans `~/.zeroclaw/workspace/.pairing`. Les clients (agent, CLI) doivent présenter ce secret pour se connecter.

```bash
zeroclaw pairing rotate  # Génère un nouveau secret et invalide l'ancien
```

### Sandboxing

- **Runtime Docker** — isolation complète du conteneur avec systèmes de fichiers et réseaux séparés
- **Runtime Natif** — exécute en tant que processus utilisateur, scoped au workspace par défaut

### Listes d'Autorisation

Les canaux peuvent restreindre l'accès par ID utilisateur :

```toml
[channels.telegram]
enabled = true
allowed_users = [123456789, 987654321]  # Liste d'autorisation explicite
```

### Chiffrement

- **Matrix E2EE** — chiffrement de bout en bout complet avec vérification de dispositif
- **Transport TLS** — tout le trafic API et tunnel utilise HTTPS/TLS

Voir [Documentation Sécurité](docs/security/README.md) pour les politiques et pratiques complètes.

## Observabilité

ZeroClaw journalise vers `~/.zeroclaw/workspace/logs/` par défaut. Les journaux sont stockés par composant :

```
~/.zeroclaw/workspace/logs/
├── daemon.log           # Journaux du daemon (startup, requêtes API, erreurs)
├── agent.log            # Journaux de l'agent (routage message, exécution outil)
├── telegram.log         # Journaux spécifiques au canal (si activé)
└── matrix.log           # Journaux spécifiques au canal (si activé)
```

### Configuration de Journalisation

```toml
[logging]
level = "info"                           # debug, info, warn, error
path = "~/.zeroclaw/workspace/logs/"
rotation = "daily"                       # daily, hourly, size
max_size_mb = 100                        # Pour rotation basée sur la taille
retention_days = 30                      # Purge automatique après N jours
```

Voir [Référence de Configuration](docs/config-reference.md#logging) pour toutes les options de journalisation.

### Métriques (Planifié)

Support de métriques Prometheus pour la surveillance en production à venir. Suivi dans [#234](https://github.com/zeroclaw-labs/zeroclaw/issues/234).

## Compétences (Skills)

ZeroClaw prend en charge les compétences personnalisées — des modules réutilisables qui étendent les capacités du système.

### Définition de Compétence

Les compétences sont stockées dans `~/.zeroclaw/workspace/skills/<nom-compétence>/` avec cette structure :

```
skills/
└── ma-compétence/
    ├── skill.toml       # Métadonnées de compétence (nom, description, dépendances)
    ├── prompt.md        # Prompt système pour l'IA
    └── tools/           # Outils personnalisés optionnels
        └── mon_outil.py
```

### Exemple de Compétence

```toml
# skills/recherche-web/skill.toml
[skill]
name = "recherche-web"
description = "Recherche sur le web et résume les résultats"
version = "1.0.0"

[dependencies]
tools = ["web_fetch", "bash"]
```

```markdown
<!-- skills/recherche-web/prompt.md -->

Tu es un assistant de recherche. Lorsqu'on te demande de rechercher quelque chose :

1. Utilise web_fetch pour récupérer le contenu
2. Résume les résultats dans un format facile à lire
3. Cite les sources avec des URLs
```

### Utilisation de Compétences

Les compétences sont chargées automatiquement au démarrage de l'agent. Référencez-les par nom dans les conversations :

```
Utilisateur : Utilise la compétence recherche-web pour trouver les dernières actualités IA
Bot : [charge la compétence recherche-web, exécute web_fetch, résume les résultats]
```

Voir la section [Compétences (Skills)](#compétences-skills) pour les instructions de création de compétences complètes.

## Open Skills

ZeroClaw prend en charge les [Open Skills](https://github.com/openagents-com/open-skills) — un système modulaire et agnostique des fournisseurs pour étendre les capacités des agents IA.

### Activer Open Skills

```toml
[skills]
open_skills_enabled = true
# open_skills_dir = "/path/to/open-skills"  # optionnel
```

Vous pouvez également surcharger au runtime avec `ZEROCLAW_OPEN_SKILLS_ENABLED` et `ZEROCLAW_OPEN_SKILLS_DIR`.

## Développement

```bash
cargo build              # Build de développement
cargo build --release    # Build release (codegen-units=1, fonctionne sur tous les dispositifs incluant Raspberry Pi)
cargo build --profile release-fast    # Build plus rapide (codegen-units=8, nécessite 16 Go+ RAM)
cargo test               # Exécute la suite de tests complète
cargo clippy --locked --all-targets -- -D clippy::correctness
cargo fmt                # Format

# Exécute le benchmark de comparaison SQLite vs Markdown
cargo test --test memory_comparison -- --nocapture
```

### Hook pre-push

Un hook git exécute `cargo fmt --check`, `cargo clippy -- -D warnings`, et `cargo test` avant chaque push. Activez-le une fois :

```bash
git config core.hooksPath .githooks
```

### Dépannage de Build (erreurs OpenSSL sur Linux)

Si vous rencontrez une erreur de build `openssl-sys`, synchronisez les dépendances et recompilez avec le lockfile du dépôt :

```bash
git pull
cargo build --release --locked
cargo install --path . --force --locked
```

ZeroClaw est configuré pour utiliser `rustls` pour les dépendances HTTP/TLS ; `--locked` maintient le graphe transitif déterministe sur les environnements vierges.

Pour sauter le hook lorsque vous avez besoin d'un push rapide pendant le développement :

```bash
git push --no-verify
```

## Collaboration & Docs

Commencez par le hub de documentation pour une carte basée sur les tâches :

- Hub de documentation : [`docs/README.md`](docs/README.md)
- Table des matières unifiée docs : [`docs/SUMMARY.md`](docs/SUMMARY.md)
- Référence des commandes : [`docs/commands-reference.md`](docs/commands-reference.md)
- Référence de configuration : [`docs/config-reference.md`](docs/config-reference.md)
- Référence des fournisseurs : [`docs/providers-reference.md`](docs/providers-reference.md)
- Référence des canaux : [`docs/channels-reference.md`](docs/channels-reference.md)
- Runbook des opérations : [`docs/operations-runbook.md`](docs/operations-runbook.md)
- Dépannage : [`docs/troubleshooting.md`](docs/troubleshooting.md)
- Inventaire/classification docs : [`docs/docs-inventory.md`](docs/docs-inventory.md)
- Instantané triage PR/Issue (au 18 février 2026) : [`docs/project-triage-snapshot-2026-02-18.md`](docs/project-triage-snapshot-2026-02-18.md)

Références de collaboration principales :

- Hub de documentation : [docs/README.md](docs/README.md)
- Modèle de documentation : [docs/doc-template.md](docs/doc-template.md)
- Checklist de modification de documentation : [docs/README.md#4-documentation-change-checklist](docs/README.md#4-documentation-change-checklist)
- Référence de configuration des canaux : [docs/channels-reference.md](docs/channels-reference.md)
- Opérations de salles chiffrées Matrix : [docs/matrix-e2ee-guide.md](docs/matrix-e2ee-guide.md)
- Guide de contribution : [CONTRIBUTING.md](CONTRIBUTING.md)
- Politique de workflow PR : [docs/pr-workflow.md](docs/pr-workflow.md)
- Playbook du relecteur (triage + revue approfondie) : [docs/reviewer-playbook.md](docs/reviewer-playbook.md)
- Carte de propriété et triage CI : [docs/ci-map.md](docs/ci-map.md)
- Politique de divulgation de sécurité : [SECURITY.md](SECURITY.md)

Pour le déploiement et les opérations runtime :

- Guide de déploiement réseau : [docs/network-deployment.md](docs/network-deployment.md)
- Playbook d'agent proxy : [docs/proxy-agent-playbook.md](docs/proxy-agent-playbook.md)

## Soutenir ZeroClaw

Si ZeroClaw aide votre travail et que vous souhaitez soutenir le développement continu, vous pouvez faire un don ici :

<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Offrez-moi un café" /></a>

### 🙏 Remerciements Spéciaux

Un remerciement sincère aux communautés et institutions qui inspirent et alimentent ce travail open-source :

- **Harvard University** — pour favoriser la curiosité intellectuelle et repousser les limites du possible.
- **MIT** — pour défendre la connaissance ouverte, l'open source, et la conviction que la technologie devrait être accessible à tous.
- **Sundai Club** — pour la communauté, l'énergie, et la volonté incessante de construire des choses qui comptent.
- **Le Monde & Au-Delà** 🌍✨ — à chaque contributeur, rêveur, et constructeur là-bas qui fait de l'open source une force pour le bien. C'est pour vous.

Nous construisons en open source parce que les meilleures idées viennent de partout. Si vous lisez ceci, vous en faites partie. Bienvenue. 🦀❤️

## ⚠️ Dépôt Officiel & Avertissement d'Usurpation d'Identité

**Ceci est le seul dépôt officiel ZeroClaw :**

> <https://github.com/zeroclaw-labs/zeroclaw>

Tout autre dépôt, organisation, domaine ou package prétendant être "ZeroClaw" ou impliquant une affiliation avec ZeroClaw Labs est **non autorisé et non affilié à ce projet**. Les forks non autorisés connus seront listés dans [TRADEMARK.md](TRADEMARK.md).

Si vous rencontrez une usurpation d'identité ou une utilisation abusive de marque, veuillez [ouvrir une issue](https://github.com/zeroclaw-labs/zeroclaw/issues).

---

## Licence

ZeroClaw est sous double licence pour une ouverture maximale et la protection des contributeurs :

| Licence                      | Cas d'utilisation                                            |
| ---------------------------- | ------------------------------------------------------------ |
| [MIT](LICENSE-MIT)               | Open-source, recherche, académique, usage personnel          |
| [Apache 2.0](LICENSE-APACHE) | Protection de brevet, institutionnel, déploiement commercial |

Vous pouvez choisir l'une ou l'autre licence. **Les contributeurs accordent automatiquement des droits sous les deux** — voir [CLA.md](CLA.md) pour l'accord de contributeur complet.

### Marque

Le nom **ZeroClaw** et le logo sont des marques déposées de ZeroClaw Labs. Cette licence n'accorde pas la permission de les utiliser pour impliquer une approbation ou une affiliation. Voir [TRADEMARK.md](TRADEMARK.md) pour les utilisations permises et interdites.

### Protections des Contributeurs

- Vous **conservez les droits d'auteur** de vos contributions
- **Concession de brevet** (Apache 2.0) vous protège contre les réclamations de brevet par d'autres contributeurs
- Vos contributions sont **attribuées de manière permanente** dans l'historique des commits et [NOTICE](NOTICE)
- Aucun droit de marque n'est transféré en contribuant

## Contribuer

Voir [CONTRIBUTING.md](CONTRIBUTING.md) et [CLA.md](CLA.md). Implémentez un trait, soumettez une PR :

- Guide de workflow CI : [docs/ci-map.md](docs/ci-map.md)
- Nouveau `Provider` → `src/providers/`
- Nouveau `Channel` → `src/channels/`
- Nouveau `Observer` → `src/observability/`
- Nouveau `Tool` → `src/tools/`
- Nouvelle `Memory` → `src/memory/`
- Nouveau `Tunnel` → `src/tunnel/`
- Nouvelle `Skill` → `~/.zeroclaw/workspace/skills/<n>/`

---

**ZeroClaw** — Zéro surcharge. Zéro compromis. Déployez n'importe où. Échangez n'importe quoi. 🦀

## Historique des Étoiles

<p align="center">
  <a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
    <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
     <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
     <img alt="Graphique Historique des Étoiles" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
    </picture>
  </a>
</p>