ClawHub

TG Cam Skill

Data & APIs

探鸽摄像头 Skill 服务。用于查询当前 Skill 已绑定设备、查看当前画面、查询事件、查看事件图片、确认设备状态和电量。当用户要查看可操作设备、看某个摄像头当前截图、查询某天或某时段发生了什么、查看最近事件或事件图片、确认在线状态、查询电量时使用。

Audits

Pending
ClawScanReview

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPending

Multi-engine malware detections and file reputation.

Install

openclaw skills install tg-cam-api

Webcam Skill

概述

这个 Skill 用于查询当前 Skill 已绑定摄像头的设备信息、当前画面、事件记录、事件图片、在线状态和电量，并在需要时完成拍照等操作。默认返回整理后的结论、摘要和图片，不直接回传长段原始接口响应。

  • 可以做的事：查看设备列表、拍一张当前画面、查询事件、查看事件图片、确认在线状态、查询电量
  • 典型触发：用户说“看看有哪些设备”“帮我看下门口摄像头现在画面”“今天发生了什么”“最近一次事件是什么”“这条事件的图片给我看看”“设备在线吗”“查下电量”
  • 默认输出：整理后的结论、摘要和图片，不把长段原始 JSON 直接甩给用户

使用规则

基础规则

  • 所有请求都使用 https://skill.webcamapp.cc 作为唯一 API Base URL。
  • 环境变量：
    • TIVS_CLI_ID：摄像头 Skill 服务分配的 cli_id
    • TIVS_API_KEY：摄像头 Skill 服务分配的 cli_api_key
  • 所有请求都带上以下请求头：
X-Client-ID: $TIVS_CLI_ID
X-Api-Key: $TIVS_API_KEY
X-Skill-Version-Code: 2
Content-Type: application/json
  • 缺少 TIVS_CLI_ID 或 TIVS_API_KEY 时，提醒用户到摄像头 APP 内获取当前 Skill 的凭据，不要伪造请求
  • 不要在聊天内容中回显 TIVS_API_KEY 的真实值
  • 除非接口明确是 GET 且无请求体，否则默认按 JSON 请求发送
  • 统一按 Header 方式调用

授权配置

如果会话中收到 TIVS_CLI_ID 和 TIVS_API_KEY，请将其写入 openclaw.json：

{
  "skills": {
    "entries": {
      "tg-cam-api": {
        "env": {
          "TIVS_CLI_ID": "{TIVS_CLI_ID}",
          "TIVS_API_KEY": "{TIVS_API_KEY}"
        }
      }
    }
  }
}

结果读取

成功或失败都使用统一响应信封：

{
  "requestId": "req_xxx",
  "code": "ok",
  "msg": "ok",
  "data": {},
  "clientNotice": "发现新版本 Skill，建议升级"
}
  • 读取结果时优先关注 data
  • 只解释已经确认的字段，不要给未知字段强行编含义
  • 默认把接口结果整理成用户能直接理解的答案，不输出长段原始 JSON
  • 需要额外解析 clientNotice，里面会包含一些重要消息；如果里面包含升级消息，提醒用户升级当前 Skill
  • 同一条 clientNotice 一天内最多提示 1-2 次，避免频繁打扰用户

图片处理

  • 图片 URL 可能带签名参数；需要访问时必须使用完整 URL，不要截断。
  • 默认不要把原始图片 URL 直接发给用户；优先获取图片内容后再展示。

调用约束

  • Query 参数统一使用 snake_case，例如 device_id、start_time、event_id
  • 截图接口请求体使用 camelCase，字段名固定为 deviceId
  • 响应字段通常是 camelCase，以实际返回为准
  • 不要臆造不存在的接口路径，也不要把 devices 和 device 写混
  • 如果用户按设备名、备注名或位置描述来操作，先查询设备列表确认目标设备
  • event_id 必须使用系统已经返回过的值，不要自己拼
  • 看到“实时画面”“拍一张”“截个图”时，将其理解为获取一张当前截图，不是实时视频流

调用指南

