---
title: "安装 LangSmith 追踪插件"
summary: "安装 tracing@langsmith-codex-plugins，使用 TRACE_TO_LANGSMITH 开启追踪。需要 Codex 0.153.4+，凭证使用 LANGSMITH_CODEX_API_KEY。"
category: hooks
level: starter
surfaces: [cli, app]
tags: ["plugins", "LangSmith", "hooks", "observability"]
canonical: /tips/langsmith-codex-tracing-plugin/
---

# 安装 LangSmith 追踪插件

安装 tracing@langsmith-codex-plugins，使用 TRACE_TO_LANGSMITH 开启追踪。需要 Codex 0.153.4+，凭证使用 LANGSMITH_CODEX_API_KEY。

LangSmith 官方 Codex 追踪：marketplace add langchain-ai/langsmith-codex-plugins，再 plugin add tracing@langsmith-codex-plugins。这是把 Codex 会话追踪发送到 LangSmith，不是去查 LangChain 文档，也不是去改 LangSmith 项目数据。官方集成页和仓库 README 都写了 marketplace；集成页只写 `enabled = true`，清单 `.agents/plugins/marketplace.json` 的 name 是 `langsmith-codex-plugins`，插件 name 是 `tracing`，所以现行 CLI 还要 `plugin add`。源是 `./plugins/tracing`。本机要 Node.js 22+。仓库要求 Codex **0.153.4** 以上，并且同步 `UserPromptSubmit` 钩子已启用且信任。

```bash
codex plugin marketplace add langchain-ai/langsmith-codex-plugins
codex plugin add tracing@langsmith-codex-plugins
codex plugin list
```

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

钩子要单独打开并信任。现行键是 `hooks`，**不要**抄集成页仍写着的 `plugin_hooks`（这面旗已经从 Codex 删掉）：

```toml
[features]
hooks = true

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

新开会话后若出现 Hooks need review，打开 `/hooks`，审过 LangSmith 的 **UserPromptSubmit**（以及配套 Stop）再信任。只开插件不够。Codex 按钩子哈希记信任；插件升级改了命令要再审一次。旧版只会 Stop 追踪，不够用。

追踪默认关。启动 Codex 的那个进程要看见 `TRACE_TO_LANGSMITH=true`（仓库解析还接受 `1` / `yes` / `on`，官方页示例用字符串 `true`），以及 `LANGSMITH_CODEX_API_KEY`（没有再退到 `LANGSMITH_API_KEY`）。可选 `LANGSMITH_CODEX_PROJECT`，默认项目名 `codex`；自建才设 `LANGSMITH_CODEX_ENDPOINT`。变量必须在启动 Codex 的 shell 里；Codex **不**读 `.env`。该服务插件不是 MCP，**不要** `codex mcp login`，也不要把 `lsv2_pt_…` 写进 `config.toml` 的 `env` 表。

也可以写 json。查找顺序（仓库 README，比文档页完整）：环境变量 → 项目 `.codex/langsmith.json` → 项目根 `langsmith-plugins.json` → 用户 `~/.codex/langsmith.json` → 家目录 `~/.langsmith-plugins.json`。仓库根一份裸 `langsmith.json` **不会**被读。json 里有 api_key，**不要提交**。

会话里静音上传，提交**普通消息**，不要加斜杠：

```text
langsmith-tracing:mute
```

恢复用 `langsmith-tracing:unmute`。TUI 会把未知斜杠当命令拦掉，所以 `/langsmith-tracing:mute` 无效。默认全量上传；长期只要结构、不要正文，设 `LANGSMITH_CODEX_DEFAULT_MUTED=true`。默认会在上传前脱敏；关掉才 `LANGSMITH_CODEX_REDACT=false`。含密钥或客户数据的会话不要开全量追踪。

改完彻底重启 Codex，再新开一局。测一条短 `codex exec`，到 LangSmith 的 `codex` 项目看回合。升级用清单名：

```bash
codex plugin marketplace upgrade langsmith-codex-plugins
codex plugin add tracing@langsmith-codex-plugins
```

这**不是** `langchain-ai/langchain-plugins` 里的 `langsmith-mcp`。对应的 Remote MCP 的 OAuth 和现行 Codex 不兼容，官方写明不要用。也不要手写 `https://api.smith.langchain.com/mcp`。

配置说明：

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

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

## 来源

- [LangSmith · Trace OpenAI Codex sessions](https://docs.langchain.com/langsmith/trace-with-codex)
- [langchain-ai/langsmith-codex-plugins](https://github.com/langchain-ai/langsmith-codex-plugins)
- [marketplace.json](https://github.com/langchain-ai/langsmith-codex-plugins/blob/main/.agents/plugins/marketplace.json)