企业官网建设流程全解析

Home Assistant System Bridge「Open path」动作完全指南：远程打开文件路径的自动化实践

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

本篇技术指南围绕 Home Assistant 中 System Bridge 集成的Open path（system_bridge.open_path）动作展开，讲解如何让 Home Assistant 远程调用 System Bridge 服务器、使用系统默认程序打开指定文件或目录。读完本文，你将掌握该动作的 UI 配置流程、YAML 调用方式、响应数据结构，以及它与open_url、键盘控制等兄弟动作的组合用法，可直接落地到自动化与脚本场景中。

动作定位：System Bridge 的远程文件打开能力

system_bridge.open_path是 System Bridge 集成提供的一类"远程操控"动作。System Bridge 是一个运行在本地设备上的应用程序，通过其 API/WebSocket 向 Home Assistant 分享系统信息，同时也能接收命令对设备进行操作，例如打开 URL、发送键盘按键等（见 System Bridge 集成文档）。

Open path动作的核心行为是：在指定的 System Bridge 服务器上，用该文件类型的默认应用程序打开一个文件（或目录）。典型应用场景包括：

• 自动化触发后在服务器电脑上打开图片、文档、视频；
• 脚本根据条件在远程主机上拉起某个应用或文件夹；
• 配合通知按钮、语音助手等入口实现"一键打开"。

该动作的 front matter 元数据定义如下（见 动作文档）：

title: "Open path" action: system_bridge.open_path domain: system_bridge description: "Opens a file on a System Bridge server with the default application." related_actions: - system_bridge.open_url

其关联动作是system_bridge.open_url，后者负责用默认浏览器等程序打开 URL。二者一文件一网址，互为补充。

前置条件：集成与服务器选择

在调用system_bridge.open_path之前，需要先确保满足以下前提（详见 System Bridge 集成文档）：

1. 版本要求：System Bridge 需要 4.0.2 及以上版本，旧版本无法与此集成协同工作。
2. Token：集成配置需要 System Bridge 的 token，用于 Home Assistant 与服务器之间的鉴权。
3. 配置流：该集成通过ha_config_flow: true支持 UI 配置，设备通过ha_zeroconf: true支持局域网自动发现。

配置完成后，Home Assistant 中会存在一个代表该 System Bridge 服务器的"设备"（device），其bridge参数即设备的 ID（device ID）。system_bridge.open_path属于该域下的动作，必须通过bridge字段显式指定目标服务器。

在 UI 中配置该动作（可视化流程）

动作文档给出的 UI 操作步骤如下（摘录并整理自 动作文档）：

1. 进入设置 > 自动化与场景（Settings > Automations & scenes）。
2. 打开现有的自动化或脚本，或选择创建新建一个。
3. 若是新建自动化，在When部分添加一个触发器；脚本无需触发器。
4. 在Then do部分选择添加动作（Add action）。
5. 在搜索框中搜索并选择System Bridge: Open path。
6. 选择要操作的Bridge服务器，并填写要打开的Path。
7. 保存。

UI 中该动作的可配置选项如下：

关于 target 的说明

该动作不支持 targets。大多数动作可以通过选择区域、设备、实体或标签来隐式确定执行对象，但system_bridge.open_path不同——在 UI 中必须通过Bridge字段显式指定服务器。这意味着你无法用"区域/设备/实体/标签"这类通用目标机制来路由该动作，目标服务器的选择是唯一的必填前提。

在 YAML 中调用该动作（技术参考）

如果你直接在 YAML 中编写自动化或脚本，或者想精确了解 Home Assistant 底层实际传递的字段，可以按以下形式调用。动作文档给出的标准写法如下：

action: | action: system_bridge.open_path data: bridge: 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d path: "C:\\image.jpg" response_variable: result

YAML 参数明细：

路径写法的注意事项

• Windows 路径中的反斜杠需要转义，即C:\image.jpg应写作C:\\image.jpg（如上方示例），或用单引号包裹以避免转义歧义。
• 该字段是自由字符串，既可以指向文件（如C:\image.jpg），也可以指向目录——最终交由服务器端以该类型的默认程序打开。
• 由于动作在服务器所在的操作系统上执行，路径必须相对于服务器本机的文件系统，而不是 Home Assistant 所在主机。

使用响应变量串联后续步骤

