---
title: "使用 Braintrust 追踪 Codex 会话"
summary: "通过 bt trace enable codex 安装追踪插件并指定项目。新会话中确认 Braintrust 钩子权限，MCP 查询服务单独配置。"
category: hooks
level: starter
surfaces: [cli, app, ide]
tags: ["Braintrust", "hooks", "plugins", "MCP"]
canonical: /tips/braintrust-trace-codex-plugin/
---

# 使用 Braintrust 追踪 Codex 会话

通过 bt trace enable codex 安装追踪插件并指定项目。新会话中确认 Braintrust 钩子权限，MCP 查询服务单独配置。

Braintrust 用 bt trace enable codex 装 trace-codex@braintrust-codex-plugins。官方 Codex 页把会话追踪和 MCP 拆开：追踪靠 `bt` 写 `~/.codex/braintrust.json` 并装插件；查实验、日志走远程 MCP。不要把旧文档里的 `TRACE_TO_BRAINTRUST=true` 当现行安装器，也不要和 ModelTrace Guard 那条 `/hooks` 插件混用。

先在普通终端装 Codex CLI，并装好 `bt`（追踪要 **v0.16.0+**）。登录用 `bt login`，再设组织/项目上下文。Windows 上追踪钩子仍要 Bash。然后：

```bash
bt trace enable codex --project my-project
codex plugin list --json
bt trace doctor codex
```

`bt trace setup` 只是 `enable` 的旧别名。这条命令会刷新 marketplace `braintrustdata/braintrust-codex-plugin`，装上并启用 `trace-codex@braintrust-codex-plugins`，再写下追踪文件。文件里是路由和是否开启，**不是**密钥；鉴权归 `bt`。清单名是 `braintrust-codex-plugins`。只想手装插件、不配追踪时才：

```bash
codex plugin marketplace add braintrustdata/braintrust-codex-plugin
codex plugin add trace-codex@braintrust-codex-plugins
```

手装**不会**写 `braintrust.json`，普通会话仍不会出日志。改项目、profile、组织请再跑 `bt trace enable`，`bt switch` **不会**改这份追踪文件。只升级插件、不动路由用 `bt trace update codex`。关掉追踪用 `bt trace disable codex`，凭据还在。

装完**新开会话**。打开 `/hooks`，审查并确认 Braintrust 的钩子定义；不要一键信全部钩子。插件钩子把事件交给 `bt trace hook --source codex`，失败是 fail-open，不会打断这一轮。单次覆盖用 `bt trace run --project my-project -- codex …`；这条**拒绝** `--dangerously-bypass-hook-trust`。无头自动化真要绕过钩子信任时，直接跑已装插件的 `codex`，而且你必须信当前启用的**每一条**钩子。

MCP 是另一条路，marketplace **不会**登记它。官方现行是：

```bash
codex mcp add braintrust --url https://api.braintrust.dev/mcp
codex mcp login braintrust
```

```toml
[mcp_servers.braintrust]
url = "https://api.braintrust.dev/mcp"
enabled = true
```

用户层表名官方就是 `braintrust`。这是 Streamable HTTP。先走 OAuth（`mcp login` 和 `bt login` 不是同一套）。以前写过 `bearer_token_env_var = "BRAINTRUST_API_KEY"` 就先删掉再切 OAuth，避免重复配置。EU 换 `https://api-eu.braintrust.dev/mcp`，不要加尾斜杠。若 `codex plugin list --json` 里还有退役的 `braintrust@braintrust-codex-plugins`，先 `codex plugin remove braintrust@braintrust-codex-plugins`；留下 marketplace，追踪插件还要用。

配置说明：

- 不要把 `TRACE_TO_BRAINTRUST`、`BRAINTRUST_PROJECT` 当成现行普通会话的开关。v1.0.1 起读 `~/.codex/braintrust.json`。
- 即使改了 `CODEX_HOME`，追踪文件仍在 `~/.codex/braintrust.json`。

0.154 起先看**当前会话**；当前会话没有再新开。网页 Cloud 不读你该服务插件缓存。不要 `required = true`。不要一上来 `--yolo`。写实验、改数据集保持批准。

## 来源

- [Braintrust · Codex](https://www.braintrust.dev/docs/integrations/developer-tools/codex)
- [braintrustdata/braintrust-codex-plugin](https://github.com/braintrustdata/braintrust-codex-plugin)
- [Braintrust · bt trace](https://www.braintrust.dev/docs/reference/cli/trace)