> ## 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 Codex

> Tracez les sessions agentiques, les appels LLM et les exécutions d’outils de Codex dans Agent Lens.

Le plugin Weave pour Codex trace automatiquement chaque tour de conversation Codex et envoie les données structurées à Agent Lens. 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 les sessions, auditer l’utilisation des outils et surveiller le coût et la latence d’un run à l’autre.

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 hors du chemin critique de Codex, via un Stop hook de type « fire-and-forget » : Codex n’attend donc jamais le réseau.

<Note>
  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.
</Note>

<Warning>
  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 Agent Lens.

  Le nettoyage des données personnelles (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 `WEAVE_CODEX_CAPTURE_CONTENT=0`. 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.
</Warning>

<h2 id="prerequisites">
  Prérequis
</h2>

* [Node.js](https://nodejs.org/) v20 ou version ultérieure.
* [OpenAI Codex CLI](https://github.com/openai/codex) avec le système de hooks.
* Un compte CoreWeave Forge et une [clé API](https://forge.coreweave.com/settings#apikeys) définie dans la variable d’environnement `WANDB_API_KEY`.
* Un projet Agent Lens (`[YOUR-TEAM]/[YOUR-PROJECT]`) destiné à recevoir les traces.

<h2 id="install-the-plugin">
  Installer le plugin
</h2>

<Steps>
  <Step title="Installer le package">
    ```bash lines theme={"system"}
    npm install -g weave-codex
    ```
  </Step>

  <Step title="Définir les identifiants d’authentification et le projet">
    ```bash lines theme={"system"}
    wandb login
    export WEAVE_PROJECT="YOUR-TEAM/YOUR-PROJECT"
    ```

    Au lieu d’utiliser `wandb login`, vous pouvez aussi définir directement la variable d’environnement `WANDB_API_KEY`. Voir [Ordre de résolution des identifiants d’authentification](#credential-resolution-order) pour connaître l’ensemble des règles de priorité.
  </Step>

  <Step title="Installer le hook Stop">
    ```bash lines theme={"system"}
    weave-codex install
    ```

    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 de rollout à partir d’un curseur propre à chaque session, reconstruit les spans et les exporte vers Agent Lens.
  </Step>

  <Step title="Approuver le hook dans Codex">
    Codex considère les hooks nouvellement ajoutés comme non approuvés 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 également 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é.
  </Step>
</Steps>

Vous pouvez maintenant utiliser Codex normalement : chaque tour de conversation terminé apparaît dans Agent Lens en une seconde environ.

<h2 id="view-codex-traces-in-agent-lens">
  Afficher les traces Codex dans Agent Lens
</h2>

Après avoir exécuté au moins une session Codex, 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 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](/fr/products/agent-lens/conversations/view-activity).

Le plugin émet une trace OTEL par tour de conversation Codex, conformément aux [conventions sémantiques GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/) :

| Span | Émis | Attributs clés |
| - | - | - |
| `invoke_agent codex` | À chaque tour de conversation (span racine) | Nom ou version de l’agent, `gen_ai.conversation.id`, modèle, utilisation cumulée des jetons, prompt de l’utilisateur et réponse finale (lorsque la capture du contenu est activée) |
| `chat <model>` | À chaque appel de modèle | `gen_ai.usage.*` (jetons d’entrée, de sortie, mis en cache et de raisonnement), motif de fin, `server.address`, sortie de l’assistant (lorsque la capture du contenu est activée) |
| `execute_tool <name>` | À chaque exécution d’outil | `gen_ai.tool.name`, `gen_ai.tool.call.id`, arguments et résultat (lorsque la capture du contenu est activée) ; les appels MCP comportent également `mcp.server.name` |

Dans l’onglet Conversations, Agent Lens regroupe les tours en une seule conversation à l’aide de `gen_ai.conversation.id`, dont la valeur correspond à l’ID de session Codex sur chaque span. Les horodatages des spans sont antidatés à partir de ceux du fichier de rollout : les durées reflètent donc le temps d’exécution réel.

Comme tous les attributs suivent les conventions sémantiques GenAI, les traces s’affichent également dans n’importe quel backend compatible OTEL.

<h3 id="known-limitations">
  Limitations connues
</h3>

* 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 subagent lancé n’apparaît que 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 terminés en erreur, qui ne sont donc pas capturés.

<h2 id="configuration-reference">
  Référence de configuration
</h2>

Cette section répertorie les paramètres que vous pouvez utiliser pour 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`.

| Paramètre | Variable d’environnement | Clé `settings.json` | Par défaut |
| - | - | - | - |
| Clé API Forge | `WANDB_API_KEY` | `wandb_api_key` | `~/.netrc` (via `wandb login`) |
| Projet Agent Lens | `WEAVE_PROJECT` | `weave_project` | Aucune (obligatoire, `entity/project`) |
| Capturer le contenu | `WEAVE_CODEX_CAPTURE_CONTENT` | `capture_content` | `true` |
| Journalisation de débogage | `WEAVE_CODEX_DEBUG` | `debug` | Désactivée (les erreurs sont toujours journalisées) |

<h3 id="credential-resolution-order">
  Ordre de résolution des identifiants d’authentification
</h3>

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 Agent Lens.

<h2 id="check-plugin-status">
  Vérifier le statut du plugin
</h2>

Vous pouvez utiliser ces commandes CLI pour vérifier le statut du plugin ou résoudre d'éventuels problèmes :

```bash lines theme={"system"}
weave-codex status
```

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 Agent Lens, consultez le journal du collecteur :

```bash lines theme={"system"}
cat ~/.weave-codex/logs/collector.log
```

<h2 id="troubleshooting">
  Dépannage
</h2>

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`.

<h3 id="no-traces-appear-after-running-codex">
  Aucune trace n’apparaît après l’exécution de Codex
</h3>

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é l’invite d’approbation lors du premier lancement, exécutez à 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 résolue des identifiants d’authentification. Si elle indique `WANDB_API_KEY env` alors que vous avez défini la clé ailleurs, le plugin lit une valeur erronée.

<h3 id="turns-appear-but-inputoutput-text-is-empty">
  Les tours de conversation s’affichent, mais le texte d’entrée et de sortie est vide
</h3>

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`.

<h3 id="errors-sending-traces-to-agent-lens">
  Erreurs lors de l’envoi des traces vers Agent Lens
</h3>

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.

| Symptôme | Cause la plus probable | Solution |
| - | - | - |
| Erreur 401 ou 403 renvoyée par `trace.wandb.ai` | Clé API non valide ou de portée limitée | Vérifiez que la clé est toujours valide et que l’équipe est propriétaire de l’entity et du projet. Contrôlez la source d’identifiants d’authentification résolue avec `weave-codex status`. |
| Connexion refusée ou erreur DNS | DNS, proxy ou pare-feu | Vérifiez que l’hôte peut joindre `trace.wandb.ai` sur le port 443. |

<h3 id="hook-locked-environments">
  Environnements aux hooks verrouillés
</h3>

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 :

```toml lines theme={"system"}
# ~/.codex/config.toml
notify = ["sh", "/Users/you/.weave-codex/stop-hook.sh"]
```

<h2 id="uninstall">
  Désinstallation
</h2>

```bash lines theme={"system"}
weave-codex uninstall
```

Cette opération supprime uniquement les entrées `weave-codex` du fichier `~/.codex/hooks.json`.