Agent

Un agent dans OpenClaw est une instance d'exécution qui traite des messages, prend des décisions, utilise des outils et maintient une conversation cohérente.

Qu'est-ce qu'un agent ?

Un agent est :

  • Autonome : Prend des décisions basées sur le contexte
  • Orienté tâches : Peut décomposer et résoudre des problèmes complexes
  • Équipé d'outils : Accès à bash, browser, nodes, etc.
  • Contextuel : Se souvient de l'historique et du contexte
  • Adaptatif : Apprend de ses erreurs et s'améliore

Architecture

┌─────────────────┐
│  Message User   │
└────────┬────────┘
         ↓
┌─────────────────┐
│     Gateway     │ ← Point d'entrée
└────────┬────────┘
         ↓
┌─────────────────┐
│  Agent Loop     │ ← Cycle d'exécution
└────────┬────────┘
         ↓
┌─────────────────┐
│  Model (LLM)    │ ← Inférence
└────────┬────────┘
         ↓
┌─────────────────┐
│  Tools/Skills   │ ← Exécution
└────────┬────────┘
         ↓
┌─────────────────┐
│  Response       │ ← Réponse finale
└─────────────────┘

Composants

1. Runtime

L'environnement d'exécution :

  • Workspace isolé
  • Variables d'environnement
  • Compétences chargées
  • Contexte assemblé

Voir Agent Runtime

2. Loop

Le cycle d'exécution :

  • Réception message
  • Assemblage contexte + prompt
  • Inférence modèle
  • Exécution outils
  • Streaming réponse
  • Persistance

Voir Agent Loop

3. Prompt système

Instructions de base :

  • Identité (SOUL.md)
  • Règles (AGENTS.md)
  • Contexte utilisateur (USER.md)
  • Outils disponibles
  • Mémoire

Voir System Prompt

4. Workspace

Espace de fichiers :

  • Fichiers de contexte
  • Mémoire (daily + long-term)
  • Projets utilisateur
  • Scripts/outils

Voir Agent Workspace

5. Session

État de conversation :

  • Historique messages
  • Metadata
  • Token usage
  • Lifecycle

Voir Session

Types d'agents

Agent principal (main)

Session par défaut :

  • Conversation directe utilisateur ↔ agent
  • Accès complet au workspace
  • Mémoire long terme (MEMORY.md)
  • Tous les outils disponibles

Subagents

Agents spécialisés spawned pour une tâche :

  • Tâche définie (ex: "traduire 12 pages")
  • Contexte limité
  • Pas d'accès MEMORY.md
  • Auto-terminaison après tâche

Voir Subagents

Agents de groupe

Dans les chats de groupe :

  • Écoute tous les messages
  • Répond quand mentionné ou pertinent
  • Ne domine pas la conversation
  • Comportement social approprié

Capacités (Tools/Skills)

Fichiers

  • Read : Lire fichiers
  • Write : Créer/écrire fichiers
  • Edit : Éditer précisément

Shell

  • exec : Exécuter commandes bash
  • process : Gérer processus background

Web

  • web_search : Recherche Brave
  • web_fetch : Récupérer contenu web
  • browser : Automatisation navigateur

Messagerie

  • message : Envoyer messages (email, Telegram, Discord, etc.)
  • tts : Text-to-speech

Nodes

  • nodes : Contrôler appareils pairés (caméras, etc.)

Autres

  • image : Analyser images
  • canvas : Présenter UI
  • Plugins personnalisés

Voir Tools

Configuration

config.yaml

agents:
  defaults:
    model: "anthropic/claude-sonnet-4"
    timeoutSeconds: 600
    thinking: "low"
    verbose: false
    compaction:
      enabled: true
      threshold: 0.8

Variables d'environnement

export OPENCLAW_MODEL="anthropic/claude-sonnet-4"
export OPENCLAW_THINKING="low"
export OPENCLAW_VERBOSE="false"

Paramètres d'exécution

# CLI
openclaw agent --model claude-opus-4 --thinking high "Analyze this codebase"

# RPC
gateway.rpc('agent', {
  model: 'anthropic/claude-opus-4',
  thinking: 'high',
  verbose: true,
  message: 'Analyze this codebase'
})

Lifecycle

  1. Création : Session créée ou réutilisée
  2. Initialisation : Chargement contexte + compétences
  3. Exécution : Boucle agent
  4. Complétion : Réponse finale
  5. Persistance : Sauvegarde historique
  6. Nettoyage : Libération ressources

Modes de thinking

  • off : Pas de raisonnement visible
  • low : Raisonnement minimal (rapide)
  • medium : Raisonnement équilibré
  • high : Raisonnement approfondi (lent)

Voir Thinking Levels

Verbose mode

  • false : Réponses concises
  • true : Détails d'exécution (outils, erreurs, etc.)

Streaming

Réponses progressives :

  • Assistant deltas : Texte au fur et à mesure
  • Tool events : Outils en cours d'exécution
  • Lifecycle events : Start, end, error

Voir Streaming

Erreurs et retry

  • Timeout : Abandon après timeoutSeconds
  • Compaction error : Retry après compaction
  • Tool error : Continuer ou échouer selon configuration
  • Model error : Retry avec backoff

Bonnes pratiques

  1. Sessions courtes : /new pour nouveaux sujets
  2. Mémoire externe : Fichiers > historique de session
  3. Outils appropriés : Bash > Python exec si possible
  4. Context minimal : Charger seulement ce qui est nécessaire
  5. Monitoring : Surveiller token usage et performances

Commandes utiles

# Exécuter agent
openclaw agent "Deploy latest changes"

# Avec options
openclaw agent --model opus-4 --thinking high --verbose "Complex analysis"

# Session spécifique
openclaw agent --session project-a "Status?"

# Attendre complétion
openclaw agent --wait "Long task"

Voir CLI Agent pour toutes les options.

Développement

Créer un agent personnalisé

import { createAgent } from '@openclaw/core';

const agent = await createAgent({
  model: 'anthropic/claude-sonnet-4',
  workspace: '/path/to/workspace',
  skills: ['exec', 'web_search', 'message'],
  hooks: {
    before_agent_start: async (ctx) => {
      // Custom logic
    }
  }
});

const result = await agent.run({
  message: 'Hello',
  sessionKey: 'custom:session'
});

Tests

# Tester agent
npm run test:agent

# Test d'intégration
npm run test:integration

Voir Development pour plus de détails.