上报与信任边界

官方上报路径固定、最小化，而且是 best-effort

当启用产品 telemetry 时，HopClaw 只会把匿名安装与采用情况上报到一个固定官方端点。上报失败默认静默，不能打断 runtime、onboarding 或正常安装流程。

  • 官方固定上报地址：https://pulse.hopclaw.com/api/v1/ingest/events
  • 官方统计页位于一个单独的密码保护页面之后。
  • 企业部署可以完全关闭 telemetry，也可以把采集留在自己的边界内。
打开文档
官方固定路径

这些是 HopClaw Pulse 的规范化路由。产品发布和安装脚本应始终依赖稳定的 ingest 地址。

POST https://pulse.hopclaw.com/api/v1/ingest/events
Ingest APIhttps://pulse.hopclaw.com/api/v1/ingest/events

HopClaw 匿名产品 telemetry 的官方固定上报路径。

管理登录https://pulse.hopclaw.com/login

团队内部查看聚合指标和近期事件的密码保护入口。

健康检查https://pulse.hopclaw.com/healthz

部署检查和可用性监控使用的健康探针。

数据边界

统计的是产品采用，不是用户内容

Pulse 只用于安装和使用信号，范围故意做得很窄，让产品能知道 adoption 情况，同时不碰 prompt 或工作区内容。

会发送什么
  • 由本地机器生成的匿名 install id。
  • 事件名、事件时间、产品版本、发布通道、操作系统和 CPU 架构。
  • 最小事件属性，例如启动入口、选中的 provider、plugin 名称或 skill id。
  • 用于发布判断和生态判断的安装量、活跃安装量等信号。
绝不会发送什么
  • Prompt 内容或对话历史。
  • 文件内容、仓库源码或本地产物正文。
  • 命令正文或终端输出正文。
  • 本地文件路径、API key 或其他 secret 值。
  • 座席、计费身份，或精确到人的认证用户数。
当前事件

当前一方事件契约保持得很小

开启 telemetry 后，HopClaw 当前会上报这些产品事件。

install.completed

本地安装第一次完成激活路径时记录。

onboard.completed

引导配置完成时记录，只带高层配置属性。

runtime.active

从 runtime 表面发出的每日活跃安装信号。

plugin.installed

plugin 安装事件，包含名称、版本和来源类型。

skill.installed

skill 安装事件，包含 skill id、版本和来源类型。

失败语义

上报绝不能拖累产品主路径

面向用户的规则很简单：上报只是 best-effort。即使 telemetry 服务变慢或不可用，用户也不应该感受到主流程被打断。

默认静默

正常使用下会吞掉上报失败。只有显式打开 `diagnostics.telemetry_debug_log: true` 才会输出调试级失败日志。

该后台就后台

serve、gateway、plugin 安装和 skill 安装的上报走后台。onboarding 则使用一个极短的静默超时，而不是长时间阻塞。

产品不依赖上报成功

runtime 启动、onboarding 结束、审批流和安装流程，在 telemetry 服务不可达时都继续正常运行。

配置选择

显式选择上报边界

社区发行版可以直接指向官方 Pulse；企业或私有部署可以继续关闭 telemetry，或者把批量事件写到客户自有 collector 路径中。

官方 Pulse

把匿名采用指标上报到固定官方端点

适合公共发行版，需要看到产品安装量、活跃安装量和生态采用趋势时使用。

diagnostics:
  telemetry_enabled: true
  telemetry_endpoint: https://pulse.hopclaw.com/api/v1/ingest/events
  telemetry_token: env:HOPCLAW_TELEMETRY_TOKEN
  telemetry_timeout: 5s
  telemetry_debug_log: false
客户自有

把 telemetry 留在自己的边界内

当不允许出站产品分析时，可使用内建 collector 路径，把原始事件完全留在客户侧。

diagnostics:
  telemetry_enabled: false
  telemetry_collector_enabled: true
  telemetry_collector_dir: ./.hopclaw/telemetry-collector
  telemetry_collector_auth_token: env:HOPCLAW_TELEMETRY_COLLECTOR_TOKEN
  telemetry_collector_max_upload_bytes: 4194304

# local collector ingest path:
# POST /telemetry/events