Plugin OpenClaw

Le plugin CoreWeave Forge pour OpenClaw trace automatiquement chaque session d’agent qui transite par la passerelle OpenClaw et envoie les données structurées à Agent Lens. Le plugin journalise chaque tour de conversation, chaque appel de modèle et chaque exécution d’outil, sans aucune modification du code de l’application. Utilisez ces traces pour déboguer les sessions, auditer l’utilisation des outils et surveiller les coûts et la latence de l’ensemble de vos runs. Ce guide s’adresse aux opérateurs de la passerelle OpenClaw qui souhaitent activer le traçage Agent Lens pour les agents exécutés derrière la passerelle. Il explique comment installer et configurer le plugin, consulter les traces obtenues et résoudre les problèmes courants.

Ce plugin envoie les données de session OpenClaw à Agent Lens. Ces données peuvent inclure les prompts des utilisateurs, les réponses des modèles, les entrées et sorties des outils, les résultats des outils et l’historique des conversations.Le plugin n’assure ni l’effacement des informations personnelles identifiables (PII) ni le masquage des données sensibles. Pour désactiver la capture du contenu, définissez captureContent: false dans la configuration du plugin. Si vos exigences de sécurité ou de conformité ne vous permettent pas d’envoyer ces données à Agent Lens, n’installez pas ce plugin.

Prérequis

Node.js v24.16 ou version ultérieure, ou v26.1 ou version ultérieure. Node.js v25 n’est pas pris en charge.
OpenClaw 2026.9.8 ou version ultérieure.
Un compte CoreWeave Forge et une clé API.
Un projet Agent Lens ([YOUR-TEAM]/[YOUR-PROJECT]) destiné à recevoir les traces.

Installer le plugin

Suivez les étapes ci-dessous pour installer le plugin, l’enregistrer auprès de la passerelle OpenClaw et vérifier que les traces parviennent bien à votre projet Agent Lens.

Installer le paquet

Ce plugin est distinct du plugin weave-openclaw documenté dans le guide Weave. Son identifiant de plugin est forge, et c’est ce nom qu’utilisent son entrée de configuration et sa commande de statut. Si vous avez installé weave-openclaw, désactivez-le et désinstallez-le avant d’installer ce plugin, afin d’éviter que les deux n’envoient des traces en double. Déplacez vos paramètres de plugins.entries.weave vers plugins.entries.forge et remplacez weave par forge dans plugins.allow. Les champs de configuration et les identifiants d’authentification restent inchangés.

openclaw plugins install clawhub:@coreweave/forge-agent-lens-for-openclaw

La passerelle OpenClaw charge le plugin via sa configuration. Vous n’avez pas besoin de l’importer dans le code de votre application.

Définir votre clé API

Remplacez [YOUR-API-KEY] par votre clé API, puis exportez-la :

export WANDB_API_KEY="[YOUR-API-KEY]"

OpenClaw charge également WANDB_API_KEY depuis ~/.openclaw/.env. Consultez la référence de configuration pour découvrir les autres façons de fournir la clé.

Ajouter le plugin à la configuration de votre passerelle

Par défaut, la configuration se trouve dans ~/.openclaw/openclaw.json (au format JSON5, qui autorise les commentaires et les virgules finales). Si vous n’en avez pas encore, exécutez openclaw onboard pour en générer une. Remplacez [YOUR-TEAM] et [YOUR-PROJECT] par les valeurs de votre projet.

{
  plugins: {
    allow: ["forge"],
    entries: {
      forge: {
        enabled: true,
        config: { entity: "YOUR-TEAM", project: "YOUR-PROJECT" },
        hooks: { allowConversationAccess: true },
      },
    },
  },
}

Définissez hooks.allowConversationAccess sur true pour qu’OpenClaw exécute les hooks du plugin qui transmettent du contenu, llm_input et agent_end. Sans ce paramètre, les spans d’appel de modèle ne contiennent ni le texte du prompt ni les instructions système. La structure des traces, les appels d’outils ainsi que les totaux de jetons et de coûts restent néanmoins transmis via les événements de diagnostic.Le paramètre de premier niveau diagnostics.enabled d’OpenClaw vaut true par défaut. Si vous le définissez sur false, les événements de diagnostic sur lesquels repose le plugin sont désactivés, et aucune trace n’est envoyée.

