跳到主要内容

追踪 Codex CLI

Codex CLI Tracing via the notify hook

MLflow Tracing 为 OpenAI 基于终端的编码代理 Codex CLI 提供自动追踪功能。设置完成后，MLflow 将自动捕获 Codex 对话的追踪信息，包括：

  • 用户提示词 (User prompts) 和助手回复
  • 工具使用（Shell 命令、文件操作等）
  • Token 用量（输入、输出和总 Token 数）
  • 包含工作目录和用户信息在内的会话元数据

追踪信息在每次对话轮次结束后创建 — 无需等待会话结束。

设置​

要求​

  • 正在运行的 MLflow 跟踪服务器
  • 已安装 Codex CLI
  • Node.js 18+
  • @mlflow/codex npm 包

第 1 步：安装追踪插件​

bash
npm install -g @mlflow/codex

如果您不想进行全局安装，可以通过 npx 调用二进制文件（例如 npx @mlflow/codex setup）——以下所有操作方式相同。

第 2 步：运行设置命令​

运行 mlflow-codex setup 将启动一个交互式流程来设置追踪钩子 (hook)。

text
~/my-project $ mlflow-codex setup

Configure MLflow tracing for Codex CLI
? Where should MLflow tracing be installed?
  ● Project  ./.codex/  (default)
  ○ User  ~/.codex/

  ↑/↓ to move, enter to select

✓ Created /path/to/project/.codex/config.toml with notify hook

  MLflow tracking URI [https://:5000] https://:5000
  MLflow experiment ID [0] 1

✓ Wrote tracing config to /path/to/project/.codex/mlflow-tracing.json

Next steps
  1. Start the MLflow tracking server in a separate terminal:
       mlflow server --port 5000
  2. Launch codex — traces appear at https://:5000 after each turn.

传递 --non-interactive / -y 参数可跳过交互式流程并使用默认值。

警告

设置程序拒绝覆盖预先存在的 notify = ... 条目，因此您的 Codex 配置永远不会被破坏——如果已经注册了其他通知程序，请自行编辑 config.toml。

第 3 步：启动 MLflow 跟踪服务器​

必须运行 MLflow 服务器才能接收追踪信息。请在单独的终端中启动它：

bash
mlflow server --port 5000

第 4 步：正常使用 Codex​

bash
codex "help me refactor this function"

每次对话轮次完成后，追踪信息会在 https://:5000 可见。

注意

MLFLOW_TRACKING_URI 和 MLFLOW_EXPERIMENT_ID 环境变量（如果在启动 codex 的 Shell 中设置）将覆盖写入 mlflow-tracing.json 的值。这对于 CI 中的一次性覆盖，或在本地端点与 Databricks 端点之间切换时非常方便。

工作原理​

  1. config.toml 中的 notify 钩子在每次 Codex 对话轮次后触发
  2. Codex 将轮次数据（用户提示、助手响应）作为 JSON 参数传递
  3. 插件可选择读取会话记录（JSONL 回放文件），以获取更丰富的数据，如工具调用和 Token 使用情况
  4. MLflow 追踪将以 AGENT 根跨度 (root span) 以及 LLM/TOOL 子跨度创建

配置示例​

setup 命令会写入两个配置文件：

  • ./.codex/config.toml — 添加 notify = ["mlflow-codex", "notify-hook"]，以便 Codex 在每轮对话后调用该钩子。
  • ./.codex/mlflow-tracing.json — 持久化存储您的 MLflow 配置，以便钩子无需 Shell 导出即可运行。

如果您倾向于手动编辑，等效的条目如下：

config.toml
toml
notify = ["mlflow-codex", "notify-hook"]
mlflow-tracing.json
json
{
  "trackingUri": "https://:5000",
  "experimentId": "0"
}

通过环境变量进行的单次运行覆盖（优先级高于配置文件）

bash
MLFLOW_TRACKING_URI=databricks MLFLOW_EXPERIMENT_ID=123456789 codex "..."

OTLP 追踪（适用于运营监控）​

Codex CLI 还通过其 config.toml 支持原生的 OpenTelemetry 追踪

~/.codex/config.toml
toml
[otel]
exporter = { otlp-http = {
  endpoint = "https://:5000/v1/traces",
  protocol = "binary",
  headers = { "x-mlflow-experiment-id" = "0" }
}}
注意

Codex 的原生 OTLP 追踪捕获的是内部执行细节（WebSocket 连接、请求处理、工具调度），而不是清晰的对话流。对于包含提示词、响应和工具结果的用户级对话追踪，推荐使用上述的 notify 钩子方法。

OTLP 追踪可用于调试 Codex 内部组件或性能监控，并可与基于钩子的追踪结合使用。

Token 使用与成本​

MLflow 会自动跟踪 Codex 对话中每次 LLM 调用的 Token 使用情况。详见Token 使用与成本跟踪文档。

注意

成本是根据 API 定价计算的。如果您使用的是订阅计划而非按 API 调用付费，计算出的成本可能无法反映您的实际支出。

故障排除​

常见问题​

追踪未生效

  • 验证 notify = ["mlflow-codex", "notify-hook"] 条目是否存在于 ~/.codex/config.toml 中
  • 确认 mlflow-codex 位于 PATH 中：运行 which mlflow-codex（应在 npm install -g @mlflow/codex 后解析）
  • 确认 ~/.codex/mlflow-tracing.json 存在且包含有效的 trackingUri。如果文件缺失或过时，请重新运行 mlflow-codex setup。
  • 检查是否正在使用 Node.js 18+（fetch 支持所必需）
  • 检查 MLflow 跟踪服务器是否可访问

追踪丢失

  • 追踪信息是按对话轮次创建的，而不是按会话创建
  • 验证 MLflow 跟踪服务器是否可访问

禁用追踪​

从 ~/.codex/config.toml 中删除 notify 行。现有的追踪信息会被保留。