海康云眸设备控制（Hikvision设备控制）

海康云眸设备能力 Overview

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

本技能只处理以下能力：

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

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

OpenClaw 配置

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

{ 技能s: { entries: { "hik-cloud-device-control": { enabled: true, env: { HIK_OPEN_命令行工具ENT_ID: "...", HIK_OPEN_命令行工具ENT_SECRET: "...", HIK_OPEN_BASE_URL: "https://your-custom-base-url" } } } } }

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

域名切换优先级：

--base-url HIK_OPEN_BASE_URL 默认正式环境：https://API2.hik-cloud.com

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

执行规则 认证固定使用 Authorization: Bearer <访问_令牌>。 令牌 来源优先级： --访问-令牌 HIK_OPEN_访问_令牌 令牌 缓存 HIK_OPEN_命令行工具ENT_ID + HIK_OPEN_命令行工具ENT_SECRET 自动换取 域名来源优先级： --base-url HIK_OPEN_BASE_URL 默认正式环境 https://API2.hik-cloud.com 若业务接口返回 HTTP 401，自动刷新 令牌 并重试一次。 若接口返回非成功状态，直接返回真实错误，不臆造结果。 默认通道号只在文档明确允许时使用 1；若用户未提供且上下文无法确认，不要擅自猜测。 用户若要求“展示 令牌 / 返回 令牌 原文”，说明这不属于本技能的主要职责；仅在明确要求调试认证链路时再解释。 快速开始

先准备环境变量：

导出 HIK_OPEN_命令行工具ENT_ID="" 导出 HIK_OPEN_命令行工具ENT_SECRET=""

切换到自定义环境域名：

导出 HIK_OPEN_BASE_URL="https://your-custom-base-url"

设备布防：

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

查询布撤防状态：

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

开始云台控制：

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

停止云台控制：

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

远程抓图：

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

设备校时：

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

获取设备校时配置：

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

配置 NTP 服务器：

python3 {baseDir}/scripts/hik_open_device_control.py ntp-设置 \ --device-serial C13032017 \ --ntp-server-id 1 \ --添加ressing-格式化-type hostname \ --host-name time.windows.com \ --port-no 123 \ --同步hronize-interval 1440

获取指定 NTP 服务器配置：

python3 {baseDir}/scripts/hik_open_device_control.py ntp-config-获取 \ --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-进度 \ --device-serial 123456

设置 OSD 名称：

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

查询 OSD 名称：

python3 {baseDir}/scripts/hik_open_device_control.py osd-获取-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-设置：设置设备布撤防状态 arm-获取：查询设备布撤防状态 ptz-启动：开始云台控制 ptz-停止：停止云台控制 capture：远程抓图 osd-设置-name：设置设备 OSD 名称 osd-获取-name：查询设备 OSD 名称 osd-config：配置设备 OSD 展示信息 time-获取：获取设备校时配置 time-设置：配置设备校时 ntp-获取：获取 NTP 服务器配置 ntp-设置：配置 NTP 服务器 ntp-config-获取：获取指定 NTP 服务器配置 ntp-config-设置：配置指定 NTP 服务器参数 storage-init：初始化设备存储卡 storage-init-进度：查询设备存储卡初始化进度

通用参数：

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

通用环境变量：

HIK_OPEN_命令行工具ENT_ID HIK_OPEN_命令行工具ENT_SECRET HIK_OPEN_访问_令牌 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 添加ressing格式化Type： hostname 模式主要使用 hostName ip添加ress 模式主要使用 ip添加ress ipv6添加ress 仅在 IPv6 场景使用 hostName、ip添加ress、ipv6添加ress 要跟 添加ressing格式化Type 配套，尽量不要混填 抓图 质量： 仅 NVR 支持 0-流畅、1-高清、2-4CIF、3-1080P 输出约定 --格式化 text：输出简要结果摘要和关键字段 --格式化 json：输出结构化结果，包含请求上下文和原始响应数据 资源说明 {baseDir}/scripts/hik_open_device_control.py：主脚本，负责认证、缓存、设备接口调用 {baseDir}/references/auth.md：认证与 令牌 自动刷新规则 {baseDir}/references/device-arm-disarm.md：设备布撤防文档摘要 {baseDir}/references/ptz-control.md：云台控制文档摘要 {baseDir}/references/remote-capture.md：远程抓图文档摘要 {baseDir}/references/device-osd.md：设备 OSD 文档摘要 {baseDir}/references