快速路由

用户意图优先调用前置动作回答重点
查看设备列表或指定设备GET /api/v1/skill/devices无设备清单或指定设备信息
按设备名找目标设备GET /api/v1/skill/devices用结果确认 deviceId设备匹配结果
看某个设备当前画面POST /api/v1/skill/device/snapshot先确认 deviceId截图和简短说明
查某天或某时段事件GET /api/v1/skill/device/events先确认 device_id，再补时间范围事件列表或摘要
看最近一个事件GET /api/v1/skill/device/events/latest先确认 device_id单条事件摘要和图片
看某条事件图片GET /api/v1/skill/device/events/image需要已有 event_id图片和简短事件信息
查设备在线状态GET /api/v1/skill/device/online先确认 device_id是否在线
查设备电量GET /api/v1/skill/device/battery先确认 device_id电量结果

通用流程

  1. 设备不明确时，先查设备列表，不要直接猜 deviceId。
  2. 命中多个设备时，先向用户澄清，不要替用户随意选择。
  3. 用户说“今天”“昨天”“最近一段时间”时，先换成明确的日期或时间范围，再发请求。
  4. 事件类查询默认返回整理后的摘要；用户明确要列表时，再按时间顺序列出重点事件。
  5. 图片可用时优先展示图片，同时补一句简短说明；图片不可用时，明确说明并保留事件摘要。
  6. 结果为空时直接说明“当前没有查到”，不要臆造原因或补不存在的数据。

常见场景

以下示例用于帮助快速选路。

  • 用户想看当前有哪些设备：

    1. 调用 GET /api/v1/skill/devices
    2. 整理成可读的设备清单，优先给出设备名、设备 ID、是否在线等关键信息

  • 用户想看某个设备当前画面：

    1. 先确认 deviceId
    2. 调用 POST /api/v1/skill/device/snapshot
    3. 返回截图结果和简短说明

  • 用户想知道今天发生了什么：

    1. 先确认 device_id
    2. 将“今天”换成明确时间范围
    3. 调用 GET /api/v1/skill/device/events
    4. 按时间整理事件，并给出简短总结

  • 用户想看下午有没有快递来：

    1. 先确认 device_id
    2. 将“下午”换成明确时间范围
    3. 调用 GET /api/v1/skill/device/events
    4. 优先关注 body、ai_summary，先看 detailDescription，需要时再查看事件图片

  • 用户想看最近一个事件：

    1. 先确认 device_id
    2. 调用 GET /api/v1/skill/device/events/latest
    3. 返回事件摘要；有图片时一并展示

  • 用户想查询设备电量：

    1. 先确认 device_id
    2. 调用 GET /api/v1/skill/device/battery
    3. 直接解释电量结果，不输出原始结构

  • 用户想看多个设备某一天发生了什么：

    1. 先调用 GET /api/v1/skill/devices 确认目标设备，并解析出多个 device_id
    2. 将目标日期换成明确时间范围
    3. 对每个设备分别调用 GET /api/v1/skill/device/events
    4. 先按设备整理事件，再给出跨设备总结

  • 用户想看某个设备最近几天发生了什么：

    1. 先确认 device_id
    2. 将“最近几天”换成明确日期范围，总跨度不要超过 7 天
    3. 按单日时间范围多次调用 GET /api/v1/skill/device/events
    4. 先按日期总结，再给出跨天结论

接口说明

1. 查询设备列表

GET /api/v1/skill/devices
  • 用途：查询当前 Skill 可操作的设备；传入 device_id 时返回指定设备信息
  • Query：
    • device_id：可选；传入后仅返回该设备，不存在或无权限时 items 为空
  • 返回要点：
    • data.items[].deviceId：设备ID
    • data.items[].deviceName：设备名称
    • data.items[].isOwner：设备归属；true 为本人设备，false 为共享设备
    • data.items[].connectWay：联网方式
    • data.items[].extend.bindTime：绑定时间
  • 注意：如果用户按设备名操作，先用这一步确认目标设备；查电量前可先看 data.items[].attrs.power 是否有 battery

