Plugin OpenClaw - CoreWeave Docs

Le plugin Weave OpenClaw trace automatiquement chaque session d’agent qui transite par la passerelle OpenClaw et envoie les données structurées vers W&B Weave. 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 le coût et la latence de vos runs. Ce guide s’adresse aux opérateurs de passerelle OpenClaw qui souhaitent activer le traçage Weave pour les agents exécutés derrière la passerelle. Il explique comment installer et configurer le plugin, consulter les traces générées et résoudre les problèmes courants.

Ce plugin envoie les données de session OpenClaw vers Weave. Ces données peuvent inclure les prompts des utilisateurs, les réponses du modèle, les entrées et sorties des outils, les résultats des outils et l’historique des conversations.Le plugin ne prend en charge ni la suppression 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é vous interdisent d’envoyer ces données vers Weave, n’installez pas ce plugin.

Prérequis

Node.js v22.14 ou version ultérieure.
OpenClaw 2026.4.25 ou version ultérieure, avec l’API de plugins.
Un compte CoreWeave Forge et une clé API.
Un projet Weave ([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 Weave.

Installer le paquet

openclaw plugins install weave-openclaw

Utilisez le nom complet weave-openclaw (weave seul désigne le SDK W&B, et non ce plugin). La passerelle OpenClaw charge le plugin via sa configuration : vous n’avez pas à l’importer dans le code de votre application.

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: ["weave"],
    entries: {
      weave: {
        enabled: true,
        config: { entity: "YOUR-TEAM", project: "YOUR-PROJECT" },
        hooks: { allowConversationAccess: true },
      },
    },
  },
}

Définissez hooks.allowConversationAccess sur true afin qu’OpenClaw exécute les hooks qui transportent du contenu (llm_input, llm_output, agent_end) et que les spans incluent le texte d’entrée et de sortie, ainsi que les arguments et les résultats des outils.diagnostics.enabled est activé par défaut. Ne le définissez explicitement que si vous souhaitez le désactiver.

Redémarrer la passerelle et vérifier

Redémarrez la passerelle OpenClaw, puis exécutez /weave status dans n’importe quelle interface de chat OpenClaw pour vérifier que le plugin est actif. Les traces apparaissent à l’adresse https://forge.coreweave.com/wandb/[YOUR-TEAM]/[YOUR-PROJECT]/weave/ quelques secondes après le premier run de votre agent.

Afficher les traces OpenClaw dans Weave

Une fois le plugin actif, chaque session d’agent produit une trace que vous pouvez inspecter dans l’interface de Weights & Biases. Après avoir exécuté au moins une session d’agent, ouvrez votre projet dans l’interface de Weights & Biases :

Accédez à Forge et sélectionnez votre projet.
Dans le menu latéral, sélectionnez Agents.
Sélectionnez l’onglet Conversations pour afficher toutes les conversations d’agent enregistrées dans votre projet.
Sélectionnez une conversation pour inspecter son arborescence complète.

Pour en savoir plus sur la vue Agents, consultez Afficher l’activité des agents. Le plugin émet des spans conformément aux conventions sémantiques GenAI d’OpenTelemetry (OTel) :

Span	Émis	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 constitue la référence de configuration complète de l’entrée du plugin weave dans openclaw.json. Le champ apiKey prend en charge quatre sources d’authentification, résolues dans l’ordre suivant :

Un objet SecretRef avec source: "env" ou source: "file" (voir la ligne 10 de l’exemple ci-dessous).
Une chaîne apiKey littérale (prise en charge, mais déconseillée).
La variable d’environnement WANDB_API_KEY.
Une entrée ~/.netrc pour l’hôte Weave, renseignée par wandb login.

