Création d'agents IA personnalisés avec OpenClaw : guide du développeur

Construire un agent IA prêt pour la production n’est pas la même chose qu’écrire un chatbot. Les agents doivent percevoir le contexte, raisonner sur des informations incomplètes, exécuter des plans en plusieurs étapes et se remettre des échecs, le tout sans supervision humaine. OpenClaw est une plateforme d'agents d'IA d'entreprise conçue spécifiquement pour ce niveau d'autonomie opérationnelle, offrant aux développeurs un environnement d'exécution structuré, un modèle de composition des compétences et une observabilité de premier ordre dès le premier jour.

Ce guide est destiné aux ingénieurs qui souhaitent passer de zéro à un agent OpenClaw déployé et surveillé. Nous couvrons les composants internes de l'architecture, la création de compétences, la gestion de la mémoire, les hooks d'orchestration et les modèles de déploiement qui garantissent la fiabilité des agents sous charge de production.

Points clés à retenir

Les agents OpenClaw sont composés de compétences (capacités atomiques), de couches mémoire et d'un orchestrateur qui planifie les séquences d'exécution.

Le fichier manifeste de l'agent déclare toutes les dépendances, autorisations et liaisons d'outils avant l'exécution.

Les compétences sont des fonctions sans état qui acceptent les entrées typées et émettent des sorties typées : la testabilité est intégrée.

Les niveaux Mémoire de travail, Mémoire d'épisode et Mémoire à long terme répondent à différents besoins de rétention et de récupération.

Les hooks (pré-exécution, post-exécution, sur erreur) vous permettent d'injecter une logique de surveillance, de limitation de débit et de repli sans modifier le code de compétence de base.

Le mode Sandbox d'OpenClaw vous permet de rejouer les traces de production localement pour le débogage sans appels d'API en direct.

Les transferts multi-agents utilisent un bus de messages typé : aucune chaîne brute ne transite entre les agents.

ECOSIRE fournit des implémentations gérées d'OpenClaw, des bibliothèques de compétences personnalisées et une optimisation continue pour les équipes d'entreprise.

Comprendre le modèle d'agent OpenClaw

Chaque agent OpenClaw est une composition de quatre primitives : Compétences, Mémoire, Outils et un Orchestreur.

Les Compétences sont les unités atomiques de la capacité de l'agent. Une compétence est une fonction qui accepte un schéma d'entrée typé et renvoie un schéma de sortie typé. Les compétences peuvent être synchrones ou asynchrones et déclarent explicitement leurs dépendances externes. Exemples : ParseInvoice, SendSlackMessage, QueryCRMContact, GenerateReport.

Les outils sont des liaisons système externes. OpenClaw est livré avec des outils intégrés pour les API REST, les bases de données, les systèmes de fichiers, les navigateurs et les files d'attente de messages. Vous enregistrez les outils dans le manifeste de l'agent et les injectez dans les compétences au moment de l'exécution via l'injection de dépendances.

La mémoire est organisée en trois niveaux. La mémoire de travail contient l'état actuel de la tâche : le bloc-notes de l'agent. La mémoire d'épisode stocke les historiques de tâches terminées qui peuvent être récupérés par similarité sémantique au sein de la session en cours. La mémoire à long terme persiste au fil des sessions et stocke les faits appris, les préférences de l'utilisateur et les connaissances du domaine.

L'Orchestrateur est le cœur du raisonnement. Il reçoit un énoncé d'objectif, interroge le registre de compétences disponible, construit un plan d'exécution et surveille chaque étape. Lorsqu'une compétence échoue, l'orchestrateur décide s'il doit réessayer, remplacer une compétence alternative ou passer à un humain.

Le schéma d'architecture d'un agent unique ressemble à ceci :

User Request
     ↓
[ Orchestrator ]
     ↓ plan
[ Skill Selector ] → [ Skill Registry ]
     ↓ execute
[ Skill Instance ]
     ↓ tool calls
[ Tool Layer ] → [ External Systems ]
     ↓ result
[ Memory Writer ]
     ↓ store
[ Working / Episode / Long-Term Memory ]
     ↓ next step or done
[ Orchestrator ] → response

Cette boucle se poursuit jusqu'à ce que l'orchestrateur détermine que l'objectif est atteint ou qu'une condition d'arrêt est atteinte.

Configuration de votre environnement de développement

Avant d'écrire votre première compétence, vous avez besoin du SDK OpenClaw et d'un runtime d'agent local.

npm install @openclaw/sdk @openclaw/runtime @openclaw/cli
npx openclaw init my-agent --template=typescript

La commande init génère un projet avec cette structure :

