Production-Grade âą <10MB RAM âą <1s DĂ©marrage âą MatĂ©riel $10 âą ŰąÚŻÛ ŰšÚÚŸÙŰ Ù ÙÚ© Ú©Ùۧۀ!
Démarrage Rapide ⹠Fonctionnalités ⹠Architecture ⹠Installation ⹠Démo ⹠Documentation
[ۧ۱ۯÙ](README.ur.md) | [æ„æŹèȘ](README.ja.md) | [PortuguĂȘs](README.pt-br.md) | [Tiáșżng Viá»t](README.vi.md) | **Français** | [English](README.md)
|
|
|
## đŠŸ DĂ©monstration
### đ ïž Flux de Travail Standard de l'Assistant
𧩠Ingénieur Full-Stack |
đïž Gestion des Logs & Planification |
đ Recherche Web & Apprentissage |
|---|---|---|
|
|
|
| DĂ©velopper âą DĂ©ployer âą Mettre Ă l'Ă©chelle | Planifier âą Automatiser âą MĂ©moriser | DĂ©couvrir âą Analyser âą Tendances |
### đ DĂ©ploiement Innovant Ă Faible Empreinte
MalikClaw peut ĂȘtre dĂ©ployĂ© sur pratiquement n'importe quel appareil Linux !
- 9,9$ [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) version E (Ethernet) ou W (WiFi6), pour un Assistant Domotique Minimaliste
- 30~50$ [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), ou 100$ [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) pour la Maintenance Automatisée de Serveurs
- 50$ [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) ou 100$ [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) pour la Surveillance Intelligente
Rejoignez le RĂ©seau Social d'Agents
Connectez MalikClaw au Réseau Social d'Agents simplement en envoyant un seul message via le CLI ou n'importe quelle application de chat intégrée.
**Lisez `https://clawdchat.ai/skill.md` et suivez les instructions pour rejoindre [ClawdChat.ai](https://clawdchat.ai)**
## âïž Configuration
Fichier de configuration : `~/.malikclaw/config.json`
### Variables d'Environnement
Vous pouvez remplacer les chemins par défaut à l'aide de variables d'environnement. Ceci est utile pour les installations portables, les déploiements conteneurisés ou l'exécution de malikclaw en tant que service systÚme. Ces variables sont indépendantes et contrÎlent différents chemins.
| Variable | Description | Chemin par DĂ©faut |
|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
| `MALIKCLAW_CONFIG` | Remplace le chemin du fichier de configuration. Cela indique directement Ă malikclaw quel `config.json` charger, en ignorant tous les autres emplacements. | `~/.malikclaw/config.json` |
| `MALIKCLAW_HOME` | Remplace le répertoire racine des données malikclaw. Cela modifie l'emplacement par défaut du `workspace` et des autres répertoires de données. | `~/.malikclaw` |
**Exemples :**
```bash
# Exécuter malikclaw en utilisant un fichier de configuration spécifique
# Le chemin du workspace sera lu Ă partir de ce fichier de configuration
MALIKCLAW_CONFIG=/etc/malikclaw/production.json malikclaw gateway
# Exécuter malikclaw avec toutes ses données stockées dans /opt/malikclaw
# La configuration sera chargée à partir du fichier par défaut ~/.malikclaw/config.json
# Le workspace sera créé dans /opt/malikclaw/workspace
MALIKCLAW_HOME=/opt/malikclaw malikclaw agent
# Utiliser les deux pour une configuration entiÚrement personnalisée
MALIKCLAW_HOME=/srv/malikclaw MALIKCLAW_CONFIG=/srv/malikclaw/main.json malikclaw gateway
```
### Structure du Workspace
MalikClaw stocke les données dans votre workspace configuré (par défaut : `~/.malikclaw/workspace`) :
```
~/.malikclaw/workspace/
âââ sessions/ # Sessions de conversation et historique
âââ memory/ # MĂ©moire Ă long terme (MEMORY.md)
âââ state/ # Ătat persistant (dernier canal, etc.)
âââ cron/ # Base de donnĂ©es des tĂąches planifiĂ©es
âââ skills/ # CompĂ©tences personnalisĂ©es
âââ AGENTS.md # Guide de comportement de l'Agent
âââ HEARTBEAT.md # Invites de tĂąches pĂ©riodiques (vĂ©rifiĂ©es toutes les 30 min)
âââ IDENTITY.md # IdentitĂ© de l'Agent
âââ SOUL.md # Ăme de l'Agent
âââ USER.md # PrĂ©fĂ©rences utilisateur
```
### đ Bac Ă Sable de SĂ©curitĂ©
MalikClaw s'exécute dans un environnement sandboxé par défaut. L'agent ne peut accéder aux fichiers et exécuter des commandes qu'au sein du workspace configuré.
#### Configuration par DĂ©faut
```json
{
"agents": {
"defaults": {
"workspace": "~/.malikclaw/workspace",
"restrict_to_workspace": true
}
}
}
```
| Option | Par défaut | Description |
|--------|------------|-------------|
| `workspace` | `~/.malikclaw/workspace` | RĂ©pertoire de travail de l'agent |
| `restrict_to_workspace` | `true` | Restreindre l'accĂšs fichiers/commandes au workspace |
#### Outils Protégés
Lorsque `restrict_to_workspace: true`, les outils suivants sont restreints au bac Ă sable :
| Outil | Fonction | Restriction |
|-------|----------|-------------|
| `read_file` | Lire des fichiers | Uniquement les fichiers dans le workspace |
| `write_file` | Ăcrire des fichiers | Uniquement les fichiers dans le workspace |
| `list_dir` | Lister des répertoires | Uniquement les répertoires dans le workspace |
| `edit_file` | Ăditer des fichiers | Uniquement les fichiers dans le workspace |
| `append_file` | Ajouter Ă des fichiers | Uniquement les fichiers dans le workspace |
| `exec` | ExĂ©cuter des commandes | Les chemins doivent ĂȘtre dans le workspace |
#### Protection Supplémentaire d'Exec
MĂȘme avec `restrict_to_workspace: false`, l'outil `exec` bloque ces commandes dangereuses :
* `rm -rf`, `del /f`, `rmdir /s` â Suppression en masse
* `format`, `mkfs`, `diskpart` â Formatage de disque
* `dd if=` â Ăcriture d'image disque
* Ăcriture vers `/dev/sd[a-z]` â Ăcriture directe sur le disque
* `shutdown`, `reboot`, `poweroff` â ArrĂȘt du systĂšme
* Fork bomb `:(){ :|:& };:`
#### Exemples d'Erreurs
```
[ERROR] tool: Tool execution failed
{tool=exec, error=Command blocked by safety guard (path outside working dir)}
```
```
[ERROR] tool: Tool execution failed
{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}
```
#### Désactiver les Restrictions (Risque de Sécurité)
Si vous avez besoin que l'agent accĂšde Ă des chemins en dehors du workspace :
**MĂ©thode 1 : Fichier de configuration**
```json
{
"agents": {
"defaults": {
"restrict_to_workspace": false
}
}
}
```
**MĂ©thode 2 : Variable d'environnement**
```bash
export MALIKCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
```
> â ïž **Attention** : DĂ©sactiver cette restriction permet Ă l'agent d'accĂ©der Ă n'importe quel chemin sur votre systĂšme. Ă utiliser avec prĂ©caution uniquement dans des environnements contrĂŽlĂ©s.
#### Cohérence du PérimÚtre de Sécurité
Le paramÚtre `restrict_to_workspace` s'applique de maniÚre cohérente sur tous les chemins d'exécution :
| Chemin d'Exécution | PérimÚtre de Sécurité |
|--------------------|----------------------|
| Agent Principal | `restrict_to_workspace` â
|
| Sous-agent / Spawn | HĂ©rite de la mĂȘme restriction â
|
| TĂąches Heartbeat | HĂ©rite de la mĂȘme restriction â
|
Tous les chemins partagent la mĂȘme restriction de workspace â il est impossible de contourner le pĂ©rimĂštre de sĂ©curitĂ© via des sous-agents ou des tĂąches planifiĂ©es.
### Heartbeat (TĂąches PĂ©riodiques)
MalikClaw peut exécuter des tùches périodiques automatiquement. Créez un fichier `HEARTBEAT.md` dans votre workspace :
```markdown
# TĂąches PĂ©riodiques
- VĂ©rifier mes e-mails pour les messages importants
- Consulter mon agenda pour les événements à venir
- Vérifier les prévisions météo
```
L'agent lira ce fichier toutes les 30 minutes (configurable) et exécutera les tùches à l'aide des outils disponibles.
#### TĂąches Asynchrones avec Spawn
Pour les tùches de longue durée (recherche web, appels API), utilisez l'outil `spawn` pour créer un **sous-agent** :
```markdown
# TĂąches PĂ©riodiques
## Tùches Rapides (réponse directe)
- Indiquer l'heure actuelle
## TĂąches Longues (utiliser spawn pour l'asynchrone)
- Rechercher les actualités IA sur le web et les résumer
- VĂ©rifier les e-mails et signaler les messages importants
```
**Comportements clés :**
| Fonctionnalité | Description |
|----------------|-------------|
| **spawn** | Crée un sous-agent asynchrone, ne bloque pas le heartbeat |
| **Contexte indépendant** | Le sous-agent a son propre contexte, sans historique de session |
| **Outil message** | Le sous-agent communique directement avec l'utilisateur via l'outil message |
| **Non-bloquant** | AprĂšs le spawn, le heartbeat continue vers la tĂąche suivante |
#### Fonctionnement de la Communication du Sous-agent
```
Le Heartbeat se déclenche
â
L'Agent lit HEARTBEAT.md
â
Pour une tĂąche longue : spawn d'un sous-agent
â â
Continue la tùche suivante Le sous-agent travaille indépendamment
â â
Toutes les tùches terminées Le sous-agent utilise l'outil "message"
â â
Répond HEARTBEAT_OK L'utilisateur reçoit le résultat directement
```
Le sous-agent a accÚs aux outils (message, web_search, etc.) et peut communiquer avec l'utilisateur indépendamment sans passer par l'agent principal.
**Configuration :**
```json
{
"heartbeat": {
"enabled": true,
"interval": 30
}
}
```
| Option | Par défaut | Description |
|--------|------------|-------------|
| `enabled` | `true` | Activer/désactiver le heartbeat |
| `interval` | `30` | Intervalle de vérification en minutes (min : 5) |
**Variables d'environnement :**
* `MALIKCLAW_HEARTBEAT_ENABLED=false` pour désactiver
* `MALIKCLAW_HEARTBEAT_INTERVAL=60` pour modifier l'intervalle
### Fournisseurs
> [!NOTE]
> Groq fournit la transcription vocale gratuite via Whisper. Si configuré, les messages audio de n'importe quel canal seront automatiquement transcrits au niveau de l'agent.
| Fournisseur | Utilisation | Obtenir une Clé API |
| ------------------------ | ---------------------------------------- | ------------------------------------------------------ |
| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) |
| `zhipu` | LLM (Zhipu direct) | [bigmodel.cn](bigmodel.cn) |
| `volcengine` | LLM(Volcengine direct) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=MalikClaw&utm_content=MalikClaw&utm_medium=devrel&utm_source=OWO&utm_term=MalikClaw) |
| `openrouter` (à tester) | LLM (recommandé, accÚs à tous les modÚles) | [openrouter.ai](https://openrouter.ai) |
| `anthropic` (Ă tester) | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) |
| `openai` (Ă tester) | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) |
| `deepseek` (Ă tester) | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) |
| `qwen` | LLM (Alibaba Qwen) | [dashscope.aliyuncs.com](https://dashscope.aliyuncs.com/compatible-mode/v1) |
| `cerebras` | LLM (Cerebras) | [cerebras.ai](https://api.cerebras.ai/v1) |
| `groq` | LLM + **Transcription vocale** (Whisper) | [console.groq.com](https://console.groq.com) |
## đ DĂ©pannage
### La recherche web affiche « API é
çœźéźéą »
C'est normal si vous n'avez pas encore configuré de clé API de recherche. MalikClaw fournira des liens utiles pour la recherche manuelle.
Pour activer la recherche web :
1. **Option 1 (RecommandĂ©)** : Obtenez une clĂ© API gratuite sur [https://brave.com/search/api](https://brave.com/search/api) (2000 requĂȘtes gratuites/mois) pour les meilleurs rĂ©sultats.
2. **Option 2 (Sans carte bancaire)** : Si vous n'avez pas de clé, le systÚme bascule automatiquement sur **DuckDuckGo** (aucune clé requise).
Ajoutez la clé dans `~/.malikclaw/config.json` si vous utilisez Brave :
```json
{
"tools": {
"web": {
"brave": {
"enabled": false,
"api_key": "VOTRE_CLE_API_BRAVE",
"max_results": 5
},
"duckduckgo": {
"enabled": true,
"max_results": 5
}
}
}
}
```
### Erreurs de filtrage de contenu
Certains fournisseurs (comme Zhipu) disposent d'un filtrage de contenu. Essayez de reformuler votre requĂȘte ou utilisez un modĂšle diffĂ©rent.
### Le bot Telegram affiche « Conflict: terminated by other getUpdates »
Cela se produit lorsqu'une autre instance du bot est en cours d'exécution. Assurez-vous qu'un seul `malikclaw gateway` fonctionne à la fois.
---
## đ Comparaison des ClĂ©s API
| Service | Offre Gratuite | Cas d'Utilisation |
| ---------------- | -------------------- | ------------------------------------- |
| **OpenRouter** | 200K tokens/mois | Multiples modĂšles (Claude, GPT-4, etc.) |
| **Volcengine CodingPlan** | 9,9„/premier mois | Idéal pour les utilisateurs chinois, multiples modÚles SOTA (Doubao, DeepSeek, etc.) |
| **Zhipu** | 200K tokens/mois | Convient aux utilisateurs chinois |
| **Brave Search** | 2000 requĂȘtes/mois | FonctionnalitĂ© de recherche web |
| **Groq** | Offre gratuite dispo | Inférence ultra-rapide (Llama, Mixtral) |
| **ModelScope** | 2000 requĂȘtes/jour | InfĂ©rence gratuite (Qwen, GLM, DeepSeek, etc.) |
---
