---
title: "使用 Langfuse 追踪 Codex 会话"
summary: "安装 tracing@codex-observability-plugin，通过 Stop 钩子采集会话。设置 TRACE_TO_LANGFUSE=true，凭证通过进程环境传入。"
category: hooks
level: starter
surfaces: [cli, app]
tags: ["plugins", "Langfuse", "hooks", "observability"]
canonical: /tips/langfuse-codex-observability-plugin/
---

# 使用 Langfuse 追踪 Codex 会话

安装 tracing@codex-observability-plugin，通过 Stop 钩子采集会话。设置 TRACE_TO_LANGFUSE=true，凭证通过进程环境传入。

Langfuse 官方 Codex 追踪：marketplace add langfuse/codex-observability-plugin，再 plugin add tracing@codex-observability-plugin。这是把 Codex 会话追踪发送到 Langfuse，不是去查文档、也不是去改 Langfuse 项目数据。官方集成页和仓库 README 都写了 marketplace；集成页把 `plugin add` 也写出来了，跟 `.agents/plugins/marketplace.json` 对得上。清单 name 是 `codex-observability-plugin`，展示名 Langfuse，插件 name 是 `tracing`，所以是 `tracing@codex-observability-plugin`。源是 npm 包 `@langfuse/codex-observability-plugin`，本机要 Node.js 22+ 且 `npm` 在 PATH 里。仓库 README 要求 Codex **0.143** 以上。

```bash
codex plugin marketplace add langfuse/codex-observability-plugin
codex plugin add tracing@codex-observability-plugin
codex plugin list
```

`codex plugin list` 应看到 `tracing@codex-observability-plugin` 为 installed, enabled。加完先看**当前会话**；当前会话 `/plugins` 没有再新开。IDE 扩展没有 `/plugins`，用 CLI 加。网页 Cloud 不读本机 marketplace。

钩子要单独打开并信任。现行键是 `hooks`，**不要**抄集成页仍写着的 `plugin_hooks`：

```toml
[features]
hooks = true

[plugins."tracing@codex-observability-plugin"]
enabled = true
```

新开会话后若出现 Hooks need review，打开 `/hooks`，审过 Langfuse 的 **Stop** 钩子再信任。Codex 按钩子哈希记信任；插件升级改了命令要再审一次。`plugin list` 显示已装不等于钩子已跑。成功时应能看到 `hook: Stop` 随后 `hook: Stop Completed`。

追踪默认关。必须让启动 Codex 的那个进程看见 `TRACE_TO_LANGFUSE=true`（就是这四个字母，不是 `1` / `yes`），以及 `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY`。可选 `LANGFUSE_BASE_URL`：欧盟默认 `https://cloud.langfuse.com`，美区 `https://us.cloud.langfuse.com`，日本 `jp`，HIPAA `hipaa`。同一组名也可加 `LANGFUSE_CODEX_` 前缀，只给 Codex 用。变量必须在启动 Codex 的 shell 里；Codex **不**读 `.env`。**不要**把 `sk-lf-…` 写进 `[mcp_servers]` 的 `env` 表，该服务插件也不是 MCP，**不要** `codex mcp login`。

也可以写 `~/.codex/langfuse.json`（项目层是仓库 `.codex/langfuse.json`）。解析顺序是默认值 → 全局 json → 项目 json → 环境变量，环境变量赢。json 里有 secret_key，**不要提交**。

改完彻底重启 Codex，再新开一局。测的时候连发两条短消息：Stop 钩子上传已完成的回合，最新那一回合要等下一次钩子才收口。Langfuse 里搜 `Codex Turn`。不要给含密钥、客户数据的会话打开追踪。可用 `LANGFUSE_CODEX_MAX_CHARS` 截断超长输入输出。默认失败敞开，上传出错不会卡住 Codex；排错才设 `LANGFUSE_CODEX_DEBUG=true`。

无头 `codex exec` 若要事先知道 trace id，才设 `LANGFUSE_CODEX_TRACE_SEED`（每趟唯一）。不要复用种子。升级：

```bash
codex plugin marketplace upgrade codex-observability-plugin
```

这**不是** `https://langfuse.com/api/mcp` 对应的无鉴权文档 MCP，也不是 `cloud.langfuse.com/api/public/mcp` 对应的产品 MCP。不要和那两张表写成一台。

配置说明：

- 不要抄集成页的 `plugin_hooks = true`。现行是 `hooks = true`。
- 不要 `codex mcp add langfuse-tracing`，也不要 `mcp login`。
- 不要把 `sk-lf-…` 写进 `config.toml` 的 `env` 表。
- 不要一上来 `--yolo`。

网页 Cloud 不读这份插件。改完用 `codex plugin list` 和 `codex features list` 核对 `hooks`。

## 来源

- [Langfuse · OpenAI Codex tracing](https://langfuse.com/integrations/developer-tools/codex)
- [langfuse/codex-observability-plugin](https://github.com/langfuse/codex-observability-plugin)
- [marketplace.json](https://github.com/langfuse/codex-observability-plugin/blob/main/.agents/plugins/marketplace.json)