---
title: "使用 W&B Weave 追踪 Codex 会话"
summary: "使用 weave-codex install 配置 Stop 钩子，WEAVE_PROJECT 指定 entity/project。默认采集提示词和命令输出，无头任务使用 weave-codex run。"
category: hooks
level: starter
surfaces: [cli, app]
tags: ["hooks", "Weave", "W&B", "observability"]
canonical: /tips/weave-codex-wandb-plugin/
---

# 使用 W&B Weave 追踪 Codex 会话

使用 weave-codex install 配置 Stop 钩子，WEAVE_PROJECT 指定 entity/project。默认采集提示词和命令输出，无头任务使用 weave-codex run。

W&B Weave 官方 Codex 追踪：npm i -g weave-codex，再 weave-codex install 写 Stop 钩子。这是把 Codex 会话追踪发送到 W&B Weave，不是去给 Python 脚本做 `weave.init()`，也不是 `codex plugin marketplace add`。官方集成页和 npm 包 `weave-codex` 都写了这条。本机要 Node.js 20+，并且 Codex 会写默认的 rollout（`~/.codex/sessions/**/rollout-*.jsonl`）。`--ephemeral` 关掉会话落盘，追踪也会没了。

```bash
npm install -g weave-codex
wandb login
export WEAVE_PROJECT="YOUR-TEAM/YOUR-PROJECT"
weave-codex install
weave-codex status
```

也可以 `export WANDB_API_KEY`，不必 `wandb login`。解析顺序是环境变量 → `~/.weave-codex/settings.json` → `~/.netrc`。`WEAVE_PROJECT` 必须是 `entity/project`，没有默认值。密钥必须在**启动 Codex 的那个进程**里；Codex **不**读 `.env`。**不要**把 `WANDB_API_KEY` 写进 `config.toml` 的 `env` 表。该服务也不是 MCP，**不要** `codex mcp login`。

`weave-codex install` 把 Stop 钩子合并进 `~/.codex/hooks.json`。回合结束时钩子在后台读新增的 rollout 行，再导出到 Weave，不挡 Codex 主路径。新开会话后若出现 Hooks need review，打开 `/hooks`，审过 **weave-codex** 再信任。Codex 按钩子哈希记信任；升级改了命令要再审一次。`weave-codex status` 显示已装不等于钩子已跑。

默认会采集 span 正文：prompt、模型回复和推理、工具参数、以及含 shell 命令、输出、文件内容的工具结果，并送到你的 Weave 实例。官方写明**没有** PII 清洗。只想要结构、token、模型和耗时时，设 `WEAVE_CODEX_CAPTURE_CONTENT=0`。含密钥或客户数据的会话不要开正文采集。

改完彻底重启 Codex，再新开一局。测的时候连发两条短消息：Stop 钩子上传已完成的回合，最新那一回合要等下一次钩子才收口。Weave 里打开项目的 Agents 视图（按 Codex session id 合成一轮对话），或看 Traces 里的 span 树。根 span 是 `invoke_agent codex`。

交互 TUI 和 `codex exec` 官方都支持，但部分无头 / CI 环境 Stop 钩子根本不跑。这时不要干等钩子，扫 rollout：

```bash
weave-codex collect --all
weave-codex run -- codex exec "fix the failing test"
```

`collect` 按会话游标幂等，已经导出的回合会跳过。`weave-codex run` 会继承 stdio、用子进程退出码，报告打到 stderr，好让 `codex exec --json` 的 stdout 干净。`codex mcp` 和 `app-server` 官方写明不覆盖。子代理目前只看得到 `spawn_agent` 那次工具调用。打断或失败的回合 Stop 不跑，也就没有追踪。排错看 `~/.weave-codex/logs/collector.log`，或 `weave-codex status --json`（不含密钥，只报 `apiKeyResolved`）。

企业开了 `allow_managed_hooks_only`、本机 `hooks.json` 加不进去时，官方回退是 `notify` 调 `~/.weave-codex/stop-hook.sh`，不是再抄一份用户钩子。自建 / Dedicated Cloud 才设 `WANDB_BASE_URL`。卸装只删自己的钩子条目：

```bash
weave-codex uninstall
```

配置说明：

- 不要 `codex mcp add weave`，也不要 `mcp login`。
- 不要一上来 `bypass_hook_trust = true`。先走 `/hooks` 审查。
- 不要把 `WANDB_API_KEY` 写进仓库或 `config.toml`。
- 不要一上来 `--yolo`。
- 不要用 `--ephemeral` 还指望出追踪。

网页 Cloud 不读这份本机 `hooks.json`。改完用 `weave-codex status` 核对项目名和钩子状态。

## 来源

- [W&B Weave · Codex plugin](https://docs.wandb.ai/weave/guides/integrations/agents/codex-harness)
- [npm · weave-codex](https://www.npmjs.com/package/weave-codex)
- [W&B Weave · Choose an agent integration](https://docs.wandb.ai/weave/agent-integration-quickstart)