Passer au contenu principal
Weave for Agents est en préversion publique. Les fonctionnalités, les API et l’interface utilisateur de la vue Agents peuvent encore évoluer avant la disponibilité générale.
Le plugin Weave OpenClaw trace automatiquement chaque session d’agent exécutée via 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 nécessiter de 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 sur l’ensemble des exécutions. Ce guide s’adresse aux opérateurs de la passerelle OpenClaw qui souhaitent activer le traçage Weave pour les agents exécutés derrière la passerelle. Il vous explique comment installer le plugin, le configurer, afficher les traces obtenues et résoudre les problèmes courants.
Ce plugin envoie les données de session OpenClaw à Weave. Ces données peuvent inclure des prompts utilisateur, 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 n’implémente ni le masquage des informations personnelles identifiables (PII), ni celui des données sensibles. Si vous devez empêcher la capture du contenu, définissez captureContent: false dans la configuration du plugin. Si vous ne pouvez pas envoyer ces données à Weave au regard de vos exigences de sécurité ou de conformité, 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 plugin.
  • Un compte W&B et une clé API.
  • Un projet Weave ([YOUR-TEAM]/[YOUR-PROJECT]) pour recevoir des traces.

​
Installer le plugin

Suivez les étapes ci-dessous pour installer le plugin, l’enregistrer auprès de la passerelle OpenClaw et confirmer que les traces arrivent dans votre projet Weave.
1

Installer le package

openclaw plugins install weave-openclaw
Utilisez le nom complet weave-openclaw (weave seul correspond au SDK W&B, pas à ce plugin). La passerelle OpenClaw charge le plugin via sa configuration. Vous ne l’importez pas dans le code de l’application.
2

Ajouter le plugin à la configuration de votre passerelle

L’emplacement de configuration par défaut est ~/.openclaw/openclaw.json (JSON5, qui autorise les commentaires et les virgules finales). Exécutez openclaw onboard pour en générer le squelette si vous n’en avez pas encore. 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 avec contenu (llm_input, llm_output, agent_end) et que les spans incluent le texte d’entrée et de sortie, les arguments des outils et les résultats des outils.diagnostics.enabled est activé par défaut. Définissez-le explicitement uniquement si vous devez le désactiver.
3

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 confirmer que le plugin est actif. Les traces apparaissent dans https://wandb.ai/[YOUR-TEAM]/[YOUR-PROJECT] quelques secondes après la première exécution de votre agent.

​
Afficher les traces OpenClaw dans Weave

Une fois le plugin activé, chaque session d’agent produit une trace que vous pouvez examiner dans l’interface Weave. Après avoir exécuté au moins une session d’agent, ouvrez votre projet dans l’interface Weave :
  1. Accédez à https://wandb.ai et sélectionnez votre projet.
  2. Dans la barre latérale, sélectionnez Agents pour la vue de conversation multi-tour et le regroupement par version d’agent, ou sélectionnez Traces pour l’arborescence brute des spans.
  3. Sélectionnez une conversation pour examiner l’arborescence complète de la session.
