公开接口Public API

ClawPanel 官网 API 文档ClawPanel Site API

这些接口面向客户端更新、下载、公告通知、心跳统计和 AI Agent 接入。Base URL 自动按当前访问域名生成。Stable endpoints for client updates, downloads, announcements, heartbeat telemetry and AI Agent integrations.

Latest release

GEThttps://claw.qt.cool/api/v1/latest?platform=windows&arch=x64

返回最新版、资产列表、下载入口、更新清单和客户端心跳配置。支持 platform、arch、file_type 过滤；服务端会直接过滤资产，并按平台给出推荐安装包。

{
  "schema": "clawpanel.latest.v1",
  "version": "0.17.0",
  "assets": [{
    "id": 123,
    "name": "ClawPanel_0.17.0_x64-setup.exe",
    "platform": "windows",
    "arch": "x64",
    "fileType": "exe",
    "sha256": "sha256:...",
    "source": "mirror",
    "downloadUrl": "https://claw.qt.cool/api/v1/download/123",
    "recommended": true
  }]
}

推荐规则：Windows 优先轻量 x64-setup.exe；macOS 按 ARM / Intel 各推荐一个 DMG；Linux 优先 AppImage；Web 更新只推荐 web-*.zip。

Stable download

GEThttps://claw.qt.cool/api/v1/download/{assetId}

返回 302 到一次性 /dl/{token}。客户端必须跟随重定向。服务端优先读取 R2/本地镜像；未镜像但有上游地址时走官网代理兜底。

curl -L -o ClawPanel.exe "https://claw.qt.cool/api/v1/download/123"

Announcements

GEThttps://claw.qt.cool/api/v1/announcements?app=ClawPanel&version=0.17.0&locale=zh-CN&surface=client

客户端弹窗公告、通知、迁移提醒和紧急安全通知使用这个接口。后台可配置投放位置、展示形态、目标 App、版本范围、展示时间、CTA 和 dismissKey。测试公告只在 test=1、staging=1 或 Staging/Test App 名称下返回。

{
  "schema": "clawpanel.announcements.v1",
  "surface": "client",
  "announcements": [{
    "id": 1,
    "type": "modal",
    "displayType": "modal",
    "targetSurface": "client",
    "level": "warning",
    "title": "重要升级提醒",
    "body": "请升级到最新版本。",
    "ctaText": "立即下载",
    "ctaUrl": "https://claw.qt.cool/download",
    "minVersion": "0.17.0",
    "maxVersion": "",
    "startAt": "2026-06-05T00:00:00Z",
    "expiresAt": "",
    "dismissKey": "upgrade-0.17.0",
    "testOnly": false
  }]
}

surface=client 返回客户端公告，surface=home 返回官网主页公告，targetSurface=all 的公告会同时返回。客户端关闭公告后应保存 dismissKey；后台更换 dismissKey 后，同一条公告可以再次触达。

Client heartbeat

POSThttps://claw.qt.cool/api/v1/client/heartbeat

建议客户端每 60 秒上报一次。必须提供稳定客户端 ID，优先使用 X-ClawPanel-Client-ID；后台按最近 5 分钟心跳统计在线客户端，并展示版本、平台、运行时分布。

curl -X POST "https://claw.qt.cool/api/v1/client/heartbeat" \
  -H "Content-Type: application/json" \
  -H "X-ClawPanel-Client-ID: stable-device-id" \
  -d "{\"clientId\":\"stable-device-id\",\"app\":\"ClawPanel\",\"version\":\"0.17.0\",\"platform\":\"windows\",\"arch\":\"x64\",\"runtime\":\"openclaw\",\"locale\":\"zh-CN\"}"

Legacy updater

GEThttps://claw.qt.cool/update/latest.json

兼容旧官网 https://claw.qt.cool/update/latest.json，只返回最新版 web-*.zip。该接口和 /api/v1/latest 都使用强回源缓存头，避免客户端拿到长期缓存的旧版本；hash 跟随 web zip 的 SHA256，minAppVersion 不会随同步自动抬高。

Integration rules

所有客户端更新入口都应使用 HTTPS。本站在真实域名访问时默认输出 HTTPS URL，本地调试保留 http://127.0.0.1。
不要直接依赖 GitHub 下载地址；优先使用 downloadUrl，让官网处理 R2、本地镜像和代理兜底。
如果 assets[].downloadUrl 为空或 source=unavailable，客户端应显示不可下载，不要自行猜测链接。
心跳统计按客户端 ID 去重，不把 IP 或 User-Agent 当成唯一用户。缺少客户端 ID 会返回 400。
后台接口不属于公开协议。外部程序只使用本页列出的 /api/v1/* 和 /update/latest.json。
qt.cool