Hik Cloud Device Management

调用海康云眸开放平台设备基础管理接口，包括注册设备、删除设备、修改设备名称、查询设备详情、查询设备列表、获取设备总数、查询设备状态和设备重启。用户提到设备注册、设备删除、设备重命名、设备列表、设备状态、设备重启等场景时使用。本技能自动处理 access_token 获取与刷新，不向用户暴露 token 调用流程。

Security Scan

The skill is internally consistent with its stated purpose (Hik-Cloud device management): it requires the expected credentials, provides a Python helper script, and its instructions align with the described API calls.

Purpose & Capability

Name/description (Hik Cloud device management) match what the files implement: a Python script and docs that call Hik-Cloud OpenAPI endpoints for create/delete/rename/get/list/count/status/reboot. Required binaries (python3) and required env vars (HIK_OPEN_CLIENT_ID, HIK_OPEN_CLIENT_SECRET) are appropriate for OAuth client_credentials flows.

Instruction Scope

SKILL.md instructs running the included script and documents token handling, flags, and outputs. It explicitly caches tokens and will auto-refresh on 401. One notable capability: the base API URL can be overridden via --base-url or HIK_OPEN_BASE_URL, which is useful for staging but means misconfiguring that value could redirect credentials/token requests to a non-official endpoint.

Install Mechanism

There is no install spec (instruction-only skill plus an included Python script). No networked install/downloads or third-party package pulls are present. The script runs with system Python and uses only the standard library.

Credentials

Requested environment variables (client_id, client_secret, optional access token, optional base URL) are proportional to the functionality. The script reads/writes a token cache file (~/.cache/hik_open/token.json) to store access_token and expiry; this is expected but should be noted because cached tokens are sensitive.

Persistence & Privilege

The skill does not request always-on inclusion and does not modify other skills or global configs. Its persistent effect is limited to writing a token cache file under the user's home directory (standard behavior for caching OAuth tokens).

Assessment

This skill appears to do what it claims: a Python helper that manages Hik-Cloud devices using your HIK_OPEN_CLIENT_ID and HIK_OPEN_CLIENT_SECRET. Before installing, consider: (1) Protect your client secret — supply it via the agent's secure env/sandbox configuration rather than pasting it into chat. (2) The script caches access tokens at ~/.cache/hik_open/token.json; treat that file as sensitive. (3) The skill allows overriding the base URL (HIK_OPEN_BASE_URL or --base-url) for testing; do not set this to an untrusted endpoint, because the client credentials/token exchange would then be sent to that URL. (4) The skill can perform high-impact operations (device reboot/delete); ensure proper confirmation/authorization in your workflows. If you need additional assurance, review the full script locally before enabling and verify network calls go to expected Hik-Cloud endpoints.

海康云眸设备基础管理

Overview

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

本技能只处理以下能力：

• 注册设备
• 删除设备
• 修改设备名称
• 查询单个设备信息
• 查询设备列表
• 获取设备总数
• 查询设备状态
• 设备重启

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

OpenClaw 配置

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

{
  skills: {
    entries: {
      "hik-cloud-device-management": {
        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

执行规则

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. 设备重启属于高影响操作，执行前应再次确认设备序列号。
7. 查询设备状态接口目前仅支持萤石设备。
8. 用户若要求“展示 token / 返回 token 原文”，说明这不属于本技能的主要职责；仅在明确要求调试认证链路时再解释。

快速开始

先准备环境变量：

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

注册设备：

python3 {baseDir}/scripts/hik_open_device_management.py create \
  --device-serial E05426006 \
  --group-no fsdfe \
  --validate-code ADSEFE

删除设备：

python3 {baseDir}/scripts/hik_open_device_management.py delete \
  --device-serial 123456

修改设备名称：

python3 {baseDir}/scripts/hik_open_device_management.py rename \
  --device-serial E05426006 \
  --device-name "设备名称"

查询单个设备信息：

python3 {baseDir}/scripts/hik_open_device_management.py get \
  --device-serial D05215100 \
  --need-defence

查询设备列表：

python3 {baseDir}/scripts/hik_open_device_management.py list \
  --group-no 1 \
  --page-no 1 \
  --page-size 50

获取设备总数：

python3 {baseDir}/scripts/hik_open_device_management.py count

查询设备状态：

python3 {baseDir}/scripts/hik_open_device_management.py status \
  --device-serial C01563792

设备重启：

python3 {baseDir}/scripts/hik_open_device_management.py reboot \
  --device-serial 123456789

子命令说明

• create：注册设备
• delete：删除设备
• rename：修改设备名称
• get：查询单个设备信息
• list：查询设备列表
• count：获取设备总数
• status：查询设备状态
• reboot：设备重启

通用参数：

• --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

输出约定

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

判读关键字段时优先看这些值：

• deviceStatus：0 离线，1 在线
• defence：只在 get + --need-defence 时返回；具防护能力设备是 0 睡眠、8 在家、16 外出，普通 IPC 是 0 撤防、1 布防
• privacyStatus：0 关闭、1 打开、-1 初始值、2 不支持、-2 未上报/不支持
• pirStatus：1 启用、0 禁用、-1 初始值、2 不支持、-2 未上报/不支持
• alarmSoundMode：0 短叫、1 长叫、2 静音、3 自定义语音、-1 未上报/不支持
• cloudStatus：-2 不支持、-1 未开通、0 未激活、1 激活、2 过期
• diskState / nvrDiskState：状态串按盘位拼接，0 正常、1 存储介质错、2 未格式化、3 正在格式化；nvrDiskState 额外支持 -2 未关联

资源说明

• {baseDir}/scripts/hik_open_device_management.py：主脚本，负责认证、缓存和设备管理接口调用
• {baseDir}/references/auth.md：认证与 token 自动刷新规则
• {baseDir}/references/device-management.md：设备基础管理文档摘要