为OpenClaw AI助手构建可观测性：基于Prometheus与Grafana的监控实践

1. 项目概述：为你的AI助手装上“仪表盘”

如果你正在使用OpenClaw这个强大的AI助手，那你一定遇到过这样的困惑：刚才那轮对话到底消耗了多少Token？这个月的API成本累计到多少了？我的缓存机制到底有没有在帮我省钱？工作空间里的文件状态是否健康？这些问题，如果每次都靠手动去翻日志、查账单，不仅效率低下，而且很难形成直观的趋势洞察。

这正是openclaw_exporter诞生的原因。简单来说，它是一个Prometheus Exporter，专门为OpenClaw设计。你可以把它理解为一个“翻译官”或“数据采集器”，它的核心任务就是持续不断地读取你的OpenClaw工作空间（~/.openclaw/workspace）里产生的各种运行时数据——比如会话记录、Token用量、成本信息、文件状态等——然后将这些数据转换成Prometheus能够理解和抓取的标准化指标格式。

有了这些指标，你再配合上Prometheus（时序数据库）和Grafana（可视化仪表盘），就能为你的OpenClaw搭建一套完整的可观测性（Observability）体系。想象一下，在你的Grafana面板上，实时滚动着Token消耗速率曲线、累计成本柱状图、缓存命中率仪表，甚至工作空间关键文件的健康状态指示灯。这不再是模糊的感觉，而是清晰、量化、可预警的“仪表盘”，让你对AI助手的运行状况了如指掌。

这个项目尤其适合两类朋友：一是重度依赖OpenClaw进行开发、写作或研究的个人用户，你需要精细化管理API成本并优化使用效率；二是在团队或生产环境中部署了OpenClaw的开发者，你需要监控其稳定性和资源消耗。接下来，我会带你从零开始，一步步部署、配置这套监控系统，并分享我在实际使用中积累的配置技巧和避坑经验。

2. 核心监控指标深度解析

在动手部署之前，我们先彻底搞明白openclaw_exporter到底能为我们提供哪些数据。理解这些指标的含义，是后续配置告警和设计仪表盘的基础。指标主要分为两大类：会话运行时指标和工作空间指标。

2.1 会话运行时指标：洞察每一次对话的成本与效率

这类指标围绕每一次OpenClaw会话（Session）展开，是成本控制和性能优化的核心。

• openclaw_session_tokens_*_total系列：这是最关键的资源消耗指标。它细分为输入Token、输出Token、缓存读取Token和缓存写入Token。为什么区分这么细？因为不同模型的定价策略不同，输入和输出Token的价格可能相差数倍。而缓存读写Token则直接反映了你为优化成本所做的缓存策略（如OpenClaw可能使用的向量缓存）的实际效果。监控这些指标的比值和趋势，能帮你判断是对话内容变复杂了（输入输出比变化），还是缓存策略需要调整（缓存命中率低）。
• openclaw_session_cost_total：累计成本（美元）。这是所有Token消耗经过模型单价计算后的最终财务体现。一个重要的实操心得是：不要只看静态值，更要关注其变化速率（通过PromQL的rate()或increase()函数）。你可以设置一个告警规则，当“过去1小时的成本增速超过X美元”时触发，这能有效防止因意外循环调用或提示词设计不当导致的“账单爆炸”。
• openclaw_session_cache_hit_rate：缓存命中率（0到1之间）。这个值越接近1，说明你的缓存效率越高，重复性问题从缓存中直接获取答案的比例越大，从而节省了大量Token。如果这个值长期低于0.3，你就需要警惕了，可能意味着你的会话话题非常发散，缓存难以复用；或者缓存配置（如TTL、容量）需要优化。
• openclaw_session_duration_seconds：会话持续时间。结合Token总量，可以计算出平均Token吞吐速率，帮助你评估AI模型的响应效率或网络状况。
• openclaw_model_info与openclaw_thinking_level：这两个指标以标签（Label）的形式提供了会话的上下文信息。model_info告诉你当前会话使用的是哪个供应商（如openrouter）的哪个模型（如z-ai/glm-5）。thinking_level则反映了OpenClaw的“思考深度”配置。在制作Grafana面板时，我强烈建议利用这些标签进行分组或筛选，例如，可以对比不同模型（model标签）在完成相似任务时的成本和耗时差异，为模型选型提供数据支持。

2.2 工作空间指标：保障AI助手的运行基础

OpenClaw的正常运行依赖于工作空间内一系列配置文件、记忆文件和技能模块。这些指标就像系统的“健康检查”。

