From Black Box to Observability: Tracing OpenClaw with MLflow

从黑盒到可观测性：使用 MLflow 追踪 OpenClaw | MLflow

从黑盒到可观测性：使用 MLflow 追踪 OpenClaw

2026年5月6日

·

10分钟阅读

Yuki Watanabe

Databricks 软件工程师

OpenClaw 是一个开源的个人 AI 代理，可在您自己的设备上运行。您可以通过 WhatsApp、Telegram、Discord、Slack 或 20 多个消息渠道与它交流，它将代表您执行操作：处理电子邮件、跨 Notion 和 Things 3 管理任务、搜索网络、读写本地文件，并协调您构建的任何自定义技能。凭借 68,000+ 的 GitHub 星标和 ClawHub 上超过 5,400 个社区构建的技能，它迅速成为运行本地优先 AI 助理最受欢迎的方式之一。

挑战在于 OpenClaw 的强大功能来自于其自主性。它决定调用哪些工具、调用顺序，以及是否为子任务生成子代理。这使它具备能力，但也使其难以理解。当代理很好地处理请求时，您不知道原因；当处理得不好时，您不知道哪里出错了。您只能看到聊天中的最终消息。

本文将展示如何将 MLflow Tracing 添加到 OpenClaw，使每次代理运行都成为可完全检查的执行时间线。我们将逐步讲解设置过程，解释追踪捕获的内容，并通过具体示例展示追踪如何将模糊的怀疑转化为可操作的调试信息。

为什么追踪对个人代理很重要

您可能认为追踪仅适用于具有 SLA 和正常运行时间要求的生产系统。但个人代理也有自己版本的相同问题：您依赖代理为您完成实际工作，当它出错时，您需要了解发生了什么以便进行修复。

考虑一些没有追踪难以调试的场景。您要求 OpenClaw 代理总结本周的 AI 新闻并起草一份简报，但摘要内容浅显且遗漏了最重要的新闻。是网络搜索工具返回了差的结果？模型在总结时忽略了相关结果？还是达到了上下文窗口限制并静默丢弃了内容？您要求它根据日历重新安排会议，但它选择了错误的时间段。是日历工具返回了过时的数据？还是模型误解了您给出的约束条件？仅凭聊天回复您无法得知。

追踪记录了每次代理运行的完整执行路径：每个 LLM 调用的提示和响应、每个工具调用的参数和结果、每个子代理生成及其自身的嵌套步骤，以及所有内容的标记计数和时间戳。这些记录将调试从猜测转变为直接检查。您打开追踪记录，找到与预期偏离的步骤，现在您确切知道需要修复什么，无论是技能定义、工具配置，还是您提出请求的方式。

除了调试单次运行，追踪还成为系统性改进代理的基础。当您看到代理如何处理任务时，可以为其提供针对性反馈，优化其使用的技能，并验证您的更改是否真正生效。正是追踪使得这种反馈循环成为可能。

您的数据保留在本地

MLflow 在此处是一个理想选择的原因之一在于，它与 OpenClaw 共享相同的本地优先理念。MLflow 是 100% 开源的，由 Linux 基金会管理，并且完全支持自托管部署。当你在本地机器上运行 MLflow 服务器时，所有来自 OpenClaw 代理的追踪数据都会保留在你的基础设施内，绝不会外泄。没有任何遥测数据会被发送给第三方，也没有任何供应商能够访问你的提示内容或工具输出。对于一个负责处理你电子邮件、日历和文件的个人代理来说，这一点至关重要。

通过 AI 网关管理 LLM 访问

OpenClaw 会自主决定何时调用 LLM 以及调用哪些工具。这种自主性正是其设计初衷，但也意味着代理可以在你未参与的情况下发起大量 API 调用。如果你的 API 密钥存储在环境变量中或分散在各个配置文件中，它们会暴露给机器上的所有进程。如果某个技能触发了重试循环或生成了需要各自调用模型的子代理，成本可能会迅速累积，且没有统一的监控点。

MLflow AI 网关位于 OpenClaw 和你的 LLM 提供商之间，解决了这两个问题。你只需在网关中一次性存储 API 密钥，这些密钥会被加密且永远不会暴露给客户端代码。网关还为你提供了一个统一的位置来设置所有提供商的全局预算上限，无论调用的是哪个模型，失控的循环都无法悄无声息地累积成本。对于一个自主决定何时以及多频繁调用 LLM 的代理来说，这种防护机制非常有价值。

使用 OpenClaw 设置 MLflow 追踪

只需三个步骤即可开始使用。首先，安装 OpenClaw 的 MLflow 插件：

openclaw plugins install @mlflow/mlflow-openclaw

然后在本地启动 MLflow 服务器以接收追踪数据：

uvx mlflow server --port 5000

info