2. 查询设备在线状态

GET /api/v1/skill/device/online
  • 用途：判断设备当前是否在线、是否可用
  • Query：
    • device_id：必填
  • 返回要点：
    • data.deviceId
    • data.isOnline
  • 注意：按接口实际返回直接解释即可

3. 查询设备当前画面

POST /api/v1/skill/device/snapshot
  • 用途：查询设备当前截图，适合“拍一张”“看当前画面”“帮我截个图”

请求体示例：

{
  "deviceId": "678A7QP6Q5WD"
}
  • Body：
    • deviceId：必填
  • 返回要点：
    • data.deviceId
    • data.status
    • data.imageUrl
  • 注意：
    • 请求体字段必须写成 deviceId
    • 这是截图，不是实时视频流
    • 该接口不是直接读取现成图片，而是由服务器先给设备下发截图指令，再等待设备上传图片，通常会有约 3 秒等待时间
    • 截图会产生一定存储和流量成本，不要频繁调用

4. 查询设备某天或某时间段事件

GET /api/v1/skill/device/events
  • 用途：查询某一天或某个时间段内发生了什么，也可按标签过滤
  • Query：
    • device_id：必填
    • start_time：可选，Unix 秒时间戳
    • end_time：可选，Unix 秒时间戳
    • tag：可选，可重复传多个
    • limit：可选，整数，需大于等于 0
    • offset：可选，整数，需大于等于 0
  • 返回要点：
    • data.items[].id
    • data.items[].tag
    • data.items[].time
    • data.items[].deviceId
    • data.items[].detailDescription
  • tag 说明：
    • tag 是事件的分类标识，用于表示事件所属分类；tag / tags 都可用于筛选，重复传多个值表示同时关注多个分类
    • 常见 tag 示例：motion（移动）、sound（声音）、body（人形）、pet（宠物）、livestock（家畜）、fire（火焰）、guard（看守异常）、image_abnormal（画面异常）、car（发现车辆）、ai_summary（AI 文字摘要）
    • 实际支持哪些 tag，以接口返回结果为准
  • 使用建议：
    • 可结合 tag 筛选，并优先阅读 data.items[].detailDescription
    • 需要事件图片时，再用返回的 id 作为 event_id 调用 GET /api/v1/skill/device/events/image查询
  • 注意：
    • 未传 start_time 和 end_time 时，默认查询设备时区当天的事件
    • 查时间范围时，建议同时传 start_time 和 end_time，且需满足 start_time < end_time
    • limit 和 offset 不能是负数

5. 查询设备最近一个事件

GET /api/v1/skill/device/events/latest
  • 用途：查看设备最近一次发生了什么
  • Query：
    • device_id：必填
    • start_time：可选，Unix 秒时间戳
    • end_time：可选，Unix 秒时间戳
  • 返回要点：
    • data.id
    • data.tag
    • data.time
    • data.deviceId
    • data.detailDescription
    • data.imageUrl
  • 注意：这是单条事件，不是事件列表

6. 查询设备事件图片

GET /api/v1/skill/device/events/image
  • 用途：查看某条事件对应的图片
  • Query：
    • event_id：必填
  • 返回要点：
    • data.id
    • data.tag
    • data.time
    • data.deviceId
    • data.imageUrl
  • 注意：event_id 请使用系统已经返回过的事件 ID，不要自己拼，例如 /api/v1/skill/device/events 返回结果中的 id

7. 查询设备电量

GET /api/v1/skill/device/battery
  • 用途：查看设备电量
  • Query：
    • device_id：必填
  • 返回要点：
    • data.deviceId
    • data.batteryPercent：电量百分比，值为 0-100
    • data.isCharging：是否正在充电
  • 注意：仅当设备 attrs.power 有 battery 时，才可查询电量；若没有 battery，直接说明该设备不支持电量查询

补充规则

  • 缺少 deviceId、device_id 或 event_id 时，先提示用户补充，或先走上游查询步骤
More in Data & APIs