Vercel 部署看门狗技能（Vercel Deployment Watchdog Skill）

⚠️ 安全与使用免责声明

本技能专为监控您**自有**的 Web 应用及部署而设计。严禁将其用于探测、扫描或监控任何您不拥有、且未获得明确授权的系统。

允许用途：

• 监控部署在 Vercel 或类似平台上的自有网站和 API
• 对您所控制的部署执行自动化健康检查
• 与您自有的告警系统（如 Telegram 等）集成

禁止用途：

• 未经授权扫描第三方网站
• 尝试访问私有/内网环境
• 测试您不拥有或未管理的系统
• 任何可能被视为未授权访问或骚扰的行为

使用本技能即表示您同意：仅将其用于您自有基础设施的合法监控。

技能概览

面向 Vercel 托管应用的自动化部署监控能力。本技能提供以下功能：

1. 部署后健康检查：验证 HTTP 状态码、缓存新鲜度、内容有效性
2. Vercel API 集成：自动识别新部署
3. Feed 验证：校验 API 端点返回符合预期结构的有效 JSON 数据
4. Cron 任务配置：按计划定期执行检查，或在部署完成时触发
5. 告警集成：通过 OpenClaw cron 任务配置，将失败通知发送至 Telegram / WhatsApp 或 Webhook（投递由 OpenClaw 平台统一处理）

🔒 安全与合规性

内置安全机制

本技能包含多项安全防护措施：

1. URL 校验：所有 URL 均经严格验证，确保满足以下条件：

   • 必须以 http:// 或 https:// 协议开头
   • 警告/拦截本地地址（localhost、127.0.0.1、0.0.0.0）
   • 可配置为拦截私有 IP 地址段（RFC 1918）
   • 可通过 ALLOW_INTERNAL=true 环境变量显式启用对内网资源的监控（需主动开启；无 CLI 绕过参数）
   • 安全提示：仅当确需监控 localhost / 私有 IP 且已获明确授权时，方可启用 ALLOW_INTERNAL=true。启用后将允许网络访问内网地址。

2. 凭证安全：

   • 绝不硬编码 API Token 或密钥
   • 支持通过环境变量（首选）或 CLI 参数传入 Token
   • 脚本不会记录敏感凭证信息

3. 网络限制：

   • 默认禁止向私有 IP 地址段发起出站网络请求
   • 支持为 HTTP 请求配置超时限制
   • 提供速率限制建议

符合 ClawHub 政策

本技能：

• 不尝试绕过任何安全控制机制
• 不包含混淆或隐藏功能
• 为开源项目，所有操作完全透明
• 尊重 robots.txt 及通用 Web 标准
• 遵循最小权限原则

负责任使用的必要条件

您必须做到：

1. 对所有目标 URL 具备明确的监控授权
2. 使用具备最小必要作用域的自有 API Token
3. 遵守被监控服务的速率限制
4. 不得将本技能用于监视或骚扰目的
5. 遵守所有适用法律及服务条款

违反上述条款可能导致您从 ClawHub 移除，并暂停您的账户。

快速开始

1. 前置依赖

# 检查 curl 和 jq 是否已安装
command -v curl >/dev/null 2>&1 && command -v jq >/dev/null 2>&1 || {
    echo "错误：curl 和 jq 是必需依赖，但尚未安装。"
    echo "请使用系统包管理器安装："
    echo "  Debian/Ubuntu：sudo apt-get install curl jq"
    echo "  macOS：brew install curl jq"
    echo "  其他系统请参考：https://curl.se/ 和 https://stedolan.github.io/jq/"
    exit 1
}

2. 配置环境变量

创建 .env 文件或直接设置环境变量：

# Vercel API Token（在 https://vercel.com/account/tokens 创建）
export VERCEL_TOKEN="vcp_..."

# 待监控的目标 URL
export HOMEPAGE_URL="https://your-site.com/"
export API_FEED_URL="https://your-site.com/api/feed"

# 可选：OpenClaw cron 通知所用的 Telegram 聊天 ID（脚本本身不使用该变量）
export TELEGRAM_CHAT_ID="YOUR_TELEGRAM_CHAT_ID"

# 安全设置：仅当需监控 localhost / 私有 IP 时才设置 ALLOW_INTERNAL=true
# export ALLOW_INTERNAL="true"

3. 手动运行检查

# 设置脚本可执行权限
chmod +x scripts/watchdog-check.sh

# 运行检查
./scripts/watchdog-check.sh --homepage "$HOMEPAGE_URL" --api "$API_FEED_URL"

4. 使用 OpenClaw Cron 定期调度（推荐）

为保障安全性与平台集成度，请优先使用 OpenClaw 内置的 cron 系统，而非系统级 cron：