• openclaw_file_size_bytes与openclaw_file_mtime_seconds：监控关键文件（如AGENTS.md,SOUL.md,MEMORY.md）的大小和最后修改时间。一个非常实用的场景是：你可以为MEMORY.md（记忆文件）的大小设置一个增长告警。如果它在短时间内暴增，可能意味着记忆机制出现了异常写入；如果它长期不变，则可能意味着记忆功能未正常工作。
• openclaw_workspace_file_exists：文件存在性检查（1表示存在，0表示丢失）。这是最基础的健壮性监控。你可以用一条简单的PromQL来检查所有必需文件的健康状态：avg(openclaw_workspace_file_exists) * 100。这个值如果小于100，就说明有文件丢失了，需要立即介入检查。
• openclaw_skills_total：已安装技能总数。监控这个数字可以确保你的技能库在更新或迁移过程中没有意外丢失。
• openclaw_memory_files_total：每日记忆文件的数量。这有助于你了解AI助手记忆活动的频繁程度。

理解这些指标后，你就会发现，部署exporter不仅仅是“把数据收集起来”，更是为你打开了一扇量化理解AI助手行为模式的大门。接下来，我们进入实战部署环节。

3. 从零开始部署与配置实战

我将以macOS系统为例，演示最清晰的手动部署流程。Linux用户的操作大同小异，主要区别在于包管理器和服务管理工具（systemd）。

3.1 第一步：安装Prometheus

Prometheus是监控系统的“大脑”，负责抓取和存储指标数据。

# 使用Homebrew安装是最简单的方式 brew install prometheus

安装完成后，你可以通过prometheus --version验证。这里有个注意事项：Homebrew默认会把Prometheus安装为服务并开机自启。但对于我们这种单一用途的场景，我更喜欢手动管理，避免不必要的后台服务。所以我们后续会用手动命令启动，或者使用自定义的launchd配置。

3.2 第二步：安装OpenClaw Exporter

这是我们的数据采集器。你可以选择下载预编译的二进制文件，也可以从源码构建。

方案A：下载预编译版本（推荐，最快捷）

首先，访问项目的 GitHub Releases 页面，查看最新的版本号。假设最新版本是v0.1.0。

# 根据你的芯片架构选择对应的下载链接。以Apple Silicon (arm64) 为例： export EXPORTER_VERSION="v0.1.0" curl -sL "https://github.com/JetSquirrel/openclaw_exporter/releases/download/${EXPORTER_VERSION}/openclaw-exporter-darwin-arm64" -o openclaw_exporter # 赋予可执行权限，并移动到系统路径 chmod +x openclaw_exporter sudo mv openclaw_exporter /usr/local/bin/

方案B：从源码构建（适合需要自定义或开发的情况）

确保你的系统已经安装了Go语言环境（1.19+）。

git clone https://github.com/JetSquirrel/openclaw_exporter.git cd openclaw_exporter # 构建 go build -o openclaw_exporter . # 同样，移动到合适的位置 sudo mv openclaw_exporter /usr/local/bin/

验证安装：执行openclaw_exporter -h，如果能看到帮助信息，说明安装成功。

3.3 第三步：编写Prometheus配置文件

Prometheus需要知道去哪里抓取openclaw_exporter的指标。我们需要创建一个配置文件prometheus.yml。我建议将它放在你的OpenClaw工作空间目录下，便于管理。

# 切换到你的OpenClaw工作空间目录，通常是 ~/.openclaw/workspace cd ~/.openclaw/workspace

使用文本编辑器（如nano或vim）创建prometheus.yml文件，内容如下：

global: scrape_interval: 15s # 全局抓取间隔，15秒一次 evaluation_interval: 15s # 规则评估间隔 # 告警规则文件配置，可以先留空 # rule_files: # - "alert_rules.yml" # 告警管理器配置，可以先留空 # alerting: # alertmanagers: # - static_configs: # - targets: # # - alertmanager:9093 scrape_configs: # 第一个抓取任务：监控Prometheus自己 - job_name: 'prometheus' static_configs: - targets: ['localhost:9090'] # Prometheus自己的服务地址 # 第二个抓取任务：监控OpenClaw Exporter（核心配置） - job_name: 'openclaw' static_configs: - targets: ['localhost:9101'] # openclaw_exporter默认监听端口 scrape_interval: 5s # 针对此任务，提高抓取频率为5秒，以获得更实时的话务数据 # 你可以添加额外的标签，方便在Grafana中分类 # labels: # monitor: 'ai-assistant'

关键配置解析：

