Home Assistant Agent DVR 连续录像实战：agent_dvr.start_recording 动作完整指南
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
Agent DVR 是一款可运行在 Windows、macOS 与 Linux 上的免费软件 DVR 方案，支持对接大量第三方摄像头并内置高级运动检测（含 DeepStack 物体识别）。本文基于 Home Assistant 官方文档中agent_dvr.start_recording动作的完整说明，系统讲解如何在自动化与脚本中控制 Agent DVR 摄像头开始连续录像，覆盖 UI 可视化配置、YAML 直写、目标选择（Targets）与配套动作，帮助你搭建"检测到异常即开始录像"等典型安防场景。
前置条件：先接入 Agent DVR 集成
agent_dvr.start_recording属于 Agent DVR 集成（ha_domain: agent_dvr，集成类型为 hub，包含alarm_control_panel与camera两种平台）提供的动作。要使用它，你首先需要将 Agent DVR 服务器添加到 Home Assistant：
- 在集成配置界面输入 Agent DVR 服务器的 IP 与端口，格式如
http://192.168.1.3:8090/； - 若在 Agent DVR 服务器上开启了 "Protect API" 功能，可将用户名密码一并写入 URL，例如
http://username:password@192.168.1.3:8090； - 官方文档特别强调：请确保使用 Agent DVR v2.6.1.0 及以上版本。
从实现层面看，该集成通过配置流（config flow）完成接入（见 source/_integrations/agent_dvr.markdown 中的ha_config_flow: true），接入后每个摄像头会以camera.*实体形式暴露给 Home Assistant，agent_dvr.start_recording动作正是作用在这些摄像头实体上。
动作概览：start_recording 做什么
根据 agent_dvr.start_recording 动作文档 的定义：
使用该动作在 Agent DVR 摄像头上开始连续录像（continuous recording）。录像会持续进行，直到你用
agent_dvr.stop_recording动作将其停止。
两个关键事实需要明确：
- "连续录像"是持续行为：该动作一旦执行，录像不会自动结束，必须由配套的
agent_dvr.stop_recording动作显式停止； - 存储发生在 Agent DVR 侧：录像文件由 Agent DVR 服务端负责捕获与存储，Home Assistant 只负责下发控制指令，因此录像的码流、存储策略与告警行为均遵循 Agent DVR 自身的配置。
动作元数据中声明了相关动作（related_actions）：agent_dvr.stop_recording与agent_dvr.snapshot，分别对应停止录像与抓拍快照，构成一组完整的事件取证能力。
从 UI 中使用该动作（自动化与脚本）
如果你倾向可视化配置，Home Assistant 会在编辑器中逐步引导你完成设置——选择目标、调整选项、保存即可，无需掌握 YAML。官方文档给出的操作步骤如下：
- 进入Settings > Automations & scenes（自动化与场景）；
- 打开已有的自动化或脚本，或选择Create automation>Create new automation新建；
- 若在新建自动化，需先在When（触发条件）部分添加触发器；脚本则不需要触发器，脚本在被其他东西调用时才会运行；
- 在Then do（执行动作）部分，选择Add action（添加动作）；
- 选择你要控制的对象：在By target（按目标，详见下文"Targets"）下选择你的 Agent DVR 摄像头；
- 从该目标可用的动作列表中，选择Start recording（开始录像）；
- 点击Save（保存）。
UI 选项说明：该动作在 UI 中没有额外的选项字段（"This action has no additional options in the UI"），你只需要指定目标即可。这与同域其他动作（
stop_recording、snapshot、enable_alerts、disable_alerts）保持一致。
在 YAML 中使用该动作
如果你直接编写 YAML，或希望精确了解 Home Assistant 底层的行为，本节提供技术参考，列出 YAML 中的字段名、类型与必填项。在 YAML 中，动作名称为agent_dvr.start_recording，官方给出如下最小可运行示例：
action: agent_dvr.start_recording target: entity_id: camera.living_room该动作只有一个必填要素——target（目标），且无额外参数。你可以将此动作直接嵌入自动化或脚本中，例如结合运动检测传感器：
alias: 门口检测到人时开始录像 triggers: - trigger: state entity_id: binary_sensor.front_door_motion to: "on" actions: - action: agent_dvr.start_recording target: entity_id: camera.front_door请务必同时规划停止录像的动作（见下文"停止录像与配套动作"），否则录像将持续占用存储空间。
Targets：动作的作用对象
根据 actions/targets.md 模板，agent_dvr.start_recording需要指定一个 target，它是动作的作用对象。你可以将动作指向单个实体、设备、区域、楼层或标签，Home Assistant 会对该目标背后的每一个匹配camera实体执行动作。可选的目标类型：
- Entity（实体）：某一个具体的
camera实体，例如camera.living_room； - Device（设备）：属于某台设备的所有
camera实体； - Area（区域）：某个房间或区域内的所有
camera实体； - Floor（楼层）：某一楼层上的所有
camera实体； - Label（标签）：共享某个标签的所有
camera实体。
你还可以在同一个动作中混合选择不同类型的目标，例如同时指定一个具体实体和一个区域，让动作对二者同时生效。这一机制让你可以一条动作同时启动多路摄像头录像，例如"全屋布防时对所有室外摄像头开始录像"。
停止录像与配套动作
agent_dvr.start_recording启动的连续录像不会自己停止，配套动作是 agent_dvr.stop_recording：它停止此前通过start_recording开始的连续录像。YAML 写法对称：
action: agent_dvr.stop_recording target: entity_id: camera.living_room同一动作族中还有两个常用能力，便于组合成完整的安防取证流程：
- agent_dvr.snapshot：在 Agent DVR 摄像头上拍摄一张照片，快照由 Agent DVR 捕获并存储；
- agent_dvr.enable_alerts / agent_dvr.disable_alerts：启用/禁用 Agent DVR 的告警事件（例如检测到运动时产生告警事件），实现按需开关事件通知。
参考的实战组合：运动传感器触发时先enable_alerts并start_recording，运动消失后stop_recording，需要时再snapshot固定现场画面。此外，Agent DVR 摄像头同样支持标准 camera 动作，例如开关摄像头与切换运动检测，可将录像控制与开关控制分层使用。
立即测试动作
如果你想在不写任何 YAML 的情况下验证效果，可以打开Settings > Tools > Actions（开发者工具中的动作面板，即文档中所述 Actions 工具），搜索该动作，填写字段后点击Perform action（执行动作），即可在你真实的实体上观察结果。
排错建议
如果动作没有按预期生效，可按以下方向排查：
- 确认版本与连接：Agent DVR 需为 v2.6.1.0+，且 Home Assistant 与 Agent DVR 服务器网络互通（该集成属于 Local Polling 本地轮询类型）；
- 确认目标实体：
target中填写的实体必须是对应 Agent DVR 摄像头的camera.*实体，可通过 UI 中的目标选择器核对实际实体 ID； - 确认录像确实在"连续"模式：该动作启动的是连续录像而非事件录像，停止动作必须显式调用
agent_dvr.stop_recording； - 查看日志与社区：如果问题依旧，可在 Home Assistant 官方社区渠道（Discord、社区论坛或 subreddit）发帖，附上你调用的动作、目标实体与预期行为，便于他人快速定位。
小结
agent_dvr.start_recording是 Home Assistant 控制 Agent DVR 摄像头连续录像的核心动作：它通过 UI 与 YAML 两种方式都可使用，唯一的必填参数是 target，配合stop_recording、snapshot与告警开关动作，即可构建从"检测事件 → 开始录像 → 抓拍取证 → 停止录像"的完整自动化链路。对以本地存储、无需端口转发的 Agent DVR 用户而言，这是把第三方摄像头接入 Home Assistant 自动化体系最直接的一环。
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
