Skip to main content
Le plugin CoreWeave Forge pour Codex trace automatiquement les tours Codex et envoie les données structurées à Agent Lens. Chaque appel de modèle et chaque exécution d’outil sont journalisés, sans aucune modification de votre flux de travail Codex. Utilisez ces traces pour déboguer les sessions, auditer l’utilisation des outils et surveiller l’utilisation des jetons et la latence d’un run à l’autre. Le plugin lit les fichiers d’enregistrement de session générés par Codex (~/.codex/sessions/**/rollout-*.jsonl) pour reconstituer les spans. À la fin de chaque tour de conversation, un Stop hook lance un collecteur détaché : Codex n’attend donc jamais le réseau. Les tours d’une même session Codex partagent un identifiant de conversation, si bien qu’Agent Lens les affiche comme une seule conversation.
Par défaut, ce plugin capture le contenu des spans : vos prompts, les réponses et le raisonnement du modèle, les arguments des appels d’outils, les résultats d’outils et le répertoire de travail. Les résultats d’outils comprennent les commandes shell, la sortie des commandes et le contenu des fichiers. Ces données sont envoyées à votre instance Agent Lens.Le nettoyage des informations personnelles identifiables (PII) et le masquage des données sensibles ne sont pas pris en charge. Pour n’envoyer que la structure, l’utilisation des jetons, le modèle et les durées (sans prompts, code ni sortie), définissez FORGE_CODEX_INCLUDE_CONTENT=false. Voir Désactiver la capture du contenu. 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

  • macOS ou Linux. Windows n’est pas pris en charge.
  • Node.js v20.6 ou version ultérieure.
  • OpenAI Codex CLI, avec les hooks et la journalisation des enregistrements de session activés. codex --ephemeral n’est pas pris en charge, car cette commande n’écrit aucun fichier d’enregistrement de session.
  • Un compte CoreWeave Forge et une clé API Forge.
  • Un projet Agent Lens ([YOUR-TEAM]/[YOUR-PROJECT]) destiné à recevoir les traces.

​
Installer le plugin

1

Installer le paquet

Ce plugin est distinct du plugin weave-codex documenté dans le guide Weave. Son paquet est @coreweave/forge-agent-lens-for-codex, et sa commande, ses variables d’environnement et son répertoire de paramètres utilisent les noms forge-agent-lens-for-codex et FORGE_. Si vous avez installé weave-codex, exécutez weave-codex uninstall et npm uninstall -g weave-codex avant d’installer ce plugin, afin d’éviter que les deux n’envoient des traces en double. Attribuez à FORGE_TRACE_PROJECT la valeur que vous utilisiez pour WEAVE_PROJECT. Le plugin ne lit pas les paramètres de weave-codex.
2

Définir votre projet et votre clé API

Remplacez [YOUR-TEAM]/[YOUR-PROJECT] par votre projet Agent Lens et [YOUR-API-KEY] par votre clé API, puis exportez-les :
Vous pouvez également exécuter wandb login au lieu de définir WANDB_API_KEY. Pour savoir comment le plugin détermine la valeur de chaque paramètre, consultez la Référence de configuration.
3

Installer le Stop hook

Cette commande ajoute un Stop hook à ~/.codex/hooks.json et sauvegarde une seule fois le fichier original dans hooks.json.bak. Elle ignore également vos sessions Codex existantes : seuls les tours de conversation exécutés après l’installation sont envoyés à Agent Lens. Pour envoyer délibérément cet historique, consultez Collecter les sessions passées.
4

Approuver le hook dans Codex

Codex n’exécute pas les hooks nouvellement ajoutés tant que vous ne les avez pas approuvés :
  1. Ouvrez un terminal et exécutez :
  2. Dans l’écran interactif de Codex, et non dans votre shell, saisissez :
  3. Sous Stop Events, sélectionnez le hook Forge Agent Lens, puis activez-le ou marquez-le comme approuvé.