// 创建一个 OpenClaw cron 任务（每 5 分钟执行一次）
{
  "name": "Vercel Watchdog",
  "schedule": { "kind": "every", "everyMs": 300000 },
  "payload": {
    "kind": "agentTurn",
    "message": "Run deployment watchdog check for my site"
  },
  "delivery": {
    "mode": "announce",
    "channel": "telegram",
    "to": "YOUR_TELEGRAM_CHAT_ID"
  }
}

详见下方“与 OpenClaw 集成”章节。

功能特性

健康检查组件

1. HTTP 状态码校验：确保首页与 API 返回 200 OK
2. 缓存新鲜度检查：校验 age: 0 与 x-vercel-cache: MISS 响应头
3. 内容有效性验证：确认页面标题中包含预期文本
4. JSON Feed 验证：校验 API 响应结构与数据完整性
5. 部署状态检测：调用 Vercel API 获取最新部署信息

Vercel API 集成

本技能支持：

• 列出近期部署，以识别新部署
• 检查部署状态（READY、ERROR、BUILDING）
• 获取部署 URL 与元数据
• 在部署状态变为 READY 时自动触发健康检查

告警机制

当检查失败时，本技能可：

• 通过 OpenClaw 发送 Telegram 消息
• 记录详细的失败信息
• 提供修复建议
• 在连续失败后升级告警级别

使用示例

基础健康检查

./scripts/watchdog-check.sh --homepage "https://your-site.com" --api "https://your-site.com/api/feed"

Vercel 部署监控

脚本会自动读取 VERCEL_TOKEN 环境变量；您也可通过 --token 参数显式传入。

# 检查过去 10 分钟内是否有新部署
./scripts/vercel-monitor.sh --project "your-project" --since 10m

脚本参考

scripts/watchdog-check.sh

主健康检查脚本，支持以下参数：

--homepage URL    # 待检查的首页 URL（默认：https://your-site.com/）
--api URL         # 待检查的 API Feed URL（默认：https://your-site.com/api/feed）
--verbose         # 启用详细输出
--json            # 以 JSON 格式输出结果，便于程序化调用

scripts/vercel-monitor.sh

Vercel API 集成脚本：

--token TOKEN     # Vercel API Token（必填）
--project NAME    # 待监控的项目名称（默认：自动识别）
--since MINUTES   # 检查最近 N 分钟内的部署（默认：5）
--team-id ID      # 组织账户对应的 Team ID

与 OpenClaw 的集成

注意：本技能提供的是向 stdout 输出结果的监控脚本。通知投递由 OpenClaw 的 cron 投递系统（delivery.mode: "announce"）在配置后完成，脚本自身不发起外部 API 调用进行通知。

作为 Cron 任务运行

通过 OpenClaw 的 cron 系统周期性执行本技能：

// 示例 cron 任务配置
{
  "name": "Vercel Watchdog",
  "schedule": { "kind": "every", "everyMs": 300000 }, // 每 5 分钟一次
  "payload": {
    "kind": "agentTurn",
    "message": "Run deployment watchdog check and notify if any failures"
  },
  "delivery": {
    "mode": "announce",
    "channel": "telegram",
    "to": "YOUR_TELEGRAM_CHAT_ID"
  }
}

作为子代理（Sub-Agent）运行

启动子代理在后台执行监控任务：

# 使用 OpenClaw sessions_spawn 在后台运行监控
openclaw sessions spawn --task "Monitor your site deployment health for next hour" --runtime subagent --label deployment-watchdog

故障排查

常见问题

1. Vercel API 认证失败：

   • 确认 Token 已授予 deployment:read 权限
   • 检查 Token 是否已过期（可前往 https://vercel.com/account/tokens 重新生成）

2. 缺失缓存新鲜度标识：

   • 部署可能被 CDN 缓存
   • 等待数分钟后重试
   • 检查 Vercel 项目设置中的缓存响应头配置

3. API Feed 验证失败：

   • 确认 API 端点可正常访问
   • 若跨域访问，请检查 CORS 设置
   • 使用 jq . <(curl -s API_URL) 验证 JSON 结构

调试模式

启用详细输出以查看完整检查过程：

./scripts/watchdog-check.sh --verbose

技能扩展

添加新检查项

1. 在 scripts/watchdog-check.sh 中添加检查函数
2. 更新汇总输出逻辑
3. 使用 --verbose 参数进行测试

与其他服务集成

• Slack 通知：添加 Webhook 集成
• 邮件告警：使用 himalaya CLI 或 gog 技能
• 仪表盘集成：输出 JSON 格式结果供外部监控系统消费

参考资料

详见 references/ 目录，其中包含：

• Vercel API 文档
• HTTP 缓存响应头规范
• JSON Schema 校验示例
• OpenClaw Cron 任务配置指南