1. scrape_interval: 抓取间隔。对于OpenClaw会话监控，5秒是一个比较合理的值，既能及时反映变化，又不会对系统造成过大压力。
2. targets: 指定exporter的访问地址。localhost:9101是openclaw_exporter的默认监听地址。
3. job_name: 给这组监控目标起个名字，在Prometheus和Grafana中会用到。

3.4 第四步：启动服务并验证

现在，我们分别在两个终端窗口启动服务。

终端1：启动Prometheus

cd ~/.openclaw/workspace # 指定配置文件，并设置数据存储路径 prometheus --config.file=prometheus.yml --storage.tsdb.path=./prometheus_data

启动后，你应该能看到类似Server is ready to receive web requests.的日志。Prometheus的Web界面运行在http://localhost:9090。

终端2：启动OpenClaw Exporter

# 最关键的是通过 -openclaw.dir 参数指定你的工作空间路径 openclaw_exporter -openclaw.dir=~/.openclaw/workspace

如果一切正常，exporter会输出日志Listening on :9101。它的指标暴露在http://localhost:9101/metrics。

验证数据流：

1. 打开浏览器，访问http://localhost:9101/metrics。你应该能看到大量以openclaw_开头的指标文本。这证明exporter正在正确采集数据。
2. 访问http://localhost:9090，进入Prometheus的Web UI。
3. 在顶部导航栏点击“Status” -> “Targets”。你应该能看到两个目标：prometheus和openclaw，状态均为“UP”。这证明Prometheus正在成功抓取exporter的数据。
4. 回到“Graph”页面，在查询框中输入openclaw_skills_total并执行，如果能看到具体的数值（比如51），那么恭喜你，整个监控数据链路已经打通了！

4. 配置系统服务实现开机自启（macOS launchd）

手动启动适合测试，但我们需要一个稳定的、能开机自启的方案。在macOS上，我们使用launchd来管理这两个服务。

4.1 为OpenClaw Exporter创建守护进程

创建配置文件~/Library/LaunchAgents/local.openclaw.exporter.plist：

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>local.openclaw.exporter</string> <!-- 服务唯一标识 --> <key>ProgramArguments</key> <array> <!-- 可执行文件路径，必须绝对路径 --> <string>/usr/local/bin/openclaw_exporter</string> <!-- 启动参数：指定OpenClaw工作空间 --> <string>-openclaw.dir</string> <string>/Users/你的用户名/.openclaw/workspace</string> <!-- 务必修改为你的实际用户名和路径！ --> </array> <key>RunAtLoad</key> <true/> <!-- 在加载本配置时立即运行 --> <key>KeepAlive</key> <true/> <!-- 进程退出后自动重启 --> <key>StandardOutPath</key> <string>/tmp/openclaw-exporter.log</string> <!-- 标准输出日志 --> <key>StandardErrorPath</key> <string>/tmp/openclaw-exporter.log</string> <!-- 标准错误日志，合并到同一文件 --> <key>EnvironmentVariables</key> <dict> <!-- 可以在这里设置环境变量，比如PATH --> <key>PATH</key> <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string> </dict> </dict> </plist>

4.2 为Prometheus创建守护进程

创建配置文件~/Library/LaunchAgents/local.prometheus.plist：

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>local.prometheus</string> <key>ProgramArguments</key> <array> <!-- 使用 which prometheus 命令查找的绝对路径 --> <string>/opt/homebrew/bin/prometheus</string> <!-- 通常是这个路径，请用 which prometheus 确认 --> <string>--config.file</string> <string>/Users/你的用户名/.openclaw/workspace/prometheus.yml</string> <string>--storage.tsdb.path</string> <string>/Users/你的用户名/.openclaw/workspace/prometheus_data</string> <!-- 数据目录 --> <string>--web.listen-address=:9090</string> <!-- 明确指定监听地址 --> </array> <key>RunAtLoad</key> <true/> <key>KeepAlive</key> <true/> <key>StandardOutPath</key> <string>/tmp/prometheus.log</string> <key>StandardErrorPath</key> <string>/tmp/prometheus.log</string> <key>EnvironmentVariables</key> <dict> <key>PATH</key> <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string> </dict> </dict> </plist>

重要操作步骤与避坑指南：

1. 路径替换：将上面两个XML文件中的/Users/你的用户名全部替换成你电脑的实际用户名（echo $HOME可以查看）。这是最常见的错误来源。
2. 验证Prometheus路径：在终端执行which prometheus，确保local.prometheus.plist中ProgramArguments的第一个字符串与该路径完全一致。
3. 加载服务：

   # 加载服务配置 launchctl load ~/Library/LaunchAgents/local.openclaw.exporter.plist launchctl load ~/Library/LaunchAgents/local.prometheus.plist

