追踪 OpenAI Codex 会话 - 以编程方式使用文档

该 langsmith-codex-plugins 市场提供了一个追踪插件，可发送 OpenAI Codex 会话数据至 LangSmith。使用它检查代理轮次、模型元数据、令牌使用量、工具调用以及 Codex 工作流中的子代理线程。

前提条件

在设置追踪前，请确保您已具备：

- Codex CLI v0.128 或更高版本。
- A LangSmith API 密钥.

安装并启用插件

使用 Codex CLI 添加市场：

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

在 ~/.codex/config.toml中全局启用插件钩子和追踪插件，或仅在特定项目中启用 .codex/config.toml:

[features]
plugin_hooks = true

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

配置追踪

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

环境变量

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

变量	必填	默认	描述
`TRACE_TO_LANGSMITH`	是	-	设为 `"true"` 以启用追踪。
`LANGSMITH_CODEX_API_KEY`	条件性	-	LangSmith API 密钥。回退到 `LANGSMITH_API_KEY`。除非每个副本都提供自己的 API 密钥，否则必填。
`LANGSMITH_CODEX_ENDPOINT`	No	`https://api.smith.langchain.com`	LangSmith API URL。回退到 `LANGSMITH_ENDPOINT`.
`LANGSMITH_CODEX_PROJECT`	No	`codex`	LangSmith 项目名称。回退到 `LANGSMITH_PROJECT`.
`LANGSMITH_CODEX_METADATA`	否	-	合并到根追踪元数据的 JSON 对象。回退到 `LANGSMITH_METADATA`.
`LANGSMITH_CODEX_RUNS_ENDPOINTS`	否	-	副本目标的 JSON 数组。回退到 `LANGSMITH_RUNS_ENDPOINTS`.

将变量添加到您的 shell 配置文件（~/.zshrc, ~/.bashrc, or ~/.bash_profile):

配置文件

使用 <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 目的地。

将包含 API 密钥的配置文件排除在版本控制之外。

追踪到多个目的地

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

追踪到多个副本适用于：

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

Config file (recommended)

In <project>/.codex/langsmith.json or ~/.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" } }
    }
  ]
}

Shell environment variable

要生成转义的 JSON 字符串，请使用：

echo '[{"apiUrl":"...","apiKey":"...","projectName":"..."}]' | jq -c .

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

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

追踪内容

每次 LLM 运行包括：

输入：累积的对话消息。
输出：助手响应内容。
元数据：模型提供商、模型名称、停止原因和令牌使用情况。

工具调用（函数调用、Shell 调用、计算机调用、文件读取、网络搜索）会包含其输入和输出。子代理线程会被解析并作为嵌套子运行上传到父轮次下。

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

在 LangSmith 中查看追踪

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

故障排除

如果追踪未出现在 LangSmith 中：

- 确认 plugin_hooks = true 且追踪插件已在 config.toml.
- 中启用 TRACE_TO_LANGSMITH=true 对 Codex 进程可见。
- 确认 LANGSMITH_CODEX_API_KEY or LANGSMITH_API_KEY 已设置且有效。
- 如果运行进入了错误的项目，请设置 LANGSMITH_CODEX_PROJECT 或 project 配置键。
- 如果未使用自定义端点，请设置 LANGSMITH_CODEX_ENDPOINT 或 api_url 配置键。