> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Plugin OpenClaw
> Suivez les sessions d’agent OpenClaw dans W&B Weave à des fins d’observabilité et de débogage.
export const AgentLensBanner = ({href}) =>
This workflow is also available in CoreWeave Agent Lens. Agent Lens is the Forge experience built for tracing, monitoring, and analyzing AI agents, with automated insights into agent failures and user intents. It uses the same trace data as Weights & Biases Weave, so the traces you already send appear there with nothing to migrate.{' '}
{href ? 'See how to do this in Agent Lens' : 'Learn about Agent Lens'}.
;
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](https://nodejs.org/) v22.14 ou version ultérieure.
* [OpenClaw](https://openclaw.ai) `2026.4.25` ou version ultérieure, avec l’API de plugins.
* Un compte CoreWeave Forge et une [clé API](https://forge.coreweave.com/settings#apikeys).
* 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.
```bash lines theme={"system"}
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.
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.
```json lines theme={"system"}
{
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é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 :
1. Accédez à [Forge](https://forge.coreweave.com/wandb) et sélectionnez votre projet.
2. Dans le menu latéral, sélectionnez **Agents**.
3. Sélectionnez l’onglet **Conversations** pour afficher toutes les conversations d’agent enregistrées dans votre projet.
4. Sélectionnez une conversation pour inspecter son arborescence complète.
Pour en savoir plus sur la vue Agents, consultez [Afficher l’activité des agents](/fr/products/wandb/weave/guides/tracking/view-agent-activity).
Le plugin émet des spans conformément aux [conventions sémantiques GenAI d’OpenTelemetry (OTel)](https://opentelemetry.io/docs/specs/semconv/gen-ai/) :
| Span | Émis | Attributs clés |
| - | - | - |
| `invoke_agent ` | À chaque run d’agent | `gen_ai.agent.name`, `gen_ai.conversation.id`, coût cumulé, utilisation des jetons |
| `chat ` | À chaque appel de modèle | `gen_ai.request.model`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens` |
| `execute_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 :
1. Un objet `SecretRef` avec `source: "env"` ou `source: "file"` (voir la ligne 10 de l’exemple ci-dessous).
2. Une chaîne `apiKey` littérale (prise en charge, mais déconseillée).
3. La variable d’environnement `WANDB_API_KEY`.
4. Une entrée `~/.netrc` pour l’hôte Weave, renseignée par `wandb login`.
```json lines theme={"system"}
{
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](https://github.com/wandb/weave/tree/master/sdks/node). 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
1. 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`.
2. Assurez-vous de ne pas avoir défini `diagnostics.enabled: false` dans la configuration de la passerelle. Ce champ doit valoir `true`.
3. 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]`.
4. 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 :
```text theme={"system"}
[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`. |