Pour une exécution d’automatisation ponctuelle, Codex prend également en charge l’option --dangerously-bypass-hook-trust.Exécutez forge-agent-lens-for-codex status pour vérifier que le hook est installé et que le plugin est ready.
Vous pouvez désormais utiliser Codex normalement : chaque tour de conversation terminé est envoyé à Agent Lens.

​
Afficher les traces Codex dans Agent Lens

Après avoir exécuté au moins une session Codex, ouvrez votre projet dans l’interface d’Agent Lens :
  1. 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.
  2. Dans le menu latéral, sélectionnez Conversations.
  3. Sélectionnez une conversation pour examiner la hiérarchie complète de ses tours de conversation.
Pour en savoir plus sur l’onglet Conversations, consultez Afficher l’activité des agents. Le plugin émet une trace OTEL par tour de conversation Codex, conformément aux conventions sémantiques GenAI : Les horodatages des spans proviennent du fichier d’enregistrement de session : les durées reflètent donc le temps d’exécution réel. Chaque tour de conversation n’est envoyé qu’une seule fois. En cas d’échec d’un export, le plugin renvoie ce tour au prochain déclenchement du Stop hook.

​
Limitations connues

  • Les commandes codex (TUI interactive) et codex exec sont prises en charge. En revanche, codex mcp, les sessions passant directement par le serveur d’application ou l’API, ainsi que les tours de conversation interrompus qui ne déclenchent aucun événement Stop ne sont pas couverts.
  • Un sous-agent lancé n’apparaît que sous forme de span d’outil. Son fichier d’enregistrement de session distinct n’est pas reconstitué en trace imbriquée ; ses propres appels au modèle et exécutions d’outils ne sont donc pas capturés.
  • Certains environnements codex exec n’exécutent pas le Stop hook. Voir Headless runs and explicit collection dans le README du plugin.

​
Référence de configuration

Cette section répertorie les paramètres disponibles pour personnaliser le comportement du plugin. L’état, les paramètres et le fichier journal se trouvent dans ~/.forge-agent-lens-for-codex/, notamment settings.json et logs/collector.log. Ne définissez FORGE_CODEX_HOME que pour des environnements de développement ou de test isolés. Définissez FORGE_CODEX_PROVIDER_NAME si Codex envoie les requêtes via un proxy ou une passerelle vers un autre fournisseur de modèles. Le plugin enregistre cette valeur dans les spans de modèle.

​
Ordre de résolution des identifiants

Le plugin n’écrit jamais votre clé API dans settings.json. Il recherche une clé dans l’ordre suivant :
  1. La variable d’environnement WANDB_API_KEY.
  2. L’entrée ~/.netrc pour api.wandb.ai, ou pour l’hôte défini dans WANDB_BASE_URL si vous avez défini cette variable.
Pour le projet et les autres paramètres, une variable d’environnement est prioritaire sur settings.json, lui-même prioritaire sur la valeur par défaut. Le SDK Forge détermine le trace server et le transport. Pour un déploiement personnalisé, définissez WANDB_BASE_URL, ou définissez WF_TRACE_SERVER_URL pour remplacer explicitement le trace server.

​
Désactiver la capture du contenu

Définissez FORGE_CODEX_INCLUDE_CONTENT=false pour omettre les prompts, la sortie de l’assistant, le raisonnement, les arguments et résultats des outils, ainsi que le répertoire de travail. Les spans conservent les noms de modèles, l’utilisation des jetons, les durées, les noms d’outils, les ID d’appel et les noms des serveurs MCP. Pour la collecte interactive via le Stop hook, définissez plutôt include_content sur false dans ~/.forge-agent-lens-for-codex/settings.json. Une variable définie uniquement sur la commande codex risque de ne pas être transmise aux hooks exécutés par un serveur d’application Codex déjà en cours d’exécution ; le paramètre défini dans le fichier est donc la méthode fiable. L’environnement du processus du hook est prioritaire sur le fichier de paramètres : assurez-vous donc que cet environnement ne définit pas FORGE_CODEX_INCLUDE_CONTENT=true. Si cette variable n’est pas définie, le plugin utilise la valeur de settings.json. La variable d’environnement est fiable pour les exécutions explicites de forge-agent-lens-for-codex collect.

