追踪 OpenAI Codex 会话

在 LangSmith 中捕获 OpenAI Codex agent 轮次、工具调用、模型元数据和子 agent 线程。

langsmith-codex-plugins 市场提供了一个追踪插件，可将 OpenAI Codex 会话数据发送到 LangSmith。使用它可以从 Codex 工作流中检查 agent 轮次、模型元数据、token 使用量、工具调用和子 agent 线程。

前置条件

在设置追踪之前，请确保你具备：

• Node.js 22.x 或更高版本。
• Codex CLI v0.153.4 或更高版本，并启用且信任同步 UserPromptSubmit 插件 hook。
• 一个 LangSmith API 密钥。

安装并启用插件

使用 Codex CLI 添加市场：

codex plugin marketplace add langchain-ai/langsmith-codex-plugins

在 ~/.codex/config.toml 中全局启用追踪插件，或仅在 .codex/config.toml 中为特定项目启用：

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

然后使用 /hooks 信任此插件的 hook，或在提示时在 Codex 的插件 UI 中信任。仅启用插件并不会信任其 hook。

配置追踪

在 TRACE_TO_LANGSMITH 为 "true" 或配置文件中 enabled 为 true 之前，追踪处于禁用状态。使用环境变量、JSON 配置文件或两者配置凭据。

环境变量

插件首先读取 Codex 特定变量，然后回退到通用 LangSmith SDK 变量。

变量	必填	默认值	描述
TRACE_TO_LANGSMITH	是	-	设置为 "true" 以启用追踪。
LANGSMITH_CODEX_API_KEY	条件	-	LangSmith API 密钥。回退到 LANGSMITH_API_KEY。除非每个副本都提供自己的 API 密钥，否则为必填。
LANGSMITH_CODEX_ENDPOINT	否	https://api.smith.langchain.com	LangSmith API URL。回退到 LANGSMITH_ENDPOINT。
LANGSMITH_CODEX_PROJECT	否	codex	LangSmith 项目名称。回退到 LANGSMITH_PROJECT。
LANGSMITH_CODEX_METADATA	否	-	合并到根追踪元数据的 JSON 对象。回退到 LANGSMITH_METADATA。
LANGSMITH_CODEX_RUNS_ENDPOINTS	否	-	副本目标的 JSON 数组。回退到 LANGSMITH_RUNS_ENDPOINTS。
LANGSMITH_CODEX_REDACT	否	true	设置为假值以禁用密钥脱敏。回退到 LANGSMITH_REDACT。
LANGSMITH_CODEX_REDACT_EXTRA	否	-	额外 { pattern, replace } 脱敏规则的 JSON 数组。回退到 LANGSMITH_REDACT_EXTRA。

将变量添加到 shell 配置文件（~/.zshrc、~/.bashrc 或 ~/.bash_profile）：

export TRACE_TO_LANGSMITH="true"
export LANGSMITH_CODEX_API_KEY="<your-langsmith-api-key>"
export LANGSMITH_CODEX_PROJECT="codex"

配置文件

使用 <project>/.codex/langsmith.json 进行项目级设置，或使用 ~/.codex/langsmith.json 进行全局默认设置。全局文件首先加载，项目文件覆盖它，而匹配的环境变量优先于两者。

{
  "enabled": true,
  "api_key": "<your-langsmith-api-key>",
  "api_url": "https://api.smith.langchain.com",
  "project": "codex",
  "metadata": {
    "team": "agents",
    "environment": "dev"
  }
}

字段	环境变量	默认值	描述
enabled	TRACE_TO_LANGSMITH	false	设置为 true 以启用追踪。
api_key	LANGSMITH_CODEX_API_KEY、LANGSMITH_API_KEY	-	LangSmith API 密钥。
api_url	LANGSMITH_CODEX_ENDPOINT、LANGSMITH_ENDPOINT	LangSmith 默认值	LangSmith API URL。
project	LANGSMITH_CODEX_PROJECT、LANGSMITH_PROJECT	codex	LangSmith 项目名称。
metadata	LANGSMITH_CODEX_METADATA、LANGSMITH_METADATA	-	合并到根追踪元数据的对象。
replicas	LANGSMITH_CODEX_RUNS_ENDPOINTS、LANGSMITH_RUNS_ENDPOINTS	-	要将追踪复制到的其他 LangSmith 目标。
redact	LANGSMITH_CODEX_REDACT、LANGSMITH_REDACT	true	设置为 false 以禁用密钥脱敏。
redact_extra_rules	LANGSMITH_CODEX_REDACT_EXTRA、LANGSMITH_REDACT_EXTRA	-	在内置规则之后应用的额外 { pattern, replace } 规则。

请勿将包含 API key 的配置文件纳入版本控制。

追踪到多个目标

在 langsmith.json 或 LANGSMITH_CODEX_RUNS_ENDPOINTS 中设置 replicas，以将相同的追踪数据发送到其他 LangSmith 工作区或项目。设置后，副本列表会覆盖其他客户端设置。

