OpenClaw 网关 Prometheus 指标：/metrics 抓取设计、直方图与摘要、基数护栏，以及云 Mac mini 上的 macOS LaunchAgent 排演

智能体网关是控制平面：鉴权工具、扇出模型调用、执行预算。日志在事故后讲故事，而 Prometheus 指标能在没人被叫醒前提示延迟是否缓慢漂移。2026 年，成熟的 OpenClaw 部署会在 /metrics（或兄弟管理端口）暴露文本指标，让 SRE 以可预测的基数、统一的命名抓取，并仅在链路追踪开启时附带 exemplar。本文说明抓取拓扑、直方图与摘要取舍、标签卫生、指标如何与既有健康检查及日志管线互补，以及如何用 LaunchAgent 定时器在租用的 Mac mini 上镜像生产节奏完成排演。请同时阅读 网关健康监控与可用性探测、日志脱敏与 logrotate 纪律、升级与迁移清单，以及 nginx 流量排空与滚动切换，以便在发布窗口内让告警、日志与指标保持同一叙事。

成本语境：MacHTML 云 Apple Silicon 约 $16.9/天，足以长期保留一台与生产抓取配置一致的排演机，而不必借用设计师笔记本。

网关为何需要一等 Prometheus 指标

与单体 Web 不同，网关复用大量异步流：WebSocket 工具调用、HTTP 批处理、供应商重试与文件系统副作用。单一 p99 尖峰在聚合 CPU 曲线上可能完全看不见，因为工作从一名 worker 转移到另一名。Prometheus 计数器与直方图在谨慎埋点下能以低开销捕获请求量、错误码、队列深度以及供应商特定的退避窗口；没有它们，值班只能依赖尾部采样，直到账单揭示那些稀有却昂贵的工具调用。

OpenClaw 的架构也意味着局部故障：某个供应商降级而其他仍健康。指标应暴露按路由的成功率片段，却不能制造成千上万种标签组合。可观测性与基数之间的张力贯穿下文每一节。

在静态导出或边缘托管场景，指标还能充当“轻量黑匣子”：即便你无法在 CDN 层运行完整 APM，也可以在网关进程内保留最关键的队列与错误计数，为后续关联日志提供锚点。这样当客户报告“偶发卡顿”时，团队能先对照直方图桶迁移，再下钻到脱敏日志，而不是盲猜。

/metrics 监听的抓取设计

除非能保证 mTLS 与严格 ACL，否则不要把指标与业务流量绑在同一套套接字。常见模式是在网关主机绑定 127.0.0.1:9108，由 node_exporter 边车或 Prometheus agent 通过 SSH 隧道或 VPC 对等抓取。若必须远程暴露，应在 nginx 终止 TLS，并要求内部 PKI 签发的客户端证书。

scrape_configs:
  - job_name: openclaw-gateway
    scrape_interval: 15s
    metrics_path: /metrics
    static_configs:
      - targets: ['gateway-prod.internal:9108']

尊重 Prometheus 的过期语义：发布失败导致抓取中断时，图表应空白而非撒谎。将抓取间隔与 systemd 或 LaunchAgent 的重启预算对齐，避免首次开机抓取恰好撞上冷 JIT 尖峰，误导弹性伸缩。

若经由服务发现注册多个实例，务必为每个实例设置一致的 instance 与 job 标签，并在 relabel 阶段剥离环境密钥。对多区域部署，可用 region 这类低基数维度帮助分面，而不是把完整主机 FQDN 复制进每个指标名。

2026 年的直方图与摘要

原生直方图让服务端暴露结构化桶，Prometheus 在副本间一致地计算分位数；客户端摘要预先计算分位数，却无法在 Pod 间安全平均。对 OpenClaw 网关，请求延迟与工具耗时应优先直方图，桶边界与 SLO 阈值对齐（例如 250ms、500ms、1s、2s、5s）。对无法控制的 SDK 可暂用摘要，但不要在同一指标名上混用两种语义。

Exemplar 连接追踪：仅在尾部采样允许时附加 trace id，并在导出前剥离敏感客户标识。macOS 排演机默认关闭 exemplar，以控制本地 TSDB 体积。

当团队同时运行 Grafana 与 Alertmanager 时，提前约定直方图 heatmap 的桶顺序与颜色梯度，避免不同面板对同一 SLO 给出冲突视觉。对中文运营同事，文档里写清“桶上界含不含”能减少误读。

基数护栏与标签预算

每个唯一标签集都是独立时间序列。网关很容易诱惑你用 API key、模型名、租户 UUID 或文件路径打标签——不要。改为输出有界标签如 provider="anthropic" 或 region="us-west"，把高基数维度推入你已按日志文章做脱敏的结构化日志。为自定义指标设硬预算：每进程活跃序列少于两百（不含 Go 运行时默认）。

用记录规则把工具级计数折叠到队列：sum by (route)(rate(openclaw_tool_calls_total[5m])) 比导出每个工具 ID 更安全，除非这些 ID 是编译期封闭的枚举。