动作返回的结果可以通过response_variable存入变量，供同一自动化或脚本的后续步骤使用。这是该动作支持"返回结果到响应变量"特性的体现（文档明确说明 "This action returns its result in a response variable"）。在后续动作中可通过模板引用该变量，例如判断是否成功打开后决定是否继续执行通知等后续操作。

响应数据结构

每次调用都会返回一条响应，确认被打开的路径。响应包含以下字段：

响应示例（来自 动作文档）：

id: abc123 type: OPENED data: path: C:\image.jpg message: Path opened

结合源码理解实现要点

从仓库结构与文档元数据可以推断以下实现事实：

• 所有 System Bridge 动作文档都采用同一套字段结构（action、domain、related_actions、options_ui、options_yaml、Response data章节），说明这些动作由同一个代码生成框架驱动（见 source/_actions/ 目录下的system_bridge.*系列文档）。动作文档本身是生成物，底层对应 System Bridge 集成中各 action 的 schema 定义。
• bridge字段在所有动作中均为必填字符串，且描述统一为 "The device ID of the System Bridge server"，印证了"一个集成对应一个服务器设备、动作必须显式指定设备"的架构约束。
• 响应中type的取值随动作而异（如OPENED、KEYBOARD_TEXT_SENT、KEYBOARD_KEY_PRESSED），data回显的是请求载荷，message则是服务器端生成的可读状态文本——这种"请求回显 + 类型 + 消息"的结构在各动作间保持一致，便于自动化对结果做统一解析。

这些证据共同说明：system_bridge.open_path是 System Bridge 远程命令通道上的一个标准动作，其行为本质是"把路径经由 API 交给服务器端，由服务器以默认程序打开"，然后以结构化响应返回执行结果。

实战：与关联动作组合的自动化示例

system_bridge.open_path可以与同域下的其他动作配合，构建立体化的远程控制方案。仓库中可用的 System Bridge 动作还包括（见 source/_actions/ 目录）：

• system_bridge.open_url：用默认浏览器打开 URL；
• system_bridge.send_text：向服务器发送文本，模拟键盘输入；
• system_bridge.send_keypress：向服务器发送单个按键（如a、enter、audio_play，完整按键列表见 robotjs 按键语法）；
• system_bridge.power_command：向服务器发送电源命令；
• system_bridge.get_process_by_id/system_bridge.get_processes_by_name：按 ID 或名称查询进程信息。

例如，一个"远程演示"场景可以这样组织：先用system_bridge.open_path打开服务器上的演示文稿文件，再通过system_bridge.send_keypress发送enter键开始播放。完整 YAML 骨架如下：

alias: "Remote presentation" triggers: - trigger: state entity_id: input_boolean.present to: "on" actions: - action: system_bridge.open_path data: bridge: 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d path: "D:\\slides\\demo.pdf" response_variable: open_result - if: - condition: template value_template: "{{ open_result['type'] == 'OPENED' }}" then: - action: system_bridge.send_keypress data: bridge: 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d key: "enter"

快速验证与排障

• Try it yourself：可以在设置 > 工具 > 动作（Settings > Tools > Actions）中搜索该动作，填写字段并点击执行动作，无需编写任何 YAML 即可在真实设备上观察效果（见 actions/try_it.md）。
• 常见失败点：
  • bridge填错或为空：动作无法路由到服务器，响应会报错；
  • 路径不存在或权限不足：服务器端默认程序无法打开，响应中的message会给出可读错误；
  • 路径格式错误：例如未转义的反斜杠、相对路径等，建议使用绝对路径；
  • 服务器版本过低：低于 4.0.2 的 System Bridge 与该集成不兼容，需先升级。
• 响应变量作用域：response_variable中的结果仅在同一自动化或脚本的后续步骤中可用，跨自动化传递需要配合全局变量或事件机制。

小结

system_bridge.open_path为 Home Assistant 提供了一条干净、可编程的远程文件打开通道：UI 配置只需选择 Bridge 服务器并填写路径，YAML 调用则要求bridge与path两个必填参数，且必须通过响应变量获取OPENED类型的结果以驱动后续流程。结合同域下的open_url、键盘模拟等动作，你可以把一台运行 System Bridge 的电脑变成完全受 Home Assistant 编排的远程执行节点。相关完整参考请继续阅读 动作文档、集成文档 及 source/_actions/ 目录下的同域动作文档。

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io