Redémarrer la passerelle et vérifier

Redémarrez la passerelle OpenClaw :

openclaw gateway restart

Exécutez ensuite /forge status dans n’importe quelle interface de chat OpenClaw. Si le plugin indique running, il est actif. Les traces apparaissent dans votre projet Agent Lens à l’adresse https://forge.coreweave.com/agent-lens/[YOUR-TEAM]/[YOUR-PROJECT] quelques secondes après votre premier run d’agent. La ligne dashboard de la sortie de statut renvoie vers le même projet dans Weave, qui partage les données de trace.

Afficher les traces OpenClaw dans Agent Lens

Une fois le plugin actif, chaque session d’agent génère une trace que vous pouvez examiner dans l’interface d’Agent Lens. Après avoir exécuté au moins une session d’agent, ouvrez votre projet dans l’interface d’Agent Lens :

Accédez à CoreWeave Forge, sélectionnez Agent Lens dans le menu des produits, puis sélectionnez votre projet dans le sélecteur de projet, en haut du menu latéral.
Dans le menu latéral, sélectionnez Conversations.
Sélectionnez l’onglet Conversations pour afficher toutes les conversations d’agent enregistrées dans votre projet.
Sélectionnez une conversation pour examiner son arborescence complète.

Pour plus d’informations sur l’onglet Conversations, consultez Afficher l’activité des agents. Le plugin émet des spans conformément aux conventions sémantiques GenAI d’OpenTelemetry (OTel) :