MLflow 支持多种部署方案，包括 Docker、Kubernetes 以及 Databricks 和 AWS SageMaker 等托管服务。有关更多细节，请参阅《设置 MLflow 服务器》。

接着使用内置的设置向导配置 MLflow 连接：

openclaw mlflow configure

向导会引导你交互式地设置追踪 URI 和实验 ID。如果你更倾向于手动设置，也可以使用环境变量：

export MLFLOW_TRACKING_URI=http://localhost:5000
export MLFLOW_EXPERIMENT_ID=<your-experiment-id>

完成这些操作后，像往常一样启动 OpenClaw 并正常使用即可。一旦启用集成，追踪将自动进行。每次代理运行都会生成一个追踪记录，并存储在你的 MLflow 服务器中。无需修改技能、工具定义或代理配置。

在浏览器中打开 http://localhost:5000，当你的 OpenClaw 代理运行时，你将看到追踪记录实时出现。

追踪记录的结构

每个 OpenClaw 代理运行都会生成一个分层跨度树。最顶层是代表整个运行过程的根代理跨度，从你的消息到达开始到代理发送回复结束。嵌套在其中的是代理执行的各个步骤，按类型进行组织。

LLM 跨度会捕获每次模型调用，包括发送给模型的完整提示、接收到的响应以及令牌计数（输入、输出、总计）。由于 OpenClaw 使用 ReAct 循环（模型进行推理、行动、观察并再次推理），单个用户请求可能生成多个 LLM 轮次。每个轮次都会作为独立的跨度显示，因此你可以逐步跟踪代理的推理过程。

工具跨度记录每次工具调用。您可以查看工具名称、模型选择传递的参数以及返回值或错误。当工具调用失败时，错误信息会直接记录在跨度中，立即可见。这对于OpenClaw丰富的工具生态系统尤其有用，因为单个请求可能涉及网络搜索、文件I/O、日历API和消息通道。

当OpenClaw创建子代理处理子任务时，会出现子代理跨度。每个子代理在跨度树中都有自己的分支，其中包含自己的LLM和工具跨度。即使代理将任务委托给其他代理，这种结构也能让您全面理解整个执行过程。

每个跨度都包含元数据，包括时间戳、持续时间和使用统计信息。最终形成一个完整、可检查的时间线，记录代理执行的所有操作。

使用仪表板监控趋势

当追踪数据开始流入MLflow后，操作仪表板将为您提供代理运行情况的全局视图。您可以查看各次运行的错误率、最常调用的工具以及随时间变化的令牌消耗趋势。如果在更新技能后代理开始更频繁地失败，或因新工具触发更长的推理链导致令牌使用量激增，仪表板会在您通过聊天注意到之前就提前显示这些异常。将其视为您个人代理的健康检查：一页即可告诉您系统是否运行顺畅，或是否需要关注某些问题。您还可以启用自动评估，对每条追踪数据进行评分，使代理运行过程中出现的异常行为能被自动标记。

从观察到改进

追踪数据对调试很有帮助，但其真正的价值在于在您与代理之间建立反馈循环。

当您查看追踪数据并注意到代理表现良好或存在不足时，可以在MLflow中将这些反馈记录为追踪或会话（共享对话ID的追踪组）的结构化注释。例如，对使用了错误工具的追踪数据添加差评注释，或在代理遗漏早期消息上下文的会话中添加备注。随着时间推移，这些数据会积累成一个标注数据集，记录代理正确和错误处理的案例。该数据集成为后续所有工作的基础：评估新技能版本、优化提示词、了解代理可靠处理的请求类型。

这里出现了更有趣的部分。您可以通过MLflow CLI和Skills直接向OpenClaw提供其自身的追踪数据和反馈。代理可以读取过去运行的追踪数据，查看哪些追踪收到了负面反馈，并利用这些信息优化自己的技能定义。您提供信号（追踪数据的反馈），代理则负责将这些信号转化为更优的行为。这就是追踪技术实现的自我改进循环：观察、标注，并让代理从自身历史中学习。

未来展望

追踪是基础，而非终点。一旦你获得可见性并建立起反馈习惯，下一步自然就是评估。为最关心的质量维度定义评分标准，并将其应用于收集到的追踪数据中。这些评分器将揭示你可能未手动注意到的模式：也许你的代理始终过于冗长，或始终未能正确引用来源，或对某一类请求的处理明显优于其他类别。MLflow还支持持续评估功能，可自动对每条新追踪进行评分，因此你根本无需手动运行评估。

这一过程是刻意设计的：从可见性开始，加入人工反馈，然后自动化质量测量。每一步都建立在前一步的基础上，你可以根据需求在任意阶段停止。

如果这个功能对你有帮助，请在GitHub上给我们点个星标：github.com/mlflow/mlflow ⭐️

有疑问或反馈？在MLflow社区中打开问题或参与讨论。