\r \r

海康云眸设备能力\r

\r

Overview\r

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

• 设备布撤防\r
• 布撤防状态查询\r
• 云台开始控制\r
• 云台停止控制\r
• 远程抓图\r
• OSD 名称设置\r
• OSD 名称查询\r
• OSD 配置\r
• 设备校时\r
• NTP 服务器配置\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-control": {\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
需要切换环境时，可通过 `HIK_OPEN_BASE_URL` 指定自定义域名。认证接口和设备接口都跟随同一个 base URL。\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. 默认通道号只在文档明确允许时使用 `1`；若用户未提供且上下文无法确认，不要擅自猜测。\r
7. 用户若要求“展示 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
export HIK_OPEN_BASE_URL="https://your-custom-base-url"\r
```\r
\r
设备布防：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_control.py arm-set \\r
  --device-serial K05818510 \\r
  --is-defence 1\r
```\r
\r
查询布撤防状态：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_control.py arm-get \\r
  --device-serial K05818510\r
```\r
\r
开始云台控制：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_control.py ptz-start \\r
  --device-serial D20591677 \\r
  --channel-no 1 \\r
  --direction 9 \\r
  --speed 2 \\r
  --mode 0\r
```\r
\r
停止云台控制：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_control.py ptz-stop \\r
  --device-serial D20591677 \\r
  --channel-no 1 \\r
  --direction 9\r
```\r
\r
远程抓图：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_control.py capture \\r
  --device-serial D20591677 \\r
  --channel-no 1 \\r
  --quality 0\r
```\r
\r
设备校时：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_control.py time-set \\r
  --device-serial C13032017 \\r
  --time-mode NTP\r
```\r
\r
获取设备校时配置：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_control.py time-get \\r
  --device-serial C13032017\r
```\r
\r
配置 NTP 服务器：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_control.py ntp-set \\r
  --device-serial C13032017 \\r
  --ntp-server-id 1 \\r
  --addressing-format-type hostname \\r
  --host-name time.windows.com \\r
  --port-no 123 \\r
  --synchronize-interval 1440\r
```\r
\r
获取指定 NTP 服务器配置：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_control.py ntp-config-get \\r
  --device-serial C13032017 \\r
  --ntp-server-id 1\r
```\r
\r
存储卡初始化：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_control.py storage-init \\r
  --device-serial 123456\r
```\r
\r
存储卡初始化进度查询：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_control.py storage-init-progress \\r
  --device-serial 123456\r
```\r
\r
设置 OSD 名称：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_control.py osd-set-name \\r
  --device-serial K05818510 \\r
  --channel-no 1 \\r
  --osd-name "前厅1号机"\r
```\r
\r
查询 OSD 名称：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_control.py osd-get-name \\r
  --device-serial G29746408 \\r
  --channel-no 1\r
```\r
\r
配置 OSD：\r
\r
```bash\r
python3 {baseDir}/scripts/hik_open_device_control.py osd-config \\r
  --device-serial K05818510 \\r
  --channel-no 1 \\r
  --channel-name-osd-enabled true \\r
  --channel-name-osd-position-x 700 \\r
  --channel-name-osd-position-y 500\r
```\r
\r
## 子命令说明\r
\r
- `arm-set`：设置设备布撤防状态\r
- `arm-get`：查询设备布撤防状态\r
- `ptz-start`：开始云台控制\r
- `ptz-stop`：停止云台控制\r
- `capture`：远程抓图\r
- `osd-set-name`：设置设备 OSD 名称\r
- `osd-get-name`：查询设备 OSD 名称\r
- `osd-config`：配置设备 OSD 展示信息\r
- `time-get`：获取设备校时配置\r
- `time-set`：配置设备校时\r
- `ntp-get`：获取 NTP 服务器配置\r
- `ntp-set`：配置 NTP 服务器\r
- `ntp-config-get`：获取指定 NTP 服务器配置\r
- `ntp-config-set`：配置指定 NTP 服务器参数\r
- `storage-init`：初始化设备存储卡\r
- `storage-init-progress`：查询设备存储卡初始化进度\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
- 布撤防 `isDefence`：\r
  - 具有防护能力设备：`0-睡眠`、`8-在家`、`16-外出`\r
  - 普通 IPC：`0-撤防`、`1-布防`\r
- 云台 `direction`：\r
  - `0-上`、`1-下`、`2-左`、`3-右`\r
  - `4-左上`、`5-左下`、`6-右上`、`7-右下`\r
  - `8-放大`、`9-缩小`、`10-近焦距`、`11-远焦距`\r
- 云台 `mode` / `speed`：\r
  - `mode` 默认是 `0`\r
  - `mode=0` 时 `speed` 只能取 `0-慢`、`1-适中`、`2-快`\r
  - `mode=1` 时 `speed` 只能取 `0~7`\r
  - `mode` 和 `speed` 要配套理解\r
- NTP `addressingFormatType`：\r
  - `hostname` 模式主要使用 `hostName`\r
  - `ipaddress` 模式主要使用 `ipAddress`\r
  - `ipv6Address` 仅在 IPv6 场景使用\r
  - `hostName`、`ipAddress`、`ipv6Address` 要跟 `addressingFormatType` 配套，尽量不要混填\r
- 抓图 `quality`：\r
  - 仅 NVR 支持\r
  - `0-流畅`、`1-高清`、`2-4CIF`、`3-1080P`\r
\r
## 输出约定\r
\r
- `--format text`：输出简要结果摘要和关键字段\r
- `--format json`：输出结构化结果，包含请求上下文和原始响应数据\r
\r
## 资源说明\r
\r
- `{baseDir}/scripts/hik_open_device_control.py`：主脚本，负责认证、缓存、设备接口调用\r
- `{baseDir}/references/auth.md`：认证与 token 自动刷新规则\r
- `{baseDir}/references/device-arm-disarm.md`：设备布撤防文档摘要\r
- `{baseDir}/references/ptz-control.md`：云台控制文档摘要\r
- `{baseDir}/references/remote-capture.md`：远程抓图文档摘要\r
- `{baseDir}/references/device-osd.md`：设备 OSD 文档摘要\r
- `{baseDir}/references/time-sync.md`：设备校时文档摘要\r
- `{baseDir}/references/storage-card-init.md`：设备存储卡初始化文档摘要\r