Span	Émis pour	Attributs clés
`invoke_agent <agent>`	Chaque run d’agent	`gen_ai.agent.name`, `gen_ai.conversation.id`, coût cumulé, utilisation des jetons
`chat <model>`	Chaque appel de modèle	`gen_ai.request.model`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`
`execute_tool <tool>`	Chaque exécution d’outil	`gen_ai.tool.name`, `gen_ai.tool.call.id`

Référence de configuration

Cette section présente la référence de configuration complète de l’entrée du plugin forge dans openclaw.json. Seuls entity et project sont requis. Le plugin recherche une clé API dans l’ordre suivant :

Le champ apiKey dans la configuration du plugin, sous forme d’objet SecretRef ou de chaîne littérale. Pour des raisons de sécurité, nous déconseillons l’utilisation de chaînes littérales.
La variable d’environnement WANDB_API_KEY, qu’OpenClaw charge également depuis ~/.openclaw/.env.
Une entrée ~/.netrc pour api.wandb.ai, renseignée par wandb login.

Un SecretRef de type env fonctionne sans configuration supplémentaire. Un SecretRef de type file ou exec nécessite une entrée secrets.providers correspondante dans la configuration de votre passerelle. Voir Gestion des secrets OpenClaw.

{
  plugins: {
    entries: {
      forge: {
        enabled: true,
        config: {
          entity: "YOUR-TEAM",
          project: "YOUR-PROJECT",
          // Lit WANDB_API_KEY depuis l’environnement si apiKey est omis.
          // SecretRef prend en charge source: "env", "file" ou "exec". La source
          // "env" fonctionne avec provider: "default". Les sources "file" et "exec"
          // nécessitent une entrée secrets.providers correspondante.
          // Une chaîne en clair est prise en charge, mais déconseillée.
          apiKey: { source: "env", provider: "default", id: "WANDB_API_KEY" },
          serviceName: "openclaw-agent",
          // Facultatif : améliore le regroupement dans l’onglet Conversations.
          agentName: "my-agent",
          agentVersion: "v1.0",
          agentDescription: "What my agent does.",
          // Activé par défaut. Définissez sur false pour une désactivation complète (politique
          // de conformité ou de conservation). Le plugin ne masque pas les chaînes
          // capturées ; nettoyez-les en amont si nécessaire.
          captureContent: true,
          // Fréquence, en millisecondes, d’envoi des traces par le plugin. Minimum 1000.
          flushIntervalMs: 1000,
        },
        hooks: { allowConversationAccess: true },
      },
    },
  },
}

captureContent vaut true par défaut. Lorsque captureContent vaut true, le plugin émet également les messages d’entrée et de sortie, les arguments et les résultats des outils, en respectant la structure de charge utile gen_ai.input.messages et gen_ai.output.messages. Le plugin consigne les sous-agents, les événements de compaction, la détection de boucles, les nouvelles tentatives et le dimensionnement du contexte sous forme d’attributs supplémentaires et d’événements de span. Définissez captureContent sur false pour désactiver la capture si vos politiques de conformité ou de conservation l’exigent.

Dépannage

Si les traces n’atteignent pas Agent Lens ou si les champs content sont vides, utilisez les sections suivantes pour diagnostiquer les causes les plus courantes. Le journal de la passerelle correspond à la sortie affichée dans le terminal par le processus qui exécute openclaw, ou au flux de journaux de votre gestionnaire de processus si vous l’avez exécuté en tant que démon.

Plugin chargé, mais aucun span n’apparaît

Exécutez /forge status. Si le cycle de vie est disabled, config-error ou not-started, le plugin ne s’est pas activé. Recherchez dans le journal de la passerelle les messages forge: entity is required, forge: project is required ou forge: init failed.
Assurez-vous de ne pas avoir défini diagnostics.enabled: false dans la configuration de la passerelle. Ce champ doit être à true.
Vérifiez que l’entity et le projet correspondent au projet Agent Lens que vous consultez. /forge status doit afficher project=[YOUR-TEAM]/[YOUR-PROJECT].
Vérifiez la source d’authentification. /forge status doit afficher auth=.... Si la valeur indiquée est WANDB_API_KEY env alors que vous avez défini la clé dans une autre variable d’environnement, le plugin lit la mauvaise clé.

Les spans arrivent, mais le texte d’entrée est vide

Recherchez les messages suivants dans le journal de la passerelle :

[plugins] typed hook "llm_input"  blocked because non-bundled plugins must set
                                  plugins.entries.forge.hooks.allowConversationAccess=true
[plugins] typed hook "agent_end"  blocked ...

OpenClaw conditionne les hooks qui transportent du contenu à une activation explicite par l’opérateur. Définissez plugins.entries.forge.hooks.allowConversationAccess: true dans votre configuration, puis redémarrez la passerelle. La structure des spans ainsi que les données de coût et d’utilisation transitent par les événements de diagnostic, et non par les hooks. Elles restent donc disponibles même lorsque allowConversationAccess vaut false.

Erreurs lors de l’envoi des spans vers Agent Lens

Si le plugin est actif et génère des spans, mais que ceux-ci n’apparaissent pas dans Agent Lens, recherchez une erreur d’exportation dans le journal de la passerelle et reportez-vous au tableau suivant.

Symptôme	Cause la plus probable	Solution
`401` ou `403`	Clé API non valide ou de portée limitée	Vérifiez que la clé est à jour et qu’elle a accès à l’entity et au projet. La commande `wandb login` actualise `~/.netrc`.
Connexion refusée ou erreur DNS	DNS, proxy ou pare-feu	Vérifiez que l’hôte de la passerelle peut joindre Forge sur le port `443`.

Gérer le plugin

Utilisez les commandes suivantes pour mettre à jour, désactiver, activer ou supprimer le plugin :

openclaw plugins update forge
openclaw plugins disable forge
openclaw plugins enable forge
openclaw plugins uninstall forge

Agent Lens

Guides

Intégrations

Référence

Prérequis

Installer le plugin

Afficher les traces OpenClaw dans Agent Lens

Référence de configuration

Dépannage

Plugin chargé, mais aucun span n’apparaît

Les spans arrivent, mais le texte d’entrée est vide

Erreurs lors de l’envoi des spans vers Agent Lens

Gérer le plugin

​Prérequis

​Installer le plugin

​Afficher les traces OpenClaw dans Agent Lens

​Référence de configuration

​Dépannage

​Plugin chargé, mais aucun span n’apparaît

​Les spans arrivent, mais le texte d’entrée est vide

​Erreurs lors de l’envoi des spans vers Agent Lens

​Gérer le plugin

Prérequis

Installer le plugin

Afficher les traces OpenClaw dans Agent Lens

Référence de configuration

Dépannage

Plugin chargé, mais aucun span n’apparaît

Les spans arrivent, mais le texte d’entrée est vide

Erreurs lors de l’envoi des spans vers Agent Lens

Gérer le plugin