Hik Cloud Device Control

调用海康云眸开放平台设备控制类接口，包括设备布撤防、布撤防状态查询、云台控制、远程抓图、设备 OSD 设置与查询、设备校时与 NTP 服务器配置、设备存储卡初始化与进度查询。用户提到设备序列号、通道号、布防/撤防、抓图、云台转动、OSD 设置、校时、NTP 配置、存储卡初始化等场景时使用。本技能自动处理 acce...

Security Scan

The skill's requirements, instructions, and included script align with a Hik‑Cloud device control helper and do not ask for unrelated secrets or install arbitrary third‑party code.

Purpose & Capability

Name/description, SKILL.md, reference docs and the Python script consistently implement Hik Cloud device control endpoints (arm/disarm, PTZ, capture, OSD, time/NTP, storage init). Required env vars (client_id/client_secret) match the OAuth client‑credentials flow described.

Instruction Scope

SKILL.md instructs the agent to run the included Python script and documents token resolution, base URL precedence, and allowed operations. It does not request unrelated file reads or external endpoints beyond the service base URL and token exchange.

Install Mechanism

There is no install spec (instruction-only), which is low risk. The bundle does include a Python script that will be executed by the agent; no external downloads or installers are used. Review the included script before running in sensitive environments.

Credentials

Declared env vars (HIK_OPEN_CLIENT_ID, HIK_OPEN_CLIENT_SECRET and optional HIK_OPEN_ACCESS_TOKEN/HIK_OPEN_BASE_URL) are appropriate and necessary for OAuth and endpoint selection. No unrelated secrets or broad cloud credentials are requested.

Persistence & Privilege

Skill does not request always:true and allows autonomous invocation by default (normal). The helper caches tokens to ~/.cache/hik_open/token.json and may create that directory; this is expected but worth noting if you want no on‑disk artifacts.

Assessment