​
Collecter les sessions passées

collect --all effectue un import rétroactif explicite. Cette commande envoie, depuis chaque enregistrement de session, les tours qui n’ont pas encore été exportés. Un enregistrement de session sans curseur est lu depuis le début. Cette commande peut donc envoyer un historique antérieur à l’installation du plugin :
Ajoutez --json pour envoyer les résultats au format JSON.

​
Vérifier le statut du plugin

Vous pouvez utiliser cette commande pour vérifier le statut du plugin ou diagnostiquer des problèmes :
La sortie affiche la version du plugin, l’état d’installation du hook, le projet résolu, si une clé API a été résolue, le fournisseur, les paramètres de contenu et de débogage, le chemin du fichier journal, le nombre de fichiers d’enregistrement de session trouvés, ainsi que le statut. La commande n’affiche jamais votre clé API. Ajoutez --json pour obtenir le même rapport au format JSON. Si les tours de conversation n’apparaissent pas dans Agent Lens, consultez le journal du collecteur :

​
Dépannage

Les sections suivantes décrivent les problèmes courants et la manière de les résoudre. Le journal du collecteur, situé dans ~/.forge-agent-lens-for-codex/logs/collector.log, constitue la principale source de diagnostic. Le plugin journalise toujours les erreurs, quelle que soit la valeur du paramètre debug.

​
Aucune trace n’apparaît après l’exécution de Codex

  1. Exécutez forge-agent-lens-for-codex status. Si la dernière ligne indique not ready, corrigez le problème signalé.
  2. Vérifiez que le hook est installé et activé. Si vous avez ignoré l’approbation, exécutez codex, puis /hooks, et activez le hook.
  3. Vérifiez que FORGE_TRACE_PROJECT est défini sur un slug entity/project valide, contenant exactement un /. status affiche le projet résolu.
  4. Vérifiez qu’une clé API a bien été résolue. status indique si c’est le cas, mais pas d’où provient la clé. Si le plugin lit la mauvaise clé, vérifiez WANDB_API_KEY et ~/.netrc.
  5. Vérifiez que Codex ne s’exécute pas avec --ephemeral. Cette option empêche la création du fichier d’enregistrement de session que lit le plugin.
  6. Si vous avez mis à niveau le paquet ou changé de version de Node.js, exécutez de nouveau forge-agent-lens-for-codex install. Le hook conserve les chemins de Node.js et du paquet en vigueur lors de son installation.

​
Les tours de conversation s’affichent, mais le texte d’entrée et de sortie est vide

La capture du contenu est peut-être désactivée. Vérifiez que FORGE_CODEX_INCLUDE_CONTENT n’est pas défini sur false et que include_content n’est pas défini sur false dans ~/.forge-agent-lens-for-codex/settings.json. La commande status affiche la valeur résolue de include content.

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

Si le plugin est actif et génère des spans qui n’apparaissent pas dans Agent Lens, recherchez une erreur d’exportation dans le journal du collecteur et reportez-vous au tableau ci-dessous.

​
Mettre à niveau le plugin

Le hook enregistre les chemins de Node.js et du paquet utilisés lors de son installation. Pour effectuer une mise à niveau, ou après avoir changé de version de Node.js, réinstallez le paquet et exécutez à nouveau install :

​
Désinstallation

Pour arrêter le traçage automatique et supprimer le handler du Stop hook de Codex :
Ensuite, pour désinstaller le paquet, exécutez :
Dernière modification le 23 octobre 2026