对多租户 SaaS，若业务坚持“按租户看延迟”，优先在查询层用日志派生或独立计费仓，而不是在 Prometheus 里按租户拆时间序列；否则任何热门租户都会放大抓取成本与压缩压力。

与健康检查和日志配对

指标不应复制合成探测流量，而是互补：健康检查回答“端口从外面是否可达”，计数器回答“内部队列是否在排空”。把面板接线成：探针变红时同时看到 gateway_errors_total 上升与直方图停滞。按上文链接的迁移清单跟踪升级时，若连续两个间隔抓取成功率低于五个九，应暂停自动扩缩容以免放大噪声。

当日志管线引入新的脱敏规则时，回写一份“指标—日志关联表”，列出哪些 label 与哪些日志字段可 join，避免值班在压力下发明临时查询。

nginx 排空期间的抓取协同

滚动切换会在进程退出前调整上游权重；若服务发现滞后，Prometheus 可能短暂打到正在终止的 Pod。使用就绪门，让端点在排空开始瞬间从 SD 消失，与引言中 nginx 滚动指引一致。若经由 nginx 抓取，为 /metrics 增加专用 location 与 IP 白名单，不要复用按无关节奏轮换的公共 TLS 证书。

在双活或多入口场景，记录每次权重调整的时间戳到 Grafana 注释，便于事后对齐抓取失败窗口与流量曲线。

本地抓取器的 macOS LaunchAgent 模式

在开发者笔记本与云 Mac mini 上，LaunchAgent 比 cron 更准时，也能把日志写入统一日志。每分钟对 localhost 运行轻量 promtool check metrics curl，可在 CI 之前捕获 exposition 回归。

<key>StartInterval</key>
<integer>60</integer>

保持 Agent 非特权；永远不要把 bearer token 写进 plist——通过带相应权利的小助手从 macOS 钥匙串读取。

若同一主机并行跑多个网关版本（蓝绿），为每个版本分配独立 metrics 端口并在 plist 中用标签区分，避免抓取器误把 canary 与 stable 混写入同一 job。

云 Mac 排演与一致性测试

云 Mac mini 能复现 Apple 调度器、文件系统大小写默认与 TLS 栈怪癖。镜像生产抓取配置但缩短保留期，然后对网关施压并观察 TSDB 压缩滞后。以约 $16.9/天 的成本，你可以承担在共享预发集群上显得“粗鲁”的多日浸泡测试。

排演脚本应包含：拔插网线模拟、切换 DNS、以及人为延迟供应商响应，以验证直方图桶是否仍能提供可行动信号。

安全：鉴权、TLS 与管理面隔离

指标端点会泄露运行细节：队列名、依赖版本、断路器状态。用网络策略、SSH 隧道或零信任网格保护。若必须并排暴露 JSON 调试与 Prometheus 文本，确保 content-type 永不冲突，并防止 DNS 切换时管理端口意外对公网开放而被爬虫抓取。

对合规行业，审计日志应记录谁访问了 metrics URL，而不仅是业务 API。

SLO 接线：燃尽率与记录规则

在网关延迟与错误占比上定义 SLI，然后映射多窗口燃尽告警。记录规则应预计算五分钟与一小时速率以保持面板敏捷。用历史事故校验阈值，而非拍脑袋，并在 runbook 中把指标面板链接到按请求 ID 过滤的日志查询。

若 SLO 同时覆盖人类客服时段与夜间批处理，考虑拆分 burn 规则，避免夜间合法尖峰淹没白天交互体验。

矩阵：导出什么、丢弃什么

信号	导出？	备注
每次请求 UUID	否	写入脱敏日志。
队列深度 gauge	是	背压可见性关键。
供应商 429 计数	是	有界标签；与 Retry-After 关联。
堆采样	否	pprof 走独立鉴权端点。

编号上线清单

1. 清点现有指标，删除超出预算基数的时间序列。
2. 将直方图桶与 SLO 阈值对齐并文档化边界。
3. 编写抓取配置：TLS、ACL、relabel 剥离环境密钥。
4. 测试排空行为，确保终止的 Pod 在抓取恢复前从 SD 消失。
5. 在云 Mac 上对合成负载同时验证探针与指标。
6. 交付带发布窗口注释的 Grafana 面板。
7. 在 macOS 主机跑 LaunchAgent 金丝雀，尽早发现 exposition 漂移。
8. 审查保留策略：本地排演 Prometheus 需要激进降采样。

常见问题

是否应在网关主机上运行 Prometheus？

通常否——远程抓取进集中 TSDB，以缩小爆炸半径。

OpenTelemetry 呢？

OTLP 与 Prometheus 互补；对以 PromQL 标准化的团队可转换 exposition。

如何在 CI 测试基数回归？

在集成测试后快照序列计数，新标签未经评审即失败构建。

可靠指标与可用性检查、结构化日志同属可靠性计划。在 MacHTML 租用的专用 Mac mini（约 $16.9/天）上排演抓取路径，可在进入生产 Prometheus 之前捕获 TLS、网络与时序问题。