> ## 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 Agent Lens à des fins d’observabilité et de débogage.
Le plugin Weave 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.
Il s’agit d’un plugin Weights & Biases Weave. Aucune version CoreWeave Forge n’est encore disponible. Les traces envoyées par le plugin apparaissent dans Agent Lens, car Agent Lens et Weave partagent les mêmes données de trace.
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](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 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 arrivent bien dans votre projet Agent Lens.
```bash lines theme={"system"}
openclaw plugins install weave-openclaw
```
Utilisez le nom complet `weave-openclaw` (`weave` seul désigne le SDK Weave, 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`** pour qu’OpenClaw exécute les hooks qui transmettent du 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 leurs résultats.
`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 sur `https://forge.coreweave.com/agent-lens/[YOUR-TEAM]/[YOUR-PROJECT]` quelques secondes après le premier run d’agent.
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 :
1. Accédez à [CoreWeave Forge](https://forge.coreweave.com), 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.
2. Dans le menu latéral, sélectionnez **Conversations**.
3. Sélectionnez l’onglet **Conversations** pour afficher toutes les conversations d’agent enregistrées dans votre projet.
4. Sélectionnez une conversation pour examiner son arborescence complète.
Pour plus d’informations sur l’onglet Conversations, consultez [Afficher l’activité des agents](/fr/products/agent-lens/conversations/view-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 pour | 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 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 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 Agent Lens, renseignée par `wandb login`.
```json lines theme={"system"}
{
plugins: {
entries: {
weave: {
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" 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 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,
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
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 être à `true`.
3. Vérifiez que l’entity et le projet correspondent au slug d’URL du projet Agent Lens que vous consultez. `/weave status` doit afficher `project=[YOUR-TEAM]/[YOUR-PROJECT]`.
4. Vérifiez la source d’authentification. `/weave 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/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 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 traces 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` 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 bien propriétaire de l’entity et du 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 `trace.wandb.ai` sur le port `443`. |