4. 检查服务状态：

   launchctl list | grep -E "(openclaw|prometheus)"

   如果看到local.openclaw.exporter和local.prometheus，且前面的数字不是负数（负数代表错误），说明加载成功。
5. 查看日志：如果服务没有启动，第一时间检查日志文件。

   tail -f /tmp/openclaw-exporter.log tail -f /tmp/prometheus.log

6. 管理服务：

   # 停止服务 launchctl stop local.openclaw.exporter launchctl stop local.prometheus # 卸载服务（修改配置文件后需要先卸载再重新加载） launchctl unload ~/Library/LaunchAgents/local.openclaw.exporter.plist launchctl load ~/Library/LaunchAgents/local.openclaw.exporter.plist

完成以上步骤后，重启你的电脑，这两个服务应该会自动启动。你可以再次访问localhost:9090/targets和localhost:9101/metrics来验证。

5. 使用Grafana打造专属AI助手监控面板

数据有了，但看原始指标太不直观。Grafana能将数据变成漂亮的图表和仪表盘。这里假设你已经通过brew install grafana安装了Grafana并启动（默认访问http://localhost:3000，初始账号密码admin/admin）。

5.1 添加Prometheus数据源

1. 登录Grafana后，点击左侧齿轮图标 ->“Data Sources”。
2. 点击“Add data source”，选择“Prometheus”。
3. 在URL一栏填写http://localhost:9090（这是Prometheus的地址）。
4. 其他保持默认，点击最下方的“Save & test”。如果显示“Data source is working”，恭喜，连接成功。

5.2 导入或创建仪表盘

你可以从头开始创建面板，但对于新手，我强烈建议先使用我根据经验总结的核心监控面板配置思路，在Grafana中手动创建以下几个最重要的图表：

面板1：成本与Token消耗概览（Stat + Graph）

• 查询A（大数字显示）：openclaw_session_cost_total。选择“Stat”可视化类型，设置合适的单位（如currency USD）。
• 查询B（时间序列图）：rate(openclaw_session_tokens_total[5m]) * 60。这是每分钟的Token消耗速率。选择“Time series”图。在这个图里，你可以添加多个序列进行对比：
  • 输入Token速率：rate(openclaw_session_tokens_input_total[5m]) * 60
  • 输出Token速率：rate(openclaw_session_tokens_output_total[5m]) * 60
  • 缓存读取速率：rate(openclaw_session_tokens_cache_read_total[5m]) * 60
  • 这样你就能一眼看出消耗主要来自哪里。

面板2：缓存效率与健康度（Gauge + Graph）

• 查询A（仪表盘）：openclaw_session_cache_hit_rate。选择“Gauge”可视化类型，设置范围0-1。绿色区域可以设在0.6-1.0，黄色0.3-0.6，红色0-0.3。这是一个非常直观的健康度指示器。
• 查询B（时间序列图）：openclaw_session_errors_total。使用“Time series”图，但选择“Bars”样式。错误次数应该是偶发的尖刺，如果出现连续的错误柱，就需要立即排查。

面板3：工作空间文件监控（Table + Stat）

• 查询A（表格）：创建一个“Table”面板，查询语句为：

  openclaw_file_size_bytes{file=~".*\\.(md|yaml|yml|json)$"}

  这会列出所有重要配置文件的大小。你可以添加一列“修改时间”，查询openclaw_file_mtime_seconds。
• 查询B（状态）：avg(openclaw_workspace_file_exists) * 100。用“Stat”显示，单位percent (0-100)。这就是你的工作空间健康分。

面板4：按模型/会话细分（Graph with Legend）

• 查询：sum(rate(openclaw_session_tokens_total[5m]) * 60) by (model)。选择“Time series”图。这个查询会按照不同的AI模型（model标签）对Token消耗速率进行分组求和。你可以清晰地看到哪个模型是你的“耗电大户”。
• 进阶：复制这个面板，把by (model)改成by (session_id)，可以观察不同会话的活跃度。

按照这个思路创建4-6个面板，并合理布局，你就能得到一个功能全面、信息密度高的专属监控仪表盘了。别忘了给仪表盘起个好名字，比如“OpenClaw AI助手监控中心”。

6. 高级技巧与故障排查实录

部署过程看似顺利，但实际使用中总会遇到各种“小坑”。下面是我在实际运行中总结的一些经验和常见问题的解决方法。

6.1 指标抓取失败或无数据

这是最常见的问题。请按照以下步骤排查：

