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 第一步安装PrometheusPrometheus是监控系统的“大脑”负责抓取和存储指标数据。# 使用Homebrew安装是最简单的方式 brew install prometheus安装完成后你可以通过prometheus --version验证。这里有个注意事项Homebrew默认会把Prometheus安装为服务并开机自启。但对于我们这种单一用途的场景我更喜欢手动管理避免不必要的后台服务。所以我们后续会用手动命令启动或者使用自定义的launchd配置。3.2 第二步安装OpenClaw Exporter这是我们的数据采集器。你可以选择下载预编译的二进制文件也可以从源码构建。方案A下载预编译版本推荐最快捷首先访问项目的 GitHub Releases 页面查看最新的版本号。假设最新版本是v0.1.0。# 根据你的芯片架构选择对应的下载链接。以Apple Silicon (arm64) 为例 export EXPORTER_VERSIONv0.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关键配置解析scrape_interval: 抓取间隔。对于OpenClaw会话监控5秒是一个比较合理的值既能及时反映变化又不会对系统造成过大压力。targets: 指定exporter的访问地址。localhost:9101是openclaw_exporter的默认监听地址。job_name: 给这组监控目标起个名字在Prometheus和Grafana中会用到。3.4 第四步启动服务并验证现在我们分别在两个终端窗口启动服务。终端1启动Prometheuscd ~/.openclaw/workspace # 指定配置文件并设置数据存储路径 prometheus --config.fileprometheus.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。验证数据流打开浏览器访问http://localhost:9101/metrics。你应该能看到大量以openclaw_开头的指标文本。这证明exporter正在正确采集数据。访问http://localhost:9090进入Prometheus的Web UI。在顶部导航栏点击“Status” - “Targets”。你应该能看到两个目标prometheus和openclaw状态均为“UP”。这证明Prometheus正在成功抓取exporter的数据。回到“Graph”页面在查询框中输入openclaw_skills_total并执行如果能看到具体的数值比如51那么恭喜你整个监控数据链路已经打通了4. 配置系统服务实现开机自启macOS launchd手动启动适合测试但我们需要一个稳定的、能开机自启的方案。在macOS上我们使用launchd来管理这两个服务。4.1 为OpenClaw Exporter创建守护进程创建配置文件~/Library/LaunchAgents/local.openclaw.exporter.plist?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringlocal.openclaw.exporter/string !-- 服务唯一标识 -- keyProgramArguments/key array !-- 可执行文件路径必须绝对路径 -- string/usr/local/bin/openclaw_exporter/string !-- 启动参数指定OpenClaw工作空间 -- string-openclaw.dir/string string/Users/你的用户名/.openclaw/workspace/string !-- 务必修改为你的实际用户名和路径 -- /array keyRunAtLoad/key true/ !-- 在加载本配置时立即运行 -- keyKeepAlive/key true/ !-- 进程退出后自动重启 -- keyStandardOutPath/key string/tmp/openclaw-exporter.log/string !-- 标准输出日志 -- keyStandardErrorPath/key string/tmp/openclaw-exporter.log/string !-- 标准错误日志合并到同一文件 -- keyEnvironmentVariables/key dict !-- 可以在这里设置环境变量比如PATH -- keyPATH/key string/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin/string /dict /dict /plist4.2 为Prometheus创建守护进程创建配置文件~/Library/LaunchAgents/local.prometheus.plist?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringlocal.prometheus/string keyProgramArguments/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 keyRunAtLoad/key true/ keyKeepAlive/key true/ keyStandardOutPath/key string/tmp/prometheus.log/string keyStandardErrorPath/key string/tmp/prometheus.log/string keyEnvironmentVariables/key dict keyPATH/key string/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin/string /dict /dict /plist重要操作步骤与避坑指南路径替换将上面两个XML文件中的/Users/你的用户名全部替换成你电脑的实际用户名echo $HOME可以查看。这是最常见的错误来源。验证Prometheus路径在终端执行which prometheus确保local.prometheus.plist中ProgramArguments的第一个字符串与该路径完全一致。加载服务# 加载服务配置 launchctl load ~/Library/LaunchAgents/local.openclaw.exporter.plist launchctl load ~/Library/LaunchAgents/local.prometheus.plist检查服务状态launchctl list | grep -E (openclaw|prometheus)如果看到local.openclaw.exporter和local.prometheus且前面的数字不是负数负数代表错误说明加载成功。查看日志如果服务没有启动第一时间检查日志文件。tail -f /tmp/openclaw-exporter.log tail -f /tmp/prometheus.log管理服务# 停止服务 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数据源登录Grafana后点击左侧齿轮图标 -“Data Sources”。点击“Add data source”选择“Prometheus”。在URL一栏填写http://localhost:9090这是Prometheus的地址。其他保持默认点击最下方的“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 指标抓取失败或无数据这是最常见的问题。请按照以下步骤排查检查exporter进程ps aux | grep openclaw_exporter。确保进程在运行并且命令行参数-openclaw.dir指向的路径绝对正确。一个常见错误是路径中的~没有被正确展开在启动脚本或配置文件中最好使用绝对路径/Users/username/.openclaw/workspace。手动访问指标端点在浏览器中打开http://localhost:9101/metrics。如果打不开可能是exporter没启动或端口冲突。如果打开了但没有openclaw_开头的指标说明exporter没有正确读取到你的OpenClaw工作空间。检查工作空间目录的权限确保运行exporter的用户有读取权限。检查Prometheus Targets访问http://localhost:9090/targets查看openclaw这个job的状态。如果是“DOWN”将鼠标悬停在错误图标上会显示具体错误信息通常是“connection refused”或“timeout”。connection refusedPrometheus连不上9101端口。回到步骤1和2。timeout网络或防火墙问题在本地环境下较少见。查看exporter日志日志是定位问题的金钥匙。如果你配置了launchd日志在/tmp/openclaw-exporter.log。重点关注启动时的错误信息例如“failed to read directory”等。6.2 Prometheus数据存储与保留策略默认情况下Prometheus数据存储在--storage.tsdb.path指定的目录。对于个人监控数据增长很慢但了解以下两点有益数据清理Prometheus默认只保留15天的数据。你可以在启动参数中修改--storage.tsdb.retention.time90d表示保留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工具的使用方式可能就悄然改变了。