追踪到多个副本适用于：

• 将追踪同时发送到生产项目和暂存项目。
• 使用不同 API 密钥追踪到多个工作区。
• 向特定副本目标添加额外元数据。

在 <project>/.codex/langsmith.json 或 ~/.codex/langsmith.json 中：

{
  "enabled": true,
  "replicas": [
    {
      "apiUrl": "https://api.smith.langchain.com",
      "apiKey": "lsv2_pt_workspace_a",
      "projectName": "project-prod"
    },
    {
      "apiUrl": "https://api.smith.langchain.com",
      "apiKey": "lsv2_pt_workspace_b",
      "projectName": "project-staging",
      "updates": { "metadata": { "environment": "staging" } }
    }
  ]
}

每个副本对象支持以下字段：

字段	必填	描述
apiUrl	是	LangSmith API URL（通常为 https://api.smith.langchain.com）。
apiKey	是	目标工作区的 API 密钥。
projectName	是	目标工作区中的项目名称。
updates	否	可选的要覆盖复制运行的运行字段，例如额外元数据。

密钥脱敏

插件会在将检测到的密钥从运行输入、输出、错误和元数据上传到 LangSmith 之前对其进行脱敏。脱敏默认开启。

脱敏在上传前于你的机器上运行，因此未脱敏的内容永远不会到达 LangSmith。副本目标接收相同的脱敏负载。

检测涵盖提供程序 API 密钥前缀、JSON Web Token 和 PEM 私钥块。它还涵盖上下文形态，例如 API_KEY=<value>、Authorization header 以及嵌入 URL 的密码。每个匹配项都会替换为 [SECRET_DETECTED]。有关规则列表，请参阅从追踪中脱敏密钥。

脱敏匹配已知的凭据形态，因此请将其视为安全网而非保证。格式无法识别的凭据仍会到达 LangSmith，附件、运行名称和标签不会经过匿名器。已脱敏的追踪仍保留构建它时使用的提示、文件内容和工具结果，因此请限制谁可以读取追踪项目。

要关闭脱敏，请将 LANGSMITH_CODEX_REDACT 设置为 false、0、no 或 off，或在配置文件中设置 "redact": false。值会被修剪并以不区分大小写的方式比较。

要脱敏其他模式，请将 LANGSMITH_CODEX_REDACT_EXTRA 设置为 { "pattern": ..., "replace": ... } 规则的 JSON 数组，或在配置文件中设置 redact_extra_rules。每个 pattern 是正则表达式字符串，以全局且区分大小写的方式应用。replace 是可选的，默认回退为 [redacted]。额外规则在内置规则之后运行。

{
  "enabled": true,
  "project": "codex",
  "redact": true,
  "redact_extra_rules": [{ "pattern": "ACME-[A-Z0-9]{16}", "replace": "[REDACTED_ACME_KEY]" }]
}

将 redact_extra_rules 设置为 [] 可清除从较低优先级源继承的规则。在配置文件中，一个具有无效正则表达式的规则会丢弃该文件中的所有设置，因此在提交之前请验证这些模式。

由于项目级的 .codex/langsmith.json 或 langsmith-plugins.json 可以将 redact 设置为 false，因此在你无法控制的仓库中启用追踪之前，请检查这些文件。

追踪内容

每个 LLM 运行包括：

• 输入：累积的对话消息。
• 输出：assistant 响应内容。
• 元数据：模型提供程序、模型名称、停止原因和 token 使用量。

工具调用（函数调用、shell 调用、computer 调用、文件读取、Web 搜索）会连同其输入和输出一起包含。子 agent 线程会被解析并作为父轮次下的嵌套子运行上传。

用户在响应中途取消的中断轮次在会话完成后仍会上传。

在 LangSmith 中查看追踪

打开配置的 LangSmith 项目并完成一个 Codex 轮次。默认情况下，追踪会出现在 codex 项目中。插件会上传已完成的 Codex 转录数据，包括消息、工具调用输入和输出、模型元数据、token 使用量以及子 agent 线程结构。

WARNING

插件会将完整的 Codex 转录数据上传到 LangSmith。不要为包含你不想存储在 LangSmith 中的数据会话启用追踪。

故障排查

如果追踪未出现在 LangSmith 中：

• 确认追踪插件已在 config.toml 中启用，并且其 hook 已受信任（/hooks）。[features] hooks 默认开启，因此仅在你需要撤销本地覆盖时才设置它。
• 确认 TRACE_TO_LANGSMITH=true 对 Codex 进程可见。
• 确认 LANGSMITH_CODEX_API_KEY 或 LANGSMITH_API_KEY 已设置且有效。
• 如果运行落入错误项目，请设置 LANGSMITH_CODEX_PROJECT 或 project 配置键。
• 如果未使用自定义端点，请设置 LANGSMITH_CODEX_ENDPOINT 或 api_url 配置键。

---