1. 检查exporter进程：ps aux | grep openclaw_exporter。确保进程在运行，并且命令行参数-openclaw.dir指向的路径绝对正确。一个常见错误是路径中的~没有被正确展开，在启动脚本或配置文件中，最好使用绝对路径（/Users/username/.openclaw/workspace）。
2. 手动访问指标端点：在浏览器中打开http://localhost:9101/metrics。如果打不开，可能是exporter没启动或端口冲突。如果打开了但没有openclaw_开头的指标，说明exporter没有正确读取到你的OpenClaw工作空间。检查工作空间目录的权限，确保运行exporter的用户有读取权限。
3. 检查Prometheus Targets：访问http://localhost:9090/targets，查看openclaw这个job的状态。如果是“DOWN”，将鼠标悬停在错误图标上会显示具体错误信息，通常是“connection refused”或“timeout”。
   • connection refused：Prometheus连不上9101端口。回到步骤1和2。
   • timeout：网络或防火墙问题，在本地环境下较少见。
4. 查看exporter日志：日志是定位问题的金钥匙。如果你配置了launchd，日志在/tmp/openclaw-exporter.log。重点关注启动时的错误信息，例如“failed to read directory”等。

6.2 Prometheus数据存储与保留策略

默认情况下，Prometheus数据存储在--storage.tsdb.path指定的目录。对于个人监控，数据增长很慢，但了解以下两点有益：

• 数据清理：Prometheus默认只保留15天的数据。你可以在启动参数中修改：--storage.tsdb.retention.time=90d表示保留90天。
• 磁盘空间：使用命令du -sh ./prometheus_data查看数据目录大小。如果异常增大，可能是抓取目标过多或间隔太短。对于单个exporter，每月数据量通常只有几MB到几十MB。

6.3 编写有用的告警规则（Alerting Rules）

监控的更高阶价值是预警。我们可以在Prometheus中配置告警规则。在prometheus.yml同目录下创建alert_rules.yml文件：

groups: - name: openclaw_alerts rules: # 规则1：成本消耗过快告警 - alert: HighOpenClawCostRate expr: rate(openclaw_session_cost_total[1h]) > 0.5 # 过去1小时，成本增速超过0.5美元/小时 for: 5m # 持续5分钟才触发，避免毛刺 labels: severity: warning annotations: summary: "OpenClaw成本消耗过快" description: "成本消耗速率持续偏高，当前速率 {{ $value }} USD/h。请检查是否有异常会话。" # 规则2：缓存命中率过低告警 - alert: LowOpenClawCacheHitRate expr: avg_over_time(openclaw_session_cache_hit_rate[30m]) < 0.2 # 过去30分钟平均缓存命中率低于20% for: 10m labels: severity: info annotations: summary: "OpenClaw缓存效率低下" description: "缓存命中率持续偏低，当前30分钟平均值为 {{ $value }}。考虑优化提示词或检查缓存配置。" # 规则3：工作空间文件丢失告警 - alert: OpenClawWorkspaceFileMissing expr: avg(openclaw_workspace_file_exists) < 1 # 有文件不存在 for: 2m labels: severity: critical annotations: summary: "OpenClaw工作空间文件丢失" description: "检测到必需文件缺失，健康度降至 {{ $value * 100 }}%。请立即检查。"

然后在prometheus.yml中取消rule_files部分的注释，并指向这个文件。告警触发后，需要配置Alertmanager才能发送通知（邮件、Slack等），这属于更进阶的配置，但有了规则，你就已经完成了最关键的一步。

6.4 性能考量与扩展思路

对于个人使用，openclaw_exporter和Prometheus的资源消耗微乎其微。但如果你监控多个工作空间或团队部署，可以考虑：

• 多个Exporter实例：为每个需要独立监控的OpenClaw工作空间（或用户）运行一个exporter实例，监听不同端口（如-web.listen-address=:9102），然后在Prometheus的scrape_configs中配置多个targets。
• Grafana告警：如果觉得Prometheus的Alertmanager配置复杂，可以直接使用Grafana内置的告警功能。在刚才创建的面板图表上，可以直接设置告警规则（比如当缓存命中率面板的值低于0.3时），并通过Grafana配置邮件或Webhook通知，对新手更友好。

经过以上步骤，你应该已经拥有了一套稳定、直观、可预警的OpenClaw AI助手监控系统。这套系统不仅能帮你省钱，更能让你以数据驱动的方式，去理解、优化你与AI协作的整个工作流。从看到成本曲线的瞬间开始，你对AI工具的使用方式，可能就悄然改变了。