{
  plugins: {
    entries: {
      weave: {
        enabled: true,
        config: {
          entity: "YOUR-TEAM",
          project: "YOUR-PROJECT",
          // Si apiKey est omis, WANDB_API_KEY est lu depuis l’environnement.
          // SecretRef prend en charge source: "env" ou "file" :
          //   { source: "env",  provider: "default", id: "WANDB_API_KEY" }
          //   { source: "file", provider: "default", id: "/run/secrets/wandb" }
          // 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 Agents.
          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 rétention). Le plugin ne masque pas les
          // chaînes capturées ; nettoyez-les en amont si nécessaire.
          captureContent: true,
          flushIntervalMs: 1000,
        },
        hooks: { allowConversationAccess: true },
      },
    },
  },
}

captureContent est défini sur true par défaut. Lorsque captureContent vaut true, le plugin émet également les messages d’entrée et de sortie, les arguments des outils et les résultats des outils, selon la structure de charge utile gen_ai.input.messages et gen_ai.output.messages. Le plugin consigne également 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, par exemple pour respecter vos politiques de conformité ou de rétention des données.

Cloud dédié de W&B ou instances auto-hébergées

Le plugin délègue la gestion du point de terminaison et de l’authentification au Weave Node SDK. Il lit les variables d’environnement suivantes, selon les mêmes conventions que les SDK Weave pour Python et Node :

Variable	Description
`WANDB_BASE_URL`	URL de base de l’API W&B. Par défaut : `https://api.wandb.ai`. Définissez cette variable pour les installations en Cloud dédié ou auto-hébergées.
`WF_TRACE_SERVER_URL`	Remplace l’URL complète du serveur de traces. À utiliser pour les configurations autogérées ou derrière un proxy.

Dépannage

Si les traces n’arrivent pas dans Weave ou si les champs de contenu sont vides, les sections suivantes vous aideront à diagnostiquer les causes les plus courantes. Le journal de la passerelle correspond à la sortie du terminal du processus qui exécute openclaw, ou au flux de journaux de votre gestionnaire de processus si vous l’avez lancé en tant que démon.

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

Exécutez /weave 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 weave: config.entity is required, weave: configuration error ou [weave] incompatible plugin SDK.
Assurez-vous de ne pas avoir défini diagnostics.enabled: false dans la configuration de la passerelle. Ce champ doit valoir true.
Vérifiez que l’entity et le projet correspondent au slug d’URL du projet Weave que vous examinez. /weave status doit afficher project=[YOUR-TEAM]/[YOUR-PROJECT].
Vérifiez la source d’authentification. /weave status doit afficher auth=.... S’il indique WANDB_API_KEY env alors que vous avez défini la clé dans une autre variable d’environnement, le plugin ne lit pas la bonne clé.

Les spans arrivent, mais le texte d’entrée/de sortie 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.weave.hooks.allowConversationAccess=true
[plugins] typed hook "llm_output" blocked ...
[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.weave.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 proviennent des événements de diagnostic, et non des hooks. Elles restent donc disponibles même lorsque allowConversationAccess vaut false.

Erreurs lors de l’envoi des traces vers Weave

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

Symptôme	Cause la plus probable	Solution
`401` ou `403` renvoyé par `trace.wandb.ai`	Clé API non valide ou de portée limitée	Vérifiez que la clé est à jour et que l’équipe est propriétaire de l’entity et du projet. `wandb login` actualise `~/.netrc`.
`404` renvoyé par le point de terminaison des agents	URL de base ou URL du serveur de traces incorrecte	Pour les installations en Cloud dédié, définissez `WANDB_BASE_URL` sur l’hôte de votre installation. Pour les installations autogérées ou derrière un proxy, définissez `WF_TRACE_SERVER_URL` sur l’URL du serveur de traces.
Connexion refusée ou erreur DNS	DNS, proxy ou pare-feu	Vérifiez que l’hôte de la passerelle peut atteindre `trace.wandb.ai` (cloud) ou l’hôte de votre installation (Cloud dédié) sur le port `443`.

​Prérequis

​Installer le plugin

​Afficher les traces OpenClaw dans Weave

​Référence de configuration

​Cloud dédié de W&B ou instances auto-hébergées

​Dépannage

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

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

​Erreurs lors de l’envoi des traces vers Weave