\r \r

海康云眸设备基础管理\r

\r

Overview\r

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

• 注册设备\r
• 删除设备\r
• 修改设备名称\r
• 查询单个设备信息\r
• 查询设备列表\r
• 获取设备总数\r
• 查询设备状态\r
• 设备重启\r \r 本技能不对外暴露 “获取 access_token” 操作。鉴权属于内部基础设施：脚本会自动读取凭证、获取 token、缓存 token，并在 401 时自动刷新后重试一次。\r \r

OpenClaw 配置\r

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

{\r
  skills: {\r
    entries: {\r
      "hik-cloud-device-management": {\r
        enabled: true,\r
        env: {\r
          HIK_OPEN_CLIENT_ID: "...",\r
          HIK_OPEN_CLIENT_SECRET: "...",\r
          HIK_OPEN_BASE_URL: "https://your-custom-base-url"\r
        }\r
      }\r
    }\r
  }\r
}\r
```\r
\r
若 Session 运行在 sandbox 中，宿主环境变量不会自动继承。此时应通过 OpenClaw 的 sandbox env 配置注入凭证，而不是依赖本机 shell 的 `process.env`。\r
\r
域名切换优先级：\r
\r
1. `--base-url`\r
2. `HIK_OPEN_BASE_URL`\r
3. 默认正式环境：`https://api2.hik-cloud.com`\r
\r
## 执行规则\r
\r
1. 认证固定使用 `Authorization: Bearer \x3Caccess_token>`。\r
2. token 来源优先级：\r
   - `--access-token`\r
   - `HIK_OPEN_ACCESS_TOKEN`\r
   - token cache\r
   - `HIK_OPEN_CLIENT_ID + HIK_OPEN_CLIENT_SECRET` 自动换取\r
3. 域名来源优先级：\r
   - `--base-url`\r
   - `HIK_OPEN_BASE_URL`\r
   - 默认正式环境 `https://api2.hik-cloud.com`\r
4. 若业务接口返回 HTTP `401`，自动刷新 token 并重试一次。\r
5. 若接口返回非成功状态，直接返回真实错误，不臆造结果。\r
6. 设备重启属于高影响操作，执行前应再次确认设备序列号。\r
7. 查询设备状态接口目前仅支持萤石设备。\r
8. 用户若要求“展示 token / 返回 token 原文”，说明这不属于本技能的主要职责；仅在明确要求调试认证链路时再解释。\r
\r
## 快速开始\r
\r
先准备环境变量：\r
\r
```bash\r
export HIK_OPEN_CLIENT_ID="\x3CYOUR_CLIENT_ID>"\r
export HIK_OPEN_CLIENT_SECRET="\x3CYOUR_CLIENT_SECRET>"\r
```\r
\r
注册设备：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_management.py create \\r
  --device-serial E05426006 \\r
  --group-no fsdfe \\r
  --validate-code ADSEFE\r
```\r
\r
删除设备：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_management.py delete \\r
  --device-serial 123456\r
```\r
\r
修改设备名称：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_management.py rename \\r
  --device-serial E05426006 \\r
  --device-name "设备名称"\r
```\r
\r
查询单个设备信息：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_management.py get \\r
  --device-serial D05215100 \\r
  --need-defence\r
```\r
\r
查询设备列表：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_management.py list \\r
  --group-no 1 \\r
  --page-no 1 \\r
  --page-size 50\r
```\r
\r
获取设备总数：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_management.py count\r
```\r
\r
查询设备状态：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_management.py status \\r
  --device-serial C01563792\r
```\r
\r
设备重启：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_management.py reboot \\r
  --device-serial 123456789\r
```\r
\r
## 子命令说明\r
\r
- `create`：注册设备\r
- `delete`：删除设备\r
- `rename`：修改设备名称\r
- `get`：查询单个设备信息\r
- `list`：查询设备列表\r
- `count`：获取设备总数\r
- `status`：查询设备状态\r
- `reboot`：设备重启\r
\r
通用参数：\r
\r
- `--base-url`：显式指定接口域名，优先级高于环境变量\r
- `--access-token`：显式指定 access token\r
- `--timeout`：请求超时秒数，默认 `20`\r
- `--token-cache-file`：token 缓存文件，默认 `~/.cache/hik_open/token.json`\r
- `--format`：`text` 或 `json`\r
\r
通用环境变量：\r
\r
- `HIK_OPEN_CLIENT_ID`\r
- `HIK_OPEN_CLIENT_SECRET`\r
- `HIK_OPEN_ACCESS_TOKEN`\r
- `HIK_OPEN_BASE_URL`\r
\r
## 输出约定\r
\r
- `--format text`：输出简要结果摘要和关键字段\r
- `--format json`：输出结构化结果，包含请求上下文和原始响应数据\r
\r
判读关键字段时优先看这些值：\r
\r
- `deviceStatus`：`0` 离线，`1` 在线\r
- `defence`：只在 `get + --need-defence` 时返回；具防护能力设备是 `0` 睡眠、`8` 在家、`16` 外出，普通 IPC 是 `0` 撤防、`1` 布防\r
- `privacyStatus`：`0` 关闭、`1` 打开、`-1` 初始值、`2` 不支持、`-2` 未上报/不支持\r
- `pirStatus`：`1` 启用、`0` 禁用、`-1` 初始值、`2` 不支持、`-2` 未上报/不支持\r
- `alarmSoundMode`：`0` 短叫、`1` 长叫、`2` 静音、`3` 自定义语音、`-1` 未上报/不支持\r
- `cloudStatus`：`-2` 不支持、`-1` 未开通、`0` 未激活、`1` 激活、`2` 过期\r
- `diskState` / `nvrDiskState`：状态串按盘位拼接，`0` 正常、`1` 存储介质错、`2` 未格式化、`3` 正在格式化；`nvrDiskState` 额外支持 `-2` 未关联\r
\r
## 资源说明\r
\r
- `{baseDir}/scripts/hik_open_device_management.py`：主脚本，负责认证、缓存和设备管理接口调用\r
- `{baseDir}/references/auth.md`：认证与 token 自动刷新规则\r
- `{baseDir}/references/device-management.md`：设备基础管理文档摘要\r