my-agent/
  agent.manifest.json   # Agent declaration
  skills/               # Skill implementations
  tools/                # Tool registrations
  memory/               # Memory adapter config
  tests/                # Skill and integration tests
  .openclaw/            # Local runtime state

Le agent.manifest.json est le fichier le plus important. Il déclare tout ce dont OpenClaw a besoin pour amorcer votre agent :

{
  "name": "invoice-processor",
  "version": "1.0.0",
  "runtime": "node-20",
  "skills": [
    "skills/extract-line-items.ts",
    "skills/validate-vendor.ts",
    "skills/post-to-erp.ts"
  ],
  "tools": {
    "erp": { "type": "rest", "baseUrl": "${ERP_BASE_URL}", "auth": "bearer" },
    "storage": { "type": "s3", "bucket": "${DOCS_BUCKET}" }
  },
  "memory": {
    "working": { "ttl": 3600 },
    "episode": { "backend": "redis", "maxItems": 500 },
    "longTerm": { "backend": "postgres", "table": "agent_facts" }
  },
  "permissions": ["read:invoices", "write:erp", "read:vendors"]
}

Les variables d'environnement sont injectées au moment de l'exécution et ne sont jamais stockées dans le manifeste.

Écrire votre première compétence

Les compétences suivent un contrat strict. Ils acceptent un objet input correspondant à un schéma déclaré, reçoivent tools et memory injectés, et renvoient un objet output ou lancent un SkillError typé.

import { defineSkill, SkillError } from "@openclaw/sdk";
import { z } from "zod";

const ExtractLineItemsInput = z.object({
  documentUrl: z.string().url(),
  documentType: z.enum(["invoice", "receipt", "purchase-order"]),
});

const ExtractLineItemsOutput = z.object({
  lineItems: z.array(
    z.object({
      description: z.string(),
      quantity: z.number(),
      unitPrice: z.number(),
      total: z.number(),
    })
  ),
  confidence: z.number().min(0).max(1),
});

export const ExtractLineItems = defineSkill({
  name: "extract-line-items",
  description: "Extracts line items from a document using OCR and LLM parsing",
  input: ExtractLineItemsInput,
  output: ExtractLineItemsOutput,
  tools: ["storage"],
  async run({ input, tools, memory }) {
    const fileBuffer = await tools.storage.get(input.documentUrl);
    if (!fileBuffer) {
      throw new SkillError("DOCUMENT_NOT_FOUND", `No document at ${input.documentUrl}`);
    }

    // OCR + LLM extraction logic here
    const extracted = await runOcrPipeline(fileBuffer);

    await memory.working.set("lastExtraction", extracted);

    return {
      lineItems: extracted.items,
      confidence: extracted.confidence,
    };
  },
});

Règles clés de conception des compétences :

Aucun effet secondaire sur la saisie : les compétences ne doivent pas modifier leurs objets de saisie.
Erreurs de frappe : lancez toujours SkillError avec un code lisible par machine, et non un Error générique.
Déclarer les dépendances des outils : Seuls les outils déclarés dans le tableau tools sont injectés. Les outils non déclarés provoquent une erreur de validation de démarrage.
Écrire explicitement en mémoire : les compétences ne conservent pas automatiquement leur état. Appelez memory.working.set() délibérément.

Gestion de la mémoire en pratique

Les trois niveaux de mémoire répondent à des objectifs différents, et le choix du niveau approprié est essentiel pour l'exactitude des agents.

La Mémoire de travail est un magasin de valeurs-clés en cours qui dure toute la durée d'une seule exécution de tâche. Utilisez-le pour transmettre des résultats intermédiaires entre compétences sans passer par la chaîne de sortie. Il s'efface automatiquement lorsque l'orchestrateur termine ou expire.

// Skill A writes
await memory.working.set("vendorId", "VND-4521");

// Skill B reads
const vendorId = await memory.working.get("vendorId");

Episode Memory est un magasin de recherche sémantique. Lorsqu'une tâche est terminée, l'orchestrateur écrit éventuellement un résumé intégré dans la mémoire de l'épisode. Les tâches futures peuvent récupérer des épisodes passés similaires pour éclairer leur raisonnement.

// Query past episodes
const relatedEpisodes = await memory.episode.search(
  "invoice from Acme Corp with disputed line items",
  { topK: 3, minScore: 0.75 }
);

La mémoire à long terme est la base de connaissances persistante de votre agent. Utilisez-le pour les faits qui devraient survivre au fil des sessions : règles de catégorisation des fournisseurs, préférences des utilisateurs, contraintes de domaine apprises.

// Store a learned fact
await memory.longTerm.upsert({
  key: `vendor:${vendorId}:paymentTerms`,
  value: "NET-30",
  source: "invoice-2024-0312",
  confidence: 0.9,
});