Pour plus d’informations sur la vue Agents, voir Afficher l’activité de l’agent. Le plugin émet des spans conformément aux conventions sémantiques OpenTelemetry (OTel) GenAI :
SpanÉmis pourAttributs clés
invoke_agent <agent>Pour chaque exécution d’agentgen_ai.agent.name, gen_ai.conversation.id, coût cumulé, utilisation des jetons
chat <model>Pour chaque appel au modèlegen_ai.request.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens
execute_tool <tool>Pour chaque exécution d’outilgen_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 weave dans openclaw.json. Le champ apiKey prend en charge quatre sources d’authentification, résolues dans cet ordre :
  1. Un objet SecretRef avec source: "env" ou source: "file" (voir la ligne 10 dans l’exemple suivant).
  2. Une chaîne littérale apiKey (prise en charge, mais non recommandée).
  3. La variable d’environnement WANDB_API_KEY.
  4. 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",
          // Reads WANDB_API_KEY from env if apiKey is omitted.
          // SecretRef supports source: "env" or "file":
          //   { source: "env",  provider: "default", id: "WANDB_API_KEY" }
          //   { source: "file", provider: "default", id: "/run/secrets/wandb" }
          // Plain string is supported but discouraged.
          apiKey: { source: "env", provider: "default", id: "WANDB_API_KEY" },
          serviceName: "openclaw-agent",
          // Optional, improves Agents tab grouping.
          agentName: "my-agent",
          agentVersion: "v1.0",
          agentDescription: "What my agent does.",
          // ON by default. Set to false for a hard off (compliance or
          // retention policy). The plugin does not redact captured
          // strings; scrub upstream if needed.
          captureContent: true,
          flushIntervalMs: 1000,
        },
        hooks: { allowConversationAccess: true },
      },
    },
  },
}
captureContent est défini sur true par défaut. Lorsque captureContent est true, le plugin émet également les messages d’entrée et de sortie, les arguments des outils et les résultats des outils selon le format de charge utile gen_ai.input.messages et gen_ai.output.messages. Le plugin consigne les sous-agents, les événements de compactage, la détection de boucle, les tentatives de réessai 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 afin de respecter les politiques de conformité ou de conservation.

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

Le plugin délègue le point de terminaison et l’authentification au SDK Node de Weave. Il lit les variables d’environnement suivantes selon les mêmes conventions que les SDK Python et Node de Weave :
VariableDescription
WANDB_BASE_URLURL 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_URLRemplacement complet de l’URL du serveur de traces. À utiliser pour les configurations autogérées ou derrière un proxy.

​
Dépannage

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

​
Le plugin est chargé, mais aucun span ne s’affiche

  1. Exécutez /weave status. Si le cycle de vie est disabled, config-error ou not-started, le plugin ne s’est pas activé. Vérifiez le journal de la passerelle pour y trouver weave: config.entity is required, weave: configuration error ou [weave] incompatible plugin SDK.
  2. Vérifiez que vous n’avez pas défini diagnostics.enabled: false dans la configuration de la passerelle. Ce champ doit être défini sur true.
  3. Vérifiez que l’entité et le projet correspondent au slug de l’URL du projet Weave que vous inspectez. /weave status doit afficher project=[YOUR-TEAM]/[YOUR-PROJECT].
  4. Vérifiez la source d’authentification. /weave status doit afficher auth=.... Si WANDB_API_KEY env s’affiche 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 et de sortie est vide

Recherchez 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 soumet les hooks qui donnent accès au 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 transitent via des événements de diagnostic, et non via des hooks ; elles continuent donc de fonctionner même lorsque allowConversationAccess est défini sur false.

​
Erreurs lors de l’envoi de traces vers Weave

Si le plugin est actif et génère des spans mais qu’ils n’apparaissent pas dans Weave, consultez les journaux de la passerelle pour repérer une erreur d’exportation et comparez-la au tableau suivant.
SymptômeCause la plus probableCorrectif
401 ou 403 depuis trace.wandb.aiClé API invalide ou à portée limitéeVérifiez que la clé est toujours valide et que l’équipe est propriétaire de l’entité et du project. wandb login actualise ~/.netrc.
404 depuis le point de terminaison des agentsURL de base ou URL du serveur de traces incorrectePour les installations dédiées, définissez WANDB_BASE_URL sur l’hôte de votre installation. Pour une installation autogérée ou derrière un proxy, définissez WF_TRACE_SERVER_URL sur l’URL du serveur de traces.
Connexion refusée ou erreur DNSDNS, proxy ou pare-feuVérifiez que l’hôte de la passerelle peut joindre trace.wandb.ai (cloud) ou l’hôte de votre installation (dédiée) sur le port 443.