Skip to main content
Le plugin Weave pour Codex trace automatiquement chaque tour de conversation Codex et envoie les données structurées vers W&B Weave. Chaque appel de modèle, chaque exécution d’outil et chaque étape de raisonnement sont journalisés, sans aucune modification de votre flux de travail Codex. Utilisez ces traces pour déboguer des sessions, auditer l’utilisation des outils et surveiller les coûts et la latence de vos runs. Le plugin lit les fichiers de session rollout générés par Codex (~/.codex/sessions/**/rollout-*.jsonl) pour reconstituer les spans. Il s’exécute entièrement en dehors du chemin critique de Codex grâce à un Stop hook de type « fire-and-forget », si bien que Codex n’attend jamais le réseau.
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 et les résultats des outils. Ces résultats comprennent les commandes shell, leur sortie et le contenu des fichiers. Ces données sont envoyées à votre instance Weave.Aucun nettoyage des données personnelles (PII) ni masquage des données sensibles n’est mis en œuvre. Pour n’envoyer que la structure, l’utilisation des jetons, le modèle et les durées (sans prompts, code ni sortie), définissez WEAVE_CODEX_CAPTURE_CONTENT=0. Si vos exigences de sécurité ou de conformité ne vous permettent pas d’envoyer ces données vers Weave, n’installez pas ce plugin.

​
Prérequis

  • Node.js v20 ou version ultérieure.
  • OpenAI Codex CLI avec son système de hooks.
  • Un compte CoreWeave Forge et une clé API définie dans la variable d’environnement WANDB_API_KEY.
  • Un projet Weave ([YOUR-TEAM]/[YOUR-PROJECT]) destiné à recevoir les traces.

​
Installer le plugin

1

Installer le package

2

Définir les identifiants d’authentification et le projet

Au lieu d’utiliser wandb login, vous pouvez aussi définir directement la variable d’environnement WANDB_API_KEY. Pour connaître l’ensemble des règles de priorité, consultez Ordre de résolution des identifiants d’authentification.
3

Installer le hook Stop

Cette commande ajoute un Stop hook au fichier ~/.codex/hooks.json. À la fin de chaque tour de conversation Codex, le hook lance un worker détaché qui lit les nouvelles lignes du rollout à partir d’un curseur propre à chaque session, reconstruit les spans et les exporte vers Weave.
4

Approuver le hook dans Codex

Codex considère les hooks nouvellement ajoutés comme non fiables et ne les exécute pas tant que vous ne les avez pas approuvés. Au prochain lancement de codex, approuvez le hook weave-codex lorsque vous y êtes invité.Vous pouvez aussi définir bypass_hook_trust = true dans ~/.codex/config.toml pour ignorer cette invite.Exécutez weave-codex status pour vérifier que tout est correctement configuré.
Vous pouvez désormais utiliser Codex normalement : chaque tour de conversation terminé apparaît dans Weave en une seconde environ.

​
Afficher les traces Codex dans Weave

Après avoir exécuté au moins une session Codex, ouvrez votre projet dans l’interface utilisateur de Weights & Biases :
  1. Accédez à Forge et sélectionnez votre projet.
  2. Dans la barre latérale, sélectionnez Agents pour afficher la vue de chat sur plusieurs tours de conversation et le regroupement par version d’agent, ou sélectionnez Traces pour afficher l’arborescence brute des spans.
  3. Sélectionnez une conversation pour examiner la hiérarchie complète des tours de conversation.
Pour en savoir plus sur la vue Agents, consultez Afficher l’activité des agents. Le plugin émet une trace OTEL par tour de conversation Codex, conformément aux conventions sémantiques GenAI : Dans la vue Agents, Weave regroupe les tours de conversation en une seule conversation à l’aide de gen_ai.conversation.id, qui correspond à l’ID de session Codex sur chaque span. Les horodatages des spans sont antidatés à partir de ceux du fichier de rollout, de sorte que les durées reflètent le temps d’exécution réel. Les traces s’affichent également dans n’importe quel backend compatible OTEL, puisque tous les attributs respectent les conventions sémantiques GenAI.

​
Limitations connues

  • Les commandes codex (TUI interactive) et codex exec sont prises en charge. Les commandes codex mcp et app-server ne sont pas couvertes, car elles ne déclenchent aucun hook.
  • Un sous-agent lancé apparaît uniquement sous la forme de son appel d’outil spawn_agent. Ses propres appels de modèle et exécutions d’outils ne sont pas capturés.
  • Le Stop hook ne se déclenche pas pour les tours de conversation interrompus ou ayant échoué ; ceux-ci ne sont donc pas capturés.

​
Référence de configuration

Cette section répertorie les paramètres permettant de personnaliser le comportement du plugin. Les fichiers de configuration et d’exécution sont stockés dans ~/.weave-codex/, notamment settings.json, le shim du hook, les curseurs par session et le fichier journal logs/collector.log.

​
Ordre de résolution des identifiants d’authentification

Le plugin résout les identifiants d’authentification dans l’ordre suivant :
  1. Variables d’environnement (WANDB_API_KEY, WEAVE_PROJECT).
  2. ~/.weave-codex/settings.json.
  3. Entrée du fichier ~/.netrc correspondant à l’hôte Weave.

​
Instances W&B en Cloud dédié ou autohébergées

Définissez WANDB_BASE_URL sur l’hôte de votre installation avant d’exécuter Codex :

​
Vérifier le statut du plugin

Vous pouvez utiliser les commandes CLI suivantes pour vérifier le statut du plugin ou résoudre d’éventuels problèmes :
Chaque ligne affiche ✓ (OK), ✗ (action requise) ou - (pas encore actif, sans que ce soit une erreur). Si les tours de conversation n’apparaissent pas dans Weave, 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 ~/.weave-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 weave-codex status. Vérifiez que tous les contrôles réussissent.
  2. Vérifiez que le hook est approuvé. Si vous avez ignoré la demande d’approbation lors du premier lancement, exécutez de nouveau codex et donnez votre approbation lorsque vous y êtes invité, ou définissez bypass_hook_trust = true dans ~/.codex/config.toml.
  3. Vérifiez que WEAVE_PROJECT est défini sur un slug entity/project valide. weave-codex status affiche le projet résolu.
  4. Vérifiez la source d’authentification. weave-codex status affiche la source d’identifiants d’authentification résolue. Si elle indique WANDB_API_KEY env alors que vous avez défini la clé ailleurs, le plugin lit une valeur incorrecte.

​
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 WEAVE_CODEX_CAPTURE_CONTENT n’est pas défini sur 0 et que capture_content n’est pas défini sur false dans ~/.weave-codex/settings.json.

​
Erreurs lors de l’envoi des traces vers Weave

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

​
Environnements à hooks verrouillés

Si allow_managed_hooks_only est défini dans votre configuration Codex, vous ne pouvez pas ajouter directement de hooks personnalisés. Utilisez plutôt le programme notify de Codex comme déclencheur de repli :

​
Désinstallation

Cette opération supprime uniquement les entrées weave-codex du fichier ~/.codex/hooks.json.
Dernière modification le 30 septembre 2026