Une erreur courante consiste à écraser le contenu dans la mémoire à long terme. Conservez-le pour des faits stables et fiables. Le raisonnement éphémère appartient à la mémoire de travail.

Hooks de cycle de vie pour l'observabilité et le contrôle

OpenClaw expose quatre hooks de cycle de vie par exécution de compétence : preRun, postRun, onError et onTimeout. Enregistrez les hooks dans le manifeste de l'agent ou par programme dans votre fichier d'amorçage.

import { AgentRuntime } from "@openclaw/runtime";

const agent = new AgentRuntime({ manifest: "./agent.manifest.json" });

agent.useHook("preRun", async (ctx) => {
  ctx.metadata.startTime = Date.now();
  console.log(`[${ctx.skill}] starting with input keys: ${Object.keys(ctx.input)}`);
});

agent.useHook("postRun", async (ctx) => {
  const elapsed = Date.now() - ctx.metadata.startTime;
  metrics.record("skill.duration", elapsed, { skill: ctx.skill });
});

agent.useHook("onError", async (ctx) => {
  if (ctx.error.code === "RATE_LIMIT_EXCEEDED") {
    await sleep(ctx.error.retryAfterMs);
    return "retry";
  }
  alerting.send(`Skill ${ctx.skill} failed: ${ctx.error.message}`);
  return "escalate";
});

La valeur de retour du hook onError contrôle le comportement de l'orchestrateur : "retry" déclenche une nouvelle tentative (jusqu'au maximum configuré), "escalate" achemine la tâche vers une file d'attente humaine, "fail" termine la tâche immédiatement.

Tester les compétences en isolement

Étant donné que les compétences ont des entrées et des sorties typées, les tests unitaires sont simples. Les utilitaires de test d'OpenClaw fournissent des implémentations fictives de toutes les interfaces des outils.

import { testSkill } from "@openclaw/testing";
import { ExtractLineItems } from "../skills/extract-line-items";

describe("ExtractLineItems", () => {
  it("extracts items from a valid invoice", async () => {
    const result = await testSkill(ExtractLineItems, {
      input: {
        documentUrl: "s3://test-bucket/invoice-001.pdf",
        documentType: "invoice",
      },
      mocks: {
        storage: {
          get: jest.fn().mockResolvedValue(samplePdfBuffer),
        },
      },
    });

    expect(result.lineItems).toHaveLength(3);
    expect(result.confidence).toBeGreaterThan(0.8);
  });

  it("throws DOCUMENT_NOT_FOUND for missing file", async () => {
    await expect(
      testSkill(ExtractLineItems, {
        input: { documentUrl: "s3://test-bucket/missing.pdf", documentType: "invoice" },
        mocks: { storage: { get: jest.fn().mockResolvedValue(null) } },
      })
    ).rejects.toMatchObject({ code: "DOCUMENT_NOT_FOUND" });
  });
});

Utilisez le mode Sandbox pour les tests d'intégration. Sandbox rejoue les traces de production enregistrées par rapport à votre code de compétence actuel, détectant les régressions avant qu'elles n'atteignent les systèmes en direct.

npx openclaw sandbox replay --trace=traces/invoice-20240315.json

Déploiement en production

Les agents OpenClaw peuvent être déployés sous forme de conteneurs Docker, de fonctions sans serveur ou de processus de longue durée. Le modèle recommandé pour les déploiements d'entreprise est un pool d'agents conteneurisé derrière une file d'attente de tâches.

FROM openclaw/runtime:node-20
WORKDIR /agent
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN npx openclaw build
CMD ["npx", "openclaw", "serve", "--workers=4"]

Pour les scénarios à haut débit, configurez le pool d'agents avec des règles de mise à l'échelle automatique. Le runtime OpenClaw expose les métriques Prometheus à /metrics pour la profondeur de la file d'attente, les centiles de latence des compétences, les taux d'erreur et l'utilisation de la mémoire : connectez-les à votre pile d'alertes.

Liste de contrôle de production avant la mise en service :

Toutes les variables d'environnement se trouvent dans un gestionnaire de secrets (AWS Secrets Manager, HashiCorp Vault), et non dans des fichiers .env.
Les backends de mémoire (Redis, PostgreSQL) ont configuré le pool de connexions.
Le paramètre maxConcurrentTasks correspond à la capacité de votre infrastructure.
Les limites de débit sur les appels d'outils externes correspondent aux limites de l'API du fournisseur.
Une file d'attente de lettres mortes est configurée pour les tâches qui épuisent les tentatives.
Le traçage distribué (OpenTelemetry) est activé et les traces circulent vers votre plateforme d'observabilité.

Questions fréquemment posées

Comment l'orchestrateur OpenClaw décide-t-il quelle compétence exécuter ensuite ?