This skill appears to be what it claims: a Hik‑Cloud device control helper. Before installing, confirm you trust the author and are comfortable providing Hik Cloud client credentials. Review the included scripts if you want to verify there are no additional network endpoints or unexpected behavior. Note the script will cache an access token at ~/.cache/hik_open/token.json and may write that directory; if you prefer not to persist tokens, run with an explicit --access-token or clear the cache after use. If you need to restrict network destinations, ensure the base URL (HIK_OPEN_BASE_URL) is set to the official endpoint (https://api2.hik-cloud.com) and avoid pointing it at untrusted domains.

海康云眸设备能力

Overview

按固定链路执行海康云眸开放平台设备控制类接口，优先使用 {baseDir}/scripts/hik_open_device_control.py，不要临时手写认证、URL 拼接和重试逻辑。

本技能只处理以下能力：

• 设备布撤防
• 布撤防状态查询
• 云台开始控制
• 云台停止控制
• 远程抓图
• OSD 名称设置
• OSD 名称查询
• OSD 配置
• 设备校时
• NTP 服务器配置
• 设备存储卡初始化

本技能不对外暴露 “获取 access_token” 操作。鉴权属于内部基础设施：脚本会自动读取凭证、获取 token、缓存 token，并在 401 时自动刷新后重试一次。

OpenClaw 配置

当 OpenClaw 通过 ~/.openclaw/openclaw.json 管理本技能时，使用 metadata.openclaw.skillKey 作为配置键：

{
  skills: {
    entries: {
      "hik-cloud-device-control": {
        enabled: true,
        env: {
          HIK_OPEN_CLIENT_ID: "...",
          HIK_OPEN_CLIENT_SECRET: "...",
          HIK_OPEN_BASE_URL: "https://your-custom-base-url"
        }
      }
    }
  }
}

若 Session 运行在 sandbox 中，宿主环境变量不会自动继承。此时应通过 OpenClaw 的 sandbox env 配置注入凭证，而不是依赖本机 shell 的 process.env。

域名切换优先级：

1. --base-url
2. HIK_OPEN_BASE_URL
3. 默认正式环境：https://api2.hik-cloud.com

需要切换环境时，可通过 HIK_OPEN_BASE_URL 指定自定义域名。认证接口和设备接口都跟随同一个 base URL。

执行规则

1. 认证固定使用 Authorization: Bearer <access_token>。
2. token 来源优先级：
   • --access-token
   • HIK_OPEN_ACCESS_TOKEN
   • token cache
   • HIK_OPEN_CLIENT_ID + HIK_OPEN_CLIENT_SECRET 自动换取
3. 域名来源优先级：
   • --base-url
   • HIK_OPEN_BASE_URL
   • 默认正式环境 https://api2.hik-cloud.com
4. 若业务接口返回 HTTP 401，自动刷新 token 并重试一次。
5. 若接口返回非成功状态，直接返回真实错误，不臆造结果。
6. 默认通道号只在文档明确允许时使用 1；若用户未提供且上下文无法确认，不要擅自猜测。
7. 用户若要求“展示 token / 返回 token 原文”，说明这不属于本技能的主要职责；仅在明确要求调试认证链路时再解释。

快速开始

先准备环境变量：

export HIK_OPEN_CLIENT_ID="<YOUR_CLIENT_ID>"
export HIK_OPEN_CLIENT_SECRET="<YOUR_CLIENT_SECRET>"

切换到自定义环境域名：

export HIK_OPEN_BASE_URL="https://your-custom-base-url"

设备布防：

python3 {baseDir}/scripts/hik_open_device_control.py arm-set \
  --device-serial K05818510 \
  --is-defence 1

查询布撤防状态：

python3 {baseDir}/scripts/hik_open_device_control.py arm-get \
  --device-serial K05818510

开始云台控制：

python3 {baseDir}/scripts/hik_open_device_control.py ptz-start \
  --device-serial D20591677 \
  --channel-no 1 \
  --direction 9 \
  --speed 2 \
  --mode 0

停止云台控制：

python3 {baseDir}/scripts/hik_open_device_control.py ptz-stop \
  --device-serial D20591677 \
  --channel-no 1 \
  --direction 9

远程抓图：

python3 {baseDir}/scripts/hik_open_device_control.py capture \
  --device-serial D20591677 \
  --channel-no 1 \
  --quality 0

设备校时：

python3 {baseDir}/scripts/hik_open_device_control.py time-set \
  --device-serial C13032017 \
  --time-mode NTP

获取设备校时配置：

python3 {baseDir}/scripts/hik_open_device_control.py time-get \
  --device-serial C13032017

配置 NTP 服务器：

python3 {baseDir}/scripts/hik_open_device_control.py ntp-set \
  --device-serial C13032017 \
  --ntp-server-id 1 \
  --addressing-format-type hostname \
  --host-name time.windows.com \
  --port-no 123 \
  --synchronize-interval 1440

获取指定 NTP 服务器配置：

python3 {baseDir}/scripts/hik_open_device_control.py ntp-config-get \
  --device-serial C13032017 \
  --ntp-server-id 1

存储卡初始化：

python3 {baseDir}/scripts/hik_open_device_control.py storage-init \
  --device-serial 123456

存储卡初始化进度查询：

python3 {baseDir}/scripts/hik_open_device_control.py storage-init-progress \
  --device-serial 123456

设置 OSD 名称：

python3 {baseDir}/scripts/hik_open_device_control.py osd-set-name \
  --device-serial K05818510 \
  --channel-no 1 \
  --osd-name "前厅1号机"

查询 OSD 名称：

python3 {baseDir}/scripts/hik_open_device_control.py osd-get-name \
  --device-serial G29746408 \
  --channel-no 1

配置 OSD：

python3 {baseDir}/scripts/hik_open_device_control.py osd-config \
  --device-serial K05818510 \
  --channel-no 1 \
  --channel-name-osd-enabled true \
  --channel-name-osd-position-x 700 \
  --channel-name-osd-position-y 500

子命令说明

• arm-set：设置设备布撤防状态
• arm-get：查询设备布撤防状态
• ptz-start：开始云台控制
• ptz-stop：停止云台控制
• capture：远程抓图
• osd-set-name：设置设备 OSD 名称
• osd-get-name：查询设备 OSD 名称
• osd-config：配置设备 OSD 展示信息
• time-get：获取设备校时配置
• time-set：配置设备校时
• ntp-get：获取 NTP 服务器配置
• ntp-set：配置 NTP 服务器
• ntp-config-get：获取指定 NTP 服务器配置
• ntp-config-set：配置指定 NTP 服务器参数
• storage-init：初始化设备存储卡
• storage-init-progress：查询设备存储卡初始化进度

通用参数：

• --base-url：显式指定接口域名，优先级高于环境变量
• --access-token：显式指定 access token
• --timeout：请求超时秒数，默认 20
• --token-cache-file：token 缓存文件，默认 ~/.cache/hik_open/token.json
• --format：text 或 json

通用环境变量：

• HIK_OPEN_CLIENT_ID
• HIK_OPEN_CLIENT_SECRET
• HIK_OPEN_ACCESS_TOKEN
• HIK_OPEN_BASE_URL：可切换到自定义环境域名

参数约束

• 布撤防 isDefence：
  • 具有防护能力设备：0-睡眠、8-在家、16-外出
  • 普通 IPC：0-撤防、1-布防
• 云台 direction：
  • 0-上、1-下、2-左、3-右
  • 4-左上、5-左下、6-右上、7-右下
  • 8-放大、9-缩小、10-近焦距、11-远焦距
• 云台 mode / speed：
  • mode 默认是 0
  • mode=0 时 speed 只能取 0-慢、1-适中、2-快
  • mode=1 时 speed 只能取 0~7
  • mode 和 speed 要配套理解
• NTP addressingFormatType：
  • hostname 模式主要使用 hostName
  • ipaddress 模式主要使用 ipAddress
  • ipv6Address 仅在 IPv6 场景使用
  • hostName、ipAddress、ipv6Address 要跟 addressingFormatType 配套，尽量不要混填
• 抓图 quality：
  • 仅 NVR 支持
  • 0-流畅、1-高清、2-4CIF、3-1080P

输出约定

• --format text：输出简要结果摘要和关键字段
• --format json：输出结构化结果，包含请求上下文和原始响应数据

资源说明

• {baseDir}/scripts/hik_open_device_control.py：主脚本，负责认证、缓存、设备接口调用
• {baseDir}/references/auth.md：认证与 token 自动刷新规则
• {baseDir}/references/device-arm-disarm.md：设备布撤防文档摘要
• {baseDir}/references/ptz-control.md：云台控制文档摘要
• {baseDir}/references/remote-capture.md：远程抓图文档摘要
• {baseDir}/references/device-osd.md：设备 OSD 文档摘要
• {baseDir}/references/time-sync.md：设备校时文档摘要
• {baseDir}/references/storage-card-init.md：设备存储卡初始化文档摘要