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: 3
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": {
      "webcam": {
        "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 必须使用系统已经返回过的值，不要自己拼
• 看到“实时画面”“拍一张”“截个图”时，将其理解为获取一张当前截图，不是实时视频流

调用指南

快速路由

通用流程

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 时，先提示用户补充，或先走上游查询步骤