L'orchestrateur utilise une combinaison de décomposition des objectifs et de correspondance des compétences. Il divise l'objectif principal en sous-objectifs, puis interroge le registre de compétences en utilisant la similarité sémantique par rapport à la description de chaque sous-objectif. Les compétences sont classées par score de pertinence, disponibilité des dépendances et taux de réussite historique. L'orchestrateur crée un graphique acyclique dirigé des exécutions de compétences et résout les dépendances avant de démarrer.

Une compétence peut-elle appeler directement une autre compétence ?

Non : les compétences ne doivent pas appeler directement d’autres compétences. La coordination transversale est de la responsabilité de l'orchestrateur. Si vous avez besoin du résultat de la compétence A avant l'exécution de la compétence B, déclarez la dépendance dans le plan orchestrateur. Cela permet de conserver les compétences apatrides et testables individuellement. L'exception concerne les compétences composites, qui sont explicitement marquées comme primitives d'orchestration.

Que se passe-t-il lorsqu'une API externe est en panne lors de l'exécution d'une compétence ?

Le hook onError intercepte l’échec. Si le hook renvoie "retry", l'orchestrateur attend l'intervalle d'attente configuré et réessaye la compétence. Après des tentatives épuisées, la tâche est déplacée vers la file d'attente de lettres mortes. Si vous disposez d’une compétence de secours enregistrée pour la même fonctionnalité, l’orchestrateur l’essaiera avant d’abandonner. L'état partiel de la tâche est conservé dans la mémoire de travail afin que la tâche puisse reprendre à partir de la dernière compétence réussie.

Comment gérez-vous les secrets dont les compétences ont besoin au moment de l'exécution ?

Les outils déclarés dans le manifeste de l'agent sont initialisés avec les informations d'identification au démarrage, et non par compétence. Votre gestionnaire de secrets remplit les variables d'environnement référencées dans le manifeste (${ERP_BASE_URL}, ${DOCS_BUCKET}, etc.) au démarrage du conteneur. Les compétences ne voient jamais les informations d'identification brutes : elles interagissent avec les instances d'outils pré-authentifiées injectées par le runtime.

Y a-t-il une limite au nombre de compétences qu'un agent peut posséder ?

Le registre de compétences n'a pas de limite stricte, mais la qualité pratique de l'orchestration se dégrade si vous enregistrez des centaines de compétences dont les descriptions se chevauchent. Regroupez les compétences connexes en ensembles de compétences et utilisez des descriptions claires et distinctes. Pour les très grandes bibliothèques de compétences, envisagez de les diviser en agents spécialisés et d’utiliser l’orchestration multi-agents pour acheminer les tâches vers le bon agent.

Les agents OpenClaw peuvent-ils s'exécuter sur site sans dépendances cloud ?

Oui. OpenClaw est indépendant du cloud. Le moteur d'exécution, les backends de mémoire et la couche d'outils peuvent tous être configurés pour utiliser une infrastructure sur site. Redis peut s'exécuter localement, le backend de mémoire à long terme peut pointer vers une instance PostgreSQL sur site et les intégrations d'outils peuvent cibler les API internes. Le seul appel externe est adressé au fournisseur LLM pour le raisonnement de l'orchestrateur. Vous pouvez le configurer pour utiliser un LLM sur site si nécessaire.

Comment versionner les compétences d'un agent sans interrompre les tâches en cours d'exécution ?

Les compétences sont versionnées dans le manifeste de l'agent avec une version sémantique. Le runtime prend en charge l’exécution simultanée de plusieurs versions de compétences lors d’un déploiement continu. Les tâches en vol continuent d'utiliser la version de compétence avec laquelle elles ont commencé ; les nouvelles tâches récupèrent la dernière version. Les modifications radicales apportées aux schémas d'entrée/sortie des compétences nécessitent une modification majeure de la version et un plan de migration pour tout agent qui consomme la sortie de cette compétence.

Prochaines étapes

La création d'agents d'IA de niveau production nécessite bien plus qu'un bon code : cela nécessite une expérience opérationnelle des modes de défaillance, des modèles de mise à l'échelle et des bibliothèques de compétences spécifiques à un domaine qui prennent des mois à développer et à affiner.

Le service OpenClaw Custom Skills d'ECOSIRE assure le développement d'agents de bout en bout : analyse des besoins, architecture des compétences, intégration avec vos systèmes existants, tests, déploiement et optimisation continue. Notre équipe a créé des agents OpenClaw pour le traitement des documents, l'automatisation ERP, le support client, l'analyse financière, etc.

Parlez à un spécialiste OpenClaw pour discuter de vos besoins en automatisation et obtenir une feuille de route de développement personnalisée.

Building Custom AI Agents with OpenClaw: Developer Guide